@aztec/ethereum 0.0.1-commit.b655e406 → 0.0.1-commit.b8a057fa

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

@@ -0,0 +1,200 @@
+import { toHex as toPaddedHex } from '@aztec/foundation/bigint-buffer';
+import type { CheckpointNumber, SlotNumber } from '@aztec/foundation/branded-types';
+import type { Buffer32 } from '@aztec/foundation/buffer';
+import { merge } from '@aztec/foundation/collection';
+import type { Fr } from '@aztec/foundation/curves/bn254';
+
+import type { StateOverride } from 'viem';
+
+import { type FeeHeader, RollupContract } from './rollup.js';
+
+/**
+ * Override values for the pending checkpoint that the simulation should treat as already applied.
+ * Every field is optional at plan-building time so callers can populate them incrementally; whatever
+ * is present at translation time is forwarded to the partial `tempCheckpointLogs` helper so the
+ * load-bearing `slotNumber` can land even if other fields could not be derived locally.
+ */
+export type PendingCheckpointOverrideState = {
+  archive?: Fr;
+  feeHeader?: FeeHeader;
+  headerHash?: Fr;
+  outHash?: Fr;
+  payloadDigest?: Buffer32;
+  slotNumber?: SlotNumber;
+};
+
+export type ChainTipsOverride = {
+  pending?: CheckpointNumber;
+  proven?: CheckpointNumber;
+};
+
+/** Describes the simulated L1 rollup state that downstream calls should observe. */
+export type SimulationOverridesPlan = {
+  chainTipsOverride?: ChainTipsOverride;
+  pendingCheckpointState?: PendingCheckpointOverrideState;
+  disableBlobCheck?: boolean;
+};
+
+/** Builds a single-checkpoint simulation plan before it is translated into a viem state override. */
+export class SimulationOverridesBuilder {
+  private chainTipsOverride?: ChainTipsOverride;
+  private pendingCheckpointState?: PendingCheckpointOverrideState;
+  private disableBlobCheck = false;
+
+  /** Starts from an existing plan so callers can extend or specialize it. */
+  public static from(plan: SimulationOverridesPlan | undefined): SimulationOverridesBuilder {
+    return new SimulationOverridesBuilder().merge(plan);
+  }
+
+  /**
+   * Merges another plan into this builder. Later values win on a per-half basis for chain tips,
+   * but explicit `undefined` fields in the incoming plan are ignored so they cannot erase a
+   * previously-set value.
+   */
+  public merge(plan: SimulationOverridesPlan | undefined): this {
+    if (!plan) {
+      return this;
+    }
+
+    if (plan.chainTipsOverride) {
+      this.chainTipsOverride = merge(this.chainTipsOverride ?? {}, plan.chainTipsOverride);
+    }
+    if (plan.pendingCheckpointState) {
+      this.pendingCheckpointState = merge(this.pendingCheckpointState ?? {}, plan.pendingCheckpointState);
+    }
+    this.disableBlobCheck = this.disableBlobCheck || (plan.disableBlobCheck ?? false);
+
+    return this;
+  }
+
+  /**
+   * Sets the pending and/or proven checkpoint number overrides. Subsequent calls merge into the existing
+   * override on a per-half basis, so callers can set pending in one call and proven in another without
+   * clobbering each other.
+   */
+  public withChainTips(override: ChainTipsOverride): this {
+    this.chainTipsOverride = { ...(this.chainTipsOverride ?? {}), ...override };
+    return this;
+  }
+
+  /** Overrides the archive root for the configured pending checkpoint. */
+  public withPendingArchive(archive: Fr): this {
+    this.assertPendingCheckpointNumber();
+    this.pendingCheckpointState = { ...(this.pendingCheckpointState ?? {}), archive };
+    return this;
+  }
+
+  /** Overrides the fee header for the configured pending checkpoint. */
+  public withPendingFeeHeader(feeHeader: FeeHeader): this {
+    this.assertPendingCheckpointNumber();
+    this.pendingCheckpointState = { ...(this.pendingCheckpointState ?? {}), feeHeader };
+    return this;
+  }
+
+  /**
+   * Overrides one or more `tempCheckpointLogs` cell fields for the configured pending checkpoint.
+   * Fields are independent: any subset can be provided. The translator (`makeTempCheckpointLogOverride`)
+   * emits a stateDiff entry per field actually set, so unspecified fields stay at their on-chain
+   * values.
+   *
+   * `slotNumber` is load-bearing for `STFLib.canPruneAtTime`: when the simulation overrides `pending`
+   * to a checkpoint that has no on-chain `tempCheckpointLogs` entry yet, the missing slotNumber falls
+   * back to 0 and the contract treats the pending tip as belonging to epoch 0, triggering a phantom
+   * prune that silently undoes the `pending` override.
+   */
+  public withPendingTempCheckpointLogFields(fields: {
+    headerHash?: Fr;
+    outHash?: Fr;
+    payloadDigest?: Buffer32;
+    slotNumber?: SlotNumber;
+  }): this {
+    this.assertPendingCheckpointNumber();
+    this.pendingCheckpointState = { ...(this.pendingCheckpointState ?? {}), ...fields };
+    return this;
+  }
+
+  /** Disables blob checking for simulations that cannot provide DA inputs. */
+  public withoutBlobCheck(): this {
+    this.disableBlobCheck = true;
+    return this;
+  }
+
+  /** Builds the final plan, or `undefined` when no overrides were configured. */
+  public build(): SimulationOverridesPlan | undefined {
+    if (!this.pendingCheckpointState && !this.chainTipsOverride && !this.disableBlobCheck) {
+      return undefined;
+    }
+
+    return {
+      chainTipsOverride: this.chainTipsOverride,
+      pendingCheckpointState: this.pendingCheckpointState,
+      disableBlobCheck: this.disableBlobCheck || undefined,
+    };
+  }
+
+  private assertPendingCheckpointNumber(): void {
+    if (this.chainTipsOverride?.pending === undefined) {
+      throw new Error('withChainTips({ pending }) must be called before attaching archive or fee header overrides');
+    }
+  }
+}
+
+/** Translates a simulation plan into the viem state override shape expected by rollup calls. */
+export async function buildSimulationOverridesStateOverride(
+  rollup: RollupContract,
+  plan: SimulationOverridesPlan | undefined,
+): Promise<StateOverride> {
+  if (!plan) {
+    return [];
+  }
+
+  const rollupStateDiff: NonNullable<StateOverride[number]['stateDiff']> = [];
+
+  if (plan.chainTipsOverride) {
+    rollupStateDiff.push(...extractRollupStateDiff(await rollup.makeChainTipsOverride(plan.chainTipsOverride)));
+  }
+
+  if (plan.pendingCheckpointState && plan.chainTipsOverride?.pending === undefined) {
+    throw new Error('pendingCheckpointState requires chainTipsOverride.pending to be set');
+  }
+
+  if (plan.pendingCheckpointState?.archive) {
+    rollupStateDiff.push(
+      ...extractRollupStateDiff(
+        rollup.makeArchiveOverride(plan.chainTipsOverride!.pending!, plan.pendingCheckpointState.archive),
+      ),
+    );
+  }
+
+  if (plan.pendingCheckpointState) {
+    rollupStateDiff.push(
+      ...extractRollupStateDiff(
+        await rollup.makeTempCheckpointLogOverride(plan.chainTipsOverride!.pending!, {
+          headerHash: plan.pendingCheckpointState.headerHash,
+          outHash: plan.pendingCheckpointState.outHash,
+          payloadDigest: plan.pendingCheckpointState.payloadDigest,
+          slotNumber: plan.pendingCheckpointState.slotNumber,
+          feeHeader: plan.pendingCheckpointState.feeHeader,
+        }),
+      ),
+    );
+  }
+
+  if (plan.disableBlobCheck) {
+    rollupStateDiff.push({
+      slot: toPaddedHex(RollupContract.checkBlobStorageSlot, true),
+      value: toPaddedHex(0n, true),
+    });
+  }
+
+  if (rollupStateDiff.length === 0) {
+    return [];
+  }
+
+  return [{ address: rollup.address, stateDiff: rollupStateDiff }];
+}
+
+function extractRollupStateDiff(override: StateOverride | StateOverride[number] | undefined) {
+  const entries = Array.isArray(override) ? override : override ? [override] : [];
+  return entries.flatMap(entry => entry.stateDiff ?? []);
+}

