@aztec/ethereum 0.0.1-commit.b2a5d0dd1 → 0.0.1-commit.b3d3157a

package/src/contracts/multicall.ts

@@ -1,16 +1,37 @@
-import { toHex as toPaddedHex } from '@aztec/foundation/bigint-buffer';
-import { TimeoutError } from '@aztec/foundation/error';
+import { EthAddress } from '@aztec/foundation/eth-address';
 import type { Logger } from '@aztec/foundation/log';
 
-import { type Address, type EncodeFunctionDataParameters, type Hex, encodeFunctionData, multicall3Abi } from 'viem';
+import {
+  type Abi,
+  type Address,
+  type BlockOverrides,
+  type Hex,
+  type RequiredBy,
+  type StateOverride,
+  type TransactionReceipt,
+  decodeFunctionResult,
+  encodeFunctionData,
+  multicall3Abi,
+} from 'viem';
 
 import type { L1BlobInputs, L1TxConfig, L1TxRequest, L1TxUtils } from '../l1_tx_utils/index.js';
 import type { ExtendedViemWalletClient } from '../types.js';
-import { FormattedViemError, formatViemError } from '../utils.js';
-import { RollupContract } from './rollup.js';
+import { tryDecodeRevertReason } from '../utils.js';
 
 export const MULTI_CALL_3_ADDRESS = '0xcA11bde05977b3631167028862bE2a173976CA11' as const;
 
