Fix: Facilitator should validate user balance before sending settlement transaction (#199)

* Fix: Facilitator should validate user balance before sending settlement transaction

* Apply changes from Holon

---------

Co-authored-by: holonbot[bot] <250454749+holonbot[bot]@users.noreply.github.com>

Author: holonbot[bot]

typescript/packages/facilitator-sdk/src/index.ts

@@ -41,6 +41,7 @@ export {
   parseSettlementRouterParams,
   settleWithSettlementRouter,
   executeSettlementWithWalletClient,
+  InsufficientBalanceError,
 } from "./settlement.js";
 
 // Validation utilities

typescript/packages/facilitator-sdk/src/settlement.ts

@@ -184,6 +184,38 @@ export function calculateGasLimit(
   return totalGas;
 }
 
+/**
+ * Custom error for insufficient balance errors
+ * Thrown when user's token balance is less than required amount for settlement
+ */
+export class InsufficientBalanceError extends Error {
+  /** User's current balance */
+  readonly balance: bigint;
+  /** Required amount (payment + facilitator fee) */
+  readonly required: bigint;
+  /** Payment amount */
+  readonly payment: bigint;
+  /** Facilitator fee amount */
+  readonly fee: bigint;
+
+  constructor(
+    balance: bigint,
+    required: bigint,
+    payment: bigint,
+    fee: bigint,
+  ) {
+    super(
+      `Insufficient balance: user has ${balance} tokens, but needs ${required} ` +
+      `(payment: ${payment} + facilitator fee: ${fee})`
+    );
+    this.name = "InsufficientBalanceError";
+    this.balance = balance;
+    this.required = required;
+    this.payment = payment;
+    this.fee = fee;
+  }
+}
+
 /**
  * Check if a settlement has already been executed
  */
@@ -208,14 +240,42 @@ export async function checkIfSettled(
 }
 
 /**
- * Execute settlement via SettlementRouter
+ * ERC20 ABI for balance checks
+ */
+const ERC20_ABI = [
+  {
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "account", type: "address" }],
+    name: "balanceOf",
+    outputs: [{ type: "uint256" }],
+  },
+] as const;
+
+/**
+ * Execute settlement via SettlementRouter.
+ *
+ * @param walletClient - The viem {@link WalletClient} used to send the settlement transaction.
+ * @param params - The {@link SettlementRouterParams} describing the settlement to execute.
+ * @param config - Optional configuration overrides.
+ * @param config.gasLimit - Explicit gas limit to use for the transaction. If omitted, it is derived
+ *   from {@link calculateGasLimit} based on the facilitator fee and `gasMultiplier`.
+ * @param config.gasMultiplier - Multiplier applied when estimating gas usage (for safety margin).
+ * @param config.publicClient - Optional viem {@link PublicClient} to use for read operations
+ *   (for example, balance checks). If provided, the user's token balance will be validated before
+ *   sending the transaction to avoid wasting gas on insufficient balance scenarios.
+ * @returns A promise that resolves to the transaction hash of the settlement as a hex string.
+ * @throws {InsufficientBalanceError} When `publicClient` is provided and the user's token balance
+ *   is less than the required amount (payment + facilitator fee).
+ * @throws {Error} When transaction execution fails (e.g., invalid signature, contract revert).
  */
 export async function executeSettlementWithRouter(
   walletClient: WalletClient,
   params: SettlementRouterParams,
   config: {
     gasLimit?: bigint;
     gasMultiplier?: number;
+    publicClient?: PublicClient;
   } = {},
 ): Promise<Hex> {
   const gasLimit =
@@ -238,6 +298,36 @@ export async function executeSettlementWithRouter(
     settlementRouter: params.settlementRouter,
   });
 
