@ckb-ccc/core 1.9.1 → 1.11.0

package/src/ckb/transactionErrors.ts

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

package/src/client/cache/cache.ts

@@ -6,7 +6,7 @@ import {
   TransactionLike,
 } from "../../ckb/index.js";
 import { HexLike } from "../../hex/index.js";
-import { NumLike } from "../../num/index.js";
+import { numFrom, NumLike } from "../../num/index.js";
 import { ClientCollectableSearchKeyLike } from "../clientTypes.advanced.js";
 import {
   ClientBlock,
@@ -16,6 +16,7 @@ import {
   ClientTransactionResponse,
   ClientTransactionResponseLike,
 } from "../clientTypes.js";
+import { DEFAULT_CONFIRMED_BLOCK_TIME } from "./memory.advanced.js";
 
 /**
  * @public
@@ -185,4 +186,16 @@ export abstract class ClientCache {
   async getBlockByNumber(_number: NumLike): Promise<ClientBlock | undefined> {
     return;
   }
+
+  /**
+   * Checks if a block header is considered confirmed.
+   * The default implementation compares the header's timestamp against the current time
+   * and a configured confirmation time. Override this method for custom confirmation logic.
+   * @param header
+   */
+  hasHeaderConfirmed(header: ClientBlockHeader): boolean {
+    return (
+      numFrom(Date.now()) - header.timestamp >= DEFAULT_CONFIRMED_BLOCK_TIME
+    );
+  }
 }

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

@@ -8,6 +8,8 @@ import {
 } from "../clientTypes.advanced.js";
 import { ClientIndexerSearchKey } from "../clientTypes.js";
 
