Spore SDK

https://github.com/sporeprotocol/spore-sdk
Admin
The Ultimate TypeScript SDK for Spore Protocol, enabling effortless creation of dapps for on-chain...
Tokens:9,691
Snippets:61
Trust Score:4.7
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Setup Spore SDK Development Environment

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/examples/acp/README.md

This command installs project dependencies and builds necessary packages for the Spore SDK examples, ensuring the local environment is ready for execution.

```shell
pnpm i && pnpm run build:packages
```

--------------------------------

### Setup Spore SDK Development Environment

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/examples/omnilock/README.md

This command installs project dependencies using PNPM and then builds the necessary packages within the Spore SDK, preparing the local environment for running examples.

```shell
pnpm i && pnpm run build:packages
```

--------------------------------

### Setup Spore SDK Development Environment

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/examples/secp256k1/README.md

Instructions to install dependencies and build packages for the Spore SDK.

```shell
pnpm i && pnpm run build:packages
```

--------------------------------

### Install Spore SDK Core Package via npm

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/setup.md

This command installs the `@spore-sdk/core` package as a dependency in your project using npm, a popular package manager for JavaScript. This is the initial step to integrate Spore SDK into your application development.

```shell
npm install @spore-sdk/core
```

--------------------------------

### Execute a Spore ACP Example

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/examples/acp/README.md

This command demonstrates how to run a specific Spore ACP example, such as creating an ACP Cluster, using `ts-node` from the current directory.

```shell
ts-node apis/createAcpCluster.ts
```

--------------------------------

### Execute a Spore SDK Example

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/examples/secp256k1/README.md

Command to run a specific TypeScript example file using ts-node.

```shell
ts-node apis/createSpore.ts
```

--------------------------------

### Configure Spore SDK Examples

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/examples/secp256k1/README.md

Instructions on how to update configuration settings for Spore SDK examples, including replacing default testing accounts and modifying SporeConfig.

```APIDOC
Configuration Options:
  File: examples/secp256k1/utils/config.ts
    - Replace default testing accounts
    - Modify default SporeConfig

Account Replacement:
  Locally (secp256k1 examples only):
    File: examples/secp256k1/utils/config.ts
    Variable: accounts
  Globally (all examples):
    File: examples/shared/index.ts
    Variable: accounts
```

--------------------------------

### Execute a Spore Omnilock Example

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/examples/omnilock/README.md

Navigate to the `examples/omnilock` directory and run a specific TypeScript example file, such as `createAcpCluster.ts`, using `ts-node` to demonstrate Omnilock functionality on-chain.

```shell
ts-node acp/createAcpCluster.ts
```

--------------------------------

### Install @spore-sdk/core package

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/packages/core/README.md

Install the @spore-sdk/core package as a dependency using npm, a common package manager.

```shell
npm install @spore-sdk/core
```

--------------------------------

### Review CKB Transaction on Explorer

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/examples/secp256k1/README.md

Guidance on how to review a transaction on CKB Explorer using its hash.

```shell
https://pudge.explorer.nervos.org/transaction/{hash}
```

--------------------------------

### Generate and Fund New CKB Testing Accounts

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/examples/secp256k1/README.md

Steps to create new CKB accounts using a generator tool and claim faucet CKBytes for testing purposes.

```APIDOC
Generate Account:
  1. Open CKB Generator Tool: https://ckb.tools/generator
  2. Click refresh icon (🔄) on the page to generate a new account
  3. Copy 'Private Key (256-bit)' from the 'Private/Public Key' block
  4. Replace any of the default testing accounts with the new account

Claim Faucet CKBytes:
  1. Copy 'Nervos CKB Address' from the 'Default Lock (Secp256k1-Blake160) - Testnet' block
  2. Open Nervos Faucet: https://faucet.nervos.org/
  3. Paste the address into the address input
  4. Click the 'Claim' button
  5. Wait for a while until the faucet process is completed
```

--------------------------------

### ClusterProxy Protocol API Operations

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/examples/secp256k1/README.md

Overview of core API functionalities for managing ClusterProxy entities, including creation, transfer, and melting.

```APIDOC
ClusterProxy API:
  createClusterProxy: Create a ClusterProxy
  transferClusterProxy: Transfer a ClusterProxy to another account
  meltClusterProxy: Melt a ClusterProxy and redeem occupied CKBytes
```

--------------------------------

### Spore Protocol API Operations

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/examples/secp256k1/README.md

Overview of core API functionalities for managing Spore assets, including creation, transfer, and melting.

```APIDOC
Spore API:
  createSpore: Create a Spore
  createSporeWithCluster: Create a Clustered Spore with a Cluster
  createSporeWithClusterAgent: Create a Clustered Spore with a ClusterAgent
  transferSpore: Transfer a Spore to another account
  meltSpore: Melt a Spore and redeem occupied CKBytes
```

--------------------------------

### Review Spore Transaction on CKB Explorer

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/examples/acp/README.md

After sending a transaction, this URL pattern allows users to review the transaction details on the CKB Explorer by replacing `{hash}` with the returned transaction hash.

```shell
https://pudge.explorer.nervos.org/transaction/{hash}
```

--------------------------------

### Cluster Protocol API Operations

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/examples/secp256k1/README.md

Overview of core API functionalities for managing Cluster entities, including creation and transfer.

```APIDOC
Cluster API:
  createCluster: Create a Cluster
  transferCluster: Transfer a Cluster to another account
```

--------------------------------

### Review Spore Transaction on CKB Explorer

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/examples/omnilock/README.md

