@aztec/slasher 0.0.1-commit.001888fc

package/src/slasher_client_facade.ts

@@ -0,0 +1,103 @@
+import { EpochCache } from '@aztec/epoch-cache';
+import { RollupContract } from '@aztec/ethereum/contracts';
+import type { ViemClient } from '@aztec/ethereum/types';
+import type { SlotNumber } from '@aztec/foundation/branded-types';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { createLogger } from '@aztec/foundation/log';
+import { DateProvider } from '@aztec/foundation/timer';
+import { AztecLMDBStoreV2 } from '@aztec/kv-store/lmdb-v2';
+import type { SlasherConfig } from '@aztec/stdlib/interfaces/server';
+import type { DataStoreConfig } from '@aztec/stdlib/kv-store';
+import type { Offense, ProposerSlashAction, SlashPayloadRound } from '@aztec/stdlib/slashing';
+
+import { createSlasherImplementation } from './factory/create_implementation.js';
+import type { SlasherClientInterface } from './slasher_client_interface.js';
+import type { Watcher } from './watcher.js';
+
+/**
+ * Facade for the Slasher client. This class forwards all requests to the actual Slasher client implementation.
+ * This class also monitors via the rollup contract when the underlying slasher proposer contract changes, and when it
+ * does, it stops the current slasher client, recreates a new one with the new contract address, and starts it again.
+ */
+export class SlasherClientFacade implements SlasherClientInterface {
+  private client: SlasherClientInterface | undefined;
+  private unwatch: (() => void) | undefined;
+
+  constructor(
+    private config: SlasherConfig & DataStoreConfig & { ethereumSlotDuration: number },
+    private rollup: RollupContract,
+    private l1Client: ViemClient,
+    private slashFactoryAddress: EthAddress | undefined,
+    private watchers: Watcher[],
+    private epochCache: EpochCache,
+    private dateProvider: DateProvider,
+    private kvStore: AztecLMDBStoreV2,
+    private rollupRegisteredAtL2Slot: SlotNumber,
+    private logger = createLogger('slasher'),
+  ) {}
+
+  public async start(): Promise<void> {
+    this.client = await this.createSlasherClient();
+    await this.client?.start();
+
+    this.unwatch = this.rollup.listenToSlasherChanged(() => {
+      void this.handleSlasherChange().catch(error => {
+        this.logger.error('Error handling slasher change', error);
+      });
+    });
+  }
+
+  public async stop(): Promise<void> {
+    await this.client?.stop();
+    this.unwatch?.();
+    this.unwatch = undefined;
+  }
+
+  public getConfig(): SlasherConfig {
+    return this.config;
+  }
+
+  public updateConfig(config: Partial<SlasherConfig>): void {
+    this.config = { ...this.config, ...config };
+    this.client?.updateConfig(config);
+    this.watchers.forEach(watcher => watcher.updateConfig?.(config));
+  }
+
+  public getSlashPayloads(): Promise<SlashPayloadRound[]> {
+    return this.client?.getSlashPayloads() ?? Promise.reject(new Error('Slasher client not initialized'));
+  }
+
+  public gatherOffensesForRound(round?: bigint): Promise<Offense[]> {
+    return this.client?.gatherOffensesForRound(round) ?? Promise.reject(new Error('Slasher client not initialized'));
+  }
+
+  public getPendingOffenses(): Promise<Offense[]> {
+    return this.client?.getPendingOffenses() ?? Promise.reject(new Error('Slasher client not initialized'));
+  }
+
+  public getProposerActions(slotNumber: SlotNumber): Promise<ProposerSlashAction[]> {
+    return this.client?.getProposerActions(slotNumber) ?? Promise.reject(new Error('Slasher client not initialized'));
+  }
+
+  private createSlasherClient() {
+    return createSlasherImplementation(
+      this.config,
+      this.rollup,
+      this.l1Client,
+      this.slashFactoryAddress,
+      this.watchers,
+      this.epochCache,
+      this.dateProvider,
+      this.kvStore,
+      this.rollupRegisteredAtL2Slot,
+      this.logger,
+    );
+  }
+
+  private async handleSlasherChange() {
+    this.logger.warn('Slasher contract changed, recreating slasher client');
+    await this.client?.stop();
+    this.client = await this.createSlasherClient();
+    await this.client?.start();
+  }
+}

package/src/slasher_client_interface.ts

