@ckb-ccc/core 1.16.1 → 1.18.0

package/src/ckb/transaction.ts

@@ -32,6 +32,30 @@ import {
 } from "./transactionErrors.js";
 import type { LumosTransactionSkeletonType } from "./transactionLumos.js";
 
+const MAX_ARRAY_INDEX = 2n ** 32n - 2n;
+
+function transactionIndexFrom(index: NumLike): number | undefined {
+  try {
+    const value = numFrom(index);
+    if (value < 0n || value > MAX_ARRAY_INDEX) {
+      return;
+    }
+    return Number(value);
+  } catch (_) {
+    return;
+  }
+}
+
+function transactionIndexOrThrow(index: number): number {
+  const value = transactionIndexFrom(index);
+  if (value === undefined) {
+    throw new Error(
+      `Index ${index} must be a valid array index between 0 and ${MAX_ARRAY_INDEX}`,
+    );
+  }
+  return value;
+}
+
 export const DepTypeCodec: Codec<DepTypeLike, DepType> = Codec.from({
   byteLength: 1,
   encode: depTypeToBytes,
@@ -1169,6 +1193,10 @@ export class Transaction extends Entity.Base<TransactionLike, Transaction>() {
    * ```
    */
   copy(txLike: TransactionLike) {
+    if (txLike === this) {
+      return;
+    }
+
     const tx = Transaction.from(txLike);
     this.version = tx.version;
     this.cellDeps = tx.cellDeps;
@@ -1620,41 +1648,75 @@ export class Transaction extends Entity.Base<TransactionLike, Transaction>() {
   }
 
   /**
-   * Set output data at index.
+   * Sets output data at an index.
+   *
+   * @deprecated Use {@link setOutputData} instead.
+   */
+  setOutputDataAt(index: number, data: HexLike): void {
+    this.setOutputData(index, data);
+  }
+
+  /**
+   * Sets output data at an index, filling any skipped positions with empty data.
    *
    * @param index - The index of the output data.
    * @param data - The data to set.
+   * @throws If `index` is invalid or does not identify an existing output.
    *
    * @example
    * ```typescript
-   * tx.setOutputDataAt(0, "0x00");
+   * tx.setOutputData(0, "0x00");
    * ```
    */
-  setOutputDataAt(index: number, data: HexLike): void {
-    if (this.outputsData.length < index) {
+  setOutputData(index: number, data: HexLike): void {
+    const i = transactionIndexOrThrow(index);
+    if (i >= this.outputs.length) {
+      throw new Error(
+        `Index ${index} is out of bounds for outputs of length ${this.outputs.length}`,
+      );
+    }
+
+    if (this.outputsData.length < i) {
       this.outputsData.push(
-        ...Array.from(
-          new Array(index - this.outputsData.length),
-          (): Hex => "0x",
-        ),
+        ...Array.from(new Array(i - this.outputsData.length), (): Hex => "0x"),
       );
     }
 
-    this.outputsData[index] = hexFrom(data);
+    this.outputsData[i] = hexFrom(data);
+  }
+
+  /**
+   * Gets the data associated with an output.
+   *
+   * @param index - The output index.
+   * @returns The output data, or `undefined` if the index is invalid or out of bounds.
+   *
+   * @example
+   * ```typescript
+   * const data = tx.getOutputData(0);
+   * ```
+   */
+  getOutputData(index: NumLike): Hex | undefined {
+    const i = transactionIndexFrom(index);
+    return i !== undefined && i < this.outputs.length
+      ? (this.outputsData[i] ?? "0x")
+      : undefined;
   }
 
   /**
-   * get input
+   * Gets an input.
    *
-   * @param index - The cell input index
+   * @param index - The cell input index.
+   * @returns The input, or `undefined` if the index is invalid or out of bounds.
    *
    * @example
    * ```typescript
-   * await tx.getInput(0);
+   * tx.getInput(0);
    * ```
    */
   getInput(index: NumLike): CellInput | undefined {
-    return this.inputs[Number(numFrom(index))];
+    const i = transactionIndexFrom(index);
+    return i === undefined ? undefined : this.inputs[i];
   }
   /**
    * add input
@@ -1675,18 +1737,19 @@ export class Transaction extends Entity.Base<TransactionLike, Transaction>() {
   }
 
   /**
-   * get output
+   * Gets an output cell together with its data.
    *
-   * @param index - The cell output index
+   * @param index - The cell output index.
+   * @returns The output cell, or `undefined` if the index is invalid or out of bounds.
    *
    * @example
    * ```typescript
-   * await tx.getOutput(0);
+   * tx.getOutput(0);
    * ```
    */
   getOutput(index: NumLike): CellAny | undefined {
-    const i = Number(numFrom(index));
-    if (i >= this.outputs.length) {
+    const i = transactionIndexFrom(index);
+    if (i === undefined || i >= this.outputs.length) {
       return;
     }
     return CellAny.from({
@@ -1769,85 +1832,238 @@ export class Transaction extends Entity.Base<TransactionLike, Transaction>() {
           });
 
     const len = this.outputs.push(cell.cellOutput);
-    this.setOutputDataAt(len - 1, cell.outputData);
+    this.setOutputData(len - 1, cell.outputData);
 
     return len;
   }
 
   /**
-   * Get witness at index as WitnessArgs
+   * Sets or appends an output cell.
+   *
+   * An index equal to the current output count appends the cell. Existing
+   * outputs are replaced together with their corresponding output data.
+   *
+   * @param index - The output index to set, from zero through the current output count.
+   * @param cellLike - A cell-like object containing both the output and its data.
+   * @throws If `index` is not a valid array index or is greater than the output count.
+   *
+   * @example
+   * ```typescript
+   * tx.setOutput(0, {
+   *   cellOutput: { lock: recipientLock },
+   *   outputData: "0x1234",
+   * });
+   * ```
+   */
+  setOutput(index: number, cellLike: CellAnyLike): void;
+
+  /**
+   * Sets or appends an output and its data.
+   *
+   * @param index - The output index to set, from zero through the current output count.
+   * @param outputLike - The cell output to set.
+   * @param outputDataLike - The output data, defaulting to `"0x"`.
+   * @throws If `index` is not a valid array index or is greater than the output count.
+   *
+   * @example
+   * ```typescript
+   * tx.setOutput(0, { lock: recipientLock }, "0x1234");
+   * ```
+   */
+  setOutput(
+    index: number,
+    outputLike: CellOutputLike,
+    outputDataLike?: HexLike | null,
+  ): void;
+  setOutput(
+    index: number,
+    cellOrOutputLike: CellAnyLike | CellOutputLike,
+    outputDataLike?: HexLike | null,
+  ): void {
+    const i = transactionIndexOrThrow(index);
+    if (i > this.outputs.length) {
+      throw new Error(
+        `Index ${index} is out of bounds for outputs of length ${this.outputs.length}`,
+      );
+    }
+
+    const cell =
+      "cellOutput" in cellOrOutputLike
+        ? CellAny.from(cellOrOutputLike)
+        : CellAny.from({
+            cellOutput: cellOrOutputLike,
+            outputData: outputDataLike,
+          });
+
+    if (i === this.outputs.length) {
+      this.addOutput(cell);
+    } else {
+      this.outputs[i] = cell.cellOutput;
+      this.setOutputData(i, cell.outputData);
+    }
+  }
+
+  /**
+   * Sets or appends an input.
+   *
+   * An index equal to the current input count appends the input using
+   * {@link addInput}, preserving witness alignment. An existing index replaces
+   * only that input.
+   *
+   * @param index - The input index to set, from zero through the current input count.
+   * @param inputLike - The cell input to set.
+   * @throws If `index` is not a valid array index or is greater than the input count.
+   *
+   * @example
+   * ```typescript
+   * tx.setInput(0, {
+   *   previousOutput: { txHash: "0x...", index: 0 },
+   * });
+   * ```
+   */
+  setInput(index: number, inputLike: CellInputLike): void {
+    const i = transactionIndexOrThrow(index);
+    if (i > this.inputs.length) {
+      throw new Error(
+        `Index ${index} is out of bounds for inputs of length ${this.inputs.length}`,
+      );
+    }
+
+    if (i === this.inputs.length) {
+      this.addInput(inputLike);
+    } else {
+      this.inputs[i] = CellInput.from(inputLike);
+    }
+  }
+
+  /**
+   * Gets a raw witness.
+   *
+   * @param index - The witness index.
+   * @returns The witness, or `undefined` if the index is invalid or out of bounds.
+   *
+   * @example
+   * ```typescript
+   * const witness = tx.getWitness(0);
+   * ```
+   */
+  getWitness(index: NumLike): Hex | undefined {
+    const i = transactionIndexFrom(index);
+    return i === undefined ? undefined : this.witnesses[i];
+  }
+
+  /**
+   * Gets the witness at an index as `WitnessArgs`.
    *
    * @param index - The index of the witness.
    * @returns The witness parsed as WitnessArgs.
    *
    * @example
    * ```typescript
-   * const witnessArgs = tx.getWitnessArgsAt(0);
+   * const witnessArgs = tx.getWitnessArgs(0);
    * ```
    */
-  getWitnessArgsAt(index: number): WitnessArgs | undefined {
+  getWitnessArgs(index: NumLike): WitnessArgs | undefined {
     try {
-      return this.getWitnessArgsAtUnsafe(index);
+      return this.getWitnessArgsUnsafe(index);
     } catch (_) {
       return undefined;
     }
   }
 
   /**
-   * Get witness at index as WitnessArgs, throw if failed to decode
+   * Gets the witness at an index as `WitnessArgs`, throwing if decoding fails.
    *
    * @param index - The index of the witness.
    * @returns The witness parsed as WitnessArgs.
+   * @throws If the witness cannot be decoded as `WitnessArgs`.
    *
    * @example
    * ```typescript
-   * const witnessArgs = tx.getWitnessArgsAtUnsafe(0);
+   * const witnessArgs = tx.getWitnessArgsUnsafe(0);
    * ```
    */
-  getWitnessArgsAtUnsafe(index: number): WitnessArgs | undefined {
-    const rawWitness = this.witnesses[index];
-    return (rawWitness ?? "0x") !== "0x"
+  getWitnessArgsUnsafe(index: NumLike): WitnessArgs | undefined {
+    const rawWitness = this.getWitness(index);
+    return rawWitness && rawWitness !== "0x"
       ? WitnessArgs.fromBytes(rawWitness)
       : undefined;
   }
 
   /**
-   * Set witness at index by WitnessArgs
+   * Sets a witness at an index from `WitnessArgs`.
    *
    * @param index - The index of the witness.
-   * @param witness - The WitnessArgs to set.
+   * @param witnessLike - The WitnessArgs-like value to set.
+   * @throws If `index` is not a valid array index.
    *
    * @example
    * ```typescript
-   * await tx.setWitnessArgsAt(0, witnessArgs);
+   * tx.setWitnessArgs(0, witnessArgs);
    * ```
    */
-  setWitnessArgsAt(index: number, witness: WitnessArgs): void {
-    this.setWitnessAt(index, witness.toBytes());
+  setWitnessArgs(index: number, witnessLike: WitnessArgsLike): void {
+    this.setWitness(index, WitnessArgs.from(witnessLike).toBytes());
   }
 
   /**
-   * Set witness at index
+   * Sets a witness at an index, filling any skipped positions with empty witnesses.
    *
    * @param index - The index of the witness.
    * @param witness - The witness to set.
+   * @throws If `index` is not a valid array index.
    *
    * @example
    * ```typescript
-   * await tx.setWitnessAt(0, witness);
+   * tx.setWitness(0, witness);
    * ```
    */
-  setWitnessAt(index: number, witness: HexLike): void {
-    if (this.witnesses.length < index) {
+  setWitness(index: number, witness: HexLike): void {
+    const i = transactionIndexOrThrow(index);
+
+    if (this.witnesses.length < i) {
       this.witnesses.push(
-        ...Array.from(
-          new Array(index - this.witnesses.length),
-          (): Hex => "0x",
-        ),
+        ...Array.from(new Array(i - this.witnesses.length), (): Hex => "0x"),
       );
     }
 
-    this.witnesses[index] = hexFrom(witness);
+    this.witnesses[i] = hexFrom(witness);
+  }
+
+  /**
+   * Gets the witness at an index as `WitnessArgs`.
+   *
+   * @deprecated Use {@link getWitnessArgs} instead.
+   */
+  getWitnessArgsAt(index: NumLike): WitnessArgs | undefined {
+    return this.getWitnessArgs(index);
+  }
+
+  /**
+   * Gets the witness at an index as `WitnessArgs`, throwing if decoding fails.
+   *
+   * @deprecated Use {@link getWitnessArgsUnsafe} instead.
+   */
+  getWitnessArgsAtUnsafe(index: NumLike): WitnessArgs | undefined {
+    return this.getWitnessArgsUnsafe(index);
+  }
+
+  /**
+   * Sets a witness at an index from `WitnessArgs`.
+   *
+   * @deprecated Use {@link setWitnessArgs} instead.
+   */
+  setWitnessArgsAt(index: number, witnessLike: WitnessArgsLike): void {
+    this.setWitnessArgs(index, witnessLike);
+  }
+
+  /**
+   * Sets a witness at an index.
+   *
+   * @deprecated Use {@link setWitness} instead.
+   */
+  setWitnessAt(index: number, witness: HexLike): void {
+    this.setWitness(index, witness);
   }
 
   /**
@@ -1873,9 +2089,9 @@ export class Transaction extends Entity.Base<TransactionLike, Transaction>() {
       return;
     }
 
-    const witness = this.getWitnessArgsAt(position) ?? WitnessArgs.from({});
+    const witness = this.getWitnessArgs(position) ?? WitnessArgs.from({});
     witness.lock = hexFrom(Array.from(new Array(lockLen), () => 0));
-    this.setWitnessArgsAt(position, witness);
+    this.setWitnessArgs(position, witness);
   }
 
   async getInputsCapacityExtra(client: Client): Promise<Num> {
@@ -2210,6 +2426,8 @@ export class Transaction extends Entity.Base<TransactionLike, Transaction>() {
     let leastFee = Zero;
     let leastExtraCapacity = Zero;
     let collected = 0;
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    let tx: Transaction = this;
 
     // ===
     // Usually, for the worst situation, three iterations are needed
@@ -2224,7 +2442,7 @@ export class Transaction extends Entity.Base<TransactionLike, Transaction>() {
         }
 
         try {
-          return await this.completeInputsByCapacity(
+          return await tx.completeInputsByCapacity(
             from,
             leastFee + leastExtraCapacity,
             filter,
@@ -2243,7 +2461,8 @@ export class Transaction extends Entity.Base<TransactionLike, Transaction>() {
         }
       })();
 
-      const fee = await this.getFee(from.client);
+      tx = await from.prepareTransaction(tx);
+      const fee = await tx.getFee(from.client);
       if (fee < leastFee + leastExtraCapacity) {
         // Not enough capacity are collected, it should only happens when shouldAddInputs is false
         throw new ErrorTransactionInsufficientCapacity(
@@ -2251,44 +2470,45 @@ export class Transaction extends Entity.Base<TransactionLike, Transaction>() {
           { isForChange: leastExtraCapacity !== Zero },
         );
       }
-
-      await from.prepareTransaction(this);
       if (leastFee === Zero) {
         // The initial fee is calculated based on prepared transaction
         // This should only happens during the first iteration
-        leastFee = this.estimateFee(feeRate);
+        leastFee = tx.estimateFee(feeRate);
       }
       // 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)));
+      let changedTx = tx.clone();
+      const needed = numFrom(
+        await Promise.resolve(change(changedTx, fee - leastFee)),
+      );
       if (needed > Zero) {
         // No enough extra capacity to create new cells for change, collect inputs again
         leastExtraCapacity = needed;
         continue;
       }
 
-      if ((await tx.getFee(from.client)) !== leastFee) {
+      if ((await changedTx.getFee(from.client)) !== leastFee) {
         throw new Error(
           "The change function doesn't use all available capacity",
         );
       }
 
       // New change cells created, update the fee
-      await from.prepareTransaction(tx);
-      const changedFee = tx.estimateFee(feeRate);
+      changedTx = await from.prepareTransaction(changedTx);
+      const changedFee = changedTx.estimateFee(feeRate);
       if (leastFee > changedFee) {
         throw new Error("The change function removed existed transaction data");
       }
       // The fee has been paid
       if (leastFee === changedFee) {
-        this.copy(tx);
+        this.copy(changedTx);
         return [collected, true];
       }
 

package/src/client/jsonRpc/client.ts

@@ -13,6 +13,7 @@ import { Num, NumLike, numFrom, numToHex } from "../../num/index.js";
 import { apply } from "../../utils/index.js";
 import { ClientCache } from "../cache/index.js";
 import { Client } from "../client.js";
+import { DEFAULT_MIN_FEE_RATE } from "../clientTypes.advanced.js";
 import {
   ClientFindCellsResponse,
   ClientIndexerSearchKeyLike,
@@ -131,9 +132,12 @@ export abstract class ClientJsonRpc extends Client {
   getFeeRateStatistics = this.buildSender(
     "get_fee_rate_statistics",
     [(n: NumLike) => apply(numFrom, n)],
-    ({ mean, median }: { mean: NumLike; median: NumLike }) => ({
-      mean: numFrom(mean),
-      median: numFrom(median),
+    // TODO: This is a temporary workaround for the fact that the node may return null for fee rate statistics.
+    // We should change the method signature to return null instead of falling back to the default value,
+    // but this would be a breaking change.
+    (res: { mean: NumLike; median: NumLike } | null) => ({
+      mean: numFrom(res?.mean ?? DEFAULT_MIN_FEE_RATE),
+      median: numFrom(res?.median ?? DEFAULT_MIN_FEE_RATE),
     }),
   ) as Client["getFeeRateStatistics"];
 

package/src/codec/entity.ts

@@ -1,7 +1,9 @@
 import { Bytes, bytesEq, bytesFrom, BytesLike } from "../bytes/index.js";
 import { hashCkb } from "../hasher/index.js";
 import { Hex, hexFrom } from "../hex/index.js";
+import type { UnionDecoded, UnionMatchHandlers } from "../molecule/codec.js";
 import { Constructor } from "../utils/index.js";
+import type { CodecLike, DecodedType } from "./codec.js";
 
 /**
  * The base class of CCC to create a serializable instance. This should be used with the {@link codec} decorator.
@@ -144,10 +146,101 @@ export abstract class Entity {
     return Impl;
   }
 
+  /**
+   * Convert the entity to bytes.
+   * @public
+   * @returns The bytes representation of the entity.
+   */
   abstract toBytes(): Bytes;
+
+  /**
+   * Calculate the hash of the entity.
+   * @public
+   * @returns The hash of the entity.
+   */
   abstract hash(): Hex;
+
+  /**
+   * Convert the entity to a full-byte untrimmed Hex representation.
+   * @public
+   * @returns The entity full-byte untrimmed hexadecimal representation.
+   */
   abstract toHex(): Hex;
+
+  /**
+   * Create a clone of the entity.
+   * @public
+   * @returns A clone of the entity.
+   */
   abstract clone(): Entity;
+
+  /**
+   * Generate a base class of CCC to create a serializable Union instance.
+   * This should be used with the {@link codec} decorator.
+   * @public
+   */
+  static BaseUnion<
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    CodecType extends CodecLike<any, UnionDecoded<any, any>>,
+    SubTypeLike,
+    SubType = SubTypeLike,
+  >() {
+    type Handlers<Result> = UnionMatchHandlers<CodecType, Result>;
+    type Decoded = DecodedType<CodecType>;
+
+    abstract class Impl extends Entity.Base<SubTypeLike, SubType>() {
+      /**
+       * The inner decoded object representing the union value.
+       * @public
+       */
+      constructor(public readonly inner: Decoded) {
+        super();
+      }
+
+      /**
+       * Match the union type with a set of handlers.
+       * @public
+       * @param handlers - A map of type-specific handlers, all variants must be handled if no default handler `_` is provided.
+       * @returns The result returned by the matching handler.
+       */
+      match<Result>(
+        handlers: Handlers<Result> & {
+          _?: undefined | null;
+        },
+      ): Result;
+      /**
+       * Match the union type with a set of handlers.
+       * @public
+       * @param handlers - A map of type-specific handlers, unmatched variants will be handled by the default handler `_`.
+       * @returns The result returned by the matching handler.
+       */
+      match<Result>(
+        handlers: Partial<Handlers<Result>> & {
+          _: (inner: Decoded) => Result;
+        },
+      ): Result;
+      match<Result>(
+        handlers:
+          | (Handlers<Result> & {
+              _?: undefined | null;
+            })
+          | (Partial<Handlers<Result>> & {
+              _: (inner: Decoded) => Result;
+            }),
+      ): Result {
+        const type = this.inner.type as Decoded["type"];
+        const handler = (handlers as Partial<Handlers<Result>>)[type];
+
+        if (handler != undefined) {
+          return handler(this.inner.value);
+        }
+
+        return (handlers._ as (inner: Decoded) => Result)(this.inner);
+      }
+    }
+
+    return Impl;
+  }
 }
 
 /**

package/src/jsonRpc/requestor.ts

@@ -129,14 +129,19 @@ export class RequestorJsonRpc {
       await pending;
     }
 
-    this.concurrent += 1;
-    const res = (await this.transport.request(payload)) as {
+    const res = (await (async () => {
+      this.concurrent += 1;
+      try {
+        return await this.transport.request(payload);
+      } finally {
+        this.concurrent -= 1;
+        this.pending.shift()?.();
+      }
+    })()) as {
       id: number;
       error: unknown;
       result: unknown;
     };
-    this.concurrent -= 1;
-    this.pending.shift()?.();
 
     if (res.id !== payload.id) {
       throw new Error(`Id mismatched, got ${res.id}, expected ${payload.id}`);