@aztec/sequencer-client 0.0.0-test.0

package/src/sequencer/timetable.ts

@@ -0,0 +1,123 @@
+import { createLogger } from '@aztec/aztec.js';
+
+import type { SequencerMetrics } from './metrics.js';
+import { SequencerState } from './utils.js';
+
+export class SequencerTimetable {
+  /** How late into the slot can we be to start working */
+  public readonly initialTime = 3;
+
+  /** How long it takes to get ready to start building */
+  public readonly blockPrepareTime = 1;
+
+  /** How long it takes to for proposals and attestations to travel across the p2p layer (one-way) */
+  public readonly attestationPropagationTime = 2;
+
+  /** How much time we spend validating and processing a block after building it, and assembling the proposal to send to attestors */
+  public readonly blockValidationTime = 1;
+
+  /**
+   * How long it takes to get a published block into L1. L1 builders typically accept txs up to 4 seconds into their slot,
+   * but we'll timeout sooner to give it more time to propagate (remember we also have blobs!). Still, when working in anvil,
+   * we can just post in the very last second of the L1 slot and still expect the tx to be accepted.
+   */
+  public readonly l1PublishingTime;
+
+  constructor(
+    private readonly ethereumSlotDuration: number,
+    private readonly aztecSlotDuration: number,
+    private readonly maxL1TxInclusionTimeIntoSlot: number,
+    private readonly enforce: boolean = true,
+    private readonly metrics?: SequencerMetrics,
+    private readonly log = createLogger('sequencer:timetable'),
+  ) {
+    this.l1PublishingTime = this.ethereumSlotDuration - this.maxL1TxInclusionTimeIntoSlot;
+  }
+
+  private get afterBlockBuildingTimeNeededWithoutReexec() {
+    return this.blockValidationTime + this.attestationPropagationTime * 2 + this.l1PublishingTime;
+  }
+
+  public getBlockProposalExecTimeEnd(secondsIntoSlot: number): number {
+    // We are N seconds into the slot. We need to account for `afterBlockBuildingTimeNeededWithoutReexec` seconds,
+    // send then split the remaining time between the re-execution and the block building.
+    const maxAllowed = this.aztecSlotDuration - this.afterBlockBuildingTimeNeededWithoutReexec;
+    const available = maxAllowed - secondsIntoSlot;
+    const executionTimeEnd = secondsIntoSlot + available / 2;
+    this.log.debug(`Block proposal execution time deadline is ${executionTimeEnd}`, {
+      secondsIntoSlot,
+      maxAllowed,
+      available,
+      executionTimeEnd,
+    });
+    return executionTimeEnd;
+  }
+
+  private get afterBlockReexecTimeNeeded() {
+    return this.attestationPropagationTime + this.l1PublishingTime;
+  }
+
+  public getValidatorReexecTimeEnd(secondsIntoSlot: number): number {
+    // We need to leave for `afterBlockReexecTimeNeeded` seconds available.
+    const validationTimeEnd = this.aztecSlotDuration - this.afterBlockReexecTimeNeeded;
+    this.log.debug(`Validator re-execution time deadline is ${validationTimeEnd}`, {
+      secondsIntoSlot,
+      validationTimeEnd,
+    });
+    return validationTimeEnd;
+  }
+
+  public getMaxAllowedTime(state: SequencerState): number | undefined {
+    switch (state) {
+      case SequencerState.STOPPED:
+      case SequencerState.IDLE:
+      case SequencerState.SYNCHRONIZING:
+      case SequencerState.PROPOSER_CHECK:
+        return; // We don't really care about times for this states
+      case SequencerState.INITIALIZING_PROPOSAL:
+        return this.initialTime;
+      case SequencerState.CREATING_BLOCK:
+        return this.initialTime + this.blockPrepareTime;
+      case SequencerState.COLLECTING_ATTESTATIONS:
+        return this.aztecSlotDuration - this.l1PublishingTime - 2 * this.attestationPropagationTime;
+      case SequencerState.PUBLISHING_BLOCK:
+        return this.aztecSlotDuration - this.l1PublishingTime;
+      default: {
+        const _exhaustiveCheck: never = state;
+        throw new Error(`Unexpected state: ${state}`);
+      }
+    }
+  }
+
+  public assertTimeLeft(newState: SequencerState, secondsIntoSlot: number) {
+    if (!this.enforce) {
+      return;
+    }
+
+    const maxAllowedTime = this.getMaxAllowedTime(newState);
+    if (maxAllowedTime === undefined) {
+      return;
+    }
+
+    const bufferSeconds = maxAllowedTime - secondsIntoSlot;
+    if (bufferSeconds < 0) {
+      throw new SequencerTooSlowError(newState, maxAllowedTime, secondsIntoSlot);
+    }
+
+    this.metrics?.recordStateTransitionBufferMs(Math.floor(bufferSeconds * 1000), newState);
+    this.log.trace(`Enough time to transition to ${newState}`, { maxAllowedTime, secondsIntoSlot });
+  }
+}
+
+export class SequencerTooSlowError extends Error {
+  constructor(
+    public readonly proposedState: SequencerState,
+    public readonly maxAllowedTime: number,
+    public readonly currentTime: number,
+  ) {
+    super(
+      `Too far into slot for ${proposedState} (time into slot ${currentTime}s greater than ${maxAllowedTime}s allowance)`,
+    );
+    this.name = 'SequencerTooSlowError';
+  }
+}

