@aztec-labs/ethereum 6.0.0-nightly.20260829

package/src/contracts/slasher_contract.ts

@@ -0,0 +1,89 @@
+import { SlasherAbi } from '@aztec/l1-artifacts/SlasherAbi';
+
+import { EthAddress } from '@aztec-labs/foundation/eth-address';
+import { createLogger } from '@aztec-labs/foundation/log';
+import { type GetContractReturnType, getContract } from 'viem';
+
+import type { ViemClient } from '../types.js';
+
+/**
+ * Typescript wrapper around the Slasher contract.
+ */
+export class SlasherContract {
+  private contract: GetContractReturnType<typeof SlasherAbi, ViemClient>;
+
+  constructor(
+    private readonly client: ViemClient,
+    private readonly address: EthAddress,
+    private readonly log = createLogger('slasher-contract'),
+  ) {
+    this.contract = getContract({
+      address: this.address.toString(),
+      abi: SlasherAbi,
+      client: this.client,
+    });
+  }
+
+  /**
+   * Checks if a slash payload is vetoed.
+   * @param payloadAddress - The address of the payload to check
+   * @returns True if the payload is vetoed, false otherwise
+   */
+  public async isPayloadVetoed(payloadAddress: EthAddress): Promise<boolean> {
+    try {
+      return await this.contract.read.vetoedPayloads([payloadAddress.toString()]);
+    } catch (error) {
+      this.log.error(`Error checking if payload ${payloadAddress} is vetoed`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Checks if slashing is currently enabled. Slashing can be disabled by the vetoer.
+   * @returns True if slashing is enabled, false otherwise
+   */
+  public async isSlashingEnabled(): Promise<boolean> {
+    try {
+      return await this.contract.read.isSlashingEnabled();
+    } catch (error) {
+      this.log.error(`Error checking if slashing is enabled`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Gets the current vetoer address.
+   * @returns The vetoer address
+   */
+  public async getVetoer(): Promise<EthAddress> {
+    const vetoer = await this.contract.read.VETOER();
+    return EthAddress.fromString(vetoer);
+  }
+
+  /**
+   * Gets the disable duration by the vetoer.
+   * @returns The disable duration in seconds
+   */
+  public async getSlashingDisableDuration(): Promise<number> {
+    const duration = await this.contract.read.SLASHING_DISABLE_DURATION();
+    return Number(duration);
+  }
+
+  /**
+   * Gets the current governance address.
+   * @returns The governance address
+   */
+  public async getGovernance(): Promise<EthAddress> {
+    const governance = await this.contract.read.GOVERNANCE();
+    return EthAddress.fromString(governance);
+  }
+
+  /**
+   * Gets the current proposer address.
+   * @returns The proposer address
+   */
+  public async getProposer(): Promise<EthAddress> {
+    const proposer = await this.contract.read.PROPOSER();
+    return EthAddress.fromString(proposer);
+  }
+}

package/src/contracts/slashing_proposer.ts

@@ -0,0 +1,397 @@
+import { SlasherAbi } from '@aztec/l1-artifacts/SlasherAbi';
+import { SlashingProposerAbi } from '@aztec/l1-artifacts/SlashingProposerAbi';
+
+import type { L1TxRequest } from '@aztec-labs/ethereum/l1-tx-utils';
+import type { ViemClient } from '@aztec-labs/ethereum/types';
+import { mergeAbis, tryExtractEvent } from '@aztec-labs/ethereum/utils';
+import { SlotNumber } from '@aztec-labs/foundation/branded-types';
+import { Buffer32 } from '@aztec-labs/foundation/buffer';
+import { memoize } from '@aztec-labs/foundation/decorators';
+import { EthAddress } from '@aztec-labs/foundation/eth-address';
+import { Signature } from '@aztec-labs/foundation/eth-signature';
+import { createLogger } from '@aztec-labs/foundation/log';
+import { hexToBuffer } from '@aztec-labs/foundation/string';
+import {
+  type GetContractReturnType,
+  type Hex,
+  type Log,
+  type TypedDataDefinition,
+  encodeFunctionData,
+  getContract,
+} from 'viem';
+
+import { type WatchContractEventOptions, watchContractEvent } from './watch_event.js';
+
+/**
+ * Wrapper around the SlashingProposer contract that provides
+ * a TypeScript interface for interacting with the consensus-based slashing system.
+ */
+export class SlashingProposerContract {
+  private readonly contract: GetContractReturnType<typeof SlashingProposerAbi, ViemClient>;
+  private readonly logger = createLogger('ethereum:slashing_proposer');
+
+  /**
+   * Slash target validators of the last round asked for. Safe to cache because a round's targets are the committees
+   * of epochs that had already ended when the round opened (see SLASH_OFFSET_IN_ROUNDS), and those committees are
+   * sampled from validator set and randao snapshots taken before the epoch started, so they cannot change while the
+   * round is live. The promise is cached rather than the result, so concurrent callers share one in-flight read.
+   */
+  private slashTargetValidators: { round: bigint; validators: Promise<EthAddress[]> } | undefined;
+
+  constructor(
+    public readonly client: ViemClient,
+    address: Hex | EthAddress,
+  ) {
+    this.contract = getContract({
+      address: typeof address === 'string' ? address : address.toString(),
+      abi: SlashingProposerAbi,
+      client,
+    });
+  }
+
+  public get address() {
+    return EthAddress.fromString(this.contract.address);
+  }
+
+  public getQuorumSize(): Promise<bigint> {
+    return this.contract.read.QUORUM();
+  }
+
+  public getRoundSize(): Promise<bigint> {
+    return this.contract.read.ROUND_SIZE();
+  }
+
+  public getCommitteeSize(): Promise<bigint> {
+    return this.contract.read.COMMITTEE_SIZE();
+  }
+
+  public getRoundSizeInEpochs(): Promise<bigint> {
+    return this.contract.read.ROUND_SIZE_IN_EPOCHS();
+  }
+
+  public getLifetimeInRounds(): Promise<bigint> {
+    return this.contract.read.LIFETIME_IN_ROUNDS();
+  }
+
+  public getExecutionDelayInRounds(): Promise<bigint> {
+    return this.contract.read.EXECUTION_DELAY_IN_ROUNDS();
+  }
+
+  /** Returns the slash amounts for the three slash unit levels. Immutable on the contract, so memoized. */
+  @memoize
+  public getSlashingAmounts(): Promise<[bigint, bigint, bigint]> {
+    return Promise.all([
+      this.contract.read.SLASH_AMOUNT_SMALL(),
+      this.contract.read.SLASH_AMOUNT_MEDIUM(),
+      this.contract.read.SLASH_AMOUNT_LARGE(),
+    ]);
+  }
+
+  public getSlashOffsetInRounds(): Promise<bigint> {
+    return this.contract.read.SLASH_OFFSET_IN_ROUNDS();
+  }
+
+  public getCurrentRound(): Promise<bigint> {
+    return this.contract.read.getCurrentRound();
+  }
+
+  /**
+   * Get round information
+   * @param round - The round number to query
+   * @returns Round status information
+   */
+  public async getRound(round: bigint): Promise<{
+    isExecuted: boolean;
+    voteCount: bigint;
+  }> {
+    const [isExecuted, voteCount] = await this.contract.read.getRound([round]);
+    return { isExecuted, voteCount };
+  }
+
+  /**
+   * Check if a round is ready to execute at a given slot
+   * @param round - The round number to check
+   * @param slot - The slot number to check at
+   * @returns Whether the round is ready to execute
+   */
+  public async isRoundReadyToExecute(round: bigint, slot: SlotNumber): Promise<boolean> {
+    return await this.contract.read.isRoundReadyToExecute([round, BigInt(slot)]);
+  }
+
+  /** Returns the slash actions and payload address for a given round (zero if no slash actions) */
+  public async getPayload(
+    round: bigint,
+  ): Promise<{ actions: { slashAmount: bigint; validator: EthAddress }[]; address: EthAddress }> {
+    const { result: committees } = await this.contract.simulate.getSlashTargetCommittees([round]);
+    const tally = await this.contract.read.getTally([round, committees]);
+    const address = await this.contract.read.getPayloadAddress([round, tally]);
+    const actions = this.mapSlashActions(tally);
+    return { actions, address: EthAddress.fromString(address) };
+  }
+
+  /** Returns the slash actions to be executed for a given round based on votes */
+  public async getTally(
+    round: bigint,
+  ): Promise<{ actions: { slashAmount: bigint; validator: EthAddress }[]; committees: EthAddress[][] }> {
+    const { result: committees } = await this.contract.simulate.getSlashTargetCommittees([round]);
+    const tally = await this.contract.read.getTally([round, committees]);
+    return { actions: this.mapSlashActions(tally), committees: committees.map(c => c.map(EthAddress.fromString)) };
+  }
+
+  private mapSlashActions(
+    actions: readonly { slashAmount: bigint; validator: Hex }[],
+  ): { slashAmount: bigint; validator: EthAddress }[] {
+    return actions.map(({ validator, slashAmount }) => ({
+      validator: EthAddress.fromString(validator),
+      slashAmount,
+    }));
+  }
+
+  /** Tries to extract a VoteCast event from the given logs. */
+  public tryExtractVoteCastEvent(logs: Log[]) {
+    return tryExtractEvent(logs, this.address.toString(), SlashingProposerAbi, 'VoteCast');
+  }
+
+  /** Tries to extract a RoundExecuted event from the given logs. */
+  public tryExtractRoundExecutedEvent(logs: Log[]) {
+    return tryExtractEvent(logs, this.address.toString(), SlashingProposerAbi, 'RoundExecuted');
+  }
+
+  /**
+   * Create a transaction to vote for slashing offenses
+   * @param votes - The encoded votes for slashing
+   * @param slot - The slot number for the vote
+   * @param signer - The signer to produce the signature
+   * @returns L1 transaction request
+   */
+  public async buildVoteRequestFromSigner(
+    votes: Hex,
+    slot: SlotNumber,
+    signer: (msg: TypedDataDefinition) => Promise<Hex>,
+  ): Promise<L1TxRequest> {
+    const typedData = this.buildVoteTypedData(votes, slot);
+    const signature = Signature.fromString(await signer(typedData));
+
+    return {
+      to: this.contract.address,
+      abi: SlashingProposerAbi,
+      data: encodeFunctionData({
+        abi: SlashingProposerAbi,
+        functionName: 'vote',
+        args: [votes, signature.toViemSignature()],
+      }),
+    };
+  }
+
+  /** Returns the typed data definition to EIP712-sign for voting */
+  public buildVoteTypedData(votes: Hex, slot: SlotNumber): TypedDataDefinition {
+    const domain = {
+      name: 'SlashingProposer',
+      version: '1',
+      chainId: this.client.chain.id,
+      verifyingContract: this.contract.address,
+    };
+
+    const types = {
+      EIP712Domain: [
+        { name: 'name', type: 'string' },
+        { name: 'version', type: 'string' },
+        { name: 'chainId', type: 'uint256' },
+        { name: 'verifyingContract', type: 'address' },
+      ],
+      Vote: [
+        { name: 'votes', type: 'bytes' },
+        { name: 'slot', type: 'uint256' },
+      ],
+    };
+
+    return { domain, types, primaryType: 'Vote', message: { votes, slot: BigInt(slot) } };
+  }
+
+  /** Gets the digest to sign for voting directly from the contract */
+  public async getVoteDataDigest(votes: Hex, slot: SlotNumber): Promise<Buffer32> {
+    return Buffer32.fromString(await this.contract.read.getVoteSignatureDigest([votes, BigInt(slot)]));
+  }
+
+  /**
+   * Create a transaction to vote for slashing offenses
+   * @param votes - The encoded votes for slashing
+   * @param signature - The signature from the current proposer
+   * @returns L1 transaction request
+   */
+  public buildVoteRequestWithSignature(votes: Hex, signature: { v: number; r: Hex; s: Hex }): L1TxRequest {
+    return {
+      to: this.contract.address,
+      abi: SlashingProposerAbi,
+      data: encodeFunctionData({
+        abi: SlashingProposerAbi,
+        functionName: 'vote',
+        args: [votes, signature],
+      }),
+    };
+  }
+
+  /**
+   * Create a transaction to execute a slashing round
+   * @param round - The round number to execute
+   * @param committees - The committees for each epoch in the round
+   * @returns L1 transaction request
+   */
+  public buildExecuteRoundRequest(round: bigint, committees: EthAddress[][]): L1TxRequest {
+    return {
+      to: this.contract.address,
+      abi: mergeAbis([SlashingProposerAbi, SlasherAbi]),
+      data: encodeFunctionData({
+        abi: SlashingProposerAbi,
+        functionName: 'executeRound',
+        args: [round, committees.map(c => c.map(addr => addr.toString()))],
+      }),
+    };
+  }
+
+  /**
+   * Returns the validators eligible to be voted against in a round, in the order votes encode them. Cached for the
+   * last round asked for: reading them runs a committee sampling simulation on L1, and every vote of a round decodes
+   * against the same list, so a caller walking a round's votes would otherwise repeat that call per vote. Only the
+   * last round is kept since callers move forward round by round.
+   */
+  public getSlashTargetValidators(round: bigint): Promise<EthAddress[]> {
+    const cached = this.slashTargetValidators;
+    if (cached?.round === round) {
+      return cached.validators;
+    }
+
+    const entry = { round, validators: this.fetchSlashTargetValidators(round) };
+    this.slashTargetValidators = entry;
+    // A failed read must not stay cached, or every later vote of the round would replay the same rejection
+    entry.validators.catch(() => {
+      if (this.slashTargetValidators === entry) {
+        this.slashTargetValidators = undefined;
+      }
+    });
+    return entry.validators;
+  }
+
+  private async fetchSlashTargetValidators(round: bigint): Promise<EthAddress[]> {
+    const { result } = await this.contract.simulate.getSlashTargetCommittees([round]);
+    return result.flat().map(validator => EthAddress.fromString(validator));
+  }
+
+  /**
+   * Returns the slash amount voted for each target validator by a single vote of a round.
+   * @param index - Position of the vote within the round, from 0 (inclusive) to the round's vote count (exclusive)
+   */
+  public async getVoteAt(round: bigint, index: bigint): Promise<SlashVoteTarget[]> {
+    const [validators, vote, slashAmounts] = await Promise.all([
+      this.getSlashTargetValidators(round),
+      this.contract.read.getVotes([round, index]),
+      this.getSlashingAmounts(),
+    ]);
+    return decodeVote(vote, validators, slashAmounts);
+  }
+
+  /** Returns the last vote emitted for a given round  */
+  public async getLastVote(round: bigint) {
+    const { voteCount } = await this.getRound(round);
+    return await this.getVoteAt(round, voteCount - 1n);
+  }
+
+  /**
+   * Listen for VoteCast events. Events are delivered by polling `eth_getLogs`: a reorg may re-emit them and
+   * removals are never reported, and events mined within roughly one polling interval of subscribing may be missed.
+   * @param callback - Callback receiving the round, the vote's index within the round as accepted by `getVoteAt`,
+   * and the proposer that cast it
+   * @returns Unwatch function
+   */
+  public listenToVoteCast(
+    callback: (args: { round: bigint; voteIndex: bigint; proposer: string }) => unknown,
+    options?: WatchContractEventOptions,
+  ): () => void {
+    return watchContractEvent(
+      this.client,
+      this.logger,
+      {
+        address: this.contract.address,
+        abi: SlashingProposerAbi,
+        eventName: 'VoteCast',
+        onLog: log => {
+          const { round, voteIndex, proposer } = log.args;
+          if (round !== undefined && voteIndex !== undefined && proposer) {
+            return callback({ round, voteIndex, proposer });
+          }
+        },
+      },
+      options,
+    );
+  }
+
+  /**
+   * Listen for RoundExecuted events. Events are delivered by polling `eth_getLogs`: a reorg may re-emit them and
+   * removals are never reported, and events mined within roughly one polling interval of subscribing may be missed.
+   * @param callback - Callback function to handle round executed events
+   * @returns Unwatch function
+   */
+  public listenToRoundExecuted(
+    callback: (args: { round: bigint; slashCount: bigint; l1BlockHash: Hex }) => unknown,
+    options?: WatchContractEventOptions,
+  ): () => void {
+    return watchContractEvent(
+      this.client,
+      this.logger,
+      {
+        address: this.contract.address,
+        abi: SlashingProposerAbi,
+        eventName: 'RoundExecuted',
+        onLog: log => {
+          const { round, slashCount } = log.args;
+          if (round !== undefined && slashCount !== undefined) {
+            return callback({ round, slashCount, l1BlockHash: log.blockHash });
+          }
+        },
+      },
+      options,
+    );
+  }
+}
+
+/**
+ * A validator targeted by a slashing vote, with the amount voted. The position is the validator's index in the
+ * round's flattened slash target committees — the unit the contract tallies quorum by. A validator sitting in
+ * several of the round's committees holds several positions, each with its own tally.
+ */
+export type SlashVoteTarget = { validator: EthAddress; slashAmount: bigint; position: number };
+
+function decodeVote(vote: Hex, validators: EthAddress[], slashAmounts: [bigint, bigint, bigint]): SlashVoteTarget[] {
+  return decodeSlashConsensusVotes(hexToBuffer(vote))
+    .map((units, position) => ({
+      validator: validators[position],
+      slashAmount: slashAmounts[units - 1] ?? 0n,
+      position,
+    }))
+    .filter(v => v.slashAmount > 0n);
+}
+
+/**
+ * Decodes a Buffer containing slash votes back into an array of numbers.
+ * Each vote is represented as a 2-bit value (0, 1, 2, or 3) representing slashing units.
+ * @dev This should live in stdlib next to encodeSlashConsensusVotes but is here since we
+ * do not have a dependency to stdlib from the ethereum package. We need a larger refactor to fix this.
+ * @param buffer - The Buffer containing encoded slash votes
+ * @returns An array of numbers representing the slash votes
+ */
+export function decodeSlashConsensusVotes(buffer: Buffer): number[] {
+  const votes: number[] = [];
+  for (let i = 0; i < buffer.length; i++) {
+    const voteByte = buffer.readUInt8(i);
+    // Decode votes from Solidity's bit order (LSB to MSB)
+    // Bits 0-1: validator at index i*4
+    // Bits 2-3: validator at index i*4+1
+    // Bits 4-5: validator at index i*4+2
+    // Bits 6-7: validator at index i*4+3
+    votes.push((voteByte >> 0) & 0x03);
+    votes.push((voteByte >> 2) & 0x03);
+    votes.push((voteByte >> 4) & 0x03);
+    votes.push((voteByte >> 6) & 0x03);
+  }
+  return votes;
+}

package/src/contracts/utils.ts

@@ -0,0 +1,14 @@
+import type { ViemClient } from '../types.js';
+import { BlockTagTooOldError } from './errors.js';
+
+const L1_NON_ARCHIVE_BLOCK_HISTORY_LENGTH = 128n;
+
+export async function checkBlockTag(block: bigint | undefined, publicClient: ViemClient) {
+  if (block === undefined) {
+    return;
+  }
+  const latestBlock = await publicClient.getBlockNumber();
+  if (block < latestBlock - L1_NON_ARCHIVE_BLOCK_HISTORY_LENGTH) {
+    throw new BlockTagTooOldError(block, latestBlock);
+  }
+}

package/src/contracts/watch_event.ts

@@ -0,0 +1,109 @@
+import type { Logger } from '@aztec-labs/foundation/log';
+import { RunningPromise } from '@aztec-labs/foundation/promise';
+import type { Abi, ContractEventName, GetContractEventsReturnType, Hex } from 'viem';
+
+import type { ViemClient } from '../types.js';
+
+/** Default maximum number of blocks queried per `eth_getLogs` request. */
+const DEFAULT_MAX_BLOCK_RANGE = 100;
+
+/** Options for {@link watchContractEvent}. */
+export type WatchContractEventOptions = {
+  /** How often to poll for new L1 blocks, in ms. Defaults to the client's polling interval. */
+  pollingIntervalMs?: number;
+  /** Maximum number of blocks per `eth_getLogs` request; wider catch-up ranges are split into chunks. */
+  maxBlockRange?: number;
+};
+
+/** Event identity and handler for {@link watchContractEvent}. */
+export type WatchContractEventParameters<
+  TAbi extends Abi,
+  TEventName extends ContractEventName<TAbi>,
+  TStrict extends boolean | undefined = undefined,
+> = {
+  address: Hex;
+  abi: TAbi;
+  eventName: TEventName;
+  /** Whether logs must decode against the event's indexed/non-indexed arguments (defaults to false). */
+  strict?: TStrict;
+  /** Called once per event log. Errors, thrown or from a returned promise, are caught and logged. */
+  onLog: (log: GetContractEventsReturnType<TAbi, TEventName, TStrict>[number]) => unknown;
+};
+
+/**
+ * Watches for contract events by polling `eth_blockNumber` (cached by viem per client) and fetching new logs with
+ * ranged `eth_getLogs` requests, never installing server-side filters. Server-side filters are unusable against
+ * real-world endpoints: a load balancer routes polls to backends that never saw the filter, and providers report a
+ * purged filter with error codes viem does not recognize as "filter gone", so viem's own watchers either churn
+ * recreating filters or poll a dead filter id forever while silently missing events.
+ *
+ * The block that is latest on the first poll becomes the starting cursor, so its events are reported and events from
+ * earlier blocks are not. Requests never span more than `maxBlockRange` blocks: catching up after downtime is
+ * chunked into multiple requests, and the cursor advances per successful chunk so a failure retries from where it
+ * left off on the next tick. A reorg may re-emit events and removals are never reported.
+ *
+ * @returns A function that stops the watcher.
+ */
+export function watchContractEvent<
+  TAbi extends Abi,
+  TEventName extends ContractEventName<TAbi>,
+  TStrict extends boolean | undefined = undefined,
+>(
+  client: ViemClient,
+  logger: Logger,
+  params: WatchContractEventParameters<TAbi, TEventName, TStrict>,
+  options: WatchContractEventOptions = {},
+): () => void {
+  const { address, abi, eventName, strict, onLog } = params;
+  const pollingIntervalMs = options.pollingIntervalMs ?? client.pollingInterval;
+  const maxBlockRange = BigInt(options.maxBlockRange ?? DEFAULT_MAX_BLOCK_RANGE);
+
+  const logHandlerError = (err: unknown) => logger.error(`Error handling ${eventName} L1 event`, err);
+  const deliver = (log: GetContractEventsReturnType<TAbi, TEventName, TStrict>[number]) => {
+    try {
+      const result = onLog(log);
+      if (result instanceof Promise) {
+        result.catch(logHandlerError);
+      }
+    } catch (err) {
+      logHandlerError(err);
+    }
+  };
+
+  let stopped = false;
+  let nextBlock: bigint | undefined;
+
+  const poll = async () => {
+    const latestBlock = await client.getBlockNumber();
+    if (nextBlock === undefined) {
+      nextBlock = latestBlock;
+      return;
+    }
+    let fromBlock: bigint = nextBlock;
+    while (fromBlock <= latestBlock && !stopped) {
+      const chunkEnd = fromBlock + maxBlockRange - 1n;
+      const toBlock = chunkEnd < latestBlock ? chunkEnd : latestBlock;
+      const logs = await client.getContractEvents<TAbi, TEventName, TStrict, bigint, bigint>({
+        address,
+        abi,
+        eventName,
+        strict,
+        fromBlock,
+        toBlock,
+      });
+      for (const log of logs) {
+        deliver(log);
+      }
+      fromBlock = toBlock + 1n;
+      nextBlock = fromBlock;
+    }
+  };
+
+  const handlePollError = (err: unknown) => logger.warn(`Error polling for ${eventName} L1 events`, { err });
+  const runner = new RunningPromise(poll, logger, pollingIntervalMs, handlePollError).start();
+
+  return () => {
+    stopped = true;
+    void runner.stop();
+  };
+}