Documentation Index
Fetch the complete documentation index at: https://mintlify.com/ckb-devrel/ccc/llms.txt
Use this file to discover all available pages before exploring further.
@ckb-ccc/spore implements the Spore Protocol — CKB’s on-chain digital object (DOB) standard. Spores are content-addressed cells that carry arbitrary content (images, JSON, binary blobs) secured by CKB’s UTXO model.
Installation
npm install @ckb-ccc/spore
@ckb-ccc/shell, spore is already included as ccc.spore.
Exports
The package exports the spore namespace from the barrel:
import { spore } from "@ckb-ccc/spore";
// or, when using @ckb-ccc/shell:
import { ccc } from "@ckb-ccc/shell";
// ccc.spore.createSpore(...)
| Export | Description |
|---|
createSpore | Create a new Spore cell |
transferSpore | Transfer a Spore to a new owner |
meltSpore | Destroy a Spore and recover capacity |
findSpore | Look up a single Spore cell by ID |
findSpores | Search Spore cells by lock or cluster |
findSporesBySigner | Find all Spores owned by a signer |
createSporeCluster | Create a new Cluster |
transferSporeCluster | Transfer a Cluster to a new owner |
findCluster | Look up a Cluster by ID |
findSporeClusters | Search Cluster cells |
findSporeClustersBySigner | Find all Clusters owned by a signer |
dob | Digital object encoding utilities |
Key function signatures
createSpore
async function createSpore(params: {
signer: ccc.Signer;
data: SporeDataView;
to?: ccc.ScriptLike;
clusterMode?: "lockProxy" | "clusterCell" | "skip";
tx?: ccc.TransactionLike;
scriptInfo?: SporeScriptInfoLike;
scriptInfoHash?: ccc.HexLike;
}): Promise<{ tx: ccc.Transaction; id: ccc.Hex }>
transferSpore
async function transferSpore(params: {
signer: ccc.Signer;
id: ccc.HexLike;
to: ccc.ScriptLike;
tx?: ccc.TransactionLike;
scripts?: SporeScriptInfoLike[];
scriptInfoHash?: ccc.HexLike;
}): Promise<{ tx: ccc.Transaction }>
meltSpore
async function meltSpore(params: {
signer: ccc.Signer;
id: ccc.HexLike;
tx?: ccc.TransactionLike;
scripts?: SporeScriptInfoLike[];
scriptInfoHash?: ccc.HexLike;
}): Promise<{ tx: ccc.Transaction }>
createSporeCluster
async function createSporeCluster(params: {
signer: ccc.Signer;
data: ClusterDataView;
to?: ccc.ScriptLike;
tx?: ccc.TransactionLike;
scriptInfo?: SporeScriptInfoLike;
scriptInfoHash?: ccc.HexLike;
}): Promise<{ tx: ccc.Transaction; id: ccc.Hex }>
transferSporeCluster
async function transferSporeCluster(params: {
signer: ccc.Signer;
id: ccc.HexLike;
to: ccc.ScriptLike;
tx?: ccc.TransactionLike;
scripts?: SporeScriptInfoLike[];
scriptInfoHash?: ccc.HexLike;
}): Promise<{ tx: ccc.Transaction }>
Usage examples
Create a Spore
import { spore } from "@ckb-ccc/spore";
import { ccc } from "@ckb-ccc/shell";
const { tx, id } = await spore.createSpore({
signer,
data: {
contentType: "text/plain",
content: new TextEncoder().encode("Hello, Spore!"),
},
});
await tx.completeFeeBy(signer);
const txHash = await signer.sendTransaction(tx);
console.log("Spore ID:", id);
Create a Spore in a Cluster
const { tx: clusterTx, id: clusterId } = await spore.createSporeCluster({
signer,
data: {
name: "My Collection",
description: "A collection of digital objects",
},
});
await clusterTx.completeFeeBy(signer);
await signer.sendTransaction(clusterTx);
// Create a Spore that belongs to the cluster
const { tx, id: sporeId } = await spore.createSpore({
signer,
data: {
contentType: "image/png",
content: pngBytes,
clusterId,
},
clusterMode: "lockProxy",
});
await tx.completeFeeBy(signer);
await signer.sendTransaction(tx);
Find and transfer a Spore
const { cell } = await spore.findSpore(signer.client, sporeId);
const { script: newOwnerLock } = await ccc.Address.fromString(
"ckb1qzda0cr08m85hc8jlnfp3gog...",
signer.client,
);
const { tx } = await spore.transferSpore({
signer,
id: sporeId,
to: newOwnerLock,
});
await tx.completeFeeBy(signer);
await signer.sendTransaction(tx);
Melt a Spore
const { tx } = await spore.meltSpore({ signer, id: sporeId });
await tx.completeFeeBy(signer);
await signer.sendTransaction(tx);
DOB (digital object) encoding
The dob sub-namespace provides utilities for encoding Spore data following the DOB0/DOB1 specifications:
import { spore } from "@ckb-ccc/spore";
const encoded = spore.dob.encodeNativeRendererDob0({ /* DOB0 content */ });
Predefined script configurations
The package ships with predefined script info for both mainnet and testnet. These are selected automatically based on your client. You can also pass a custom scriptInfo to every function to target a different deployment.