package/src/sequencer/utils.ts

@@ -0,0 +1,74 @@
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import { Signature } from '@aztec/foundation/eth-signature';
+import type { BlockAttestation } from '@aztec/stdlib/p2p';
+
+export enum SequencerState {
+  /**
+   * Sequencer is stopped and not processing any txs from the pool.
+   */
+  STOPPED = 'STOPPED',
+  /**
+   * Sequencer is awaiting the next call to work().
+   */
+  IDLE = 'IDLE',
+  /**
+   * Synchronizing with the L2 chain.
+   */
+  SYNCHRONIZING = 'SYNCHRONIZING',
+  /**
+   * Checking if we are the proposer for the current slot.
+   */
+  PROPOSER_CHECK = 'PROPOSER_CHECK',
+  /**
+   * Initializing the block proposal. Will move to CREATING_BLOCK if there are valid txs to include, or back to SYNCHRONIZING otherwise.
+   */
+  INITIALIZING_PROPOSAL = 'INITIALIZING_PROPOSAL',
+  /**
+   * Creating a new L2 block. Includes processing public function calls and running rollup circuits. Will move to PUBLISHING_CONTRACT_DATA.
+   */
+  CREATING_BLOCK = 'CREATING_BLOCK',
+  /**
+   * Collecting attestations from its peers. Will move to PUBLISHING_BLOCK.
+   */
+  COLLECTING_ATTESTATIONS = 'COLLECTING_ATTESTATIONS',
+  /**
+   * Sending the tx to L1 with the L2 block data and awaiting it to be mined. Will move to SYNCHRONIZING.
+   */
+  PUBLISHING_BLOCK = 'PUBLISHING_BLOCK',
+}
+
+export type SequencerStateCallback = () => SequencerState;
+
+export function sequencerStateToNumber(state: SequencerState): number {
+  return Object.values(SequencerState).indexOf(state);
+}
+
+/** Order Attestations
+ *
+ * Returns attestation signatures in the order of a series of provided ethereum addresses
+ * The rollup smart contract expects attestations to appear in the order of the committee
+ *
+ * @todo: perform this logic within the memory attestation store instead?
+ */
+export async function orderAttestations(
+  attestations: BlockAttestation[],
+  orderAddresses: EthAddress[],
+): Promise<Signature[]> {
+  // Create a map of sender addresses to BlockAttestations
+  const attestationMap = new Map<string, BlockAttestation>();
+
+  for (const attestation of attestations) {
+    const sender = await attestation.getSender();
+    if (sender) {
+      attestationMap.set(sender.toString(), attestation);
+    }
+  }
+
+  // Create the ordered array based on the orderAddresses, else return an empty signature
+  const orderedAttestations = orderAddresses.map(address => {
+    const addressString = address.toString();
+    return attestationMap.get(addressString)?.signature || Signature.empty();
+  });
+
+  return orderedAttestations;
+}

package/src/slasher/factory.ts

