@aztec/ethereum 0.0.0-test.1 → 0.0.1-commit.0b941701

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_base.ts

@@ -1,19 +1,89 @@
+import type { SlotNumber } from '@aztec/foundation/branded-types';
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import { Signature } from '@aztec/foundation/eth-signature';
 import { EmpireBaseAbi } from '@aztec/l1-artifacts/EmpireBaseAbi';
 
-import { type Hex, encodeFunctionData } from 'viem';
+import { type Hex, type TypedDataDefinition, encodeFunctionData } from 'viem';
 
-import type { L1TxRequest } from '../l1_tx_utils.js';
+import type { L1TxRequest } from '../l1_tx_utils/index.js';
 
 export interface IEmpireBase {
-  getRoundInfo(rollupAddress: Hex, round: bigint): Promise<{ lastVote: bigint; leader: Hex; executed: boolean }>;
-  computeRound(slot: bigint): Promise<bigint>;
-  createVoteRequest(payload: Hex): L1TxRequest;
+  get address(): EthAddress;
+  getRoundInfo(
+    rollupAddress: Hex,
+    round: bigint,
+  ): Promise<{ lastSignalSlot: SlotNumber; payloadWithMostSignals: Hex; quorumReached: boolean; executed: boolean }>;
+  computeRound(slot: SlotNumber): Promise<bigint>;
+  createSignalRequest(payload: Hex): L1TxRequest;
+  createSignalRequestWithSignature(
+    payload: Hex,
+    slot: SlotNumber,
+    chainId: number,
+    signerAddress: Hex,
+    signer: (msg: TypedDataDefinition) => Promise<Hex>,
+  ): Promise<L1TxRequest>;
 }
 
