@aztec-labs/ethereum 6.0.0-nightly.20260829

package/src/test/start_anvil.ts

@@ -0,0 +1,255 @@
+import { createLogger } from '@aztec-labs/foundation/log';
+import { makeBackoff, retry } from '@aztec-labs/foundation/retry';
+import type { TestDateProvider } from '@aztec-labs/foundation/timer';
+import { type ChildProcess, spawn } from 'child_process';
+
+import { resolveFoundryBinary } from '../foundry_binary.js';
+
+/** Minimal interface matching the @viem/anvil Anvil shape used by callers. */
+export interface Anvil {
+  readonly port: number;
+  readonly host: string;
+  readonly status: 'listening' | 'idle';
+  stop(): Promise<void>;
+}
+
+// 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.
+//
+// The poll loop also exits when ANVIL itself dies: startAnvil detects a failed start via the
+// supervisor's 'close' event, so a supervisor that outlived a dead anvil (e.g. port already in use,
+// unsupported flag) would turn a loud startup error into an unresolvable await — the caller would
+// hang until an outer timeout with no output at all.
+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 && kill -0 "$anvil_pid" 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: {
+    port?: number;
+    l1BlockTime?: number;
+    log?: boolean;
+    captureMethodCalls?: boolean;
+    accounts?: number;
+    chainId?: number;
+    /** The hardfork to use (e.g. 'cancun', 'latest'). */
+    hardfork?: string;
+    /**
+     * Number of slots per epoch used by anvil to compute the 'finalized' and 'safe' block tags.
+     * Anvil reports `finalized = latest - slotsInAnEpoch * 2`.
+     * Defaults to 1 so the finalized block advances immediately, making tests that check
+     * L1-finality-based logic work without needing hundreds of mined blocks.
+     */
+    slotsInAnEpoch?: number;
+    /**
+     * If provided, the date provider will be synced to anvil's block time on every mined block.
+     * This keeps the dateProvider in lockstep with anvil's chain time, avoiding drift between
+     * the wall clock and the L1 chain when computing L1 slot timestamps.
+     */
+    dateProvider?: TestDateProvider;
+  } = {},
+): Promise<{ anvil: Anvil; methodCalls?: string[]; rpcUrl: string; stop: () => Promise<void> }> {
+  const anvilBinary = resolveFoundryBinary('anvil');
+  const logger = opts.log ? createLogger('ethereum:anvil') : undefined;
+  const methodCalls = opts.captureMethodCalls ? ([] as string[]) : undefined;
+
+  let detectedPort: number | undefined;
+
+  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: string[] = [
+        '--host',
+        '127.0.0.1',
+        '--port',
+        String(port),
+        '--accounts',
+        String(opts.accounts ?? 20),
+        '--gas-limit',
+        String(45_000_000),
+        '--chain-id',
+        String(opts.chainId ?? 31337),
+      ];
+      if (opts.l1BlockTime !== undefined) {
+        args.push('--block-time', String(opts.l1BlockTime));
+      }
+      if (opts.hardfork !== undefined) {
+        args.push('--hardfork', opts.hardfork);
+      }
+      args.push('--slots-in-an-epoch', String(opts.slotsInAnEpoch ?? 1));
+
+      // 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', 'pipe'],
+        env: { ...process.env, ANVIL_BIN: anvilBinary, RAYON_NUM_THREADS: '1' },
+      });
+
+      // Wait for "Listening on" or an early exit.
+      await new Promise<void>((resolve, reject) => {
+        let stderr = '';
+
+        const onStdout = (data: Buffer) => {
+          const text = data.toString();
+          logger?.debug(text.trim());
+          methodCalls?.push(...(text.match(/eth_[^\s]+/g) || []));
+
+          if (detectedPort === undefined && text.includes('Listening on')) {
+            const match = text.match(/Listening on ([^:]+):(\d+)/);
+            if (match) {
+              detectedPort = parseInt(match[2]);
+            }
+          }
+          if (detectedPort !== undefined) {
+            child.stdout?.removeListener('data', onStdout);
+            child.stderr?.removeListener('data', onStderr);
+            child.removeListener('close', onClose);
+            resolve();
+          }
+        };
+
+        const onStderr = (data: Buffer) => {
+          stderr += data.toString();
+          logger?.debug(data.toString().trim());
+        };
+
+        const onClose = (code: number | null) => {
+          child.stdout?.removeListener('data', onStdout);
+          child.stderr?.removeListener('data', onStderr);
+          reject(new Error(`Anvil exited with code ${code} before listening. stderr: ${stderr}`));
+        };
+
+        child.stdout?.on('data', onStdout);
+        child.stderr?.on('data', onStderr);
+        child.once('close', onClose);
+      });
+
+      // Continue piping for logging, method-call capture, and/or dateProvider sync after startup.
+      if (logger || opts.captureMethodCalls || opts.dateProvider) {
+        child.stdout?.on('data', (data: Buffer) => {
+          const text = data.toString();
+          logger?.debug(text.trim());
+          methodCalls?.push(...(text.match(/eth_[^\s]+/g) || []));
+          if (opts.dateProvider) {
+            syncDateProviderFromAnvilOutput(text, opts.dateProvider);
+          }
+        });
+        child.stderr?.on('data', (data: Buffer) => {
+          logger?.debug(data.toString().trim());
+        });
+      } else {
+        // Consume streams so the child process doesn't block on full pipe buffers.
+        child.stdout?.resume();
+        child.stderr?.resume();
+      }
+
+      return child;
+    },
+    'Start anvil',
+    makeBackoff([5, 5, 5]),
+  );
+
+  if (!detectedPort) {
+    throw new Error('Failed to start anvil');
+  }
+
+  const port = detectedPort;
+  let status: 'listening' | 'idle' = 'listening';
+
+  anvil.once('close', () => {
+    status = 'idle';
+  });
+
+  const stop = async () => {
+    if (status === 'idle') {
+      return;
+    }
+    await killChild(anvil);
+  };
+
+  const anvilObj: Anvil = {
+    port,
+    host: '127.0.0.1',
+    get status() {
+      return status;
+    },
+    stop,
+  };
+
+  return { anvil: anvilObj, methodCalls, stop, rpcUrl: `http://127.0.0.1:${port}` };
+}
+
+/** Extracts block time from anvil stdout and syncs the dateProvider. */
+function syncDateProviderFromAnvilOutput(text: string, dateProvider: TestDateProvider): void {
+  // Anvil logs mined blocks as:
+  //   Block Time: "Fri, 20 Mar 2026 02:10:46 +0000"
+  const match = text.match(/Block Time:\s*"([^"]+)"/);
+  if (match) {
+    const blockTimeMs = new Date(match[1]).getTime();
+    if (!isNaN(blockTimeMs)) {
+      dateProvider.setTime(blockTimeMs);
+    }
+  }
+}
+
+/**
+ * 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: ChildProcess): Promise<void> {
+  return new Promise<void>(resolve => {
+    if (child.exitCode !== null || child.killed) {
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+      resolve();
+      return;
+    }
+
+    let killTimer: NodeJS.Timeout | undefined;
+
+    const onClose = () => {
+      if (killTimer !== undefined) {
+        clearTimeout(killTimer);
+      }
+      // Destroy stdio streams so their PipeWrap handles don't keep the event loop alive.
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+      resolve();
+    };
+
+    child.once('close', onClose);
+    child.kill('SIGTERM');
+
+    killTimer = setTimeout(() => {
+      killTimer = undefined;
+      child.kill('SIGKILL');
+    }, 5000);
+
+    // Ensure the timer does not prevent Node from exiting.
+    killTimer.unref();
+  });
+}

package/src/test/upgrade_utils.ts

@@ -0,0 +1,109 @@
+import { GovernanceAbi } from '@aztec/l1-artifacts/GovernanceAbi';
+import { TestERC20Abi as StakingAssetAbi } from '@aztec/l1-artifacts/TestERC20Abi';
+
+import type { Logger } from '@aztec-labs/foundation/log';
+import { DateProvider } from '@aztec-labs/foundation/timer';
+import { type GetContractReturnType, type PrivateKeyAccount, getContract } from 'viem';
+
+import { extractProposalIdFromLogs } from '../contracts/governance.js';
+import type { L1ContractAddresses } from '../l1_contract_addresses.js';
+import { createL1TxUtils } from '../l1_tx_utils/index.js';
+import type { ExtendedViemWalletClient, ViemPublicClient } from '../types.js';
+import { EthCheatCodes } from './eth_cheat_codes.js';
+
+export async function executeGovernanceProposal(
+  proposalId: bigint,
+  governance: GetContractReturnType<typeof GovernanceAbi, ViemPublicClient>,
+  voteAmount: bigint,
+  privateKey: PrivateKeyAccount,
+  l1Client: ExtendedViemWalletClient,
+  rpcUrls: string[],
+  logger: Logger,
+) {
+  const proposal = await governance.read.getProposal([proposalId]);
+
+  const l1TxUtils = createL1TxUtils(l1Client);
+
+  const waitL1Block = async () => {
+    await l1TxUtils.sendAndMonitorTransaction({
+      to: l1Client.account.address,
+      value: 1n,
+    });
+  };
+
+  const cheatCodes = new EthCheatCodes(rpcUrls, new DateProvider(), logger);
+
+  const timeToActive = proposal.creation + proposal.config.votingDelay;
+  logger.info(`Warping to ${timeToActive + 1n}`);
+  await cheatCodes.warp(Number(timeToActive + 1n));
+  logger.info(`Warped to ${timeToActive + 1n}`);
+  await waitL1Block();
+
+  logger.info(`Voting`);
+  const voteTx = await governance.write.vote([proposalId, voteAmount, true], { account: privateKey });
+  await l1Client.waitForTransactionReceipt({ hash: voteTx });
+  logger.info(`Voted`);
+
+  const timeToExecutable = timeToActive + proposal.config.votingDuration + proposal.config.executionDelay + 1n;
+  logger.info(`Warping to ${timeToExecutable}`);
+  await cheatCodes.warp(Number(timeToExecutable));
+  logger.info(`Warped to ${timeToExecutable}`);
+  await waitL1Block();
+
+  const executeTx = await governance.write.execute([proposalId], { account: privateKey });
+  await l1Client.waitForTransactionReceipt({ hash: executeTx });
+  logger.info(`Executed proposal`);
+}
+
+export async function createGovernanceProposal(
+  payloadAddress: `0x${string}`,
+  addresses: L1ContractAddresses,
+  privateKey: PrivateKeyAccount,
+  publicClient: ViemPublicClient,
+  logger: Logger,
+): Promise<{
+  governance: GetContractReturnType<typeof GovernanceAbi, ViemPublicClient>;
+  voteAmount: bigint;
+  proposalId: bigint;
+}> {
+  const token = getContract({
+    address: addresses.stakingAssetAddress.toString(),
+    abi: StakingAssetAbi,
+    client: publicClient,
+  });
+
+  const governance = getContract({
+    address: addresses.governanceAddress.toString(),
+    abi: GovernanceAbi,
+    client: publicClient,
+  });
+
+  const lockAmount = 10000n * 10n ** 18n;
+  const voteAmount = 10000n * 10n ** 18n;
+
+  const mintTx = await token.write.mint([privateKey.address, lockAmount + voteAmount], { account: privateKey });
+  await publicClient.waitForTransactionReceipt({ hash: mintTx });
+  logger.info(`Minted tokens`);
+
+  const approveTx = await token.write.approve([addresses.governanceAddress.toString(), lockAmount + voteAmount], {
+    account: privateKey,
+  });
+  await publicClient.waitForTransactionReceipt({ hash: approveTx });
+  logger.info(`Approved tokens`);
+
+  const depositTx = await governance.write.deposit([privateKey.address, lockAmount + voteAmount], {
+    account: privateKey,
+  });
+  await publicClient.waitForTransactionReceipt({ hash: depositTx });
+  logger.info(`Deposited tokens`);
+
+  const proposeTx = await governance.write.proposeWithLock([payloadAddress, privateKey.address], {
+    account: privateKey,
+  });
+  const receipt = await publicClient.waitForTransactionReceipt({ hash: proposeTx });
+  logger.info(`Proposed upgrade`);
+
+  const proposalId = extractProposalIdFromLogs(receipt.logs);
+
+  return { governance, voteAmount, proposalId };
+}

package/src/types.ts

@@ -0,0 +1,97 @@
+import type {
+  Abi,
+  Account,
+  Chain,
+  Client,
+  FallbackTransport,
+  GetContractReturnType,
+  Hex,
+  HttpTransport,
+  PublicActions,
+  PublicClient,
+  PublicRpcSchema,
+  WalletActions,
+  WalletRpcSchema,
+} from 'viem';
+
+/** Type for a viem public client */
+export type ViemPublicClient = PublicClient<FallbackTransport<HttpTransport[]>, Chain>;
+
+export type PublicRpcDebugSchema = [
+  {
+    Method: 'debug_traceTransaction';
+    Parameters: [txHash: `0x${string}`, options: { tracer: 'callTracer' }];
+    ReturnType: DebugCallTrace;
+  },
+  {
+    Method: 'trace_transaction';
+    Parameters: [txHash: `0x${string}`];
+    ReturnType: TraceTransactionResponse[];
+  },
+];
+
+/** Return type for a debug_traceTransaction call */
+export type DebugCallTrace = {
+  from: Hex;
+  to?: Hex;
+  type: string;
+  input?: Hex;
+  output?: Hex;
+  gas?: Hex;
+  gasUsed?: Hex;
+  value?: Hex;
+  error?: string;
+  calls?: DebugCallTrace[];
+};
+
+/** Action object for a trace_transaction call */
+export type TraceAction = {
+  from: Hex;
+  to?: Hex;
+  callType: string;
+  gas?: Hex;
+  input?: Hex;
+  value?: Hex;
+};
+
+/** Result object for a trace_transaction call */
+export type TraceResult = {
+  gasUsed?: Hex;
+  output?: Hex;
+};
+
+/** Return type for a single trace in trace_transaction response */
+export type TraceTransactionResponse = {
+  action: TraceAction;
+  result?: TraceResult;
+  error?: string;
+  subtraces: number;
+  traceAddress: number[];
+  type: string;
+};
+
+/** Type for a viem public client with support for debug methods */
+export type ViemPublicDebugClient = PublicClient<
+  FallbackTransport<HttpTransport[]>,
+  Chain,
+  undefined,
+  [...PublicRpcSchema, ...PublicRpcDebugSchema]
+>;
+
+export type ExtendedViemWalletClient = Client<
+  FallbackTransport<readonly HttpTransport[]>,
+  Chain,
+  Account,
+  [...PublicRpcSchema, ...WalletRpcSchema],
+  PublicActions<FallbackTransport<readonly HttpTransport[]>, Chain> & WalletActions<Chain, Account>
+>;
+
+/** Type for a viem client that can be either public or extended with wallet capabilities */
+export type ViemClient = ViemPublicClient | ExtendedViemWalletClient;
+
+/** Type for a viem contract that can be used with an extended viem client */
+export type ViemContract<TAbi extends Abi> = GetContractReturnType<TAbi, ExtendedViemWalletClient>;
+
+export function isExtendedClient(client: ViemClient): client is ExtendedViemWalletClient {
+  return 'account' in client && client.account !== undefined;
+}