@aztec/ethereum 0.0.0-test.1 → 0.0.1-commit.0208eb9

package/src/contracts/governance.ts

@@ -1,20 +1,21 @@
 import { EthAddress } from '@aztec/foundation/eth-address';
 import type { Logger } from '@aztec/foundation/log';
 import { sleep } from '@aztec/foundation/sleep';
-import { GovernanceAbi } from '@aztec/l1-artifacts';
+import { GovernanceAbi } from '@aztec/l1-artifacts/GovernanceAbi';
 
 import {
   type EncodeFunctionDataParameters,
   type GetContractReturnType,
   type Hex,
+  type Log,
   encodeFunctionData,
   getContract,
+  parseEventLogs,
 } from 'viem';
 
 import type { L1ContractAddresses } from '../l1_contract_addresses.js';
-import { L1TxUtils } from '../l1_tx_utils.js';
-import type { ViemPublicClient, ViemWalletClient } from '../types.js';
-import { GovernanceProposerContract } from './governance_proposer.js';
+import { createL1TxUtilsFromViemWallet } from '../l1_tx_utils/index.js';
+import { type ExtendedViemWalletClient, type ViemClient, isExtendedClient } from '../types.js';
 
 export type L1GovernanceContractAddresses = Pick<
   L1ContractAddresses,
@@ -33,87 +34,54 @@ export enum ProposalState {
   Expired,
 }
 