After a transaction is sent and a hash is returned, use this URL pattern to review the transaction details on the CKB Explorer, replacing `{hash}` with the actual transaction hash.

```shell
https://pudge.explorer.nervos.org/transaction/{hash}
```

--------------------------------

### ClusterAgent Protocol API Operations

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/examples/secp256k1/README.md

Overview of core API functionalities for managing ClusterAgent entities, including creation, transfer, and melting.

```APIDOC
ClusterAgent API:
  createClusterAgent: Create a ClusterAgent
  transferClusterAgent: Transfer a ClusterAgent to another account
  meltClusterAgent: Melt a ClusterAgent and redeem occupied CKBytes
```

--------------------------------

### Get Global SporeConfig

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/utilities.md

Retrieves the globally set default SporeConfig, which is initially 'predefinedSporeConfigs.Aggron4'. This function allows access to the current configuration settings for the Spore SDK.

```APIDOC
declare function getSporeConfig<T extends string = string>(): SporeConfig<T>;
```

```typescript
const config = getSporeConfig();
```

--------------------------------

### Create Immortal Spore using setContentTypeParameters function (TypeScript)

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/recipes/create-immortal-spore.md

This TypeScript example illustrates an alternative method for creating an immortal Spore by utilizing the `setContentTypeParameters` helper function. This function allows for a more structured way to combine the content type string with its associated parameters, including the `immortal: true` flag, before passing it to the `createSpore` API.

```typescript
import { createSpore, setContentTypeParameters } from '@spore-sdk/core';

let { txSkeleton } = await createSpore({
  data: {
    content: JPEG_AS_BYTES,
    contentType: setContentTypeParameters(
      'image/jpeg', 
      {
        immortal: true, // enabling the immortal extension
      }
    ),
  },
  fromInfos: [WALLET_ADDRESS],
  toLock: WALLET_LOCK_SCRIPT,
});
```

--------------------------------

### Create Immortal Spore using contentTypeParameters (TypeScript)

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/recipes/create-immortal-spore.md

This TypeScript example demonstrates how to create an immortal Spore by directly embedding the `immortal: true` flag within the `contentTypeParameters` object of the `SporeData`. This method is suitable for enabling the immortal extension when defining the spore's content type properties.

```typescript
import { createSpore } from '@spore-sdk/core';

let { txSkeleton } = await createSpore({
  data: {
    content: JPEG_AS_BYTES,
    contentType: 'image/jpeg',
    contentTypeParameters: {
      immortal: true, // enabling the immortal extension
    },
  },
  fromInfos: [WALLET_ADDRESS],
  toLock: WALLET_LOCK_SCRIPT,
});
```

--------------------------------

### Set Spore SDK Configuration Globally

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/recipes/configure-spore-config.md

Illustrates how to set a SporeConfig globally using `setSporeConfig`, eliminating the need to pass the configuration object to every SDK function call. This example sets the Testnet config as the default.

```typescript
import { predefinedSporeConfigs, setSporeConfig, createSpore } from '@spore-sdk/core';

// Setting testnet config as the global default
setSporeConfig(predefinedSporeConfigs.Testnet);

// No need to pass the config object in the props
const result = await createSpore({
  data: {
    contentType: 'image/jpeg',
    content: JPEG_AS_BYTES,
  },
  fromInfos: [WALLET_ADDRESS],
  toLock: WALLET_LOCK,
});
```

--------------------------------

### Create Spore with custom capacity margin

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/recipes/capacity-margin.md

When creating a new spore or cluster, you can add an additional amount of CKBytes as capacity margin to the new cell. This margin can later be used to pay transaction fees. The example sets a margin of 2 CKB.

```typescript
import { createSpore } from '@spore-sdk/core';
import { BI } from '@ckb-lumos/lumos;

const result = await createSpore({
  data: NEW_SPORE_DATA,
  toLock: OWNER_LOCK_SCRIPT,
  fromInfos: [OWNER_ADDRESS],
  capacityMargin: BI.from(2_0000_0000) // 2 CKB
});
```

--------------------------------

### Construct Spore Creation Transaction using Spore SDK Core

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/recipes/construct-transaction.md

This TypeScript example demonstrates how to use the `createSpore` function from `@spore-sdk/core` to construct a transaction for creating a new spore on-chain. It requires `data` (contentType and content), `fromInfos` (sender addresses), and `toLock` (recipient lock). The function returns a `TransactionSkeleton` which represents an unfinished transaction ready for further processing like signing.

```typescript
import { createSpore, SporeConfig } from '@spore-sdk/core';

const createSporeResult = await createSpore({
  data: {
    contentType: 'image/jpeg',
    content: JPEG_AS_BYTES,
  },
  fromInfos: [WALLET_ADDRESS],
  toLock: WALLET_LOCK,
});
```

--------------------------------

### Decode ClusterData with @spore-sdk/core in TypeScript

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/recipes/handle-cell-data.md

This example illustrates how to decode a hexadecimal string representation of ClusterData back into its original structured object using ClusterData.unpack from @spore-sdk/core. It also demonstrates converting the decoded byte array fields back to human-readable strings using bufferToRawString.

```typescript
import { ClusterData, bufferToRawString } from '@spore-sdk/core';

const clusterDataHex = '0x3a0000000c0000001c0000000c000000636c7573746572206e616d651a0000006465736372697074696f6e206f6620636c7573746572';
const decodedClusterData = ClusterData.unpack(clusterDataHex);

console.log(decodedClusterData);
// {
//   name: '0x636c7573746572206e616d65',
//   description: '0x6465736372697074696f6e206f6620636c7573746572'
// }

console.log(bufferToRawString(decodedClusterData.name)); // cluster name
```

