@ckb-ccc/core 1.9.1 → 1.11.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;
+  }
 }
 
 /**
@@ -205,29 +235,72 @@ export class CellOutput extends mol.Entity.Base<CellOutputLike, CellOutput>() {
 
   /**
    * Creates a CellOutput instance from a CellOutputLike object.
+   * This method supports automatic capacity calculation when capacity is 0 or omitted.
    *
    * @param cellOutput - A CellOutputLike object or an instance of CellOutput.
+   *                     Can also be an object without capacity when outputData is provided.
+   * @param outputData - Optional output data used for automatic capacity calculation.
+   *                     When provided and capacity is 0, the capacity will be calculated
+   *                     as occupiedSize + outputData.length.
    * @returns A CellOutput instance.
    *
    * @example
    * ```typescript
-   * const cellOutput = CellOutput.from({
+   * // Basic usage with explicit capacity
+   * const cellOutput1 = CellOutput.from({
    *   capacity: 1000n,
    *   lock: { codeHash: "0x...", hashType: "type", args: "0x..." },
    *   type: { codeHash: "0x...", hashType: "type", args: "0x..." }
    * });
+   *
+   * // Automatic capacity calculation
+   * const cellOutput2 = CellOutput.from({
+   *   lock: { codeHash: "0x...", hashType: "type", args: "0x..." }
+   * }, "0x1234"); // Capacity will be calculated automatically
    * ```
    */
