@ckb-ccc/core 1.11.5 → 1.12.1

package/src/ckb/transaction.ts

@@ -198,7 +198,7 @@ export class OutPoint extends mol.Entity.Base<OutPointLike, OutPoint>() {
  * @public
  */
 export type CellOutputLike = {
-  capacity: NumLike;
+  capacity?: NumLike | null;
   lock: ScriptLike;
   type?: ScriptLike | null;
 };
@@ -238,7 +238,6 @@ export class CellOutput extends mol.Entity.Base<CellOutputLike, CellOutput>() {
    * 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.
@@ -259,16 +258,9 @@ export class CellOutput extends mol.Entity.Base<CellOutputLike, CellOutput>() {
    * }, "0x1234"); // Capacity will be calculated automatically
    * ```
    */
-  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: CellOutputLike,
+    outputData?: HexLike | null,
   ): CellOutput {
     if (cellOutput instanceof CellOutput) {
       return cellOutput;
@@ -307,33 +299,189 @@ export const CellOutputVec = mol.vector(CellOutput);
 
 /**
  * @public
+ * Represents a cell-like object that may or may not be on-chain.
+ * It can optionally have an `outPoint` (or `previousOutput`).
+ * This is used as a flexible input for creating `CellAny` instances.
+ * @see CellAny
  */
-export type CellLike = (
-  | {
-      outPoint: OutPointLike;
-    }
-  | { previousOutput: OutPointLike }
-) & {
+export type CellAnyLike = {
+  outPoint?: OutPointLike | null;
+  previousOutput?: OutPointLike | null;
   cellOutput: CellOutputLike;
-  outputData: HexLike;
+  outputData?: HexLike | null;
 };
 /**
+ * Represents a CKB cell that can be either on-chain (with an `outPoint`) or off-chain (without an `outPoint`).
+ * This class provides a unified interface for handling cells before they are included in a transaction,
+ * or for cells that are already part of the blockchain state.
+ *
  * @public
  */
-export class Cell {
+export class CellAny {
+  public outPoint: OutPoint | undefined;
+
   /**
-   * Creates an instance of Cell.
+   * Creates an instance of CellAny.
    *
-   * @param outPoint - The output point of the cell.
    * @param cellOutput - The cell output of the cell.
    * @param outputData - The output data of the cell.
+   * @param outPoint - The optional output point of the cell. If provided, the cell is considered on-chain.
    */
 
   constructor(
-    public outPoint: OutPoint,
     public cellOutput: CellOutput,
     public outputData: Hex,
-  ) {}
+    outPoint?: OutPoint,
+  ) {
+    this.outPoint = outPoint;
+  }
+
+  /**
+   * Creates a `CellAny` instance from a `CellAnyLike` object.
+   * This factory method provides a convenient way to create `CellAny` instances
+   * from plain objects, automatically handling the optional `outPoint` or `previousOutput`.
+   *
+   * @param cell - A `CellAnyLike` object.
+   * @returns A new `CellAny` instance.
+   *
+   * @example
+   * ```typescript
+   * // Create an off-chain cell (e.g., a new output)
+   * const offChainCell = CellAny.from({
+   *   cellOutput: { capacity: 1000n, lock: lockScript },
+   *   outputData: "0x"
+   * });
+   *
+   * // Create an on-chain cell from an input
+   * const onChainCell = CellAny.from({
+   *   outPoint: { txHash: "0x...", index: 0 },
+   *   cellOutput: { capacity: 2000n, lock: lockScript },
+   *   outputData: "0x1234"
+   * });
+   * ```
+   */
+  static from(cell: CellAnyLike): CellAny {
+    if (cell instanceof CellAny) {
+      return cell;
+    }
+
+    return new CellAny(
+      CellOutput.from(cell.cellOutput, cell.outputData),
+      hexFrom(cell.outputData ?? "0x"),
+      apply(OutPoint.from, cell.outPoint ?? cell.previousOutput),
+    );
+  }
+
+  /**
+   * Calculates the total occupied size of the cell in bytes.
+   * This includes the size of the `CellOutput` structure plus the size of the `outputData`.
+   *
+   * @returns The total occupied size in bytes.
+   */
+  get occupiedSize() {
+    return this.cellOutput.occupiedSize + bytesFrom(this.outputData).byteLength;
+  }
+
+  /**
+   * Calculates the free capacity of the cell.
+   * Free capacity is the total capacity minus the capacity occupied by the cell's structure and data.
+   *
+   * @returns The free capacity in shannons as a `Num`.
+   */
+  get capacityFree() {
+    return this.cellOutput.capacity - fixedPointFrom(this.occupiedSize);
+  }
+
+  /**
+   * Checks if the cell is a Nervos DAO cell and optionally checks its phase.
+   *
+   * @param client - A CKB client instance to fetch known script information.
+   * @param phase - Optional phase to check: "deposited" or "withdrew".
+   *                If omitted, it checks if the cell is a DAO cell regardless of phase.
+   * @returns A promise that resolves to `true` if the cell is a matching Nervos DAO cell, `false` otherwise.
+   */
+  async isNervosDao(
+    client: Client,
+    phase?: "deposited" | "withdrew",
+  ): Promise<boolean> {
+    const { type } = this.cellOutput;
+
+    const daoType = await client.getKnownScript(KnownScript.NervosDao);
+    if (
+      !type ||
+      type.codeHash !== daoType.codeHash ||
+      type.hashType !== daoType.hashType
+    ) {
+      // Non Nervos DAO cell
+      return false;
+    }
+
+    const hasWithdrew = numFrom(this.outputData) !== Zero;
+    return (
+      !phase ||
+      (phase === "deposited" && !hasWithdrew) ||
+      (phase === "withdrew" && hasWithdrew)
+    );
+  }
+
+  /**
+   * Clones the `CellAny` instance.
+   *
+   * @returns A new `CellAny` instance that is a deep copy of the current one.
+   *
+   * @example
+   * ```typescript
+   * const clonedCell = cellAny.clone();
+   * ```
+   */
+  clone(): CellAny {
+    return new CellAny(
+      this.cellOutput.clone(),
+      this.outputData,
+      this.outPoint?.clone(),
+    );
+  }
+}
+
+/**
+ * Represents a cell-like object that is guaranteed to be on-chain.
+ * It must have an `outPoint` (or its alias `previousOutput`).
+ * This is used as a type constraint for creating `Cell` instances.
+ * @see Cell
+ * @public
+ */
+export type CellLike = CellAnyLike &
+  (
+    | {
+        outPoint: OutPointLike;
+        previousOutput?: undefined | null;
+      }
+    | {
+        outPoint?: undefined | null;
+        previousOutput: OutPointLike;
+      }
+  );
+/**
+ * Represents an on-chain CKB cell, which is a `CellAny` that is guaranteed to have an `outPoint`.
+ * This class is typically used for cells that are already part of the blockchain state, such as transaction inputs.
+ * @public
+ */
+export class Cell extends CellAny {
+  /**
+   * Creates an instance of an on-chain Cell.
+   *
+   * @param outPoint - The output point of the cell.
+   * @param cellOutput - The cell output of the cell.
+   * @param outputData - The output data of the cell.
+   */
+
+  constructor(
+    public outPoint: OutPoint,
+    cellOutput: CellOutput,
+    outputData: Hex,
+  ) {
+    super(cellOutput, outputData, outPoint);
+  }
 
   /**
    * Creates a Cell instance from a CellLike object.
@@ -376,25 +524,10 @@ export class Cell {
     }
 
     return new Cell(
-      OutPoint.from("outPoint" in cell ? cell.outPoint : cell.previousOutput),
+      OutPoint.from(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,
+      hexFrom(cell.outputData ?? "0x"),
     );
-    return this.cellOutput.capacity - occupiedSize;
-  }
-
-  /**
-   * Occupied bytes of a cell on chain
-   * It's CellOutput.occupiedSize + bytesFrom(outputData).byteLength
-   */
-  get occupiedSize() {
-    return this.cellOutput.occupiedSize + bytesFrom(this.outputData).byteLength;
   }
 
   /**
@@ -426,30 +559,22 @@ export class Cell {
     return calcDaoProfit(this.capacityFree, depositHeader, withdrawHeader);
   }
 
-  async isNervosDao(
-    client: Client,
-    phase?: "deposited" | "withdrew",
-  ): Promise<boolean> {
-    const { type } = this.cellOutput;
-
-    const daoType = await client.getKnownScript(KnownScript.NervosDao);
-    if (
-      !type ||
-      type.codeHash !== daoType.codeHash ||
-      type.hashType !== daoType.hashType
-    ) {
-      // Non Nervos DAO cell
-      return false;
-    }
-
-    const hasWithdrew = numFrom(this.outputData) !== Zero;
-    return (
-      !phase ||
-      (phase === "deposited" && !hasWithdrew) ||
-      (phase === "withdrew" && hasWithdrew)
-    );
-  }
-
+  /**
+   * Retrieves detailed information about a Nervos DAO cell, including its deposit and withdrawal headers.
+   *
+   * @param client - A CKB client instance to fetch cell and header data.
+   * @returns A promise that resolves to an object containing header information.
+   *          - If not a DAO cell, returns `{}`.
+   *          - If a deposited DAO cell, returns `{ depositHeader }`.
+   *          - If a withdrawn DAO cell, returns `{ depositHeader, withdrawHeader }`.
+   *
+   * @throws If the cell is a DAO cell but its corresponding headers cannot be fetched.
+   *
+   * @example
+   * ```typescript
+   * const daoInfo = await cell.getNervosDaoInfo(client);
+   * ```
+   */
   async getNervosDaoInfo(client: Client): Promise<
     // Non Nervos DAO cell
     | {
@@ -1583,39 +1708,92 @@ export class Transaction extends mol.Entity.Base<
    * await tx.getOutput(0);
    * ```
    */
-  getOutput(index: NumLike):
-    | {
-        cellOutput: CellOutput;
-        outputData: Hex;
-      }
-    | undefined {
+  getOutput(index: NumLike): CellAny | undefined {
     const i = Number(numFrom(index));
     if (i >= this.outputs.length) {
       return;
     }
-    return {
+    return CellAny.from({
       cellOutput: this.outputs[i],
       outputData: this.outputsData[i] ?? "0x",
-    };
+    });
   }
+
   /**
-   * Add output
+   * Provides an iterable over the transaction's output cells.
+   *
+   * This getter is a convenient way to iterate through all the output cells (`CellAny`)
+   * of the transaction, combining the `outputs` and `outputsData` arrays.
+   * It can be used with `for...of` loops or other iterable-consuming patterns.
    *
-   * @param outputLike - The cell output to add
-   * @param outputData - optional output data
+   * @public
+   * @category Getter
+   * @returns An `Iterable<CellAny>` that yields each output cell of the transaction.
    *
    * @example
    * ```typescript
-   * await tx.addOutput(cellOutput, "0xabcd");
+   * for (const cell of tx.outputCells) {
+   *   console.log(`Output cell capacity: ${cell.cellOutput.capacity}`);
+   * }
    * ```
    */
+  get outputCells(): Iterable<CellAny> {
+    const { outputs, outputsData } = this;
+
+    function* generator(): Generator<CellAny> {
+      for (let i = 0; i < outputs.length; i++) {
+        yield CellAny.from({
+          cellOutput: outputs[i],
+          outputData: outputsData[i] ?? "0x",
+        });
+      }
+    }
+
+    return generator();
+  }
+
+  /**
+   * Adds an output to the transaction.
+   *
+   * This method supports two overloads for adding an output:
+   * 1. By providing a `CellAnyLike` object, which encapsulates both `cellOutput` and `outputData`.
+   * 2. By providing a `CellOutputLike` object and an optional `outputData`.
+   *
+   * @param cellOrOutputLike - A cell-like object containing both cell output and data, or just the cell output object.
+   * @param outputDataLike - Optional data for the cell output. Defaults to "0x" if not provided in the first argument.
+   * @returns The new number of outputs in the transaction.
+   *
+   * @example
+   * ```typescript
+   * // 1. Add an output using a CellAnyLike object
+   * const newLength1 = tx.addOutput({
+   *   cellOutput: { lock: recipientLock }, // capacity is calculated automatically
+   *   outputData: "0x1234",
+   * });
+   *
+   * // 2. Add an output using CellOutputLike and data separately
+   * const newLength2 = tx.addOutput({ lock: recipientLock }, "0xabcd");
+   * ```
+   */
+  addOutput(cellLike: CellAnyLike): number;
+  addOutput(
+    outputLike: CellOutputLike,
+    outputDataLike?: HexLike | null,
+  ): number;
   addOutput(
-    outputLike: Omit<CellOutputLike, "capacity"> &
-      Partial<Pick<CellOutputLike, "capacity">>,
-    outputData: HexLike = "0x",
+    cellOrOutputLike: CellAnyLike | CellOutputLike,
+    outputDataLike?: HexLike | null,
   ): number {
-    const len = this.outputs.push(CellOutput.from(outputLike, outputData));
-    this.setOutputDataAt(len - 1, outputData);
+    const cell =
+      "cellOutput" in cellOrOutputLike
+        ? CellAny.from(cellOrOutputLike)
+        : CellAny.from({
+            cellOutput: cellOrOutputLike,
+            outputData: outputDataLike,
+          });
+
+    const len = this.outputs.push(cell.cellOutput);
+    this.setOutputDataAt(len - 1, cell.outputData);
 
     return len;
   }

package/src/client/client.ts

@@ -177,6 +177,13 @@ export abstract class Client {
     txHash: HexLike,
   ): Promise<ClientTransactionResponse | undefined>;
 
+  /**
+   * Get a cell by its out point.
+   * The cell will be cached if it is found.
+   *
+   * @param outPointLike - The out point of the cell to get.
+   * @returns The cell if it exists, otherwise undefined.
+   */
   async getCell(outPointLike: OutPointLike): Promise<Cell | undefined> {
     const outPoint = OutPoint.from(outPointLike);
     const cached = await this.cache.getCell(outPoint);
@@ -195,8 +202,8 @@ export abstract class Client {
     }
 
     const cell = Cell.from({
-      outPoint,
       ...output,
+      outPoint,
     });
     await this.cache.recordCells(cell);
     return cell;
@@ -219,8 +226,8 @@ export abstract class Client {
     }
 
     const cell = Cell.from({
-      outPoint,
       ...output,
+      outPoint,
     });
     await this.cache.recordCells(cell);
     return { cell, header };

package/src/client/jsonRpc/client.ts

@@ -251,11 +251,14 @@ export abstract class ClientJsonRpc extends Client {
 
   sendTransactionNoCache = this.buildSender(
     "send_transaction",
-    [JsonRpcTransformers.transactionFrom],
+    [
+      JsonRpcTransformers.transactionFrom,
+      (validator?: OutputsValidator | null) => validator ?? undefined,
+    ],
     hexFrom,
   ) as (
     transaction: TransactionLike,
-    validator?: OutputsValidator | undefined,
+    validator?: OutputsValidator | null,
   ) => Promise<Hex>;
 
   /**

package/src/client/jsonRpc/transformers.ts

@@ -124,7 +124,12 @@ export class JsonRpcTransformers {
       since: cellInput.since,
     });
   }
-  static cellOutputFrom(cellOutput: CellOutputLike): JsonRpcCellOutput {
+  static cellOutputFrom(
+    cellOutputLike: CellOutputLike,
+    outputData?: HexLike | null,
+  ): JsonRpcCellOutput {
+    const cellOutput = CellOutput.from(cellOutputLike, outputData);
+
     return {
       capacity: numToHex(cellOutput.capacity),
       lock: JsonRpcTransformers.scriptFrom(cellOutput.lock),

package/src/jsonRpc/requestor.ts

@@ -141,8 +141,8 @@ export class RequestorJsonRpc {
     if (res.id !== payload.id) {
       throw new Error(`Id mismatched, got ${res.id}, expected ${payload.id}`);
     }
-    if (res.error) {
-      throw res.error;
+    if (res.error != null) {
+      throw res.error as unknown;
     }
     return res.result;
   }

package/src/signer/btc/verify.ts

@@ -1,10 +1,59 @@
 import { secp256k1 } from "@noble/curves/secp256k1";
 import { ripemd160 } from "@noble/hashes/legacy.js";
 import { sha256 } from "@noble/hashes/sha2.js";
-import { magicHash } from "bitcoinjs-message";
 import bs58check from "bs58check";
-import { Bytes, BytesLike, bytesConcat, bytesFrom } from "../../bytes/index.js";
+import { Bytes, bytesConcat, bytesFrom, BytesLike } from "../../bytes/index.js";
 import { Hex, hexFrom } from "../../hex/index.js";
+import { numFrom, numLeToBytes, NumLike } from "../../num/index.js";
+
+/**
+ * Encodes a number into a variable-length byte array according to the Bitcoin protocol.
+ * This format is used for encoding lengths of data, such as script lengths.
+ *
+ * @param len - The number to encode. Can be a NumLike.
+ * @returns The encoded length as a Bytes.
+ * @public
+ */
+export function btcVarLengthBytesFrom(len: NumLike): Bytes {
+  const num = numFrom(len);
+
+  return num < 0xfd
+    ? numLeToBytes(num, 1)
+    : num <= 0xffff
+      ? bytesConcat([0xfd], numLeToBytes(num, 2))
+      : num <= 0xffffffff
+        ? bytesConcat([0xfe], numLeToBytes(num, 4))
+        : bytesConcat([0xff], numLeToBytes(num, 8));
+}
+
+/**
+ * Computes the message hash for Bitcoin ECDSA signatures.
+ * This function follows the Bitcoin message signing standard, which involves
+ * prefixing the message with a magic string and its length, then double SHA256 hashing the result.
+ *
+ * @param message - The message to be hashed. Can be a string or BytesLike.
+ * @param messagePrefix - Optional. A custom prefix to use instead of the default "\u0018Bitcoin Signed Message:\n".
+ * @returns The Bitcoin hash of the prefixed message as Bytes.
+ * @public
+ */
+export function messageHashBtcEcdsa(
+  message: string | BytesLike,
+  messagePrefix?: string | BytesLike,
+): Bytes {
+  const prefix = messagePrefix ?? "\u0018Bitcoin Signed Message:\n";
+  const rawPrefix: Bytes =
+    typeof prefix === "string" ? bytesFrom(prefix, "utf8") : bytesFrom(prefix);
+  const rawMsg: Bytes =
+    typeof message === "string"
+      ? bytesFrom(message, "utf8")
+      : bytesFrom(message);
+
+  return sha256(
+    sha256(
+      bytesConcat(rawPrefix, btcVarLengthBytesFrom(rawMsg.length), rawMsg),
+    ),
+  );
+}
 
 /**
  * @public
@@ -47,7 +96,7 @@ export function verifyMessageBtcEcdsa(
 
   return secp256k1.verify(
     bytesFrom(rawSign),
-    magicHash(challenge),
+    messageHashBtcEcdsa(challenge),
     bytesFrom(publicKey),
   );
 }

package/src/signer/doge/signerDogePrivateKey.ts

@@ -1,5 +1,4 @@
 import { secp256k1 } from "@noble/curves/secp256k1";
-import { magicHash } from "bitcoinjs-message";
 import {
   Bytes,
   bytesConcat,
@@ -11,6 +10,7 @@ import { Client } from "../../client/index.js";
 import { Hex, hexFrom } from "../../hex/index.js";
 import { btcP2pkhAddressFromPublicKey } from "../btc/verify.js";
 import { SignerDoge } from "./signerDoge.js";
+import { messageHashDogeEcdsa } from "./verify.js";
 
 /**
  * A class extending SignerDoge that provides access to a Doge address.
@@ -85,7 +85,7 @@ export class SignerDogePrivateKey extends SignerDoge {
     const challenge = typeof msg === "string" ? msg : hexFrom(msg).slice(2);
 
     const signature = secp256k1.sign(
-      magicHash(challenge, "\x19Dogecoin Signed Message:\n"),
+      messageHashDogeEcdsa(challenge),
       this.privateKey,
     );
 

package/src/signer/doge/verify.ts

@@ -1,12 +1,32 @@
 import { secp256k1 } from "@noble/curves/secp256k1";
-import { magicHash } from "bitcoinjs-message";
-import { bytesFrom, BytesLike } from "../../bytes/index.js";
+import { Bytes, bytesFrom, BytesLike } from "../../bytes/index.js";
 import { hexFrom } from "../../hex/index.js";
 import {
   btcEcdsaPublicKeyHash,
   btcPublicKeyFromP2pkhAddress,
+  messageHashBtcEcdsa,
 } from "../btc/verify.js";
 
+/**
+ * Computes the message hash for Dogecoin ECDSA signatures.
+ * This function follows the Dogecoin message signing standard, which involves
+ * prefixing the message with a magic string and its length, then double SHA256 hashing the result.
+ *
+ * @param message - The message to be hashed. Can be a string or BytesLike.
+ * @param messagePrefix - Optional. A custom prefix to use instead of the default "\x19Dogecoin Signed Message:\n".
+ * @returns The Dogecoin hash of the prefixed message as Bytes.
+ * @public
+ */
+export function messageHashDogeEcdsa(
+  message: string | BytesLike,
+  messagePrefix?: string | BytesLike,
+): Bytes {
+  return messageHashBtcEcdsa(
+    message,
+    messagePrefix ?? "\x19Dogecoin Signed Message:\n",
+  );
+}
+
 /**
  * @public
  */
@@ -29,11 +49,7 @@ export function verifyMessageDogeEcdsa(
     btcPublicKeyFromP2pkhAddress(address) ===
     hexFrom(
       btcEcdsaPublicKeyHash(
-        sig
-          .recoverPublicKey(
-            magicHash(challenge, "\x19Dogecoin Signed Message:\n"),
-          )
-          .toHex(),
+        sig.recoverPublicKey(messageHashDogeEcdsa(challenge)).toHex(),
       ),
     )
   );

package/src/signer/signer/index.ts

@@ -96,11 +96,12 @@ export abstract class Signer {
   ): NetworkPreference | undefined {
     if (
       currentNetwork !== undefined &&
-      preferences.some(({ signerType, addressPrefix, network }) => {
-        signerType === this.type &&
+      preferences.some(
+        ({ signerType, addressPrefix, network }) =>
+          signerType === this.type &&
           addressPrefix === this.client.addressPrefix &&
-          network === currentNetwork;
-      })
+          network === currentNetwork,
+      )
     ) {
       return;
     }
@@ -459,14 +460,23 @@ export abstract class Signer {
   }
 
   /**
-   * prepare a transaction before signing. This method is not implemented and should be overridden by subclasses.
+   * Prepares a transaction before signing.
+   * This method can be overridden by subclasses to perform any necessary steps,
+   * such as adding cell dependencies or witnesses, before the transaction is signed.
+   * The default implementation converts the {@link TransactionLike} object to a {@link Transaction} object
+   * without modification.
    *
-   * @param _ - The transaction to prepare, represented as a TransactionLike object.
-   * @returns A promise that resolves to the prepared Transaction object.
-   * @throws Will throw an error if not implemented.
+   * @remarks
+   * Note that this default implementation does not add any cell dependencies or dummy witnesses.
+   * This may lead to an underestimation of transaction size and fees if used with methods
+   * like `Transaction.completeFee`. Subclasses for signers that are intended to sign
+   * transactions should override this method to perform necessary preparations.
+   *
+   * @param tx - The transaction to prepare.
+   * @returns A promise that resolves to the prepared {@link Transaction} object.
    */
-  prepareTransaction(_: TransactionLike): Promise<Transaction> {
-    throw Error("Signer.prepareTransaction not implemented");
+  async prepareTransaction(tx: TransactionLike): Promise<Transaction> {
+    return Transaction.from(tx);
   }
 
   /**