refactor(l1-tx-utils): add checkBalance option and InsufficientBalanceError

Adds a checkBalance flag to L1TxConfig. When true, sendTransaction computes a
worst-case cost from gasLimit, the live gas price, and (for blob txs) blob
gas, and throws InsufficientBalanceError if the sender's balance cannot cover
it. SequencerPublisher's rotation loop now consumes this typed error to
rotate to a new publisher, replacing the inline balance check that used to
live alongside Multicall3.forward.

Author: spalladino

yarn-project/ethereum/src/l1_tx_utils/l1_tx_utils.test.ts

@@ -1024,6 +1024,33 @@ describe('L1TxUtils', () => {
       expect(result.receipt.status).toBe('reverted');
     });
 
+    it('throws InsufficientBalanceError when checkBalance is enabled and balance is too low', async () => {
+      // Mock getSenderBalance to return 0 so any non-trivial gasLimit * gasPrice exceeds it.
+      const balanceSpy = jest.spyOn(gasUtils, 'getSenderBalance').mockResolvedValue(0n);
+      try {
+        await expect(gasUtils.sendTransaction(request, { gasLimit: 1_000_000n, checkBalance: true })).rejects.toThrow(
+          /insufficient balance/i,
+        );
+      } finally {
+        balanceSpy.mockRestore();
+      }
+    });
+
+    it('does not check balance by default', async () => {
+      // Even with zero balance, the call should not throw the balance error; it would only fail
+      // later for unrelated reasons. We assert by reading the rejection — if it has the
+      // insufficient-balance message, the default skipped the check incorrectly.
+      const balanceSpy = jest.spyOn(gasUtils, 'getSenderBalance').mockResolvedValue(0n);
+      try {
+        // The send may or may not succeed depending on the test anvil's state; we only care that
+        // it does NOT throw InsufficientBalanceError.
+        const result = await gasUtils.sendTransaction(request, { gasLimit: 1_000_000n }).catch(err => err);
+        expect(result?.message ?? '').not.toMatch(/insufficient balance/i);
+      } finally {
+        balanceSpy.mockRestore();
+      }
+    });
+
     it('does not consume nonce when transaction times out before sending', async () => {
       // first send a transaction to advance the nonce
       await gasUtils.sendAndMonitorTransaction(request);

yarn-project/ethereum/src/l1_tx_utils/l1_tx_utils.ts

@@ -32,6 +32,7 @@ import { ReadOnlyL1TxUtils } from './readonly_l1_tx_utils.js';
 import { Delayer, createDelayer, wrapClientWithDelayer } from './tx_delayer.js';
 import {
   DroppedTransactionError,
+  InsufficientBalanceError,
   type L1BlobInputs,
   type L1TxConfig,
   type L1TxRequest,
@@ -245,6 +246,22 @@ export class L1TxUtils extends ReadOnlyL1TxUtils {
 
       const gasPrice = await this.getGasPrice(gasConfig, !!blobInputs);
 
+      if (gasConfig.checkBalance) {
+        // Worst-case = gasLimit * maxFeePerGas, plus blob gas cost when this is a blob tx. The 2x
+        // safety factor absorbs replacement bumps and EIP-1559 spikes during the tx's lifetime.
+        const worstCaseGas = gasLimit * gasPrice.maxFeePerGas;
+        const blobBytesPerBlob = 131_072n; // 4096 field elements * 32 bytes
+        const worstCaseBlob =
+          blobInputs && gasPrice.maxFeePerBlobGas !== undefined
+            ? BigInt(blobInputs.blobs.length) * blobBytesPerBlob * gasPrice.maxFeePerBlobGas
+            : 0n;
+        const worstCase = 2n * (worstCaseGas + worstCaseBlob);
+        const balance = await this.getSenderBalance();
+        if (balance < worstCase) {
+          throw new InsufficientBalanceError(account, balance, worstCase);
+        }
+      }
+
       if (this.interrupted) {
         throw new InterruptError(`Transaction sending is interrupted`);
       }

yarn-project/ethereum/src/l1_tx_utils/types.ts

@@ -13,7 +13,17 @@ export interface L1TxRequest {
   abi?: Abi;
 }
 
-export type L1TxConfig = Partial<L1TxUtilsConfig> & { gasLimit?: bigint; txTimeoutAt?: Date };
+export type L1TxConfig = Partial<L1TxUtilsConfig> & {
+  gasLimit?: bigint;
+  txTimeoutAt?: Date;
+  /**
+   * When true, sendTransaction will compute a worst-case cost from gasLimit and the live gas price
+   * (plus blob gas if applicable) and verify the sender balance can cover it before broadcasting.
+   * If not, an InsufficientBalanceError is thrown so callers (e.g. publisher rotation) can react.
+   * Defaults to false. The check is only meaningful when `gasLimit` is set; otherwise it is skipped.
+   */
+  checkBalance?: boolean;
+};
 
 export interface L1BlobInputs {
   blobs: Uint8Array[];
@@ -83,3 +93,15 @@ export class DroppedTransactionError extends Error {
     this.name = 'DroppedTransactionError';
   }
 }
+
+/** Thrown by sendTransaction when checkBalance is true and the sender lacks the worst-case cost. */
+export class InsufficientBalanceError extends Error {
+  constructor(
+    public readonly account: string,
+    public readonly balance: bigint,
+    public readonly worstCase: bigint,
+  ) {
+    super(`Account ${account} has insufficient balance: ${balance} < ${worstCase} (worst case)`);
+    this.name = 'InsufficientBalanceError';
+  }
+}

yarn-project/sequencer-client/src/publisher/sequencer-publisher.test.ts

@@ -278,6 +278,7 @@ describe('SequencerPublisher', () => {
       {
         gasLimit: expect.any(BigInt),
         txTimeoutAt: undefined,
+        checkBalance: true,
       },
       expect.objectContaining({
         blobs: expect.any(Array),