Skip to main content

Create a Digital Object Using Spore Protocol

Tutorial Overview

⏰ Estimated Time: 5 - 10 min
💡 Topics: DOB, NFT, Spore Protocol
🔧 Tools You Need:

Spore Protocol on CKB​

Spore is an on-chain digital object (DOB) protocol backed by CKB. An "on-chain" asset refers to a digital asset whose data is directly encoded onto the blockchain. A Spore Cell can hold any type of assets users want to store on-chain, the following data structure is used in the Spore Cell:

data:
    content-type: Bytes # String Bytes
    content: Bytes
    # OPTIONAL
    cluster_id: Bytes
type:
    hash_type: "data1"
    code_hash: SPORE_TYPE_DATA_HASH
    args: SPORE_ID
lock:
    <user_defined>

Notice that the data field of the Spore Cell contains content-type and content, which allow users to turn any content form into a digital object. All the fields in a Spore Cell are immutable once created.

In this tutorial, we will build a simple dApp to turn a picture on your computer into a digital object on the blockchain using the Spore SDK.

Setup Devnet & Run Example​

Step 1: Initialize​

After installing @offckb/cli, run the following command to initlize a project with our built-in templates.

offckb init <project-name>

When prompted to select a dApp template, use your arrow keys to select Create a Digital Object Using Spore Protocol for this tutorial.

? Select a dApp template (Use arrow keys)
  View and Transfer a CKB Balance
  Write an On-Chain Message
  Create a Fungible Token
> Create a Digital Object Using Spore Protocol
a simple dApp to create on-chain digital object with spore scripts

Step 2: Start the Devnet​

To interact with the dApp, you need to have your Devnet running. Open one terminal and start the Devnet:

offckb node

You might want to check pre-funded accounts and copy private keys for later use. Open another terminal and execute:

offckb accounts

Step 3: Run the Example​

Navigate to your project, install the node dependencies, and start running the example:

cd <project-name> && yarn && yarn start

Now, the app is running in http://localhost:1234

Behind the Scene​

Open the lib.ts file in your project, it lists all the important functions that do the most of work for the project.

Create Digital Object​

Check out the createSporeDOB function:

export async function createSporeDOB(
  privkey: string,
  content: Uint8Array
): Promise<{ txHash: string; outputIndex: number }>;

It accepts two parameters,

  1. the private key that is used to sign and create the digital object
  2. the content to be stored in the digital object.

The content can be any type of data that is serialized into a Uint8Array. Here we are dealing with images, so the content is the result of FileReader.readAsArrayBuffer. You can check out the following code recipe in handleFileChange function from the react frontend index.tsx:

const reader = new FileReader();
reader.onload = () => {
  // Access the file content here
  const content = reader.result;
  if (content && content instanceof ArrayBuffer) {
    const uint8Array = new Uint8Array(content);
    setFileContent(uint8Array);
  }
};
// Read the file as ArrayBuffer
reader.readAsArrayBuffer(files[0]);

Once we have the picture content and the private key, we will build a transaction that produces a Spore output Cell, aka the digital object Cell. We can handle all the logic with Lumos.js, but with the help of Spore-SDK, it becomes very simple to do:

export async function createSporeDOB(
  privkey: string,
  content: Uint8Array
): Promise<{ txHash: string; outputIndex: number }> {
  const wallet = createDefaultLockWallet(privkey);

  const { txSkeleton, outputIndex } = await createSpore({
    data: {
      contentType: "image/jpeg",
      content,
    },
    toLock: wallet.lock,
    fromInfos: [wallet.address],
    config: SPORE_CONFIG,
  });

  const txHash = await wallet.signAndSendTransaction(txSkeleton);
  console.log(`Spore created at transaction: ${txHash}`);
  console.log(
    `Spore ID: ${
      txSkeleton.get("outputs").get(outputIndex)!.cellOutput.type!.args
    }`
  );
  return { txHash, outputIndex };
}

Notice that the createDefaultLockWallet and const txHash = await wallet.signAndSendTransaction(txSkeleton); are just some methods that helps us to keep the code clean, all it does is the same as the previous tutorials involving signing and sending transactions.

Render Content from Digital Object​

Once we created our digital object on-chain, what we love to do is to render and show this digital object. To do this, we need to first find the Spore Cell of our digital object and extract the data from the Spore Cell and decode the content from the data to render it in the browser.

Check out the showSporeContent function:

export async function showSporeContent(txHash: string, index = 0) {
  const indexHex = "0x" + index.toString(16);
  const { cell } = await rpc.getLiveCell({ txHash, index: indexHex }, true);
  if (cell == null) {
    return alert("Cell not found, please retry later");
  }
  const data = cell.data.content;
  const msg = unpackToRawSporeData(data);
  console.log("Spore data: ", msg);
  return msg;
}

We locate the Spore Cell by accepting a outpoint parameter(txHash and outputIndex), and use rpc.getLiveCell to get the Live Cell. Then we unpack the data content from this Cell:

const data = cell.data.content;
const msg = unpackToRawSporeData(data);

To render the image from this raw data, check out the renderSpore function in the index.tsx:

const renderSpore = async () => {
  const res = await showSporeContent(txHash, outputIndex);
  if (!res) return;
  setRawSporeData(res);
  // Create Blob from binary data
  const buffer = hexStringToUint8Array(res.content.toString().slice(2));
  const blob = new Blob([buffer], { type: res.contentType });
  const url = URL.createObjectURL(blob);
  setImageURL(url);
};

...
{imageURL && <img src={imageURL} />}

Congratulations!​

By following this tutorial this far, you have mastered how digital-object works on CKB. Here's a quick recap:

  • How Spore protocol works on CKB
  • Create an on-chain digital object with a picture via Spore-SDK
  • Render the picture in the browser from your digital object

Next Step​

So now your app works great on the local blockchain, you might want to switch it to different environments like Testnet and Mainnet.

To do this, you need to update the chain config and related code.

Open the ckb.ts in your project root dir, change the lumosConfig and CKB_RPC_URL:

//export const lumosConfig: config.Config = devConfig as config.Config;
export const lumosConfig = config.predefined.AGGRON4 as config.Config;

//export const CKB_RPC_URL = 'http://localhost:8114';
export const CKB_RPC_URL = "https://testnet.ckb.dev/rpc";

Acutally, we have the corresponding Testnet version examples for all these tutorials. The source code of the Testnet version is in https://github.com/nervosnetwork/docs.nervos.org/tree/develop-v2/examples, you can clone the repo and start running on Testnet.

git clone https://github.com/nervosnetwork/docs.nervos.org.git
cd docs.nervos.org.git/examples/<example-name>
yarn && yarn start

For more details, check out the README.md;

Additional Resources​