@aztec/ethereum 0.0.1-commit.2ed92850 → 0.0.1-commit.3100065

package/dest/utils.js

@@ -1,9 +1,10 @@
 import { ErrorsAbi } from '@aztec/l1-artifacts/ErrorsAbi';
 import { BaseError, ContractFunctionRevertedError, decodeErrorResult, decodeEventLog } from 'viem';
+import { formatAbiItem, formatAbiParams } from 'viem/utils';
 export class FormattedViemError extends Error {
     metaMessages;
-    constructor(message, metaMessages){
-        super(message);
+    constructor(message, metaMessages, options){
+        super(message, options);
         this.name = 'FormattedViemError';
         this.metaMessages = metaMessages;
     }
@@ -46,6 +47,51 @@ export function prettyLogViemErrorMsg(err) {
     }
     return err?.message ?? err;
 }
+export function mergeAbis(abis) {
+    let merged = [];
+    const seen = new Set();
+    for (const abi of abis){
+        for (const item of abi){
+            const key = getAbiItemKey(item);
+            if (!seen.has(key)) {
+                seen.add(key);
+                merged = [
+                    ...merged,
+                    item
+                ];
+            }
+        }
+    }
+    return merged;
+}
+function getAbiItemKey(item) {
+    if (item.type === 'function') {
+        const signature = formatAbiItem(item);
+        const outputs = formatAbiParams(item.outputs);
+        const stateMutability = typeof item.stateMutability === 'string' ? item.stateMutability : '';
+        return `function:${signature}:${outputs}:${stateMutability}`;
+    }
+    if (item.type === 'event') {
+        const signature = formatAbiItem(item);
+        const indexed = (item.inputs ?? []).map((input)=>input.indexed ? '1' : '0').join('');
+        const anonymous = item.anonymous ? 'anonymous' : 'not-anonymous';
+        return `event:${signature}:${indexed}:${anonymous}`;
+    }
+    if (item.type === 'error') {
+        const signature = formatAbiItem(item);
+        return `error:${signature}`;
+    }
+    if (item.type === 'constructor') {
+        const inputs = formatAbiParams(item.inputs);
+        const stateMutability = typeof item.stateMutability === 'string' ? item.stateMutability : '';
+        return `constructor::${inputs}:${stateMutability}`;
+    }
+    if (item.type === 'fallback' || item.type === 'receive') {
+        const stateMutability = typeof item.stateMutability === 'string' ? item.stateMutability : '';
+        return `${item.type}:::${stateMutability}`;
+    }
+    return 'unknown';
+}
 function getNestedErrorData(error) {
     // If nothing, bail
     if (!error) {
@@ -66,6 +112,19 @@ function getNestedErrorData(error) {
     // Not found
     return undefined;
 }
+/**
+ * Truncates an error message to a safe length for log renderers.
+ * LogExplorer can only render up to 2500 characters in its summary view.
+ * We cap at 2000 to leave room for decorating context added by callers.
+ */ function truncateErrorMessage(message) {
+    const MAX = 2000;
+    const CHUNK = 950;
+    if (message.length <= MAX) {
+        return message;
+    }
+    const truncated = message.length - 2 * CHUNK;
+    return message.slice(0, CHUNK) + `...${truncated} characters truncated...` + message.slice(-CHUNK);
+}
 /**
  * Formats a Viem error into a FormattedViemError instance.
  * @param error - The error to format.
@@ -76,6 +135,7 @@ function getNestedErrorData(error) {
     if (error instanceof FormattedViemError) {
         return error;
     }
+    const originalError = error;
     // First try to decode as a custom error using the ABI
     try {
         const data = getNestedErrorData(error);
@@ -86,7 +146,9 @@ function getNestedErrorData(error) {
                 data: data
             });
             if (decoded) {
-                return new FormattedViemError(`${decoded.errorName}(${decoded.args?.join(', ') ?? ''})`, error?.metaMessages);
+                return new FormattedViemError(`${decoded.errorName}(${decoded.args?.join(', ') ?? ''})`, error?.metaMessages, {
+                    cause: originalError
+                });
             }
         }
         // If it's a BaseError, try to get the custom error through ContractFunctionRevertedError
@@ -98,36 +160,36 @@ function getNestedErrorData(error) {
                     errorName = revertError.signature ?? '';
                 }
                 const args = revertError.metaMessages && revertError.metaMessages?.length > 1 ? revertError.metaMessages[1].trimStart() : '';
-                return new FormattedViemError(`${errorName}${args}`, error?.metaMessages);
+                return new FormattedViemError(`${errorName}${args}`, error?.metaMessages, {
+                    cause: originalError
+                });
             }
         }
     } catch  {
     // If decoding fails, we fall back to the original formatting
     }
-    // Strip ABI from the error object before formatting
+    // Strip ABI from the error object before formatting. We clone first to avoid mutating the
+    // caller's error, but structuredClone throws DataCloneError on values it cannot clone (e.g.
+    // viem RPC errors carrying function-valued request context). If cloning fails, fall back to
+    // formatting the original error untouched rather than letting the clone failure mask it.
     if (error && typeof error === 'object') {
-        // Create a clone to avoid modifying the original
-        const errorClone = structuredClone(error);
-        // Helper function to recursively remove ABI properties
-        // Strip ABIs from the clone
-        stripAbis(errorClone);
-        // Use the cleaned clone for further processing
-        error = errorClone;
+        try {
+            const errorClone = structuredClone(error);
+            stripAbis(errorClone);
+            error = errorClone;
+        } catch  {
+        // Leave `error` as the original; we skip stripAbis to avoid mutating the caller's object.
+        }
     }
     // If it's a regular Error instance, return it with its message
     if (error instanceof Error) {
-        return new FormattedViemError(error.message, error?.metaMessages);
-    }
-    const body = String(error);
-    const length = body.length;
-    // LogExplorer can only render up to 2500 characters in it's summary view. Try to keep the whole message below this number
-    // Limit the error to 2000 chacaters in order to allow code higher up to decorate this error with extra details (up to 500 characters)
-    if (length > 2000) {
-        const chunk = 950;
-        const truncated = length - 2 * chunk;
-        return new FormattedViemError(body.slice(0, chunk) + `...${truncated} characters truncated...` + body.slice(-1 * chunk));
-    }
-    return new FormattedViemError(body);
+        return new FormattedViemError(truncateErrorMessage(error.message), error?.metaMessages, {
+            cause: originalError
+        });
+    }
+    return new FormattedViemError(truncateErrorMessage(String(error)), undefined, {
+        cause: originalError
+    });
 }
 function stripAbis(obj) {
     if (!obj || typeof obj !== 'object') {
@@ -148,6 +210,25 @@ function stripAbis(obj) {
         }
     });
 }
+/**
+ * Best-effort decode of a raw revert payload (`0x...`) against an ABI.
+ * Returns a human-readable `ErrorName(arg1, arg2, ...)` string, or `undefined` if the selector
+ * is unknown or the payload is empty. Use to surface decoded error names alongside the raw
+ * payload in log lines for operators.
+ */ export function tryDecodeRevertReason(data, abi) {
+    if (!data || data === '0x') {
+        return undefined;
+    }
+    try {
+        const decoded = decodeErrorResult({
+            abi,
+            data
+        });
+        return `${decoded.errorName}(${decoded.args?.join(', ') ?? ''})`;
+    } catch  {
+        return undefined;
+    }
+}
 export function tryGetCustomErrorName(err) {
     try {
         // See https://viem.sh/docs/contract/simulateContract#handling-custom-errors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/ethereum",
-  "version": "0.0.1-commit.2ed92850",
+  "version": "0.0.1-commit.3100065",
   "type": "module",
   "exports": {
     "./account": "./dest/account.js",
@@ -50,17 +50,16 @@
     "../package.common.json"
   ],
   "dependencies": {
-    "@aztec/blob-lib": "0.0.1-commit.2ed92850",
-    "@aztec/constants": "0.0.1-commit.2ed92850",
-    "@aztec/foundation": "0.0.1-commit.2ed92850",
-    "@aztec/l1-artifacts": "0.0.1-commit.2ed92850",
-    "@viem/anvil": "^0.0.10",
+    "@aztec/blob-lib": "0.0.1-commit.3100065",
+    "@aztec/constants": "0.0.1-commit.3100065",
+    "@aztec/foundation": "0.0.1-commit.3100065",
+    "@aztec/l1-artifacts": "0.0.1-commit.3100065",
     "dotenv": "^16.0.3",
     "lodash.chunk": "^4.2.0",
     "lodash.pickby": "^4.5.0",
     "tslib": "^2.4.0",
     "viem": "npm:@aztec/viem@2.38.2",
-    "zod": "^3.23.8"
+    "zod": "^4"
   },
   "devDependencies": {
     "@jest/globals": "^30.0.0",
@@ -69,7 +68,6 @@
     "@types/lodash.pickby": "^4",
     "@types/node": "^22.15.17",
     "@typescript/native-preview": "7.0.0-dev.20260113.1",
-    "@viem/anvil": "^0.0.10",
     "get-port": "^7.1.0",
     "jest": "^30.0.0",
     "jest-mock-extended": "^4.0.0",

package/src/client.ts

@@ -1,9 +1,13 @@
 import type { Logger } from '@aztec/foundation/log';
 import { retryUntil } from '@aztec/foundation/retry';
+import { getErrorCause } from '@aztec/foundation/types';
 
 import {
   type Chain,
+  type FallbackTransport,
   type HDAccount,
+  HttpRequestError,
+  type HttpTransport,
   type LocalAccount,
   type PrivateKeyAccount,
   createPublicClient,
@@ -25,10 +29,69 @@ type Config = {
   l1ChainId: number;
   /** The polling interval viem uses in ms */
   viemPollingIntervalMS?: number;
+  /** Timeout for HTTP requests to the L1 RPC node in ms. */
+  l1HttpTimeoutMS?: number;
 };
 
 export type { Config as EthereumClientConfig };
 
+/** Error exposed by L1 RPC transports without including provider URLs in its message. */
+export class L1RpcError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'L1RpcError';
+  }
+}
+
+/** Creates a viem fallback HTTP transport for the given L1 RPC URLs. */
+export function makeL1HttpTransport(rpcUrls: string[], opts?: { timeout?: number }) {
+  return wrapL1RpcTransport(fallback(rpcUrls.map(url => http(url, { batch: false, timeout: opts?.timeout }))));
+}
+
+/** Returns the HTTP status from an L1 RPC error's cause chain, if one is available. */
+export function getL1RpcHttpStatus(err: unknown): number | undefined {
+  return getErrorCause(err, HttpRequestError)?.status;
+}
+
+/** Returns true when an L1 RPC error's cause chain contains the given HTTP status. */
+export function isL1RpcHttpStatus(err: unknown, status: number): boolean {
+  return getL1RpcHttpStatus(err) === status;
+}
+
+function wrapL1RpcTransport(transport: FallbackTransport<HttpTransport[]>): FallbackTransport<HttpTransport[]> {
+  const wrappedTransport: FallbackTransport<HttpTransport[]> = parameters => {
+    const fallbackTransport = transport(parameters);
+    const request: typeof fallbackTransport.request = async args => {
+      try {
+        return await fallbackTransport.request(args);
+      } catch (err) {
+        throw err instanceof L1RpcError ? err : new L1RpcError('L1 RPC request failed', { cause: err });
+      }
+    };
+    return { ...fallbackTransport, request };
+  };
+
+  return wrappedTransport;
+}
+
+/**
+ * Returns the individual RPC URLs underlying a viem public client that was constructed with a
+ * fallback HTTP transport (see {@link makeL1HttpTransport}). Returns an empty array if the
+ * transport shape is not recognized (e.g. mock clients in tests, or non-fallback transports).
+ */
+export function getRpcUrlsFromClient(client: ViemPublicClient): string[] {
+  const transport = client.transport as unknown as {
+    transports?: { value?: { url?: string } }[];
+    value?: { url?: string };
+    url?: string;
+  };
+  if (Array.isArray(transport?.transports)) {
+    return transport.transports.map(t => t?.value?.url).filter((url): url is string => typeof url === 'string');
+  }
+  const singleUrl = transport?.value?.url ?? transport?.url;
+  return typeof singleUrl === 'string' ? [singleUrl] : [];
+}
+
 // TODO: Use these methods to abstract the creation of viem clients.
 
 /** Returns a viem public client given the L1 config. */
@@ -36,7 +99,7 @@ export function getPublicClient(config: Config): ViemPublicClient {
   const chain = createEthereumChain(config.l1RpcUrls, config.l1ChainId);
   return createPublicClient({
     chain: chain.chainInfo,
-    transport: fallback(config.l1RpcUrls.map(url => http(url, { batch: false }))),
+    transport: makeL1HttpTransport(config.l1RpcUrls, { timeout: config.l1HttpTimeoutMS }),
     pollingInterval: config.viemPollingIntervalMS,
   });
 }
@@ -77,6 +140,7 @@ export function createExtendedL1Client(
   chain: Chain = foundry,
   pollingIntervalMS?: number,
   addressIndex?: number,
+  opts?: { httpTimeoutMS?: number },
 ): ExtendedViemWalletClient {
   const hdAccount =
     typeof mnemonicOrPrivateKeyOrHdAccount === 'string'
@@ -88,7 +152,7 @@ export function createExtendedL1Client(
   const extendedClient = createWalletClient({
     account: hdAccount,
     chain,
-    transport: fallback(rpcUrls.map(url => http(url, { batch: false }))),
+    transport: makeL1HttpTransport(rpcUrls, { timeout: opts?.httpTimeoutMS }),
     pollingInterval: pollingIntervalMS,
   }).extend(publicActions);
 

package/src/config.ts

@@ -2,10 +2,10 @@ import {
   type ConfigMappingsType,
   bigintConfigHelper,
   booleanConfigHelper,
-  enumConfigHelper,
   getConfigFromMappings,
   getDefaultConfig,
   numberConfigHelper,
+  omitConfigMappings,
   optionalNumberConfigHelper,
 } from '@aztec/foundation/config';
 import { EthAddress } from '@aztec/foundation/eth-address';
@@ -18,6 +18,8 @@ export type GenesisStateConfig = {
   testAccounts: boolean;
   /** Whether to populate the genesis state with initial fee juice for the sponsored FPC */
   sponsoredFPC: boolean;
+  /** Additional addresses to prefund with fee juice at genesis */
+  prefundAddresses: string[];
 };
 
 export type L1ContractsConfig = {
@@ -57,13 +59,13 @@ export type L1ContractsConfig = {
   slashingOffsetInRounds: number;
   /** How long slashing can be disabled for in seconds when vetoer disables it */
   slashingDisableDuration: number;
-  /** Type of slasher proposer */
-  slasherFlavor: 'empire' | 'tally' | 'none';
-  /** Minimum amount that can be slashed in tally slashing */
+  /** Whether to deploy a slasher proposer */
+  slasherEnabled: boolean;
+  /** Minimum amount that can be slashed */
   slashAmountSmall: bigint;
-  /** Medium amount to slash in tally slashing */
+  /** Medium amount to slash */
   slashAmountMedium: bigint;
-  /** Largest amount that can be slashed per round in tally slashing */
+  /** Largest amount that can be slashed per round */
   slashAmountLarge: bigint;
   /** Governance proposing quorum (defaults to roundSize/2 + 1) */
   governanceProposerQuorum?: number;
@@ -99,7 +101,7 @@ export const l1ContractsConfigMappings: ConfigMappingsType<L1ContractsConfig> =
   },
   aztecEpochDuration: {
     env: 'AZTEC_EPOCH_DURATION',
-    description: `How many L2 slots an epoch lasts (maximum AZTEC_MAX_EPOCH_DURATION).`,
+    description: `How many L2 slots an epoch lasts (maximum MAX_CHECKPOINTS_PER_EPOCH).`,
     ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_EPOCH_DURATION),
   },
   aztecTargetCommitteeSize: {
@@ -149,13 +151,10 @@ export const l1ContractsConfigMappings: ConfigMappingsType<L1ContractsConfig> =
       'How many slashing rounds back we slash (ie when slashing in round N, we slash for offenses committed during epochs of round N-offset)',
     ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_SLASHING_OFFSET_IN_ROUNDS),
   },
-  slasherFlavor: {
-    env: 'AZTEC_SLASHER_FLAVOR',
-    description: 'Type of slasher proposer (empire, tally, or none)',
-    ...enumConfigHelper(
-      ['empire', 'tally', 'none'] as const,
-      l1ContractsDefaultEnv.AZTEC_SLASHER_FLAVOR as 'empire' | 'tally' | 'none',
-    ),
+  slasherEnabled: {
+    env: 'AZTEC_SLASHER_ENABLED',
+    description: 'Whether to deploy a slasher proposer',
+    ...booleanConfigHelper(true),
   },
   slashAmountSmall: {
     env: 'AZTEC_SLASH_AMOUNT_SMALL',
@@ -238,7 +237,7 @@ export const l1ContractsConfigMappings: ConfigMappingsType<L1ContractsConfig> =
     description: 'The delay before a validator can exit the set',
     ...numberConfigHelper(l1ContractsDefaultEnv.AZTEC_EXIT_DELAY_SECONDS),
   },
-  ...l1TxUtilsConfigMappings,
+  ...omitConfigMappings(l1TxUtilsConfigMappings, ['ethereumSlotDuration']),
 };
 
 /**
@@ -247,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',
@@ -258,6 +292,16 @@ export const genesisStateConfigMappings: ConfigMappingsType<GenesisStateConfig>
     description: 'Whether to populate the genesis state with initial fee juice for the sponsored FPC.',
     ...booleanConfigHelper(false),
   },
+  prefundAddresses: {
+    env: 'PREFUND_ADDRESSES',
+    description: 'Comma-separated list of Aztec addresses to prefund with fee juice at genesis (local network only).',
+    parseEnv: (val: string) =>
+      val
+        .split(',')
+        .map(a => a.trim())
+        .filter(a => a.length > 0),
+    defaultValue: [],
+  },
 };
 
 export function getL1ContractsConfigEnvVars(): L1ContractsConfig {

package/src/contracts/chain_state_override.ts

@@ -0,0 +1,200 @@
+import { toHex as toPaddedHex } from '@aztec/foundation/bigint-buffer';
+import type { CheckpointNumber, SlotNumber } from '@aztec/foundation/branded-types';
+import type { Buffer32 } from '@aztec/foundation/buffer';
+import { merge } from '@aztec/foundation/collection';
+import type { Fr } from '@aztec/foundation/curves/bn254';
+
+import type { StateOverride } from 'viem';
+
+import { type FeeHeader, RollupContract } from './rollup.js';
+
+/**
+ * Override values for the pending checkpoint that the simulation should treat as already applied.
+ * Every field is optional at plan-building time so callers can populate them incrementally; whatever
+ * is present at translation time is forwarded to the partial `tempCheckpointLogs` helper so the
+ * load-bearing `slotNumber` can land even if other fields could not be derived locally.
+ */
+export type PendingCheckpointOverrideState = {
+  archive?: Fr;
+  feeHeader?: FeeHeader;
+  headerHash?: Fr;
+  outHash?: Fr;
+  payloadDigest?: Buffer32;
+  slotNumber?: SlotNumber;
+};
+
+export type ChainTipsOverride = {
+  pending?: CheckpointNumber;
+  proven?: CheckpointNumber;
+};
+
+/** Describes the simulated L1 rollup state that downstream calls should observe. */
+export type SimulationOverridesPlan = {
+  chainTipsOverride?: ChainTipsOverride;
+  pendingCheckpointState?: PendingCheckpointOverrideState;
+  disableBlobCheck?: boolean;
+};
+
+/** Builds a single-checkpoint simulation plan before it is translated into a viem state override. */
+export class SimulationOverridesBuilder {
+  private chainTipsOverride?: ChainTipsOverride;
+  private pendingCheckpointState?: PendingCheckpointOverrideState;
+  private disableBlobCheck = false;
+
+  /** Starts from an existing plan so callers can extend or specialize it. */
+  public static from(plan: SimulationOverridesPlan | undefined): SimulationOverridesBuilder {
+    return new SimulationOverridesBuilder().merge(plan);
+  }
+
+  /**
+   * Merges another plan into this builder. Later values win on a per-half basis for chain tips,
+   * but explicit `undefined` fields in the incoming plan are ignored so they cannot erase a
+   * previously-set value.
+   */
+  public merge(plan: SimulationOverridesPlan | undefined): this {
+    if (!plan) {
+      return this;
+    }
+
+    if (plan.chainTipsOverride) {
+      this.chainTipsOverride = merge(this.chainTipsOverride ?? {}, plan.chainTipsOverride);
+    }
+    if (plan.pendingCheckpointState) {
+      this.pendingCheckpointState = merge(this.pendingCheckpointState ?? {}, plan.pendingCheckpointState);
+    }
+    this.disableBlobCheck = this.disableBlobCheck || (plan.disableBlobCheck ?? false);
+
+    return this;
+  }
+
+  /**
+   * Sets the pending and/or proven checkpoint number overrides. Subsequent calls merge into the existing
+   * override on a per-half basis, so callers can set pending in one call and proven in another without
+   * clobbering each other.
+   */
+  public withChainTips(override: ChainTipsOverride): this {
+    this.chainTipsOverride = { ...(this.chainTipsOverride ?? {}), ...override };
+    return this;
+  }
+
+  /** Overrides the archive root for the configured pending checkpoint. */
+  public withPendingArchive(archive: Fr): this {
+    this.assertPendingCheckpointNumber();
+    this.pendingCheckpointState = { ...(this.pendingCheckpointState ?? {}), archive };
+    return this;
+  }
+
+  /** Overrides the fee header for the configured pending checkpoint. */
+  public withPendingFeeHeader(feeHeader: FeeHeader): this {
+    this.assertPendingCheckpointNumber();
+    this.pendingCheckpointState = { ...(this.pendingCheckpointState ?? {}), feeHeader };
+    return this;
+  }
+
+  /**
+   * Overrides one or more `tempCheckpointLogs` cell fields for the configured pending checkpoint.
+   * Fields are independent: any subset can be provided. The translator (`makeTempCheckpointLogOverride`)
+   * emits a stateDiff entry per field actually set, so unspecified fields stay at their on-chain
+   * values.
+   *
+   * `slotNumber` is load-bearing for `STFLib.canPruneAtTime`: when the simulation overrides `pending`
+   * to a checkpoint that has no on-chain `tempCheckpointLogs` entry yet, the missing slotNumber falls
+   * back to 0 and the contract treats the pending tip as belonging to epoch 0, triggering a phantom
+   * prune that silently undoes the `pending` override.
+   */
+  public withPendingTempCheckpointLogFields(fields: {
+    headerHash?: Fr;
+    outHash?: Fr;
+    payloadDigest?: Buffer32;
+    slotNumber?: SlotNumber;
+  }): this {
+    this.assertPendingCheckpointNumber();
+    this.pendingCheckpointState = { ...(this.pendingCheckpointState ?? {}), ...fields };
+    return this;
+  }
+
+  /** Disables blob checking for simulations that cannot provide DA inputs. */
+  public withoutBlobCheck(): this {
+    this.disableBlobCheck = true;
+    return this;
+  }
+
+  /** Builds the final plan, or `undefined` when no overrides were configured. */
+  public build(): SimulationOverridesPlan | undefined {
+    if (!this.pendingCheckpointState && !this.chainTipsOverride && !this.disableBlobCheck) {
+      return undefined;
+    }
+
+    return {
+      chainTipsOverride: this.chainTipsOverride,
+      pendingCheckpointState: this.pendingCheckpointState,
+      disableBlobCheck: this.disableBlobCheck || undefined,
+    };
+  }
+
+  private assertPendingCheckpointNumber(): void {
+    if (this.chainTipsOverride?.pending === undefined) {
+      throw new Error('withChainTips({ pending }) must be called before attaching archive or fee header overrides');
+    }
+  }
+}
+
+/** Translates a simulation plan into the viem state override shape expected by rollup calls. */
+export async function buildSimulationOverridesStateOverride(
+  rollup: RollupContract,
+  plan: SimulationOverridesPlan | undefined,
+): Promise<StateOverride> {
+  if (!plan) {
+    return [];
+  }
+
+  const rollupStateDiff: NonNullable<StateOverride[number]['stateDiff']> = [];
+
+  if (plan.chainTipsOverride) {
+    rollupStateDiff.push(...extractRollupStateDiff(await rollup.makeChainTipsOverride(plan.chainTipsOverride)));
+  }
+
+  if (plan.pendingCheckpointState && plan.chainTipsOverride?.pending === undefined) {
+    throw new Error('pendingCheckpointState requires chainTipsOverride.pending to be set');
+  }
+
+  if (plan.pendingCheckpointState?.archive) {
+    rollupStateDiff.push(
+      ...extractRollupStateDiff(
+        rollup.makeArchiveOverride(plan.chainTipsOverride!.pending!, plan.pendingCheckpointState.archive),
+      ),
+    );
+  }
+
+  if (plan.pendingCheckpointState) {
+    rollupStateDiff.push(
+      ...extractRollupStateDiff(
+        await rollup.makeTempCheckpointLogOverride(plan.chainTipsOverride!.pending!, {
+          headerHash: plan.pendingCheckpointState.headerHash,
+          outHash: plan.pendingCheckpointState.outHash,
+          payloadDigest: plan.pendingCheckpointState.payloadDigest,
+          slotNumber: plan.pendingCheckpointState.slotNumber,
+          feeHeader: plan.pendingCheckpointState.feeHeader,
+        }),
+      ),
+    );
+  }
+
+  if (plan.disableBlobCheck) {
+    rollupStateDiff.push({
+      slot: toPaddedHex(RollupContract.checkBlobStorageSlot, true),
+      value: toPaddedHex(0n, true),
+    });
+  }
+
+  if (rollupStateDiff.length === 0) {
+    return [];
+  }
+
+  return [{ address: rollup.address, stateDiff: rollupStateDiff }];
+}
+
+function extractRollupStateDiff(override: StateOverride | StateOverride[number] | undefined) {
+  const entries = Array.isArray(override) ? override : override ? [override] : [];
+  return entries.flatMap(entry => entry.stateDiff ?? []);
+}

package/src/contracts/fee_asset_handler.ts

@@ -43,6 +43,7 @@ export class FeeAssetHandlerContract {
     }
     return txUtils.sendAndMonitorTransaction({
       to: this.address.toString(),
+      abi: FeeAssetHandlerAbi,
       data: encodeFunctionData({
         abi: FeeAssetHandlerAbi,
         functionName: 'mint',
@@ -54,6 +55,7 @@ export class FeeAssetHandlerContract {
   public setMintAmount(txUtils: L1TxUtils, amount: bigint) {
     return txUtils.sendAndMonitorTransaction({
       to: this.address.toString(),
+      abi: FeeAssetHandlerAbi,
       data: encodeFunctionData({
         abi: FeeAssetHandlerAbi,
         functionName: 'setMintAmount',