@@ -0,0 +1,15 @@
+import type { L1ContractsConfig, L1ReaderConfig } from '@aztec/ethereum';
+import type { L2BlockSourceEventEmitter } from '@aztec/stdlib/block';
+import { type TelemetryClient, getTelemetryClient } from '@aztec/telemetry-client';
+
+import { SlasherClient } from './slasher_client.js';
+import type { SlasherConfig } from './slasher_client.js';
+
+export const createSlasherClient = (
+  _config: SlasherConfig & L1ContractsConfig & L1ReaderConfig,
+  l2BlockSource: L2BlockSourceEventEmitter,
+  telemetry: TelemetryClient = getTelemetryClient(),
+) => {
+  const config = { ..._config };
+  return new SlasherClient(config, l2BlockSource, telemetry);
+};

package/src/slasher/index.ts

@@ -0,0 +1,2 @@
+export * from './slasher_client.js';
+export { createSlasherClient } from './factory.js';

package/src/slasher/slasher_client.ts

@@ -0,0 +1,193 @@
+import {
+  type L1ContractsConfig,
+  type L1ReaderConfig,
+  type ViemPublicClient,
+  createEthereumChain,
+} from '@aztec/ethereum';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { createLogger } from '@aztec/foundation/log';
+import { SlashFactoryAbi } from '@aztec/l1-artifacts';
+import {
+  type L2BlockId,
+  type L2BlockSourceEvent,
+  type L2BlockSourceEventEmitter,
+  L2BlockSourceEvents,
+} from '@aztec/stdlib/block';
+import { type TelemetryClient, WithTracer, getTelemetryClient } from '@aztec/telemetry-client';
+
+import { type GetContractReturnType, createPublicClient, fallback, getAddress, getContract, http } from 'viem';
+
+/**
+ * Enum defining the possible states of the Slasher client.
+ */
+export enum SlasherClientState {
+  IDLE,
+  RUNNING,
+  STOPPED,
+}
+
+/**
+ * The synchronization status of the Slasher client.
+ */
+export interface SlasherSyncState {
+  /**
+   * The current state of the slasher client.
+   */
+  state: SlasherClientState;
+  /**
+   * The block number that the slasher client is synced to.
+   */
+  syncedToL2Block: L2BlockId;
+}
+
+export interface SlasherConfig {
+  blockCheckIntervalMS: number;
+  blockRequestBatchSize: number;
+}
+
+type SlashEvent = {
+  epoch: bigint;
+  amount: bigint;
+  lifetime: bigint;
+};
+
+/**
+ * @notice A Hypomeiones slasher client implementation
+ *
+ * Hypomeiones: a class of individuals in ancient Sparta who were considered inferior or lesser citizens compared
+ * to the full Spartan citizens.
+ *
+ * The implementation here is less than ideal. It exists, not to be the end all be all, but to show that
+ * slashing can be done with this mechanism.
+ *
+ * The implementation is VERY brute in the sense that it only looks for pruned blocks and then tries to slash
+ * the full committee of that.
+ * If it sees a prune, it will mark the full epoch as "to be slashed".
+ *
+ * Also, it is not particularly smart around what it should if there were to be multiple slashing events.
+ *
+ * A few improvements:
+ * - Only vote on the proposal if it is possible to reach, e.g., if 6 votes are needed and only 4 slots are left don't vote.
+ * - Stop voting on a payload once it is processed.
+ * - Only vote on the proposal if it have not already been executed
+ *  - Caveat, we need to fully decide if it is acceptable to have the same payload address multiple times. In the current
+ *    slash factory that could mean slashing the same committee for the same error multiple times.
+ * - Decide how to deal with multiple slashing events in the same round.
+ *  - This could be that multiple epochs are pruned in the same round, but with the current naive implementation we could end up
+ *    slashing only the first, because the "lifetime" of the second would have passed after that vote
+ */
+export class SlasherClient extends WithTracer {
+  private slashEvents: SlashEvent[] = [];
+
+  protected slashFactoryContract?: GetContractReturnType<typeof SlashFactoryAbi, ViemPublicClient> = undefined;
+
+  // The amount to slash for a prune.
+  // Note that we set it to 0, such that no actual slashing will happen, but the event will be fired,
+  // showing that the slashing mechanism is working.
+  private slashingAmount: bigint = 0n;
+
+  constructor(
+    private config: SlasherConfig & L1ContractsConfig & L1ReaderConfig,
+    private l2BlockSource: L2BlockSourceEventEmitter,
+    telemetry: TelemetryClient = getTelemetryClient(),
+    private log = createLogger('slasher'),
+  ) {
+    super(telemetry, 'slasher');
+
+    if (config.l1Contracts.slashFactoryAddress && config.l1Contracts.slashFactoryAddress !== EthAddress.ZERO) {
+      const chain = createEthereumChain(config.l1RpcUrls, config.l1ChainId);
+      const publicClient = createPublicClient({
+        chain: chain.chainInfo,
+        transport: fallback(chain.rpcUrls.map(url => http(url))),
+        pollingInterval: config.viemPollingIntervalMS,
+      });
+
+      this.slashFactoryContract = getContract({
+        address: getAddress(config.l1Contracts.slashFactoryAddress.toString()),
+        abi: SlashFactoryAbi,
+        client: publicClient,
+      });
+    } else {
+      this.log.warn('No slash factory address found, slashing will not be enabled');
+    }
+
+    this.log.info(`Slasher client initialized`);
+  }
+
+  public start() {
+    this.log.info('Starting Slasher client...');
+    this.l2BlockSource.on(L2BlockSourceEvents.L2PruneDetected, this.handlePruneL2Blocks.bind(this));
+  }
+
+  // This is where we should put a bunch of the improvements mentioned earlier.
+  public async getSlashPayload(slotNumber: bigint): Promise<EthAddress | undefined> {
+    if (!this.slashFactoryContract) {
+      return undefined;
+    }
+
+    // As long as the slot is greater than the lifetime, we want to keep deleting the first element
+    // since it will not make sense to include anymore.
+    while (this.slashEvents.length > 0 && this.slashEvents[0].lifetime < slotNumber) {
+      this.slashEvents.shift();
+    }
+
+    if (this.slashEvents.length == 0) {
+      return undefined;
+    }
+
+    const slashEvent = this.slashEvents[0];
+
+    const [payloadAddress, isDeployed] = await this.slashFactoryContract.read.getAddressAndIsDeployed([
+      slashEvent.epoch,
+      slashEvent.amount,
+    ]);
+
+    if (!isDeployed) {
+      // The proposal cannot be executed until it is deployed
+      this.log.verbose(`Voting on not yet deployed payload: ${payloadAddress}`);
+    }
+
+    return EthAddress.fromString(payloadAddress);
+  }
+
+  public handleBlockStreamEvent(event: L2BlockSourceEvent): Promise<void> {
+    this.log.debug(`Handling block stream event ${event.type}`);
+    switch (event.type) {
+      case L2BlockSourceEvents.L2PruneDetected:
+        this.handlePruneL2Blocks(event);
+        break;
+      default: {
+        break;
+      }
+    }
+    return Promise.resolve();
+  }
+
+  /**
+   * Allows consumers to stop the instance of the slasher client.
+   * 'ready' will now return 'false' and the running promise that keeps the client synced is interrupted.
+   */
+  public stop() {
+    this.log.debug('Stopping Slasher client...');
+    this.l2BlockSource.removeListener(L2BlockSourceEvents.L2PruneDetected, this.handlePruneL2Blocks.bind(this));
+    this.log.info('Slasher client stopped.');
+  }
+
+  // I need to get the slot number from the block that was just pruned
+  private handlePruneL2Blocks(event: L2BlockSourceEvent): void {
+    const { slotNumber, epochNumber } = event;
+    this.log.info(`Detected chain prune. Punishing the validators at epoch ${epochNumber}`);
+
+    // Set the lifetime such that we have a full round that we could vote throughout.
+    const slotsIntoRound = slotNumber % BigInt(this.config.slashingRoundSize);
+    const toNext = slotsIntoRound == 0n ? 0n : BigInt(this.config.slashingRoundSize) - slotsIntoRound;
+
+    const lifetime = slotNumber + toNext + BigInt(this.config.slashingRoundSize);
+
+    this.slashEvents.push({
+      epoch: epochNumber,
+      amount: this.slashingAmount,
+      lifetime,
+    });
+  }
+}

