@ckb-ccc/core 1.9.1 → 1.10.0

package/src/ckb/transaction.ts

@@ -7,11 +7,7 @@ import {
   type ClientBlockHeaderLike,
 } from "../client/index.js";
 import { KnownScript } from "../client/knownScript.js";
-import {
-  Zero,
-  fixedPointFrom,
-  fixedPointToString,
-} from "../fixedPoint/index.js";
+import { Zero, fixedPointFrom } from "../fixedPoint/index.js";
 import { Hasher, HasherCkb, hashCkb } from "../hasher/index.js";
 import { Hex, HexLike, hexFrom } from "../hex/index.js";
 import { mol } from "../molecule/index.js";
@@ -27,6 +23,10 @@ import type { Signer } from "../signer/index.js";
 import { apply, reduceAsync } from "../utils/index.js";
 import { Script, ScriptLike, ScriptOpt } from "./script.js";
 import { DEP_TYPE_TO_NUM, NUM_TO_DEP_TYPE } from "./transaction.advanced.js";
+import {
+  ErrorTransactionInsufficientCapacity,
+  ErrorTransactionInsufficientCoin,
+} from "./transactionErrors.js";
 import type { LumosTransactionSkeletonType } from "./transactionLumos.js";
 
 export const DepTypeCodec: mol.Codec<DepTypeLike, DepType> = mol.Codec.from({
@@ -162,6 +162,36 @@ export class OutPoint extends mol.Entity.Base<OutPointLike, OutPoint>() {
     }
     return new OutPoint(hexFrom(outPoint.txHash), numFrom(outPoint.index));
   }
+
+  /**
+   * Clone a OutPoint.
+   *
+   * @returns A cloned OutPoint instance.
+   *
+   * @example
+   * ```typescript
+   * const outPoint1 = outPoint0.clone();
+   * ```
+   */
+  clone(): OutPoint {
+    return new OutPoint(this.txHash, this.index);
+  }
+
+  /**
+   * Check if the OutPoint is equal to another OutPoint.
+   * @public
+   * @param other - The other OutPoint to compare with
+   * @returns True if the OutPoints are equal, false otherwise
+   *
+   * @example
+   * ```typescript
+   * const isEqual = outPoint0.eq(outPoint1);
+   * ```
+   */
+  eq(other: OutPointLike): boolean {
+    other = OutPoint.from(other);
+    return this.txHash === other.txHash && this.index === other.index;
+  }
 }
 
 /**
@@ -229,6 +259,20 @@ export class CellOutput extends mol.Entity.Base<CellOutputLike, CellOutput>() {
       apply(Script.from, cellOutput.type),
     );
   }
+
+  /**
+   * Clone a CellOutput.
+   *
+   * @returns A cloned CellOutput instance.
+   *
+   * @example
+   * ```typescript
+   * const cellOutput1 = cellOutput0.clone();
+   * ```
+   */
+  clone(): CellOutput {
+    return new CellOutput(this.capacity, this.lock.clone(), this.type?.clone());
+  }
 }
 export const CellOutputVec = mol.vector(CellOutput);
 
@@ -700,12 +744,23 @@ export class CellInput extends mol.Entity.Base<CellInputLike, CellInput>() {
     return (await this.getCell(client)).getDaoProfit(client);
   }
 
+  /**
+   * Clone a CellInput.
+   *
+   * @returns A cloned CellInput instance.
+   *
+   * @example
+   * ```typescript
+   * const cellInput1 = cellInput0.clone();
+   * ```
+   */
   clone(): CellInput {
-    const cloned = super.clone();
-    cloned.cellOutput = this.cellOutput;
-    cloned.outputData = this.outputData;
-
-    return cloned;
+    return new CellInput(
+      this.previousOutput.clone(),
+      this.since,
+      this.cellOutput?.clone(),
+      this.outputData,
+    );
   }
 }
 export const CellInputVec = mol.vector(CellInput);
@@ -741,21 +796,6 @@ export class CellDep extends mol.Entity.Base<CellDepLike, CellDep>() {
     super();
   }
 