+export const DEFAULT_CONFIRMED_BLOCK_TIME = numFrom(1000 * 10 * 50); // 50 blocks * 10s
+
 // [isLive, Cell | OutPoint]
 export type CellRecord =
   | [
@@ -142,49 +144,74 @@ export function filterCell(
   return true;
 }
 
+/**
+ * A Least Recently Used (LRU) cache implemented using a Map.
+ *
+ * This class extends the built-in Map to provide an LRU cache with a fixed capacity.
+ * When the cache is full, the least recently used entry is automatically evicted.
+ *
+ * @template K The type of the keys in the cache.
+ * @template V The type of the values in the cache.
+ */
 export class MapLru<K, V> extends Map<K, V> {
-  private readonly lru: K[] = [];
-
+  /**
+   * Constructs a new MapLru instance.
+   *
+   * @param capacity The maximum number of entries the cache can hold. Must be a positive integer.
+   * @throws {Error} If the capacity is not a positive integer.
+   */
   constructor(private readonly capacity: number) {
     super();
-  }
-
-  get(key: K) {
-    const val = super.get(key);
-    if (val === undefined) {
-      return;
+    if (!Number.isInteger(capacity) || capacity < 1) {
+      throw new Error("Capacity must be a positive integer");
     }
+  }
 
-    const index = this.lru.indexOf(key);
-    if (index !== -1) {
-      this.lru.splice(index, 1);
-    }
-    this.lru.push(key);
-    if (this.lru.length > this.capacity) {
-      this.delete(this.lru[0]);
-      this.lru.shift();
+  /**
+   * Retrieves a value from the cache.
+   *
+   * If the key is present in the cache, the value is moved to the most-recently-used position.
+   *
+   * @param key The key of the value to retrieve.
+   * @returns The value associated with the key, or undefined if the key is not present.
+   */
+  override get(key: K): V | undefined {
+    // Check if the key exists. If not, return undefined.
+    if (!super.has(key)) {
+      return undefined;
     }
 
-    return val;
-  }
-
-  set(key: K, value: V) {
-    this.get(key);
+    const value = super.get(key) as V;
 
+    // Move to most-recently-used position
+    super.delete(key);
     super.set(key, value);
-    return this;
+
+    return value;
   }
 
-  delete(key: K): boolean {
-    if (!super.delete(key)) {
-      return false;
-    }
+  /**
+   * Inserts a new value into the cache, or updates an existing value.
+   *
+   * If the key is already present in the cache, it is first deleted so that the re-insertion
+   * moves it to the most-recently-used position.
+   * If the cache is over capacity after the insertion, the least recently used entry is evicted.
+   *
+   * @param key The key of the value to insert or update.
+   * @param value The value to associate with the key.
+   * @returns This MapLru instance.
+   */
+  override set(key: K, value: V): this {
+    // Delete and re-insert to move key to the end (most-recently-used)
+    super.delete(key);
+    super.set(key, value);
 
-    const index = this.lru.indexOf(key);
-    if (index !== -1) {
-      this.lru.splice(index, 1);
+    // Evict oldest if over capacity
+    if (super.size > this.capacity) {
+      const oldestKey = super.keys().next().value!;
+      super.delete(oldestKey);
     }
 
-    return true;
+    return this;
   }
 }

package/src/client/cache/memory.ts

@@ -11,7 +11,12 @@ import {
   ClientTransactionResponseLike,
 } from "../clientTypes.js";
 import { ClientCache } from "./cache.js";
-import { CellRecord, filterCell, MapLru } from "./memory.advanced.js";
+import {
+  CellRecord,
+  DEFAULT_CONFIRMED_BLOCK_TIME,
+  filterCell,
+  MapLru,
+} from "./memory.advanced.js";
 
 export class ClientCacheMemory extends ClientCache {
   /**
@@ -37,10 +42,18 @@ export class ClientCacheMemory extends ClientCache {
     Pick<ClientBlock, "header"> | ClientBlock
   >;
 
+  /**
+   * @param maxCells - Maximum number of cells to store in the cache. Defaults to 512.
+   * @param maxTxs - Maximum number of transactions to store in the cache. Defaults to 256.
+   * @param maxBlocks - Maximum number of blocks to store in the cache. Defaults to 128.
+   * @param confirmedBlockTime - Time in milliseconds after which a block is considered confirmed.
+   *                              Defaults to DEFAULT_CONFIRMED_BLOCK_TIME (50 blocks * 10s).
+   */
   constructor(
     private readonly maxCells = 512,
     private readonly maxTxs = 256,
     private readonly maxBlocks = 128,
+    private readonly confirmedBlockTime = DEFAULT_CONFIRMED_BLOCK_TIME,
   ) {
     super();
 
@@ -216,4 +229,8 @@ export class ClientCacheMemory extends ClientCache {
     }
     return this.getBlockByHash(hash);
   }
+
+  hasHeaderConfirmed(header: ClientBlockHeader): boolean {
+    return numFrom(Date.now()) - header.timestamp >= this.confirmedBlockTime;
+  }
 }

package/src/client/client.ts

@@ -14,7 +14,6 @@ import { reduceAsync, sleep } from "../utils/index.js";
 import { ClientCache } from "./cache/index.js";
 import { ClientCacheMemory } from "./cache/memory.js";
 import {
-  CONFIRMED_BLOCK_TIME,
   ClientCollectableSearchKeyLike,
   DEFAULT_MAX_FEE_RATE,
   DEFAULT_MIN_FEE_RATE,
@@ -38,10 +37,6 @@ import {
 } from "./clientTypes.js";
 import { KnownScript } from "./knownScript.js";
 
-function hasHeaderConfirmed(header: ClientBlockHeader): boolean {
-  return numFrom(Date.now()) - header.timestamp >= CONFIRMED_BLOCK_TIME;
-}
-
 /**
  * @public
  */
@@ -112,7 +107,7 @@ export abstract class Client {
       verbosity,
       withCycles,
     );
-    if (res && hasHeaderConfirmed(res.header)) {
+    if (res && this.cache.hasHeaderConfirmed(res.header)) {
       await this.cache.recordBlocks(res);
     }
     return res;
@@ -132,7 +127,7 @@ export abstract class Client {
       verbosity,
       withCycles,
     );
-    if (res && hasHeaderConfirmed(res.header)) {
+    if (res && this.cache.hasHeaderConfirmed(res.header)) {
       await this.cache.recordBlocks(res);
     }
     return res;
@@ -147,7 +142,7 @@ export abstract class Client {
     }
 
     const res = await this.getHeaderByNumberNoCache(blockNumber, verbosity);
-    if (res && hasHeaderConfirmed(res)) {
+    if (res && this.cache.hasHeaderConfirmed(res)) {
       await this.cache.recordHeaders(res);
     }
     return res;
@@ -162,7 +157,7 @@ export abstract class Client {
     }
 
     const res = await this.getHeaderByHashNoCache(blockHash, verbosity);
-    if (res && hasHeaderConfirmed(res)) {
+    if (res && this.cache.hasHeaderConfirmed(res)) {
       await this.cache.recordHeaders(res);
     }
     return res;
@@ -636,7 +631,7 @@ export abstract class Client {
     const tx = await this.cache.getTransactionResponse(txHash);
     if (tx?.blockHash) {
       const header = await this.getHeaderByHash(tx.blockHash);
-      if (header && hasHeaderConfirmed(header)) {
+      if (header && this.cache.hasHeaderConfirmed(header)) {
         return {
           transaction: tx,
           header,

package/src/client/clientTypes.advanced.ts

@@ -2,7 +2,6 @@ import { ScriptLike } from "../ckb/index.js";
 import { HexLike } from "../hex/index.js";
 import { Num, numFrom, NumLike } from "../num/index.js";
 
-export const CONFIRMED_BLOCK_TIME = numFrom(1000 * 10 * 50); // 50 blocks * 10s
 export const DEFAULT_MAX_FEE_RATE = numFrom(10000000);
 export const DEFAULT_MIN_FEE_RATE = numFrom(1000);
 

package/src/hasher/hasherCkb.ts

@@ -1,8 +1,6 @@
 import { blake2b } from "@noble/hashes/blake2b";
 import { BytesLike, bytesFrom } from "../bytes/index.js";
-import { CellInput, CellInputLike } from "../ckb/index.js";
 import { Hex, hexFrom } from "../hex/index.js";
-import { NumLike, numLeToBytes } from "../num/index.js";
 import { CKB_BLAKE2B_PERSONAL } from "./advanced.js";
 import { Hasher } from "./hasher.js";
 
@@ -81,27 +79,3 @@ export function hashCkb(...data: BytesLike[]): Hex {
   data.forEach((d) => hasher.update(d));
   return hasher.digest();
 }
-
-/**
- * Computes the Type ID hash of the given data.
- * @public
- *
- * @param cellInputLike - The first cell input of the transaction.
- * @param outputIndex - The output index of the Type ID cell.
- * @returns The hexadecimal string representation of the hash.
- *
- * @example
- * ```typescript
- * const hash = hashTypeId(cellInput, outputIndex); // Outputs something like "0x..."
- * ```
- */
-
-export function hashTypeId(
-  cellInputLike: CellInputLike,
-  outputIndex: NumLike,
-): Hex {
-  return hashCkb(
-    CellInput.from(cellInputLike).toBytes(),
-    numLeToBytes(outputIndex, 8),
-  );
-}

package/src/molecule/codec.ts

@@ -459,34 +459,71 @@ type UnionDecoded<
   : never;
 
 /**
- * Union is a dynamic-size type.
- * Serializing a union has two steps:
- * - Serialize an item type id in bytes as a 32 bit unsigned integer in little-endian. The item type id is the index of the inner items, and it's starting at 0.
- * - Serialize the inner item.
- * @param codecLayout the union item record
- * @param fields the custom item type id record
+ * Constructs a union codec that can serialize and deserialize values tagged with a type identifier.
+ *
+ * If all variants have the same fixed size, the resulting union codec is fixed-size (header + payload).
+ * Otherwise, it falls back to a dynamic-size codec.
+ *
+ * Serialization format:
+ * 1. 4-byte little-endian unsigned integer for the variant index.
+ * 2. Encoded bytes of the selected variant.
+ *
+ * @typeParam T
+ *   A record mapping variant names to codecs.
+ * @param codecLayout
+ *   An object whose keys are variant names and values are codecs for each variant.
+ * @param fields
+ *   Optional mapping from variant names to custom numeric IDs. If omitted, the index
+ *   of each variant in `codecLayout` is used as its ID.
+ *
+ *
  * @example
- * // without custom id
- * union({ cafe: Uint8, bee: Uint8 })
- * // with custom id
- * union({ cafe: Uint8, bee: Uint8 }, { cafe: 0xcafe, bee: 0xbee })
+ * // Dynamic union without custom numeric IDs
+ * union({ cafe: Uint8, bee: Uint16 })
+ *
+ * // Dynamic union with custom numeric IDs
+ * union({ cafe: Uint8, bee: Uint16 }, { cafe: 0xcafe, bee: 0xbee })
+ *
+ * // Fixed-size union without custom numeric IDs
+ * const PaddedUint8 = struct({ data : u8, padding : u8 })
+ * union({ cafe: PaddedUint8, bee: Uint16 });
+ *
+ * // Fixed-size union with custom numeric IDs
+ * union({ cafe: PaddedUint8, bee: Uint16 }, { cafe: 0xcafe, bee: 0xbee })
  */
+
 export function union<T extends Record<string, CodecLike<any, any>>>(
   codecLayout: T,
   fields?: Record<keyof T, number | undefined | null>,
 ): Codec<UnionEncodable<T>, UnionDecoded<T>> {
-  const keys = Object.keys(codecLayout);
+  const entries = Object.entries(codecLayout);
+
+  // Determine if all variants have a fixed and equal byteLength.
+  let byteLength: number | undefined;
+  if (entries.length > 0) {
+    const firstLen = entries[0][1].byteLength;
+    if (
+      firstLen !== undefined &&
+      entries.every(([, { byteLength: len }]) => len === firstLen)
+    ) {
+      // Add 4 bytes for the type header
+      byteLength = firstLen + 4;
+    }
+  }
 
   return Codec.from({
+    byteLength,
     encode({ type, value }) {
       const typeStr = type.toString();
       const codec = codecLayout[typeStr];
       if (!codec) {
         throw new Error(
-          `union: invalid type, expected ${keys.toString()}, but got ${typeStr}`,
+          `union: invalid type, expected ${entries.map((e) => e[0]).toString()}, but got ${typeStr}`,
         );
       }
-      const fieldId = fields ? (fields[typeStr] ?? -1) : keys.indexOf(typeStr);
+      const fieldId = fields
+        ? (fields[typeStr] ?? -1)
+        : entries.findIndex((e) => e[0] === typeStr);
       if (fieldId < 0) {
         throw new Error(`union: invalid field id ${fieldId} of ${typeStr}`);
       }

package/src/signer/ckb/signerCkbScriptReadonly.ts

@@ -4,31 +4,46 @@ import { Client } from "../../client/index.js";
 import { Signer, SignerSignType, SignerType } from "../signer/index.js";
 
 /**
- * A class extending Signer that provides read-only access to a CKB script.
- * This class does not support signing operations.
+ * A read-only signer for a CKB script. It can be used to get addresses,
+ * but not to sign transactions. This is useful when you want to watch an address
+ * without having the private key.
+ *
  * @public
  */
 export class SignerCkbScriptReadonly extends Signer {
+  /**
+   * The type of the signer.
+   */
   get type(): SignerType {
     return SignerType.CKB;
   }
 
+  /**
+   * The sign type of the signer.
+   * As this is a read-only signer, the sign type is {@link SignerSignType.Unknown}.
+   */
   get signType(): SignerSignType {
     return SignerSignType.Unknown;
   }
 
-  private readonly script: Script;
+  /**
+   * The scripts associated with the signer.
+   */
+  public readonly scripts: Script[];
 
   /**
    * Creates an instance of SignerCkbScriptReadonly.
    *
    * @param client - The client instance used for communication.
-   * @param script - The script associated with the signer.
+   * @param scripts - The scripts associated with the signer. Can be a single script, an array of scripts, or multiple script arguments.
    */
-  constructor(client: Client, script: ScriptLike) {
+  constructor(client: Client, ...scripts: (ScriptLike | ScriptLike[])[]) {
     super(client);
 
-    this.script = Script.from(script);
+    this.scripts = scripts.flat().map(Script.from);
+    if (this.scripts.length === 0) {
+      throw new Error("SignerCkbScriptReadonly requires at least one script.");
+    }
   }
 
   /**
@@ -71,8 +86,9 @@ export class SignerCkbScriptReadonly extends Signer {
    * const addressObjs = await signer.getAddressObjs(); // Outputs the array of Address objects
    * ```
    */
-
   async getAddressObjs(): Promise<Address[]> {
-    return [Address.fromScript(this.script, this.client)];
+    return this.scripts.map((script) =>
+      Address.fromScript(script, this.client),
+    );
   }
 }

package/src/signer/signer/index.ts

@@ -6,6 +6,7 @@ import {
   Client,
   ClientFindTransactionsGroupedResponse,
   ClientFindTransactionsResponse,
+  ClientIndexerSearchKeyFilterLike,
 } from "../../client/index.js";
 import { Hex } from "../../hex/index.js";
 import { Num } from "../../num/index.js";
@@ -239,6 +240,39 @@ export abstract class Signer {
     );
   }
 
+  /**
+   * Find cells of this signer
+   *
+   * @param filter - The filter for the search key.
+   * @param withData - Whether to include cell data in the response.
+   * @param order - The order of the returned cells, can be "asc" or "desc".
+   * @param limit - The maximum number of cells for every querying chunk.
+   * @returns A async generator that yields all matching cells
+   */
+  async *findCellsOnChain(
+    filter: ClientIndexerSearchKeyFilterLike,
+    withData?: boolean | null,
+    order?: "asc" | "desc",
+    limit?: number,
+  ): AsyncGenerator<Cell> {
+    const scripts = await this.getAddressObjs();
+    for (const { script } of scripts) {
+      for await (const cell of this.client.findCellsOnChain(
+        {
+          script,
+          scriptType: "lock",
+          filter,
+          scriptSearchMode: "exact",
+          withData,
+        },
+        order,
+        limit,
+      )) {
+        yield cell;
+      }
+    }
+  }
+
   /**
    * Find cells of this signer
    *