@ckb-ccc/core 1.5.0 → 1.6.0

package/src/client/client.ts

@@ -9,11 +9,16 @@ import {
 } from "../ckb/index.js";
 import { Zero } from "../fixedPoint/index.js";
 import { Hex, HexLike, hexFrom } from "../hex/index.js";
-import { Num, NumLike, numFrom, numMax } from "../num/index.js";
+import { Num, NumLike, numFrom, numMax, numMin } from "../num/index.js";
 import { reduceAsync, sleep } from "../utils/index.js";
 import { ClientCache } from "./cache/index.js";
 import { ClientCacheMemory } from "./cache/memory.js";
-import { ClientCollectableSearchKeyLike } from "./clientTypes.advanced.js";
+import {
+  CONFIRMED_BLOCK_TIME,
+  ClientCollectableSearchKeyLike,
+  DEFAULT_MAX_FEE_RATE,
+  DEFAULT_MIN_FEE_RATE,
+} from "./clientTypes.advanced.js";
 import {
   CellDepInfo,
   CellDepInfoLike,
@@ -26,12 +31,17 @@ import {
   ClientIndexerSearchKeyLike,
   ClientIndexerSearchKeyTransactionLike,
   ClientTransactionResponse,
+  ErrorClientMaxFeeRateExceeded,
   ErrorClientWaitTransactionTimeout,
   KnownScript,
   OutputsValidator,
   ScriptInfo,
 } from "./clientTypes.js";
 
+function hasHeaderConfirmed(header: ClientBlockHeader): boolean {
+  return numFrom(Date.now()) - header.timestamp >= CONFIRMED_BLOCK_TIME;
+}
+
 /**
  * @public
  */
@@ -50,30 +60,113 @@ export abstract class Client {
   abstract getFeeRateStatistics(
     blockRange?: NumLike,
   ): Promise<{ mean: Num; median: Num }>;
-  async getFeeRate(blockRange?: NumLike): Promise<Num> {
-    return numMax((await this.getFeeRateStatistics(blockRange)).median, 1000);
+  async getFeeRate(
+    blockRange?: NumLike,
+    options?: { maxFeeRate?: NumLike },
+  ): Promise<Num> {
+    const feeRate = numMax(
+      (await this.getFeeRateStatistics(blockRange)).median,
+      DEFAULT_MIN_FEE_RATE,
+    );
+
+    const maxFeeRate = numFrom(options?.maxFeeRate ?? DEFAULT_MAX_FEE_RATE);
+    if (maxFeeRate === Zero) {
+      return feeRate;
+    }
+
+    return numMin(feeRate, maxFeeRate);
   }
 
   abstract getTip(): Promise<Num>;
   abstract getTipHeader(verbosity?: number | null): Promise<ClientBlockHeader>;
-  abstract getBlockByNumber(
+  abstract getBlockByNumberNoCache(
     blockNumber: NumLike,
     verbosity?: number | null,
     withCycles?: boolean | null,
   ): Promise<ClientBlock | undefined>;
-  abstract getBlockByHash(
+  abstract getBlockByHashNoCache(
     blockHash: HexLike,
     verbosity?: number | null,
     withCycles?: boolean | null,
   ): Promise<ClientBlock | undefined>;
-  abstract getHeaderByNumber(
+  abstract getHeaderByNumberNoCache(
     blockNumber: NumLike,
     verbosity?: number | null,
   ): Promise<ClientBlockHeader | undefined>;
-  abstract getHeaderByHash(
+  abstract getHeaderByHashNoCache(
     blockHash: HexLike,
     verbosity?: number | null,
   ): Promise<ClientBlockHeader | undefined>;
+  async getBlockByNumber(
+    blockNumber: NumLike,
+    verbosity?: number | null,
+    withCycles?: boolean | null,
+  ): Promise<ClientBlock | undefined> {
+    const block = await this.cache.getBlockByNumber(blockNumber);
+    if (block) {
+      return block;
+    }
+
+    const res = await this.getBlockByNumberNoCache(
+      blockNumber,
+      verbosity,
+      withCycles,
+    );
+    if (res && hasHeaderConfirmed(res.header)) {
+      await this.cache.recordBlocks(res);
+    }
+    return res;
+  }
+  async getBlockByHash(
+    blockHash: HexLike,
+    verbosity?: number | null,
+    withCycles?: boolean | null,
+  ): Promise<ClientBlock | undefined> {
+    const block = await this.cache.getBlockByHash(blockHash);
+    if (block) {
+      return block;
+    }
+
+    const res = await this.getBlockByHashNoCache(
+      blockHash,
+      verbosity,
+      withCycles,
+    );
+    if (res && hasHeaderConfirmed(res.header)) {
+      await this.cache.recordBlocks(res);
+    }
+    return res;
+  }
+  async getHeaderByNumber(
+    blockNumber: NumLike,
+    verbosity?: number | null,
+  ): Promise<ClientBlockHeader | undefined> {
+    const header = await this.cache.getHeaderByNumber(blockNumber);
+    if (header) {
+      return header;
+    }
+
+    const res = await this.getHeaderByNumberNoCache(blockNumber, verbosity);
+    if (res && hasHeaderConfirmed(res)) {
+      await this.cache.recordHeaders(res);
+    }
+    return res;
+  }
+  async getHeaderByHash(
+    blockHash: HexLike,
+    verbosity?: number | null,
+  ): Promise<ClientBlockHeader | undefined> {
+    const header = await this.cache.getHeaderByHash(blockHash);
+    if (header) {
+      return header;
+    }
+
+    const res = await this.getHeaderByHashNoCache(blockHash, verbosity);
+    if (res && hasHeaderConfirmed(res)) {
+      await this.cache.recordHeaders(res);
+    }
+    return res;
+  }
 
   abstract estimateCycles(transaction: TransactionLike): Promise<Num>;
   abstract sendTransactionDry(
@@ -97,25 +190,47 @@ export abstract class Client {
       return cached;
     }
 
-    const transaction = await this.getTransactionNoCache(outPoint.txHash);
+    const transaction = await this.getTransaction(outPoint.txHash);
     if (!transaction) {
       return;
     }
-
-    const index = Number(numFrom(outPoint.index));
-    if (index >= transaction.transaction.outputs.length) {
+    const output = transaction.transaction.getOutput(outPoint.index);
+    if (!output) {
       return;
     }
 
     const cell = Cell.from({
       outPoint,
-      cellOutput: transaction.transaction.outputs[index],
-      outputData: transaction.transaction.outputsData[index] ?? "0x",
+      ...output,
     });
     await this.cache.recordCells(cell);
     return cell;
   }
 
+  async getCellWithHeader(
+    outPointLike: OutPointLike,
+  ): Promise<{ cell: Cell; header?: ClientBlockHeader } | undefined> {
+    const outPoint = OutPoint.from(outPointLike);
+
+    const res = await this.getTransactionWithHeader(outPoint.txHash);
+    if (!res) {
+      return;
+    }
+    const { transaction, header } = res;
+
+    const output = transaction.transaction.getOutput(outPoint.index);
+    if (!output) {
+      return;
+    }
+
+    const cell = Cell.from({
+      outPoint,
+      ...output,
+    });
+    await this.cache.recordCells(cell);
+    return { cell, header };
+  }
+
   abstract getCellLiveNoCache(
     outPointLike: OutPointLike,
     withData?: boolean | null,
@@ -476,14 +591,19 @@ export abstract class Client {
   async sendTransaction(
     transaction: TransactionLike,
     validator?: OutputsValidator,
+    options?: { maxFeeRate?: NumLike },
   ): Promise<Hex> {
     const tx = Transaction.from(transaction);
 
+    const maxFeeRate = numFrom(options?.maxFeeRate ?? DEFAULT_MAX_FEE_RATE);
+    const fee = await tx.feeRate(this);
+    if (maxFeeRate > Zero && fee > maxFeeRate) {
+      throw new ErrorClientMaxFeeRateExceeded(maxFeeRate, fee);
+    }
+
     const txHash = await this.sendTransactionNoCache(tx, validator);
 
-    await this.cache.recordTransactions(tx);
     await this.cache.markTransactions(tx);
-
     return txHash;
   }
 
@@ -492,25 +612,48 @@ export abstract class Client {
   ): Promise<ClientTransactionResponse | undefined> {
     const txHash = hexFrom(txHashLike);
     const res = await this.getTransactionNoCache(txHash);
-    if (res?.transaction) {
+    if (res) {
+      await this.cache.recordTransactionResponses(res);
       return res;
     }
 
-    const tx = await this.cache.getTransaction(txHash);
-    if (!tx) {
-      return;
+    return this.cache.getTransactionResponse(txHash);
+  }
+
+  /**
+   * This method gets specified transaction with its block header (if existed).
+   * This is mainly for caching because we need the header to test if we can safely trust the cached tx status.
+   * @param txHashLike
+   */
+  async getTransactionWithHeader(
+    txHashLike: HexLike,
+  ): Promise<
+    | { transaction: ClientTransactionResponse; header?: ClientBlockHeader }
+    | undefined
+  > {
+    const txHash = hexFrom(txHashLike);
+    const tx = await this.cache.getTransactionResponse(txHash);
+    if (tx?.blockHash) {
+      const header = await this.getHeaderByHash(tx.blockHash);
+      if (header && hasHeaderConfirmed(header)) {
+        return {
+          transaction: tx,
+          header,
+        };
+      }
     }
 
+    const res = await this.getTransactionNoCache(txHash);
     if (!res) {
-      return {
-        transaction: tx,
-        status: "sent",
-      };
+      return;
     }
 
+    await this.cache.recordTransactionResponses(res);
     return {
-      ...res,
-      transaction: tx,
+      transaction: res,
+      header: res.blockHash
+        ? await this.getHeaderByHash(res.blockHash)
+        : undefined,
     };
   }
 
@@ -552,7 +695,7 @@ export abstract class Client {
       }
 
       if (Date.now() - startTime + interval >= timeout) {
-        throw new ErrorClientWaitTransactionTimeout();
+        throw new ErrorClientWaitTransactionTimeout(timeout);
       }
       await sleep(interval);
     }

package/src/client/clientPublicMainnet.ts

@@ -28,13 +28,8 @@ export class ClientPublicMainnet extends ClientJsonRpc {
                 "wss://mainnet.ckb.dev/ws",
                 "https://mainnet.ckb.dev/",
                 "https://mainnet.ckbapp.dev/",
-                "https://rpc.ankr.com/nervos_ckb",
               ]
-            : [
-                "https://mainnet.ckb.dev/",
-                "https://mainnet.ckbapp.dev/",
-                "https://rpc.ankr.com/nervos_ckb",
-              ]),
+            : ["https://mainnet.ckb.dev/", "https://mainnet.ckbapp.dev/"]),
       },
     );
   }

package/src/client/clientTypes.advanced.ts

@@ -2,6 +2,10 @@ 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);
+
 export function clientSearchKeyRangeFrom([a, b]: [NumLike, NumLike]): [
   Num,
   Num,

package/src/client/clientTypes.ts

@@ -3,6 +3,7 @@ import {
   CellDep,
   CellDepLike,
   Epoch,
+  EpochLike,
   HashType,
   HashTypeLike,
   OutPoint,
@@ -10,6 +11,8 @@ import {
   Script,
   ScriptLike,
   Transaction,
+  TransactionLike,
+  epochFrom,
   hashTypeFrom,
 } from "../ckb/index.js";
 import { Hex, HexLike, hexFrom } from "../hex/index.js";
@@ -67,6 +70,10 @@ export class CellDepInfo {
   ) {}
 
   static from(cellDepInfoLike: CellDepInfoLike): CellDepInfo {
+    if (cellDepInfoLike instanceof CellDepInfo) {
+      return cellDepInfoLike;
+    }
+
     return new CellDepInfo(
       CellDep.from(cellDepInfoLike.cellDep),
       apply(Script.from, cellDepInfoLike.type),
@@ -94,6 +101,10 @@ export class ScriptInfo {
   ) {}
 
   static from(scriptInfoLike: ScriptInfoLike): ScriptInfo {
+    if (scriptInfoLike instanceof ScriptInfo) {
+      return scriptInfoLike;
+    }
+
     return new ScriptInfo(
       hexFrom(scriptInfoLike.codeHash),
       hashTypeFrom(scriptInfoLike.hashType),
@@ -120,15 +131,59 @@ export type TransactionStatus =
 /**
  * @public
  */
-export type ClientTransactionResponse = {
-  transaction: Transaction;
+export type ClientTransactionResponseLike = {
+  transaction: TransactionLike;
   status: TransactionStatus;
-  cycles?: Num;
-  blockHash?: Hex;
-  blockNumber?: Num;
-  txIndex?: Num;
+  cycles?: NumLike;
+  blockHash?: HexLike;
+  blockNumber?: NumLike;
+  txIndex?: NumLike;
   reason?: string;
 };
+/**
+ * @public
+ */
+export class ClientTransactionResponse {
+  constructor(
+    public transaction: Transaction,
+    public status: TransactionStatus,
+    public cycles?: Num,
+    public blockHash?: Hex,
+    public blockNumber?: Num,
+    public txIndex?: Num,
+    public reason?: string,
+  ) {}
+
+  static from(
+    responseLike: ClientTransactionResponseLike,
+  ): ClientTransactionResponse {
+    if (responseLike instanceof ClientTransactionResponse) {
+      return responseLike;
+    }
+
+    return new ClientTransactionResponse(
+      Transaction.from(responseLike.transaction),
+      responseLike.status,
+      apply(numFrom, responseLike.cycles),
+      apply(hexFrom, responseLike.blockHash),
+      apply(numFrom, responseLike.blockNumber),
+      apply(numFrom, responseLike.txIndex),
+      responseLike.reason,
+    );
+  }
+
+  clone() {
+    return new ClientTransactionResponse(
+      this.transaction.clone(),
+      this.status,
+      this.cycles,
+      this.blockHash,
+      this.blockNumber,
+      this.txIndex,
+      this.reason,
+    );
+  }
+}
 
 /**
  * @public
@@ -154,6 +209,10 @@ export class ClientIndexerSearchKeyFilter {
   static from(
     filterLike: ClientIndexerSearchKeyFilterLike,
   ): ClientIndexerSearchKeyFilter {
+    if (filterLike instanceof ClientIndexerSearchKeyFilter) {
+      return filterLike;
+    }
+
     return new ClientIndexerSearchKeyFilter(
       apply(Script.from, filterLike.script),
       apply(clientSearchKeyRangeFrom, filterLike.scriptLenRange),
@@ -186,6 +245,10 @@ export class ClientIndexerSearchKey {
   ) {}
 
   static from(keyLike: ClientIndexerSearchKeyLike): ClientIndexerSearchKey {
+    if (keyLike instanceof ClientIndexerSearchKey) {
+      return keyLike;
+    }
+
     return new ClientIndexerSearchKey(
       Script.from(keyLike.script),
       keyLike.scriptType,
@@ -230,6 +293,10 @@ export class ClientIndexerSearchKeyTransaction {
   static from(
     keyLike: ClientIndexerSearchKeyTransactionLike,
   ): ClientIndexerSearchKeyTransaction {
+    if (keyLike instanceof ClientIndexerSearchKeyTransaction) {
+      return keyLike;
+    }
+
     return new ClientIndexerSearchKeyTransaction(
       Script.from(keyLike.script),
       keyLike.scriptType,
@@ -273,58 +340,167 @@ export type ClientFindTransactionsGroupedResponse = {
 /**
  * @public
  */
-export type ClientBlockHeader = {
-  compactTarget: Num;
+export type ClientBlockHeaderLike = {
+  compactTarget: NumLike;
   dao: {
     /**
      * C_i: the total issuance up to and including block i.
      */
-    c: Num;
+    c: NumLike;
     /**
      * AR_i: the current accumulated rate at block i.
      * AR_j / AR_i reflects the CKByte amount if one deposit 1 CKB to Nervos DAO at block i, and withdraw at block j.
      */
-    ar: Num;
+    ar: NumLike;
     /**
      * S_i: the total unissued secondary issuance up to and including block i,
      * including unclaimed Nervos DAO compensation and treasury funds.
      */
-    s: Num;
+    s: NumLike;
     /**
      * U_i: the total occupied capacities currently in the blockchain up to and including block i.
      * Occupied capacity is the sum of capacities used to store all cells.
      */
-    u: Num;
+    u: NumLike;
   };
-  epoch: Epoch;
-  extraHash: Hex;
-  hash: Hex;
-  nonce: Num;
-  number: Num;
-  parentHash: Hex;
-  proposalsHash: Hex;
-  timestamp: Num;
-  transactionsRoot: Hex;
-  version: Num;
+  epoch: EpochLike;
+  extraHash: HexLike;
+  hash: HexLike;
+  nonce: NumLike;
+  number: NumLike;
+  parentHash: HexLike;
+  proposalsHash: HexLike;
+  timestamp: NumLike;
+  transactionsRoot: HexLike;
+  version: NumLike;
 };
+/**
+ * @public
+ */
+export class ClientBlockHeader {
+  constructor(
+    public compactTarget: Num,
+    public dao: {
+      /**
+       * C_i: the total issuance up to and including block i.
+       */
+      c: Num;
+      /**
+       * AR_i: the current accumulated rate at block i.
+       * AR_j / AR_i reflects the CKByte amount if one deposit 1 CKB to Nervos DAO at block i, and withdraw at block j.
+       */
+      ar: Num;
+      /**
+       * S_i: the total unissued secondary issuance up to and including block i,
+       * including unclaimed Nervos DAO compensation and treasury funds.
+       */
+      s: Num;
+      /**
+       * U_i: the total occupied capacities currently in the blockchain up to and including block i.
+       * Occupied capacity is the sum of capacities used to store all cells.
+       */
+      u: Num;
+    },
+    public epoch: Epoch,
+    public extraHash: Hex,
+    public hash: Hex,
+    public nonce: Num,
+    public number: Num,
+    public parentHash: Hex,
+    public proposalsHash: Hex,
+    public timestamp: Num,
+    public transactionsRoot: Hex,
+    public version: Num,
+  ) {}
+
+  static from(headerLike: ClientBlockHeaderLike): ClientBlockHeader {
+    if (headerLike instanceof ClientBlockHeader) {
+      return headerLike;
+    }
+
+    return new ClientBlockHeader(
+      numFrom(headerLike.compactTarget),
+      {
+        c: numFrom(headerLike.dao.c),
+        ar: numFrom(headerLike.dao.ar),
+        s: numFrom(headerLike.dao.s),
+        u: numFrom(headerLike.dao.u),
+      },
+      epochFrom(headerLike.epoch),
+      hexFrom(headerLike.extraHash),
+      hexFrom(headerLike.hash),
+      numFrom(headerLike.nonce),
+      numFrom(headerLike.number),
+      hexFrom(headerLike.parentHash),
+      hexFrom(headerLike.proposalsHash),
+      numFrom(headerLike.timestamp),
+      hexFrom(headerLike.transactionsRoot),
+      numFrom(headerLike.version),
+    );
+  }
+}
 
 /**
  * @public
  */
-export type ClientBlockUncle = {
-  header: ClientBlockHeader;
-  proposals: Hex[];
+export type ClientBlockUncleLike = {
+  header: ClientBlockHeaderLike;
+  proposals: HexLike[];
 };
+/**
+ * @public
+ */
+export class ClientBlockUncle {
+  constructor(
+    public header: ClientBlockHeader,
+    public proposals: Hex[],
+  ) {}
+
+  static from(uncleLike: ClientBlockUncleLike): ClientBlockUncle {
+    if (uncleLike instanceof ClientBlockUncle) {
+      return uncleLike;
+    }
+
+    return new ClientBlockUncle(
+      ClientBlockHeader.from(uncleLike.header),
+      uncleLike.proposals.map(hexFrom),
+    );
+  }
+}
 
 /**
  * @public
  */
-export type ClientBlock = {
-  header: ClientBlockHeader;
-  proposals: Hex[];
-  transactions: Transaction[];
-  uncles: ClientBlockUncle[];
+export type ClientBlockLike = {
+  header: ClientBlockHeaderLike;
+  proposals: HexLike[];
+  transactions: TransactionLike[];
+  uncles: ClientBlockUncleLike[];
 };
+/**
+ * @public
+ */
+export class ClientBlock {
+  constructor(
+    public header: ClientBlockHeader,
+    public proposals: Hex[],
+    public transactions: Transaction[],
+    public uncles: ClientBlockUncle[],
+  ) {}
+
+  static from(blockLike: ClientBlockLike): ClientBlock {
+    if (blockLike instanceof ClientBlock) {
+      return blockLike;
+    }
+
+    return new ClientBlock(
+      ClientBlockHeader.from(blockLike.header),
+      blockLike.proposals.map(hexFrom),
+      blockLike.transactions.map(Transaction.from),
+      blockLike.uncles.map(ClientBlockUncle.from),
+    );
+  }
+}
 
 export interface ErrorClientBaseLike {
   message?: string;
@@ -392,8 +568,23 @@ export class ErrorClientRBFRejected extends ErrorClientBase {
   }
 }
 
-export class ErrorClientWaitTransactionTimeout extends Error {
-  constructor() {
-    super("Wait transaction timeout");
+export class ErrorClientWaitTransactionTimeout extends ErrorClientBase {
+  constructor(timeoutLike: NumLike) {
+    const timeout = numFrom(timeoutLike).toString();
+    super({
+      message: `Wait transaction timeout ${timeout}ms`,
+      data: JSON.stringify({ timeout }),
+    });
+  }
+}
+
+export class ErrorClientMaxFeeRateExceeded extends ErrorClientBase {
+  constructor(limitLike: NumLike, actualLike: NumLike) {
+    const limit = numFrom(limitLike).toString();
+    const actual = numFrom(actualLike).toString();
+    super({
+      message: `Max fee rate exceeded limit ${limit}, actual ${actual}. Developer might forgot to complete transaction fee before sending. See https://docs.ckbccc.com/classes/_ckb_ccc_core.index.ccc.Transaction.html#completeFeeBy.`,
+      data: JSON.stringify({ limit, actual }),
+    });
   }
 }