@ckb-ccc/core 1.5.3 → 1.7.0

package/src/client/cache/cache.ts

@@ -6,10 +6,31 @@ import {
   TransactionLike,
 } from "../../ckb/index.js";
 import { HexLike } from "../../hex/index.js";
+import { NumLike } from "../../num/index.js";
 import { ClientCollectableSearchKeyLike } from "../clientTypes.advanced.js";
+import {
+  ClientBlock,
+  ClientBlockHeader,
+  ClientBlockHeaderLike,
+  ClientBlockLike,
+  ClientTransactionResponse,
+  ClientTransactionResponseLike,
+} from "../clientTypes.js";
 
+/**
+ * @public
+ * The ClientCache class is mainly designed for chained transactions.
+ * Consumed & Created cells are "marked" so they can be correctly handled when composing transactions.
+ * It also act as cache for rpc requests to reduce cost, but this is optional.
+ */
 export abstract class ClientCache {
-  abstract markUsable(...cellLikes: (CellLike | CellLike[])[]): Promise<void>;
+  abstract markUsableNoCache(
+    ...cellLikes: (CellLike | CellLike[])[]
+  ): Promise<void>;
+  async markUsable(...cellLikes: (CellLike | CellLike[])[]): Promise<void> {
+    await this.recordCells(...cellLikes);
+    return this.markUsableNoCache(...cellLikes);
+  }
   abstract markUnusable(
     ...outPointLike: (OutPointLike | OutPointLike[])[]
   ): Promise<void>;
@@ -17,7 +38,12 @@ export abstract class ClientCache {
     ...transactionLike: (TransactionLike | TransactionLike[])[]
   ): Promise<void> {
     await Promise.all([
-      this.recordTransactions(...transactionLike),
+      this.recordTransactionResponses(
+        transactionLike.flat().map((transaction) => ({
+          transaction: transaction,
+          status: "sent",
+        })),
+      ),
       ...transactionLike.flat().map((transactionLike) => {
         const tx = Transaction.from(transactionLike);
         const txHash = tx.hash();
@@ -42,34 +68,121 @@ export abstract class ClientCache {
   abstract findCells(
     filter: ClientCollectableSearchKeyLike,
   ): AsyncGenerator<Cell>;
+  abstract isUnusable(outPointLike: OutPointLike): Promise<boolean>;
+
+  // ======
+  // Following methods are for requests caching and optional.
+  // ======
+
+  /**
+   * Record known cells
+   * Implement this method to enable cells query caching
+   * @param _cells
+   */
+  async recordCells(..._cells: (CellLike | CellLike[])[]): Promise<void> {}
   /**
    * Get a known cell by out point
+   * Implement this method to enable cells query caching
    * @param _outPoint
    */
-  abstract getCell(_outPoint: OutPointLike): Promise<Cell | undefined>;
-  abstract isUnusable(outPointLike: OutPointLike): Promise<boolean>;
+  async getCell(_outPoint: OutPointLike): Promise<Cell | undefined> {
+    return;
+  }
 
   /**
-   * Record known transactions
+   * Record known transaction responses.
    * Implement this method to enable transactions query caching
    * @param _transactions
    */
-  async recordTransactions(
-    ..._transactions: (TransactionLike | TransactionLike[])[]
+  async recordTransactionResponses(
+    ..._transactions: (
+      | ClientTransactionResponseLike
+      | ClientTransactionResponseLike[]
+    )[]
   ): Promise<void> {}
   /**
-   * Get a known transaction by hash
+   * Get a known transaction response by hash
    * Implement this method to enable transactions query caching
    * @param _txHash
    */
-  async getTransaction(_txHash: HexLike): Promise<Transaction | undefined> {
+  async getTransactionResponse(
+    _txHash: HexLike,
+  ): Promise<ClientTransactionResponse | undefined> {
+    return;
+  }
+  /**
+   * Record known transactions.
+   * @param transactions
+   */
+  async recordTransactions(
+    ...transactions: (TransactionLike | TransactionLike[])[]
+  ): Promise<void> {
+    return this.recordTransactionResponses(
+      transactions.flat().map((transaction) => ({
+        transaction,
+        status: "unknown",
+      })),
+    );
+  }
+  /**
+   * Get a known transaction by hash
+   * @param txHash
+   */
+  async getTransaction(txHash: HexLike): Promise<Transaction | undefined> {
+    return (await this.getTransactionResponse(txHash))?.transaction;
+  }
+
+  /**
+   * Record known block headers.
+   * Implement this method to enable block headers query caching
+   * @param _headers
+   */
+  async recordHeaders(
+    ..._headers: (ClientBlockHeaderLike | ClientBlockHeaderLike[])[]
+  ): Promise<void> {}
+  /**
+   * Get a known block header by hash
+   * Implement this method to enable block headers query caching
+   * @param _hash
+   */
+  async getHeaderByHash(
+    _hash: HexLike,
+  ): Promise<ClientBlockHeader | undefined> {
+    return;
+  }
+  /**
+   * Get a known block header by number
+   * Implement this method to enable block headers query caching
+   * @param _number
+   */
+  async getHeaderByNumber(
+    _number: NumLike,
+  ): Promise<ClientBlockHeader | undefined> {
     return;
   }
 
   /**
-   * Record known cells
-   * Implement this method to enable cells query caching
-   * @param _cells
+   * Record known blocks.
+   * Implement this method to enable blocks query caching
+   * @param _blocks
    */
-  async recordCells(..._cells: (CellLike | CellLike[])[]): Promise<void> {}
+  async recordBlocks(
+    ..._blocks: (ClientBlockLike | ClientBlockLike[])[]
+  ): Promise<void> {}
+  /**
+   * Get a known block header by hash
+   * Implement this method to enable block headers query caching
+   * @param _hash
+   */
+  async getBlockByHash(_hash: HexLike): Promise<ClientBlock | undefined> {
+    return;
+  }
+  /**
+   * Get a known block header by number
+   * Implement this method to enable block headers query caching
+   * @param _number
+   */
+  async getBlockByNumber(_number: NumLike): Promise<ClientBlock | undefined> {
+    return;
+  }
 }

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

@@ -149,7 +149,12 @@ export class MapLru<K, V> extends Map<K, V> {
     super();
   }
 
-  access(key: K) {
+  get(key: K) {
+    const val = super.get(key);
+    if (val === undefined) {
+      return;
+    }
+
     const index = this.lru.indexOf(key);
     if (index !== -1) {
       this.lru.splice(index, 1);
@@ -159,15 +164,27 @@ export class MapLru<K, V> extends Map<K, V> {
       this.delete(this.lru[0]);
       this.lru.shift();
     }
-  }
 
-  get(key: K) {
-    this.access(key);
-    return super.get(key);
+    return val;
   }
 
   set(key: K, value: V) {
-    this.access(key);
-    return super.set(key, value);
+    this.get(key);
+
+    super.set(key, value);
+    return this;
+  }
+
+  delete(key: K): boolean {
+    if (!super.delete(key)) {
+      return false;
+    }
+
+    const index = this.lru.indexOf(key);
+    if (index !== -1) {
+      this.lru.splice(index, 1);
+    }
+
+    return true;
   }
 }

package/src/client/cache/memory.ts

@@ -1,13 +1,15 @@
-import {
-  Cell,
-  CellLike,
-  OutPoint,
-  OutPointLike,
-  Transaction,
-  TransactionLike,
-} from "../../ckb/index.js";
+import { Cell, CellLike, OutPoint, OutPointLike } from "../../ckb/index.js";
 import { hexFrom, HexLike } from "../../hex/index.js";
+import { Num, numFrom, NumLike } from "../../num/index.js";
 import { ClientCollectableSearchKeyLike } from "../clientTypes.advanced.js";
+import {
+  ClientBlock,
+  ClientBlockHeader,
+  ClientBlockHeaderLike,
+  ClientBlockLike,
+  ClientTransactionResponse,
+  ClientTransactionResponseLike,
+} from "../clientTypes.js";
 import { ClientCache } from "./cache.js";
 import { CellRecord, filterCell, MapLru } from "./memory.advanced.js";
 
@@ -18,21 +20,44 @@ export class ClientCacheMemory extends ClientCache {
   private readonly cells: MapLru<string, CellRecord>;
 
   /**
-   * TX Hash => Transaction
+   * TX Hash => Transaction Response
+   */
+  private readonly knownTransactions: MapLru<string, ClientTransactionResponse>;
+
+  /**
+   * Block Number => Block Hash
+   */
+  private readonly knownBlockHashes: MapLru<Num, string>;
+
+  /**
+   * Block Hash => Block Header / Full Block
    */
-  private readonly knownTransactions: MapLru<string, Transaction>;
+  private readonly knownBlocks: MapLru<
+    string,
+    Pick<ClientBlock, "header"> | ClientBlock
+  >;
 
   constructor(
     private readonly maxCells = 512,
     private readonly maxTxs = 256,
+    private readonly maxBlocks = 128,
   ) {
     super();
 
     this.cells = new MapLru<string, CellRecord>(this.maxCells);
-    this.knownTransactions = new MapLru<string, Transaction>(this.maxTxs);
+    this.knownTransactions = new MapLru<string, ClientTransactionResponse>(
+      this.maxTxs,
+    );
+    this.knownBlockHashes = new MapLru<Num, string>(this.maxBlocks);
+    this.knownBlocks = new MapLru<
+      string,
+      Pick<ClientBlock, "header"> | ClientBlock
+    >(this.maxBlocks);
   }
 
-  async markUsable(...cellLikes: (CellLike | CellLike[])[]): Promise<void> {
+  async markUsableNoCache(
+    ...cellLikes: (CellLike | CellLike[])[]
+  ): Promise<void> {
     cellLikes.flat().forEach((cellLike) => {
       const cell = Cell.from(cellLike).clone();
       const outPointStr = hexFrom(cell.outPoint.toBytes());
@@ -73,10 +98,28 @@ export class ClientCacheMemory extends ClientCache {
         continue;
       }
 
-      this.cells.access(key);
+      this.cells.get(key);
       yield cell.clone();
     }
   }
+
+  async isUnusable(outPointLike: OutPointLike): Promise<boolean> {
+    const outPoint = OutPoint.from(outPointLike);
+
+    return !(this.cells.get(hexFrom(outPoint.toBytes()))?.[0] ?? true);
+  }
+
+  async recordCells(...cells: (CellLike | CellLike[])[]): Promise<void> {
+    cells.flat().map((cellLike) => {
+      const cell = Cell.from(cellLike);
+      const outPointStr = hexFrom(cell.outPoint.toBytes());
+
+      if (this.cells.get(outPointStr)) {
+        return;
+      }
+      this.cells.set(outPointStr, [undefined, cell]);
+    });
+  }
   async getCell(outPointLike: OutPointLike): Promise<Cell | undefined> {
     const outPoint = OutPoint.from(outPointLike);
 
@@ -86,34 +129,91 @@ export class ClientCacheMemory extends ClientCache {
     }
   }
 
-  async isUnusable(outPointLike: OutPointLike): Promise<boolean> {
-    const outPoint = OutPoint.from(outPointLike);
-
-    return !(this.cells.get(hexFrom(outPoint.toBytes()))?.[0] ?? true);
-  }
-
-  async recordTransactions(
-    ...transactions: (TransactionLike | TransactionLike[])[]
+  async recordTransactionResponses(
+    ...transactions: (
+      | ClientTransactionResponseLike
+      | ClientTransactionResponseLike[]
+    )[]
   ): Promise<void> {
     transactions.flat().map((txLike) => {
-      const tx = Transaction.from(txLike);
-      this.knownTransactions.set(tx.hash(), tx);
+      const tx = ClientTransactionResponse.from(txLike);
+      this.knownTransactions.set(tx.transaction.hash(), tx);
     });
   }
-  async getTransaction(txHashLike: HexLike): Promise<Transaction | undefined> {
+  async getTransactionResponse(
+    txHashLike: HexLike,
+  ): Promise<ClientTransactionResponse | undefined> {
     const txHash = hexFrom(txHashLike);
     return this.knownTransactions.get(txHash)?.clone();
   }
 
-  async recordCells(...cells: (CellLike | CellLike[])[]): Promise<void> {
-    cells.flat().map((cellLike) => {
-      const cell = Cell.from(cellLike);
-      const outPointStr = hexFrom(cell.outPoint.toBytes());
+  async recordHeaders(
+    ...headers: (ClientBlockHeaderLike | ClientBlockHeaderLike[])[]
+  ): Promise<void> {
+    headers.flat().map((headerLike) => {
+      const header = ClientBlockHeader.from(headerLike);
 
-      if (this.cells.get(outPointStr)) {
+      this.knownBlockHashes.set(header.number, header.hash);
+
+      const existed = this.knownBlocks.get(header.hash);
+      if (existed) {
         return;
       }
-      this.cells.set(outPointStr, [undefined, cell]);
+      this.knownBlocks.set(header.hash, { header });
     });
   }
+  async getHeaderByHash(
+    hashLike: HexLike,
+  ): Promise<ClientBlockHeader | undefined> {
+    const hash = hexFrom(hashLike);
+    const block = this.knownBlocks.get(hash);
+    if (block) {
+      this.knownBlockHashes.get(block.header.number); // For LRU
+    }
+    return block?.header;
+  }
+  async getHeaderByNumber(
+    numberLike: NumLike,
+  ): Promise<ClientBlockHeader | undefined> {
+    const number = numFrom(numberLike);
+
+    const hash = this.knownBlockHashes.get(number);
+    if (!hash) {
+      return;
+    }
+    return this.getHeaderByHash(hash);
+  }
+
+  async recordBlocks(
+    ...blocks: (ClientBlockLike | ClientBlockLike[])[]
+  ): Promise<void> {
+    blocks.flat().map((blockLike) => {
+      const block = ClientBlock.from(blockLike);
+
+      this.knownBlockHashes.set(block.header.number, block.header.hash);
+      this.knownBlocks.set(block.header.hash, block);
+    });
+  }
+  async getBlockByHash(hashLike: HexLike): Promise<ClientBlock | undefined> {
+    const hash = hexFrom(hashLike);
+    const block = this.knownBlocks.get(hash);
+    if (block) {
+      this.knownBlockHashes.get(block.header.number); // For LRU
+      if ("transactions" in block) {
+        return block;
+      }
+    }
+    return;
+  }
+  async getBlockByNumber(
+    numberLike: NumLike,
+  ): Promise<ClientBlock | undefined> {
+    const number = numFrom(numberLike);
+
+    const hash = this.knownBlockHashes.get(number);
+    if (!hash) {
+      return;
+    }
+    return this.getBlockByHash(hash);
+  }
 }