@aztec-labs/ethereum 6.0.0-nightly.20260829

package/dest/l1_tx_utils/l1_tx_utils.js

@@ -0,0 +1,720 @@
+import { RollupAbi } from '@aztec/l1-artifacts/RollupAbi';
+import { maxBigint } from '@aztec-labs/foundation/bigint';
+import { merge, pick } from '@aztec-labs/foundation/collection';
+import { InterruptError, TimeoutError } from '@aztec-labs/foundation/error';
+import { createLogger } from '@aztec-labs/foundation/log';
+import { Semaphore } from '@aztec-labs/foundation/queue';
+import { makeBackoff, retry, retryUntil } from '@aztec-labs/foundation/retry';
+import { sleep } from '@aztec-labs/foundation/sleep';
+import { DateProvider } from '@aztec-labs/foundation/timer';
+import pickBy from 'lodash.pickby';
+import { formatGwei, serializeTransaction } from 'viem';
+import { formatViemError } from '../utils.js';
+import { l1TxUtilsConfigMappings } from './config.js';
+import { MAX_L1_TX_LIMIT } from './constants.js';
+import { ReadOnlyL1TxUtils } from './readonly_l1_tx_utils.js';
+import { createDelayer, wrapClientWithDelayer } from './tx_delayer.js';
+import { DroppedTransactionError, L1TxTimeoutError, TerminalTxUtilsState, TxUtilsState, UnknownMinedTxError } from './types.js';
+const MAX_L1_TX_STATES = 32;
+// Backoff (in seconds) for retrying the read-only RPC calls that prepare a tx cancellation. A
+// cancellation is fired in the background after a tx times out and is important (it frees the stuck
+// nonce), so a transient RPC failure while reading the pending nonce or gas price must not abandon it.
+const CANCELLATION_PREP_RETRY_BACKOFF_S = [
+    1,
+    2,
+    4,
+    8
+];
+export class L1TxUtils extends ReadOnlyL1TxUtils {
+    client;
+    address;
+    signer;
+    store;
+    metrics;
+    txs;
+    /** Last nonce successfully sent to the chain. Used as a lower bound when a fallback RPC node returns a stale count. */ lastSentNonce;
+    /** Mutex to prevent concurrent sendTransaction calls from racing on the same nonce. */ sendMutex;
+    /** Tx delayer for testing. Only set when enableDelayer config is true. */ delayer;
+    /** KZG instance for blob operations. */ kzg;
+    constructor(client, address, signer, logger = createLogger('ethereum:publisher'), dateProvider = new DateProvider(), config, debugMaxGasLimit = false, store, metrics, kzg, delayer){
+        super(client, logger, dateProvider, config, debugMaxGasLimit), this.client = client, this.address = address, this.signer = signer, this.store = store, this.metrics = metrics, this.txs = [], this.sendMutex = new Semaphore(1);
+        this.kzg = kzg;
+        // Set up delayer: use provided one or create new
+        if (config?.enableDelayer && config?.ethereumSlotDuration) {
+            this.delayer = delayer ?? this.createDelayer({
+                ethereumSlotDuration: config.ethereumSlotDuration
+            }, logger.getBindings());
+            this.client = wrapClientWithDelayer(this.client, this.delayer);
+            if (config.txDelayerMaxInclusionTimeIntoSlot !== undefined) {
+                this.delayer.setMaxInclusionTimeIntoSlot(config.txDelayerMaxInclusionTimeIntoSlot);
+            }
+        } else if (delayer) {
+            // Delayer provided but enableDelayer not set — just store it without wrapping
+            logger.warn('Delayer provided but enableDelayer config is not set; delayer will not be used');
+            this.delayer = delayer;
+        }
+    }
+    get state() {
+        return this.txs.at(-1)?.status ?? TxUtilsState.IDLE;
+    }
+    get lastMinedAtBlockNumber() {
+        const minedBlockNumbers = this.txs.map((tx)=>tx.receipt?.blockNumber).filter((bn)=>bn !== undefined);
+        return minedBlockNumbers.length === 0 ? undefined : maxBigint(...minedBlockNumbers);
+    }
+    async updateState(l1TxState, newState, l1Timestamp) {
+        const oldState = l1TxState.status;
+        l1TxState.status = newState;
+        const sender = this.getSenderAddress().toString();
+        this.logger.debug(`Tx state changed from ${TxUtilsState[oldState]} to ${TxUtilsState[newState]} for nonce ${l1TxState.nonce} account ${sender}`);
+        // Record metrics
+        if (newState === TxUtilsState.MINED && l1Timestamp !== undefined) {
+            this.metrics?.recordMinedTx(l1TxState, new Date(l1Timestamp));
+        } else if (newState === TxUtilsState.NOT_MINED) {
+            this.metrics?.recordDroppedTx(l1TxState);
+            // The tx was dropped: the chain nonce reverted to l1TxState.nonce, so our lower bound is
+            // no longer valid. Clear it so the next send fetches the real nonce from the chain.
+            if (this.lastSentNonce === l1TxState.nonce) {
+                this.lastSentNonce = undefined;
+            }
+        }
+        // Update state in the store
+        await this.store?.saveState(sender, l1TxState).catch((err)=>this.logger.error('Failed to persist L1 tx state', err));
+    }
+    updateConfig(newConfig) {
+        this.config = merge(this.config, newConfig);
+        this.logger.info('Updated L1TxUtils config', pickBy(newConfig, (_, key)=>key in l1TxUtilsConfigMappings));
+    }
+    /**
+   * Clears the cached `lastSentNonce` so the next `sendTransaction` call fetches the real
+   * nonce from the chain. Call this after an L1 reorg to prevent stale nonce references.
+   */ resetNonce() {
+        this.lastSentNonce = undefined;
+    }
+    getSenderAddress() {
+        return this.address;
+    }
+    getSenderBalance() {
+        return this.client.getBalance({
+            address: this.getSenderAddress().toString()
+        });
+    }
+    /**
+   * Rehydrates transaction states from the store and resumes monitoring for pending transactions.
+   * This should be called on startup to restore state and resume monitoring of any in-flight transactions.
+   */ async loadStateAndResumeMonitoring() {
+        if (!this.store) {
+            return;
+        }
+        const account = this.getSenderAddress().toString();
+        const loadedStates = await this.store.loadStates(account);
+        if (loadedStates.length === 0) {
+            this.logger.debug(`No states to rehydrate for account ${account}`);
+            return;
+        }
+        // Clean up excess states if we have more than MAX_L1_TX_STATES
+        if (loadedStates.length > MAX_L1_TX_STATES) {
+            this.logger.warn(`Found ${loadedStates.length} tx states for account ${account}, pruning to most recent ${MAX_L1_TX_STATES}`);
+            // Keep only the most recent MAX_L1_TX_STATES
+            const statesToKeep = loadedStates.slice(-MAX_L1_TX_STATES);
+            const statesToDelete = loadedStates.slice(0, -MAX_L1_TX_STATES);
+            // Batch delete old states in a transaction for efficiency
+            const idsToDelete = statesToDelete.map((s)=>s.id);
+            await this.store.deleteState(account, ...idsToDelete);
+            this.txs = statesToKeep;
+            this.logger.info(`Cleaned up ${statesToDelete.length} old tx states, kept ${statesToKeep.length} for account ${account}`);
+        } else {
+            // Convert loaded states (which have id) to the txs format
+            this.txs = loadedStates;
+            this.logger.info(`Rehydrated ${loadedStates.length} tx states for account ${account}`);
+        }
+        // Find all pending states and resume monitoring
+        const pendingStates = this.txs.filter((state)=>!TerminalTxUtilsState.includes(state.status));
+        if (pendingStates.length === 0) {
+            return;
+        }
+        this.logger.info(`Resuming monitoring for ${pendingStates.length} pending transactions for account ${account}`, {
+            txs: pendingStates.map((s)=>({
+                    id: s.id,
+                    nonce: s.nonce,
+                    status: TxUtilsState[s.status]
+                }))
+        });
+        for (const state of pendingStates){
+            void this.monitorTransaction(state).catch((err)=>{
+                this.logger.error(`Error monitoring rehydrated tx with nonce ${state.nonce} for account ${account}`, formatViemError(err), {
+                    nonce: state.nonce,
+                    account
+                });
+            });
+        }
+    }
+    async signTransaction(txRequest) {
+        const signature = await this.signer(txRequest, this.getSenderAddress());
+        return serializeTransaction(txRequest, signature);
+    }
+    async prepareSignedTransaction(txData) {
+        const txRequest = await this.client.prepareTransactionRequest(txData);
+        return await this.signTransaction(txRequest);
+    }
+    async checkInterruptedOrTimedOut(gasConfig) {
+        if (this.interrupted) {
+            throw new InterruptError(`Transaction sending is interrupted`);
+        }
+        const now = new Date(await this.getL1Timestamp());
+        if (gasConfig.txTimeoutAt && now > gasConfig.txTimeoutAt) {
+            throw new TimeoutError(`Transaction timed out before sending (now ${now.toISOString()} > timeoutAt ${gasConfig.txTimeoutAt.toISOString()})`);
+        }
+        return now;
+    }
+    /**
+   * Sends a transaction with gas estimation and pricing
+   * @param request - The transaction request (to, data, value)
+   * @param gasConfig - Optional gas configuration
+   * @returns The transaction hash and parameters used
+   */ async sendTransaction(request, gasConfigOverrides, blobInputs, stateChange = TxUtilsState.SENT) {
+        try {
+            const gasConfig = merge(this.config, gasConfigOverrides);
+            const account = this.getSenderAddress().toString();
+            // Fail fast before doing any work (gas estimation, balance check) if we've been interrupted
+            // or if the caller's deadline has already passed. The same check is repeated after gas
+            // estimation in case it took long enough to push us past the deadline.
+            await this.checkInterruptedOrTimedOut(gasConfig);
+            let gasLimit;
+            if (this.debugMaxGasLimit) {
+                gasLimit = MAX_L1_TX_LIMIT;
+            } else if (gasConfig.gasLimit) {
+                gasLimit = gasConfig.gasLimit;
+            } else {
+                gasLimit = await this.estimateGas(account, request, gasConfig);
+            }
+            this.logger.trace(`Computed gas limit ${gasLimit}`, {
+                gasLimit,
+                ...request
+            });
+            const feesPerGas = await this.getFeesPerGas(gasConfig, !!blobInputs);
+            const now = await this.checkInterruptedOrTimedOut(gasConfig);
+            let txHash;
+            let nonce;
+            let baseState;
+            await this.sendMutex.acquire();
+            try {
+                const chainNonce = await this.client.getTransactionCount({
+                    address: account,
+                    blockTag: 'pending'
+                });
+                // If a fallback RPC node returns a stale count (lower than what we last sent), use our
+                // local lower bound to avoid sending a duplicate of an already-pending transaction.
+                nonce = this.lastSentNonce !== undefined && chainNonce <= this.lastSentNonce ? this.lastSentNonce + 1 : chainNonce;
+                baseState = {
+                    request,
+                    gasLimit,
+                    blobInputs,
+                    feesPerGas,
+                    nonce
+                };
+                const txData = this.makeTxData(baseState, {
+                    isCancelTx: false
+                });
+                const signedRequest = await this.prepareSignedTransaction(txData);
+                txHash = await this.client.sendRawTransaction({
+                    serializedTransaction: signedRequest
+                });
+                this.lastSentNonce = nonce;
+            } finally{
+                this.sendMutex.release();
+            }
+            // Create the new state for monitoring
+            const l1TxState = {
+                ...baseState,
+                id: await this.store?.consumeNextStateId(account) ?? Math.max(...this.txs.map((tx)=>tx.id), -1) + 1,
+                txHashes: [
+                    txHash
+                ],
+                cancelTxHashes: [],
+                status: TxUtilsState.IDLE,
+                txConfigOverrides: gasConfigOverrides ?? {},
+                sentAtL1Ts: now,
+                lastSentAtL1Ts: now,
+                feesPerGasHistory: [
+                    baseState.feesPerGas
+                ]
+            };
+            // And persist it
+            await this.updateState(l1TxState, stateChange);
+            await this.store?.saveBlobs(account, l1TxState.id, blobInputs);
+            this.txs.push(l1TxState);
+            // Clean up stale states
+            if (this.txs.length > MAX_L1_TX_STATES) {
+                const removed = this.txs.shift();
+                if (removed && this.store) {
+                    await this.store.deleteState(account, removed.id);
+                }
+            }
+            this.logger.info(`Sent L1 transaction ${txHash}`, {
+                to: request.to,
+                value: request.value,
+                nonce,
+                account,
+                sentAt: now,
+                gasLimit,
+                maxFeePerGas: formatGwei(feesPerGas.maxFeePerGas),
+                maxPriorityFeePerGas: formatGwei(feesPerGas.maxPriorityFeePerGas),
+                ...feesPerGas.maxFeePerBlobGas && {
+                    maxFeePerBlobGas: formatGwei(feesPerGas.maxFeePerBlobGas)
+                },
+                isBlobTx: !!blobInputs,
+                txConfig: gasConfigOverrides
+            });
+            return {
+                txHash,
+                state: l1TxState
+            };
+        } catch (err) {
+            const viemError = formatViemError(err, request.abi);
+            this.logger.error(`Failed to send L1 transaction: ${viemError.message}`, viemError, {
+                request: pick(request, 'to', 'value')
+            });
+            throw viemError;
+        }
+    }
+    async tryGetTxReceipt(txHashes, nonce, isCancelTx) {
+        for (const hash of txHashes){
+            try {
+                const receipt = await this.client.getTransactionReceipt({
+                    hash
+                });
+                if (receipt) {
+                    const account = this.getSenderAddress().toString();
+                    const what = isCancelTx ? 'Cancellation L1 transaction' : 'L1 transaction';
+                    if (receipt.status === 'reverted') {
+                        this.logger.warn(`${what} ${hash} with nonce ${nonce} reverted`, {
+                            receipt,
+                            nonce,
+                            account
+                        });
+                    } else {
+                        this.logger.info(`${what} ${hash} with nonce ${nonce} mined`, {
+                            receipt,
+                            nonce,
+                            account
+                        });
+                    }
+                    return receipt;
+                }
+            } catch (err) {
+                if (err instanceof Error && err.name === 'TransactionReceiptNotFoundError') {
+                    continue;
+                } else {
+                    this.logger.error(`Error getting receipt for tx ${hash}`, err);
+                    continue;
+                }
+            }
+        }
+    }
+    /**
+   * Returns whether a given tx should be considered as timed out and no longer monitored.
+   * Relies on the txTimeout setting for user txs, and on the txCancellationTimeout for cancel txs.
+   * @remarks We check against the latestBlockTimestamp as opposed to the current time to avoid a race condition where
+   * the tx is mined in a block with the same timestamp as txTimeoutAt, but our execution node has not yet processed it,
+   * or the loop here has not yet checked the tx before that timeout.
+   */ isTxTimedOut(state, l1Timestamp) {
+        const account = this.getSenderAddress().toString();
+        const { nonce } = state;
+        const txConfig = merge(this.config, state.txConfigOverrides);
+        const { txTimeoutAt, txTimeoutMs, maxSpeedUpAttempts } = txConfig;
+        const isCancelTx = state.cancelTxHashes.length > 0;
+        this.logger.trace(`Tx timeout check for ${account} with nonce ${nonce}`, {
+            nonce,
+            account,
+            l1Timestamp,
+            lastAttemptSent: state.lastSentAtL1Ts.getTime(),
+            initialTxTime: state.sentAtL1Ts.getTime(),
+            now: this.dateProvider.now(),
+            txTimeoutAt,
+            txTimeoutMs,
+            interrupted: this.interrupted
+        });
+        if (this.interrupted) {
+            this.logger.warn(`Tx monitoring interrupted during nonce ${nonce} for ${account} check`, {
+                nonce,
+                account
+            });
+            return true;
+        }
+        if (isCancelTx) {
+            // Note that we check against the lastSentAt time for cancellations, since we time them out
+            // after the last attempt to submit them, not the initial time.
+            const attempts = state.cancelTxHashes.length;
+            return attempts > maxSpeedUpAttempts && state.lastSentAtL1Ts.getTime() + txConfig.txCancellationFinalTimeoutMs <= l1Timestamp;
+        }
+        return txTimeoutAt !== undefined && l1Timestamp >= txTimeoutAt.getTime() || txTimeoutMs !== undefined && txTimeoutMs > 0 && l1Timestamp - state.sentAtL1Ts.getTime() >= txTimeoutMs;
+    }
+    /**
+   * Monitors a transaction until completion, handling speed-ups if needed
+   */ async monitorTransaction(state) {
+        const { nonce, gasLimit, blobInputs, txConfigOverrides: gasConfigOverrides } = state;
+        const gasConfig = merge(this.config, gasConfigOverrides);
+        const { maxSpeedUpAttempts, stallTimeMs } = gasConfig;
+        const isCancelTx = state.cancelTxHashes.length > 0;
+        const txHashes = isCancelTx ? state.cancelTxHashes : state.txHashes;
+        const isBlobTx = !!blobInputs;
+        const account = this.getSenderAddress().toString();
+        const initialTxHash = txHashes[0];
+        let currentTxHash = txHashes.at(-1);
+        let l1Timestamp = 0;
+        while(true){
+            try {
+                l1Timestamp = await this.getL1Timestamp();
+            } catch (err) {
+                // A transient RPC failure here must not abort monitoring with a rejection: callers that
+                // fire this loop in the background would surface it as an unhandled rejection (e.g. when a
+                // test tears down its L1 node while a monitor iteration is in flight). Exit quietly if we
+                // are shutting down, otherwise retry on the next interval.
+                if (this.interrupted) {
+                    break;
+                }
+                this.logger.error(`Error fetching L1 timestamp while monitoring tx ${currentTxHash}`, err, {
+                    nonce,
+                    account
+                });
+                await sleep(gasConfig.checkIntervalMs);
+                continue;
+            }
+            try {
+                const timePassed = l1Timestamp - state.lastSentAtL1Ts.getTime();
+                const [currentNonce, pendingNonce] = await Promise.all([
+                    this.client.getTransactionCount({
+                        address: account,
+                        blockTag: 'latest'
+                    }),
+                    this.client.getTransactionCount({
+                        address: account,
+                        blockTag: 'pending'
+                    })
+                ]);
+                // If the current nonce on our account is greater than our transaction's nonce then a tx with the same nonce has been mined.
+                if (currentNonce > nonce) {
+                    // We try getting the receipt twice, since sometimes anvil fails to return it if the tx has just been mined
+                    const receipt = await this.tryGetTxReceipt(state.cancelTxHashes, nonce, true) ?? await this.tryGetTxReceipt(state.txHashes, nonce, false) ?? await sleep(500) ?? await this.tryGetTxReceipt(state.cancelTxHashes, nonce, true) ?? await this.tryGetTxReceipt(state.txHashes, nonce, false);
+                    if (receipt) {
+                        state.receipt = receipt;
+                        await this.updateState(state, TxUtilsState.MINED, l1Timestamp);
+                        return receipt;
+                    }
+                    // If we get here then we have checked all of our tx versions and not found anything.
+                    // We should consider the nonce as MINED
+                    await this.updateState(state, TxUtilsState.MINED, l1Timestamp);
+                    throw new UnknownMinedTxError(nonce, account);
+                }
+                // If this is a cancel tx and its nonce is no longer on the mempool, we consider it dropped and stop monitoring
+                // If it is a regular tx, we let the loop speed it up after the stall time
+                if (isCancelTx && pendingNonce <= nonce && timePassed >= gasConfig.txUnseenConsideredDroppedMs) {
+                    this.logger.warn(`Cancellation tx with nonce ${nonce} for account ${account} has been dropped from the visible mempool`, {
+                        nonce,
+                        account,
+                        pendingNonce,
+                        timePassed
+                    });
+                    await this.updateState(state, TxUtilsState.NOT_MINED);
+                    throw new DroppedTransactionError(nonce, account);
+                }
+                // Break if the tx has timed out (ie expired)
+                if (this.isTxTimedOut(state, l1Timestamp)) {
+                    break;
+                }
+                // Speed up the transaction if it appears to be stuck (exceeded stall time and still have retry attempts)
+                const attempts = txHashes.length;
+                if (timePassed >= stallTimeMs && attempts <= maxSpeedUpAttempts) {
+                    const newFeesPerGas = await this.getFeesPerGas(gasConfig, isBlobTx, attempts, state.feesPerGas);
+                    state.feesPerGas = newFeesPerGas;
+                    state.feesPerGasHistory?.push(newFeesPerGas);
+                    this.logger.debug(`Tx ${currentTxHash} with nonce ${nonce} from ${account} appears stuck. ` + `Attempting speed-up ${attempts}/${maxSpeedUpAttempts} ` + `with new priority fee ${formatGwei(newFeesPerGas.maxPriorityFeePerGas)} gwei.`, {
+                        account,
+                        nonce,
+                        maxFeePerGas: formatGwei(newFeesPerGas.maxFeePerGas),
+                        maxPriorityFeePerGas: formatGwei(newFeesPerGas.maxPriorityFeePerGas),
+                        ...newFeesPerGas.maxFeePerBlobGas && {
+                            maxFeePerBlobGas: formatGwei(newFeesPerGas.maxFeePerBlobGas)
+                        }
+                    });
+                    const txData = this.makeTxData(state, {
+                        isCancelTx
+                    });
+                    const signedRequest = await this.prepareSignedTransaction(txData);
+                    const newHash = await this.client.sendRawTransaction({
+                        serializedTransaction: signedRequest
+                    });
+                    this.logger.verbose(`Sent L1 speed-up tx ${newHash} replacing ${currentTxHash} for nonce ${nonce} from ${account}`, {
+                        nonce,
+                        account,
+                        gasLimit,
+                        maxFeePerGas: formatGwei(newFeesPerGas.maxFeePerGas),
+                        maxPriorityFeePerGas: formatGwei(newFeesPerGas.maxPriorityFeePerGas),
+                        txConfig: state.txConfigOverrides,
+                        ...newFeesPerGas.maxFeePerBlobGas && {
+                            maxFeePerBlobGas: formatGwei(newFeesPerGas.maxFeePerBlobGas)
+                        }
+                    });
+                    currentTxHash = newHash;
+                    txHashes.push(currentTxHash);
+                    state.lastSentAtL1Ts = new Date(l1Timestamp);
+                    await this.updateState(state, isCancelTx ? TxUtilsState.CANCELLED : TxUtilsState.SPEED_UP);
+                    await sleep(gasConfig.checkIntervalMs);
+                    continue;
+                }
+                this.logger.debug(`Tx ${currentTxHash} from ${account} with nonce ${nonce} still pending after ${timePassed}ms`, {
+                    account,
+                    nonce,
+                    pendingNonce,
+                    attempts,
+                    timePassed,
+                    isBlobTx,
+                    isCancelTx,
+                    ...pick(state.feesPerGas, 'maxFeePerGas', 'maxPriorityFeePerGas', 'maxFeePerBlobGas'),
+                    ...pick(gasConfig, 'txUnseenConsideredDroppedMs', 'txCancellationFinalTimeoutMs', 'maxSpeedUpAttempts', 'stallTimeMs', 'txTimeoutAt', 'txTimeoutMs')
+                });
+                await sleep(gasConfig.checkIntervalMs);
+            } catch (err) {
+                if (err instanceof DroppedTransactionError || err instanceof UnknownMinedTxError) {
+                    throw err;
+                }
+                const viemError = formatViemError(err);
+                this.logger.error(`Error while monitoring L1 tx ${currentTxHash}`, viemError, {
+                    nonce,
+                    account
+                });
+                await sleep(gasConfig.checkIntervalMs);
+            }
+        }
+        // Oh no, the transaction has timed out!
+        if (isCancelTx || !gasConfig.cancelTxOnTimeout) {
+            await this.updateState(state, TxUtilsState.NOT_MINED);
+        } else {
+            // Otherwise we fire the cancellation without awaiting to avoid blocking the caller,
+            // and monitor it in the background so we can speed it up as needed.
+            void this.attemptTxCancellation(state).catch(async (err)=>{
+                await this.updateState(state, TxUtilsState.NOT_MINED);
+                this.logger.error(`Failed to send cancellation for timed out tx ${initialTxHash} with nonce ${nonce}`, err, {
+                    account,
+                    nonce,
+                    initialTxHash
+                });
+            });
+        }
+        const what = isCancelTx ? 'Cancellation L1' : 'L1';
+        this.logger.warn(`${what} transaction ${initialTxHash} with nonce ${nonce} from ${account} timed out`, {
+            initialTxHash,
+            currentTxHash,
+            nonce,
+            account,
+            txTimeoutAt: gasConfig.txTimeoutAt?.getTime(),
+            txTimeoutMs: gasConfig.txTimeoutMs,
+            txInitialTime: state.sentAtL1Ts.getTime(),
+            l1Timestamp,
+            now: this.dateProvider.now(),
+            attempts: txHashes.length - 1,
+            isInterrupted: this.interrupted
+        });
+        throw new TimeoutError(`L1 transaction ${initialTxHash} timed out`);
+    }
+    /**
+   * Creates tx data to be signed by viem signTransaction method, using the state as input.
+   * If isCancelTx is true, creates a 0-value tx to self with 21k gas and no data instead,
+   * and an empty blob input if the original tx also had blobs.
+   */ makeTxData(state, opts) {
+        const { request, gasLimit, blobInputs, feesPerGas, nonce } = state;
+        const isBlobTx = blobInputs !== undefined;
+        const baseTxOpts = {
+            nonce,
+            ...pick(feesPerGas, 'maxFeePerGas', 'maxPriorityFeePerGas')
+        };
+        if (opts.isCancelTx) {
+            const baseTxData = {
+                to: this.getSenderAddress().toString(),
+                value: 0n,
+                data: '0x',
+                gas: 21_000n,
+                ...baseTxOpts
+            };
+            return isBlobTx ? {
+                ...baseTxData,
+                ...this.makeEmptyBlobInputs(feesPerGas.maxFeePerBlobGas)
+            } : baseTxData;
+        }
+        const baseTxData = {
+            ...request,
+            ...baseTxOpts,
+            gas: gasLimit
+        };
+        return blobInputs ? {
+            ...baseTxData,
+            ...blobInputs,
+            maxFeePerBlobGas: feesPerGas.maxFeePerBlobGas
+        } : baseTxData;
+    }
+    /** Returns when all monitor loops have stopped. */ async waitMonitoringStopped(timeoutSeconds = 10) {
+        const account = this.getSenderAddress().toString();
+        await retryUntil(()=>this.txs.every((tx)=>TerminalTxUtilsState.includes(tx.status)), `monitoring stopped for ${account}`, timeoutSeconds, 0.1).catch(()=>this.logger.warn(`Timeout waiting for monitoring loops to stop for ${account}`));
+    }
+    /**
+   * Sends a transaction and monitors it until completion
+   * @param request - The transaction request (to, data, value)
+   * @param gasConfig - Optional gas configuration
+   * @returns The receipt of the successful transaction
+   */ async sendAndMonitorTransaction(request, gasConfig, blobInputs) {
+        const { state } = await this.sendTransaction(request, gasConfig, blobInputs);
+        try {
+            const receipt = await this.monitorTransaction(state);
+            return {
+                receipt,
+                state
+            };
+        } catch (err) {
+            if (err instanceof TimeoutError) {
+                // Snapshot the ladder now: the fire-and-forget cancellation mutates state.feesPerGas moments later.
+                throw new L1TxTimeoutError(err.message, {
+                    feesPerGasHistory: state.feesPerGasHistory ? [
+                        ...state.feesPerGasHistory
+                    ] : undefined,
+                    finalFeesPerGas: state.feesPerGas,
+                    attempts: state.txHashes.length,
+                    nonce: state.nonce,
+                    gasLimit: state.gasLimit
+                });
+            }
+            throw err;
+        }
+    }
+    async simulate(request, _blockOverrides = {}, stateOverrides = [], abi = RollupAbi, _gasConfig) {
+        const blockOverrides = {
+            ..._blockOverrides
+        };
+        const gasConfig = merge(this.config, _gasConfig);
+        // Fee fields are deliberately omitted. Supplying them makes the node apply the EIP-1559 upfront funds
+        // check (sender balance >= gas * maxFeePerGas) against the worst-case gas cap below, which rejects the
+        // whole simulation request before any execution. Omitted fee fields default to a zero gas price.
+        const call = {
+            to: request.to,
+            data: request.data,
+            from: request.from ?? this.getSenderAddress().toString(),
+            gas: request.gas ?? MAX_L1_TX_LIMIT
+        };
+        if (!request.gas && !gasConfig.ignoreBlockGasLimit) {
+            // MAX_L1_TX_LIMIT is set as call.gas, ensure block gasLimit is sufficient
+            blockOverrides.gasLimit = MAX_L1_TX_LIMIT;
+        }
+        return await this._simulate(call, blockOverrides, stateOverrides, gasConfig, abi);
+    }
+    /**
+   * Attempts to cancel a transaction by sending a 0-value tx to self with same nonce but higher gas prices
+   * Only sends the cancellation if the original tx is still pending, not if it was dropped
+   * @returns The hash of the cancellation transaction
+   */ async attemptTxCancellation(state) {
+        const isBlobTx = state.blobInputs !== undefined;
+        const { nonce, feesPerGas: previousFeesPerGas } = state;
+        const account = this.getSenderAddress().toString();
+        // Do not send cancellation if interrupted
+        if (this.interrupted) {
+            this.logger.warn(`Not sending cancellation for L1 tx from account ${account} with nonce ${nonce} as interrupted`, {
+                nonce,
+                account
+            });
+            await this.updateState(state, TxUtilsState.NOT_MINED);
+            return;
+        }
+        // Resolve the pending nonce and cancellation fees per gas up front. These are read-only RPC calls, so
+        // they are safe to retry; a transient RPC failure here must not permanently abandon the cancellation
+        // (which would leave the nonce stuck and the tx state stranded short of CANCELLED). We retry with a
+        // real backoff before giving up, unlike getFeesPerGas's tight internal retry which can be exhausted by
+        // a brief node hiccup. The retried block performs no state-changing send, so retrying cannot
+        // double-send the cancellation tx.
+        const { currentNonce, cancelFeesPerGas } = await retry(async ()=>{
+            const currentNonce = await this.client.getTransactionCount({
+                address: account,
+                blockTag: 'pending'
+            });
+            if (currentNonce >= nonce) {
+                // Get fees per gas with higher priority fee for cancellation
+                const cancelFeesPerGas = await this.getFeesPerGas({
+                    ...this.config,
+                    // Use high bump for cancellation to ensure it replaces the original tx
+                    priorityFeeRetryBumpPercentage: 150
+                }, isBlobTx, state.txHashes.length, previousFeesPerGas);
+                return {
+                    currentNonce,
+                    cancelFeesPerGas
+                };
+            }
+            return {
+                currentNonce,
+                cancelFeesPerGas: undefined
+            };
+        }, `Preparing cancellation for L1 tx from account ${account} with nonce ${nonce}`, makeBackoff(CANCELLATION_PREP_RETRY_BACKOFF_S), this.logger);
+        if (cancelFeesPerGas === undefined) {
+            this.logger.verbose(`Not sending cancellation for L1 tx from account ${account} with nonce ${nonce} as it is dropped`, {
+                nonce,
+                account,
+                currentNonce
+            });
+            await this.updateState(state, TxUtilsState.NOT_MINED);
+            return;
+        }
+        const { maxFeePerGas, maxPriorityFeePerGas, maxFeePerBlobGas } = cancelFeesPerGas;
+        this.logger.verbose(`Attempting to cancel L1 ${isBlobTx ? 'blob' : 'vanilla'} transaction from account ${account} with nonce ${nonce} after time out`, {
+            maxFeePerGas: formatGwei(maxFeePerGas),
+            maxPriorityFeePerGas: formatGwei(maxPriorityFeePerGas),
+            ...maxFeePerBlobGas && {
+                maxFeePerBlobGas: formatGwei(maxFeePerBlobGas)
+            }
+        });
+        // Send 0-value tx to self with higher gas price
+        state.feesPerGas = cancelFeesPerGas;
+        state.lastSentAtL1Ts = new Date(await this.getL1Timestamp());
+        const txData = this.makeTxData(state, {
+            isCancelTx: true
+        });
+        const signedRequest = await this.prepareSignedTransaction(txData);
+        const cancelTxHash = await this.client.sendRawTransaction({
+            serializedTransaction: signedRequest
+        });
+        state.cancelTxHashes.push(cancelTxHash);
+        await this.updateState(state, TxUtilsState.CANCELLED);
+        this.logger.warn(`Sent cancellation tx ${cancelTxHash} for timed out tx from ${account} with nonce ${nonce}`, {
+            nonce,
+            cancelFeesPerGas,
+            isBlobTx,
+            txHashes: state.txHashes
+        });
+        // Do not await the cancel tx to be mined
+        void this.monitorTransaction(state).catch((err)=>{
+            this.logger.error(`Failed to mine cancellation tx ${cancelTxHash} for nonce ${nonce} account ${account}`, err, {
+                nonce,
+                account,
+                cancelTxHash
+            });
+        });
+    }
+    /** Returns L1 timestamps in milliseconds */ async getL1Timestamp() {
+        const { timestamp } = await this.client.getBlock({
+            blockTag: 'latest',
+            includeTransactions: false
+        });
+        return Number(timestamp) * 1000;
+    }
+    /** Makes empty blob inputs for the cancellation tx. */ makeEmptyBlobInputs(maxFeePerBlobGas) {
+        if (!this.kzg) {
+            throw new Error('Cannot make empty blob inputs for cancellation without kzg');
+        }
+        const blobData = new Uint8Array(131072).fill(0);
+        return {
+            blobs: [
+                blobData
+            ],
+            kzg: this.kzg,
+            maxFeePerBlobGas
+        };
+    }
+    /** Creates a new delayer instance. */ createDelayer(opts, bindings) {
+        return createDelayer(this.dateProvider, opts, bindings);
+    }
+}