CCC Docs
    Preparing search index...

    Class CoinXUdt

    An extensible UDT (xUDT) Coin implementation.

    CoinXUdt is a small specialization of Coin that understands the xUDT type args layout from RFC 52. It keeps the generic balance, transfer, and transaction completion behavior from Coin, while exposing the parsed xUDT args via CoinXUdt.args.

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

    Hierarchy (View Summary)

    Index
    constructor
    script transformerOnOutput? coBuild client filter cellDeps args
    shouldUseCoinsForCapacity
    amountFromUnsafe transformOutput setAmount infoFrom amountFrom calculateInfo calculateBalance isCoin getInputsInfo getInputsAmount getOutputsInfo getOutputsAmount getInfoBurned getAmountBurned getIntendedAmountBurned completeInputs completeInputsByAmount completeInputsAll complete completeChangeToOutput completeChangeToLock completeBy transfer mint burn new resolveOptions
    • Internal

      Parameters

      • options: {
            script: Script;
            transformerOnOutput: CoinTransformerOnOutput | null | undefined;
            coBuild: CoBuild;
            client: Client;
            filter: ClientIndexerSearchKeyFilter;
            cellDeps: CellDep[];
            args: CoinXUdtArgs;
        }

      Returns CoinXUdt

    script: Script

    Type script that identifies this Coin.

    transformerOnOutput?: CoinTransformerOnOutput | null

    Output transformer for Coin outputs.

    coBuild: CoBuild

    CoBuild instance for this Coin.

    client: Client

    Client for network requests.

    filter: ClientIndexerSearchKeyFilter

    Indexer search filter used to find Coin cells. Defaults to cells with this type script and outputDataLenRange: [16, ∞).

    cellDeps: CellDep[]

    Cell deps required by the type script, added to every built transaction.

    args: Readonly<CoinXUdtArgs>

    Parsed and normalized xUDT type args.

    If xUdtArgs was provided, this is the normalized form of that value. If only script.args was provided, this is parsed from the existing args.

    • get shouldUseCoinsForCapacity(): boolean
      Internal

      Whether Coin inputs should also be used to cover missing CKB capacity.

      Returns boolean

    • 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

    • Applies the configured output transformer to a transaction output.

      Parameters

      • tx: Transaction
      • outputIndex: number

      Returns 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.

      If the output does not exist.

    • 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>

    • 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>

    • 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>

    • 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>

    • 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>

    • Convenience wrapper around getInputsInfo that returns only the amount.

      Parameters

      • txLike: TransactionLike

      Returns Promise<bigint>

    • Convenience wrapper around getOutputsInfo that returns only the amount.

      Parameters

      • txLike: TransactionLike

      Returns Promise<bigint>

    • 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>

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

      Parameters

      • txLike: TransactionLike

      Returns Promise<bigint>

    • 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.

      // 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,
      );

    • 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 }>

      if the signer has insufficient Coin amount.

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

    • 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 }>

    • 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>

      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);

    • 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>

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

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

    • 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>

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

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

      Parameters

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

      Returns Promise<Transaction>

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

      completeChangeToLock for more control over the change destination.

    • 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.

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

    • 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.

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

    • 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.

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

    • Creates an xUDT coin helper.

      xUdtArgs takes priority over script.args for the final type script args. A complete script takes priority over knownScript; otherwise the known script shorthand defaults to ccc.KnownScript.XUdt.

      Parameters

      Returns Promise<CoinXUdt>

      if neither xUdtArgs nor script.args is provided.

      if the selected args cannot be parsed as xUDT args.

    • Internal

      Resolves xUDT args and asynchronous Coin dependencies.

      Parameters

      Returns Promise<
          {
              script: Script;
              transformerOnOutput: CoinTransformerOnOutput
              | null
              | undefined;
              coBuild: CoBuild;
              client: Client;
              filter: ClientIndexerSearchKeyFilter;
              cellDeps: CellDep[];
              args: CoinXUdtArgs;
          },
      >

    Settings
    Member Visibility

    On This Page
    Constructors
    Properties
    Accessors
    Methods