Class Coin

Readonlyscript

Optional ReadonlytransformerOnOutput

ReadonlycoBuild

Readonlyclient

Readonlyfilter

ReadonlycellDeps

Staticnew

• new(options: CoinOptions): Promise<Coin>

  Parameters

  • options: CoinOptions

  Returns Promise<Coin>

  Example

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

  Example

  const coin = await Coin.new({
    knownScript: ccc.KnownScript.SUdt,
    script: { args: ownerLock.hash() },
    client,
    transformerOnOutput: async (tx, outputIndex) => {
      tx.addOutput(companionCell);
      return tx;
    },
  });
  Copy

StaticamountFromUnsafe

• amountFromUnsafe(outputData: BytesLike): bigint

  Reads the Coin amount from raw output data without verifying the type script. Returns 0 if the data is shorter than 16 bytes.

  ⚠️ The caller must ensure the data belongs to a valid Coin cell. For safe extraction from an arbitrary cell use amountFrom.

  Parameters

  • outputData: BytesLike

  Returns bigint

transformOutput

• transformOutput(tx: Transaction, outputIndex: number): Promise<Transaction>

  Applies the configured output transformer to a transaction output.

  Parameters

  • tx: Transaction
  • outputIndex: number

  Returns Promise<Transaction>

setAmount

• setAmount(
      tx: Transaction,
      outputIndexLike: NumLike,
      amount: NumLike,
  ): Promise<Transaction>

  Writes a Coin amount into a transaction output and applies the configured transformer for that output.

  The amount is encoded as a 16-byte little-endian integer at outputData[0..16). Any bytes after the first 16 are preserved, which lets callers keep extension data attached to token cells.

  Parameters

  • tx: Transaction

    Transaction containing the output.

  • outputIndexLike: NumLike

    Index of the output to update.

  • amount: NumLike

    Coin amount to write into outputData[0..16).

  Returns Promise<Transaction>

  The transformed transaction.

  Throws

  If the output does not exist.

infoFrom

• infoFrom(
      cells:
          | CellAnyLike
          | Iterable<CellAnyLike, any, any>
          | AsyncIterable<CellAnyLike, any, any>,
      acc?: CoinInfoLike,
  ): Promise<CoinInfo>

  Aggregates Coin info (amount, capacity, count) from cells, skipping non-Coins. Accepts a single cell, a sync iterable, or an async iterable.

  Parameters

  • cells:
        | CellAnyLike
        | Iterable<CellAnyLike, any, any>
        | AsyncIterable<CellAnyLike, any, any>
  • Optionalacc: CoinInfoLike

  Returns Promise<CoinInfo>

amountFrom

• amountFrom(
      cells:
          | CellAnyLike
          | Iterable<CellAnyLike, any, any>
          | AsyncIterable<CellAnyLike, any, any>,
      acc?: NumLike | null,
  ): Promise<bigint>

  Convenience wrapper around infoFrom that returns only the amount.

  Parameters

  • cells:
        | CellAnyLike
        | Iterable<CellAnyLike, any, any>
        | AsyncIterable<CellAnyLike, any, any>
  • Optionalacc: NumLike | null

  Returns Promise<bigint>

calculateInfo

• calculateInfo(
      signer: Signer,
      options?: { source?: "chain" | "local" | null },
  ): Promise<CoinInfo>

  Scans all Coins owned by the signer and returns aggregated info.

  Parameters

  • signer: Signer
  • Optionaloptions: { source?: "chain" | "local" | null }

    • Optionalsource?: "chain" | "local" | null

      "chain" (default) queries on-chain state; "local" uses the local indexer cache which is faster but may be stale.

      ⚠️ Expensive — scales linearly with the number of Coin cells.

  Returns Promise<CoinInfo>

calculateBalance

• calculateBalance(
      signer: Signer,
      options?: { source?: "chain" | "local" | null },
  ): Promise<bigint>

  Convenience wrapper around calculateInfo that returns only the balance.

  ⚠️ Expensive — scans all Coin cells owned by the signer.

  Parameters

  • signer: Signer
  • Optionaloptions: { source?: "chain" | "local" | null }

  Returns Promise<bigint>

isCoin

• isCoin(cellLike: CellAnyLike): Promise<boolean>

  Returns whether the cell is a valid Coin for this token. Subclasses may override this to apply additional validation rules.

  Parameters

  • cellLike: CellAnyLike

  Returns Promise<boolean>

getInputsInfo

• getInputsInfo(txLike: TransactionLike): Promise<CoinInfo>

  Returns aggregated Coin info (amount, capacity, count) for all Coin inputs in the transaction.

  Parameters

  • txLike: TransactionLike

  Returns Promise<CoinInfo>

getInputsAmount

• getInputsAmount(txLike: TransactionLike): Promise<bigint>

  Convenience wrapper around getInputsInfo that returns only the amount.

  Parameters

  • txLike: TransactionLike

  Returns Promise<bigint>