package/src/contracts/empire_base.ts

@@ -1,3 +1,4 @@
+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';
@@ -11,12 +12,12 @@ export interface IEmpireBase {
   getRoundInfo(
     rollupAddress: Hex,
     round: bigint,
-  ): Promise<{ lastSignalSlot: bigint; payloadWithMostSignals: Hex; executed: boolean }>;
-  computeRound(slot: bigint): Promise<bigint>;
+  ): Promise<{ lastSignalSlot: SlotNumber; payloadWithMostSignals: Hex; quorumReached: boolean; executed: boolean }>;
+  computeRound(slot: SlotNumber): Promise<bigint>;
   createSignalRequest(payload: Hex): L1TxRequest;
   createSignalRequestWithSignature(
     payload: Hex,
-    round: bigint,
+    slot: SlotNumber,
     chainId: number,
     signerAddress: Hex,
     signer: (msg: TypedDataDefinition) => Promise<Hex>,
@@ -51,7 +52,7 @@ export function encodeSignalWithSignature(payload: Hex, signature: Signature) {
 export async function signSignalWithSig(
   signer: (msg: TypedDataDefinition) => Promise<Hex>,
   payload: Hex,
-  slot: bigint,
+  slot: SlotNumber,
   instance: Hex,
   verifyingContract: Hex,
   chainId: number,
@@ -79,7 +80,7 @@ export async function signSignalWithSig(
 
   const message = {
     payload,
-    slot,
+    slot: BigInt(slot),
     instance,
   };
 

package/src/contracts/fee_asset_handler.ts

@@ -4,13 +4,14 @@ 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,
-    public readonly txUtils: L1TxUtils,
   ) {
     if (address instanceof EthAddress) {
       address = address.toString();
@@ -22,7 +23,7 @@ export class FeeAssetHandlerContract {
     const contract = getContract({
       abi: FeeAssetHandlerAbi,
       address: this.address.toString(),
-      client: this.txUtils.client,
+      client: this.client,
     });
     return EthAddress.fromString(await contract.read.owner());
   }
@@ -31,17 +32,18 @@ export class FeeAssetHandlerContract {
     const contract = getContract({
       abi: FeeAssetHandlerAbi,
       address: this.address.toString(),
-      client: this.txUtils.client,
+      client: this.client,
     });
     return contract.read.mintAmount();
   }
 
-  public mint(recipient: Hex | EthAddress) {
+  public mint(txUtils: L1TxUtils, recipient: Hex | EthAddress) {
     if (recipient instanceof EthAddress) {
       recipient = recipient.toString();
     }
-    return this.txUtils.sendAndMonitorTransaction({
+    return txUtils.sendAndMonitorTransaction({
       to: this.address.toString(),
+      abi: FeeAssetHandlerAbi,
       data: encodeFunctionData({
         abi: FeeAssetHandlerAbi,
         functionName: 'mint',
@@ -50,9 +52,10 @@ export class FeeAssetHandlerContract {
     });
   }
 
-  public setMintAmount(amount: bigint) {
-    return this.txUtils.sendAndMonitorTransaction({
+  public setMintAmount(txUtils: L1TxUtils, amount: bigint) {
+    return txUtils.sendAndMonitorTransaction({
       to: this.address.toString(),
+      abi: FeeAssetHandlerAbi,
       data: encodeFunctionData({
         abi: FeeAssetHandlerAbi,
         functionName: 'setMintAmount',