+/**
+ * Thrown by `Multicall3.forward` when the forwarder transaction lands but the receipt reports a
+ * reverted status. This is not expected (aggregate3 uses allowFailure: true), so callers should
+ * treat it as a fatal on-chain failure rather than retrying on a different publisher.
+ */
+export class MulticallForwarderRevertedError extends Error {
+  constructor(public readonly receipt: TransactionReceipt) {
+    super(`Multicall3 forwarder tx reverted: ${receipt.transactionHash}`);
+    this.name = 'MulticallForwarderRevertedError';
+  }
+}
+
 /** ABI fragment for aggregate3Value — not included in viem's multicall3Abi. */
 export const aggregate3ValueAbi = [
   {
@@ -44,116 +65,169 @@ export const aggregate3ValueAbi = [
   },
 ] as const;
 
+/** A single call to embed inside an aggregate3 simulation. The abi is used to decode revert reasons. */
+export type SimulateAggregate3Request = {
+  to: Address;
+  data: Hex;
+  /** Optional ABI used to decode the revert reason if this entry reverts. */
+  abi?: Abi;
+};
+
+export type SimulateAggregate3EntryResult = {
+  success: boolean;
+  /** Decoded revert reason text when `success === false` and a request abi was provided. */
+  revertReason?: string;
+  /** Raw return data hex. `'0x'` for successful entries with void return. */
+  returnData: Hex;
+};
+
+/**
+ * Outcome of a bundle simulation.
+ * - `decoded`: eth_simulateV1 ran and produced a per-entry Result[]. Use `entries` for filtering.
+ * - `fallback`: the node does not support eth_simulateV1; `fallbackGasEstimate` was returned and no
+ *    per-entry info is available. Caller should send the bundle as-is with a conservative gas cap.
+ */
+export type SimulateAggregate3Result =
+  | { kind: 'decoded'; entries: SimulateAggregate3EntryResult[]; gasUsed: bigint }
+  | { kind: 'fallback'; gasUsed: bigint };
+
+export type SimulateAggregate3Options = {
+  blockOverrides?: BlockOverrides<bigint, number>;
+  stateOverrides?: StateOverride;
+  /**
+   * If set, append a state override that fakes the sender's balance during the simulation so a
+   * low or zero balance does not cause the simulate to fail with insufficient funds. The fake
+   * balance is applied to `l1TxUtils.getSenderAddress()`.
+   */
+  fakeSenderBalance?: bigint;
+  /** Gas cap to pass on the simulate call itself (defaults to viem's behavior). */
+  gas?: bigint;
+  /** When eth_simulateV1 is unavailable, fall back to this gas estimate instead of throwing. */
+  fallbackGasEstimate?: bigint;
+};
+
 export class Multicall3 {
-  static async forward(
+  /**
+   * Returns true iff Multicall3 bytecode is deployed at MULTI_CALL_3_ADDRESS. An empty result from
+   * a non-existent contract would otherwise silently validate any bundle that uses Multicall3.
+   */
+  static async hasCode(l1TxUtils: L1TxUtils): Promise<boolean> {
+    const code = await l1TxUtils.getCode(EthAddress.fromString(MULTI_CALL_3_ADDRESS));
+    return !!code && code !== '0x';
+  }
+
+  /**
+   * Simulates an aggregate3 call composed of the given requests via eth_simulateV1 and decodes the
+   * per-entry Result[]. Entries that revert are returned with a decoded revertReason (if the request
+   * provided an abi).
+   *
+   * Use this to pre-validate a bundle before sending it through `Multicall3.forward`. The caller can
+   * drop reverted entries from the bundle and re-simulate with the reduced list to get an accurate
+   * `gasUsed`.
+   */
+  static async simulateAggregate3(
+    requests: SimulateAggregate3Request[],
+    l1TxUtils: L1TxUtils,
+    opts: SimulateAggregate3Options = {},
+  ): Promise<SimulateAggregate3Result> {
+    const calldata = encodeFunctionData({
+      abi: multicall3Abi,
+      functionName: 'aggregate3',
+      args: [
+        requests.map(r => ({
+          target: r.to,
+          callData: r.data,
+          allowFailure: true,
+        })),
+      ],
+    });
+
+    const stateOverrides: StateOverride = [...(opts.stateOverrides ?? [])];
+    if (opts.fakeSenderBalance !== undefined) {
+      stateOverrides.push({
+        address: l1TxUtils.getSenderAddress().toString(),
+        balance: opts.fakeSenderBalance,
+      });
+    }
+
+    const simResult = await l1TxUtils.simulate(
+      { to: MULTI_CALL_3_ADDRESS, data: calldata, gas: opts.gas },
+      opts.blockOverrides,
+      stateOverrides,
+      multicall3Abi,
+      { fallbackGasEstimate: opts.fallbackGasEstimate },
+    );
+
+    if (simResult.result === '0x') {
+      return { kind: 'fallback', gasUsed: simResult.gasUsed };
+    }
+
+    const decoded = decodeFunctionResult({
+      abi: multicall3Abi,
+      functionName: 'aggregate3',
+      data: simResult.result,
+    }) as readonly { success: boolean; returnData: `0x${string}` }[];
+
+    const entries: SimulateAggregate3EntryResult[] = decoded.map((entry, i) => {
+      if (entry.success) {
+        return { success: true, returnData: entry.returnData };
+      }
+      const abi = requests[i].abi;
+      const revertReason = abi ? tryDecodeRevertReason(entry.returnData, abi) : undefined;
+      return { success: false, returnData: entry.returnData, revertReason };
+    });
+
+    return { kind: 'decoded', entries, gasUsed: simResult.gasUsed };
+  }
+
+  /**
+   * Sends a batch of requests through aggregate3. Individual calls may fail (allowFailure: true),
+   * but the top-level multicall is expected to land successfully. Throws if the send fails or if
+   * the receipt reports a reverted status.
+   */
+  static async forward<TOptGasLimitRequired extends boolean>(
     requests: L1TxRequest[],
     l1TxUtils: L1TxUtils,
-    gasConfig: L1TxConfig | undefined,
+    gasConfig: TOptGasLimitRequired extends true ? RequiredBy<L1TxConfig, 'gasLimit'> : L1TxConfig | undefined,
     blobConfig: L1BlobInputs | undefined,
-    rollupAddress: Hex,
-    logger: Logger,
-    opts: { revertOnFailure?: boolean } = {},
+    opts: { gasLimitRequired?: TOptGasLimitRequired } = {},
   ) {
-    requests = requests.filter(request => request.to !== null);
-    const args = requests.map(r => ({
-      target: r.to!,
-      callData: r.data!,
-      allowFailure: !opts.revertOnFailure,
-    }));
-    const forwarderFunctionData: Required<EncodeFunctionDataParameters<typeof multicall3Abi, 'aggregate3'>> = {
+    if (opts.gasLimitRequired && !gasConfig?.gasLimit) {
+      throw new Error('Multicall gasLimit is required when gasLimitRequired is true');
+    }
+
+    const args = requests
+      .filter(request => request.to !== null)
+      .map(r => ({
+        target: r.to!,
+        callData: r.data!,
+        allowFailure: true,
+      }));
+    const encodedForwarderData = encodeFunctionData({
       abi: multicall3Abi,
       functionName: 'aggregate3',
       args: [args],
-    };
-
-    const encodedForwarderData = encodeFunctionData(forwarderFunctionData);
-    try {
-      const { receipt, state } = await l1TxUtils.sendAndMonitorTransaction(
-        {
-          to: MULTI_CALL_3_ADDRESS,
-          data: encodedForwarderData,
-          abi: multicall3Abi,
-        },
-        gasConfig,
-        blobConfig,
-      );
-
-      if (receipt.status === 'success') {
-        const stats = await l1TxUtils.getTransactionStats(receipt.transactionHash);
-        return { receipt, stats };
-      } else {
-        logger.error('Forwarder transaction failed', undefined, { receipt });
-
-        const args = {
-          ...forwarderFunctionData,
-          address: MULTI_CALL_3_ADDRESS,
-        };
-
-        let errorMsg: string | undefined;
-
-        if (blobConfig) {
-          const maxFeePerBlobGas = blobConfig.maxFeePerBlobGas ?? state.gasPrice.maxFeePerBlobGas;
-          if (maxFeePerBlobGas === undefined) {
-            errorMsg = 'maxFeePerBlobGas is required to get the error message';
-          } else {
-            logger.debug('Trying to get error from reverted tx with blob config');
-            errorMsg = await l1TxUtils.tryGetErrorFromRevertedTx(
-              encodedForwarderData,
-              args,
-              {
-                blobs: blobConfig.blobs,
-                kzg: blobConfig.kzg,
-                maxFeePerBlobGas,
-              },
-              [
-                {
-                  address: rollupAddress,
-                  stateDiff: [
-                    {
-                      slot: toPaddedHex(RollupContract.checkBlobStorageSlot, true),
-                      value: toPaddedHex(0n, true),
-                    },
-                  ],
-                },
-              ],
-            );
-          }
-        } else {
-          logger.debug('Trying to get error from reverted tx without blob config');
-          errorMsg = await l1TxUtils.tryGetErrorFromRevertedTx(encodedForwarderData, args, undefined, []);
-        }
-
-        return { receipt, errorMsg };
-      }
-    } catch (err) {
-      if (err instanceof TimeoutError) {
-        throw err;
-      }
+    });
 
-      for (const request of requests) {
-        logger.debug('Simulating request', { request });
-        const result = await l1TxUtils
-          .simulate(request, undefined, [
-            {
-              address: rollupAddress,
-              stateDiff: [
-                { slot: toPaddedHex(RollupContract.checkBlobStorageSlot, true), value: toPaddedHex(0n, true) },
-              ],
-            },
-          ])
-          .catch(err => formatViemError(err, request.abi));
-        if (result instanceof FormattedViemError) {
-          logger.error('Found error in simulation', result, {
-            to: request.to ?? 'null',
-            data: request.data,
-          });
-
-          return result;
-        }
-      }
-      logger.warn('Failed to get error from reverted tx', { err });
-      throw err;
+    const { receipt } = await l1TxUtils.sendAndMonitorTransaction(
+      {
+        to: MULTI_CALL_3_ADDRESS,
+        data: encodedForwarderData,
+        abi: multicall3Abi,
+      },
+      gasConfig,
+      blobConfig,
+    );
+
+    // This shouldn't happen. Any failure in individual calls is swallowed by forward since we set
+    // allowFailure to true for all calls, so a reverted status here would indicate a problem with
+    // the Multicall3 contract itself or the forwarder transaction (such as an out-of-gas).
+    if (receipt.status !== 'success') {
+      throw new MulticallForwarderRevertedError(receipt);
     }
+
+    const stats = await l1TxUtils.getTransactionStats(receipt.transactionHash);
+    return { receipt, stats, multicallData: encodedForwarderData };
   }
 
   /** Batch multiple value transfers into a single aggregate3Value call on Multicall3. */

package/src/contracts/outbox.ts

@@ -1,4 +1,5 @@
 import type { EpochNumber } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import { OutboxAbi } from '@aztec/l1-artifacts/OutboxAbi';
 
@@ -38,12 +39,24 @@ export class OutboxContract {
 
   static getFromConfig(config: L1ReaderConfig) {
     const client = getPublicClient(config);
-    const address = config.l1Contracts.outboxAddress.toString();
+    const address = config.outboxAddress.toString();
     return new OutboxContract(client, address);
   }
 
-  static getEpochRootStorageSlot(epoch: EpochNumber) {
-    return hexToBigInt(keccak256(encodeAbiParameters([{ type: 'uint256' }, { type: 'uint256' }], [BigInt(epoch), 0n])));
+  /**
+   * Storage slot of `epochs[epoch].roots[numCheckpointsInEpoch - 1]` in the Outbox contract.
+   *
+   * The Outbox lays out storage as `mapping(Epoch => EpochData) internal epochs` at base slot 0
+   * (ROLLUP and VERSION are immutable and do not occupy slots). For a mapping at slot `b`, the
+   * value for key `k` begins at `keccak256(abi.encode(k, b))`. `EpochData` starts with a fixed-
+   * size `bytes32[MAX_CHECKPOINTS_PER_EPOCH] roots` array, so `roots[i]` sits at the EpochData's
+   * base slot plus `i`. `numCheckpointsInEpoch` is 1-indexed (matches `Outbox.insert`/`consume`).
+   */
+  static getEpochRootStorageSlot(epoch: EpochNumber, numCheckpointsInEpoch: number) {
+    const epochDataSlot = hexToBigInt(
+      keccak256(encodeAbiParameters([{ type: 'uint256' }, { type: 'uint256' }], [BigInt(epoch), 0n])),
+    );
+    return epochDataSlot + BigInt(numCheckpointsInEpoch - 1);
   }
 
   constructor(
@@ -68,24 +81,45 @@ export class OutboxContract {
     return this.outbox.read.hasMessageBeenConsumedAtEpoch([BigInt(epoch), leafId]);
   }
 
-  public getRootData(epoch: EpochNumber) {
-    return this.outbox.read.getRootData([BigInt(epoch)]);
+  public getRootData(epoch: EpochNumber, numCheckpointsInEpoch: number) {
+    return this.outbox.read.getRootData([BigInt(epoch), BigInt(numCheckpointsInEpoch)]);
   }
 
-  public consume(message: ViemL2ToL1Msg, epoch: EpochNumber, leafIndex: bigint, path: Hex[]) {
+  /**
+   * Returns every root stored for `epoch`. Slot `i` of the returned array holds the root inserted
+   * for `numCheckpointsInEpoch = i + 1`, or `Fr.ZERO` if no proof of that depth has been inserted
+   * yet. The array length is always `MAX_CHECKPOINTS_PER_EPOCH`.
+   *
+   * @param opts - Optional viem read options. Pass `blockNumber` to pin the read to a specific L1
+   *   block, which is important for callers that want a consistent snapshot across multiple reads
+   *   (e.g. the archiver's outbox-trees resolver, which pins to the node's synced L1 block).
+   */
+  public async getRoots(epoch: EpochNumber, opts?: { blockNumber?: bigint }): Promise<Fr[]> {
+    const raw = await this.outbox.read.getRoots([BigInt(epoch)], opts);
+    return raw.map(hex => Fr.fromString(hex));
+  }
+
+  public consume(
+    message: ViemL2ToL1Msg,
+    epoch: EpochNumber,
+    numCheckpointsInEpoch: number,
+    leafIndex: bigint,
+    path: Hex[],
+  ) {
     const wallet = this.assertWallet();
-    return wallet.write.consume([message, BigInt(epoch), leafIndex, path]);
+    return wallet.write.consume([message, BigInt(epoch), BigInt(numCheckpointsInEpoch), leafIndex, path]);
   }
 
   public async getMessageConsumedEvents(
     l1BlockHash: Hex,
-  ): Promise<{ epoch: bigint; root: Hex; messageHash: Hex; leafId: bigint }[]> {
+  ): Promise<{ epoch: bigint; root: Hex; messageHash: Hex; leafId: bigint; numCheckpointsInEpoch: bigint }[]> {
     const events = await this.outbox.getEvents.MessageConsumed({}, { blockHash: l1BlockHash, strict: true });
     return events.map(event => ({
       epoch: event.args.epoch!,
       root: event.args.root!,
       messageHash: event.args.messageHash!,
       leafId: event.args.leafId!,
+      numCheckpointsInEpoch: event.args.numCheckpointsInEpoch!,
     }));
   }
 

package/src/contracts/rollup.ts

@@ -6,6 +6,7 @@ import { EthAddress } from '@aztec/foundation/eth-address';
 import type { ViemSignature } from '@aztec/foundation/eth-signature';
 import { createLogger } from '@aztec/foundation/log';
 import { makeBackoff, retry } from '@aztec/foundation/retry';
+import { getErrorCause } from '@aztec/foundation/types';
 import { EscapeHatchAbi } from '@aztec/l1-artifacts/EscapeHatchAbi';
 import { RollupAbi } from '@aztec/l1-artifacts/RollupAbi';
 import { RollupStorage } from '@aztec/l1-artifacts/RollupStorage';
@@ -13,11 +14,14 @@ import { RollupStorage } from '@aztec/l1-artifacts/RollupStorage';
 import chunk from 'lodash.chunk';
 import {
   type Account,
+  ContractFunctionRevertedError,
   type GetContractReturnType,
   type Hex,
   type Log,
+  RpcRequestError,
   type StateOverride,
   type WatchContractEventReturnType,
+  decodeErrorResult,
   encodeAbiParameters,
   encodeFunctionData,
   getContract,
@@ -140,6 +144,20 @@ export enum TempCheckpointLogField {
   FeeHeader = 6,
 }
 
+/**
+ * Field-level override input for `tempCheckpointLogs[checkpointNumber]`. Covers the fields the
+ * `propose()` path actually reads back. `payloadDigest` is `Buffer32` because it carries an
+ * arbitrary `bytes32` value rather than a BN254 scalar. `slotNumber` carries the uint32 portion
+ * of the on-chain `CompressedSlot`.
+ */
+export type TempCheckpointLogOverrideFields = {
+  headerHash?: Fr;
+  outHash?: Fr;
+  payloadDigest?: Buffer32;
+  slotNumber?: SlotNumber;
+  feeHeader?: FeeHeader;
+};
+
 /** Components of the minimum fee per mana, as returned by the L1 rollup contract. */
 export type ManaMinFeeComponents = {
   sequencerCost: bigint;
@@ -216,6 +234,32 @@ export type CheckpointProposedArgs = {
 /** Log type for CheckpointProposed events. */
 export type CheckpointProposedLog = L1EventLog<CheckpointProposedArgs>;
 
+const INSUFFICIENT_VALIDATOR_SET_SIZE_ERROR = 'ValidatorSelection__InsufficientValidatorSetSize';
+
+function isValidatorSelectionError(err: unknown, errorName: string): boolean {
+  return (
+    getErrorCause(err, ContractFunctionRevertedError)?.data?.errorName === errorName ||
+    decodeRpcRequestErrorName(err) === errorName
+  );
+}
+
+function decodeRpcRequestErrorName(err: unknown): string | undefined {
+  const data = getErrorCause(err, RpcRequestError)?.data;
+  if (!isHexString(data)) {
+    return undefined;
+  }
+
+  try {
+    return decodeErrorResult({ abi: RollupAbi, data }).errorName;
+  } catch {
+    return undefined;
+  }
+}
+
+function isHexString(value: unknown): value is Hex {
+  return typeof value === 'string' && value.startsWith('0x');
+}
+
 export class RollupContract {
   private readonly rollup: GetContractReturnType<typeof RollupAbi, ViemClient>;
   private readonly logger = createLogger('ethereum:rollup');
@@ -248,7 +292,7 @@ export class RollupContract {
 
   static getFromConfig(config: L1ReaderConfig) {
     const client = getPublicClient(config);
-    const address = config.l1Contracts.rollupAddress.toString();
+    const address = config.rollupAddress.toString();
     return new RollupContract(client, address);
   }
 
@@ -574,7 +618,7 @@ export class RollupContract {
         args: [timestamp],
       })
       .catch(e => {
-        if (e instanceof Error && e.message.includes('ValidatorSelection__InsufficientValidatorSetSize')) {
+        if (isValidatorSelectionError(e, INSUFFICIENT_VALIDATOR_SET_SIZE_ERROR)) {
           return { result: undefined };
         }
         throw e;
@@ -604,7 +648,7 @@ export class RollupContract {
         args: [],
       })
       .catch(e => {
-        if (e instanceof Error && e.message.includes('ValidatorSelection__InsufficientValidatorSetSize')) {
+        if (isValidatorSelectionError(e, INSUFFICIENT_VALIDATOR_SET_SIZE_ERROR)) {
           return { result: undefined };
         }
         throw e;
@@ -844,20 +888,32 @@ export class RollupContract {
   }
 
   /**
-   * Returns a state override that sets the pending checkpoint number to the specified value. Useful for simulations.
-   * Requires querying the current state of the contract to get the current proven checkpoint number, as they are both
-   * stored in the same slot. If the argument is undefined, it returns an empty override.
+   * Returns a state override that sets the pending and/or proven checkpoint numbers. Useful for simulations.
+   * Both values share a single storage slot (pending in the upper 128 bits, proven in the lower 128 bits), so
+   * a single combined override is emitted to avoid the second state-diff clobbering the first. The current live
+   * value is read once to preserve any half not being overridden. Returns an empty override if neither is set.
+   *
+   * Throws if the resulting `proven > pending`, which would crash the simulation: `STFLib.canPruneAtTime` calls
+   * `getEpochForCheckpoint(proven + 1)` whenever `pending != proven`, and that asserts `_n <= tips.pending`.
    */
-  public async makePendingCheckpointNumberOverride(
-    forcePendingCheckpointNumber: CheckpointNumber | undefined,
-  ): Promise<StateOverride> {
-    if (forcePendingCheckpointNumber === undefined) {
+  public async makeChainTipsOverride(override: {
+    pending?: CheckpointNumber;
+    proven?: CheckpointNumber;
+  }): Promise<StateOverride> {
+    if (override.pending === undefined && override.proven === undefined) {
       return [];
     }
     const slot = RollupContract.stfStorageSlot;
     const currentValue = await this.client.getStorageAt({ address: this.address, slot });
-    const currentProvenCheckpointNumber = currentValue ? hexToBigInt(currentValue) & ((1n << 128n) - 1n) : 0n;
-    const newValue = (BigInt(forcePendingCheckpointNumber) << 128n) | currentProvenCheckpointNumber;
+    const currentRaw = currentValue ? hexToBigInt(currentValue) : 0n;
+    const currentPending = currentRaw >> 128n;
+    const currentProven = currentRaw & ((1n << 128n) - 1n);
+    const newPending = override.pending !== undefined ? BigInt(override.pending) : currentPending;
+    const newProven = override.proven !== undefined ? BigInt(override.proven) : currentProven;
+    if (newProven > newPending) {
+      throw new Error(`Invalid chain tips override: proven (${newProven}) > pending (${newPending})`);
+    }
+    const newValue = (newPending << 128n) | newProven;
     return [
       {
         address: this.address,
@@ -867,39 +923,56 @@ export class RollupContract {
   }
 
   /**
-   * Returns a state override that sets tempCheckpointLogs[checkpointNumber].feeHeader to the compressed fee header.
-   * Used when simulating a propose call where the parent checkpoint hasn't landed on L1 yet (pipelining).
+   * Returns a state override that patches `tempCheckpointLogs[checkpointNumber]` with every field that
+   * the L1 contract reads during `propose()` for the checkpoint that builds on top of it (proposer
+   * pipelining simulation). Mirrors the writes done by `ProposeLib.addTempCheckpointLog`.
+   *
+   * `blobCommitmentsHash` and `attestationsHash` are intentionally not exposed here — the propose path
+   * never asserts against them, so leaving them at storage zero is harmless.
    */
-  public async makeFeeHeaderOverride(checkpointNumber: CheckpointNumber, feeHeader: FeeHeader): Promise<StateOverride> {
-    const { epochDuration, proofSubmissionEpochs } = await this.getRollupConstants();
-    const roundaboutSize = BigInt(epochDuration * (proofSubmissionEpochs + 1) + 1);
-    const circularIndex = BigInt(checkpointNumber) % roundaboutSize;
-
-    // tempCheckpointLogs is at offset 2 in RollupStore
-    const tempCheckpointLogsMappingBase = hexToBigInt(RollupContract.stfStorageSlot) + 2n;
+  public async makeTempCheckpointLogOverride(
+    checkpointNumber: CheckpointNumber,
+    fields: TempCheckpointLogOverrideFields,
+  ): Promise<StateOverride> {
+    const constants = await this.getRollupConstants();
+    const slotAt = (field: TempCheckpointLogField) =>
+      `0x${this.computeTempCheckpointLogStorageSlot(checkpointNumber, field, constants).toString(16).padStart(64, '0')}` as const;
+    const word = (v: bigint) => `0x${v.toString(16).padStart(64, '0')}` as const;
 
-    // Solidity mapping slot: keccak256(abi.encode(key, baseSlot))
-    const structBaseSlot = hexToBigInt(
-      keccak256(
-        encodeAbiParameters([{ type: 'uint256' }, { type: 'uint256' }], [circularIndex, tempCheckpointLogsMappingBase]),
-      ),
-    );
+    const stateDiff: { slot: `0x${string}`; value: `0x${string}` }[] = [];
 
-    // feeHeader is the 7th field (offset 6) in CompressedTempCheckpointLog
-    const feeHeaderSlot = structBaseSlot + 6n;
-    const compressed = RollupContract.compressFeeHeader(feeHeader);
+    if (fields.headerHash) {
+      stateDiff.push({ slot: slotAt(TempCheckpointLogField.HeaderHash), value: fields.headerHash.toString() });
+    }
+    if (fields.outHash) {
+      stateDiff.push({ slot: slotAt(TempCheckpointLogField.OutHash), value: fields.outHash.toString() });
+    }
+    if (fields.payloadDigest) {
+      stateDiff.push({
+        slot: slotAt(TempCheckpointLogField.PayloadDigest),
+        value: fields.payloadDigest.toString() as `0x${string}`,
+      });
+    }
+    if (fields.slotNumber !== undefined) {
+      // CompressedSlot is uint32 on L1 (SafeCast.toUint32 reverts on overflow). Match that behavior here
+      // so a malformed override surfaces immediately rather than silently truncating into a wrong slot.
+      const slotNumber = BigInt(fields.slotNumber);
+      if (slotNumber < 0n || slotNumber > 0xffffffffn) {
+        throw new Error(`slotNumber ${slotNumber} does not fit in uint32`);
+      }
+      stateDiff.push({ slot: slotAt(TempCheckpointLogField.SlotNumber), value: word(slotNumber) });
+    }
+    if (fields.feeHeader) {
+      stateDiff.push({
+        slot: slotAt(TempCheckpointLogField.FeeHeader),
+        value: word(RollupContract.compressFeeHeader(fields.feeHeader)),
+      });
+    }
 
-    return [
-      {
-        address: this.address,
-        stateDiff: [
-          {
-            slot: `0x${feeHeaderSlot.toString(16).padStart(64, '0')}`,
-            value: `0x${compressed.toString(16).padStart(64, '0')}`,
-          },
-        ],
-      },
-    ];
+    if (stateDiff.length === 0) {
+      return [];
+    }
+    return [{ address: this.address, stateDiff }];
   }
 
   /**
@@ -1330,11 +1403,20 @@ export class RollupContract {
     checkpointNumber: CheckpointNumber,
     field: TempCheckpointLogField,
   ): Promise<bigint> {
-    const fieldOffset = BigInt(field);
     const [epochDuration, proofSubmissionEpochs] = await Promise.all([
       this.getEpochDuration(),
       this.getProofSubmissionEpochs(),
     ]);
+    return this.computeTempCheckpointLogStorageSlot(checkpointNumber, field, { epochDuration, proofSubmissionEpochs });
+  }
+
+  private computeTempCheckpointLogStorageSlot(
+    checkpointNumber: CheckpointNumber,
+    field: TempCheckpointLogField,
+    constants: { epochDuration: number; proofSubmissionEpochs: number },
+  ): bigint {
+    const fieldOffset = BigInt(field);
+    const { epochDuration, proofSubmissionEpochs } = constants;
     const roundaboutSize = BigInt(epochDuration) * (BigInt(proofSubmissionEpochs) + 1n) + 1n;
     const tempCheckpointLogsBase = BigInt(RollupContract.stfStorageSlot) + 2n;
     const circularIndex = BigInt(checkpointNumber) % roundaboutSize;