--------------------------------

### Spore: Create Spore API Reference

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/composed-apis.md

Documents the `createSpore` function, which allows users to mint new Spore assets. It details parameters such as `data`, `toLock`, `fromInfos`, and optional configurations for `cluster` and `clusterAgent` integration, returning transaction skeleton and output index.

```typescript
declare function createSpore(props: {
  data: SporeDataProps;
  toLock: Script;
  fromInfos: FromInfo[];
  changeAddress?: Address;
  updateOutput?: (cell: Cell) => Cell;
  capacityMargin?: BIish | ((cell: Cell, margin: BI) => BIish);
  cluster?: {
    updateOutput?: (cell: Cell) => Cell;
    capacityMargin?: BIish | ((cell: Cell, margin: BI) => BIish);
    updateWitness?: HexString | ((witness: HexString) => HexString);
  };
  clusterAgentOutPoint?: OutPoint;
  clusterAgent?: {
    updateOutput?: (cell: Cell) => Cell;
    capacityMargin?: BIish | ((cell: Cell, margin: BI) => BIish);
    updateWitness?: HexString | ((witness: HexString) => HexString);
  };
  maxTransactionSize?: number | false;
  config?: SporeConfig;
}): Promise<{
  txSkeleton: helpers.TransactionSkeletonType;
  outputIndex: number;
  reference: {
    referenceTarget: 'cluster' | 'clusterAgent' | 'none';
    referenceType?: 'cell' | 'lockProxy';
    cluster?: {
      inputIndex: number;
      outputIndex: number;
    };
    clusterAgent?: {
      inputIndex: number;
      outputIndex: number;
    };
  };
}>;
```

--------------------------------

### Configure Spore SDK with Predefined Mainnet SporeConfig

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/recipes/configure-spore-config.md

Demonstrates how to use a predefined SporeConfig, such as `predefinedSporeConfigs.Lina` (Mainnet), when creating a spore. This allows developers to quickly switch target environments without manual configuration.

```typescript
import { predefinedSporeConfigs, createSpore } from '@spore-sdk/core';

const result = await createSpore({
  data: {
    contentType: 'image/jpeg',
    content: JPEG_AS_BYTES,
  },
  fromInfos: [WALLET_ADDRESS],
  toLock: WALLET_LOCK,
  config: predefinedSporeConfigs.Lina, // using the mainnet config
});
```

--------------------------------

### Send CKB Transaction via RPC using Spore SDK and Lumos

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/recipes/construct-transaction.md

This TypeScript snippet shows how to finalize and send a signed `TransactionSkeleton` to the CKB network. It utilizes `predefinedSporeConfigs` for network settings and `helpers.createTransactionFromSkeleton` from `@ckb-lumos/lumos` to convert the skeleton into a sendable transaction. The transaction is then sent using an `RPC` client, returning the transaction hash.

```typescript
import { predefinedSporeConfigs } from '@spore-sdk/core';
import { helpers, RPC } from '@ckb-lumos/lumos;

// Get testnet config
const config = predefinedSporeConfigs.Testnet;

// Convert TransactionSkeleton to Transaction
const tx = helpers.createTransactionFromSkeleton(txSkeleton);

// Send the transaction
const rpc = new RPC(config.ckbNodeUrl);
const hash = await rpc.sendTransaction(tx, 'passthrough');
```

--------------------------------

### SporeConfig Object Properties Reference

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/recipes/configure-spore-config.md

Defines the structure and purpose of properties within the SporeConfig object, which is essential for configuring the Spore SDK. It includes settings for Lumos, CKB node URLs, transaction size limits, and script definitions.

```APIDOC
SporeConfig:
  lumos: Config for lumos. Refer to: @ckb-lumos/config-manager.
  ckbNodeUrl: CKB RPC node's URL, will be used when creating lumos/rpc instances. Refer to: @ckb-lumos/rpc.
  ckbIndexerUrl: CKB Indexer node's URL, will be used when creating lumos/ckb-indexer instances. Refer to: @ckb-lumos/ckb-indexer.
  maxTransactionSize: Specify the maximum size (in bytes) of single transactions, will be used in variants of APIs to prevent constructing oversize transactions.
  scripts: Define necessary script infos, etc. ScriptId, CellDep. For instance, the Spore SDK will use the script infos of Spore and Cluster.
  extensions: Define what SporeExtension(s) to be used in the Spore SDK. Note: this part is WIP (working in progress).
```

--------------------------------

### Cluster: Create Cluster API Reference

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/composed-apis.md

Documents the `createCluster` function, which enables the creation of new Cluster assets. It defines parameters for `ClusterDataProps` (name, description), `toLock`, `fromInfos`, and other transaction settings, returning the transaction skeleton and output index.

```typescript
declare function createCluster(props: {
  data: ClusterDataProps;
  toLock: Script;
  fromInfos: FromInfo[];
  changeAddress?: Address;
  updateOutput?: (cell: Cell) => Cell;
  capacityMargin?: BIish | ((cell: Cell, margin: BI) => BIish);
  maxTransactionSize?: number | false;
  config?: SporeConfig;
}): Promise<{
  txSkeleton: helpers.TransactionSkeletonType;
  outputIndex: number;
}>;

interface ClusterDataProps {
  name: string;
  description: string;
}
```

--------------------------------

### Create a New Cluster Proxy

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/composed-apis.md

Creates a new Cluster Proxy linked to a specified `clusterOutPoint`. This function requires a `toLock` script for the proxy's owner and `fromInfos` to fund the transaction. It returns a transaction skeleton, the output index of the newly created proxy, and details about its reference type.

