feat(core): fee rate checks

Author: Hanssen0

.changeset/proud-crabs-grow.md

@@ -0,0 +1,5 @@
+---
+"@ckb-ccc/core": minor
+---
+
+feat(core): fee rate checks

packages/core/src/ckb/transaction.ts

@@ -1567,18 +1567,33 @@ 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(
     from: Signer,
     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 +1624,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",
         );

packages/core/src/client/client.ts

@@ -9,11 +9,15 @@ 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 {
+  ClientCollectableSearchKeyLike,
+  DEFAULT_MAX_FEE_RATE,
+  DEFAULT_MIN_FEE_RATE,
+} from "./clientTypes.advanced.js";
 import {
   CellDepInfo,
   CellDepInfoLike,
@@ -26,6 +30,7 @@ import {
   ClientIndexerSearchKeyLike,
   ClientIndexerSearchKeyTransactionLike,
   ClientTransactionResponse,
+  ErrorClientMaxFeeRateExceeded,
   ErrorClientWaitTransactionTimeout,
   KnownScript,
   OutputsValidator,
@@ -50,8 +55,21 @@ 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>;
@@ -476,9 +494,16 @@ 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);

packages/core/src/client/clientTypes.advanced.ts

@@ -2,6 +2,9 @@ import { ScriptLike } from "../ckb/index.js";
 import { HexLike } from "../hex/index.js";
 import { Num, numFrom, NumLike } from "../num/index.js";
 
+export const DEFAULT_MAX_FEE_RATE = 10000000;
+export const DEFAULT_MIN_FEE_RATE = 1000;
+
 export function clientSearchKeyRangeFrom([a, b]: [NumLike, NumLike]): [
   Num,
   Num,

packages/core/src/client/clientTypes.ts

@@ -392,8 +392,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);
+    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);
+    const actual = numFrom(actualLike);
+    super({
+      message: `Max fee rate exceeded limit ${limit.toString()}, actual ${actual.toString()}. 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 }),
+    });
   }
 }