@aztec-labs/ethereum 6.0.0-nightly.20260829

package/src/l1_tx_utils/tx_delayer.ts

@@ -0,0 +1,302 @@
+import { omit } from '@aztec-labs/foundation/collection';
+import { type Logger, type LoggerBindings, createLogger } from '@aztec-labs/foundation/log';
+import { retryUntil } from '@aztec-labs/foundation/retry';
+import type { DateProvider } from '@aztec-labs/foundation/timer';
+import { inspect } from 'util';
+import {
+  type Client,
+  type Hex,
+  type PublicClient,
+  type TransactionSerializableEIP4844,
+  type TransactionSerialized,
+  keccak256,
+  parseTransaction,
+  publicActions,
+  recoverTransactionAddress,
+  serializeTransaction,
+  walletActions,
+} from 'viem';
+
+import type { ExtendedViemWalletClient, ViemClient } from '../types.js';
+
+const MAX_WAIT_TIME_SECONDS = 180;
+
+export function waitUntilBlock<T extends Client>(
+  client: T,
+  blockNumber: number | bigint,
+  logger?: Logger,
+  timeout?: number,
+) {
+  const publicClient =
+    'getBlockNumber' in client && typeof client.getBlockNumber === 'function'
+      ? (client as unknown as PublicClient)
+      : client.extend(publicActions);
+
+  return retryUntil(
+    async () => {
+      const currentBlockNumber = await publicClient.getBlockNumber({ cacheTime: 0 });
+      logger?.debug(`Block number is ${currentBlockNumber} (waiting until ${blockNumber})`);
+      return currentBlockNumber >= BigInt(blockNumber);
+    },
+    `Wait until L1 block ${blockNumber}`,
+    timeout ?? MAX_WAIT_TIME_SECONDS,
+    0.1,
+  );
+}
+
+export function waitUntilL1Timestamp<T extends Client>(
+  client: T,
+  timestamp: number | bigint,
+  logger?: Logger,
+  timeout?: number,
+) {
+  const publicClient =
+    'getBlockNumber' in client && typeof client.getBlockNumber === 'function'
+      ? (client as unknown as PublicClient)
+      : client.extend(publicActions);
+
+  let lastBlock: bigint | undefined = undefined;
+  return retryUntil(
+    async () => {
+      const currentBlockNumber = await publicClient.getBlockNumber({ cacheTime: 0 });
+      if (currentBlockNumber === lastBlock) {
+        return false;
+      }
+      lastBlock = currentBlockNumber;
+      const currentBlock = await publicClient.getBlock({ includeTransactions: false, blockNumber: currentBlockNumber });
+      const currentTs = currentBlock.timestamp;
+      logger?.debug(`Block timstamp is ${currentTs} (waiting until ${timestamp})`);
+      return currentTs >= BigInt(timestamp);
+    },
+    `Wait until L1 timestamp ${timestamp}`,
+    timeout ?? MAX_WAIT_TIME_SECONDS,
+    0.1,
+  );
+}
+
+/** Manages tx delaying for testing, intercepting sendRawTransaction calls to delay or cancel them. */
+export class Delayer {
+  private logger: Logger;
+
+  public maxInclusionTimeIntoSlot: number | undefined = undefined;
+  public ethereumSlotDuration: bigint;
+  public nextWait:
+    | { l1Timestamp: bigint; timeoutSeconds?: number }
+    | { l1BlockNumber: bigint; timeoutSeconds?: number }
+    | { indefinitely: true }
+    | undefined = undefined;
+  public sentTxHashes: Hex[] = [];
+  public cancelledTxs: Hex[] = [];
+
+  constructor(
+    public dateProvider: DateProvider,
+    opts: { ethereumSlotDuration: bigint | number },
+    bindings: LoggerBindings,
+  ) {
+    this.ethereumSlotDuration = BigInt(opts.ethereumSlotDuration);
+    this.logger = createLogger('ethereum:tx_delayer', bindings);
+  }
+
+  /** Returns the logger instance used by this delayer. */
+  getLogger(): Logger {
+    return this.logger;
+  }
+
+  /** Returns the hashes of all effectively sent txs. */
+  getSentTxHashes() {
+    return this.sentTxHashes;
+  }
+
+  /** Returns the raw hex for all cancelled txs. */
+  getCancelledTxs(): Hex[] {
+    return this.cancelledTxs;
+  }
+
+  /** Delays the next tx to be sent so it lands on the given L1 block number. */
+  pauseNextTxUntilBlock(l1BlockNumber: number | bigint, timeoutSeconds?: number) {
+    this.nextWait = { l1BlockNumber: BigInt(l1BlockNumber), timeoutSeconds };
+  }
+
+  /** Delays the next tx to be sent so it lands on the given timestamp. */
+  pauseNextTxUntilTimestamp(l1Timestamp: number | bigint, timeoutSeconds?: number) {
+    this.nextWait = { l1Timestamp: BigInt(l1Timestamp), timeoutSeconds };
+  }
+
+  /** Delays the next tx to be sent indefinitely. */
+  cancelNextTx() {
+    this.nextWait = { indefinitely: true };
+  }
+
+  /**
+   * Sets max inclusion time into slot. If more than this many seconds have passed
+   * since the last L1 block was mined, then any tx will not be mined in the current
+   * L1 slot but will be deferred for the next one.
+   */
+  setMaxInclusionTimeIntoSlot(seconds: number | undefined) {
+    this.maxInclusionTimeIntoSlot = seconds;
+  }
+}
+
+/**
+ * Creates a new Delayer instance. Exposed so callers can create a single shared delayer
+ * and pass it to multiple `wrapClientWithDelayer` calls.
+ */
+export function createDelayer(
+  dateProvider: DateProvider,
+  opts: { ethereumSlotDuration: bigint | number },
+  bindings: LoggerBindings,
+): Delayer {
+  return new Delayer(dateProvider, opts, bindings);
+}
+
+/** Tries to recover the sender address from a serialized signed transaction. */
+async function tryRecoverSender(serializedTransaction: Hex): Promise<string | undefined> {
+  try {
+    return await recoverTransactionAddress({
+      serializedTransaction: serializedTransaction as TransactionSerialized,
+    });
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Wraps a viem client with tx delaying logic. Returns the wrapped client.
+ * The delayer intercepts sendRawTransaction calls and delays them based on the delayer's state.
+ */
+export function wrapClientWithDelayer<T extends ViemClient>(client: T, delayer: Delayer): T {
+  const logger = delayer.getLogger();
+
+  // Cast to ExtendedViemWalletClient for the extend chain since it has sendRawTransaction.
+  // The sendRawTransaction override is applied to all clients regardless of type.
+  const withRawTx = (client as unknown as ExtendedViemWalletClient)
+    // Tweak sendRawTransaction so it uses the delay defined in the delayer.
+    // Note that this will only work with local accounts (ie accounts for which we have the private key).
+    // Transactions signed by the node will not be delayed since they use sendTransaction directly,
+    // but we do not use them in our codebase at all.
+    .extend(client => ({
+      async sendRawTransaction(...args) {
+        let wait: Promise<unknown> | undefined;
+        let txHash: Hex | undefined;
+
+        const { serializedTransaction } = args[0];
+        const publicClient = client as unknown as PublicClient;
+        const sender = await tryRecoverSender(serializedTransaction);
+
+        if (delayer.nextWait !== undefined) {
+          // Check if we have been instructed to delay the next tx.
+          const waitUntil = delayer.nextWait;
+          delayer.nextWait = undefined;
+
+          // Compute the tx hash manually so we emulate sendRawTransaction response
+          txHash = computeTxHash(serializedTransaction);
+
+          // Cancel tx outright if instructed
+          if ('indefinitely' in waitUntil && waitUntil.indefinitely) {
+            logger.info(`Cancelling tx ${txHash}`, { sender });
+            delayer.cancelledTxs.push(serializedTransaction);
+            return Promise.resolve(txHash);
+          }
+
+          // Or wait until the desired block number or timestamp
+          wait =
+            'l1BlockNumber' in waitUntil
+              ? waitUntilBlock(publicClient, waitUntil.l1BlockNumber - 1n, logger, waitUntil.timeoutSeconds)
+              : 'l1Timestamp' in waitUntil
+                ? waitUntilL1Timestamp(
+                    publicClient,
+                    waitUntil.l1Timestamp - delayer.ethereumSlotDuration,
+                    logger,
+                    waitUntil.timeoutSeconds,
+                  )
+                : undefined;
+
+          logger.info(`Delaying tx ${txHash} until ${inspect(waitUntil)}`, {
+            sender,
+            argsLen: args.length,
+            ...omit(parseTransaction(serializedTransaction), 'data', 'sidecars'),
+          });
+        } else if (delayer.maxInclusionTimeIntoSlot !== undefined) {
+          // Check if we need to delay txs sent too close to the end of the slot.
+          const currentBlock = await publicClient.getBlock({ includeTransactions: false });
+          const { timestamp: lastBlockTimestamp, number } = currentBlock;
+          const now = delayer.dateProvider.now();
+
+          txHash = computeTxHash(serializedTransaction);
+          const logData = {
+            sender,
+            ...omit(parseTransaction(serializedTransaction), 'data', 'sidecars'),
+            lastBlockTimestamp,
+            now,
+            maxInclusionTimeIntoSlot: delayer.maxInclusionTimeIntoSlot,
+          };
+
+          if (now / 1000 - Number(lastBlockTimestamp) > delayer.maxInclusionTimeIntoSlot) {
+            // If the last block was mined more than `maxInclusionTimeIntoSlot` seconds ago, then we cannot include
+            // any txs in the current slot, so we delay the tx until the next slot.
+            logger.info(`Delaying inclusion of tx ${txHash} until the next slot since it was sent too late`, logData);
+            wait = waitUntilBlock(publicClient, number + 1n, logger);
+          } else {
+            logger.debug(`Immediately sending tx ${txHash} as it was received early enough in the slot`, logData);
+          }
+        }
+
+        if (wait !== undefined) {
+          // Do not await here so we can return the tx hash immediately as if it had been sent on the spot.
+          // Instead, delay it so it lands on the desired block number or timestamp, assuming anvil will
+          // mine it immediately.
+          void wait!
+            .then(async () => {
+              const clientTxHash = await client.sendRawTransaction(...args);
+              if (clientTxHash !== txHash) {
+                logger.error(`Tx hash returned by the client does not match computed one`, {
+                  clientTxHash,
+                  computedTxHash: txHash,
+                });
+              }
+              logger.info(`Sent previously delayed tx ${clientTxHash}`, { sender });
+              delayer.sentTxHashes.push(clientTxHash);
+            })
+            .catch(err => logger.error(`Error sending tx after delay`, err));
+          return Promise.resolve(txHash!);
+        } else {
+          const txHash = await client.sendRawTransaction(...args);
+          logger.debug(`Sent tx immediately ${txHash}`, { sender });
+          delayer.sentTxHashes.push(txHash);
+          return txHash;
+        }
+      },
+    }));
+
+  // Only re-bind wallet actions (sendTransaction, writeContract, deployContract) for wallet clients.
+  // This is needed for tests that use wallet actions directly rather than sendRawTransaction.
+  const isWalletClient = 'account' in client && client.account !== undefined;
+  const extended = isWalletClient
+    ? withRawTx
+        // Re-extend with sendTransaction so it uses the modified sendRawTransaction.
+        .extend(client => ({ sendTransaction: walletActions(client).sendTransaction }))
+        // And with the actions that depend on the modified sendTransaction
+        .extend(client => ({
+          writeContract: walletActions(client).writeContract,
+          deployContract: walletActions(client).deployContract,
+        }))
+    : withRawTx;
+
+  return extended as T;
+}
+
+/**
+ * Compute the tx hash given the serialized tx. Note that if this is a blob tx, we need to
+ * exclude the blobs, commitments, and proofs from the hash.
+ */
+function computeTxHash(serializedTransaction: Hex) {
+  if (serializedTransaction.startsWith('0x03')) {
+    const parsed = parseTransaction(serializedTransaction);
+    if (parsed.blobs || parsed.sidecars) {
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      const { blobs, sidecars, ...rest } = parsed;
+      return keccak256(serializeTransaction({ type: 'eip4844', ...rest } as TransactionSerializableEIP4844));
+    }
+  }
+  return keccak256(serializedTransaction);
+}

package/src/l1_tx_utils/types.ts

@@ -0,0 +1,116 @@
+import type { BlobKzgInstance } from '@aztec-labs/blob-lib/types';
+import { TimeoutError } from '@aztec-labs/foundation/error';
+import { EthAddress } from '@aztec-labs/foundation/eth-address';
+import type { ViemTransactionSignature } from '@aztec-labs/foundation/eth-signature';
+import type { Abi, Address, Hex, TransactionReceipt, TransactionSerializable } from 'viem';
+
+import type { L1TxUtilsConfig } from './config.js';
+
+export interface L1TxRequest {
+  to: Address | null;
+  data?: Hex;
+  value?: bigint;
+  abi?: Abi;
+}
+
+export type L1TxConfig = Partial<L1TxUtilsConfig> & { gasLimit?: bigint; txTimeoutAt?: Date };
+
+export interface L1BlobInputs {
+  blobs: Uint8Array[];
+  kzg: BlobKzgInstance;
+  maxFeePerBlobGas?: bigint;
+}
+
+export interface FeesPerGas {
+  maxFeePerGas: bigint;
+  maxPriorityFeePerGas: bigint;
+  maxFeePerBlobGas?: bigint;
+}
+
+export type TransactionStats = {
+  /** Address of the sender. */
+  sender: string;
+  /** Hash of the transaction. */
+  transactionHash: string;
+  /** Size in bytes of the tx calldata */
+  calldataSize: number;
+  /** Gas required to pay for the calldata inclusion (depends on size and number of zeros)  */
+  calldataGas: number;
+};
+
+export enum TxUtilsState {
+  IDLE,
+  SENT,
+  SPEED_UP,
+  CANCELLED,
+  NOT_MINED,
+  MINED,
+}
+
+export const TerminalTxUtilsState = [TxUtilsState.IDLE, TxUtilsState.MINED, TxUtilsState.NOT_MINED];
+
+export type L1TxState = {
+  id: number;
+  txHashes: Hex[];
+  cancelTxHashes: Hex[];
+  gasLimit: bigint;
+  feesPerGas: FeesPerGas;
+  /**
+   * Fees per gas used for each attempt (initial send followed by each speed-up), in order. Always set on
+   * newly sent txs; optional because states restored from the state store predate the field.
+   * In-memory only — not persisted by the state store.
+   */
+  feesPerGasHistory?: FeesPerGas[];
+  txConfigOverrides: L1TxConfig;
+  request: L1TxRequest;
+  status: TxUtilsState;
+  nonce: number;
+  sentAtL1Ts: Date;
+  lastSentAtL1Ts: Date;
+  receipt?: TransactionReceipt;
+  blobInputs: L1BlobInputs | undefined;
+};
+
+export type SigningCallback = (
+  transaction: TransactionSerializable,
+  signingAddress: EthAddress,
+) => Promise<ViemTransactionSignature>;
+
+export class UnknownMinedTxError extends Error {
+  constructor(nonce: number, account: string) {
+    super(`Nonce ${nonce} from account ${account} is MINED but not by one of our expected transactions`);
+    this.name = 'UnknownMinedTxError';
+  }
+}
+
+export class DroppedTransactionError extends Error {
+  constructor(nonce: number, account: string) {
+    super(`Transaction with nonce ${nonce} from account ${account} was dropped from the mempool`);
+    this.name = 'DroppedTransactionError';
+  }
+}
+
+/** Snapshot of what a timed-out L1 tx tried to pay, taken when the timeout is raised. */
+export type TimedOutTxState = {
+  /** Fees per gas used across the initial send and each speed-up, in order (undefined only for restored states). */
+  feesPerGasHistory?: FeesPerGas[];
+  /** The last fees per gas the tx was sent with before timing out. */
+  finalFeesPerGas: FeesPerGas;
+  /** Number of send attempts (initial + speed-ups). */
+  attempts: number;
+  nonce: number;
+  gasLimit: bigint;
+};
+
+/**
+ * Thrown by sendAndMonitorTransaction when a tx times out. Subclasses TimeoutError so existing
+ * `instanceof TimeoutError` checks keep working, while carrying the fees-per-gas ladder for diagnostics.
+ */
+export class L1TxTimeoutError extends TimeoutError {
+  constructor(
+    message: string,
+    public readonly txState: TimedOutTxState,
+  ) {
+    super(message);
+  }
+}

package/src/l1_tx_utils/utils.ts

@@ -0,0 +1,15 @@
+import { compactArray } from '@aztec-labs/foundation/collection';
+import type { ContractFunctionExecutionError } from 'viem';
+
+export function tryGetCustomErrorNameContractFunction(err: ContractFunctionExecutionError) {
+  return compactArray([err.shortMessage, ...(err.metaMessages ?? []).slice(0, 2).map(s => s.trim())]).join(' ');
+}
+
+/*
+ * Returns cost of calldata usage in Ethereum.
+ * @param data - Calldata.
+ * @returns 4 for each zero byte, 16 for each nonzero.
+ */
+export function getCalldataGasUsage(data: Uint8Array) {
+  return data.filter(byte => byte === 0).length * 4 + data.filter(byte => byte !== 0).length * 16;
+}

package/src/l1_types.ts

@@ -0,0 +1,6 @@
+import type { Buffer32 } from '@aztec-labs/foundation/buffer';
+
+export type L1BlockId = {
+  l1BlockNumber: bigint;
+  l1BlockHash: Buffer32;
+};

package/src/publisher_manager.ts

@@ -0,0 +1,239 @@
+import { pick } from '@aztec-labs/foundation/collection';
+import { type Logger, type LoggerBindings, createLogger } from '@aztec-labs/foundation/log';
+import { RunningPromise } from '@aztec-labs/foundation/running-promise';
+
+import { Multicall3 } from './contracts/multicall.js';
+import { L1TxUtils, TxUtilsState } from './l1_tx_utils/index.js';
+
+// Defines the order in which we prioritise publishers based on their state (first is better)
+const sortOrder = [
+  // Always prefer sending from idle publishers
+  TxUtilsState.IDLE,
+  // Then from publishers that have sent a tx and it got mined
+  TxUtilsState.MINED,
+  // Then from publishers that have sent a tx but it's in-flight
+  TxUtilsState.SPEED_UP,
+  TxUtilsState.SENT,
+  // We leave cancelled and not-mined states for last, since these represent failures to mines and could be problematic
+  TxUtilsState.CANCELLED,
+  TxUtilsState.NOT_MINED,
+];
+
+// Which states represent a busy publisher that we should avoid if possible
+const busyStates: TxUtilsState[] = [
+  TxUtilsState.SENT,
+  TxUtilsState.SPEED_UP,
+  TxUtilsState.CANCELLED,
+  TxUtilsState.NOT_MINED,
+];
+
+export type PublisherFilter<UtilsType extends L1TxUtils> = (utils: UtilsType) => boolean;
+
+/** Config accepted by PublisherManager. */
+type PublisherManagerConfig = {
+  publisherAllowInvalidStates?: boolean;
+  publisherFundingThreshold?: bigint;
+  publisherFundingAmount?: bigint;
+};
+
+export class PublisherManager<UtilsType extends L1TxUtils = L1TxUtils> {
+  private log: Logger;
+  private config: PublisherManagerConfig;
+  private static readonly FUNDING_CHECK_INTERVAL_MS = 2 * 60 * 1000;
+  protected funder?: UtilsType;
+  protected readonly fundingPromise?: RunningPromise;
+  private started = false;
+
+  constructor(
+    protected publishers: UtilsType[],
+    config: PublisherManagerConfig,
+    opts?: { bindings?: LoggerBindings; funder?: UtilsType },
+  ) {
+    this.funder = opts?.funder;
+    this.log = createLogger('publisher:manager', opts?.bindings);
+    this.log.info(`PublisherManager initialized with ${publishers.length} publishers.`);
+    this.publishers = publishers;
+    this.config = pick(config, 'publisherAllowInvalidStates', 'publisherFundingThreshold', 'publisherFundingAmount');
+
+    const hasThreshold = this.config.publisherFundingThreshold !== undefined;
+    const hasAmount = this.config.publisherFundingAmount !== undefined;
+    if (hasThreshold !== hasAmount) {
+      this.log.warn(`Incomplete funding config: both publisherFundingThreshold and publisherFundingAmount must be set`);
+    }
+
+    if (this.funder) {
+      const funderAddress = this.funder.getSenderAddress();
+      if (publishers.some(p => p.getSenderAddress().equals(funderAddress))) {
+        this.log.error(`Funding account ${funderAddress} is also a publisher, disabling funding to avoid self-funding`);
+        this.funder = undefined;
+      }
+    }
+
+    if (this.funder && hasThreshold && hasAmount) {
+      this.fundingPromise = new RunningPromise(
+        () => this.triggerFundingIfNeeded(),
+        this.log,
+        PublisherManager.FUNDING_CHECK_INTERVAL_MS,
+      );
+    }
+  }
+
+  /**
+   * Clears any interrupted flag left by a previous {@link stop} so publishing works again after a restart,
+   * loads the state of all publishers and the funder, and starts periodic funding checks. Idempotent: a
+   * start while already started is a no-op, so it never re-runs `loadStateAndResumeMonitoring` (which
+   * would spawn a duplicate background monitor per pending nonce). Lifecycle calls are expected to be
+   * serialized by the caller.
+   */
+  public async start(): Promise<void> {
+    if (this.started) {
+      this.log.debug('PublisherManager already started, ignoring start');
+      return;
+    }
+
+    // Clear the interrupted flag set by a previous stop() so a restarted manager can publish again.
+    // On a first start this is a no-op (the flag is already clear).
+    this.publishers.forEach(pub => pub.restart());
+    this.funder?.restart();
+
+    await Promise.all([
+      ...this.publishers.map(pub => pub.loadStateAndResumeMonitoring()),
+      this.funder?.loadStateAndResumeMonitoring(),
+    ]);
+
+    this.fundingPromise?.start();
+    // Marked started only once fully up, so a start that failed to load state can be retried.
+    this.started = true;
+  }
+
+  /**
+   * Stops the funding loop, interrupts all publishers so no further L1 txs are sent, and waits (bounded)
+   * for their in-flight tx monitor loops to wind down. Idempotent, and the manager may be restarted
+   * afterwards via {@link start}, which clears the interrupted flag.
+   */
+  public async stop(): Promise<void> {
+    this.started = false;
+    await this.fundingPromise?.stop();
+    this.publishers.forEach(pub => pub.interrupt());
+    this.funder?.interrupt();
+    // Wait for in-flight tx monitor loops to observe the interrupt, so no L1 requests are still
+    // being issued after shutdown (e.g. against an anvil instance a test is about to tear down).
+    await Promise.all([
+      ...this.publishers.map(pub => pub.waitMonitoringStopped()),
+      this.funder?.waitMonitoringStopped(),
+    ]);
+  }
+
+  // Finds and prioritises available publishers based on
+  // 1. Validity as per the provided filter function
+  // 2. Validity based on the state the publisher is in
+  // 3. Priority based on state as defined by sortOrder
+  // 4. Then priority based on highest balance
+  // 5. Then priority based on least recently used
+  public async getAvailablePublisher(filter: PublisherFilter<UtilsType> = () => true): Promise<UtilsType> {
+    this.log.debug(`Getting available publisher`, {
+      publishers: this.publishers.map(p => ({
+        address: p.getSenderAddress(),
+        state: p.state,
+        lastMined: p.lastMinedAtBlockNumber,
+      })),
+    });
+
+    // Extract the valid publishers
+    let validPublishers = this.publishers.filter((pub: UtilsType) => !busyStates.includes(pub.state) && filter(pub));
+
+    // If none found but we allow invalid (busy) states, try again including them
+    if (validPublishers.length === 0 && this.config.publisherAllowInvalidStates) {
+      this.log.warn(`No valid publishers found. Trying again including invalid states.`);
+      validPublishers = this.publishers.filter(pub => filter(pub));
+    }
+
+    // Error if none found
+    if (validPublishers.length === 0) {
+      throw new Error(`Failed to find an available publisher.`);
+    }
+
+    // Get the balances
+    const publishersWithBalance = await Promise.all(
+      validPublishers.map(async pub => {
+        return { balance: await pub.getSenderBalance(), publisher: pub };
+      }),
+    );
+
+    // Discount unfunded publishers: a publisher with no ETH cannot send a tx, so it must never win
+    // selection regardless of how favourable its state or last-used time is. Fall back to the full
+    // set only if every candidate is unfunded, so behaviour is no worse than before.
+    let fundedPublishers = publishersWithBalance.filter(p => p.balance > 0n);
+    if (fundedPublishers.length === 0) {
+      this.log.warn(`All candidate publishers have zero balance; selecting from unfunded publishers.`);
+      fundedPublishers = publishersWithBalance;
+    }
+
+    // Sort based on state, then balance, then time since last use
+    const sortedPublishers = fundedPublishers.sort((a, b) => {
+      const stateComparison = sortOrder.indexOf(a.publisher.state) - sortOrder.indexOf(b.publisher.state);
+      if (stateComparison !== 0) {
+        return stateComparison;
+      }
+      const balanceComparison = Number(b.balance - a.balance);
+      if (balanceComparison !== 0) {
+        return balanceComparison;
+      }
+      const lastUsedComparison = Number(
+        (a.publisher.lastMinedAtBlockNumber ?? 0n) - (b.publisher.lastMinedAtBlockNumber ?? 0n),
+      );
+      return lastUsedComparison;
+    });
+
+    return sortedPublishers[0].publisher;
+  }
+
+  /** Check all publisher balances and fund those below threshold. */
+  private async triggerFundingIfNeeded(): Promise<void> {
+    const { funder, config } = this;
+    if (!funder || config.publisherFundingThreshold === undefined || config.publisherFundingAmount === undefined) {
+      return;
+    }
+
+    const allBalances = await Promise.all(
+      this.publishers.map(async pub => ({ balance: await pub.getSenderBalance(), publisher: pub })),
+    );
+    const lowBalance = allBalances.filter(p => p.balance < config.publisherFundingThreshold!);
+    if (lowBalance.length === 0) {
+      return;
+    }
+
+    const fundingAmount = config.publisherFundingAmount!;
+    const funderBalance = await funder.getSenderBalance();
+
+    if (funderBalance < 10n * fundingAmount) {
+      this.log.warn(`Funding account balance is low`, { funderBalance, threshold: 10n * fundingAmount });
+    }
+    const affordableCount = Number(funderBalance / fundingAmount);
+    if (affordableCount === 0) {
+      this.log.error(`Funding account balance too low to fund any publisher`, { funderBalance, fundingAmount });
+      return;
+    }
+    if (affordableCount < lowBalance.length) {
+      this.log.warn(`Funder can only afford ${affordableCount}/${lowBalance.length} publishers`, {
+        funderBalance,
+        fundingAmount,
+      });
+    }
+
+    const toFund = lowBalance.slice(0, affordableCount).map(p => p.publisher);
+    await this.fundPublishers(toFund);
+  }
+
+  /** Fund publishers via a single Multicall3 aggregate3Value transaction. */
+  private async fundPublishers(publishers: UtilsType[]): Promise<void> {
+    const fundingAmount = this.config.publisherFundingAmount!;
+    const calls = publishers.map(pub => ({
+      to: pub.getSenderAddress().toString(),
+      value: fundingAmount,
+    }));
+
+    await Multicall3.forwardValue(calls, this.funder!, this.log);
+    this.log.info(`Funded ${publishers.length} publishers`);
+  }
+}