```typescript
declare function createClusterProxy(props: {
  clusterOutPoint: OutPoint;
  minPayment?: BIish;
  toLock: Script;
  fromInfos: FromInfo[];
  changeAddress?: Address;
  updateOutput?(cell: Cell): Cell;
  capacityMargin?: BIish | ((cell: Cell, margin: BI) => BIish);
  cluster?: {
    updateOutput?(cell: Cell): Cell;
    capacityMargin?: BIish | ((cell: Cell, margin: BI) => BIish);
    updateWitness?: HexString | ((witness: HexString) => HexString);
  };
  config?: SporeConfig;
}): Promise<{
  txSkeleton: helpers.TransactionSkeletonType;
  outputIndex: number;
  reference: {
    referenceType: 'cell' | 'lockProxy';
    cluster?: {
      inputIndex: number;
      outputIndex: number;
    };
  };
}>;
```

--------------------------------

### Clone and Modify SporeConfig

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/utilities.md

Creates a new SporeConfig by cloning an existing one and applying partial changes. This is useful for creating modified configurations without altering the original global settings.

```APIDOC
declare function forkSporeConfig<T1 extends string, T2 extends string>(
  origin: SporeConfig<T1>,
  change: Partial<SporeConfig<T2>>,
): SporeConfig<T1 | T2>;
```

```typescript
const originalConfig = predefinedSporeConfigs.Aggron4;
const forkedConfig = forkSporeConfig(originalConfig, {
  maxTransactionSize: 100,
});
```

--------------------------------

### Fork and Customize a Predefined SporeConfig

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/recipes/configure-spore-config.md

Shows how to create a new SporeConfig by forking an existing predefined configuration. This allows developers to modify specific properties, like `maxTransactionSize`, while retaining other default settings from the original config.

```typescript
import { predefinedSporeConfigs, forkSporeConfig } from '@spore-sdk/core';

// The forked config is a deep clone of the original config 
const newConfig = forkSporeConfig(predefinedSporeConfigs.Testnet, {
  maxTransactionSize: 100,
});

// The two configs has different maxTransactionSize values
console.log(newConfig.maxTransactionSize === predefinedSporeConfigs.Testnet); // false
```

--------------------------------

### Create a New Cluster Agent

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/composed-apis.md

Creates a new Cluster Agent associated with a `clusterProxyOutPoint`. This function requires a `referenceType` ('cell' or 'payment'), a `toLock` for the agent's owner, and `fromInfos` for transaction funding. It returns a transaction skeleton, the output index of the new agent, and detailed reference information.

```typescript
declare function createClusterAgent(props: {
  clusterProxyOutPoint: OutPoint;
  referenceType: 'cell' | 'payment';
  paymentAmount?: BIish | ((minPayment: BI) => BIish);
  toLock: Script;
  fromInfos: FromInfo[];
  changeAddress?: Address;
  updateOutput?: (cell: Cell) => Cell;
  capacityMargin?: BIish | ((cell: Cell, margin: BI) => BIish);
  clusterProxy?: {
    updateOutput?: (cell: Cell) => Cell;
    capacityMargin?: BIish | ((cell: Cell, margin: BI) => BIish);
    updateWitness?: HexString | ((witness: HexString) => HexString);
  };
  config?: SporeConfig;
}): Promise<{
  txSkeleton: helpers.TransactionSkeletonType;
  outputIndex: number;
  reference: {
    referenceType: 'cell' | 'payment';
    clusterProxy?: {
      inputIndex: number;
      outputIndex: number;
    };
    payment?: {
      outputIndex: number;
    };
  };
}>;
```

--------------------------------

### Set Global SporeConfig

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/utilities.md

Sets the global default SporeConfig for the SDK. This allows users to customize the configuration, overriding the initial default of 'predefinedSporeConfigs.Aggron4'.

```APIDOC
declare function setSporeConfig<T extends string = string>(config: SporeConfig<T>): void;
```

```typescript
setSporeConfig(predefinedSporeConfigs.Aggron4);
```

--------------------------------

### Create Spore without capacity margin

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/recipes/capacity-margin.md

By default, a new spore/cluster will have 1 CKB of additional capacity as margin. To explicitly prevent adding any capacity margin to a new spore or cluster, set the `capacityMargin` property to `0`.

```typescript
import { createSpore } from '@spore-sdk/core';
import { BI } from '@ckb-lumos/lumos;

const result = await createSpore({
  data: NEW_SPORE_DATA,
  toLock: OWNER_LOCK_SCRIPT,
  fromInfos: [OWNER_ADDRESS],
  capacityMargin: BI.from(0) // No capacity margin will be added
});
```

--------------------------------

### Spore: Transfer Spore API Reference

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/composed-apis.md

Documents the `transferSpore` function, used to transfer an existing Spore asset to a new lock. It specifies parameters like `outPoint`, `toLock`, and various optional transaction configurations, returning the transaction skeleton and relevant indices.

```typescript
declare function transferSpore(props: {
  outPoint: OutPoint;
  toLock: Script;
  fromInfos?: FromInfo[];
  changeAddress?: Address;
  useCapacityMarginAsFee?: boolean;
  updateOutput?: (cell: Cell) => Cell;
  capacityMargin?: BIish | ((cell: Cell, margin: BI) => BIish);
  updateWitness?: HexString | ((witness: HexString) => HexString);
  defaultWitness?: HexString;
  since?: PackedSince;
  config?: SporeConfig;
}): Promise<{
  txSkeleton: helpers.TransactionSkeletonType;
  inputIndex: number;
  outputIndex: number;
}>;
```