-export class GovernanceContract {
-  private readonly publicGovernance: GetContractReturnType<typeof GovernanceAbi, ViemPublicClient>;
-  private readonly walletGovernance: GetContractReturnType<typeof GovernanceAbi, ViemWalletClient> | undefined;
+export function extractProposalIdFromLogs(logs: Log[]): bigint {
+  const parsedLogs = parseEventLogs({
+    abi: GovernanceAbi,
+    logs: logs,
+    eventName: 'Proposed',
+  });
+
+  if (parsedLogs.length === 0) {
+    throw new Error('Proposal log not found');
+  }
+  return parsedLogs[0].args.proposalId;
+}
+
+export class ReadOnlyGovernanceContract {
+  protected readonly governanceContract: GetContractReturnType<typeof GovernanceAbi, ViemClient>;
 
   constructor(
     address: Hex,
-    public readonly publicClient: ViemPublicClient,
-    public readonly walletClient: ViemWalletClient | undefined,
+    public readonly client: ViemClient,
   ) {
-    this.publicGovernance = getContract({ address, abi: GovernanceAbi, client: publicClient });
-    this.walletGovernance = walletClient
-      ? getContract({ address, abi: GovernanceAbi, client: walletClient })
-      : undefined;
+    this.governanceContract = getContract({ address, abi: GovernanceAbi, client: client });
   }
 
   public get address() {
-    return EthAddress.fromString(this.publicGovernance.address);
+    return EthAddress.fromString(this.governanceContract.address);
   }
 
-  public async getProposer() {
-    const governanceProposerAddress = EthAddress.fromString(await this.publicGovernance.read.governanceProposer());
-    return new GovernanceProposerContract(this.publicClient, governanceProposerAddress.toString());
+  public async getGovernanceProposerAddress() {
+    return EthAddress.fromString(await this.governanceContract.read.governanceProposer());
   }
 
-  public async getGovernanceAddresses(): Promise<L1GovernanceContractAddresses> {
-    const governanceProposer = await this.getProposer();
-    const [rollupAddress, registryAddress] = await Promise.all([
-      governanceProposer.getRollupAddress(),
-      governanceProposer.getRegistryAddress(),
-    ]);
-    return {
-      governanceAddress: this.address,
-      rollupAddress,
-      registryAddress,
-      governanceProposerAddress: governanceProposer.address,
-    };
+  public getConfiguration() {
+    return this.governanceContract.read.getConfiguration();
   }
 
   public getProposal(proposalId: bigint) {
-    return this.publicGovernance.read.getProposal([proposalId]);
+    return this.governanceContract.read.getProposal([proposalId]);
   }
 
   public async getProposalState(proposalId: bigint): Promise<ProposalState> {
-    const state = await this.publicGovernance.read.getProposalState([proposalId]);
+    const state = await this.governanceContract.read.getProposalState([proposalId]);
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-enum-comparison
     if (state < 0 || state > ProposalState.Expired) {
       throw new Error(`Invalid proposal state: ${state}`);
     }
     return state as ProposalState;
   }
 
-  private assertWalletGovernance(): NonNullable<typeof this.walletGovernance> {
-    if (!this.walletGovernance) {
-      throw new Error('Wallet client is required for this operation');
-    }
-    return this.walletGovernance;
-  }
-
-  public async deposit(onBehalfOf: Hex, amount: bigint) {
-    const walletGovernance = this.assertWalletGovernance();
-    const depositTx = await walletGovernance.write.deposit([onBehalfOf, amount]);
-    await this.publicClient.waitForTransactionReceipt({ hash: depositTx });
-  }
-
-  public async proposeWithLock({
-    payloadAddress,
-    withdrawAddress,
-  }: {
-    payloadAddress: Hex;
-    withdrawAddress: Hex;
-  }): Promise<number> {
-    const walletGovernance = this.assertWalletGovernance();
-    const proposeTx = await walletGovernance.write.proposeWithLock([payloadAddress, withdrawAddress]);
-    const receipt = await this.publicClient.waitForTransactionReceipt({ hash: proposeTx });
-    if (receipt.status !== 'success') {
-      throw new Error(`Proposal failed: ${receipt.status}`);
-    }
-
-    const proposalId = Number(receipt.logs[1].topics[1]);
-    return proposalId;
-  }
-
   public async awaitProposalActive({ proposalId, logger }: { proposalId: bigint; logger: Logger }) {
     const state = await this.getProposalState(proposalId);
     if (state === ProposalState.Active) {
@@ -123,7 +91,7 @@ export class GovernanceContract {
     } else {
       const proposal = await this.getProposal(proposalId);
       const startOfActive = proposal.creation + proposal.config.votingDelay;
-      const block = await this.publicClient.getBlock();
+      const block = await this.client.getBlock();
       // Add 12 seconds to the time to make sure we don't vote too early
       const secondsToActive = Number(startOfActive - block.timestamp) + 12;
       const now = new Date();
@@ -151,7 +119,7 @@ export class GovernanceContract {
         proposal.config.votingDelay +
         proposal.config.votingDuration +
         proposal.config.executionDelay;
-      const block = await this.publicClient.getBlock();
+      const block = await this.client.getBlock();
       const secondsToExecutable = Number(startOfExecutable - block.timestamp) + 12;
       const now = new Date();
       logger.info(`
@@ -162,11 +130,55 @@ export class GovernanceContract {
       await sleep(secondsToExecutable * 1000);
     }
   }
+}
+
+export class GovernanceContract extends ReadOnlyGovernanceContract {
+  protected override readonly governanceContract: GetContractReturnType<typeof GovernanceAbi, ExtendedViemWalletClient>;
+
+  constructor(
+    address: Hex | EthAddress,
+    public override readonly client: ExtendedViemWalletClient,
+  ) {
+    if (address instanceof EthAddress) {
+      address = address.toString();
+    }
+    super(address, client);
+    if (!isExtendedClient(client)) {
+      throw new Error('GovernanceContract has to be instantiated with a wallet client.');
+    }
+    this.governanceContract = getContract({ address, abi: GovernanceAbi, client });
+  }
+
+  public async deposit(onBehalfOf: Hex, amount: bigint) {
+    const depositTx = await this.governanceContract.write.deposit([onBehalfOf, amount]);
+    await this.client.waitForTransactionReceipt({ hash: depositTx });
+  }
+
+  public async proposeWithLock({
+    payloadAddress,
+    withdrawAddress,
+  }: {
+    payloadAddress: Hex;
+    withdrawAddress: Hex;
+  }): Promise<bigint> {
+    const proposeTx = await this.governanceContract.write.proposeWithLock([payloadAddress, withdrawAddress]);
+    const receipt = await this.client.waitForTransactionReceipt({ hash: proposeTx });
+    if (receipt.status !== 'success') {
+      throw new Error(`Proposal failed: ${receipt.status}`);
+    }
+    return extractProposalIdFromLogs(receipt.logs);
+  }
 
   public async getPower(): Promise<bigint> {
-    const walletGovernance = this.assertWalletGovernance();
-    const now = await this.publicClient.getBlock();
-    return walletGovernance.read.powerAt([this.walletClient!.account.address, now.timestamp]);
+    const now = await this.client.getBlock();
+    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({
@@ -182,11 +194,10 @@ export class GovernanceContract {
     retries: number;
     logger: Logger;
   }) {
-    const walletGovernance = this.assertWalletGovernance();
-    const l1TxUtils = new L1TxUtils(this.publicClient, this.walletClient!, logger);
+    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++) {
@@ -199,7 +210,8 @@ export class GovernanceContract {
         const encodedVoteData = encodeFunctionData(voteFunctionData);
 
         const { receipt } = await l1TxUtils.sendAndMonitorTransaction({
-          to: walletGovernance.address,
+          to: this.governanceContract.address,
+          abi: GovernanceAbi,
           data: encodedVoteData,
         });
 
@@ -209,7 +221,7 @@ export class GovernanceContract {
         } else {
           const args = {
             ...voteFunctionData,
-            address: walletGovernance.address,
+            address: this.governanceContract.address,
           };
           const errorMsg = await l1TxUtils.tryGetErrorFromRevertedTx(encodedVoteData, args, undefined, []);
           logger.error(`Error voting on proposal ${proposalId}: ${errorMsg}`);
@@ -226,9 +238,9 @@ export class GovernanceContract {
     }
     logger.info(`Voted [${inFavor ? 'yea' : 'nay'}] on proposal [${proposalId}]`);
     const proposal = await this.getProposal(proposalId);
-    logger.info(`Proposal [${proposalId}] has state [${proposal.state}]`);
+    logger.info(`Proposal [${proposalId}] has cached state [${proposal.cachedState}]`);
     logger.info(`Proposal [${proposalId}] has summedBallot yea [${proposal.summedBallot.yea}]`);
-    logger.info(`Proposal [${proposalId}] has summedBallot nea [${proposal.summedBallot.nea}]`);
+    logger.info(`Proposal [${proposalId}] has summedBallot nay [${proposal.summedBallot.nay}]`);
   }
 
   public async executeProposal({
@@ -240,8 +252,7 @@ export class GovernanceContract {
     retries: number;
     logger: Logger;
   }) {
-    const walletGovernance = this.assertWalletGovernance();
-    const l1TxUtils = new L1TxUtils(this.publicClient, this.walletClient!, logger);
+    const l1TxUtils = createL1TxUtilsFromViemWallet(this.client, { logger });
     const retryDelaySeconds = 12;
     let success = false;
     for (let i = 0; i < retries; i++) {
@@ -254,7 +265,8 @@ export class GovernanceContract {
         const encodedExecuteData = encodeFunctionData(executeFunctionData);
 
         const { receipt } = await l1TxUtils.sendAndMonitorTransaction({
-          to: walletGovernance.address,
+          to: this.governanceContract.address,
+          abi: GovernanceAbi,
           data: encodedExecuteData,
         });
 
@@ -264,7 +276,7 @@ export class GovernanceContract {
         } else {
           const args = {
             ...executeFunctionData,
-            address: walletGovernance.address,
+            address: this.governanceContract.address,
           };
           const errorMsg = await l1TxUtils.tryGetErrorFromRevertedTx(encodedExecuteData, args, undefined, []);
           logger.error(`Error executing proposal ${proposalId}: ${errorMsg}`);

package/src/contracts/governance_proposer.ts

@@ -1,17 +1,32 @@
+import { SlotNumber } from '@aztec/foundation/branded-types';
 import { memoize } from '@aztec/foundation/decorators';
 import { EthAddress } from '@aztec/foundation/eth-address';
-import { GovernanceProposerAbi } from '@aztec/l1-artifacts';
+import { GovernanceProposerAbi } from '@aztec/l1-artifacts/GovernanceProposerAbi';
 
-import { type GetContractReturnType, type Hex, type TransactionReceipt, encodeFunctionData, getContract } from 'viem';
+import {
+  type GetContractReturnType,
+  type Hex,
+  type TransactionReceipt,
+  type TypedDataDefinition,
+  encodeFunctionData,
+  getContract,
+} from 'viem';
 
-import type { GasPrice, L1TxRequest, L1TxUtils } from '../l1_tx_utils.js';
-import type { ViemPublicClient } from '../types.js';
-import { type IEmpireBase, encodeVote } from './empire_base.js';
+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';
 
 export class GovernanceProposerContract implements IEmpireBase {
-  private readonly proposer: GetContractReturnType<typeof GovernanceProposerAbi, ViemPublicClient>;
+  private readonly proposer: GetContractReturnType<typeof GovernanceProposerAbi, ViemClient>;
 
-  constructor(public readonly client: ViemPublicClient, address: Hex) {
+  constructor(
+    public readonly client: ViemClient,
+    address: Hex | EthAddress,
+  ) {
+    if (address instanceof EthAddress) {
+      address = address.toString();
+    }
     this.proposer = getContract({ address, abi: GovernanceProposerAbi, client });
   }
 
@@ -29,54 +44,89 @@ export class GovernanceProposerContract implements IEmpireBase {
   }
 
   public getQuorumSize(): Promise<bigint> {
-    return this.proposer.read.N();
+    return this.proposer.read.QUORUM_SIZE();
   }
 
   public getRoundSize(): Promise<bigint> {
-    return this.proposer.read.M();
+    return this.proposer.read.ROUND_SIZE();
   }
 
-  public computeRound(slot: bigint): Promise<bigint> {
-    return this.proposer.read.computeRound([slot]);
+  public getInstance() {
+    return this.proposer.read.getInstance();
+  }
+
+  public computeRound(slot: SlotNumber): Promise<bigint> {
+    return this.proposer.read.computeRound([BigInt(slot)]);
   }
 
   public async getRoundInfo(
     rollupAddress: Hex,
     round: bigint,
-  ): Promise<{ lastVote: bigint; leader: Hex; executed: boolean }> {
-    const roundInfo = await this.proposer.read.rounds([rollupAddress, round]);
+  ): Promise<{ lastSignalSlot: SlotNumber; payloadWithMostSignals: Hex; quorumReached: boolean; executed: boolean }> {
+    const result = await this.proposer.read.getRoundData([rollupAddress, round]);
+    const [signalCount, quorum] = await Promise.all([
+      this.proposer.read.signalCount([rollupAddress, round, result.payloadWithMostSignals]),
+      this.getQuorumSize(),
+    ]);
     return {
-      lastVote: roundInfo[0],
-      leader: roundInfo[1],
-      executed: roundInfo[2],
+      lastSignalSlot: SlotNumber.fromBigInt(result.lastSignalSlot),
+      payloadWithMostSignals: result.payloadWithMostSignals,
+      quorumReached: signalCount >= quorum,
+      executed: result.executed,
     };
   }
 
-  public getProposalVotes(rollupAddress: Hex, round: bigint, proposal: Hex): Promise<bigint> {
-    return this.proposer.read.yeaCount([rollupAddress, round, proposal]);
+  public getPayloadSignals(rollupAddress: Hex, round: bigint, payload: Hex): Promise<bigint> {
+    return this.proposer.read.signalCount([rollupAddress, round, payload]);
+  }
+
+  public createSignalRequest(payload: Hex): L1TxRequest {
+    return {
+      to: this.address.toString(),
+      abi: GovernanceProposerAbi,
+      data: encodeSignal(payload),
+    };
   }
 
-  public createVoteRequest(payload: Hex): L1TxRequest {
+  public async createSignalRequestWithSignature(
+    payload: Hex,
+    slot: SlotNumber,
+    chainId: number,
+    signerAddress: Hex,
+    signer: (msg: TypedDataDefinition) => Promise<Hex>,
+  ): Promise<L1TxRequest> {
+    const signature = await signSignalWithSig(
+      signer,
+      payload,
+      slot,
+      await this.getInstance(),
+      this.address.toString(),
+      chainId,
+    );
     return {
       to: this.address.toString(),
-      data: encodeVote(payload),
+      abi: GovernanceProposerAbi,
+      data: encodeSignalWithSignature(payload, signature),
     };
   }
 
-  public executeProposal(
+  public async submitRoundWinner(
     round: bigint,
     l1TxUtils: L1TxUtils,
   ): Promise<{
     receipt: TransactionReceipt;
-    gasPrice: GasPrice;
+    proposalId: bigint;
   }> {
-    return l1TxUtils.sendAndMonitorTransaction({
+    const { receipt } = await l1TxUtils.sendAndMonitorTransaction({
       to: this.address.toString(),
+      abi: GovernanceProposerAbi,
       data: encodeFunctionData({
-        abi: this.proposer.abi,
-        functionName: 'executeProposal',
+        abi: GovernanceProposerAbi,
+        functionName: 'submitRoundWinner',
         args: [round],
       }),
     });
+    const proposalId = extractProposalIdFromLogs(receipt.logs);
+    return { receipt, proposalId };
   }
 }

package/src/contracts/gse.ts

@@ -0,0 +1,88 @@
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { GSEAbi } from '@aztec/l1-artifacts/GSEAbi';
+
+import type { ProjPointType } from '@noble/curves/abstract/weierstrass';
+import { bn254 } from '@noble/curves/bn254';
+import { type GetContractReturnType, type Hex, getContract } from 'viem';
+
+import type { ViemClient } from '../types.js';
+
+export type RegistrationTuple = {
+  publicKeyInG1: {
+    x: bigint;
+    y: bigint;
+  };
+  publicKeyInG2: {
+    x0: bigint;
+    x1: bigint;
+    y0: bigint;
+    y1: bigint;
+  };
+  proofOfPossession: {
+    x: bigint;
+    y: bigint;
+  };
+};
+
+export class GSEContract {
+  public address: EthAddress;
+  private readonly gse: GetContractReturnType<typeof GSEAbi, ViemClient>;
+
+  constructor(
+    public readonly client: ViemClient,
+    address: Hex | EthAddress,
+  ) {
+    if (address instanceof EthAddress) {
+      address = address.toString();
+    }
+    this.address = EthAddress.fromString(address);
+    this.gse = getContract({ address, abi: GSEAbi, client });
+  }
+
+  public async getOwner(): Promise<EthAddress> {
+    return EthAddress.fromString(await this.gse.read.owner());
+  }
+
+  public async getGovernance(): Promise<EthAddress> {
+    return EthAddress.fromString(await this.gse.read.getGovernance());
+  }
+
+  getAttestersFromIndicesAtTime(instance: Hex | EthAddress, ts: bigint, indices: bigint[]) {
+    if (instance instanceof EthAddress) {
+      instance = instance.toString();
+    }
+    return this.gse.read.getAttestersFromIndicesAtTime([instance, ts, indices]);
+  }
+
+  public async getRegistrationDigest(publicKey: ProjPointType<bigint>): Promise<ProjPointType<bigint>> {
+    const affinePublicKey = publicKey.toAffine();
+    const g1PointDigest = await this.gse.read.getRegistrationDigest([{ x: affinePublicKey.x, y: affinePublicKey.y }]);
+    return bn254.G1.ProjectivePoint.fromAffine(g1PointDigest);
+  }
+
+  public async makeRegistrationTuple(privateKey: bigint): Promise<RegistrationTuple> {
+    const publicKeyG1 = bn254.G1.ProjectivePoint.BASE.multiply(privateKey);
+    const digest = await this.getRegistrationDigest(publicKeyG1);
+    const signature = digest.multiply(privateKey);
+    const publicKeyG2 = bn254.G2.ProjectivePoint.BASE.multiply(privateKey);
+    const publicKeyG1Affine = publicKeyG1.toAffine();
+    const signatureAffine = signature.toAffine();
+    const publicKeyG2Affine = publicKeyG2.toAffine();
+    return {
+      publicKeyInG1: {
+        x: publicKeyG1Affine.x,
+        y: publicKeyG1Affine.y,
+      },
+      publicKeyInG2: {
+        x0: publicKeyG2Affine.x.c0,
+        x1: publicKeyG2Affine.x.c1,
+        y0: publicKeyG2Affine.y.c0,
+        y1: publicKeyG2Affine.y.c1,
+      },
+      proofOfPossession: {
+        x: signatureAffine.x,
+        y: signatureAffine.y,
+      },
+    };
+  }
+}

package/src/contracts/inbox.ts

@@ -0,0 +1,115 @@
+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';
+
+import { type BlockTag, type GetContractReturnType, type Hex, getContract } from 'viem';
+
+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>;
+
+  static getFromL1ContractsValues(deployL1ContractsValues: DeployAztecL1ContractsReturnType) {
+    const {
+      l1Client,
+      l1ContractAddresses: { inboxAddress },
+    } = deployL1ContractsValues;
+    return new InboxContract(l1Client, inboxAddress.toString());
+  }
+
+  static getFromConfig(config: L1ReaderConfig) {
+    const client = getPublicClient(config);
+    const address = config.l1Contracts.inboxAddress.toString();
+    return new InboxContract(client, address);
+  }
+
+  constructor(
+    public readonly client: ViemClient,
+    address: Hex | EthAddress,
+  ) {
+    if (address instanceof EthAddress) {
+      address = address.toString();
+    }
+    this.inbox = getContract({ address, abi: InboxAbi, client });
+  }
+
+  public get address() {
+    return this.inbox.address;
+  }
+
+  public getContract(): GetContractReturnType<typeof InboxAbi, ViemClient> {
+    return this.inbox;
+  }
+
+  public async getLag(opts: { blockTag?: BlockTag; blockNumber?: bigint } = {}): Promise<bigint> {
+    await checkBlockTag(opts.blockNumber, this.client);
+    return await this.inbox.read.LAG(opts);
+  }
+
+  public async getState(opts: { blockTag?: BlockTag; blockNumber?: bigint } = {}): Promise<InboxContractState> {
+    await checkBlockTag(opts.blockNumber, this.client);
+    const state = await this.inbox.read.getState(opts);
+    return {
+      totalMessagesInserted: state.totalMessagesInserted,
+      messagesRollingHash: Buffer16.fromString(state.rollingHash),
+      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 = {
+  totalMessagesInserted: bigint;
+  messagesRollingHash: Buffer16;
+  treeInProgress: bigint;
+};

package/src/contracts/index.ts

@@ -1,8 +1,16 @@
 export * from './empire_base.js';
+export * from './errors.js';
+export * from './fee_asset_handler.js';
 export * from './fee_juice.js';
-export * from './forwarder.js';
 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';
 export * from './rollup.js';
-export * from './slashing_proposer.js';
+export * from './empire_slashing_proposer.js';
+export * from './tally_slashing_proposer.js';
+export * from './slasher_contract.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;
+};