Module @ckb-ccc coin

CCC's Support for Coin

GitHub commit activity GitHub last commit GitHub branch check runs

CCC - CKBers' Codebase is a one-stop solution for your CKB JS/TS ecosystem development.
Empower yourself with CCC to discover the unlimited potential of CKB.
Interoperate with wallets from different chain ecosystems.
Fully enabling CKB's Turing completeness and cryptographic freedom power.

Quick Start

Coin from @ckb-ccc/coin is a generic helper for on-chain fungible tokens identified by a CKB type script.

Instantiate

import { Coin } from "@ckb-ccc/coin";
import { ccc } from "@ckb-ccc/core";

// Classic instantiation with explicit script and cellDeps
const coin = await Coin.new({
  script: {
    codeHash: "0x...",
    hashType: "type",
    args: "0x...",
  },
  client,
  cellDeps: [{ outPoint: codeOutPoint, depType: "code" }],
});

// Instantiation via knownScript (e.g., sUDT)
const sUdt = await Coin.new({
  knownScript: ccc.KnownScript.SUdt,
  script: {
    args: ownerLock.hash(),
  },
  client,
});

// Instantiation of xUDT via CoinXUdt with structured args
import { CoinXUdt } from "@ckb-ccc/coin";

const xUdt = await CoinXUdt.new({
  xUdtArgs: {
    ownerScriptHash: ownerLock.hash(),
    ownerModeOutputType: true,
  },
  client,
});

Query balance

// Total balance across all cells of the signer
const balance = await coin.calculateBalance(signer);
console.log(`Balance: ${balance}`);

// Full info: Balance + CKB capacity + cell count
const info = await coin.calculateInfo(signer);
console.log(`Balance: ${info.amount}, Cells: ${info.count}`);

Send

Build the transaction manually, then use completeBy to add Coin inputs and a change output:

const coin = await Coin.new({
  knownScript: ccc.KnownScript.SUdt,
  script: {
    args: ownerLock.hash(),
  },
  client,
});

const { script: to } = await signer.getRecommendedAddressObj();

// Build outputs
const tx = await coin.transfer([{ to, amount: 1000n }]);

// Add Coin inputs + change (change goes back to signer)
const completedTx = await coin.completeBy(signer, tx);

// Cover CKB capacity and fee
await completedTx.completeInputsByCapacity(signer);
await completedTx.completeFeeBy(signer);

const txHash = await signer.sendTransaction(completedTx);

Change to a specific address

const { script: changeLock } = await signer.getRecommendedAddressObj();
const completedTx = await coin.completeChangeToLock(signer, changeLock, tx);

Extensible UDT (xUDT) Support

CoinXUdt extends Coin to provide specialized support for RFC 52 extensible UDT (xUDT).

Args Encoding/Decoding: Provides CoinXUdtArgs to correctly build and parse xUDT type script arguments, supporting owner-mode flags.
Default Known Script: When knownScript is omitted, CoinXUdt uses ccc.KnownScript.XUdt. A complete script with codeHash and hashType takes priority over this shorthand. Pass script.args to use existing xUDT args, or pass xUdtArgs to build args from ownerScriptHash and flags.
Underlying Coin Compatibility: Inherits all query, transfer, and transaction completion methods of the generic Coin class.