+  // Check user balance before sending transaction to avoid wasting gas
+  if (config.publicClient) {
+    try {
+      const balance = await config.publicClient.readContract({
+        address: params.token,
+        abi: ERC20_ABI,
+        functionName: "balanceOf",
+        args: [params.from],
+      });
+
+      const paymentAmount = BigInt(params.value);
+      const feeAmount = BigInt(params.facilitatorFee);
+      const requiredAmount = paymentAmount + feeAmount;
+
+      if (balance < requiredAmount) {
+        throw new InsufficientBalanceError(balance, requiredAmount, paymentAmount, feeAmount);
+      }
+    } catch (error) {
+      // If balance check fails, log the error but continue with transaction
+      // The transaction will fail on-chain with a more specific error if balance is truly insufficient
+      if (error instanceof InsufficientBalanceError) {
+        // Re-throw the insufficient balance error
+        throw error;
+      } else {
+        // Log RPC/other errors and proceed with transaction
+        console.warn("[executeSettlementWithRouter] Balance check failed, proceeding with transaction:", error instanceof Error ? error.message : error);
+      }
+    }
+  }
+
   try {
     const txHash = await walletClient.writeContract({
       address: params.settlementRouter,
@@ -503,6 +593,7 @@ export async function executeSettlementWithWalletClient(
     const txHash = await executeSettlementWithRouter(walletClient, params, {
       gasLimit: config.gasLimit,
       gasMultiplier: config.gasMultiplier,
+      publicClient,
     });
 
     // Wait for receipt
@@ -594,6 +685,7 @@ export async function settleWithSettlementRouter(
     const txHash = await executeSettlementWithRouter(walletClient, params, {
       gasLimit: options.gasLimit,
       gasMultiplier: options.gasMultiplier,
+      publicClient,
     });
 
     // Wait for receipt

typescript/packages/facilitator-sdk/test/settlement.test.ts

@@ -12,6 +12,7 @@ import {
   waitForSettlementReceipt,
   parseSettlementRouterParams,
   settleWithSettlementRouter,
+  InsufficientBalanceError,
 } from "../src/index.js";
 import { SettlementRouterError } from "../src/types.js";
 import {
@@ -317,6 +318,137 @@ describe("SettlementRouter integration", () => {
       );
     });
 
+    it("should validate user balance before sending transaction when publicClient is provided", async () => {
+      const params = {
+        token: MOCK_ADDRESSES.token,
+        from: MOCK_ADDRESSES.payer,
+        value: MOCK_VALUES.paymentAmount,
+        validAfter: MOCK_VALUES.validAfter,
+        validBefore: MOCK_VALUES.validBefore,
+        nonce: MOCK_VALUES.nonce,
+        signature: MOCK_VALUES.signature,
+        salt: MOCK_VALUES.salt,
+        payTo: MOCK_ADDRESSES.merchant,
+        facilitatorFee: MOCK_VALUES.facilitatorFee,
+        hook: MOCK_ADDRESSES.hook,
+        hookData: MOCK_VALUES.hookData,
+        settlementRouter: MOCK_ADDRESSES.settlementRouter,
+      };
+
+      // Mock balance check - user has sufficient balance (2,000,000 is greater than payment 1,000,000 + fee 100,000)
+      const sufficientBalance = BigInt(2000000);
+      mockPublicClient.readContract.mockResolvedValue(sufficientBalance);
+
+      const txHash = await executeSettlementWithRouter(mockWalletClient, params, {
+        publicClient: mockPublicClient,
+      });
+
+      expect(txHash).toBe(mockSettleResponse.transaction);
+      expect(mockPublicClient.readContract).toHaveBeenCalledWith({
+        address: MOCK_ADDRESSES.token,
+        abi: expect.arrayContaining([
+          expect.objectContaining({
+            name: "balanceOf",
+            type: "function",
+          }),
+        ]),
+        functionName: "balanceOf",
+        args: [MOCK_ADDRESSES.payer],
+      });
+      expect(mockWalletClient.writeContract).toHaveBeenCalled();
+    });
+
+    it("should throw error when user has insufficient balance", async () => {
+      const params = {
+        token: MOCK_ADDRESSES.token,
+        from: MOCK_ADDRESSES.payer,
+        value: MOCK_VALUES.paymentAmount,
+        validAfter: MOCK_VALUES.validAfter,
+        validBefore: MOCK_VALUES.validBefore,
+        nonce: MOCK_VALUES.nonce,
+        signature: MOCK_VALUES.signature,
+        salt: MOCK_VALUES.salt,
+        payTo: MOCK_ADDRESSES.merchant,
+        facilitatorFee: MOCK_VALUES.facilitatorFee,
+        hook: MOCK_ADDRESSES.hook,
+        hookData: MOCK_VALUES.hookData,
+        settlementRouter: MOCK_ADDRESSES.settlementRouter,
+      };
+
+      // Mock insufficient balance (1000 is less than payment amount + facilitator fee)
+      const paymentAmount = BigInt(MOCK_VALUES.paymentAmount);
+      const facilitatorFee = BigInt(MOCK_VALUES.facilitatorFee);
+      const requiredAmount = paymentAmount + facilitatorFee;
+      const insufficientBalance = requiredAmount - 1n;
+
+      mockPublicClient.readContract.mockResolvedValue(insufficientBalance);
+
+      await expect(
+        executeSettlementWithRouter(mockWalletClient, params, {
+          publicClient: mockPublicClient,
+        }),
+      ).rejects.toThrow(InsufficientBalanceError);
+
+      // Verify transaction was NOT sent
+      expect(mockWalletClient.writeContract).not.toHaveBeenCalled();
+    });
+
+    it("should skip balance check when publicClient is not provided", async () => {
+      const params = {
+        token: MOCK_ADDRESSES.token,
+        from: MOCK_ADDRESSES.payer,
+        value: MOCK_VALUES.paymentAmount,
+        validAfter: MOCK_VALUES.validAfter,
+        validBefore: MOCK_VALUES.validBefore,
+        nonce: MOCK_VALUES.nonce,
+        signature: MOCK_VALUES.signature,
+        salt: MOCK_VALUES.salt,
+        payTo: MOCK_ADDRESSES.merchant,
+        facilitatorFee: MOCK_VALUES.facilitatorFee,
+        hook: MOCK_ADDRESSES.hook,
+        hookData: MOCK_VALUES.hookData,
+        settlementRouter: MOCK_ADDRESSES.settlementRouter,
+      };
+
+      // Call without publicClient
+      const txHash = await executeSettlementWithRouter(mockWalletClient, params);
+
+      expect(txHash).toBe(mockSettleResponse.transaction);
+      // Balance check should not be performed
+      expect(mockPublicClient.readContract).not.toHaveBeenCalled();
+      // But transaction should still be sent
+      expect(mockWalletClient.writeContract).toHaveBeenCalled();
+    });
+
+    it("should handle balance check errors gracefully and proceed with transaction", async () => {
+      const params = {
+        token: MOCK_ADDRESSES.token,
+        from: MOCK_ADDRESSES.payer,
+        value: MOCK_VALUES.paymentAmount,
+        validAfter: MOCK_VALUES.validAfter,
+        validBefore: MOCK_VALUES.validBefore,
+        nonce: MOCK_VALUES.nonce,
+        signature: MOCK_VALUES.signature,
+        salt: MOCK_VALUES.salt,
+        payTo: MOCK_ADDRESSES.merchant,
+        facilitatorFee: MOCK_VALUES.facilitatorFee,
+        hook: MOCK_ADDRESSES.hook,
+        hookData: MOCK_VALUES.hookData,
+        settlementRouter: MOCK_ADDRESSES.settlementRouter,
+      };
+
+      // Mock balance check failure (e.g., RPC error)
+      mockPublicClient.readContract.mockRejectedValue(new Error("RPC timeout"));
+
+      const txHash = await executeSettlementWithRouter(mockWalletClient, params, {
+        publicClient: mockPublicClient,
+      });
+
+      // Should still proceed with transaction despite balance check failure
+      expect(txHash).toBe(mockSettleResponse.transaction);
+      expect(mockWalletClient.writeContract).toHaveBeenCalled();
+    });
+
     it("should use custom gas limit", async () => {
       const params = {
         token: MOCK_ADDRESSES.token,