getOutputsInfo

• getOutputsInfo(txLike: TransactionLike): Promise<CoinInfo>

  Returns aggregated Coin info (amount, capacity, count) for all Coin outputs in the transaction.

  Parameters

  • txLike: TransactionLike

  Returns Promise<CoinInfo>

getOutputsAmount

• getOutputsAmount(txLike: TransactionLike): Promise<bigint>

  Convenience wrapper around getOutputsInfo that returns only the amount.

  Parameters

  • txLike: TransactionLike

  Returns Promise<bigint>

getInfoBurned

• getInfoBurned(txLike: TransactionLike): Promise<CoinInfo>

  Returns inputs minus outputs as a CoinInfo. Positive amount means tokens are burned; positive capacity means Coins provide surplus CKB.

  Parameters

  • txLike: TransactionLike

  Returns Promise<CoinInfo>

getAmountBurned

• getAmountBurned(txLike: TransactionLike): Promise<bigint>

  Convenience wrapper around getInfoBurned that returns only the amount (inputs − outputs).

  Parameters

  • txLike: TransactionLike

  Returns Promise<bigint>

getIntendedAmountBurned

• getIntendedAmountBurned(txLike: TransactionLike): Promise<bigint>

  Parameters

  • txLike: TransactionLike

  Returns Promise<bigint>

completeInputs

• completeInputs<T>(
      signer: Signer,
      accumulator: (
          acc: T,
          cell: Cell,
          coinInfo: CoinInfo,
          i: number,
          cells: Cell[],
      ) => T | Promise<T | undefined> | undefined,
      init: T,
      txLike?: TransactionLike | null,
  ): Promise<{ tx: Transaction; addedCount: number; accumulated?: T }>

  Low-level input selector driven by a custom accumulator. For each candidate Coin cell the accumulator receives (state, cell, coinInfo) and returns the next state to keep going, or undefined to stop.

  Type Parameters

  • T

  Parameters

  • signer: Signer
  • accumulator: (
        acc: T,
        cell: Cell,
        coinInfo: CoinInfo,
        i: number,
        cells: Cell[],
    ) => T | Promise<T | undefined> | undefined
  • init: T
  • OptionaltxLike: TransactionLike | null

  Returns Promise<{ tx: Transaction; addedCount: number; accumulated?: T }>

  accumulated is undefined if the target was reached before all cells were visited.

  Example

  // Collect inputs until amount reaches a target
  const { tx } = await coin.completeInputs(
    signer,
    (acc, _cell, coinInfo) => {
      const next = acc + coinInfo.amount;
      return next >= target ? undefined : next;
    },
    ccc.Zero,
    tx,
  );
  Copy

completeInputsByAmount

• completeInputsByAmount(
      signer: Signer,
      txLike?: TransactionLike | null,
      amountTweak?: NumLike | null,
      capacityTweak?: NumLike | null,
  ): Promise<{ addedCount: number; tx: Transaction }>

  Adds Coin inputs until the Coin amount gap is covered. When shouldUseCoinsForCapacity is enabled, it also attempts to cover the CKB capacity gap on a best-effort basis (capacity may still be negative if Coin inputs are exhausted before it is satisfied).

  Parameters

  • signer: Signer
  • OptionaltxLike: TransactionLike | null
  • OptionalamountTweak: NumLike | null

    Extra Coin amount to require beyond what outputs consume.

  • OptionalcapacityTweak: NumLike | null

    Extra CKB capacity to require beyond what outputs consume.

  Returns Promise<{ addedCount: number; tx: Transaction }>

  Throws

  if the signer has insufficient Coin amount.

  Example

  const { tx: completedTx } = await coin.completeInputsByAmount(signer);
  Copy

completeInputsAll

• completeInputsAll(
      signer: Signer,
      txLike?: TransactionLike | null,
  ): Promise<{ addedCount: number; tx: Transaction }>

  Adds ALL available Coins from the signer as inputs. Useful for consolidation or full sweeps.

  Parameters

  • signer: Signer
  • OptionaltxLike: TransactionLike | null

  Returns Promise<{ addedCount: number; tx: Transaction }>

complete

