@ckb-ccc/core 1.5.0 → 1.6.0

package/src/ckb/transaction.ts

@@ -229,8 +229,12 @@ export const CellOutputVec = mol.vector(CellOutput);
 /**
  * @public
  */
-export type CellLike = {
-  outPoint: OutPointLike;
+export type CellLike = (
+  | {
+      outPoint: OutPointLike;
+    }
+  | { previousOutput: OutPointLike }
+) & {
   cellOutput: CellOutputLike;
   outputData: HexLike;
 };
@@ -265,7 +269,7 @@ export class Cell {
     }
 
     return new Cell(
-      OutPoint.from(cell.outPoint),
+      OutPoint.from("outPoint" in cell ? cell.outPoint : cell.previousOutput),
       CellOutput.from(cell.cellOutput),
       hexFrom(cell.outputData),
     );
@@ -450,8 +454,12 @@ export class Since extends mol.Entity.Base<SinceLike, Since>() {
 /**
  * @public
  */
-export type CellInputLike = {
-  previousOutput: OutPointLike;
+export type CellInputLike = (
+  | {
+      previousOutput: OutPointLike;
+    }
+  | { outPoint: OutPointLike }
+) & {
   since?: SinceLike | NumLike | null;
   cellOutput?: CellOutputLike | null;
   outputData?: HexLike | null;
@@ -465,10 +473,7 @@ export type CellInputLike = {
       since: Since,
       previousOutput: OutPoint,
     })
-    .mapIn((encodable: CellInputLike) => ({
-      ...encodable,
-      since: encodable.since ?? 0,
-    })),
+    .mapIn((encodable: CellInputLike) => CellInput.from(encodable)),
 )
 export class CellInput extends mol.Entity.Base<CellInputLike, CellInput>() {
   /**
@@ -509,7 +514,11 @@ export class CellInput extends mol.Entity.Base<CellInputLike, CellInput>() {
     }
 
     return new CellInput(
-      OutPoint.from(cellInput.previousOutput),
+      OutPoint.from(
+        "previousOutput" in cellInput
+          ? cellInput.previousOutput
+          : cellInput.outPoint,
+      ),
       Since.from(cellInput.since ?? 0).toNum(),
       apply(CellOutput.from, cellInput.cellOutput),
       apply(hexFrom, cellInput.outputData),
@@ -539,6 +548,14 @@ export class CellInput extends mol.Entity.Base<CellInputLike, CellInput>() {
     this.cellOutput = cell.cellOutput;
     this.outputData = cell.outputData;
   }
+
+  clone(): CellInput {
+    const cloned = super.clone();
+    cloned.cellOutput = this.cellOutput;
+    cloned.outputData = this.outputData;
+
+    return cloned;
+  }
 }
 export const CellInputVec = mol.vector(CellInput);
 
@@ -891,6 +908,11 @@ export class Transaction extends mol.Entity.Base<
     });
   }
 
+  /**
+   * @deprecated
+   * Use ccc.stringify instead.
+   * stringify the tx to JSON string.
+   */
   stringify(): string {
     return JSON.stringify(this, (_, value) => {
       if (typeof value === "bigint") {
@@ -1230,6 +1252,58 @@ export class Transaction extends mol.Entity.Base<
     this.outputsData[index] = hexFrom(witness);
   }
 
+  /**
+   * get input
+   *
+   * @param index - The cell input index
+   *
+   * @example
+   * ```typescript
+   * await tx.getInput(0);
+   * ```
+   */
+  getInput(index: NumLike): CellInput | undefined {
+    return this.inputs[Number(numFrom(index))];
+  }
+  /**
+   * add input
+   *
+   * @param inputLike - The cell input.
+   *
+   * @example
+   * ```typescript
+   * await tx.addInput({ });
+   * ```
+   */
+  addInput(inputLike: CellInputLike): number {
+    return this.inputs.push(CellInput.from(inputLike));
+  }
+
+  /**
+   * get output
+   *
+   * @param index - The cell output index
+   *
+   * @example
+   * ```typescript
+   * await tx.getOutput(0);
+   * ```
+   */
+  getOutput(index: NumLike):
+    | {
+        cellOutput: CellOutput;
+        outputData: Hex;
+      }
+    | undefined {
+    const i = Number(numFrom(index));
+    if (i >= this.outputs.length) {
+      return;
+    }
+    return {
+      cellOutput: this.outputs[i],
+      outputData: this.outputsData[i] ?? "0x",
+    };
+  }
   /**
    * Add output
    *
@@ -1245,7 +1319,7 @@ export class Transaction extends mol.Entity.Base<
     outputLike: Omit<CellOutputLike, "capacity"> &
       Partial<Pick<CellOutputLike, "capacity">>,
     outputData: HexLike = "0x",
-  ): void {
+  ): number {
     const output = CellOutput.from({
       ...outputLike,
       capacity: outputLike.capacity ?? 0,
@@ -1255,8 +1329,10 @@ export class Transaction extends mol.Entity.Base<
         output.occupiedSize + bytesFrom(outputData).length,
       );
     }
-    const i = this.outputs.push(output) - 1;
-    this.setOutputDataAt(i, outputData);
+    const len = this.outputs.push(output);
+    this.setOutputDataAt(len - 1, outputData);
+
+    return len;
   }
 
   /**
@@ -1415,15 +1491,7 @@ export class Transaction extends mol.Entity.Base<
       acc = next;
     }
 
-    this.inputs.push(
-      ...collectedCells.map(({ outPoint, outputData, cellOutput }) =>
-        CellInput.from({
-          previousOutput: outPoint,
-          outputData,
-          cellOutput,
-        }),
-      ),
-    );
+    collectedCells.forEach((cell) => this.addInput(cell));
     if (fulfilled) {
       return {
         addedCount: collectedCells.length,
@@ -1543,13 +1611,7 @@ export class Transaction extends mol.Entity.Base<
         continue;
       }
 
-      this.inputs.push(
-        CellInput.from({
-          previousOutput: cell.outPoint,
-          outputData: cell.outputData,
-          cellOutput: cell.cellOutput,
-        }),
-      );
+      this.addInput(cell);
       return 1;
     }
 
@@ -1567,9 +1629,21 @@ export class Transaction extends mol.Entity.Base<
     return this.completeInputsAddOne(from, filter);
   }
 
+  async fee(client: Client): Promise<Num> {
+    return (await this.getInputsCapacity(client)) - this.getOutputsCapacity();
+  }
+
+  async feeRate(client: Client): Promise<Num> {
+    return (
+      ((await this.fee(client)) * numFrom(1000)) /
+      numFrom(this.toBytes().length + 4)
+    );
+  }
+
   estimateFee(feeRate: NumLike): Num {
     const txSize = this.toBytes().length + 4;
-    return (numFrom(txSize) * numFrom(feeRate) + numFrom(1000)) / numFrom(1000);
+    // + 999 then / 1000 to ceil the calculated fee
+    return (numFrom(txSize) * numFrom(feeRate) + numFrom(999)) / numFrom(1000);
   }
 
   async completeFee(
@@ -1577,8 +1651,11 @@ export class Transaction extends mol.Entity.Base<
     change: (tx: Transaction, capacity: Num) => Promise<NumLike> | NumLike,
     expectedFeeRate?: NumLike,
     filter?: ClientCollectableSearchKeyFilterLike,
+    options?: { feeRateBlockRange?: NumLike; maxFeeRate?: NumLike },
   ): Promise<[number, boolean]> {
-    const feeRate = expectedFeeRate ?? (await from.client.getFeeRate());
+    const feeRate =
+      expectedFeeRate ??
+      (await from.client.getFeeRate(options?.feeRateBlockRange, options));
 
     // Complete all inputs extra infos for cache
     await this.getInputsCapacity(from.client);
@@ -1609,27 +1686,21 @@ export class Transaction extends mol.Entity.Base<
         // The initial fee is calculated based on prepared transaction
         leastFee = tx.estimateFee(feeRate);
       }
-      const extraCapacity =
-        (await tx.getInputsCapacity(from.client)) - tx.getOutputsCapacity();
+      const fee = await tx.fee(from.client);
       // The extra capacity paid the fee without a change
-      if (extraCapacity === leastFee) {
+      if (fee === leastFee) {
         this.copy(tx);
         return [collected, false];
       }
 
-      const needed = numFrom(
-        await Promise.resolve(change(tx, extraCapacity - leastFee)),
-      );
+      const needed = numFrom(await Promise.resolve(change(tx, fee - leastFee)));
       // No enough extra capacity to create new cells for change
       if (needed > Zero) {
         leastExtraCapacity = needed;
         continue;
       }
 
-      if (
-        (await tx.getInputsCapacity(from.client)) - tx.getOutputsCapacity() !==
-        leastFee
-      ) {
+      if ((await tx.fee(from.client)) !== leastFee) {
         throw new Error(
           "The change function doesn't use all available capacity",
         );

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);
+  }
 }