@@ -0,0 +1,46 @@
+import type { SlotNumber } from '@aztec/foundation/branded-types';
+import type { SlasherConfig } from '@aztec/stdlib/interfaces/server';
+import type { Offense, ProposerSlashAction, SlashPayloadRound } from '@aztec/stdlib/slashing';
+
+/**
+ * Common interface for slasher clients used by the Aztec node.
+ * Both Empire and Consensus slasher clients implement this interface.
+ */
+export interface SlasherClientInterface {
+  /** Start the slasher client */
+  start(): Promise<void>;
+
+  /** Stop the slasher client */
+  stop(): Promise<void>;
+
+  /**
+   * Get slash payloads for the Empire model.
+   * The Consensus model should throw an error when this is called.
+   */
+  getSlashPayloads(): Promise<SlashPayloadRound[]>;
+
+  /**
+   * Gather offenses for a given round, defaults to current.
+   * Used by both Empire and Consensus models.
+   */
+  gatherOffensesForRound(round?: bigint): Promise<Offense[]>;
+
+  /** Returns all pending offenses */
+  getPendingOffenses(): Promise<Offense[]>;
+
+  /**
+   * Update the configuration.
+   * Used by both Empire and Consensus models.
+   */
+  updateConfig(config: Partial<SlasherConfig>): void;
+
+  /**
+   * Get the actions the proposer should take for slashing.
+   * @param slotNumber - The current slot number
+   * @returns The actions to take
+   */
+  getProposerActions(slotNumber: SlotNumber): Promise<ProposerSlashAction[]>;
+
+  /** Returns the current config */
+  getConfig(): SlasherConfig;
+}

package/src/stores/offenses_store.ts

@@ -0,0 +1,147 @@
+import { createLogger } from '@aztec/aztec.js/log';
+import type { AztecAsyncKVStore, AztecAsyncMap, AztecAsyncMultiMap, AztecAsyncSet } from '@aztec/kv-store';
+import {
+  type Offense,
+  type OffenseIdentifier,
+  deserializeOffense,
+  getRoundForOffense,
+  serializeOffense,
+} from '@aztec/stdlib/slashing';
+
+export const SCHEMA_VERSION = 1;
+
+export class SlasherOffensesStore {
+  /** Map from offense key to offense data */
+  private offenses: AztecAsyncMap<string, Buffer>;
+
+  /** Map from offense key to whether the offense has been executed (only used for empire based slashing) */
+  private offensesSlashed: AztecAsyncSet<string>;
+
+  /** Multimap from round to offense keys (only used for consensus based slashing) */
+  private roundsOffenses: AztecAsyncMultiMap<string, string>;
+
+  private log = createLogger('slasher:store:offenses');
+
+  constructor(
+    private kvStore: AztecAsyncKVStore,
+    private settings: {
+      slashingRoundSize: number;
+      epochDuration: number;
+      slashOffenseExpirationRounds?: number;
+    },
+  ) {
+    this.offenses = kvStore.openMap('offenses');
+    this.roundsOffenses = kvStore.openMultiMap('rounds-offenses');
+    this.offensesSlashed = kvStore.openSet('offenses-slashed');
+  }
+
+  /** Returns all offenses not marked as slashed */
+  public async getPendingOffenses(): Promise<Offense[]> {
+    const offenses: Offense[] = [];
+    for await (const [key, buffer] of this.offenses.entriesAsync()) {
+      if (await this.offensesSlashed.hasAsync(key)) {
+        continue; // Skip executed offenses
+      }
+      const offense = deserializeOffense(buffer);
+      offenses.push(offense);
+    }
+    return offenses;
+  }
+
+  /** Returns all offenses tracked for the given round */
+  public async getOffensesForRound(round: bigint): Promise<Offense[]> {
+    const offenses: Offense[] = [];
+    for await (const key of this.roundsOffenses.getValuesAsync(this.getRoundKey(round))) {
+      const buffer = await this.offenses.getAsync(key);
+      if (buffer) {
+        const offense = deserializeOffense(buffer);
+        offenses.push(offense);
+      }
+    }
+    return offenses;
+  }
+
+  /** Returns whether an offense is pending (ie not marked as slashed) */
+  public async hasPendingOffense(offense: OffenseIdentifier): Promise<boolean> {
+    const key = this.getOffenseKey(offense);
+    return (await this.offenses.getAsync(key)) !== undefined && !(await this.offensesSlashed.hasAsync(key));
+  }
+
+  /** Returns whether we have seen this offense */
+  public async hasOffense(offense: OffenseIdentifier): Promise<boolean> {
+    const key = this.getOffenseKey(offense);
+    return (await this.offenses.getAsync(key)) !== undefined;
+  }
+
+  /** Adds a new offense (defaults to pending, but will be slashed if markAsSlashed had been called for it) */
+  public async addPendingOffense(offense: Offense): Promise<void> {
+    const key = this.getOffenseKey(offense);
+    const round = getRoundForOffense(offense, this.settings);
+    await this.kvStore.transactionAsync(async () => {
+      await this.offenses.set(key, serializeOffense(offense));
+      await this.roundsOffenses.set(this.getRoundKey(round), key);
+    });
+    this.log.trace(`Adding pending offense ${key} for round ${round}`);
+  }
+
+  /** Marks the given offenses as slashed (regardless of whether they are known or not)  */
+  public async markAsSlashed(offenses: OffenseIdentifier[]): Promise<void> {
+    await this.kvStore.transactionAsync(async () => {
+      for (const offense of offenses) {
+        const key = this.getOffenseKey(offense);
+        await this.offensesSlashed.add(key);
+      }
+    });
+  }
+
+  /** Prunes all offenses expired from the store */
+  public async clearExpiredOffenses(currentRound: bigint): Promise<number> {
+    const expirationRounds = this.settings.slashOffenseExpirationRounds ?? 0;
+    if (expirationRounds <= 0) {
+      return 0; // No expiration configured
+    }
+
+    const expiredBefore = currentRound - BigInt(expirationRounds);
+    if (expiredBefore < 0) {
+      return 0; // Not enough rounds have passed to expire anything
+    }
+
+    // Collect expired offenses and rounds
+    const expiredRoundKeys = new Set<string>();
+    const expiredOffenseKeys = new Set<string>();
+    for await (const [roundKey, offenseKey] of this.roundsOffenses.entriesAsync({
+      end: this.getRoundKey(expiredBefore),
+    })) {
+      expiredOffenseKeys.add(offenseKey);
+      expiredRoundKeys.add(roundKey);
+    }
+
+    if (expiredOffenseKeys.size === 0 && expiredRoundKeys.size === 0) {
+      return 0; // Nothing to clean up
+    }
+
+    // Remove expired stuff in a transaction
+    await this.kvStore.transactionAsync(async () => {
+      for (const key of expiredOffenseKeys) {
+        this.log.trace(`Deleting offense ${key}`);
+        await this.offenses.delete(key);
+        await this.offensesSlashed.delete(key);
+      }
+      for (const roundKey of expiredRoundKeys) {
+        this.log.trace(`Deleting round info for ${roundKey}`);
+        await this.roundsOffenses.delete(roundKey);
+      }
+    });
+
+    return expiredOffenseKeys.size;
+  }
+
+  /** Generate a unique key for an offense */
+  private getOffenseKey(offense: OffenseIdentifier): string {
+    return `${offense.validator.toString()}:${offense.offenseType}:${offense.epochOrSlot}`;
+  }
+
+  private getRoundKey(round: bigint): string {
+    return round.toString().padStart(16, '0');
+  }
+}