-export function encodeVote(payload: Hex): Hex {
+export function encodeSignal(payload: Hex): Hex {
   return encodeFunctionData({
     abi: EmpireBaseAbi,
-    functionName: 'vote',
+    functionName: 'signal',
     args: [payload],
   });
 }
+
+export function encodeSignalWithSignature(payload: Hex, signature: Signature) {
+  return encodeFunctionData({
+    abi: EmpireBaseAbi,
+    functionName: 'signalWithSig',
+    args: [payload, signature.toViemSignature()],
+  });
+}
+
+/**
+ * Signs a signal proposal using EIP-712 typed data for use with signalWithSig
+ * @param walletClient - The viem wallet client to sign with
+ * @param payload - The payload address to signal
+ * @param verifyingContract - The address of the EmpireBase contract
+ * @param chainId - The chain ID where the contract is deployed
+ * @param account - The account to sign with (optional if hoisted on wallet client)
+ * @returns The EIP-712 signature
+ */
+export async function signSignalWithSig(
+  signer: (msg: TypedDataDefinition) => Promise<Hex>,
+  payload: Hex,
+  slot: SlotNumber,
+  instance: Hex,
+  verifyingContract: Hex,
+  chainId: number,
+): Promise<Signature> {
+  const domain = {
+    name: 'EmpireBase',
+    version: '1',
+    chainId,
+    verifyingContract,
+  };
+
+  const types = {
+    EIP712Domain: [
+      { name: 'name', type: 'string' },
+      { name: 'version', type: 'string' },
+      { name: 'chainId', type: 'uint256' },
+      { name: 'verifyingContract', type: 'address' },
+    ],
+    Signal: [
+      { name: 'payload', type: 'address' },
+      { name: 'slot', type: 'uint256' },
+      { name: 'instance', type: 'address' },
+    ],
+  };
+
+  const message = {
+    payload,
+    slot: BigInt(slot),
+    instance,
+  };
+
+  const typedData = { domain, types, primaryType: 'Signal', message };
+  return Signature.fromString(await signer(typedData));
+}

package/src/contracts/empire_slashing_proposer.ts

@@ -0,0 +1,270 @@
+import { SlotNumber } from '@aztec/foundation/branded-types';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { createLogger } from '@aztec/foundation/log';
+import { retryUntil } from '@aztec/foundation/retry';
+import { EmpireSlashingProposerAbi } from '@aztec/l1-artifacts/EmpireSlashingProposerAbi';
+
+import EventEmitter from 'events';
+import {
+  type EncodeFunctionDataParameters,
+  type GetContractReturnType,
+  type Hex,
+  type Log,
+  type TypedDataDefinition,
+  encodeFunctionData,
+  getContract,
+} from 'viem';
+
+import type { L1TxRequest, L1TxUtils } from '../l1_tx_utils/index.js';
+import type { ViemClient } from '../types.js';
+import { FormattedViemError, tryExtractEvent } from '../utils.js';
+import { type IEmpireBase, encodeSignal, encodeSignalWithSignature, signSignalWithSig } from './empire_base.js';
+
+export class ProposalAlreadyExecutedError extends Error {
+  constructor(round: bigint) {
+    super(`Proposal already executed: ${round}`);
+  }
+}
+
+export class EmpireSlashingProposerContract extends EventEmitter implements IEmpireBase {
+  private readonly logger = createLogger('ethereum:contracts:empire_slashing_proposer');
+  private readonly proposer: GetContractReturnType<typeof EmpireSlashingProposerAbi, ViemClient>;
+
+  public readonly type = 'empire' as const;
+
+  constructor(
+    public readonly client: ViemClient,
+    address: Hex | EthAddress,
+  ) {
+    super();
+    this.proposer = getContract({
+      address: typeof address === 'string' ? address : address.toString(),
+      abi: EmpireSlashingProposerAbi,
+      client,
+    });
+  }
+
+  public get address() {
+    return EthAddress.fromString(this.proposer.address);
+  }
+
+  public getQuorumSize() {
+    return this.proposer.read.QUORUM_SIZE();
+  }
+
+  public getRoundSize() {
+    return this.proposer.read.ROUND_SIZE();
+  }
+
+  public getLifetimeInRounds() {
+    return this.proposer.read.LIFETIME_IN_ROUNDS();
+  }
+
+  public getExecutionDelayInRounds() {
+    return this.proposer.read.EXECUTION_DELAY_IN_ROUNDS();
+  }
+
+  public getCurrentRound() {
+    return this.proposer.read.getCurrentRound();
+  }
+
+  public computeRound(slot: SlotNumber): Promise<bigint> {
+    return this.proposer.read.computeRound([BigInt(slot)]);
+  }
+
+  public getInstance() {
+    return this.proposer.read.getInstance();
+  }
+
+  public async getRoundInfo(
+    rollupAddress: Hex,
+    round: bigint,
+  ): 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 {
+      lastSignalSlot: SlotNumber.fromBigInt(result.lastSignalSlot),
+      payloadWithMostSignals: result.payloadWithMostSignals,
+      quorumReached: signalCount >= quorum,
+      executed: result.executed,
+    };
+  }
+
+  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(),
+      data: encodeSignal(payload),
+    };
+  }
+
+  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: encodeSignalWithSignature(payload, signature),
+    };
+  }
+
+  public listenToSubmittablePayloads(callback: (args: { payload: `0x${string}`; round: bigint }) => unknown) {
+    return this.proposer.watchEvent.PayloadSubmittable(
+      {},
+      {
+        strict: true,
+        onLogs: logs => {
+          for (const log of logs) {
+            const { payload, round } = log.args;
+            if (payload && round) {
+              callback({ payload, round });
+            }
+          }
+        },
+      },
+    );
+  }
+
+  public listenToPayloadSubmitted(callback: (args: { round: bigint; payload: `0x${string}` }) => unknown) {
+    return this.proposer.watchEvent.PayloadSubmitted(
+      {},
+      {
+        onLogs: logs => {
+          for (const log of logs) {
+            const { payload, round } = log.args;
+            if (round && payload) {
+              callback({ round, payload });
+            }
+          }
+        },
+      },
+    );
+  }
+
+  public listenToSignalCasted(
+    callback: (args: { round: bigint; payload: `0x${string}`; signaler: `0x${string}` }) => unknown,
+  ) {
+    return this.proposer.watchEvent.SignalCast(
+      {},
+      {
+        onLogs: logs => {
+          for (const log of logs) {
+            const { round, payload, signaler } = log.args;
+            if (round && payload && signaler) {
+              callback({ round, payload, signaler });
+            }
+          }
+        },
+      },
+    );
+  }
+
+  /** Creates an L1TxRequest to submit the round winner for the given round. */
+  public buildExecuteRoundRequest(round: bigint): L1TxRequest {
+    return {
+      to: this.address.toString(),
+      data: encodeFunctionData({
+        abi: EmpireSlashingProposerAbi,
+        functionName: 'submitRoundWinner',
+        args: [round],
+      }),
+    };
+  }
+
+  /** Tries to extract a PayloadSubmitted event from the given logs. */
+  public tryExtractPayloadSubmittedEvent(logs: Log[]) {
+    return tryExtractEvent(logs, this.address.toString(), EmpireSlashingProposerAbi, 'PayloadSubmitted');
+  }
+
+  /**
+   * Wait for a round to be reached.
+   *
+   * @param round - The round to wait for.
+   * @param pollingIntervalSeconds - The interval in seconds to poll for the round.
+   * @returns True if the round was reached, false otherwise.
+   */
+  public waitForRound(round: bigint, pollingIntervalSeconds: number = 1): Promise<boolean> {
+    return retryUntil(
+      async () => {
+        const currentRound = await this.proposer.read.getCurrentRound().catch(e => {
+          this.logger.error('Error getting current round', e);
+          return undefined;
+        });
+        return currentRound !== undefined && currentRound >= round;
+      },
+      `Waiting for round ${round} to be reached`,
+      0, // no timeout
+      pollingIntervalSeconds,
+    ).catch(() => false);
+  }
+
+  public async executeRound(
+    txUtils: L1TxUtils,
+    round: bigint | number,
+  ): ReturnType<typeof txUtils.sendAndMonitorTransaction> {
+    if (typeof round === 'number') {
+      round = BigInt(round);
+    }
+    const args: EncodeFunctionDataParameters<typeof EmpireSlashingProposerAbi, 'submitRoundWinner'> = {
+      abi: EmpireSlashingProposerAbi,
+      functionName: 'submitRoundWinner',
+      args: [round],
+    };
+    const data = encodeFunctionData(args);
+    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
+        },
+      )
+      .catch(err => {
+        if (err instanceof FormattedViemError && err.message.includes('ProposalAlreadyExecuted')) {
+          throw new ProposalAlreadyExecutedError(round);
+        }
+        throw err;
+      });
+
+    if (response.receipt.status === 'reverted') {
+      const error = await txUtils.tryGetErrorFromRevertedTx(
+        data,
+        {
+          ...args,
+          address: this.address.toString(),
+        },
+        undefined,
+        [],
+      );
+      if (error?.includes('ProposalAlreadyExecuted')) {
+        throw new ProposalAlreadyExecutedError(round);
+      }
+      const errorMessage = `Failed to execute round ${round}, TxHash: ${response.receipt.transactionHash}, Error: ${
+        error ?? 'Unknown error'
+      }`;
+      throw new Error(errorMessage);
+    }
+    return response;
+  }
+}

