@aztec-labs/ethereum 6.0.0-rc.3 → 6.0.0

package/dest/publisher_manager.js

@@ -1,21 +1,21 @@
-import { pick } from '@aztec-labs/foundation/collection';
+import { maxBy, pick } from '@aztec-labs/foundation/collection';
 import { createLogger } from '@aztec-labs/foundation/log';
 import { RunningPromise } from '@aztec-labs/foundation/running-promise';
+import { formatEther } from 'viem';
 import { Multicall3 } from './contracts/multicall.js';
-import { 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
-];
+import { INSUFFICIENT_FUNDS_BACKOFF_MS, TxUtilsState, computeSendCost } from './l1_tx_utils/index.js';
+/**
+ * Selection rank per publisher state (lower is better). IDLE and MINED rank equally: a publisher whose sends keep
+ * failing (e.g. for lack of funds) never leaves IDLE, so ranking IDLE above MINED would let it beat a working one.
+ * In-flight states come next, and cancelled or not-mined states last since they represent failures to mine.
+ */ const stateRank = {
+    [TxUtilsState.IDLE]: 0,
+    [TxUtilsState.MINED]: 0,
+    [TxUtilsState.SPEED_UP]: 1,
+    [TxUtilsState.SENT]: 1,
+    [TxUtilsState.CANCELLED]: 2,
+    [TxUtilsState.NOT_MINED]: 2
+};
 // Which states represent a busy publisher that we should avoid if possible
 const busyStates = [
     TxUtilsState.SENT,
@@ -23,22 +23,75 @@ const busyStates = [
     TxUtilsState.CANCELLED,
     TxUtilsState.NOT_MINED
 ];
+const LOW_BALANCE_WARNING_INTERVAL_MS = 10 * 60 * 1000;
+const DEFAULT_LOW_BALANCE_WARNING_MULTIPLIER = 4;
+const NO_AFFORDABLE_PUBLISHER_WARNING_KEY = 'no-affordable-publisher';
+/** Thrown when publishers are available but none holds enough ETH to afford the requested L1 send. */ export class NoAffordablePublisherError extends Error {
+    required;
+    requirement;
+    fees;
+    publishers;
+    constructor(required, requirement, fees, publishers){
+        super(`No publisher can afford the L1 send: requires ${formatEther(required)} ETH ` + `(balances: ${publishers.map((p)=>`${p.address}=${formatEther(p.balance)}`).join(', ') || 'none'})`), this.required = required, this.requirement = requirement, this.fees = fees, this.publishers = publishers;
+        this.name = 'NoAffordablePublisherError';
+    }
+    /**
+   * ETH the best funded publisher that is not backed off after an insufficient funds rejection is missing to afford the
+   * send. Undefined if every publisher is backed off.
+   */ shortfall() {
+        const richest = this.getRichestNotBackedOff();
+        return richest === undefined ? undefined : this.required - richest.balance;
+    }
+    /** Tells the operator which publisher to fund and with how much ETH for the send to become affordable. */ describeFunding() {
+        const richest = this.getRichestNotBackedOff();
+        if (richest === undefined || this.required <= richest.balance) {
+            const minutes = INSUFFICIENT_FUNDS_BACKOFF_MS / 60_000;
+            return `every publisher is backed off after an insufficient funds rejection ` + `until its balance increases or ${minutes} minutes pass`;
+        }
+        const shortfall = formatEther(this.required - richest.balance);
+        const others = this.publishers.filter((p)=>p.address !== richest.address);
+        const alternative = others.length === 0 ? '' : `, or top up any of ${others.map((p)=>p.address).join(', ')} to ${formatEther(this.required)} ETH`;
+        return `fund ${richest.address} with ${shortfall} ETH more${alternative}`;
+    }
+    /** Structured context for logging. */ toLogContext() {
+        return {
+            required: this.required,
+            shortfall: this.shortfall(),
+            gasLimit: this.requirement.gasLimit,
+            blobCount: this.requirement.blobCount,
+            maxFeePerGas: this.fees.maxFeePerGas,
+            maxFeePerBlobGas: this.fees.maxFeePerBlobGas,
+            publishers: this.publishers
+        };
+    }
+    getRichestNotBackedOff() {
+        return maxBy(this.publishers.filter((p)=>p.insufficientFundsAtBalance === undefined), (p)=>p.balance);
+    }
+}
 export class PublisherManager {
     publishers;
+    static BALANCE_CHECK_INTERVAL_MS = 60 * 1000;
     log;
     config;
-    static FUNDING_CHECK_INTERVAL_MS = 2 * 60 * 1000;
     funder;
-    fundingPromise;
+    balanceCheckPromise;
     started;
+    metrics;
+    referenceSend;
+    /** Whether the balance check has run since the last start, so the first one logs a summary of all balances. */ loggedBalanceSummary;
+    /** Last time a balance warning was logged, per publisher address or per kind of warning. */ lastLowBalanceWarningAt;
     constructor(publishers, config, opts){
         this.publishers = publishers;
         this.started = false;
+        this.loggedBalanceSummary = false;
+        this.lastLowBalanceWarningAt = new Map();
         this.funder = opts?.funder;
+        this.metrics = opts?.metrics;
+        this.referenceSend = opts?.referenceSend;
         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');
+        this.config = pick(config, 'publisherAllowInvalidStates', 'publisherFundingThreshold', 'publisherFundingAmount', 'publisherLowBalanceWarningMultiplier');
         const hasThreshold = this.config.publisherFundingThreshold !== undefined;
         const hasAmount = this.config.publisherFundingAmount !== undefined;
         if (hasThreshold !== hasAmount) {
@@ -51,16 +104,14 @@ export class PublisherManager {
                 this.funder = undefined;
             }
         }
-        if (this.funder && hasThreshold && hasAmount) {
-            this.fundingPromise = new RunningPromise(()=>this.triggerFundingIfNeeded(), this.log, PublisherManager.FUNDING_CHECK_INTERVAL_MS);
-        }
+        this.balanceCheckPromise = new RunningPromise(()=>this.checkBalances(), this.log, PublisherManager.BALANCE_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.
+   * loads the state of all publishers and the funder, and starts the periodic balance check, which also tops up
+   * publishers if funding is configured. 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.
    */ async start() {
         if (this.started) {
             this.log.debug('PublisherManager already started, ignoring start');
@@ -74,17 +125,20 @@ export class PublisherManager {
             ...this.publishers.map((pub)=>pub.loadStateAndResumeMonitoring()),
             this.funder?.loadStateAndResumeMonitoring()
         ]);
-        this.fundingPromise?.start();
+        this.loggedBalanceSummary = false;
+        this.lastLowBalanceWarningAt.delete(NO_AFFORDABLE_PUBLISHER_WARNING_KEY);
+        this.balanceCheckPromise.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)
+   * Stops the balance check 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.
    */ async stop() {
         this.started = false;
-        await this.fundingPromise?.stop();
+        await this.balanceCheckPromise.stop();
+        this.metrics?.recordBalanceSnapshot(undefined);
         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
@@ -94,76 +148,264 @@ export class PublisherManager {
             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
-    async getAvailablePublisher(filter = ()=>true) {
+    /**
+   * Finds and prioritises an available publisher. Candidates must pass the filter and not be busy (unless
+   * `publisherAllowInvalidStates` is set and no idle publisher remains), and are ranked by state (see `stateRank`), then
+   * highest balance, then least recently used. Publishers backed off after an insufficient funds rejection are skipped
+   * until their balance increases or the backoff expires.
+   *
+   * With a `requirement`, only publishers whose balance covers the worst-case cost of that send are eligible, and a
+   * {@link NoAffordablePublisherError} is thrown if there are none. Without one, selection is lenient: it prefers funded
+   * publishers but falls back to unfunded ones rather than failing, for sends that are fine to attempt and lose.
+   */ async getAvailablePublisher(filter = ()=>true, opts) {
         this.log.debug(`Getting available publisher`, {
             publishers: this.publishers.map((p)=>({
                     address: p.getSenderAddress(),
                     state: p.state,
                     lastMined: p.lastMinedAtBlockNumber
-                }))
+                })),
+            requirement: opts?.requirement
         });
-        // Extract the valid publishers
-        let validPublishers = this.publishers.filter((pub)=>!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
+        const filtered = this.publishers.filter((pub)=>filter(pub));
+        let validPublishers = filtered.filter((pub)=>!busyStates.includes(pub.state));
+        // If none found but we allow invalid (busy) states, try again including them. When the send has a requirement we
+        // also consider busy ones, so that an idle but unaffordable publisher does not hide a busy affordable one. Busy
+        // publishers still rank below idle ones.
+        if (this.config.publisherAllowInvalidStates && (validPublishers.length === 0 || opts?.requirement)) {
+            if (validPublishers.length === 0) {
+                this.log.warn(`No valid publishers found. Trying again including invalid states.`);
+            }
+            validPublishers = filtered;
+        }
         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);
+        const withBalance = await this.getBalances(validPublishers);
+        let candidates;
+        if (opts?.requirement) {
+            candidates = await this.getAffordable(withBalance, opts.requirement);
+        } else {
+            candidates = this.getLenientCandidates(withBalance);
+        }
+        const sortedPublishers = candidates.sort((a, b)=>{
+            const stateComparison = stateRank[a.publisher.state] - stateRank[b.publisher.state];
             if (stateComparison !== 0) {
                 return stateComparison;
             }
-            const balanceComparison = Number(b.balance - a.balance);
-            if (balanceComparison !== 0) {
-                return balanceComparison;
+            if (a.balance !== b.balance) {
+                return b.balance > a.balance ? 1 : -1;
             }
             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. */ async triggerFundingIfNeeded() {
+    /**
+   * Reads the balance of every publisher and the funder, prices the reference send at current fees, records metrics,
+   * logs balances that are low or cannot afford the reference send, and tops up publishers below the funding threshold
+   * if funding is configured. Runs once a minute while started.
+   */ async checkBalances() {
+        const funder = this.funder;
+        const [publisherBalances, funderBalance] = await Promise.all([
+            Promise.all(this.publishers.map((publisher)=>this.tryGetBalance(publisher))),
+            funder ? this.tryGetBalance(funder) : undefined
+        ]);
+        const withBalance = this.publishers.flatMap((publisher, i)=>{
+            const balance = publisherBalances[i];
+            return balance === undefined ? [] : [
+                {
+                    publisher,
+                    balance
+                }
+            ];
+        });
+        const cost = await this.tryGetReferenceCost();
+        const required = cost !== undefined && cost.required > 0n ? cost.required : undefined;
+        const snapshot = {
+            publishers: withBalance.map(({ publisher, balance })=>({
+                    address: publisher.getSenderAddress().toString(),
+                    balance,
+                    sendsAffordable: required === undefined ? undefined : publisher.hasActiveInsufficientFundsBackoff(balance) ? 0 : Number(balance / required)
+                })),
+            funder: funder && funderBalance !== undefined ? {
+                address: funder.getSenderAddress().toString(),
+                balance: funderBalance
+            } : undefined,
+            required
+        };
+        this.metrics?.recordBalanceSnapshot(snapshot);
+        this.logBalances(withBalance, snapshot, cost?.fees);
+        if (required !== undefined) {
+            this.warnOnLowBalances(withBalance, required);
+        }
+        await this.fundIfNeeded(withBalance, funderBalance);
+    }
+    getBalances(publishers) {
+        return Promise.all(publishers.map(async (publisher)=>({
+                publisher,
+                balance: await publisher.getSenderBalance()
+            })));
+    }
+    /** Returns the publishers that can afford the requirement, or throws NoAffordablePublisherError if none. */ async getAffordable(publishers, requirement) {
+        if (publishers.length === 0) {
+            throw new Error(`Failed to find an available publisher.`);
+        }
+        // All publishers share the L1 network, so fees are fetched once rather than per publisher.
+        const fees = await publishers[0].publisher.getFeesPerGas(undefined, requirement.blobCount > 0, 0);
+        const required = computeSendCost(fees, requirement);
+        const affordable = publishers.filter((p)=>p.balance >= required && !p.publisher.isBackedOffForInsufficientFunds(p.balance));
+        if (affordable.length === 0) {
+            throw new NoAffordablePublisherError(required, requirement, fees, this.toBalanceInfo(publishers));
+        }
+        return affordable;
+    }
+    toBalanceInfo(publishers) {
+        return publishers.map(({ publisher, balance })=>({
+                address: publisher.getSenderAddress().toString(),
+                balance,
+                state: TxUtilsState[publisher.state],
+                insufficientFundsAtBalance: publisher.hasActiveInsufficientFundsBackoff(balance) ? publisher.getInsufficientFundsAtBalance() : undefined
+            }));
+    }
+    /**
+   * Prefers publishers that are funded and not backed off after an insufficient funds rejection, but never returns an
+   * empty list: if every candidate is excluded, falls back to the full set so lenient sends still have something to try.
+   */ getLenientCandidates(publishers) {
+        const usable = publishers.filter((p)=>p.balance > 0n && !p.publisher.isBackedOffForInsufficientFunds(p.balance));
+        if (usable.length > 0) {
+            return usable;
+        }
+        const funded = publishers.filter((p)=>p.balance > 0n);
+        if (funded.length > 0) {
+            return funded;
+        }
+        this.log.warn(`All candidate publishers have zero balance; selecting from unfunded publishers.`);
+        return publishers;
+    }
+    async tryGetBalance(utils) {
+        try {
+            return await utils.getSenderBalance();
+        } catch (err) {
+            const address = utils.getSenderAddress().toString();
+            if (this.shouldWarn(`balance-read:${address}`)) {
+                this.log.warn(`Failed to read L1 balance of account`, {
+                    address,
+                    err
+                });
+            }
+            return undefined;
+        }
+    }
+    async tryGetReferenceCost() {
+        const { referenceSend } = this;
+        if (referenceSend === undefined || this.publishers.length === 0) {
+            return undefined;
+        }
+        try {
+            // All publishers share the L1 network, so fees are fetched once rather than per publisher.
+            const fees = await this.publishers[0].getFeesPerGas(undefined, referenceSend.requirement.blobCount > 0, 0);
+            return {
+                fees,
+                required: computeSendCost(fees, referenceSend.requirement)
+            };
+        } catch (err) {
+            if (this.shouldWarn('fee-read')) {
+                this.log.warn(`Failed to read L1 fees to check whether publishers can afford a ${referenceSend.name}`, {
+                    err
+                });
+            }
+            return undefined;
+        }
+    }
+    /**
+   * Logs a summary of all balances on the first check after a start, and an error (at most once per interval) while no
+   * publisher can afford the reference send.
+   */ logBalances(publishers, snapshot, fees) {
+        const firstCheck = !this.loggedBalanceSummary;
+        this.loggedBalanceSummary = true;
+        const { referenceSend } = this;
+        const { required } = snapshot;
+        const context = {
+            publishers: snapshot.publishers.map((p)=>({
+                    address: p.address,
+                    balance: formatEther(p.balance),
+                    sendsAffordable: p.sendsAffordable
+                })),
+            referenceSend: referenceSend?.name,
+            required: required === undefined ? undefined : formatEther(required),
+            funder: snapshot.funder && {
+                address: snapshot.funder.address,
+                balance: formatEther(snapshot.funder.balance)
+            }
+        };
+        const allRead = publishers.length === this.publishers.length;
+        const noneAffordable = referenceSend !== undefined && required !== undefined && fees !== undefined && allRead && snapshot.publishers.length > 0 && snapshot.publishers.every((p)=>(p.sendsAffordable ?? 0) < 1);
+        if (!noneAffordable) {
+            // Only a publisher seen affording the send ends an episode. A check that could not tell (failed reads) must not
+            // reset the rate limit, or alternating failed and empty checks would log the error on every empty one.
+            if (snapshot.publishers.some((p)=>(p.sendsAffordable ?? 0) >= 1)) {
+                this.lastLowBalanceWarningAt.delete(NO_AFFORDABLE_PUBLISHER_WARNING_KEY);
+            }
+            if (firstCheck) {
+                this.log.info(`Publisher balances`, context);
+            }
+            return;
+        }
+        if (this.shouldWarn(NO_AFFORDABLE_PUBLISHER_WARNING_KEY)) {
+            const err = new NoAffordablePublisherError(required, referenceSend.requirement, fees, this.toBalanceInfo(publishers));
+            this.log.error(`No publisher can afford a ${referenceSend.name} at current L1 fees: ${err.describeFunding()}`, {
+                ...context,
+                shortfall: err.shortfall()
+            });
+        }
+    }
+    /** Warns at most once per interval for every publisher below the low-balance level. */ warnOnLowBalances(publishers, required) {
+        const multiplier = this.config.publisherLowBalanceWarningMultiplier ?? DEFAULT_LOW_BALANCE_WARNING_MULTIPLIER;
+        const warningLevel = required * BigInt(Math.round(multiplier * 1000)) / 1000n;
+        for (const { publisher, balance } of publishers){
+            if (balance >= warningLevel) {
+                continue;
+            }
+            const address = publisher.getSenderAddress().toString();
+            if (this.shouldWarn(address)) {
+                this.log.warn(`Publisher balance is low relative to the ETH required for an L1 send`, {
+                    address,
+                    balance,
+                    required,
+                    multiplier,
+                    warningLevel
+                });
+            }
+        }
+        const { publisherFundingThreshold } = this.config;
+        if (this.funder && publisherFundingThreshold !== undefined && publisherFundingThreshold < warningLevel && this.shouldWarn('funding-threshold')) {
+            this.log.warn(`Publisher funding threshold is below the low-balance warning level`, {
+                publisherFundingThreshold,
+                warningLevel,
+                required,
+                multiplier
+            });
+        }
+    }
+    shouldWarn(key) {
+        const now = Date.now();
+        const last = this.lastLowBalanceWarningAt.get(key);
+        if (last !== undefined && now - last < LOW_BALANCE_WARNING_INTERVAL_MS) {
+            return false;
+        }
+        this.lastLowBalanceWarningAt.set(key, now);
+        return true;
+    }
+    /** Funds the publishers below the funding threshold, using the balances read in the same balance check. */ async fundIfNeeded(publishers, funderBalance) {
         const { funder, config } = this;
-        if (!funder || config.publisherFundingThreshold === undefined || config.publisherFundingAmount === undefined) {
+        const { publisherFundingThreshold, publisherFundingAmount: fundingAmount } = config;
+        if (!funder || publisherFundingThreshold === undefined || fundingAmount === 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) {
+        const lowBalance = publishers.filter((p)=>p.balance < publisherFundingThreshold);
+        if (lowBalance.length === 0 || funderBalance === undefined) {
             return;
         }
-        const fundingAmount = config.publisherFundingAmount;
-        const funderBalance = await funder.getSenderBalance();
         if (funderBalance < 10n * fundingAmount) {
             this.log.warn(`Funding account balance is low`, {
                 funderBalance,
@@ -185,15 +427,14 @@ export class PublisherManager {
             });
         }
         const toFund = lowBalance.slice(0, affordableCount).map((p)=>p.publisher);
-        await this.fundPublishers(toFund);
+        await this.fundPublishers(funder, toFund, fundingAmount);
     }
-    /** Fund publishers via a single Multicall3 aggregate3Value transaction. */ async fundPublishers(publishers) {
-        const fundingAmount = this.config.publisherFundingAmount;
+    /** Fund publishers via a single Multicall3 aggregate3Value transaction. */ async fundPublishers(funder, publishers, fundingAmount) {
         const calls = publishers.map((pub)=>({
                 to: pub.getSenderAddress().toString(),
                 value: fundingAmount
             }));
-        await Multicall3.forwardValue(calls, this.funder, this.log);
+        await Multicall3.forwardValue(calls, funder, this.log);
         this.log.info(`Funded ${publishers.length} publishers`);
     }
 }

package/dest/test/anvil_hardfork.d.ts

@@ -0,0 +1,42 @@
+import { type EIP1193RequestFn } from 'viem';
+import type { EthCheatCodes } from './eth_cheat_codes.js';
+import { type Anvil, startAnvil } from './start_anvil.js';
+/**
+ * Starts a throwaway anvil on `hardfork` and checks that it mines blocks of that fork, so a test that needs a fork
+ * the installed foundry cannot run fails within seconds instead of after its whole setup. Never skips.
+ */
+export declare function assertAnvilSupportsHardfork(hardfork: string): Promise<void>;
+/**
+ * Writes anvil's state, including the historical states it still keeps, as the plain JSON file `--load-state` reads.
+ * Without history, reads at blocks before a restart fail on the reloaded anvil. A dump with history easily exceeds
+ * viem's default response size limit, so `client` must be one built without it, such as `createExtendedL1Client`'s.
+ */
+export declare function dumpAnvilStateWithHistory(client: {
+    request: EIP1193RequestFn;
+}, path: string): Promise<void>;
+/**
+ * Moves an interval-mining anvil to another hardfork, continuing its chain. Anvil cannot change hardfork at runtime,
+ * so this stops mining, dumps the state with history to `stateDir` using `dumpClient`, stops `anvil`, and starts a new
+ * anvil on the same port from the dump with `startOpts`. Mining stays stopped until the old anvil is gone, so no block
+ * mined after the dump is lost. Pending txs are lost, since the mempool is not part of the dump.
+ *
+ * The reloaded anvil would stamp its next block as if no time had passed since the dump, so the first block on the new
+ * hardfork is mined at the first L1 slot of the old chain's grid that is not in the past, and interval mining resumes
+ * from there.
+ *
+ * @returns The new anvil, which replaces `anvil`, and the first block mined on `hardfork`.
+ */
+export declare function restartAnvilOnHardfork(anvil: Anvil, cheat: EthCheatCodes, dumpClient: {
+    request: EIP1193RequestFn;
+}, opts: {
+    hardfork: string;
+    stateDir: string;
+    startOpts?: Parameters<typeof startAnvil>[0];
+}): Promise<{
+    anvil: Anvil;
+    forkBlock: {
+        number: bigint;
+        timestamp: bigint;
+    };
+}>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYW52aWxfaGFyZGZvcmsuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy90ZXN0L2FudmlsX2hhcmRmb3JrLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUlBLE9BQU8sRUFBRSxLQUFLLGdCQUFnQixFQUFzQyxNQUFNLE1BQU0sQ0FBQztBQUlqRixPQUFPLEtBQUssRUFBRSxhQUFhLEVBQUUsTUFBTSxzQkFBc0IsQ0FBQztBQUMxRCxPQUFPLEVBQUUsS0FBSyxLQUFLLEVBQUUsVUFBVSxFQUFFLE1BQU0sa0JBQWtCLENBQUM7QUFFMUQ7OztHQUdHO0FBQ0gsd0JBQXNCLDJCQUEyQixDQUFDLFFBQVEsRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQWtCakY7QUFFRDs7OztHQUlHO0FBQ0gsd0JBQXNCLHlCQUF5QixDQUFDLE1BQU0sRUFBRTtJQUFFLE9BQU8sRUFBRSxnQkFBZ0IsQ0FBQTtDQUFFLEVBQUUsSUFBSSxFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFDLENBU2xIO0FBRUQ7Ozs7Ozs7Ozs7O0dBV0c7QUFDSCx3QkFBc0Isc0JBQXNCLENBQzFDLEtBQUssRUFBRSxLQUFLLEVBQ1osS0FBSyxFQUFFLGFBQWEsRUFDcEIsVUFBVSxFQUFFO0lBQUUsT0FBTyxFQUFFLGdCQUFnQixDQUFBO0NBQUUsRUFDekMsSUFBSSxFQUFFO0lBQUUsUUFBUSxFQUFFLE1BQU0sQ0FBQztJQUFDLFFBQVEsRUFBRSxNQUFNLENBQUM7SUFBQyxTQUFTLENBQUMsRUFBRSxVQUFVLENBQUMsT0FBTyxVQUFVLENBQUMsQ0FBQyxDQUFDLENBQUMsQ0FBQTtDQUFFLEdBQ3pGLE9BQU8sQ0FBQztJQUFFLEtBQUssRUFBRSxLQUFLLENBQUM7SUFBQyxTQUFTLEVBQUU7UUFBRSxNQUFNLEVBQUUsTUFBTSxDQUFDO1FBQUMsU0FBUyxFQUFFLE1BQU0sQ0FBQTtLQUFFLENBQUE7Q0FBRSxDQUFDLENBMEI3RSJ9

package/dest/test/anvil_hardfork.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anvil_hardfork.d.ts","sourceRoot":"","sources":["../../src/test/anvil_hardfork.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,gBAAgB,EAAsC,MAAM,MAAM,CAAC;AAIjF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,KAAK,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE1D;;;GAGG;AACH,wBAAsB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBjF;AAED;;;;GAIG;AACH,wBAAsB,yBAAyB,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,gBAAgB,CAAA;CAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CASlH;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,aAAa,EACpB,UAAU,EAAE;IAAE,OAAO,EAAE,gBAAgB,CAAA;CAAE,EACzC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;CAAE,GACzF,OAAO,CAAC;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,SAAS,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC,CA0B7E"}

package/dest/test/anvil_hardfork.js

@@ -0,0 +1,107 @@
+import { Buffer } from 'buffer';
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { gunzipSync } from 'node:zlib';
+import { createPublicClient, http } from 'viem';
+import { resolveFoundryBinary } from '../foundry_binary.js';
+import { isAmsterdamBlock } from '../l1_tx_utils/amsterdam.js';
+import { startAnvil } from './start_anvil.js';
+/**
+ * Starts a throwaway anvil on `hardfork` and checks that it mines blocks of that fork, so a test that needs a fork
+ * the installed foundry cannot run fails within seconds instead of after its whole setup. Never skips.
+ */ export async function assertAnvilSupportsHardfork(hardfork) {
+    let res;
+    try {
+        res = await startAnvil({
+            port: 0,
+            hardfork
+        });
+        const client = createPublicClient({
+            transport: http(res.rpcUrl, {
+                batch: false
+            })
+        });
+        await client.request({
+            method: 'evm_mine',
+            params: []
+        });
+        const block = await client.getBlock({
+            blockTag: 'latest'
+        });
+        if (isAmsterdamBlock(block) !== (hardfork === 'amsterdam')) {
+            throw new Error(`anvil --hardfork ${hardfork} mined block ${block.number} with the wrong header shape`);
+        }
+    } catch (err) {
+        throw new Error(`Anvil at ${resolveFoundryBinary('anvil')} cannot run --hardfork ${hardfork}; foundry >= 1.8.5 is required`, {
+            cause: err
+        });
+    } finally{
+        await res?.stop();
+    }
+}
+/**
+ * Writes anvil's state, including the historical states it still keeps, as the plain JSON file `--load-state` reads.
+ * Without history, reads at blocks before a restart fail on the reloaded anvil. A dump with history easily exceeds
+ * viem's default response size limit, so `client` must be one built without it, such as `createExtendedL1Client`'s.
+ */ export async function dumpAnvilStateWithHistory(client, path) {
+    const hex = await client.request({
+        method: 'anvil_dumpState',
+        params: [
+            true
+        ]
+    });
+    const dump = Buffer.from(hex.slice(2), 'hex');
+    const isGzip = dump[0] === 0x1f && dump[1] === 0x8b;
+    // Kept as a Buffer: a dump with history can exceed the maximum length of a V8 string.
+    await writeFile(path, isGzip ? gunzipSync(dump) : dump);
+}
+/**
+ * Moves an interval-mining anvil to another hardfork, continuing its chain. Anvil cannot change hardfork at runtime,
+ * so this stops mining, dumps the state with history to `stateDir` using `dumpClient`, stops `anvil`, and starts a new
+ * anvil on the same port from the dump with `startOpts`. Mining stays stopped until the old anvil is gone, so no block
+ * mined after the dump is lost. Pending txs are lost, since the mempool is not part of the dump.
+ *
+ * The reloaded anvil would stamp its next block as if no time had passed since the dump, so the first block on the new
+ * hardfork is mined at the first L1 slot of the old chain's grid that is not in the past, and interval mining resumes
+ * from there.
+ *
+ * @returns The new anvil, which replaces `anvil`, and the first block mined on `hardfork`.
+ */ export async function restartAnvilOnHardfork(anvil, cheat, dumpClient, opts) {
+    const blockTimeS = await cheat.getIntervalMining();
+    if (!blockTimeS) {
+        throw new Error('restartAnvilOnHardfork needs an anvil in interval mining');
+    }
+    await cheat.setIntervalMining(0, {
+        silent: true
+    });
+    const tip = await cheat.publicClient.getBlock({
+        blockTag: 'latest'
+    });
+    const statePath = join(opts.stateDir, `anvil-state-${tip.number}.json`);
+    await dumpAnvilStateWithHistory(dumpClient, statePath);
+    await anvil.stop();
+    const restarted = await startAnvil({
+        ...opts.startOpts,
+        port: anvil.port,
+        hardfork: opts.hardfork,
+        loadState: statePath,
+        l1BlockTime: blockTimeS
+    });
+    const blockTime = BigInt(blockTimeS);
+    const nowS = BigInt(Math.ceil(cheat.dateProvider.now() / 1000));
+    const slotsSinceTip = nowS > tip.timestamp ? (nowS - tip.timestamp + blockTime - 1n) / blockTime : 1n;
+    await cheat.warp(tip.timestamp + blockTime * slotsSinceTip, {
+        silent: true,
+        resetBlockInterval: true
+    });
+    const forkBlock = await cheat.publicClient.getBlock({
+        blockNumber: tip.number + 1n
+    });
+    return {
+        anvil: restarted.anvil,
+        forkBlock: {
+            number: forkBlock.number,
+            timestamp: forkBlock.timestamp
+        }
+    };
+}