package/src/test/index.ts

@@ -0,0 +1,20 @@
+import type { PublicProcessorFactory } from '@aztec/simulator/server';
+
+import { SequencerClient } from '../client/sequencer-client.js';
+import type { SequencerPublisher } from '../publisher/sequencer-publisher.js';
+import { Sequencer } from '../sequencer/sequencer.js';
+import type { SequencerTimetable } from '../sequencer/timetable.js';
+
+class TestSequencer_ extends Sequencer {
+  public override publicProcessorFactory!: PublicProcessorFactory;
+  public override timetable!: SequencerTimetable;
+  public override publisher!: SequencerPublisher;
+}
+
+export type TestSequencer = TestSequencer_;
+
+class TestSequencerClient_ extends SequencerClient {
+  public override sequencer!: TestSequencer;
+}
+
+export type TestSequencerClient = TestSequencerClient_;

package/src/tx_validator/archive_cache.ts

@@ -0,0 +1,28 @@
+import type { Fr } from '@aztec/foundation/fields';
+import type { ArchiveSource } from '@aztec/p2p';
+import type { MerkleTreeReadOperations } from '@aztec/stdlib/interfaces/server';
+import { MerkleTreeId } from '@aztec/stdlib/trees';
+
+/**
+ * Implements an archive source by checking a DB and an in-memory collection.
+ * Intended for validating transactions as they are added to a block.
+ */
+export class ArchiveCache implements ArchiveSource {
+  archives: Map<string, bigint>;
+
+  constructor(private db: MerkleTreeReadOperations) {
+    this.archives = new Map<string, bigint>();
+  }
+
+  public async getArchiveIndices(archives: Fr[]): Promise<(bigint | undefined)[]> {
+    const toCheckDb = archives.filter(n => !this.archives.has(n.toString()));
+    const dbHits = await this.db.findLeafIndices(MerkleTreeId.ARCHIVE, toCheckDb);
+    dbHits.forEach((x, index) => {
+      if (x !== undefined) {
+        this.archives.set(toCheckDb[index].toString(), x);
+      }
+    });
+
+    return archives.map(n => this.archives.get(n.toString()));
+  }
+}

