@aztec/ethereum 0.0.1-commit.7d4e6cd → 0.0.1-commit.858058eac

package/src/contracts/README.md

@@ -0,0 +1,157 @@
+# L1 Contract Wrappers
+
+This folder contains TypeScript wrappers for L1 contracts defined in `l1-contracts/`. These wrappers are used by the node client to interact with the rollup and related contracts on Ethereum.
+
+## Purpose
+
+The goal of wrapping is to shield consumers from L1-specific and viem-specific details. Clients using these wrappers interact with domain types and branded types native to the Aztec codebase, without needing to understand viem's ABI type system or deal with raw types like `Hex` and `bigint`.
+
+## Type Safety
+
+### Explicit Return Types
+
+Every function in the contract wrappers must declare its return type explicitly. This is critical because viem's type inference over ABI types is slow and significantly impacts IDE performance.
+
+```typescript
+// Good: Explicit return type
+async getSlotNumber(): Promise<SlotNumber> {
+  return SlotNumber.fromBigInt(await this.rollup.read.getCurrentSlot());
+}
+
+// Bad: Inferred return type (slow)
+async getSlotNumber() {
+  return SlotNumber.fromBigInt(await this.rollup.read.getCurrentSlot());
+}
+```
+
+### Branded and Domain Types
+
+Use branded types and domain-specific types instead of viem's autogenerated types for both arguments and return values:
+
+- `CheckpointNumber`, `EpochNumber`, `SlotNumber` instead of `bigint`
+- `EthAddress` instead of `` `0x${string}` `` or `Hex`
+- `Fr`, `Buffer32` instead of `Hex` for hashes and field elements
+- Custom domain types (e.g., `CheckpointLog`, `AttesterView`) instead of raw tuples
+
+Type conversions happen inside wrapper methods, not at the call site:
+
+```typescript
+async getCheckpoint(checkpointNumber: CheckpointNumber): Promise<CheckpointLog> {
+  const result = await this.rollup.read.getCheckpoint([BigInt(checkpointNumber)]);
+  return {
+    archive: Fr.fromString(result.archive),
+    headerHash: Buffer32.fromString(result.headerHash),
+    blockCount: result.blockCount,
+  };
+}
+```
+
+## Wrapper Pattern
+
+### Basic Structure
+
+Each wrapper follows a consistent structure:
+
+```typescript
+export class FooContract {
+  private readonly foo: GetContractReturnType<typeof FooAbi, ViemClient>;
+
+  constructor(
+    public readonly client: ViemClient,
+    address: Hex | EthAddress,
+  ) {
+    if (address instanceof EthAddress) {
+      address = address.toString();
+    }
+    this.foo = getContract({ address, abi: FooAbi, client });
+  }
+
+  public get address(): Hex {
+    return this.foo.address;
+  }
+
+  public getContract(): GetContractReturnType<typeof FooAbi, ViemClient> {
+    return this.foo;
+  }
+}
+```
+
+The raw contract is exposed via `getContract()` for cases where direct access is needed, but most consumers should use the typed wrapper methods. Relying on `getContract()` is a code smell and should be avoided.
+
+### Static Factory Methods
+
+Wrappers may provide static factory methods for common initialization patterns:
+
+- `getFromConfig(config)` - construct from configuration object
+- `getFromL1ContractsValues(deployResult)` - construct from deployment result
+
+### Wallet Assertions
+
+For write operations that require a wallet, use an assertion helper:
+
+```typescript
+private assertWallet(): GetContractReturnType<typeof FooAbi, ExtendedViemWalletClient> {
+  if (!isExtendedClient(this.client)) {
+    throw new Error('Wallet client is required for this operation');
+  }
+  return this.foo as GetContractReturnType<typeof FooAbi, ExtendedViemWalletClient>;
+}
+```
+
+## Event Handling
+
+### Event Log Types
+
+Event logs are wrapped in `L1EventLog<T>` to include L1 block context:
+
+```typescript
+type L1EventLog<T> = {
+  l1BlockNumber: bigint;
+  l1BlockHash: Buffer32;
+  l1TransactionHash: Hex;
+  args: T;
+};
+```
+
+### Event Fetching
+
+Methods that fetch events convert viem's raw logs to domain types:
+
+```typescript
+async getCheckpointProposedEvents(fromBlock: bigint, toBlock: bigint): Promise<CheckpointProposedLog[]> {
+  const logs = await this.rollup.getEvents.CheckpointProposed({}, { fromBlock, toBlock });
+  return logs.map(log => ({
+    l1BlockNumber: log.blockNumber!,
+    l1BlockHash: Buffer32.fromString(log.blockHash!),
+    l1TransactionHash: log.transactionHash!,
+    args: {
+      checkpointNumber: CheckpointNumber.fromBigInt(log.args.checkpointNumber!),
+      // ... convert other fields
+    },
+  }));
+}
+```
+
+### Event Listeners
+
+For reactive event handling, wrapper methods convert arguments before invoking callbacks:
+
+```typescript
+public listenToCheckpointInvalidated(
+  callback: (args: { checkpointNumber: CheckpointNumber }) => unknown,
+): WatchContractEventReturnType {
+  return this.rollup.watchEvent.CheckpointInvalidated({}, {
+    onLogs: logs => {
+      for (const log of logs) {
+        if (log.args.checkpointNumber !== undefined) {
+          callback({ checkpointNumber: CheckpointNumber.fromBigInt(log.args.checkpointNumber) });
+        }
+      }
+    },
+  });
+}
+```
+
+## Error Handling
+
+Custom error classes in `errors.ts` extend `Error` and set `this.name` for proper error identification. Include relevant context as public readonly properties.

