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

package/src/contracts/governance_proposer.ts

@@ -15,11 +15,19 @@ import {
 import type { L1TxRequest, L1TxUtils } from '../l1_tx_utils/index.js';
 import type { ViemClient } from '../types.js';
 import { type IEmpireBase, encodeSignal, encodeSignalWithSignature, signSignalWithSig } from './empire_base.js';
-import { extractProposalIdFromLogs } from './governance.js';
+import { ReadOnlyGovernanceContract, extractProposalIdFromLogs } from './governance.js';
 
 export class GovernanceProposerContract implements IEmpireBase {
   private readonly proposer: GetContractReturnType<typeof GovernanceProposerAbi, ViemClient>;
 
+  /**
+   * Cache of bytecode-existence checks keyed by payload address. The check is stable for a
+   * contract's lifetime -- a contract either has code or it does not, and code cannot be removed
+   * after deployment (selfdestruct aside, which is not relevant here). Safe to memoize
+   * indefinitely for the lifetime of this instance.
+   */
+  private readonly emptyPayloadCache: Map<Hex, boolean> = new Map();
+
   constructor(
     public readonly client: ViemClient,
     address: Hex | EthAddress,
@@ -83,6 +91,7 @@ export class GovernanceProposerContract implements IEmpireBase {
   public createSignalRequest(payload: Hex): L1TxRequest {
     return {
       to: this.address.toString(),
+      abi: GovernanceProposerAbi,
       data: encodeSignal(payload),
     };
   }
@@ -104,10 +113,56 @@ export class GovernanceProposerContract implements IEmpireBase {
     );
     return {
       to: this.address.toString(),
+      abi: GovernanceProposerAbi,
       data: encodeSignalWithSignature(payload, signature),
     };
   }
 
+  /**
+   * Resolves the Governance contract this proposer submits winners to. Lazily reads
+   * `GovernanceProposer.getGovernance()` (which itself looks the address up via the registry) and
+   * memoizes the resulting wrapper.
+   */
+  @memoize
+  public async getGovernance(): Promise<ReadOnlyGovernanceContract> {
+    const address = await this.proposer.read.getGovernance();
+    return new ReadOnlyGovernanceContract(address, this.client);
+  }
+
+  /**
+   * Returns true iff the given original payload is currently the subject of a live (non-terminal)
+   * Governance proposal. Delegates to `ReadOnlyGovernanceContract.hasActiveProposalWithPayload`, which
+   * implements the actual sweep against the Governance contract -- this method exists only as a
+   * convenience wrapper so callers that already hold a GovernanceProposer reference don't have to
+   * resolve the Governance address themselves.
+   */
+  public async hasActiveProposalWithPayload(payload: Hex): Promise<boolean> {
+    const governance = await this.getGovernance();
+    return governance.hasActiveProposalWithPayload(payload);
+  }
+
+  /**
+   * Returns true if the given payload address has no deployed bytecode. Used as a cheap
+   * pre-flight check before casting a governance signal — voting for a zero-code address
+   * is unrecoverable.
+   *
+   * We only cache the `false` result (address has bytecode). The `true` result is NOT
+   * cached because a CREATE2-redeployed address could go from empty to populated, and
+   * caching `true` would make us keep skipping a payload that later becomes valid.
+   */
+  public async isPayloadEmpty(payload: EthAddress): Promise<boolean> {
+    const key = payload.toString() as Hex;
+    if (this.emptyPayloadCache.get(key) === false) {
+      return false;
+    }
+    const code = await this.client.getCode({ address: key });
+    const isEmpty = !code || code === '0x';
+    if (!isEmpty) {
+      this.emptyPayloadCache.set(key, false);
+    }
+    return isEmpty;
+  }
+
   public async submitRoundWinner(
     round: bigint,
     l1TxUtils: L1TxUtils,
@@ -117,8 +172,9 @@ export class GovernanceProposerContract implements IEmpireBase {
   }> {
     const { receipt } = await l1TxUtils.sendAndMonitorTransaction({
       to: this.address.toString(),
+      abi: GovernanceProposerAbi,
       data: encodeFunctionData({
-        abi: this.proposer.abi,
+        abi: GovernanceProposerAbi,
         functionName: 'submitRoundWinner',
         args: [round],
       }),

package/src/contracts/gse.ts

@@ -47,11 +47,16 @@ export class GSEContract {
     return EthAddress.fromString(await this.gse.read.getGovernance());
   }
 
-  getAttestersFromIndicesAtTime(instance: Hex | EthAddress, ts: bigint, indices: bigint[]) {
+  getAttestersFromIndicesAtTime(
+    instance: Hex | EthAddress,
+    ts: bigint,
+    indices: bigint[],
+    options?: { blockNumber?: bigint },
+  ) {
     if (instance instanceof EthAddress) {
       instance = instance.toString();
     }
-    return this.gse.read.getAttestersFromIndicesAtTime([instance, ts, indices]);
+    return this.gse.read.getAttestersFromIndicesAtTime([instance, ts, indices], options);
   }
 
   public async getRegistrationDigest(publicKey: ProjPointType<bigint>): Promise<ProjPointType<bigint>> {

package/src/contracts/inbox.ts

@@ -1,3 +1,4 @@
+import { maxBigint } from '@aztec/foundation/bigint';
 import { CheckpointNumber } from '@aztec/foundation/branded-types';
 import { Buffer16, Buffer32 } from '@aztec/foundation/buffer';
 import { Fr } from '@aztec/foundation/curves/bn254';
@@ -37,7 +38,7 @@ export class InboxContract {
 
   static getFromConfig(config: L1ReaderConfig) {
     const client = getPublicClient(config);
-    const address = config.l1Contracts.inboxAddress.toString();
+    const address = config.inboxAddress.toString();
     return new InboxContract(client, address);
   }
 
@@ -82,10 +83,17 @@ export class InboxContract {
       .map(log => this.mapMessageSentLog(log));
   }
 
-  /** Fetches MessageSent events for a specific message hash within the given block range. */
-  async getMessageSentEventByHash(hash: Hex, fromBlock: bigint, toBlock: bigint): Promise<MessageSentLog[]> {
-    const logs = await this.inbox.getEvents.MessageSent({ hash }, { fromBlock, toBlock });
-    return logs.map(log => this.mapMessageSentLog(log));
+  /** Fetches MessageSent events for a specific message hash around a specific block. */
+  async getMessageSentEventByHash(msgHash: Hex, aroundL1BlockNumber: bigint): Promise<MessageSentLog> {
+    // We don't use blockHash here because we don't want the query to throw if the L1 block number no longer exists on chain
+    // due to an L1 reorg. The use case for this method is usually checking if a message still exists on the Inbox after
+    // a reorg, so it's possible the message was moved one block up or down, and that the original L1 block where we
+    // saw it no longer exists, rendering the block-by-hash approach invalid.
+    const [log] = await this.inbox.getEvents.MessageSent(
+      { hash: msgHash },
+      { fromBlock: maxBigint(aroundL1BlockNumber - 5n, 1n), toBlock: aroundL1BlockNumber + 5n },
+    );
+    return log && this.mapMessageSentLog(log);
   }
 
   private mapMessageSentLog(log: {

package/src/contracts/index.ts

@@ -1,6 +1,8 @@
+export * from './chain_state_override.js';
 export * from './empire_base.js';
 export * from './errors.js';
 export * from './fee_asset_handler.js';
+export * from './fee_asset_price_oracle.js';
 export * from './fee_juice.js';
 export * from './governance.js';
 export * from './governance_proposer.js';
@@ -11,6 +13,5 @@ export * from './multicall.js';
 export * from './outbox.js';
 export * from './registry.js';
 export * from './rollup.js';
-export * from './empire_slashing_proposer.js';
-export * from './tally_slashing_proposer.js';
+export * from './slashing_proposer.js';
 export * from './slasher_contract.js';

package/src/contracts/multicall.ts

@@ -1,123 +1,264 @@
-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 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 = [
+  {
+    inputs: [
+      {
+        components: [
+          { internalType: 'address', name: 'target', type: 'address' },
+          { internalType: 'bool', name: 'allowFailure', type: 'bool' },
+          { internalType: 'uint256', name: 'value', type: 'uint256' },
+          { internalType: 'bytes', name: 'callData', type: 'bytes' },
+        ],
+        internalType: 'struct Multicall3.Call3Value[]',
+        name: 'calls',
+        type: 'tuple[]',
+      },
+    ],
+    name: 'aggregate3Value',
+    outputs: [
+      {
+        components: [
+          { internalType: 'bool', name: 'success', type: 'bool' },
+          { internalType: 'bytes', name: 'returnData', type: 'bytes' },
+        ],
+        internalType: 'struct Multicall3.Result[]',
+        name: 'returnData',
+        type: 'tuple[]',
+      },
+    ],
+    stateMutability: 'payable',
+    type: 'function',
+  },
+] 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 },
-        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. */
+  static async forwardValue(calls: { to: Address; value: bigint }[], l1TxUtils: L1TxUtils, logger: Logger) {
+    const args = calls.map(c => ({
+      target: c.to,
+      allowFailure: false,
+      value: c.value,
+      callData: '0x' as Hex,
+    }));
+
+    const data = encodeFunctionData({
+      abi: aggregate3ValueAbi,
+      functionName: 'aggregate3Value',
+      args: [args],
+    });
+
+    const totalValue = calls.reduce((sum, c) => sum + c.value, 0n);
+
+    logger.info(`Sending aggregate3Value with ${calls.length} calls`, { totalValue });
+    const { receipt } = await l1TxUtils.sendAndMonitorTransaction({
+      to: MULTI_CALL_3_ADDRESS,
+      data,
+      value: totalValue,
+    });
+
+    if (receipt.status !== 'success') {
+      throw new Error(`aggregate3Value transaction reverted: ${receipt.transactionHash}`);
+    }
+
+    return { receipt };
   }
 }
 

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/registry.ts

@@ -3,7 +3,7 @@ import { createLogger } from '@aztec/foundation/log';
 import { RegistryAbi } from '@aztec/l1-artifacts/RegistryAbi';
 import { TestERC20Abi } from '@aztec/l1-artifacts/TestERC20Abi';
 
-import { type GetContractReturnType, type Hex, getContract } from 'viem';
+import { type GetContractReturnType, type Hex, getAbiItem, getContract } from 'viem';
 
 import type { L1ContractAddresses } from '../l1_contract_addresses.js';
 import type { ViemClient } from '../types.js';
@@ -128,4 +128,34 @@ export class RegistryContract {
   public async getRewardDistributor(): Promise<EthAddress> {
     return EthAddress.fromString(await this.registry.read.getRewardDistributor());
   }
+
+  /** Returns the L1 timestamp at which the given rollup was registered via addRollup(). */
+  public async getCanonicalRollupRegistrationTimestamp(
+    rollupAddress: EthAddress,
+    fromBlock?: bigint,
+  ): Promise<bigint | undefined> {
+    const event = getAbiItem({ abi: RegistryAbi, name: 'CanonicalRollupUpdated' });
+    const start = fromBlock ?? 0n;
+    const latestBlock = await this.client.getBlockNumber();
+    const chunkSize = 1_000n;
+
+    for (let from = start; from <= latestBlock; from += chunkSize) {
+      const to = from + chunkSize - 1n > latestBlock ? latestBlock : from + chunkSize - 1n;
+      const logs = await this.client.getLogs({
+        address: this.address.toString(),
+        fromBlock: from,
+        toBlock: to,
+        strict: true,
+        event,
+        args: { instance: rollupAddress.toString() },
+      });
+
+      if (logs.length > 0) {
+        const block = await this.client.getBlock({ blockNumber: logs[0].blockNumber });
+        return block.timestamp;
+      }
+    }
+
+    return undefined;
+  }
 }