package/src/contracts/errors.ts

@@ -0,0 +1,13 @@
+export class BlockTagTooOldError extends Error {
+  constructor(blockTag: bigint | number, latestBlock: bigint | number) {
+    super(`Block tag ${blockTag} is more than 128 blocks behind the latest block ${latestBlock}`);
+    this.name = 'BlockTagTooOldError';
+  }
+}
+
+export class NoCommitteeError extends Error {
+  constructor() {
+    super('The committee does not exist on L1');
+    this.name = 'NoCommitteeError';
+  }
+}

package/src/contracts/fee_asset_handler.ts

@@ -0,0 +1,64 @@
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { FeeAssetHandlerAbi } from '@aztec/l1-artifacts/FeeAssetHandlerAbi';
+
+import { type Hex, encodeFunctionData, getContract } from 'viem';
+
+import type { L1TxUtils } from '../l1_tx_utils/index.js';
+import type { ViemClient } from '../types.js';
+
+export class FeeAssetHandlerContract {
+  public address: EthAddress;
+
+  constructor(
+    public readonly client: ViemClient,
+    address: Hex | EthAddress,
+  ) {
+    if (address instanceof EthAddress) {
+      address = address.toString();
+    }
+    this.address = EthAddress.fromString(address);
+  }
+
+  public async getOwner(): Promise<EthAddress> {
+    const contract = getContract({
+      abi: FeeAssetHandlerAbi,
+      address: this.address.toString(),
+      client: this.client,
+    });
+    return EthAddress.fromString(await contract.read.owner());
+  }
+
+  public getMintAmount() {
+    const contract = getContract({
+      abi: FeeAssetHandlerAbi,
+      address: this.address.toString(),
+      client: this.client,
+    });
+    return contract.read.mintAmount();
+  }
+
+  public mint(txUtils: L1TxUtils, recipient: Hex | EthAddress) {
+    if (recipient instanceof EthAddress) {
+      recipient = recipient.toString();
+    }
+    return txUtils.sendAndMonitorTransaction({
+      to: this.address.toString(),
+      data: encodeFunctionData({
+        abi: FeeAssetHandlerAbi,
+        functionName: 'mint',
+        args: [recipient],
+      }),
+    });
+  }
+
+  public setMintAmount(txUtils: L1TxUtils, amount: bigint) {
+    return txUtils.sendAndMonitorTransaction({
+      to: this.address.toString(),
+      data: encodeFunctionData({
+        abi: FeeAssetHandlerAbi,
+        functionName: 'setMintAmount',
+        args: [amount],
+      }),
+    });
+  }
+}

