@aztec-labs/ethereum 6.0.0-nightly.20260829

package/src/contracts/governance_proposer.ts

@@ -0,0 +1,181 @@
+import { GovernanceProposerAbi } from '@aztec/l1-artifacts/GovernanceProposerAbi';
+
+import { SlotNumber } from '@aztec-labs/foundation/branded-types';
+import { memoize } from '@aztec-labs/foundation/decorators';
+import { EthAddress } from '@aztec-labs/foundation/eth-address';
+import {
+  type GetContractReturnType,
+  type Hex,
+  type TransactionReceipt,
+  type TypedDataDefinition,
+  encodeFunctionData,
+  getContract,
+} from 'viem';
+
+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 { type PayloadProposalStatus, 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,
+  ) {
+    if (address instanceof EthAddress) {
+      address = address.toString();
+    }
+    this.proposer = getContract({ address, abi: GovernanceProposerAbi, client });
+  }
+
+  public get address(): EthAddress {
+    return EthAddress.fromString(this.proposer.address);
+  }
+
+  public async getRollupAddress(): Promise<EthAddress> {
+    return EthAddress.fromString(await this.proposer.read.getInstance());
+  }
+
+  @memoize
+  public async getRegistryAddress(): Promise<EthAddress> {
+    return EthAddress.fromString(await this.proposer.read.REGISTRY());
+  }
+
+  public getQuorumSize(): Promise<bigint> {
+    return this.proposer.read.QUORUM_SIZE();
+  }
+
+  public getRoundSize(): Promise<bigint> {
+    return this.proposer.read.ROUND_SIZE();
+  }
+
+  public computeRound(slot: SlotNumber): Promise<bigint> {
+    return this.proposer.read.computeRound([BigInt(slot)]);
+  }
+
+  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(),
+      abi: GovernanceProposerAbi,
+      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.getRollupAddress()).toString(),
+      this.address.toString(),
+      chainId,
+    );
+    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);
+  }
+
+  /**
+   * Classifies the given original payload against the Governance proposal history (`'live'` /
+   * `'executed'` / `'none'`). Delegates to `ReadOnlyGovernanceContract.getPayloadProposalStatus`,
+   * 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 getPayloadProposalStatus(payload: Hex): Promise<PayloadProposalStatus> {
+    const governance = await this.getGovernance();
+    return governance.getPayloadProposalStatus(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,
+  ): Promise<{
+    receipt: TransactionReceipt;
+    proposalId: bigint;
+  }> {
+    const { receipt } = await l1TxUtils.sendAndMonitorTransaction({
+      to: this.address.toString(),
+      abi: GovernanceProposerAbi,
+      data: encodeFunctionData({
+        abi: GovernanceProposerAbi,
+        functionName: 'submitRoundWinner',
+        args: [round],
+      }),
+    });
+    const proposalId = extractProposalIdFromLogs(receipt.logs);
+    return { receipt, proposalId };
+  }
+}

package/src/contracts/gse.ts

@@ -0,0 +1,105 @@
+import { GSEAbi } from '@aztec/l1-artifacts/GSEAbi';
+
+import { EthAddress } from '@aztec-labs/foundation/eth-address';
+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[],
+    options?: { blockNumber?: bigint },
+  ) {
+    if (instance instanceof EthAddress) {
+      instance = instance.toString();
+    }
+    return this.gse.read.getAttestersFromIndicesAtTime([instance, ts, indices], options);
+  }
+
+  /** Number of attesters registered to `instance` as of the given L1 timestamp. */
+  public async getAttesterCountAtTime(
+    instance: Hex | EthAddress,
+    ts: bigint,
+    options?: { blockNumber?: bigint },
+  ): Promise<number> {
+    if (instance instanceof EthAddress) {
+      instance = instance.toString();
+    }
+    return Number(await this.gse.read.getAttesterCountAtTime([instance, ts], options));
+  }
+
+  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,223 @@
+import { InboxAbi } from '@aztec/l1-artifacts/InboxAbi';
+
+import { asyncPool } from '@aztec-labs/foundation/async-pool';
+import { maxBigint } from '@aztec-labs/foundation/bigint';
+import { Buffer32 } from '@aztec-labs/foundation/buffer';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { EthAddress } from '@aztec-labs/foundation/eth-address';
+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';
+
+/** The full L1-to-L2 message emitted by the Inbox, decoded from the event. Hashing it yields `leaf`. */
+export type MessageSentMessage = {
+  sender: { actor: `0x${string}`; chainId: bigint };
+  recipient: { actor: Fr; version: bigint };
+  content: Fr;
+  secretHash: Fr;
+  index: bigint;
+};
+
+/** Arguments for the MessageSent event. */
+export type MessageSentArgs = {
+  /** Compact cumulative index of the message in the Inbox insertion order (lifted from `message.index`). */
+  index: bigint;
+  leaf: Fr;
+  /** Consensus rolling hash (truncated sha256 chain) after this message. */
+  inboxRollingHash: Fr;
+  /** Sequence number of the Inbox bucket this message was absorbed into. */
+  bucketSeq: bigint;
+  /** The full message as emitted, making the event a self-contained record. */
+  message: MessageSentMessage;
+};
+
+/** Log type for MessageSent events, enriched with the emitting L1 block's timestamp (the bucket recency key). */
+export type MessageSentLog = L1EventLog<MessageSentArgs> & {
+  /** Timestamp (in seconds) of the L1 block that emitted the event; the key of the message's Inbox bucket. */
+  l1BlockTimestamp: bigint;
+};
+
+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.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;
+  }
+
+  /**
+   * Returns the Inbox's live chain position in one atomic call: the consensus rolling hash and cumulative total
+   * after the most recent message, plus the current bucket sequence. Used by the archiver's message sync and
+   * L1-reorg detection.
+   */
+  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 {
+      rollingHash: Fr.fromString(state.rollingHash),
+      totalMessagesInserted: state.totalMessagesInserted,
+      currentBucketSeq: state.currentBucketSeq,
+    };
+  }
+
+  /** Returns the sequence number of the Inbox bucket currently accumulating messages. */
+  public async getCurrentBucketSeq(opts: { blockTag?: BlockTag; blockNumber?: bigint } = {}): Promise<bigint> {
+    await checkBlockTag(opts.blockNumber, this.client);
+    return this.inbox.read.getCurrentBucketSeq(opts);
+  }
+
+  /** Returns the Inbox bucket with the given sequence number. */
+  public async getBucket(
+    seq: bigint,
+    opts: { blockTag?: BlockTag; blockNumber?: bigint } = {},
+  ): Promise<InboxContractBucket> {
+    await checkBlockTag(opts.blockNumber, this.client);
+    const bucket = await this.inbox.read.getBucket([seq], opts);
+    return {
+      rollingHash: Fr.fromString(bucket.rollingHash),
+      totalMsgCount: bucket.totalMsgCount,
+      timestamp: bucket.timestamp,
+      msgCount: bucket.msgCount,
+    };
+  }
+
+  /** 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 })).filter(
+      log => log.blockNumber! >= fromBlock && log.blockNumber! <= toBlock,
+    );
+    const timestamps = await this.getBlockTimestamps(logs.map(log => log.blockHash!));
+    return logs.map(log => this.mapMessageSentLog(log, timestamps.get(log.blockHash!)!));
+  }
+
+  /** 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 },
+    );
+    if (!log) {
+      return log as unknown as MessageSentLog;
+    }
+    const [timestamp] = (await this.getBlockTimestamps([log.blockHash!])).values();
+    return this.mapMessageSentLog(log, timestamp);
+  }
+
+  /**
+   * Fetches the timestamp of each distinct L1 block, so each MessageSent log can carry its bucket key. Blocks are
+   * resolved by hash, which pins them to the same fork the logs were read from: resolving by number would silently
+   * return the same-height block of another fork if the chain reorgs between the log query and this lookup, storing a
+   * timestamp that never applied to the message. By hash, such a reorg fails the lookup instead, and the caller
+   * retries against the reorged chain. Fetched with bounded concurrency to keep a large sync batch from fanning out
+   * unbounded RPC requests.
+   */
+  private async getBlockTimestamps(blockHashes: Hex[]): Promise<Map<Hex, bigint>> {
+    const uniqueBlockHashes = [...new Set(blockHashes)];
+    const timestamps = new Map<Hex, bigint>();
+    await asyncPool(10, uniqueBlockHashes, async blockHash => {
+      const block = await this.client.getBlock({ blockHash, includeTransactions: false });
+      timestamps.set(blockHash, block.timestamp);
+    });
+    return timestamps;
+  }
+
+  private mapMessageSentLog(
+    log: {
+      blockNumber: bigint | null;
+      blockHash: `0x${string}` | null;
+      transactionHash: `0x${string}` | null;
+      args: {
+        hash?: `0x${string}`;
+        inboxRollingHash?: `0x${string}`;
+        bucketSeq?: bigint;
+        message?: {
+          sender: { actor: `0x${string}`; chainId: bigint };
+          recipient: { actor: `0x${string}`; version: bigint };
+          content: `0x${string}`;
+          secretHash: `0x${string}`;
+          index: bigint;
+        };
+      };
+    },
+    l1BlockTimestamp: bigint,
+  ): MessageSentLog {
+    const message = log.args.message!;
+    return {
+      l1BlockNumber: log.blockNumber!,
+      l1BlockHash: Buffer32.fromString(log.blockHash!),
+      l1TransactionHash: log.transactionHash!,
+      l1BlockTimestamp,
+      args: {
+        index: message.index,
+        leaf: Fr.fromString(log.args.hash!),
+        inboxRollingHash: Fr.fromString(log.args.inboxRollingHash!),
+        bucketSeq: log.args.bucketSeq!,
+        message: {
+          sender: message.sender,
+          recipient: { actor: Fr.fromString(message.recipient.actor), version: message.recipient.version },
+          content: Fr.fromString(message.content),
+          secretHash: Fr.fromString(message.secretHash),
+          index: message.index,
+        },
+      },
+    };
+  }
+}
+
+/** The Inbox's live chain position, read atomically from the contract's getState. */
+export type InboxContractState = {
+  /** Consensus rolling hash after the most recently inserted message (zero when none was ever inserted). */
+  rollingHash: Fr;
+  /** Cumulative number of messages inserted into the Inbox. */
+  totalMessagesInserted: bigint;
+  /** Sequence number of the bucket currently accumulating messages. */
+  currentBucketSeq: bigint;
+};
+
+/** A snapshot of an on-chain Inbox rolling-hash bucket. */
+export type InboxContractBucket = {
+  /** Consensus rolling hash (truncated sha256 chain) after the last message absorbed into this bucket. */
+  rollingHash: Fr;
+  /** Cumulative number of messages inserted into the Inbox up to and including this bucket. */
+  totalMsgCount: bigint;
+  /** L1 block timestamp at which this bucket was opened; its recency key, in seconds. */
+  timestamp: bigint;
+  /** Number of messages absorbed into this bucket. */
+  msgCount: number;
+};

package/src/contracts/index.ts

@@ -0,0 +1,17 @@
+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';
+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 './slasher_contract.js';

package/src/contracts/log.ts

@@ -0,0 +1,13 @@
+import type { Buffer32 } from '@aztec-labs/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;
+};