@ckb-ccc/core 1.9.1 → 1.11.0

package/dist/ckb/transaction.js

@@ -8,7 +8,7 @@ var OutPoint_1, CellOutput_1, Since_1, CellInput_1, CellDep_1, WitnessArgs_1, Tr
 import { bytesFrom } from "../bytes/index.js";
 import { ClientBlockHeader, } 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 { HasherCkb, hashCkb } from "../hasher/index.js";
 import { hexFrom } from "../hex/index.js";
 import { mol } from "../molecule/index.js";
@@ -16,6 +16,7 @@ import { numFrom, numFromBytes, numToBytes, numToHex, } from "../num/index.js";
 import { apply, reduceAsync } from "../utils/index.js";
 import { Script, ScriptOpt } from "./script.js";
 import { DEP_TYPE_TO_NUM, NUM_TO_DEP_TYPE } from "./transaction.advanced.js";
+import { ErrorTransactionInsufficientCapacity, ErrorTransactionInsufficientCoin, } from "./transactionErrors.js";
 export const DepTypeCodec = mol.Codec.from({
     byteLength: 1,
     encode: depTypeToBytes,
@@ -115,6 +116,34 @@ let OutPoint = OutPoint_1 = class OutPoint extends mol.Entity.Base() {
         }
         return new OutPoint_1(hexFrom(outPoint.txHash), numFrom(outPoint.index));
     }
+    /**
+     * Clone a OutPoint.
+     *
+     * @returns A cloned OutPoint instance.
+     *
+     * @example
+     * ```typescript
+     * const outPoint1 = outPoint0.clone();
+     * ```
+     */
+    clone() {
+        return new OutPoint_1(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) {
+        other = OutPoint_1.from(other);
+        return this.txHash === other.txHash && this.index === other.index;
+    }
 };
 OutPoint = OutPoint_1 = __decorate([
     mol.codec(mol.struct({
@@ -143,26 +172,28 @@ let CellOutput = CellOutput_1 = class CellOutput extends mol.Entity.Base() {
     get occupiedSize() {
         return 8 + this.lock.occupiedSize + (this.type?.occupiedSize ?? 0);
     }
+    static from(cellOutput, outputData) {
+        if (cellOutput instanceof CellOutput_1) {
+            return cellOutput;
+        }
+        const output = new CellOutput_1(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;
+    }
     /**
-     * Creates a CellOutput instance from a CellOutputLike object.
+     * Clone a CellOutput.
      *
-     * @param cellOutput - A CellOutputLike object or an instance of CellOutput.
-     * @returns A CellOutput instance.
+     * @returns A cloned CellOutput instance.
      *
      * @example
      * ```typescript
-     * const cellOutput = CellOutput.from({
-     *   capacity: 1000n,
-     *   lock: { codeHash: "0x...", hashType: "type", args: "0x..." },
-     *   type: { codeHash: "0x...", hashType: "type", args: "0x..." }
-     * });
+     * const cellOutput1 = cellOutput0.clone();
      * ```
      */
-    static from(cellOutput) {
-        if (cellOutput instanceof CellOutput_1) {
-            return cellOutput;
-        }
-        return new CellOutput_1(numFrom(cellOutput.capacity), Script.from(cellOutput.lock), apply(Script.from, cellOutput.type));
+    clone() {
+        return new CellOutput_1(this.capacity, this.lock.clone(), this.type?.clone());
     }
 };
 CellOutput = CellOutput_1 = __decorate([
@@ -192,15 +223,43 @@ 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) {
         if (cell instanceof Cell) {
             return cell;
         }
-        return new Cell(OutPoint.from("outPoint" in cell ? cell.outPoint : cell.previousOutput), CellOutput.from(cell.cellOutput), hexFrom(cell.outputData));
+        return new Cell(OutPoint.from("outPoint" in cell ? cell.outPoint : cell.previousOutput), CellOutput.from(cell.cellOutput, cell.outputData), hexFrom(cell.outputData));
     }
     get capacityFree() {
         const occupiedSize = fixedPointFrom(this.cellOutput.occupiedSize + bytesFrom(this.outputData).length);
@@ -493,11 +552,18 @@ let CellInput = CellInput_1 = class CellInput extends mol.Entity.Base() {
     async getExtraCapacity(client) {
         return (await this.getCell(client)).getDaoProfit(client);
     }
+    /**
+     * Clone a CellInput.
+     *
+     * @returns A cloned CellInput instance.
+     *
+     * @example
+     * ```typescript
+     * const cellInput1 = cellInput0.clone();
+     * ```
+     */
     clone() {
-        const cloned = super.clone();
-        cloned.cellOutput = this.cellOutput;
-        cloned.outputData = this.outputData;
-        return cloned;
+        return new CellInput_1(this.previousOutput.clone(), this.since, this.cellOutput?.clone(), this.outputData);
     }
 };
 CellInput = CellInput_1 = __decorate([
@@ -525,19 +591,6 @@ let CellDep = CellDep_1 = class CellDep extends mol.Entity.Base() {
         this.outPoint = outPoint;
         this.depType = depType;
     }
-    /**
-     * Clone a CellDep.
-     *
-     * @returns A cloned CellDep instance.
-     *
-     * @example
-     * ```typescript
-     * const cellDep1 = cellDep0.clone();
-     * ```
-     */
-    clone() {
-        return new CellDep_1(this.outPoint.clone(), this.depType);
-    }
     /**
      * Creates a CellDep instance from a CellDepLike object.
      *
@@ -558,6 +611,19 @@ let CellDep = CellDep_1 = class CellDep extends mol.Entity.Base() {
         }
         return new CellDep_1(OutPoint.from(cellDep.outPoint), depTypeFrom(cellDep.depType));
     }
+    /**
+     * Clone a CellDep.
+     *
+     * @returns A cloned CellDep instance.
+     *
+     * @example
+     * ```typescript
+     * const cellDep1 = cellDep0.clone();
+     * ```
+     */
+    clone() {
+        return new CellDep_1(this.outPoint.clone(), this.depType);
+    }
 };
 CellDep = CellDep_1 = __decorate([
     mol.codec(mol.struct({
@@ -671,6 +737,9 @@ let Transaction = Transaction_1 = 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
@@ -687,6 +756,46 @@ let Transaction = Transaction_1 = class Transaction extends mol.Entity.Base() {
         this.outputsData = tx.outputsData;
         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() {
+        return new Transaction_1(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.
      *
@@ -710,17 +819,7 @@ let Transaction = Transaction_1 = class Transaction extends mol.Entity.Base() {
         if (tx instanceof Transaction_1) {
             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;
-        }) ?? [];
+        const outputs = tx.outputs?.map((output, i) => CellOutput.from(output, tx.outputsData?.[i] ?? [])) ?? [];
         const outputsData = outputs.map((_, i) => hexFrom(tx.outputsData?.[i] ?? "0x"));
         if (tx.outputsData != null && outputsData.length < tx.outputsData.length) {
             outputsData.push(...tx.outputsData.slice(outputsData.length).map((d) => hexFrom(d)));
@@ -903,7 +1002,7 @@ let Transaction = Transaction_1 = 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
@@ -924,7 +1023,7 @@ let Transaction = Transaction_1 = 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
@@ -1012,18 +1111,18 @@ let Transaction = Transaction_1 = 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, witness) {
+    setOutputDataAt(index, data) {
         if (this.outputsData.length < index) {
             this.outputsData.push(...Array.from(new Array(index - this.outputsData.length), () => "0x"));
         }
-        this.outputsData[index] = hexFrom(witness);
+        this.outputsData[index] = hexFrom(data);
     }
     /**
      * get input
@@ -1086,14 +1185,7 @@ let Transaction = Transaction_1 = class Transaction extends mol.Entity.Base() {
      * ```
      */
     addOutput(outputLike, outputData = "0x") {
-        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;
     }
@@ -1240,7 +1332,7 @@ let Transaction = Transaction_1 = class Transaction extends mol.Entity.Base() {
         if (accumulated === undefined) {
             return addedCount;
         }
-        throw new Error(`Insufficient CKB, need ${fixedPointToString(expectedCapacity - accumulated)} extra CKB`);
+        throw new ErrorTransactionInsufficientCapacity(expectedCapacity - accumulated);
     }
     async completeInputsAll(from, filter) {
         const { addedCount } = await this.completeInputs(from, filter ?? {
@@ -1290,7 +1382,7 @@ let Transaction = Transaction_1 = class Transaction extends mol.Entity.Base() {
         if (accumulated === undefined || accumulated >= expectedBalance) {
             return addedCount;
         }
-        throw new Error(`Insufficient coin, need ${expectedBalance - accumulated} extra coin`);
+        throw new ErrorTransactionInsufficientCoin(expectedBalance - accumulated, type);
     }
     async completeInputsAddOne(from, filter) {
         const { addedCount, accumulated } = await this.completeInputs(from, filter ?? {
@@ -1320,6 +1412,44 @@ let Transaction = Transaction_1 = class Transaction extends mol.Entity.Base() {
         // + 999 then / 1000 to ceil the calculated fee
         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, change, expectedFeeRate, filter, options) {
         const feeRate = expectedFeeRate ??
             (await from.client.getFeeRate(options?.feeRateBlockRange, options));
@@ -1327,33 +1457,53 @@ let Transaction = Transaction_1 = class Transaction extends mol.Entity.Base() {
         await this.getInputsCapacity(from.client);
         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(from, leastFee + leastExtraCapacity, filter);
+                    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;
             }
@@ -1375,7 +1525,39 @@ let Transaction = Transaction_1 = class Transaction extends mol.Entity.Base() {
             leastFee = changedFee;
         }
     }
-    completeFeeChangeToLock(from, change, feeRate, filter) {
+    /**
+     * 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, change, feeRate, filter, options) {
         const script = Script.from(change);
         return this.completeFee(from, (tx, capacity) => {
             const changeCell = CellOutput.from({ capacity: 0, lock: script });
@@ -1386,13 +1568,69 @@ let Transaction = Transaction_1 = class Transaction extends mol.Entity.Base() {
             changeCell.capacity = capacity;
             tx.addOutput(changeCell);
             return 0;
-        }, feeRate, filter);
+        }, feeRate, filter, options);
     }
-    async completeFeeBy(from, feeRate, filter) {
+    /**
+     * 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, feeRate, filter, options) {
         const { script } = await from.getRecommendedAddressObj();
-        return this.completeFeeChangeToLock(from, script, feeRate, filter);
+        return this.completeFeeChangeToLock(from, script, feeRate, filter, options);
     }
-    completeFeeChangeToOutput(from, index, feeRate, filter) {
+    /**
+     * 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, index, feeRate, filter, options) {
         const change = Number(numFrom(index));
         if (!this.outputs[change]) {
             throw new Error("Non-existed output to change");
@@ -1400,7 +1638,7 @@ let Transaction = Transaction_1 = class Transaction extends mol.Entity.Base() {
         return this.completeFee(from, (tx, capacity) => {
             tx.outputs[change].capacity += capacity;
             return 0;
-        }, feeRate, filter);
+        }, feeRate, filter, options);
     }
 };
 Transaction = Transaction_1 = __decorate([
@@ -1420,7 +1658,26 @@ Transaction = Transaction_1 = __decorate([
 ], Transaction);
 export { Transaction };
 /**
- * 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, depositHeaderLike, withdrawHeaderLike) {
     const depositHeader = ClientBlockHeader.from(depositHeaderLike);
@@ -1430,8 +1687,26 @@ export function calcDaoProfit(profitableCapacity, depositHeaderLike, withdrawHea
         profitableSize);
 }
 /**
- * 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, withdrawHeader) {
     const depositEpoch = ClientBlockHeader.from(depositHeader).epoch;

package/dist/ckb/transactionErrors.d.ts

@@ -0,0 +1,15 @@
+import { Num, NumLike } from "../num/index.js";
+import { Script, ScriptLike } from "./script.js";
+export declare class ErrorTransactionInsufficientCapacity extends Error {
+    readonly amount: Num;
+    readonly isForChange: boolean;
+    constructor(amountLike: NumLike, reason?: {
+        isForChange?: boolean;
+    });
+}
+export declare class ErrorTransactionInsufficientCoin extends Error {
+    readonly amount: Num;
+    readonly type: Script;
+    constructor(amountLike: NumLike, typeLike: ScriptLike);
+}
+//# sourceMappingURL=transactionErrors.d.ts.map

package/dist/ckb/transactionErrors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactionErrors.d.ts","sourceRoot":"","sources":["../../src/ckb/transactionErrors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAW,OAAO,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEjD,qBAAa,oCAAqC,SAAQ,KAAK;IAC7D,SAAgB,MAAM,EAAE,GAAG,CAAC;IAC5B,SAAgB,WAAW,EAAE,OAAO,CAAC;gBAGnC,UAAU,EAAE,OAAO,EACnB,MAAM,CAAC,EAAE;QACP,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB;CAUJ;AAED,qBAAa,gCAAiC,SAAQ,KAAK;IACzD,SAAgB,MAAM,EAAE,GAAG,CAAC;IAC5B,SAAgB,IAAI,EAAE,MAAM,CAAC;gBAEjB,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU;CAOtD"}

package/dist/ckb/transactionErrors.js

@@ -0,0 +1,21 @@
+import { fixedPointToString } from "../fixedPoint/index.js";
+import { numFrom } from "../num/index.js";
+import { Script } from "./script.js";
+export class ErrorTransactionInsufficientCapacity extends Error {
+    constructor(amountLike, reason) {
+        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 {
+    constructor(amountLike, typeLike) {
+        const amount = numFrom(amountLike);
+        const type = Script.from(typeLike);
+        super(`Insufficient coin, need ${amount} extra coin`);
+        this.amount = amount;
+        this.type = type;
+    }
+}