package/src/contracts/fee_juice.ts

@@ -1,43 +1,57 @@
 import { EthAddress } from '@aztec/foundation/eth-address';
-import { TestERC20Abi as FeeJuiceAbi } from '@aztec/l1-artifacts';
+import { TestERC20Abi as FeeJuiceAbi } from '@aztec/l1-artifacts/TestERC20Abi';
 
 import { type GetContractReturnType, type Hex, getContract } from 'viem';
 
-import type { L1Clients } from '../types.js';
+import { type ExtendedViemWalletClient, type ViemClient, isExtendedClient } from '../types.js';
 
 export class FeeJuiceContract {
-  private readonly publicFeeJuice: GetContractReturnType<typeof FeeJuiceAbi, L1Clients['publicClient']>;
-  private readonly walletFeeJuice: GetContractReturnType<typeof FeeJuiceAbi, L1Clients['walletClient']> | undefined;
+  private readonly feeJuiceContract: GetContractReturnType<typeof FeeJuiceAbi, ViemClient>;
 
   constructor(
-    address: Hex,
-    public readonly publicClient: L1Clients['publicClient'],
-    public readonly walletClient: L1Clients['walletClient'] | undefined,
+    address: Hex | EthAddress,
+    public readonly client: ViemClient,
   ) {
-    this.publicFeeJuice = getContract({ address, abi: FeeJuiceAbi, client: publicClient });
-    this.walletFeeJuice = walletClient ? getContract({ address, abi: FeeJuiceAbi, client: walletClient }) : undefined;
+    if (address instanceof EthAddress) {
+      address = address.toString();
+    }
+    this.feeJuiceContract = getContract({ address, abi: FeeJuiceAbi, client });
   }
 
   public get address() {
-    return EthAddress.fromString(this.publicFeeJuice.address);
+    return EthAddress.fromString(this.feeJuiceContract.address);
+  }
+
+  public async getOwner(): Promise<EthAddress> {
+    return EthAddress.fromString(await this.feeJuiceContract.read.owner());
   }
 
-  private assertWalletFeeJuice() {
-    if (!this.walletFeeJuice) {
+  private assertWalletFeeJuice(): GetContractReturnType<typeof FeeJuiceAbi, ExtendedViemWalletClient> {
+    if (!isExtendedClient(this.client)) {
       throw new Error('Wallet client is required for this operation');
     }
-    return this.walletFeeJuice;
+    return this.feeJuiceContract as GetContractReturnType<typeof FeeJuiceAbi, ExtendedViemWalletClient>;
   }
 
   public async mint(to: Hex, amount: bigint) {
     const walletFeeJuice = this.assertWalletFeeJuice();
     const tx = await walletFeeJuice.write.mint([to, amount]);
-    await this.publicClient.waitForTransactionReceipt({ hash: tx });
+    const receipt = await this.client.waitForTransactionReceipt({ hash: tx });
+
+    if (receipt.status === 'success') {
+      return;
+    }
+    throw new Error('Mint failed');
   }
 
   public async approve(spender: Hex, amount: bigint) {
     const walletFeeJuice = this.assertWalletFeeJuice();
     const tx = await walletFeeJuice.write.approve([spender, amount]);
-    await this.publicClient.waitForTransactionReceipt({ hash: tx });
+    const receipt = await this.client.waitForTransactionReceipt({ hash: tx });
+
+    if (receipt.status === 'success') {
+      return;
+    }
+    throw new Error('Approve failed');
   }
 }