@aztec/ethereum 5.0.0-rc.2 → 5.0.1

package/dest/test/start_anvil.js

@@ -1,16 +1,41 @@
 import { createLogger } from '@aztec/foundation/log';
 import { makeBackoff, retry } from '@aztec/foundation/retry';
-import { fileURLToPath } from '@aztec/foundation/url';
 import { spawn } from 'child_process';
-import { dirname, resolve } from 'path';
+import { resolveFoundryBinary } from '../foundry_binary.js';
+// Watchdog wrapper: instead of spawning anvil directly, we spawn a small bash supervisor that runs
+// anvil as a background child and polls its own parent (this node process). If the parent dies for
+// ANY reason — including SIGKILL / crash / OOM, where node's own exit handlers never run — the poll
+// loop ends and the EXIT trap reaps anvil. The script is inlined (rather than shipped as a `.sh`) so
+// it works from the published npm tarball too, and the resolved anvil binary is passed via
+// `$ANVIL_BIN` so it works without `anvil` on PATH.
+//
+// `$@` is the anvil argv; `bash -c <script> bash <...args>` puts the args in `$@` and `$0` = 'bash'.
+//
+// The EXIT trap reaps anvil; INT/TERM just `exit` (which fires the EXIT trap) so a signal terminates
+// the supervisor promptly instead of being swallowed — a trapped TERM does NOT terminate the shell,
+// so trapping the kill directly on TERM would leave the poll loop running and the caller's teardown
+// hanging until its SIGKILL escalation. `sleep & wait` makes the poll interruptible, so INT/TERM are
+// handled immediately rather than after the current `sleep` returns.
+const ANVIL_WATCHDOG = `
+set -u
+parent=$PPID
+"$ANVIL_BIN" "$@" &
+anvil_pid=$!
+trap 'kill "$anvil_pid" 2>/dev/null' EXIT
+trap 'exit 0' INT TERM
+while kill -0 "$parent" 2>/dev/null; do sleep 1 & wait $!; done
+`;
 /**
  * Ensures there's a running Anvil instance and returns the RPC URL.
  */ export async function startAnvil(opts = {}) {
-    const anvilBinary = resolve(dirname(fileURLToPath(import.meta.url)), '../../', 'scripts/anvil_kill_wrapper.sh');
+    const anvilBinary = resolveFoundryBinary('anvil');
     const logger = opts.log ? createLogger('ethereum:anvil') : undefined;
     const methodCalls = opts.captureMethodCalls ? [] : undefined;
     let detectedPort;
     const anvil = await retry(async ()=>{
+        // `--port 0` lets anvil bind an OS-assigned ephemeral port; the actual port is read back from
+        // its "Listening on host:port" stdout below, so independent suites can spawn their own anvil
+        // in parallel without fighting over a fixed port.
         const port = opts.port ?? (process.env.ANVIL_PORT ? parseInt(process.env.ANVIL_PORT) : 8545);
         const args = [
             '--host',
@@ -31,7 +56,14 @@ import { dirname, resolve } from 'path';
             args.push('--hardfork', opts.hardfork);
         }
         args.push('--slots-in-an-epoch', String(opts.slotsInAnEpoch ?? 1));
-        const child = spawn(anvilBinary, args, {
+        // Spawn the watchdog (see ANVIL_WATCHDOG). It launches anvil with these args and reaps it if we
+        // die; `$0` is 'bash' and `$@` is the anvil argv.
+        const child = spawn('bash', [
+            '-c',
+            ANVIL_WATCHDOG,
+            'bash',
+            ...args
+        ], {
             stdio: [
                 'ignore',
                 'pipe',
@@ -39,6 +71,7 @@ import { dirname, resolve } from 'path';
             ],
             env: {
                 ...process.env,
+                ANVIL_BIN: anvilBinary,
                 RAYON_NUM_THREADS: '1'
             }
         });
@@ -139,7 +172,10 @@ import { dirname, resolve } from 'path';
         }
     }
 }
-/** Send SIGTERM, wait up to 5 s, then SIGKILL. All timers are always cleared. */ function killChild(child) {
+/**
+ * Send SIGTERM to the watchdog, wait up to 5 s, then SIGKILL. The watchdog's trap forwards the
+ * signal to anvil, so terminating it tears down anvil too. All timers are always cleared.
+ */ function killChild(child) {
     return new Promise((resolve)=>{
         if (child.exitCode !== null || child.killed) {
             child.stdout?.destroy();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/ethereum",
-  "version": "5.0.0-rc.2",
+  "version": "5.0.1",
   "type": "module",
   "exports": {
     "./account": "./dest/account.js",
@@ -50,10 +50,10 @@
     "../package.common.json"
   ],
   "dependencies": {
-    "@aztec/blob-lib": "5.0.0-rc.2",
-    "@aztec/constants": "5.0.0-rc.2",
-    "@aztec/foundation": "5.0.0-rc.2",
-    "@aztec/l1-artifacts": "5.0.0-rc.2",
+    "@aztec/blob-lib": "5.0.1",
+    "@aztec/constants": "5.0.1",
+    "@aztec/foundation": "5.0.1",
+    "@aztec/l1-artifacts": "5.0.1",
     "dotenv": "^16.0.3",
     "lodash.chunk": "^4.2.0",
     "lodash.pickby": "^4.5.0",

package/src/config.ts

@@ -246,6 +246,41 @@ export const l1ContractsConfigMappings: ConfigMappingsType<L1ContractsConfig> =
  */
 export const DefaultL1ContractsConfig = getDefaultConfig(l1ContractsConfigMappings);
 
+/**
+ * Validates that `ethereumSlotDuration` and `aztecSlotDuration` are positive and that the L2 slot is an exact
+ * multiple of the L1 slot. Every L2 slot boundary must land on an L1 slot boundary; a non-multiple pairing
+ * desyncs the epoch/checkpoint timing math throughout the sequencer, validator client, and timetables. Returns
+ * a list of error messages (empty when valid).
+ */
+export function validateSlotDurations(
+  config: Pick<L1ContractsConfig, 'ethereumSlotDuration' | 'aztecSlotDuration'>,
+): string[] {
+  const errors: string[] = [];
+  if (config.ethereumSlotDuration <= 0) {
+    errors.push(`ethereumSlotDuration must be positive (got ${config.ethereumSlotDuration})`);
+  }
+  if (config.aztecSlotDuration <= 0) {
+    errors.push(`aztecSlotDuration must be positive (got ${config.aztecSlotDuration})`);
+  }
+  if (config.ethereumSlotDuration > 0 && config.aztecSlotDuration % config.ethereumSlotDuration !== 0) {
+    errors.push(
+      `aztecSlotDuration (${config.aztecSlotDuration}s) must be a multiple of ethereumSlotDuration ` +
+        `(${config.ethereumSlotDuration}s)`,
+    );
+  }
+  return errors;
+}
+
+/** Throws if {@link validateSlotDurations} reports any errors. */
+export function assertValidSlotDurations(
+  config: Pick<L1ContractsConfig, 'ethereumSlotDuration' | 'aztecSlotDuration'>,
+): void {
+  const errors = validateSlotDurations(config);
+  if (errors.length > 0) {
+    throw new Error(`Invalid slot duration configuration:\n${errors.map(e => `  - ${e}`).join('\n')}`);
+  }
+}
+
 export const genesisStateConfigMappings: ConfigMappingsType<GenesisStateConfig> = {
   testAccounts: {
     env: 'TEST_ACCOUNTS',

package/src/deploy_aztec_l1_contracts.ts

@@ -19,9 +19,10 @@ import { mainnet, sepolia } from 'viem/chains';
 
 import { createEthereumChain, isAnvilTestChain } from './chain.js';
 import { createExtendedL1Client } from './client.js';
-import type { L1ContractsConfig } from './config.js';
+import { type L1ContractsConfig, assertValidSlotDurations } from './config.js';
 import { deployMulticall3 } from './contracts/multicall.js';
 import { RollupContract } from './contracts/rollup.js';
+import { resolveFoundryBinary } from './foundry_binary.js';
 import type { L1ContractAddresses } from './l1_contract_addresses.js';
 import type { ExtendedViemWalletClient } from './types.js';
 
@@ -93,11 +94,16 @@ function runProcess<T>(
 
 // Covers an edge where where we may have a cached BlobLib that is not meant for production.
 // Despite the profile apparently sometimes cached code remains (so says Lasse after his ignition-monorepo arc).
-async function maybeForgeForceProductionBuild(l1ContractsPath: string, script: string, chainId: number) {
+async function maybeForgeForceProductionBuild(
+  forgeBin: string,
+  l1ContractsPath: string,
+  script: string,
+  chainId: number,
+) {
   if (chainId === mainnet.id) {
     logger.info(`Recompiling ${script} with production profile for mainnet deployment`);
     logger.info('This may take a minute but ensures production BlobLib is used.');
-    await runProcess('forge', ['build', script, '--force'], { FOUNDRY_PROFILE: 'production' }, l1ContractsPath);
+    await runProcess(forgeBin, ['build', script, '--force'], { FOUNDRY_PROFILE: 'production' }, l1ContractsPath);
   }
 }
 
@@ -282,6 +288,7 @@ export async function deployAztecL1Contracts(
   args: DeployAztecL1ContractsArgs,
 ): Promise<DeployAztecL1ContractsReturnType> {
   logger.info(`Deploying L1 contracts with config: ${jsonStringify(args)}`);
+  assertValidSlotDurations(args);
   if (args.initialValidators && args.initialValidators.length > 0 && args.existingTokenAddress) {
     throw new Error(
       'Cannot deploy with both initialValidators and existingTokenAddress. ' +
@@ -319,8 +326,9 @@ export async function deployAztecL1Contracts(
   // Use foundry-artifacts from l1-artifacts package
   const l1ContractsPath = prepareL1ContractsForDeployment();
 
+  const forgeBin = resolveFoundryBinary('forge');
   const FORGE_SCRIPT = 'script/deploy/DeployAztecL1Contracts.s.sol';
-  await maybeForgeForceProductionBuild(l1ContractsPath, FORGE_SCRIPT, chainId);
+  await maybeForgeForceProductionBuild(forgeBin, l1ContractsPath, FORGE_SCRIPT, chainId);
 
   // Verify contracts on Etherscan when on mainnet/sepolia and ETHERSCAN_API_KEY is available.
   const isVerifiableChain = chainId === mainnet.id || chainId === sepolia.id;
@@ -345,6 +353,8 @@ export async function deployAztecL1Contracts(
     ...(shouldVerify ? ['--verify'] : []),
   ];
   const forgeEnv = {
+    // Resolved forge binary picked up by forge_broadcast.js, so it works without forge on PATH.
+    FORGE_BIN: forgeBin,
     // Env vars required by l1-contracts/script/deploy/DeploymentConfiguration.sol.
     NETWORK: getActiveNetworkName(),
     FOUNDRY_PROFILE: chainId === mainnet.id ? 'production' : undefined,
@@ -612,12 +622,15 @@ export const deployRollupForUpgrade = async (
   // Use foundry-artifacts from l1-artifacts package
   const l1ContractsPath = prepareL1ContractsForDeployment();
 
+  const forgeBin = resolveFoundryBinary('forge');
   const FORGE_SCRIPT = 'script/deploy/DeployRollupForUpgrade.s.sol';
-  await maybeForgeForceProductionBuild(l1ContractsPath, FORGE_SCRIPT, chainId);
+  await maybeForgeForceProductionBuild(forgeBin, l1ContractsPath, FORGE_SCRIPT, chainId);
 
   const scriptPath = join(getL1ContractsPath(), 'scripts', 'forge_broadcast.js');
   const forgeArgs = [FORGE_SCRIPT, '--sig', 'run()', '--private-key', privateKey, '--rpc-url', rpcUrl];
   const forgeEnv = {
+    // Resolved forge binary picked up by forge_broadcast.js, so it works without forge on PATH.
+    FORGE_BIN: forgeBin,
     FOUNDRY_PROFILE: chainId === mainnet.id ? 'production' : undefined,
     // Env vars required by l1-contracts/script/deploy/RollupConfiguration.sol.
     REGISTRY_ADDRESS: registryAddress.toString(),

package/src/foundry_binary.ts

@@ -0,0 +1,57 @@
+import { spawnSync } from 'child_process';
+import { accessSync, constants } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+function isExecutable(path: string): boolean {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Locate a Foundry binary (`anvil`, `forge`, ...) without relying on the caller's PATH. Order:
+ *   1. `$<NAME>_BIN` (e.g. `$ANVIL_BIN`, `$FORGE_BIN`) — explicit override, e.g. for CI with a pinned
+ *      version. Throws if set but not pointing at an executable, instead of silently falling back.
+ *   2. `~/.aztec/current/internal-bin/<name>` — where aztec-up installs it.
+ *   3. `~/.aztec/current/bin/aztec-<name>` — the publicly-exposed symlink.
+ *   4. `~/.foundry/bin/<name>` — standalone foundryup install.
+ *   5. `command -v <name>` — anything else on PATH.
+ *
+ * Throws with a directive message if none work.
+ */
+export function resolveFoundryBinary(name: string): string {
+  const envVar = `${name.toUpperCase()}_BIN`;
+  const envBin = process.env[envVar];
+  if (envBin) {
+    if (!isExecutable(envBin)) {
+      throw new Error(`$${envVar} is set to ${envBin}, which does not exist or is not executable.`);
+    }
+    return envBin;
+  }
+
+  const candidates = [
+    join(homedir(), '.aztec', 'current', 'internal-bin', name),
+    join(homedir(), '.aztec', 'current', 'bin', `aztec-${name}`),
+    join(homedir(), '.foundry', 'bin', name),
+  ];
+  for (const path of candidates) {
+    if (isExecutable(path)) {
+      return path;
+    }
+  }
+
+  const which = spawnSync('sh', ['-c', `command -v ${name}`], { encoding: 'utf8' });
+  if (which.status === 0 && which.stdout.trim()) {
+    return which.stdout.trim();
+  }
+
+  throw new Error(
+    `${name} binary not found. Tried $${envVar}, ~/.aztec/current/internal-bin/${name}, ` +
+      `~/.aztec/current/bin/aztec-${name}, ~/.foundry/bin/${name}, and $PATH. ` +
+      `Install via \`aztec-up\` or set ${envVar} to a working binary.`,
+  );
+}

package/src/l1_tx_utils/config.ts

@@ -73,7 +73,7 @@ export const l1TxUtilsConfigMappings: ConfigMappingsType<L1TxUtilsConfig> = {
   gasLimitBufferPercentage: {
     description: 'How much to increase calculated gas limit by (percentage)',
     env: 'L1_GAS_LIMIT_BUFFER_PERCENTAGE',
-    ...numberConfigHelper(20),
+    ...floatConfigHelper(20),
   },
   maxGwei: {
     description: 'Maximum gas price in gwei to be used for transactions.',
@@ -90,12 +90,12 @@ export const l1TxUtilsConfigMappings: ConfigMappingsType<L1TxUtilsConfig> = {
   priorityFeeBumpPercentage: {
     description: 'How much to increase priority fee by each attempt (percentage)',
     env: 'L1_PRIORITY_FEE_BUMP_PERCENTAGE',
-    ...numberConfigHelper(20),
+    ...floatConfigHelper(20),
   },
   priorityFeeRetryBumpPercentage: {
     description: 'How much to increase priority fee by each retry attempt (percentage)',
     env: 'L1_PRIORITY_FEE_RETRY_BUMP_PERCENTAGE',
-    ...numberConfigHelper(50),
+    ...floatConfigHelper(50),
   },
   minimumPriorityFeePerGas: {
     description:

package/src/l1_tx_utils/l1_tx_utils.ts

@@ -5,7 +5,7 @@ import { InterruptError, TimeoutError } from '@aztec/foundation/error';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import { type Logger, type LoggerBindings, createLogger } from '@aztec/foundation/log';
 import { Semaphore } from '@aztec/foundation/queue';
-import { retryUntil } from '@aztec/foundation/retry';
+import { makeBackoff, retry, retryUntil } from '@aztec/foundation/retry';
 import { sleep } from '@aztec/foundation/sleep';
 import { DateProvider } from '@aztec/foundation/timer';
 import { RollupAbi } from '@aztec/l1-artifacts/RollupAbi';
@@ -44,6 +44,11 @@ import {
 
 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 {
   protected txs: L1TxState[] = [];
   /** Last nonce successfully sent to the chain. Used as a lower bound when a fallback RPC node returns a stale count. */
@@ -431,10 +436,23 @@ export class L1TxUtils extends ReadOnlyL1TxUtils {
 
     const initialTxHash = txHashes[0];
     let currentTxHash = txHashes.at(-1)!;
-    let l1Timestamp: number;
+    let l1Timestamp = 0;
 
     while (true) {
-      l1Timestamp = await this.getL1Timestamp();
+      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();
@@ -706,9 +724,37 @@ export class L1TxUtils extends ReadOnlyL1TxUtils {
       return;
     }
 
-    // Check if the original tx is still pending
-    const currentNonce = await this.client.getTransactionCount({ address: account, blockTag: 'pending' });
-    if (currentNonce < nonce) {
+    // Resolve the pending nonce and cancellation gas price 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 getGasPrice'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, cancelGasPrice } = await retry(
+      async () => {
+        const currentNonce = await this.client.getTransactionCount({ address: account, blockTag: 'pending' });
+        if (currentNonce >= nonce) {
+          // Get gas price with higher priority fee for cancellation
+          const cancelGasPrice = await this.getGasPrice(
+            {
+              ...this.config,
+              // Use high bump for cancellation to ensure it replaces the original tx
+              priorityFeeRetryBumpPercentage: 150, // 150% bump should be enough to replace any tx
+            },
+            isBlobTx,
+            state.txHashes.length,
+            previousGasPrice,
+          );
+          return { currentNonce, cancelGasPrice };
+        }
+        return { currentNonce, cancelGasPrice: undefined };
+      },
+      `Preparing cancellation for L1 tx from account ${account} with nonce ${nonce}`,
+      makeBackoff(CANCELLATION_PREP_RETRY_BACKOFF_S),
+      this.logger,
+    );
+
+    if (cancelGasPrice === undefined) {
       this.logger.verbose(
         `Not sending cancellation for L1 tx from account ${account} with nonce ${nonce} as it is dropped`,
         { nonce, account, currentNonce },
@@ -717,18 +763,6 @@ export class L1TxUtils extends ReadOnlyL1TxUtils {
       return;
     }
 
-    // Get gas price with higher priority fee for cancellation
-    const cancelGasPrice = await this.getGasPrice(
-      {
-        ...this.config,
-        // Use high bump for cancellation to ensure it replaces the original tx
-        priorityFeeRetryBumpPercentage: 150, // 150% bump should be enough to replace any tx
-      },
-      isBlobTx,
-      state.txHashes.length,
-      previousGasPrice,
-    );
-
     const { maxFeePerGas, maxPriorityFeePerGas, maxFeePerBlobGas } = cancelGasPrice;
     this.logger.verbose(
       `Attempting to cancel L1 ${isBlobTx ? 'blob' : 'vanilla'} transaction from account ${account} with nonce ${nonce} after time out`,

package/src/publisher_manager.ts

@@ -40,11 +40,12 @@ export class PublisherManager<UtilsType extends L1TxUtils = L1TxUtils> {
   private log: Logger;
   private config: PublisherManagerConfig;
   private static readonly FUNDING_CHECK_INTERVAL_MS = 2 * 60 * 1000;
-  private funder?: UtilsType;
-  private fundingPromise?: RunningPromise;
+  protected funder?: UtilsType;
+  protected readonly fundingPromise?: RunningPromise;
+  private started = false;
 
   constructor(
-    private publishers: UtilsType[],
+    protected publishers: UtilsType[],
     config: PublisherManagerConfig,
     opts?: { bindings?: LoggerBindings; funder?: UtilsType },
   ) {
@@ -67,34 +68,60 @@ export class PublisherManager<UtilsType extends L1TxUtils = L1TxUtils> {
         this.funder = undefined;
       }
     }
+
+    if (this.funder && hasThreshold && hasAmount) {
+      this.fundingPromise = new RunningPromise(
+        () => this.triggerFundingIfNeeded(),
+        this.log,
+        PublisherManager.FUNDING_CHECK_INTERVAL_MS,
+      );
+    }
   }
 
-  /** Loads the state of all publishers and the funder, and starts periodic funding checks. */
+  /**
+   * 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(),
     ]);
 
-    if (
-      this.funder &&
-      this.config.publisherFundingThreshold !== undefined &&
-      this.config.publisherFundingAmount !== undefined
-    ) {
-      this.fundingPromise = new RunningPromise(
-        () => this.triggerFundingIfNeeded(),
-        this.log,
-        PublisherManager.FUNDING_CHECK_INTERVAL_MS,
-      );
-      this.fundingPromise.start();
-    }
+    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 and interrupts all publishers. */
+  /**
+   * 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

package/src/test/blob_kzg_warmup.ts

@@ -0,0 +1,65 @@
+import { getBytesPerBlob, getBytesPerCommitment, getKzg } from '@aztec/blob-lib';
+import type { Logger } from '@aztec/foundation/log';
+
+import type { ExtendedViemWalletClient } from '../types.js';
+
+/**
+ * Warms both KZG trusted setups in parallel for tests against a local anvil:
+ *   - anvil's own setup, loaded lazily when it first validates a blob sidecar in `eth_sendRawTransaction`
+ *   - our `@crate-crypto/node-eth-kzg` singleton (`getKzg()`, a ~2.2s synchronous precomp build)
+ *
+ * Without this, the first checkpoint publish pays both serially (~4.4s). The recipe does all RPC round
+ * trips up front, fires a single bare raw send carrying a fake (garbage) blob sidecar that anvil rejects
+ * after loading its trusted setup, yields once to flush the socket write, then synchronously builds our
+ * own precomp tables while anvil warms in parallel. The fake tx is rejected at admission, so it never
+ * enters the pool, mines no block, and burns no nonce — sending it from the passed client is harmless.
+ *
+ * Best-effort: any failure is debug-logged and swallowed, leaving lazy init as the fallback. Never throws.
+ *
+ * @param l1Client - The L1 client whose account sends the (rejected) warm-up blob tx.
+ */
+export async function warmBlobKzg(l1Client: ExtendedViemWalletClient, logger?: Logger): Promise<void> {
+  try {
+    // A pure-JS fake kzg: returns deterministic garbage of the correct lengths (commitment and proof are
+    // both 48 bytes). It makes viem build a syntactically valid sidecar without initializing any native
+    // module, so anvil loads its trusted setup to validate the (invalid) proof and then rejects the tx.
+    const fakeKzg = {
+      blobToKzgCommitment: () => {
+        const commitment = new Uint8Array(getBytesPerCommitment());
+        commitment.fill(0xab);
+        commitment[0] = 0xc0;
+        return commitment;
+      },
+      computeBlobKzgProof: () => {
+        const proof = new Uint8Array(getBytesPerCommitment());
+        proof.fill(0xcd);
+        proof[0] = 0xc0;
+        return proof;
+      },
+    };
+
+    // All RPC round trips (nonce, fees, gas) happen here, so only a single socket write remains to flush.
+    const prepared = await l1Client.prepareTransactionRequest({
+      blobs: [new Uint8Array(getBytesPerBlob())],
+      kzg: fakeKzg,
+      to: '0x0000000000000000000000000000000000000000',
+      value: 0n,
+      maxFeePerBlobGas: 1_000_000_000_000n,
+    });
+    const serialized = await l1Client.signTransaction(prepared);
+
+    // Fire the raw send without awaiting and swallow the expected rejection.
+    const sent = l1Client.request({ method: 'eth_sendRawTransaction', params: [serialized] }).catch(() => {});
+
+    // Flush the single socket write so anvil receives the tx and starts loading its trusted setup in its
+    // own process before we block the event loop below.
+    await new Promise(resolve => setImmediate(resolve));
+
+    // Synchronously build our precomp tables (~2.2s, event-loop-blocking); anvil warms in parallel.
+    getKzg();
+
+    await sent;
+  } catch (err) {
+    logger?.debug('Failed to warm blob KZG; falling back to lazy init', { err });
+  }
+}