@ckb-ccc/core 1.22.0 → 1.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckb-ccc/core",
-  "version": "1.22.0",
+  "version": "1.23.0",
   "description": "Core of CCC - CKBer's Codebase",
   "author": "Hanssen0 <hanssen0@hanssen0.com>",
   "license": "MIT",

package/src/address/index.ts

@@ -52,18 +52,46 @@ export class Address {
   /**
    * Creates an Address instance from an address string.
    *
-   * @param address - The address string to parse.
-   * @param clients - A Client instance or a record of Client instances keyed by prefix.
+   * @param address - The address string to parse. If it does not parse, a
+   * single Client's `addressResolver` may resolve it.
+   * @param client - The Client instance used to parse or resolve the address.
    * @returns A promise that resolves to an Address instance.
    *
-   * @throws Will throw an error if the address prefix is unknown or mismatched.
+   * @throws Will throw an error if the address prefix is unknown or mismatched,
+   * or if the resolver handles the address but does not find it.
    */
 
+  static async fromString(address: string, client: Client): Promise<Address>;
+
+  /**
+   * @deprecated Pass a single Client instead. Callers supporting multiple
+   * prefixes should try each Client themselves.
+   */
+  static async fromString(
+    address: string,
+    clients: Record<string, Client>,
+  ): Promise<Address>;
+
   static async fromString(
     address: string,
     clients: Client | Record<string, Client>,
   ): Promise<Address> {
-    const { prefix, format, payload } = addressPayloadFromString(address);
+    let parsed: ReturnType<typeof addressPayloadFromString>;
+    try {
+      parsed = addressPayloadFromString(address);
+    } catch (error) {
+      const client = clients as Client;
+      const resolver = client.addressResolver;
+      if (!resolver?.shouldResolve(address)) {
+        throw error;
+      }
+      const script = await resolver.resolve(address, client);
+      if (!script) {
+        throw new Error(`Address ${address} not found`, { cause: error });
+      }
+      return Address.fromScript(script, client);
+    }
+    const { prefix, format, payload } = parsed;
 
     const client = (clients as Record<string, Client>)[prefix] ?? clients;
     if (!client) {

package/src/ckb/transaction.ts

@@ -265,12 +265,13 @@ export class CellOutput extends Entity.Base<CellOutputLike, CellOutput>() {
 
   /**
    * Creates a CellOutput instance from a CellOutputLike object.
-   * This method supports automatic capacity calculation when outputData is provided and capacity is 0 or omitted.
+   *
+   * If `outputData` is provided, capacity is ensured to meet the occupied minimum.
+   * Valid instances are returned as-is, while invalid instances are reconstructed
+   * shallowly without mutating the original.
    *
    * @param cellOutput - A CellOutputLike object or an instance of CellOutput.
-   * @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.
+   * @param outputData - Optional output data for capacity verification.
    * @returns A CellOutput instance.
    *
    * @example
@@ -285,23 +286,33 @@ export class CellOutput extends Entity.Base<CellOutputLike, CellOutput>() {
    * // Automatic capacity calculation
    * const cellOutput2 = CellOutput.from({
    *   lock: { codeHash: "0x...", hashType: "type", args: "0x..." }
-   * }, "0x1234"); // Capacity will be calculated automatically
+   * }, "0x1234");
    * ```
    */
   static from(
     cellOutput: CellOutputLike,
     outputData?: HexLike | null,
   ): CellOutput {
-    const output = (() => {
-      if (cellOutput instanceof CellOutput) {
+    if (cellOutput instanceof CellOutput) {
+      if (outputData == null) {
         return cellOutput;
       }
-      return new CellOutput(
-        numFrom(cellOutput.capacity ?? 0),
-        Script.from(cellOutput.lock),
-        apply(Script.from, cellOutput.type),
+
+      const minCapacity = fixedPointFrom(
+        cellOutput.occupiedSize + bytesFrom(outputData).length,
       );
-    })();
+      if (cellOutput.capacity >= minCapacity) {
+        return cellOutput;
+      }
+
+      return new CellOutput(minCapacity, cellOutput.lock, cellOutput.type);
+    }
+
+    const output = new CellOutput(
+      numFrom(cellOutput.capacity ?? 0),
+      Script.from(cellOutput.lock),
+      apply(Script.from, cellOutput.type),
+    );
 
     if (outputData != null) {
       output.capacity = numMax(
@@ -374,11 +385,12 @@ export class CellAny {
 
   /**
    * 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`.
+   *
+   * Returns valid instances as-is. Reconstructs a corrected instance shallowly
+   * without mutating the original if capacity is insufficient for the data.
    *
    * @param cell - A `CellAnyLike` object.
-   * @returns A new `CellAny` instance.
+   * @returns A `CellAny` instance.
    *
    * @example
    * ```typescript
@@ -398,8 +410,11 @@ export class CellAny {
    */
   static from(cell: CellAnyLike): CellAny {
     if (cell instanceof CellAny) {
-      cell.cellOutput = CellOutput.from(cell.cellOutput, cell.outputData);
-      return cell;
+      const output = CellOutput.from(cell.cellOutput, cell.outputData);
+      if (output === cell.cellOutput) {
+        return cell;
+      }
+      return new CellAny(output, cell.outputData, cell.outPoint);
     }
 
     const outputData = hexFrom(cell.outputData ?? "0x");
@@ -524,13 +539,13 @@ export class Cell extends CellAny {
 
   /**
    * 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.
+   *
+   * Returns valid instances as-is. Reconstructs a corrected instance shallowly
+   * without mutating the original if capacity is insufficient for the data.
    *
    * @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
@@ -550,7 +565,6 @@ export class Cell extends CellAny {
    *   previousOutput: { txHash: "0x...", index: 0 },
    *   cellOutput: {
    *     lock: { codeHash: "0x...", hashType: "type", args: "0x..." }
-   *     // capacity will be calculated automatically
    *   },
    *   outputData: "0x1234"
    * });
@@ -559,8 +573,11 @@ export class Cell extends CellAny {
 
   static from(cell: CellLike): Cell {
     if (cell instanceof Cell) {
-      cell.cellOutput = CellOutput.from(cell.cellOutput, cell.outputData);
-      return cell;
+      const output = CellOutput.from(cell.cellOutput, cell.outputData);
+      if (output === cell.cellOutput) {
+        return cell;
+      }
+      return new Cell(cell.outPoint, output, cell.outputData);
     }
 
     return new Cell(
@@ -1261,6 +1278,9 @@ export class Transaction extends Entity.Base<TransactionLike, Transaction>() {
   /**
    * Creates a Transaction instance from a TransactionLike object.
    *
+   * Returns valid instances as-is. Reconstructs a corrected transaction shallowly
+   * without mutating the original if any output capacity is insufficient.
+   *
    * @param tx - A TransactionLike object or an instance of Transaction.
    * @returns A Transaction instance.
    *
@@ -1280,10 +1300,22 @@ export class Transaction extends Entity.Base<TransactionLike, Transaction>() {
 
   static from(tx: TransactionLike): Transaction {
     if (tx instanceof Transaction) {
-      tx.outputs.forEach((output, i) => {
-        tx.outputs[i] = CellOutput.from(output, tx.outputsData[i] ?? "0x");
-      });
-      return tx;
+      const outputs = tx.outputs.map((output, i) =>
+        CellOutput.from(output, tx.outputsData[i] ?? "0x"),
+      );
+      if (outputs.every((output, i) => output === tx.outputs[i])) {
+        return tx;
+      }
+
+      return new Transaction(
+        tx.version,
+        Array.from(tx.cellDeps),
+        Array.from(tx.headerDeps),
+        Array.from(tx.inputs),
+        outputs,
+        Array.from(tx.outputsData),
+        Array.from(tx.witnesses),
+      );
     }
     const outputs =
       tx.outputs?.map((output, i) =>
@@ -2497,13 +2529,22 @@ export class Transaction extends Entity.Base<TransactionLike, Transaction>() {
       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 changedTx.getFee(from.client)) !== leastFee) {
+      const changedActualFee = await changedTx.getFee(from.client);
+      if (changedActualFee < leastFee && fee < leastFee) {
+        // Fee is not fully paid yet because the initial transaction had insufficient inputs.
+        // Collect inputs again to pay leastFee.
+        leastExtraCapacity = Zero;
+        continue;
+      }
+
+      if (changedActualFee !== leastFee) {
         throw new Error(
           "The change function doesn't use all available capacity",
         );
@@ -2671,14 +2712,21 @@ export class Transaction extends Entity.Base<TransactionLike, Transaction>() {
       shouldAddInputs?: boolean;
     },
   ): Promise<[number, boolean]> {
-    const change = Number(numFrom(index));
-    if (!this.outputs[change]) {
+    const change = transactionIndexFrom(index);
+    if (change === undefined || !this.outputs[change]) {
       throw new Error("Non-existed output to change");
     }
     return this.completeFee(
       from,
       (tx, capacity) => {
-        tx.outputs[change].capacity += capacity;
+        tx.setOutput(
+          change,
+          {
+            ...tx.outputs[change],
+            capacity: tx.outputs[change].capacity + capacity,
+          },
+          tx.outputsData[change],
+        );
         return 0;
       },
       feeRate,

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

@@ -1,6 +1,6 @@
 import { bytesFrom } from "../../bytes/index.js";
 import { Cell, CellLike, Script, ScriptLike } from "../../ckb/index.js";
-import { HexLike, hexFrom } from "../../hex/index.js";
+import { Hex, HexLike, hexFrom } from "../../hex/index.js";
 import { NumLike, numFrom } from "../../num/index.js";
 import {
   ClientCollectableSearchKeyLike,
@@ -19,12 +19,27 @@ export type CellRecord =
   | [true, Cell]
   | [undefined, Cell];
 
+function matchPartialHex(data: Hex, filter: Hex): boolean {
+  const needle = filter.slice(2);
+  if (needle.length === 0) {
+    return true;
+  }
+  let pos = data.indexOf(needle, 2);
+  while (pos !== -1) {
+    if (pos % 2 === 0) {
+      return true;
+    }
+    pos = data.indexOf(needle, pos + 1);
+  }
+  return false;
+}
+
 export function filterData(
   dataLike: HexLike,
   filterLike: HexLike | undefined,
   filterMode: "exact" | "prefix" | "partial",
 ): boolean {
-  if (!filterLike) {
+  if (filterLike == null) {
     return true;
   }
 
@@ -33,7 +48,7 @@ export function filterData(
   if (
     (filterMode === "exact" && data !== filter) ||
     (filterMode === "prefix" && !data.startsWith(filter)) ||
-    (filterMode === "partial" && data.search(filter) === -1)
+    (filterMode === "partial" && !matchPartialHex(data, filter))
   ) {
     return false;
   }

package/src/client/client.ts

@@ -38,9 +38,23 @@ import {
 } from "./clientTypes.js";
 import { KnownScript } from "./knownScript.js";
 
+/**
+ * Resolves address representations that `Address.fromString` cannot parse,
+ * such as human-readable names, to scripts.
+ *
+ * @public
+ */
+export interface AddressResolver {
+  /** Whether this resolver handles the representation. */
+  shouldResolve(address: string): boolean;
+  /** The script it points to, or `undefined` if it is not found. */
+  resolve(address: string, client: Client): Promise<ScriptLike | undefined>;
+}
+
 export type ClientConfig = {
   cache?: ClientCache;
   scripts?: Partial<Record<KnownScript, ScriptInfoLike>>;
+  addressResolver?: AddressResolver;
 };
 
 /**
@@ -49,10 +63,12 @@ export type ClientConfig = {
 export abstract class Client {
   public cache: ClientCache;
   private readonly scripts: Partial<Record<KnownScript, ScriptInfoLike>>;
+  public readonly addressResolver?: AddressResolver;
 
   constructor(config?: ClientConfig) {
     this.cache = config?.cache ?? new ClientCacheMemory();
     this.scripts = config?.scripts ?? {};
+    this.addressResolver = config?.addressResolver;
   }
 
   /**
@@ -161,7 +177,7 @@ export abstract class Client {
   /**
    * Get the header of the latest block.
    *
-   * @param verbosity - Verbosity level (0 for hex, 1 for object).
+   * @param verbosity - Deprecated; this parameter has no effect.
    * @returns The tip block header.
    *
    * @example
@@ -175,28 +191,45 @@ export abstract class Client {
    * console.log(`Block #${header.number}, hash: ${header.hash}`);
    * ```
    */
-  abstract getTipHeader(verbosity?: number | null): Promise<ClientBlockHeader>;
+  abstract getTipHeader(
+    /** @deprecated This parameter has no effect and will be removed. */
+    verbosity?: number | null,
+  ): Promise<ClientBlockHeader>;
   abstract getBlockByNumberNoCache(
     blockNumber: NumLike,
+    /** @deprecated This parameter has no effect and will be removed. */
     verbosity?: number | null,
+    /**
+     * @deprecated This parameter has no effect and will be removed.
+     */
     withCycles?: boolean | null,
   ): Promise<ClientBlock | undefined>;
   abstract getBlockByHashNoCache(
     blockHash: HexLike,
+    /** @deprecated This parameter has no effect and will be removed. */
     verbosity?: number | null,
+    /**
+     * @deprecated This parameter has no effect and will be removed.
+     */
     withCycles?: boolean | null,
   ): Promise<ClientBlock | undefined>;
   abstract getHeaderByNumberNoCache(
     blockNumber: NumLike,
+    /** @deprecated This parameter has no effect and will be removed. */
     verbosity?: number | null,
   ): Promise<ClientBlockHeader | undefined>;
   abstract getHeaderByHashNoCache(
     blockHash: HexLike,
+    /** @deprecated This parameter has no effect and will be removed. */
     verbosity?: number | null,
   ): Promise<ClientBlockHeader | undefined>;
   async getBlockByNumber(
     blockNumber: NumLike,
+    /** @deprecated This parameter has no effect and will be removed. */
     verbosity?: number | null,
+    /**
+     * @deprecated This parameter has no effect and will be removed.
+     */
     withCycles?: boolean | null,
   ): Promise<ClientBlock | undefined> {
     const block = await this.cache.getBlockByNumber(blockNumber);
@@ -216,7 +249,11 @@ export abstract class Client {
   }
   async getBlockByHash(
     blockHash: HexLike,
+    /** @deprecated This parameter has no effect and will be removed. */
     verbosity?: number | null,
+    /**
+     * @deprecated This parameter has no effect and will be removed.
+     */
     withCycles?: boolean | null,
   ): Promise<ClientBlock | undefined> {
     const block = await this.cache.getBlockByHash(blockHash);
@@ -236,6 +273,7 @@ export abstract class Client {
   }
   async getHeaderByNumber(
     blockNumber: NumLike,
+    /** @deprecated This parameter has no effect and will be removed. */
     verbosity?: number | null,
   ): Promise<ClientBlockHeader | undefined> {
     const header = await this.cache.getHeaderByNumber(blockNumber);
@@ -251,6 +289,7 @@ export abstract class Client {
   }
   async getHeaderByHash(
     blockHash: HexLike,
+    /** @deprecated This parameter has no effect and will be removed. */
     verbosity?: number | null,
   ): Promise<ClientBlockHeader | undefined> {
     const header = await this.cache.getHeaderByHash(blockHash);

package/src/client/clientPublicMainnet.ts

@@ -52,9 +52,14 @@ export class ClientPublicMainnet extends ClientJsonRpc {
     config: Omit<Parameters<typeof RequestorJsonRpc.new>[0], "onError"> &
       ClientConfig,
   ): ClientPublicMainnet {
-    const { cache, scripts, ...requestorConfig } = config;
+    const { cache, scripts, addressResolver, ...requestorConfig } = config;
     const requestor = this.newRequestor(requestorConfig);
-    return new ClientPublicMainnet({ cache, scripts, requestor });
+    return new ClientPublicMainnet({
+      cache,
+      scripts,
+      addressResolver,
+      requestor,
+    });
   }
 
   /** Opens a Client with explicit ownership of its default dependencies. */
@@ -70,6 +75,7 @@ export class ClientPublicMainnet extends ClientJsonRpc {
     const {
       cache,
       scripts,
+      addressResolver,
       urls = this.defaultUrls(),
       ...requestorConfig
     } = config ?? {};
@@ -81,6 +87,7 @@ export class ClientPublicMainnet extends ClientJsonRpc {
         new ClientPublicMainnet({
           cache,
           scripts,
+          addressResolver,
           requestor,
           url: urls[0],
           fallbacks: [...urls.slice(1)],

package/src/client/clientPublicTestnet.ts

@@ -52,9 +52,14 @@ export class ClientPublicTestnet extends ClientJsonRpc {
     config: Omit<Parameters<typeof RequestorJsonRpc.new>[0], "onError"> &
       ClientConfig,
   ): ClientPublicTestnet {
-    const { cache, scripts, ...requestorConfig } = config;
+    const { cache, scripts, addressResolver, ...requestorConfig } = config;
     const requestor = this.newRequestor(requestorConfig);
-    return new ClientPublicTestnet({ cache, scripts, requestor });
+    return new ClientPublicTestnet({
+      cache,
+      scripts,
+      addressResolver,
+      requestor,
+    });
   }
 
   /** Opens a Client with explicit ownership of its default dependencies. */
@@ -70,6 +75,7 @@ export class ClientPublicTestnet extends ClientJsonRpc {
     const {
       cache,
       scripts,
+      addressResolver,
       urls = this.defaultUrls(),
       ...requestorConfig
     } = config ?? {};
@@ -81,6 +87,7 @@ export class ClientPublicTestnet extends ClientJsonRpc {
         new ClientPublicTestnet({
           cache,
           scripts,
+          addressResolver,
           requestor,
           url: urls[0],
           fallbacks: [...urls.slice(1)],

package/src/client/jsonRpc/client.ts

@@ -178,7 +178,7 @@ export abstract class ClientJsonRpc extends Client {
 
   getFeeRateStatistics = this.buildSender(
     "get_fee_rate_statistics",
-    [(n: NumLike) => apply(numFrom, n)],
+    [(n?: NumLike) => apply(numToHex, n)],
     // 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.
@@ -203,7 +203,7 @@ export abstract class ClientJsonRpc extends Client {
   /**
    * Get tip block header
    *
-   * @param verbosity - result format which allows 0 and 1. (Optional, the default is 1.)
+   * @param verbosity - Deprecated; this parameter has no effect.
    * @returns BlockHeader
    */
   getTipHeader = this.buildSender(
@@ -216,8 +216,8 @@ export abstract class ClientJsonRpc extends Client {
    * Get block by block number
    *
    * @param blockNumber - The block number.
-   * @param verbosity - result format which allows 0 and 2. (Optional, the default is 2.)
-   * @param withCycles - whether the return cycles of block transactions. (Optional, default false.)
+   * @param verbosity - Deprecated; this parameter has no effect.
+   * @param withCycles - Deprecated; this parameter has no effect.
    * @returns Block
    */
   getBlockByNumberNoCache = this.buildSender(
@@ -230,8 +230,8 @@ export abstract class ClientJsonRpc extends Client {
    * Get block by block hash
    *
    * @param blockHash - The block hash.
-   * @param verbosity - result format which allows 0 and 2. (Optional, the default is 2.)
-   * @param withCycles - whether the return cycles of block transactions. (Optional, default false.)
+   * @param verbosity - Deprecated; this parameter has no effect.
+   * @param withCycles - Deprecated; this parameter has no effect.
    * @returns Block
    */
   getBlockByHashNoCache = this.buildSender(
@@ -244,7 +244,7 @@ export abstract class ClientJsonRpc extends Client {
    * Get header by block number
    *
    * @param blockNumber - The block number.
-   * @param verbosity - result format which allows 0 and 1. (Optional, the default is 1.)
+   * @param verbosity - Deprecated; this parameter has no effect.
    * @returns BlockHeader
    */
   getHeaderByNumberNoCache = this.buildSender(
@@ -257,7 +257,7 @@ export abstract class ClientJsonRpc extends Client {
    * Get header by block hash
    *
    * @param blockHash - The block hash.
-   * @param verbosity - result format which allows 0 and 1. (Optional, the default is 1.)
+   * @param verbosity - Deprecated; this parameter has no effect.
    * @returns BlockHeader
    */
   getHeaderByHashNoCache = this.buildSender(