--------------------------------

### Transfer Spore with Custom Capacity Margin

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/recipes/capacity-margin.md

Demonstrates how to use the `transferSpore` function from `@spore-sdk/core` to transfer a Spore cell while explicitly adding a `capacityMargin` and disabling `useCapacityMarginAsFee`. This is crucial for scenarios where the cell's existing capacity is insufficient for transaction fees, allowing the owner to 'fill up the gas'. Note that `capacityMargin` cannot be specified if `useCapacityMarginAsFee` is set to `true`.

```typescript
import { transferSpore } from '@spore-sdk/core';
import { BI } from '@ckb-lumos/lumos';

const result = await transferSpore({
  outPoint: LIVE_SPORE_OUTPOINT,
  toLock: OWNER_LOCK_SCRIPT,
  fromInfos: [OWNER_ADDRESS],
  capacityMargin: BI.from(1_0000_0000), // Add 1 CKB as margin, default to 0
  useCapacityMarginAsFee: false // Disable the feature, default to true
});
```

--------------------------------

### Encode SporeData with @spore-sdk/core

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/recipes/handle-cell-data.md

Demonstrates how to use `SporeData.pack` to encode SporeData, including content type and binary content, for on-chain storage. This process converts a structured SporeData object into a `Uint8Array` or hexadecimal string. Requires `@spore-sdk/core` and `@ckb-lumos/codec`.

```typescript
import { SporeData, bytifyRawString } from '@spore-sdk/core';
import { bytes } from '@ckb-lumos/codec;

const encodedSporeData = SporeData.pack({
  // specifies the file type of the content
  contentType: bytifyRawString('image/jpeg'),
  // jpeg file as bytes or hex
  content: '0xffd8ffe000104a46494600010101004800480000ffdb0043000a07070807060a0808080b0a0a0b0e18100e0d0d0e1d15161118231f2524221f2221262b372f26293429212230413134393b3e3e3e252e4449433c48373d3e3bffdb0043010a0b0b0e0d0e1c10101c3b2822283b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3bffc0001108000a000a03012200021101031101ffc4001500010100000000000000000000000000000407ffc4001f1000030002020301010000000000000000010203040500110621314114ffc40014010100000000000000000000000000000000ffc40014110100000000000000000000000000000000ffda000c03010002110311003f0064773b5c2d6f9b6c2db3cc7c76ced8e1499eec7f8dd10b40a127a9a92ce9ebd9631007de50fc4ed5c9f0ed2def57ad6baf83d28ec599d8cd49249fa49fde29f4daaa62e462beb30db1f2aa6d91230529672412cc3ae99bb00f67dfa1c4c632c684e10924a5250939a28554503a0001f001f9c0ffd9',
});

console.log(encodedSporeData); // Uint8Array [ ... ]
console.log(bytes.hexify(encodedSporeData)); // 0x42020000100000001e000000420200000a000000696d6167652f6a706567200200002f396a2f34414151536b5a4a5267414241514541534142494141442f3277424441416f484277674842676f494341674c43676f4c446867514467304e44683056466845594978386c4a4349664969456d4b7a63764a696b304b5345694d4545784e446b37506a342b4a53354553554d3853446339506a762f3277424441516f4c4377344e44687751454277374b43496f4f7a73374f7a73374f7a73374f7a73374f7a73374f7a73374f7a73374f7a73374f7a73374f7a73374f7a73374f7a73374f7a73374f7a73374f7a73374f7a762f774141524341414b41416f444153494141684542417845422f38514146514142415141414141414141414141414141414141414241662f7841416645414144414149434177454241414141414141414141414241674d4542514152426945785152542f784141554151454141414141414141414141414141414141414141412f38514146424542414141414141414141414141414141414141414141502f61414177444151414345514d52414438415a486337584331766d327774733878386473375934556d6537482b4e305174416f53657071537a7036396c6a454166655550784f31636e773753337656363172723450536a73575a324d314a4a4a2b6b6e393470394e71715975526976724d4e73664b71625a456a42536c6e4a424c4d4f756d627341396e33364845786a4c47684f454a4a4b556c43546d69685652514f6741423841483577502f5a
```

--------------------------------

### Log Decoded SporeData Content Type

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/recipes/handle-cell-data.md

Demonstrates logging the raw string representation of `decodedSporeData.contentType` after it has been processed from a buffer, showing its MIME type.

```typescript
console.log(bufferToRawString(decodedSporeData.contentType)); // image/jpeg
```

--------------------------------

### Decode SporeData with @spore-sdk/core

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/recipes/handle-cell-data.md

Illustrates how to use `SporeData.unpack` to decode a hexadecimal representation of SporeData back into its structured object, revealing its content type and content. This function simplifies the process of reading on-chain spore data. Requires `@spore-sdk/core`.