-  /**
-   * Clone a CellDep.
-   *
-   * @returns A cloned CellDep instance.
-   *
-   * @example
-   * ```typescript
-   * const cellDep1 = cellDep0.clone();
-   * ```
-   */
-
-  clone(): CellDep {
-    return new CellDep(this.outPoint.clone(), this.depType);
-  }
-
   /**
    * Creates a CellDep instance from a CellDepLike object.
    *
@@ -781,6 +821,20 @@ export class CellDep extends mol.Entity.Base<CellDepLike, CellDep>() {
       depTypeFrom(cellDep.depType),
     );
   }
+
+  /**
+   * Clone a CellDep.
+   *
+   * @returns A cloned CellDep instance.
+   *
+   * @example
+   * ```typescript
+   * const cellDep1 = cellDep0.clone();
+   * ```
+   */
+  clone(): CellDep {
+    return new CellDep(this.outPoint.clone(), this.depType);
+  }
 }
 export const CellDepVec = mol.vector(CellDep);
 
@@ -964,6 +1018,55 @@ export class Transaction extends mol.Entity.Base<
     this.witnesses = tx.witnesses;
   }
 
+  /**
+   * Creates a deep copy of the transaction.
+   * This method creates a new Transaction instance with all nested objects cloned,
+   * ensuring that modifications to the cloned transaction do not affect the original.
+   *
+   * @returns A new Transaction instance that is a deep copy of the current transaction.
+   *
+   * @example
+   * ```typescript
+   * const originalTx = Transaction.from({
+   *   version: 0,
+   *   inputs: [{ previousOutput: { txHash: "0x...", index: 0 } }],
+   *   outputs: [{ capacity: 1000n, lock: lockScript }],
+   *   outputsData: ["0x"],
+   *   witnesses: ["0x"]
+   * });
+   *
+   * const clonedTx = originalTx.clone();
+   *
+   * // Modifications to clonedTx won't affect originalTx
+   * clonedTx.addOutput({ capacity: 2000n, lock: anotherLockScript });
+   * console.log(originalTx.outputs.length); // Still 1
+   * console.log(clonedTx.outputs.length);   // Now 2
+   * ```
+   *
+   * @remarks
+   * The clone operation performs deep copying for:
+   * - Cell dependencies (cellDeps) - each CellDep is cloned
+   * - Inputs - each CellInput is cloned
+   * - Outputs - each CellOutput is cloned
+   *
+   * The following are shallow copied (references to immutable data):
+   * - Header dependencies (headerDeps) - Hex strings are immutable
+   * - Output data (outputsData) - Hex strings are immutable
+   * - Witnesses - Hex strings are immutable
+   * - Version - bigint is immutable
+   */
+  clone(): Transaction {
+    return new Transaction(
+      this.version,
+      this.cellDeps.map((c) => c.clone()),
+      this.headerDeps.map((h) => h),
+      this.inputs.map((i) => i.clone()),
+      this.outputs.map((o) => o.clone()),
+      this.outputsData.map((o) => o),
+      this.witnesses.map((w) => w),
+    );
+  }
+
   /**
    * Creates a Transaction instance from a TransactionLike object.
    *
@@ -1697,8 +1800,8 @@ export class Transaction extends mol.Entity.Base<
       return addedCount;
     }
 
-    throw new Error(
-      `Insufficient CKB, need ${fixedPointToString(expectedCapacity - accumulated)} extra CKB`,
+    throw new ErrorTransactionInsufficientCapacity(
+      expectedCapacity - accumulated,
     );
   }
 
@@ -1782,8 +1885,9 @@ export class Transaction extends mol.Entity.Base<
       return addedCount;
     }
 
-    throw new Error(
-      `Insufficient coin, need ${expectedBalance - accumulated} extra coin`,
+    throw new ErrorTransactionInsufficientCoin(
+      expectedBalance - accumulated,
+      type,
     );
   }
 
@@ -1836,12 +1940,54 @@ export class Transaction extends mol.Entity.Base<
     return (numFrom(txSize) * numFrom(feeRate) + numFrom(999)) / numFrom(1000);
   }
 
+  /**
+   * Completes the transaction fee by adding inputs and handling change outputs.
+   * This method automatically calculates the required fee based on the transaction size and fee rate,
+   * adds necessary inputs to cover the fee, and handles change outputs through the provided change function.
+   *
+   * @param from - The signer to complete inputs from and prepare the transaction.
+   * @param change - A function that handles change capacity. It receives the transaction and excess capacity,
+   *                 and should return the additional capacity needed (0 if change is handled successfully,
+   *                 positive number if more capacity is needed for change cell creation).
+   * @param expectedFeeRate - The expected fee rate in shannons per 1000 bytes. If not provided,
+   *                          it will be fetched from the client.
+   * @param filter - Optional filter for selecting cells when adding inputs.
+   * @param options - Optional configuration object.
+   * @param options.feeRateBlockRange - Block range for fee rate calculation when expectedFeeRate is not provided.
+   * @param options.maxFeeRate - Maximum allowed fee rate.
+   * @param options.shouldAddInputs - Whether to add inputs automatically. Defaults to true.
+   * @returns A promise that resolves to a tuple containing:
+   *          - The number of inputs added during the process
+   *          - A boolean indicating whether change outputs were created (true) or fee was paid without change (false)
+   *
+   * @throws {ErrorTransactionInsufficientCapacity} When there's not enough capacity to cover the fee.
+   * @throws {Error} When the change function doesn't properly handle the available capacity.
+   *
+   * @example
+   * ```typescript
+   * const [addedInputs, hasChange] = await tx.completeFee(
+   *   signer,
+   *   (tx, capacity) => {
+   *     if (capacity >= 61_00000000n) { // Minimum for a change cell
+   *       tx.addOutput({ capacity, lock: changeScript });
+   *       return 0;
+   *     }
+   *     return 61_00000000n; // Need more capacity for change cell
+   *   },
+   *   1000n // 1000 shannons per 1000 bytes
+   * );
+   * ```
+   */
   async completeFee(
     from: Signer,
     change: (tx: Transaction, capacity: Num) => Promise<NumLike> | NumLike,
     expectedFeeRate?: NumLike,
     filter?: ClientCollectableSearchKeyFilterLike,
-    options?: { feeRateBlockRange?: NumLike; maxFeeRate?: NumLike },
+    options?: {
+      feeRateBlockRange?: NumLike;
+      maxFeeRate?: NumLike;
+      shouldAddInputs?: boolean;
+    },
   ): Promise<[number, boolean]> {
     const feeRate =
       expectedFeeRate ??
@@ -1856,6 +2002,15 @@ export class Transaction extends mol.Entity.Base<
     while (true) {
       const tx = this.clone();
       const collected = await (async () => {
+        if (!(options?.shouldAddInputs ?? true)) {
+          const fee =
+            (await tx.getFee(from.client)) - leastFee - leastExtraCapacity;
+          if (fee < Zero) {
+            throw new ErrorTransactionInsufficientCapacity(-fee);
+          }
+          return 0;
+        }
+
         try {
           return await tx.completeInputsByCapacity(
             from,
@@ -1863,8 +2018,13 @@ export class Transaction extends mol.Entity.Base<
             filter,
           );
         } catch (err) {
-          if (leastExtraCapacity !== Zero) {
-            throw new Error("Not enough capacity for the change cell");
+          if (
+            err instanceof ErrorTransactionInsufficientCapacity &&
+            leastExtraCapacity !== Zero
+          ) {
+            throw new ErrorTransactionInsufficientCapacity(err.amount, {
+              isForChange: true,
+            });
           }
 
           throw err;
@@ -1918,6 +2078,11 @@ export class Transaction extends mol.Entity.Base<
     change: ScriptLike,
     feeRate?: NumLike,
     filter?: ClientCollectableSearchKeyFilterLike,
+    options?: {
+      feeRateBlockRange?: NumLike;
+      maxFeeRate?: NumLike;
+      shouldAddInputs?: boolean;
+    },
   ): Promise<[number, boolean]> {
     const script = Script.from(change);
 
@@ -1935,6 +2100,7 @@ export class Transaction extends mol.Entity.Base<
       },
       feeRate,
       filter,
+      options,
     );
   }
 
@@ -1942,10 +2108,15 @@ export class Transaction extends mol.Entity.Base<
     from: Signer,
     feeRate?: NumLike,
     filter?: ClientCollectableSearchKeyFilterLike,
+    options?: {
+      feeRateBlockRange?: NumLike;
+      maxFeeRate?: NumLike;
+      shouldAddInputs?: boolean;
+    },
   ): Promise<[number, boolean]> {
     const { script } = await from.getRecommendedAddressObj();
 
-    return this.completeFeeChangeToLock(from, script, feeRate, filter);
+    return this.completeFeeChangeToLock(from, script, feeRate, filter, options);
   }
 
   completeFeeChangeToOutput(
@@ -1953,6 +2124,11 @@ export class Transaction extends mol.Entity.Base<
     index: NumLike,
     feeRate?: NumLike,
     filter?: ClientCollectableSearchKeyFilterLike,
+    options?: {
+      feeRateBlockRange?: NumLike;
+      maxFeeRate?: NumLike;
+      shouldAddInputs?: boolean;
+    },
   ): Promise<[number, boolean]> {
     const change = Number(numFrom(index));
     if (!this.outputs[change]) {
@@ -1966,6 +2142,7 @@ export class Transaction extends mol.Entity.Base<
       },
       feeRate,
       filter,
+      options,
     );
   }
 }