-  static from(cellOutput: CellOutputLike): CellOutput {
+  static from(cellOutput: CellOutputLike, outputData?: HexLike): CellOutput;
+  static from(
+    cellOutput: Omit<CellOutputLike, "capacity"> &
+      Partial<Pick<CellOutputLike, "capacity">>,
+    outputData: HexLike,
+  ): CellOutput;
+  static from(
+    cellOutput: Omit<CellOutputLike, "capacity"> &
+      Partial<Pick<CellOutputLike, "capacity">>,
+    outputData?: HexLike,
+  ): CellOutput {
     if (cellOutput instanceof CellOutput) {
       return cellOutput;
     }
 
-    return new CellOutput(
-      numFrom(cellOutput.capacity),
+    const output = new CellOutput(
+      numFrom(cellOutput.capacity ?? 0),
       Script.from(cellOutput.lock),
       apply(Script.from, cellOutput.type),
     );
+
+    if (output.capacity === Zero) {
+      output.capacity = fixedPointFrom(
+        output.occupiedSize + bytesFrom(outputData ?? "0x").length,
+      );
+    }
+
+    return output;
+  }
+
+  /**
+   * 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);
@@ -264,9 +337,37 @@ export class Cell {
 
   /**
    * Creates a Cell instance from a CellLike object.
+   * This method accepts either `outPoint` or `previousOutput` to specify the cell's location,
+   * and supports automatic capacity calculation for the cell output.
    *
-   * @param cell - A CellLike object or an instance of Cell.
+   * @param cell - A CellLike object or an instance of Cell. The object can use either:
+   *               - `outPoint`: For referencing a cell output
+   *               - `previousOutput`: For referencing a cell input (alternative name for outPoint)
+   *               The cellOutput can omit capacity for automatic calculation.
    * @returns A Cell instance.
+   *
+   * @example
+   * ```typescript
+   * // Using outPoint with explicit capacity
+   * const cell1 = Cell.from({
+   *   outPoint: { txHash: "0x...", index: 0 },
+   *   cellOutput: {
+   *     capacity: 1000n,
+   *     lock: { codeHash: "0x...", hashType: "type", args: "0x..." }
+   *   },
+   *   outputData: "0x"
+   * });
+   *
+   * // Using previousOutput with automatic capacity calculation
+   * const cell2 = Cell.from({
+   *   previousOutput: { txHash: "0x...", index: 0 },
+   *   cellOutput: {
+   *     lock: { codeHash: "0x...", hashType: "type", args: "0x..." }
+   *     // capacity will be calculated automatically
+   *   },
+   *   outputData: "0x1234"
+   * });
+   * ```
    */
 
   static from(cell: CellLike): Cell {
@@ -276,7 +377,7 @@ export class Cell {
 
     return new Cell(
       OutPoint.from("outPoint" in cell ? cell.outPoint : cell.previousOutput),
-      CellOutput.from(cell.cellOutput),
+      CellOutput.from(cell.cellOutput, cell.outputData),
       hexFrom(cell.outputData),
     );
   }
@@ -700,12 +801,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 +853,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 +878,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);
 
@@ -947,6 +1058,9 @@ export class Transaction extends mol.Entity.Base<
 
   /**
    * Copy every properties from another transaction.
+   * This method replaces all properties of the current transaction with those from the provided transaction.
+   *
+   * @param txLike - The transaction-like object to copy properties from.
    *
    * @example
    * ```typescript
@@ -964,6 +1078,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.
    *
@@ -989,19 +1152,9 @@ export class Transaction extends mol.Entity.Base<
       return tx;
     }
     const outputs =
-      tx.outputs?.map((output, i) => {
-        const o = CellOutput.from({
-          ...output,
-          capacity: output.capacity ?? 0,
-        });
-        if (o.capacity === Zero) {
-          o.capacity = fixedPointFrom(
-            o.occupiedSize +
-              (apply(bytesFrom, tx.outputsData?.[i])?.length ?? 0),
-          );
-        }
-        return o;
-      }) ?? [];
+      tx.outputs?.map((output, i) =>
+        CellOutput.from(output, tx.outputsData?.[i] ?? []),
+      ) ?? [];
     const outputsData = outputs.map((_, i) =>
       hexFrom(tx.outputsData?.[i] ?? "0x"),
     );
@@ -1229,7 +1382,7 @@ export class Transaction extends mol.Entity.Base<
    *
    * @param scriptLike - The script associated with the transaction, represented as a ScriptLike object.
    * @param client - The client for complete extra infos in the transaction.
-   * @returns A promise that resolves to the prepared transaction
+   * @returns A promise that resolves to the found index, or undefined if no matching input is found.
    *
    * @example
    * ```typescript
@@ -1256,7 +1409,7 @@ export class Transaction extends mol.Entity.Base<
    *
    * @param scriptLike - The script associated with the transaction, represented as a ScriptLike object.
    * @param client - The client for complete extra infos in the transaction.
-   * @returns A promise that resolves to the prepared transaction
+   * @returns A promise that resolves to the found index, or undefined if no matching input is found.
    *
    * @example
    * ```typescript
@@ -1369,14 +1522,14 @@ export class Transaction extends mol.Entity.Base<
    * Set output data at index.
    *
    * @param index - The index of the output data.
-   * @param witness - The data to set.
+   * @param data - The data to set.
    *
    * @example
    * ```typescript
-   * await tx.setOutputDataAt(0, "0x00");
+   * tx.setOutputDataAt(0, "0x00");
    * ```
    */
-  setOutputDataAt(index: number, witness: HexLike): void {
+  setOutputDataAt(index: number, data: HexLike): void {
     if (this.outputsData.length < index) {
       this.outputsData.push(
         ...Array.from(
@@ -1386,7 +1539,7 @@ export class Transaction extends mol.Entity.Base<
       );
     }
 
-    this.outputsData[index] = hexFrom(witness);
+    this.outputsData[index] = hexFrom(data);
   }
 
   /**
@@ -1461,16 +1614,7 @@ export class Transaction extends mol.Entity.Base<
       Partial<Pick<CellOutputLike, "capacity">>,
     outputData: HexLike = "0x",
   ): number {
-    const output = CellOutput.from({
-      ...outputLike,
-      capacity: outputLike.capacity ?? 0,
-    });
-    if (output.capacity === Zero) {
-      output.capacity = fixedPointFrom(
-        output.occupiedSize + bytesFrom(outputData).length,
-      );
-    }
-    const len = this.outputs.push(output);
+    const len = this.outputs.push(CellOutput.from(outputLike, outputData));
     this.setOutputDataAt(len - 1, outputData);
 
     return len;
@@ -1697,8 +1841,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 +1926,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 +1981,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 ??
@@ -1852,40 +2039,67 @@ export class Transaction extends mol.Entity.Base<
 
     let leastFee = Zero;
     let leastExtraCapacity = Zero;
-
+    let collected = 0;
+
+    // ===
+    // Usually, for the worst situation, three iterations are needed
+    // 1. First attempt to complete the transaction.
+    // 2. Not enough capacity for the change cell.
+    // 3. Fee increased by the change cell.
+    // ===
     while (true) {
-      const tx = this.clone();
-      const collected = await (async () => {
+      collected += await (async () => {
+        if (!(options?.shouldAddInputs ?? true)) {
+          return 0;
+        }
+
         try {
-          return await tx.completeInputsByCapacity(
+          return await this.completeInputsByCapacity(
             from,
             leastFee + leastExtraCapacity,
             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;
         }
       })();
 
-      await from.prepareTransaction(tx);
+      const fee = await this.getFee(from.client);
+      if (fee < leastFee + leastExtraCapacity) {
+        // Not enough capacity are collected, it should only happens when shouldAddInputs is false
+        throw new ErrorTransactionInsufficientCapacity(
+          leastFee + leastExtraCapacity - fee,
+          { isForChange: leastExtraCapacity !== Zero },
+        );
+      }
+
+      await from.prepareTransaction(this);
       if (leastFee === Zero) {
         // The initial fee is calculated based on prepared transaction
-        leastFee = tx.estimateFee(feeRate);
+        // This should only happens during the first iteration
+        leastFee = this.estimateFee(feeRate);
       }
-      const fee = await tx.getFee(from.client);
       // The extra capacity paid the fee without a change
+      // leastExtraCapacity should be 0 here, otherwise we should failed in the previous check
+      // So this only happens in the first iteration
       if (fee === leastFee) {
-        this.copy(tx);
         return [collected, false];
       }
 
+      // Invoke the change function on a transaction multiple times may cause problems, so we clone it
+      const tx = this.clone();
       const needed = numFrom(await Promise.resolve(change(tx, fee - leastFee)));
-      // No enough extra capacity to create new cells for change
       if (needed > Zero) {
+        // No enough extra capacity to create new cells for change, collect inputs again
         leastExtraCapacity = needed;
         continue;
       }
@@ -1913,11 +2127,48 @@ export class Transaction extends mol.Entity.Base<
     }
   }
 
+  /**
+   * Completes the transaction fee by adding inputs and creating a change output with the specified lock script.
+   * This is a convenience method that automatically creates a change cell with the provided lock script
+   * when there's excess capacity after paying the transaction fee.
+   *
+   * @param from - The signer to complete inputs from and prepare the transaction.
+   * @param change - The lock script for the change output cell.
+   * @param feeRate - Optional 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 feeRate 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)
+   *
+   * @example
+   * ```typescript
+   * const changeScript = Script.from({
+   *   codeHash: "0x...",
+   *   hashType: "type",
+   *   args: "0x..."
+   * });
+   *
+   * const [addedInputs, hasChange] = await tx.completeFeeChangeToLock(
+   *   signer,
+   *   changeScript,
+   *   1000n // 1000 shannons per 1000 bytes
+   * );
+   * ```
+   */
   completeFeeChangeToLock(
     from: Signer,
     change: ScriptLike,
     feeRate?: NumLike,
     filter?: ClientCollectableSearchKeyFilterLike,
+    options?: {
+      feeRateBlockRange?: NumLike;
+      maxFeeRate?: NumLike;
+      shouldAddInputs?: boolean;
+    },
   ): Promise<[number, boolean]> {
     const script = Script.from(change);
 
@@ -1935,24 +2186,91 @@ export class Transaction extends mol.Entity.Base<
       },
       feeRate,
       filter,
+      options,
     );
   }
 
+  /**
+   * Completes the transaction fee using the signer's recommended address for change.
+   * This is a convenience method that automatically uses the signer's recommended
+   * address as the change destination, making it easier to complete transactions
+   * without manually specifying a change address.
+   *
+   * @param from - The signer to complete inputs from and prepare the transaction.
+   * @param feeRate - Optional 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 feeRate 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)
+   *
+   * @example
+   * ```typescript
+   * const [addedInputs, hasChange] = await tx.completeFeeBy(
+   *   signer,
+   *   1000n // 1000 shannons per 1000 bytes
+   * );
+   *
+   * // Change will automatically go to signer's recommended address
+   * ```
+   */
   async completeFeeBy(
     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);
   }
 
+  /**
+   * Completes the transaction fee by adding excess capacity to an existing output.
+   * Instead of creating a new change output, this method adds any excess capacity
+   * to the specified existing output in the transaction.
+   *
+   * @param from - The signer to complete inputs from and prepare the transaction.
+   * @param index - The index of the existing output to add excess capacity to.
+   * @param feeRate - Optional 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 feeRate 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 was applied (true) or fee was paid without change (false)
+   *
+   * @throws {Error} When the specified output index doesn't exist.
+   *
+   * @example
+   * ```typescript
+   * // Add excess capacity to the first output (index 0)
+   * const [addedInputs, hasChange] = await tx.completeFeeChangeToOutput(
+   *   signer,
+   *   0, // Output index
+   *   1000n // 1000 shannons per 1000 bytes
+   * );
+   * ```
+   */
   completeFeeChangeToOutput(
     from: Signer,
     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,12 +2284,32 @@ export class Transaction extends mol.Entity.Base<
       },
       feeRate,
       filter,
+      options,
     );
   }
 }
 
 /**
- * Calculate Nervos DAO profit between two blocks
+ * Calculate Nervos DAO profit between two blocks.
+ * This function computes the profit earned from a Nervos DAO deposit
+ * based on the capacity and the time period between deposit and withdrawal.
+ *
+ * @param profitableCapacity - The capacity that earns profit (total capacity minus occupied capacity).
+ * @param depositHeaderLike - The block header when the DAO deposit was made.
+ * @param withdrawHeaderLike - The block header when the DAO withdrawal is made.
+ * @returns The profit amount in CKB (capacity units).
+ *
+ * @example
+ * ```typescript
+ * const profit = calcDaoProfit(
+ *   ccc.fixedPointFrom(100), // 100 CKB profitable capacity
+ *   depositHeader,
+ *   withdrawHeader
+ * );
+ * console.log(`Profit: ${profit} shannons`);
+ * ```
+ *
+ * @see {@link https://github.com/nervosnetwork/rfcs/blob/master/rfcs/0023-dao-deposit-withdraw/0023-dao-deposit-withdraw.md | Nervos DAO RFC}
  */
 export function calcDaoProfit(
   profitableCapacity: NumLike,
@@ -1990,8 +2328,26 @@ export function calcDaoProfit(
 }
 
 /**
- * Calculate claimable epoch for Nervos DAO withdrawal
- * See https://github.com/nervosnetwork/rfcs/blob/master/rfcs/0023-dao-deposit-withdraw/0023-dao-deposit-withdraw.md
+ * Calculate claimable epoch for Nervos DAO withdrawal.
+ * This function determines the earliest epoch when a Nervos DAO withdrawal
+ * can be claimed based on the deposit and withdrawal epochs.
+ *
+ * @param depositHeader - The block header when the DAO deposit was made.
+ * @param withdrawHeader - The block header when the DAO withdrawal was initiated.
+ * @returns The epoch when the withdrawal can be claimed, represented as [number, index, length].
+ *
+ * @example
+ * ```typescript
+ * const claimEpoch = calcDaoClaimEpoch(depositHeader, withdrawHeader);
+ * console.log(`Can claim at epoch: ${claimEpoch[0]}, index: ${claimEpoch[1]}, length: ${claimEpoch[2]}`);
+ * ```
+ *
+ * @remarks
+ * The Nervos DAO has a minimum lock period of 180 epochs (~30 days).
+ * This function calculates the exact epoch when the withdrawal becomes claimable
+ * based on the deposit epoch and withdrawal epoch timing.
+ *
+ * @see {@link https://github.com/nervosnetwork/rfcs/blob/master/rfcs/0023-dao-deposit-withdraw/0023-dao-deposit-withdraw.md | Nervos DAO RFC}
  */
 export function calcDaoClaimEpoch(
   depositHeader: ClientBlockHeaderLike,