```typescript
import { SporeData, bufferToRawString } from '@spore-sdk/core';

const sporeDataHex = '0x42020000100000001e000000420200000a000000696d6167652f6a706567200200002f396a2f34414151536b5a4a5267414241514541534142494141442f3277424441416f484277674842676f494341674c43676f4c446867514467304e44683056466845594978386c4a4349664969456d4b7a63764a696b304b5345694d4545784e446b37506a342b4a53354553554d3853446339506a762f3277424441516f4c4377344e44687751454277374b43496f4f7a73374f7a73374f7a73374f7a73374f7a73374f7a73374f7a73374f7a73374f7a73374f7a73374f7a73374f7a73374f7a73374f7a73374f7a73374f7a762f774141524341414b41416f444153494141684542417845422f38514146514142415141414141414141414141414141414141414241662f7841416645414144414149434177454241414141414141414141414241674d4542514152426945785152542f784141554151454141414141414141414141414141414141414141412f38514146424542414141414141414141414141414141414141414141502f61414177444151414345514d52414438415a486337584331766d327774733878386473375934556d6537482b4e305174416f53657071537a7036396c6a454166655550784f31636e773753337656363172723450536a73575a324d314a4a4a2b6b6e393470394e71715975526976724d4e73664b71625a456a42536c6e4a424c4d4f756d627341396e33364845786a4c47684f454a4a4b556c43546d69685652514f6741423841483577502f5a';
const decodedSporeData = SporeData.unpack(sporeDataHex);

console.log(decodedSporeData);
// {
//   contentType: '0x696d6167652f6a706567',

```

--------------------------------

### Melt a Cluster Proxy

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/composed-apis.md

Melts (destroys) an existing Cluster Proxy identified by its `outPoint`. This operation requires a `toLock` for the recipient of any remaining capacity and supports optional transaction details like `fromInfos` and `minPayment`. It returns a transaction skeleton with the input and output indices related to the melted proxy.

```typescript
declare function meltClusterProxy(props: {
  outPoint: OutPoint;
  toLock: Script;
  minPayment?: BIish;
  fromInfos?: FromInfo[];
  changeAddress?: Address;
  useCapacityMarginAsFee?: boolean;
  updateOutput?: (cell: Cell) => Cell;
  capacityMargin?: BIish | ((cell: Cell, margin: BI) => BIish);
  updateWitness?: HexString | ((witness: HexString) => HexString);
  defaultWitness?: HexString;
  since?: PackedSince;
  config?: SporeConfig;
}): Promise<{
  txSkeleton: helpers.TransactionSkeletonType;
  inputIndex: number;
  outputIndex: number;
}>;
```

--------------------------------

### Decode SporeData Content Type using @spore-sdk/core

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/recipes/handle-cell-data.md

Shows how to use the `decodeContentType` function from `@spore-sdk/core` to parse a content type string into a structured object, including its type, subtype, media type, and parameters.

```typescript
import { encodeContentType, decodeContentType } from '@spore-sdk/core';

const decoded = decodeContentType('image/jpeg;a=1;a=2');

console.log(decoded);
// {
//   type: 'image',
//   subtype: 'jpeg',
//   mediaType: 'image/jpeg',
//   parameters: {
//     a: 1,
//   },
// }
```

```APIDOC
decodeContentType(contentTypeString: string): object
  - contentTypeString: string (required) - The content type string to decode (e.g., 'image/jpeg;a=1;a=2')
Returns: object - The decoded content type object:
  - type: string (e.g., 'image')
  - subtype: string (e.g., 'jpeg')
  - mediaType: string (e.g., 'image/jpeg')
  - parameters: object (e.g., { a: 1 })
```

--------------------------------

### SporeData.contentType Property Structure

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/recipes/handle-cell-data.md

Describes the structure of the `SporeData.contentType` property, which is a MIME type string composed of a media type and optional parameters.

```APIDOC
SporeData.contentType: string
  - Type: string (e.g., "image")
  - Subtype: string (e.g., "jpeg")
  - MediaType: string (e.g., "image/jpeg")
  - Parameters: object (key-value pairs, e.g., { a: "1", b: "2" })
```

--------------------------------

### Check SporeScript Support in Config

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/utilities.md

Determines if a given ScriptId is supported by the SporeConfig. Optionally, it can also verify if the script's name matches the target. Returns a boolean indicating support.

```APIDOC
declare function isSporeScriptSupported(config: SporeConfig, scriptId: ScriptId, scriptName?: string): boolean;
```

```typescript
const cell: Cell = { /* ... */ };
const isSupportedByName = isSporeScriptSupported(config, cell.cellOutput.type, 'Spore');
console.log(isSupportedByName); // true or false

const isSupportedAsSpore = isSporeScriptSupported(config, cell.cellOutput.type, 'Spore');
console.log(isSupportedAsSpore); // true or false
```

--------------------------------

### Retrieve SporeScript from Configuration

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/utilities.md

Fetches a specific SporeScript from the provided SporeConfig using its name, optionally filtered by tags or a precise ScriptId. This function throws an error if the requested script is not found.

```APIDOC
declare function getSporeScript(config: SporeConfig, scriptName: string): SporeScript;
declare function getSporeScript(config: SporeConfig, scriptName: string, tags: string[]): SporeScript;
declare function getSporeScript(config: SporeConfig, scriptName: string, scriptId: ScriptId): SporeScript;
```

```typescript
const sporeScript = getSporeScript(config, 'Spore');
const sporeScriptWithTag = getSporeScript(config, 'Spore', ['latest']);
const sporeScriptWithId = getSporeScript(config, 'Spore', {
  codehash: '0xbbad126377d45f90a8ee120da988a2d7332c78ba8fd679aab478a19d6c133494',
  hashType: 'data1',
});
```

--------------------------------

### Spore: Melt Spore API Reference

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/composed-apis.md

Documents the `meltSpore` function, designed to destroy or "melt" a Spore asset. It requires the `outPoint` of the Spore to be melted and allows for optional address and witness updates, returning the transaction skeleton and input index.

```typescript
declare function meltSpore(props: {
  outPoint: OutPoint;
  changeAddress?: Address;
  updateWitness?: HexString | ((witness: HexString) => HexString);
  defaultWitness?: HexString;
  since?: PackedSince;
  config?: SporeConfig;
}): Promise<{
  txSkeleton: helpers.TransactionSkeletonType;
  inputIndex: number;
}>;
```