• complete(
      signer: Signer,
      change: (
          tx: Transaction,
          amount: bigint,
      ) => TransactionLike | Promise<TransactionLike>,
      txLike?: TransactionLike | null,
      options?: { shouldAddInputs?: boolean | null },
  ): Promise<Transaction>

  Low-level completion primitive. Adds Coin inputs, then calls change(tx, amount) to write the change output.

  complete never manages CKB capacity on its own — it only opportunistically uses any capacity gap between inputs and outputs to merge Coin cells (reducing the number of Coin inputs added), on a best-effort basis. It does not guarantee tx has enough capacity afterwards; follow up with tx.completeBy (or similar) to complete capacity.

  Parameters

  • signer: Signer
  • change: (tx: Transaction, amount: bigint) => TransactionLike | Promise<TransactionLike>

    Callback that receives the transaction and the excess Coin amount, writes the change output, and returns the resulting transaction. It must be side-effect-free beyond modifying tx, as it may be invoked more than once (e.g. speculatively on a clone) before being applied to the final transaction.

  • OptionaltxLike: TransactionLike | null
  • Optionaloptions: { shouldAddInputs?: boolean | null }

    • OptionalshouldAddInputs?: boolean | null

      When false, skips input sourcing entirely; the caller is responsible for ensuring tx already has enough Coin inputs. Defaults to true.

  Returns Promise<Transaction>

  Example

  const completedTx = await coin.complete(signer, async (tx, amount) => {
    const outputIndex = tx.addOutput({
      cellOutput: { lock: changeLock, type: coin.script },
      outputData: "0x",
    }) - 1;
    return coin.setAmount(tx, outputIndex, amount);
  }, tx);
  Copy

completeChangeToOutput

• completeChangeToOutput(
      signer: Signer,
      indexLike: NumLike,
      txLike?: TransactionLike | null,
      options?: { shouldAddInputs?: boolean | null },
  ): Promise<Transaction>

  Completes the transaction by writing the excess Coin amount into the existing output at index. The output must already be a valid Coin cell with this type script.

  Parameters

  • signer: Signer
  • indexLike: NumLike
  • OptionaltxLike: TransactionLike | null
  • Optionaloptions: { shouldAddInputs?: boolean | null }

  Returns Promise<Transaction>

  Throws

  If the output at index does not exist or is not a valid Coin.

  Example

  // Change goes into output 1 of the transaction
  const completedTx = await coin.completeChangeToOutput(signer, 1, tx);
  Copy

completeChangeToLock

• completeChangeToLock(
      signer: Signer,
      changeLike: {} & {},
      txLike?: TransactionLike | null,
      options?: { shouldAddInputs?: boolean | null },
  ): Promise<Transaction>

  Completes the transaction by creating a new change output locked to changeLike.

  Parameters

  • signer: Signer
  • changeLike: {} & {}
  • OptionaltxLike: TransactionLike | null
  • Optionaloptions: { shouldAddInputs?: boolean | null }

  Returns Promise<Transaction>

  Example

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

completeBy

• completeBy(
      signer: Signer,
      tx?: TransactionLike | null,
      options?: { shouldAddInputs?: boolean | null },
  ): Promise<Transaction>

  Convenience wrapper around completeChangeToLock using the signer's recommended address.

  Parameters

  • signer: Signer
  • Optionaltx: TransactionLike | null
  • Optionaloptions: { shouldAddInputs?: boolean | null }

  Returns Promise<Transaction>

  Example

  const completedTx = await coin.completeBy(signer, tx);
  await completedTx.completeFeeBy(signer);
  await signer.sendTransaction(completedTx);
  Copy

  See

  completeChangeToLock for more control over the change destination.

transfer

• transfer(
      transfers: { to: {} & {}; amount: NumLike }[],
      txLike?: TransactionLike | null,
  ): Promise<Transaction>

  Make the transaction perform transfer actions to the specified recipients.

  Parameters

  • transfers: { to: {} & {}; amount: NumLike }[]
  • OptionaltxLike: TransactionLike | null

  Returns Promise<Transaction>

  The updated transaction with added transfer outputs and CoBuild actions.

  Example

  const tx = await coin.transfer([
    { to: recipientLock, amount: 100n },
  ]);
  const completedTx = await coin.completeBy(signer, tx);
  await completedTx.completeFeeBy(signer);
  await signer.sendTransaction(completedTx);
  Copy

mint

• mint(
      mints: { to: {} & {}; amount: NumLike }[],
      txLike?: TransactionLike | null,
  ): Promise<Transaction>

  Make the transaction perform mint actions to the specified recipients.

  Parameters

  • mints: { to: {} & {}; amount: NumLike }[]
  • OptionaltxLike: TransactionLike | null

  Returns Promise<Transaction>

  The updated transaction with added mint outputs and CoBuild actions.

  Example

  const tx = await coin.mint([
    { to: recipientLock, amount: 100n },
  ]);
  const completedTx = await coin.completeBy(signer, tx);
  await completedTx.completeFeeBy(signer);
  await signer.sendTransaction(completedTx);
  Copy

burn

• burn(amount: NumLike, txLike?: TransactionLike | null): Promise<Transaction>

  Make the transaction perform burn actions for the specified amount.

  Parameters

  • amount: NumLike
  • OptionaltxLike: TransactionLike | null

  Returns Promise<Transaction>

  The updated transaction with appended CoBuild actions.

  Example

  const tx = await coin.burn(100n);
  const completedTx = await coin.completeBy(signer, tx);
  await completedTx.completeFeeBy(signer);
  await signer.sendTransaction(completedTx);
  Copy