package/src/tx_validator/gas_validator.ts

@@ -0,0 +1,101 @@
+import { Fr } from '@aztec/foundation/fields';
+import { createLogger } from '@aztec/foundation/log';
+import { computeFeePayerBalanceStorageSlot } from '@aztec/protocol-contracts/fee-juice';
+import { getExecutionRequestsByPhase } from '@aztec/simulator/server';
+import { FunctionSelector } from '@aztec/stdlib/abi';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { GasFees } from '@aztec/stdlib/gas';
+import { type Tx, TxExecutionPhase, type TxValidationResult, type TxValidator } from '@aztec/stdlib/tx';
+
+/** Provides a view into public contract state */
+export interface PublicStateSource {
+  storageRead: (contractAddress: AztecAddress, slot: Fr) => Promise<Fr>;
+}
+
+export class GasTxValidator implements TxValidator<Tx> {
+  #log = createLogger('sequencer:tx_validator:tx_gas');
+  #publicDataSource: PublicStateSource;
+  #feeJuiceAddress: AztecAddress;
+  #gasFees: GasFees;
+
+  constructor(publicDataSource: PublicStateSource, feeJuiceAddress: AztecAddress, gasFees: GasFees) {
+    this.#publicDataSource = publicDataSource;
+    this.#feeJuiceAddress = feeJuiceAddress;
+    this.#gasFees = gasFees;
+  }
+
+  async validateTx(tx: Tx): Promise<TxValidationResult> {
+    if (await this.#shouldSkip(tx)) {
+      return Promise.resolve({ result: 'skipped', reason: ['Insufficient fee per gas'] });
+    }
+    return this.#validateTxFee(tx);
+  }
+
+  /**
+   * Check whether the tx's max fees are valid for the current block, and skip if not.
+   * We skip instead of invalidating since the tx may become eligible later.
+   * Note that circuits check max fees even if fee payer is unset, so we
+   * keep this validation even if the tx does not pay fees.
+   */
+  async #shouldSkip(tx: Tx): Promise<boolean> {
+    const gasSettings = tx.data.constants.txContext.gasSettings;
+
+    // Skip the tx if its max fees are not enough for the current block's gas fees.
+    const maxFeesPerGas = gasSettings.maxFeesPerGas;
+    const notEnoughMaxFees =
+      maxFeesPerGas.feePerDaGas.lt(this.#gasFees.feePerDaGas) ||
+      maxFeesPerGas.feePerL2Gas.lt(this.#gasFees.feePerL2Gas);
+
+    if (notEnoughMaxFees) {
+      this.#log.warn(`Skipping transaction ${await tx.getTxHash()} due to insufficient fee per gas`, {
+        txMaxFeesPerGas: maxFeesPerGas.toInspect(),
+        currentGasFees: this.#gasFees.toInspect(),
+      });
+    }
+    return notEnoughMaxFees;
+  }
+
+  async #validateTxFee(tx: Tx): Promise<TxValidationResult> {
+    const feePayer = tx.data.feePayer;
+
+    // Compute the maximum fee that this tx may pay, based on its gasLimits and maxFeePerGas
+    const feeLimit = tx.data.constants.txContext.gasSettings.getFeeLimit();
+
+    // Read current balance of the feePayer
+    const initialBalance = await this.#publicDataSource.storageRead(
+      this.#feeJuiceAddress,
+      await computeFeePayerBalanceStorageSlot(feePayer),
+    );
+
+    // If there is a claim in this tx that increases the fee payer balance in Fee Juice, add it to balance
+    const setupFns = getExecutionRequestsByPhase(tx, TxExecutionPhase.SETUP);
+    const increasePublicBalanceSelector = await FunctionSelector.fromSignature(
+      '_increase_public_balance((Field),u128)',
+    );
+    const claimFunctionCall = setupFns.find(
+      fn =>
+        fn.callContext.contractAddress.equals(this.#feeJuiceAddress) &&
+        fn.callContext.msgSender.equals(this.#feeJuiceAddress) &&
+        fn.args.length > 2 &&
+        // Public functions get routed through the dispatch function, whose first argument is the target function selector.
+        fn.args[0].equals(increasePublicBalanceSelector.toField()) &&
+        fn.args[1].equals(feePayer.toField()) &&
+        !fn.callContext.isStaticCall,
+    );
+
+    // The claim amount is at index 2 in the args array because:
+    // - Index 0: Target function selector (due to dispatch routing)
+    // - Index 1: Amount recipient
+    // - Index 2: Amount being claimed
+    const balance = claimFunctionCall ? initialBalance.add(claimFunctionCall.args[2]) : initialBalance;
+    if (balance.lt(feeLimit)) {
+      this.#log.warn(`Rejecting transaction due to not enough fee payer balance`, {
+        feePayer,
+        balance: balance.toBigInt(),
+        feeLimit: feeLimit.toBigInt(),
+      });
+      return { result: 'invalid', reason: ['Insufficient fee payer balance'] };
+    }
+    return { result: 'valid' };
+  }
+}