--------------------------------

### Wait for On-Chain Transaction Commitment (TypeScript)

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/utilities.md

This asynchronous function waits for a specified transaction to be committed on the blockchain. It requires the transaction hash and an RPC client, and will throw an error if the transaction is not confirmed within approximately two minutes, providing a robust way to handle transaction finality.

```TypeScript
declare function waitForTransaction(hash: Hash, rpc: RPC): Promise<TransactionWithStatus>;
```

```TypeScript
import { RPC } from '@ckb-lumos/lumos';

const rpc = new RPC(predefinedSporeConfigs.Aggron4.ckbNodeUrl);
const tx = await waitForTransaction('0x...', rpc);
```

--------------------------------

### Encode ClusterData with @spore-sdk/core in TypeScript

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/recipes/handle-cell-data.md

This snippet demonstrates how to encode ClusterData for an on-chain cluster's Cell.data using the ClusterData.pack function from @spore-sdk/core. It shows the conversion of raw strings to byte arrays using bytifyRawString before packing, and then hexifying the result.

```typescript
import { ClusterData, bytifyRawString } from '@spore-sdk/core';
import { bytes } from '@ckb-lumos/codec';

const encodedClusterData = ClusterData.pack({
  name: bytifyRawString('cluster name'),
  description: bytifyRawString('description of the cluster'),
});

console.log(encodedClusterData); // Uint8Array [ ... ]
console.log(bytes.hexify(encodedClusterData)); // 0x3a0000000c0000001c0000000c000000636c7573746572206e616d651a0000006465736372697074696f6e206f6620636c7573746572
```

--------------------------------

### Transfer Cluster Ownership

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/composed-apis.md

Transfers ownership of an existing Cluster identified by its `outPoint`. It requires a `toLock` script for the new owner and supports optional parameters for transaction customization like `fromInfos` and `changeAddress`. The function returns a transaction skeleton along with the input and output indices of the transferred Cluster.

```typescript
declare function transferCluster(props: {
  outPoint: OutPoint;
  toLock: Script;
  fromInfos?: FromInfo[];
  changeAddress?: Address;
  useCapacityMarginAsFee?: boolean;
  updateOutput?: (cell: Cell) => Cell;
  capacityMargin?: BIish | ((cell: Cell, margin: BI) => BIish);
  updateWitness?: HexString | ((witness: HexString) => HexString);
  defaultWitness?: HexString;
  since?: PackedSince;
  config?: SporeConfig;
}): Promise<{
  txSkeleton: helpers.TransactionSkeletonType;
  inputIndex: number;
  outputIndex: number;
}>;
```

--------------------------------

### Melt Cluster Agent Function Declaration (TypeScript)

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/composed-apis.md

Defines the `meltClusterAgent` function, which is used to melt a cluster agent. It takes an `OutPoint` and optional `changeAddress`, `updateWitness`, and `config` as input, returning a transaction skeleton and the input index.

```TypeScript
declare function meltClusterAgent(props: {
  outPoint: OutPoint;
  changeAddress?: Address;
  updateWitness?: HexString | ((witness: HexString) => HexString);
  config?: SporeConfig;
}): Promise<{
  txSkeleton: helpers.TransactionSkeletonType;
  inputIndex: number;
}>;
```

--------------------------------

### Encode SporeData Content Type using @spore-sdk/core

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/recipes/handle-cell-data.md

Illustrates how to use the `encodeContentType` function from `@spore-sdk/core` to convert a structured content type object (type, subtype, parameters) into its string representation.

```typescript
import { encodeContentType, decodeContentType } from '@spore-sdk/core';

const encoded = encodeContentType({
  type: 'image',
  subtype: 'jpeg',
  parameters: {
    a: 1,
  },
});

console.log(encoded); // image/jpeg;a=1
```

```APIDOC
encodeContentType(contentTypeObject: object): string
  - contentTypeObject:
    - type: string (required) - The main type (e.g., 'image')
    - subtype: string (required) - The subtype (e.g., 'jpeg')
    - parameters: object (optional) - Key-value pairs of parameters (e.g., { a: 1 })
Returns: string - The encoded content type string (e.g., 'image/jpeg;a=1')
```

--------------------------------

### Transfer Cluster Agent Ownership

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/composed-apis.md

Transfers ownership of an existing Cluster Agent identified by its `outPoint`. It requires a `toLock` script for the new owner and supports optional transaction parameters like `fromInfos` and `useCapacityMarginAsFee`. The function returns a transaction skeleton along with the input and output indices of the transferred Cluster Agent.

```typescript
declare function transferClusterAgent(props: {
  outPoint: OutPoint;
  toLock: Script;
  fromInfos?: FromInfo[];
  changeAddress?: Address;
  useCapacityMarginAsFee?: boolean;
  updateOutput?: (cell: Cell) => Cell;
  capacityMargin?: BIish | ((cell: Cell, margin: BI) => BIish);
  updateWitness?: HexString | ((witness: HexString) => HexString);
  defaultWitness?: HexString;
  since?: PackedSince;
  config?: SporeConfig;
}): Promise<{
  txSkeleton: helpers.TransactionSkeletonType;
  inputIndex: number;
  outputIndex: number;
}>;
```

--------------------------------

### Transfer Cluster Proxy Ownership

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/composed-apis.md

Transfers ownership of an existing Cluster Proxy identified by its `outPoint`. Similar to transferring a Cluster, it specifies the new owner with `toLock` and allows for various transaction customization options such as `fromInfos` and `capacityMargin`. The function returns a transaction skeleton with the input and output indices of the transferred Cluster Proxy.