package/src/ckb/transactionErrors.ts

@@ -0,0 +1,36 @@
+import { fixedPointToString } from "../fixedPoint/index.js";
+import { Num, numFrom, NumLike } from "../num/index.js";
+import { Script, ScriptLike } from "./script.js";
+
+export class ErrorTransactionInsufficientCapacity extends Error {
+  public readonly amount: Num;
+  public readonly isForChange: boolean;
+
+  constructor(
+    amountLike: NumLike,
+    reason?: {
+      isForChange?: boolean;
+    },
+  ) {
+    const amount = numFrom(amountLike);
+    const isForChange = reason?.isForChange ?? false;
+    super(
+      `Insufficient CKB, need ${fixedPointToString(amount)} extra CKB${isForChange ? " for the change cell" : ""}`,
+    );
+    this.amount = amount;
+    this.isForChange = isForChange;
+  }
+}
+
+export class ErrorTransactionInsufficientCoin extends Error {
+  public readonly amount: Num;
+  public readonly type: Script;
+
+  constructor(amountLike: NumLike, typeLike: ScriptLike) {
+    const amount = numFrom(amountLike);
+    const type = Script.from(typeLike);
+    super(`Insufficient coin, need ${amount} extra coin`);
+    this.amount = amount;
+    this.type = type;
+  }
+}