package/src/contracts/empire_slashing_proposer.ts

@@ -6,7 +6,6 @@ import { EmpireSlashingProposerAbi } from '@aztec/l1-artifacts/EmpireSlashingPro
 
 import EventEmitter from 'events';
 import {
-  type EncodeFunctionDataParameters,
   type GetContractReturnType,
   type Hex,
   type Log,
@@ -100,6 +99,7 @@ export class EmpireSlashingProposerContract extends EventEmitter implements IEmp
   public createSignalRequest(payload: Hex): L1TxRequest {
     return {
       to: this.address.toString(),
+      abi: EmpireSlashingProposerAbi,
       data: encodeSignal(payload),
     };
   }
@@ -121,6 +121,7 @@ export class EmpireSlashingProposerContract extends EventEmitter implements IEmp
     );
     return {
       to: this.address.toString(),
+      abi: EmpireSlashingProposerAbi,
       data: encodeSignalWithSignature(payload, signature),
     };
   }
@@ -180,6 +181,7 @@ export class EmpireSlashingProposerContract extends EventEmitter implements IEmp
   public buildExecuteRoundRequest(round: bigint): L1TxRequest {
     return {
       to: this.address.toString(),
+      abi: EmpireSlashingProposerAbi,
       data: encodeFunctionData({
         abi: EmpireSlashingProposerAbi,
         functionName: 'submitRoundWinner',
@@ -222,24 +224,13 @@ export class EmpireSlashingProposerContract extends EventEmitter implements IEmp
     if (typeof round === 'number') {
       round = BigInt(round);
     }
-    const args: EncodeFunctionDataParameters<typeof EmpireSlashingProposerAbi, 'submitRoundWinner'> = {
-      abi: EmpireSlashingProposerAbi,
-      functionName: 'submitRoundWinner',
-      args: [round],
-    };
-    const data = encodeFunctionData(args);
+    const request = this.buildExecuteRoundRequest(round);
     const response = await txUtils
-      .sendAndMonitorTransaction(
-        {
-          to: this.address.toString(),
-          data,
-        },
-        {
-          // Gas estimation is way off for this, likely because we are creating the contract/selector to call
-          // for the actual slashing dynamically.
-          gasLimitBufferPercentage: 50, // +50% gas
-        },
-      )
+      .sendAndMonitorTransaction(request, {
+        // Gas estimation is way off for this, likely because we are creating the contract/selector to call
+        // for the actual slashing dynamically.
+        gasLimitBufferPercentage: 50, // +50% gas
+      })
       .catch(err => {
         if (err instanceof FormattedViemError && err.message.includes('ProposalAlreadyExecuted')) {
           throw new ProposalAlreadyExecutedError(round);
@@ -248,15 +239,13 @@ export class EmpireSlashingProposerContract extends EventEmitter implements IEmp
       });
 
     if (response.receipt.status === 'reverted') {
-      const error = await txUtils.tryGetErrorFromRevertedTx(
-        data,
-        {
-          ...args,
-          address: this.address.toString(),
-        },
-        undefined,
-        [],
-      );
+      const args = {
+        abi: EmpireSlashingProposerAbi,
+        functionName: 'submitRoundWinner' as const,
+        args: [round] as const,
+        address: this.address.toString(),
+      };
+      const error = await txUtils.tryGetErrorFromRevertedTx(request.data!, args, undefined, []);
       if (error?.includes('ProposalAlreadyExecuted')) {
         throw new ProposalAlreadyExecutedError(round);
       }

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',

package/src/contracts/governance.ts

@@ -174,6 +174,13 @@ export class GovernanceContract extends ReadOnlyGovernanceContract {
     return this.governanceContract.read.powerAt([this.client.account.address, now.timestamp]);
   }
 
+  /** Returns the user's voting power for a specific proposal, checked at pendingThrough timestamp. */
+  public async getPowerForProposal(proposalId: bigint): Promise<bigint> {
+    const proposal = await this.getProposal(proposalId);
+    const pendingThrough = proposal.creation + proposal.config.votingDelay;
+    return this.governanceContract.read.powerAt([this.client.account.address, pendingThrough]);
+  }
+
   public async vote({
     proposalId,
     voteAmount,
@@ -190,7 +197,7 @@ export class GovernanceContract extends ReadOnlyGovernanceContract {
     const l1TxUtils = createL1TxUtilsFromViemWallet(this.client, { logger });
     const retryDelaySeconds = 12;
 
-    voteAmount = voteAmount ?? (await this.getPower());
+    voteAmount = voteAmount ?? (await this.getPowerForProposal(proposalId));
 
     let success = false;
     for (let i = 0; i < retries; i++) {
@@ -204,6 +211,7 @@ export class GovernanceContract extends ReadOnlyGovernanceContract {
 
         const { receipt } = await l1TxUtils.sendAndMonitorTransaction({
           to: this.governanceContract.address,
+          abi: GovernanceAbi,
           data: encodedVoteData,
         });
 
@@ -258,6 +266,7 @@ export class GovernanceContract extends ReadOnlyGovernanceContract {
 
         const { receipt } = await l1TxUtils.sendAndMonitorTransaction({
           to: this.governanceContract.address,
+          abi: GovernanceAbi,
           data: encodedExecuteData,
         });
 

package/src/contracts/governance_proposer.ts

@@ -83,6 +83,7 @@ export class GovernanceProposerContract implements IEmpireBase {
   public createSignalRequest(payload: Hex): L1TxRequest {
     return {
       to: this.address.toString(),
+      abi: GovernanceProposerAbi,
       data: encodeSignal(payload),
     };
   }
@@ -104,6 +105,7 @@ export class GovernanceProposerContract implements IEmpireBase {
     );
     return {
       to: this.address.toString(),
+      abi: GovernanceProposerAbi,
       data: encodeSignalWithSignature(payload, signature),
     };
   }
@@ -117,8 +119,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/inbox.ts

@@ -1,4 +1,6 @@
-import { Buffer16 } from '@aztec/foundation/buffer';
+import { CheckpointNumber } from '@aztec/foundation/branded-types';
+import { Buffer16, Buffer32 } from '@aztec/foundation/buffer';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import { InboxAbi } from '@aztec/l1-artifacts/InboxAbi';
 
@@ -8,8 +10,20 @@ import { getPublicClient } from '../client.js';
 import type { DeployAztecL1ContractsReturnType } from '../deploy_aztec_l1_contracts.js';
 import type { L1ReaderConfig } from '../l1_reader.js';
 import type { ViemClient } from '../types.js';
+import type { L1EventLog } from './log.js';
 import { checkBlockTag } from './utils.js';
 
+/** Arguments for the MessageSent event. */
+export type MessageSentArgs = {
+  index: bigint;
+  leaf: Fr;
+  checkpointNumber: CheckpointNumber;
+  rollingHash: Buffer16;
+};
+
+/** Log type for MessageSent events. */
+export type MessageSentLog = L1EventLog<MessageSentArgs>;
+
 export class InboxContract {
   private readonly inbox: GetContractReturnType<typeof InboxAbi, ViemClient>;
 
@@ -59,6 +73,39 @@ export class InboxContract {
       treeInProgress: state.inProgress,
     };
   }
+
+  /** Fetches MessageSent events within the given block range. */
+  async getMessageSentEvents(fromBlock: bigint, toBlock: bigint): Promise<MessageSentLog[]> {
+    const logs = await this.inbox.getEvents.MessageSent({}, { fromBlock, toBlock });
+    return logs
+      .filter(log => log.blockNumber! >= fromBlock && log.blockNumber! <= toBlock)
+      .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));
+  }
+
+  private mapMessageSentLog(log: {
+    blockNumber: bigint | null;
+    blockHash: `0x${string}` | null;
+    transactionHash: `0x${string}` | null;
+    args: { index?: bigint; hash?: `0x${string}`; checkpointNumber?: bigint; rollingHash?: `0x${string}` };
+  }): MessageSentLog {
+    return {
+      l1BlockNumber: log.blockNumber!,
+      l1BlockHash: Buffer32.fromString(log.blockHash!),
+      l1TransactionHash: log.transactionHash!,
+      args: {
+        index: log.args.index!,
+        leaf: Fr.fromString(log.args.hash!),
+        checkpointNumber: CheckpointNumber.fromBigInt(log.args.checkpointNumber!),
+        rollingHash: Buffer16.fromString(log.args.rollingHash!),
+      },
+    };
+  }
 }
 
 export type InboxContractState = {

package/src/contracts/index.ts

@@ -6,6 +6,7 @@ export * from './governance.js';
 export * from './governance_proposer.js';
 export * from './gse.js';
 export * from './inbox.js';
+export * from './log.js';
 export * from './multicall.js';
 export * from './outbox.js';
 export * from './registry.js';

package/src/contracts/log.ts

@@ -0,0 +1,13 @@
+import type { Buffer32 } from '@aztec/foundation/buffer';
+
+/** Base L1 event log with common fields. */
+export type L1EventLog<T> = {
+  /** L1 block number where the event was emitted. */
+  l1BlockNumber: bigint;
+  /** L1 block hash. */
+  l1BlockHash: Buffer32;
+  /** L1 transaction hash that emitted the event. */
+  l1TransactionHash: `0x${string}`;
+  /** Event-specific arguments. */
+  args: T;
+};

package/src/contracts/multicall.ts

@@ -34,10 +34,13 @@ export class Multicall3 {
     };
 
     const encodedForwarderData = encodeFunctionData(forwarderFunctionData);
-
     try {
       const { receipt, state } = await l1TxUtils.sendAndMonitorTransaction(
-        { to: MULTI_CALL_3_ADDRESS, data: encodedForwarderData },
+        {
+          to: MULTI_CALL_3_ADDRESS,
+          data: encodedForwarderData,
+          abi: multicall3Abi,
+        },
         gasConfig,
         blobConfig,
       );

package/src/contracts/rollup.ts

@@ -5,6 +5,7 @@ import { memoize } from '@aztec/foundation/decorators';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import type { ViemSignature } from '@aztec/foundation/eth-signature';
 import { makeBackoff, retry } from '@aztec/foundation/retry';
+import { EscapeHatchAbi } from '@aztec/l1-artifacts/EscapeHatchAbi';
 import { RollupAbi } from '@aztec/l1-artifacts/RollupAbi';
 import { RollupStorage } from '@aztec/l1-artifacts/RollupStorage';
 
@@ -30,6 +31,7 @@ import type { ViemClient } from '../types.js';
 import { formatViemError } from '../utils.js';
 import { EmpireSlashingProposerContract } from './empire_slashing_proposer.js';
 import { GSEContract } from './gse.js';
+import type { L1EventLog } from './log.js';
 import { SlasherContract } from './slasher_contract.js';
 import { TallySlashingProposerContract } from './tally_slashing_proposer.js';
 import { checkBlockTag } from './utils.js';
@@ -69,6 +71,7 @@ export type ViemHeader = {
   blockHeadersHash: `0x${string}`;
   blobsHash: `0x${string}`;
   inHash: `0x${string}`;
+  outHash: `0x${string}`;
   slotNumber: bigint;
   timestamp: bigint;
   coinbase: `0x${string}`;
@@ -105,7 +108,7 @@ export enum AttesterStatus {
 export type FeeHeader = {
   excessMana: bigint;
   manaUsed: bigint;
-  feeAssetPriceNumerator: bigint;
+  ethPerFeeAsset: bigint;
   congestionCost: bigint;
   proverCost: bigint;
 };
@@ -185,10 +188,28 @@ export type RollupStatusResponse = {
   archiveOfMyCheckpoint: Fr;
 };
 
+/** Arguments for the CheckpointProposed event. */
+export type CheckpointProposedArgs = {
+  checkpointNumber: CheckpointNumber;
+  archive: Fr;
+  versionedBlobHashes: Buffer[];
+  /** Hash of attestations. Undefined for older events (backwards compatibility). */
+  attestationsHash?: Buffer32;
+  /** Digest of the payload. Undefined for older events (backwards compatibility). */
+  payloadDigest?: Buffer32;
+};
+
+/** Log type for CheckpointProposed events. */
+export type CheckpointProposedLog = L1EventLog<CheckpointProposedArgs>;
+
 export class RollupContract {
   private readonly rollup: GetContractReturnType<typeof RollupAbi, ViemClient>;
 
   private static cachedStfStorageSlot: Hex | undefined;
+  private cachedEscapeHatch?: {
+    address: EthAddress;
+    contract: GetContractReturnType<typeof EscapeHatchAbi, ViemClient>;
+  };
 
   static get checkBlobStorageSlot(): bigint {
     const asString = RollupStorage.find(storage => storage.label === 'checkBlob')?.slot;
@@ -370,20 +391,24 @@ export class RollupContract {
     slotDuration: number;
     epochDuration: number;
     proofSubmissionEpochs: number;
+    targetCommitteeSize: number;
   }> {
-    const [l1StartBlock, l1GenesisTime, slotDuration, epochDuration, proofSubmissionEpochs] = await Promise.all([
-      this.getL1StartBlock(),
-      this.getL1GenesisTime(),
-      this.getSlotDuration(),
-      this.getEpochDuration(),
-      this.getProofSubmissionEpochs(),
-    ]);
+    const [l1StartBlock, l1GenesisTime, slotDuration, epochDuration, proofSubmissionEpochs, targetCommitteeSize] =
+      await Promise.all([
+        this.getL1StartBlock(),
+        this.getL1GenesisTime(),
+        this.getSlotDuration(),
+        this.getEpochDuration(),
+        this.getProofSubmissionEpochs(),
+        this.getTargetCommitteeSize(),
+      ]);
     return {
       l1StartBlock,
       l1GenesisTime,
       slotDuration,
       epochDuration: Number(epochDuration),
       proofSubmissionEpochs: Number(proofSubmissionEpochs),
+      targetCommitteeSize,
     };
   }
 
@@ -391,6 +416,58 @@ export class RollupContract {
     return EthAddress.fromString(await this.rollup.read.getSlasher());
   }
 
+  /**
+   * Returns the configured escape hatch contract address, or zero if disabled.
+   */
+  async getEscapeHatchAddress(): Promise<EthAddress> {
+    return EthAddress.fromString(await this.rollup.read.getEscapeHatch());
+  }
+
+  private async getEscapeHatchContract(): Promise<
+    GetContractReturnType<typeof EscapeHatchAbi, ViemClient> | undefined
+  > {
+    const escapeHatchAddress = await this.getEscapeHatchAddress();
+    if (escapeHatchAddress.isZero()) {
+      return undefined;
+    }
+
+    // Cache the viem contract wrapper since it will be used frequently.
+    if (!this.cachedEscapeHatch || !this.cachedEscapeHatch.address.equals(escapeHatchAddress)) {
+      this.cachedEscapeHatch = {
+        address: escapeHatchAddress,
+        contract: getContract({
+          address: escapeHatchAddress.toString(),
+          abi: EscapeHatchAbi,
+          client: this.client,
+        }),
+      };
+    }
+
+    return this.cachedEscapeHatch.contract;
+  }
+
+  /**
+   * Returns whether the escape hatch is open for the given epoch.
+   * If escape hatch is not configured, returns false.
+   *
+   * This function is intentionally defensive: any failure to query the escape hatch
+   * (RPC issues, transient errors, etc.) is treated as "closed" to avoid callers
+   * needing to sprinkle try/catch everywhere.
+   */
+  async isEscapeHatchOpen(epoch: EpochNumber): Promise<boolean> {
+    try {
+      const escapeHatch = await this.getEscapeHatchContract();
+      if (!escapeHatch) {
+        return false;
+      }
+
+      const [isOpen] = await escapeHatch.read.isHatchOpen([BigInt(epoch)]);
+      return isOpen;
+    } catch {
+      return false;
+    }
+  }
+
   /**
    * Returns a SlasherContract instance for interacting with the slasher contract.
    */
@@ -442,8 +519,8 @@ export class RollupContract {
     };
   }
 
-  getFeeAssetPerEth(): Promise<bigint> {
-    return this.rollup.read.getFeeAssetPerEth();
+  getEthPerFeeAsset(): Promise<bigint> {
+    return this.rollup.read.getEthPerFeeAsset();
   }
 
   async getCommitteeAt(timestamp: bigint): Promise<EthAddress[] | undefined> {
@@ -528,7 +605,7 @@ export class RollupContract {
       feeHeader: {
         excessMana: result.feeHeader.excessMana,
         manaUsed: result.feeHeader.manaUsed,
-        feeAssetPriceNumerator: result.feeHeader.feeAssetPriceNumerator,
+        ethPerFeeAsset: result.feeHeader.ethPerFeeAsset,
         congestionCost: result.feeHeader.congestionCost,
         proverCost: result.feeHeader.proverCost,
       },
@@ -732,6 +809,7 @@ export class RollupContract {
   ): L1TxRequest {
     return {
       to: this.address,
+      abi: RollupAbi,
       data: encodeFunctionData({
         abi: RollupAbi,
         functionName: 'invalidateBadAttestation',
@@ -753,6 +831,7 @@ export class RollupContract {
   ): L1TxRequest {
     return {
       to: this.address,
+      abi: RollupAbi,
       data: encodeFunctionData({
         abi: RollupAbi,
         functionName: 'invalidateInsufficientAttestations',
@@ -886,6 +965,7 @@ export class RollupContract {
   setupEpoch(l1TxUtils: L1TxUtils) {
     return l1TxUtils.sendAndMonitorTransaction({
       to: this.address,
+      abi: RollupAbi,
       data: encodeFunctionData({
         abi: RollupAbi,
         functionName: 'setupEpoch',
@@ -897,6 +977,7 @@ export class RollupContract {
   vote(l1TxUtils: L1TxUtils, proposalId: bigint) {
     return l1TxUtils.sendAndMonitorTransaction({
       to: this.address,
+      abi: RollupAbi,
       data: encodeFunctionData({
         abi: RollupAbi,
         functionName: 'vote',
@@ -965,4 +1046,23 @@ export class RollupContract {
       },
     );
   }
+
+  /** Fetches CheckpointProposed events within the given block range. */
+  async getCheckpointProposedEvents(fromBlock: bigint, toBlock: bigint): Promise<CheckpointProposedLog[]> {
+    const logs = await this.rollup.getEvents.CheckpointProposed({}, { fromBlock, toBlock });
+    return logs
+      .filter(log => log.blockNumber! >= fromBlock && log.blockNumber! <= toBlock)
+      .map(log => ({
+        l1BlockNumber: log.blockNumber!,
+        l1BlockHash: Buffer32.fromString(log.blockHash!),
+        l1TransactionHash: log.transactionHash!,
+        args: {
+          checkpointNumber: CheckpointNumber.fromBigInt(log.args.checkpointNumber!),
+          archive: Fr.fromString(log.args.archive!),
+          versionedBlobHashes: log.args.versionedBlobHashes!.map(h => Buffer.from(h.slice(2), 'hex')),
+          attestationsHash: log.args.attestationsHash ? Buffer32.fromString(log.args.attestationsHash) : undefined,
+          payloadDigest: log.args.payloadDigest ? Buffer32.fromString(log.args.payloadDigest) : undefined,
+        },
+      }));
+  }
 }