package/src/stores/payloads_store.ts

@@ -0,0 +1,149 @@
+import { EthAddress } from '@aztec/foundation/eth-address';
+import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
+import {
+  type SlashPayload,
+  type SlashPayloadRound,
+  deserializeSlashPayload,
+  serializeSlashPayload,
+} from '@aztec/stdlib/slashing';
+
+export class SlasherPayloadsStore {
+  /** Map from payload address to payload data */
+  private payloads: AztecAsyncMap<string, Buffer>;
+
+  /** Map from `round:payload` to votes */
+  private roundPayloadVotes: AztecAsyncMap<string, bigint>;
+
+  constructor(
+    private kvStore: AztecAsyncKVStore,
+    private settings?: {
+      slashingPayloadLifetimeInRounds?: number;
+    },
+  ) {
+    this.payloads = kvStore.openMap('slash-payloads');
+    this.roundPayloadVotes = kvStore.openMap('round-payload-votes');
+  }
+
+  public async getPayloadsForRound(round: bigint): Promise<SlashPayloadRound[]> {
+    const payloads: SlashPayloadRound[] = [];
+    const votes = await this.getVotesForRound(round);
+    for (const [address, votesCount] of votes) {
+      const payload = await this.getPayload(address);
+      if (payload) {
+        payloads.push({ ...payload, votes: votesCount, round });
+      }
+    }
+    return payloads;
+  }
+
+  public async getPayloadAtRound(payloadAddress: EthAddress, round: bigint): Promise<SlashPayloadRound | undefined> {
+    const address = payloadAddress.toString();
+    const buffer = await this.payloads.getAsync(address);
+    if (!buffer) {
+      return undefined;
+    }
+
+    const data = deserializeSlashPayload(buffer);
+    const votes = (await this.roundPayloadVotes.getAsync(this.getPayloadVotesKey(round, address))) ?? 0n;
+
+    return { ...data, votes, round };
+  }
+
+  private async getVotesForRound(round: bigint): Promise<[string, bigint][]> {
+    const votes: [string, bigint][] = [];
+    for await (const [fullKey, roundVotes] of this.roundPayloadVotes.entriesAsync(
+      this.getPayloadVotesKeyRangeForRound(round),
+    )) {
+      // Extract just the address part from the key (remove "round:" prefix)
+      const address = fullKey.split(':')[1];
+      votes.push([address, roundVotes]);
+    }
+    return votes;
+  }
+
+  private getRoundKey(round: bigint): string {
+    return round.toString().padStart(16, '0');
+  }
+
+  private getPayloadVotesKey(round: bigint, payloadAddress: EthAddress | string): string {
+    return `${this.getRoundKey(round)}:${payloadAddress.toString()}`;
+  }
+
+  private getPayloadVotesKeyRangeForRound(round: bigint): { start: string; end: string } {
+    const start = `${this.getRoundKey(round)}:`;
+    const end = `${this.getRoundKey(round)}:Z`; // 'Z' sorts after any hex address, 0x-prefixed or not
+    return { start, end };
+  }
+
+  /**
+   * Purge vote payload data for expired rounds. Does not delete actual payload data.
+   */
+  public async clearExpiredPayloads(currentRound: bigint): Promise<void> {
+    const lifetimeInRounds = this.settings?.slashingPayloadLifetimeInRounds ?? 0;
+    if (lifetimeInRounds <= 0) {
+      return; // No lifetime configured
+    }
+
+    const expiredBefore = currentRound - BigInt(lifetimeInRounds);
+    if (expiredBefore < 0) {
+      return; // Not enough rounds have passed to expire anything
+    }
+
+    // Collect expired payload votes by scanning round-payload keys
+    const expiredPayloads: string[] = [];
+    const expiredVoteKeys: string[] = [];
+
+    for await (const key of this.roundPayloadVotes.keysAsync({
+      end: `${this.getRoundKey(expiredBefore)}:Z`,
+    })) {
+      const [roundStr, payloadAddress] = key.split(':');
+      if (BigInt(roundStr) <= expiredBefore) {
+        expiredVoteKeys.push(key);
+        expiredPayloads.push(payloadAddress);
+      }
+    }
+
+    if (expiredVoteKeys.length === 0) {
+      return; // No expired payloads to clean up
+    }
+
+    // Remove expired payload vote records
+    // Note that we do not delete payload data since these could be repurposed in future votes
+    await this.kvStore.transactionAsync(async () => {
+      for (const key of expiredVoteKeys) {
+        await this.roundPayloadVotes.delete(key);
+      }
+    });
+  }
+
+  public async incrementPayloadVotes(payloadAddress: EthAddress, round: bigint): Promise<bigint> {
+    const key = this.getPayloadVotesKey(round, payloadAddress);
+    let newVotes: bigint;
+    await this.kvStore.transactionAsync(async () => {
+      const currentVotes = (await this.roundPayloadVotes.getAsync(key)) || 0n;
+      newVotes = currentVotes + 1n;
+      await this.roundPayloadVotes.set(key, newVotes);
+    });
+    return newVotes!;
+  }
+
+  public async addPayload(payload: SlashPayloadRound): Promise<void> {
+    const address = payload.address.toString();
+
+    await this.kvStore.transactionAsync(async () => {
+      await this.payloads.set(address, serializeSlashPayload(payload));
+      await this.roundPayloadVotes.set(this.getPayloadVotesKey(payload.round, address), payload.votes);
+    });
+  }
+
+  public async getPayload(payloadAddress: EthAddress | string): Promise<SlashPayload | undefined> {
+    const address = payloadAddress.toString();
+    const buffer = await this.payloads.getAsync(address);
+    return buffer ? deserializeSlashPayload(buffer) : undefined;
+  }
+
+  public async hasPayload(payload: EthAddress): Promise<boolean> {
+    const address = payload.toString();
+    return (await this.payloads.getAsync(address)) !== undefined;
+  }
+}

package/src/stores/schema_version.ts

@@ -0,0 +1 @@
+export const SCHEMA_VERSION = 1;