package/src/client/cache/cache.ts

@@ -6,7 +6,7 @@ import {
   TransactionLike,
 } from "../../ckb/index.js";
 import { HexLike } from "../../hex/index.js";
-import { NumLike } from "../../num/index.js";
+import { numFrom, NumLike } from "../../num/index.js";
 import { ClientCollectableSearchKeyLike } from "../clientTypes.advanced.js";
 import {
   ClientBlock,
@@ -16,6 +16,7 @@ import {
   ClientTransactionResponse,
   ClientTransactionResponseLike,
 } from "../clientTypes.js";
+import { DEFAULT_CONFIRMED_BLOCK_TIME } from "./memory.advanced.js";
 
 /**
  * @public
@@ -185,4 +186,16 @@ export abstract class ClientCache {
   async getBlockByNumber(_number: NumLike): Promise<ClientBlock | undefined> {
     return;
   }
+
+  /**
+   * Checks if a block header is considered confirmed.
+   * The default implementation compares the header's timestamp against the current time
+   * and a configured confirmation time. Override this method for custom confirmation logic.
+   * @param header
+   */
+  hasHeaderConfirmed(header: ClientBlockHeader): boolean {
+    return (
+      numFrom(Date.now()) - header.timestamp >= DEFAULT_CONFIRMED_BLOCK_TIME
+    );
+  }
 }