```typescript
declare function transferClusterProxy(props: {
  outPoint: OutPoint;
  toLock: Script;
  fromInfos?: FromInfo[];
  changeAddress?: Address;
  useCapacityMarginAsFee?: boolean;
  updateOutput?: (cell: Cell) => Cell;
  capacityMargin?: BIish | ((cell: Cell, margin: BI) => BIish);
  updateWitness?: HexString | ((witness: HexString) => HexString);
  defaultWitness?: HexString;
  since?: PackedSince;
  config?: SporeConfig;
}): Promise<{
  txSkeleton: helpers.TransactionSkeletonType;
  inputIndex: number;
  outputIndex: number;
}>;
```

--------------------------------

### Encode ContentType Object to String

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/utilities.md

Converts a structured ContentType object into its string representation, following standard content type formatting. This is useful for serializing content type information for network transmission or storage.

```APIDOC
declare function encodeContentType(encodable: EncodableContentType): string;
```

```typescript
const contentType = encodeContentType({
  type: 'image',
  subtype: 'svg+xml',
  parameters: {
    immortal: true,
    q: 0.9,
  },
});
console.log(contentType); // 'image/svg+xml;immortal=true;q=0.9'
```

--------------------------------

### Convert UTF-8 String to Uint8Array

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/utilities.md

Converts a UTF-8 raw string into a Uint8Array. This utility is useful for packing string data into a byte array format for various operations.

```APIDOC
declare function bytifyRawString(text: string): Uint8Array;
```

```typescript
const bytes: Uint8Array = bytifyRawString('hello world');
console.log(bytes.hexify(bytes)); // 0x07000000636f6e74656e74
```

--------------------------------

### Transfer Spore using default capacity margin fee payment

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/recipes/capacity-margin.md

When transferring a spore or cluster, the Spore SDK will, by default, attempt to use any existing capacity margin on the cell to pay for the transaction fee. No special configuration is required for this behavior.

```typescript
import { transferSpore } from '@spore-sdk/core';
import { BI } from '@ckb-lumos/lumos;

const result = await transferSpore({
  outPoint: LIVE_SPORE_OUTPOINT,
  toLock: RECEIVER_LOCK
});
```

--------------------------------

### Update SporeData Content Type Parameters using @spore-sdk/core

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/recipes/handle-cell-data.md

Demonstrates how to modify existing parameters of a content type string using the `setContentTypeParameters` function from `@spore-sdk/core`, allowing for easy updates without full re-encoding.

```typescript
import { setContentTypeParameters } from '@spore-sdk/core';

const contentType = 'image/jpeg;a=1;b=3';
const modified = setContentTypeParameters(contentType, {
  a: 2,
});

console.log(modified); // image/jpeg;a=2;b=3
```

```APIDOC
setContentTypeParameters(contentTypeString: string, parameters: object): string
  - contentTypeString: string (required) - The original content type string (e.g., 'image/jpeg;a=1;b=3')
  - parameters: object (required) - An object containing parameters to set or update (e.g., { a: 2 })
Returns: string - The modified content type string (e.g., 'image/jpeg;a=2;b=3')
```

--------------------------------

### Decode ContentType String to Object (TypeScript)

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/utilities.md

This function converts a content type string into a structured `DecodedContentType` object. It parses the main type, subtype, and any associated parameters, making it easier to work with complex content type definitions.

```TypeScript
declare function decodeContentType(contentType: string): DecodedContentType;
```

```TypeScript
const decoded = decodeContentType('image/svg+xml;immortal=true;q=0.9');
console.log(decoded); // { type: 'image', subtype: 'svg+xml', mediaType: 'image/svg+xml', parameters: { immortal: true, q: 0.9 } }
```

--------------------------------

### Convert Uint8Array to UTF-8 String

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/utilities.md

Unpacks a Uint8Array (or BytesLike) into a UTF-8 raw string. This function is the inverse of `bytifyRawString`, used for decoding byte array data back into human-readable text.

```APIDOC
declare function bufferToRawString(source: BytesLike, options?: TextDecodeOptions): string;
```

```typescript
const text: string = bufferToRawString('0x07000000636f6e74656e74');
console.log(text); // content
```

--------------------------------

### Validate ContentType String Format (TypeScript)

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/core/utilities.md

This function checks if a given content type string adheres to a valid format. It returns a boolean indicating whether the content type is well-formed, which is useful for input validation and ensuring data integrity.

```TypeScript
declare function isContentTypeValid(contentType: string): boolean;
```

```TypeScript
const result1 = isContentTypeValid('image/svg+xml;immortal=true;q=0.9');
console.log(result1); // true

const result2 = isContentTypeValid('image/;test=1');
console.log(result2); // false
```

--------------------------------

### Transfer Spore disabling capacity margin fee payment

Source: https://github.com/sporeprotocol/spore-sdk/blob/beta/docs/recipes/capacity-margin.md

To disable the use of capacity margin for fee payment during a spore transfer and instead use the general method of collecting additional cells, set `useCapacityMarginAsFee` to `false`. Note that `fromInfos` must also be provided when disabling this feature.

```typescript
import { transferSpore } from '@spore-sdk/core';
import { BI } from '@ckb-lumos/lumos;

const result = await transferSpore({
  outPoint: LIVE_SPORE_OUTPOINT,
  toLock: RECEIVER_LOCK,
  fromInfos: [OWNER_ADDRESS],
  useCapacityMarginAsFee: false
});
```
Tokens:
Raw