package/src/tx_validator/nullifier_cache.ts

@@ -0,0 +1,30 @@
+import type { NullifierSource } from '@aztec/p2p';
+import type { MerkleTreeReadOperations } from '@aztec/stdlib/interfaces/server';
+import { MerkleTreeId } from '@aztec/stdlib/trees';
+
+/**
+ * Implements a nullifier source by checking a DB and an in-memory collection.
+ * Intended for validating transactions as they are added to a block.
+ */
+export class NullifierCache implements NullifierSource {
+  nullifiers: Set<string>;
+
+  constructor(private db: MerkleTreeReadOperations) {
+    this.nullifiers = new Set();
+  }
+
+  public async nullifiersExist(nullifiers: Buffer[]): Promise<boolean[]> {
+    const cacheResults = nullifiers.map(n => this.nullifiers.has(n.toString()));
+    const toCheckDb = nullifiers.filter((_n, index) => !cacheResults[index]);
+    const dbHits = await this.db.findLeafIndices(MerkleTreeId.NULLIFIER_TREE, toCheckDb);
+
+    let dbIndex = 0;
+    return nullifiers.map((_n, index) => cacheResults[index] || dbHits[dbIndex++] !== undefined);
+  }
+
+  public addNullifiers(nullifiers: Buffer[]) {
+    for (const nullifier of nullifiers) {
+      this.nullifiers.add(nullifier.toString());
+    }
+  }
+}