package/src/client/cache/memory.advanced.ts

@@ -8,6 +8,8 @@ import {
 } from "../clientTypes.advanced.js";
 import { ClientIndexerSearchKey } from "../clientTypes.js";
 
+export const DEFAULT_CONFIRMED_BLOCK_TIME = numFrom(1000 * 10 * 50); // 50 blocks * 10s
+
 // [isLive, Cell | OutPoint]
 export type CellRecord =
   | [
@@ -142,49 +144,74 @@ export function filterCell(
   return true;
 }
 
+/**
+ * A Least Recently Used (LRU) cache implemented using a Map.
+ *
+ * This class extends the built-in Map to provide an LRU cache with a fixed capacity.
+ * When the cache is full, the least recently used entry is automatically evicted.
+ *
+ * @template K The type of the keys in the cache.
+ * @template V The type of the values in the cache.
+ */
 export class MapLru<K, V> extends Map<K, V> {
-  private readonly lru: K[] = [];
-
+  /**
+   * Constructs a new MapLru instance.
+   *
+   * @param capacity The maximum number of entries the cache can hold. Must be a positive integer.
+   * @throws {Error} If the capacity is not a positive integer.
+   */
   constructor(private readonly capacity: number) {
     super();
-  }
-
-  get(key: K) {
-    const val = super.get(key);
-    if (val === undefined) {
-      return;
+    if (!Number.isInteger(capacity) || capacity < 1) {
+      throw new Error("Capacity must be a positive integer");
     }
+  }
 
-    const index = this.lru.indexOf(key);
-    if (index !== -1) {
-      this.lru.splice(index, 1);
-    }
-    this.lru.push(key);
-    if (this.lru.length > this.capacity) {
-      this.delete(this.lru[0]);
-      this.lru.shift();
+  /**
+   * Retrieves a value from the cache.
+   *
+   * If the key is present in the cache, the value is moved to the most-recently-used position.
+   *
+   * @param key The key of the value to retrieve.
+   * @returns The value associated with the key, or undefined if the key is not present.
+   */
+  override get(key: K): V | undefined {
+    // Check if the key exists. If not, return undefined.
+    if (!super.has(key)) {
+      return undefined;
     }
 
-    return val;
-  }
-
-  set(key: K, value: V) {
-    this.get(key);
+    const value = super.get(key) as V;
 
+    // Move to most-recently-used position
+    super.delete(key);
     super.set(key, value);
-    return this;
+
+    return value;
   }
 
-  delete(key: K): boolean {
-    if (!super.delete(key)) {
-      return false;
-    }
+  /**
+   * Inserts a new value into the cache, or updates an existing value.
+   *
+   * If the key is already present in the cache, it is first deleted so that the re-insertion
+   * moves it to the most-recently-used position.
+   * If the cache is over capacity after the insertion, the least recently used entry is evicted.
+   *
+   * @param key The key of the value to insert or update.
+   * @param value The value to associate with the key.
+   * @returns This MapLru instance.
+   */
+  override set(key: K, value: V): this {
+    // Delete and re-insert to move key to the end (most-recently-used)
+    super.delete(key);
+    super.set(key, value);
 
-    const index = this.lru.indexOf(key);
-    if (index !== -1) {
-      this.lru.splice(index, 1);
+    // Evict oldest if over capacity
+    if (super.size > this.capacity) {
+      const oldestKey = super.keys().next().value!;
+      super.delete(oldestKey);
     }
 
-    return true;
+    return this;
   }
 }

package/src/client/cache/memory.ts

@@ -11,7 +11,12 @@ import {
   ClientTransactionResponseLike,
 } from "../clientTypes.js";
 import { ClientCache } from "./cache.js";
-import { CellRecord, filterCell, MapLru } from "./memory.advanced.js";
+import {
+  CellRecord,
+  DEFAULT_CONFIRMED_BLOCK_TIME,
+  filterCell,
+  MapLru,
+} from "./memory.advanced.js";
 
 export class ClientCacheMemory extends ClientCache {
   /**
@@ -37,10 +42,18 @@ export class ClientCacheMemory extends ClientCache {
     Pick<ClientBlock, "header"> | ClientBlock
   >;
 
+  /**
+   * @param maxCells - Maximum number of cells to store in the cache. Defaults to 512.
+   * @param maxTxs - Maximum number of transactions to store in the cache. Defaults to 256.
+   * @param maxBlocks - Maximum number of blocks to store in the cache. Defaults to 128.
+   * @param confirmedBlockTime - Time in milliseconds after which a block is considered confirmed.
+   *                              Defaults to DEFAULT_CONFIRMED_BLOCK_TIME (50 blocks * 10s).
+   */
   constructor(
     private readonly maxCells = 512,
     private readonly maxTxs = 256,
     private readonly maxBlocks = 128,
+    private readonly confirmedBlockTime = DEFAULT_CONFIRMED_BLOCK_TIME,
   ) {
     super();
 
@@ -216,4 +229,8 @@ export class ClientCacheMemory extends ClientCache {
     }
     return this.getBlockByHash(hash);
   }
+
+  hasHeaderConfirmed(header: ClientBlockHeader): boolean {
+    return numFrom(Date.now()) - header.timestamp >= this.confirmedBlockTime;
+  }
 }

package/src/client/client.ts

@@ -14,7 +14,6 @@ import { reduceAsync, sleep } from "../utils/index.js";
 import { ClientCache } from "./cache/index.js";
 import { ClientCacheMemory } from "./cache/memory.js";
 import {
-  CONFIRMED_BLOCK_TIME,
   ClientCollectableSearchKeyLike,
   DEFAULT_MAX_FEE_RATE,
   DEFAULT_MIN_FEE_RATE,
@@ -38,10 +37,6 @@ import {
 } from "./clientTypes.js";
 import { KnownScript } from "./knownScript.js";
 
-function hasHeaderConfirmed(header: ClientBlockHeader): boolean {
-  return numFrom(Date.now()) - header.timestamp >= CONFIRMED_BLOCK_TIME;
-}
-
 /**
  * @public
  */
@@ -112,7 +107,7 @@ export abstract class Client {
       verbosity,
       withCycles,
     );
-    if (res && hasHeaderConfirmed(res.header)) {
+    if (res && this.cache.hasHeaderConfirmed(res.header)) {
       await this.cache.recordBlocks(res);
     }
     return res;
@@ -132,7 +127,7 @@ export abstract class Client {
       verbosity,
       withCycles,
     );
-    if (res && hasHeaderConfirmed(res.header)) {
+    if (res && this.cache.hasHeaderConfirmed(res.header)) {
       await this.cache.recordBlocks(res);
     }
     return res;
@@ -147,7 +142,7 @@ export abstract class Client {
     }
 
     const res = await this.getHeaderByNumberNoCache(blockNumber, verbosity);
-    if (res && hasHeaderConfirmed(res)) {
+    if (res && this.cache.hasHeaderConfirmed(res)) {
       await this.cache.recordHeaders(res);
     }
     return res;
@@ -162,7 +157,7 @@ export abstract class Client {
     }
 
     const res = await this.getHeaderByHashNoCache(blockHash, verbosity);
-    if (res && hasHeaderConfirmed(res)) {
+    if (res && this.cache.hasHeaderConfirmed(res)) {
       await this.cache.recordHeaders(res);
     }
     return res;
@@ -636,7 +631,7 @@ export abstract class Client {
     const tx = await this.cache.getTransactionResponse(txHash);
     if (tx?.blockHash) {
       const header = await this.getHeaderByHash(tx.blockHash);
-      if (header && hasHeaderConfirmed(header)) {
+      if (header && this.cache.hasHeaderConfirmed(header)) {
         return {
           transaction: tx,
           header,