@aztec/slasher 0.87.2-nightly.20250524

package/dest/slasher_client.js

@@ -0,0 +1,309 @@
+import { ProposalAlreadyExecutedError, RollupContract } from '@aztec/ethereum';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { createLogger } from '@aztec/foundation/log';
+import { SlashFactoryAbi } from '@aztec/l1-artifacts';
+import { encodeFunctionData, getAddress, getContract } from 'viem';
+import { WANT_TO_SLASH_EVENT, bigIntToOffence } from './config.js';
+/**
+ * A Spartiate slasher client implementation
+ *
+ * Spartiates: a full citizen of the ancient polis of Sparta, member of an elite warrior class.
+ *
+ * How it works:
+ *
+ * The constructor accepts instances of Watcher classes that correspond to specific offences. These "watchers" do two things:
+ * - watch for their offence conditions and emit an event when they are detected
+ * - confirm/deny whether they agree with a proposed offence
+ *
+ * The SlasherClient class is responsible for:
+ * - listening for events from the watchers and creating a corresponding payload
+ * - listening for the payloads from L1 filtering them through the watchers
+ * - ordering the payloads and discarding stale payloads
+ * - presenting the payload that ought to be currently voted for
+ * - detecting when it wants to execute a round
+ * - executing a round
+ * - listening for the round to be executed
+ * - removing the executed round from the list of monitored payloads
+ *
+ * A few improvements:
+ * - TODO(#14421): Only vote on the proposal if it is possible to reach quorum, e.g., if 6 votes are needed and only 4 slots are left don't vote.
+ */ export class SlasherClient {
+    config;
+    slashFactoryContract;
+    slashingProposer;
+    l1TxUtils;
+    watchers;
+    dateProvider;
+    log;
+    monitoredPayloads;
+    unwatchCallbacks;
+    static async new(config, l1Contracts, l1TxUtils, watchers, dateProvider) {
+        if (!l1Contracts.rollupAddress) {
+            throw new Error('Cannot initialize SlasherClient without a rollup address');
+        }
+        if (!l1Contracts.slashFactoryAddress) {
+            throw new Error('Cannot initialize SlasherClient without a slashFactory address');
+        }
+        const rollup = new RollupContract(l1TxUtils.client, l1Contracts.rollupAddress);
+        const slashingProposer = await rollup.getSlashingProposer();
+        const slashFactoryContract = getContract({
+            address: getAddress(l1Contracts.slashFactoryAddress.toString()),
+            abi: SlashFactoryAbi,
+            client: l1TxUtils.client
+        });
+        return new SlasherClient(config, slashFactoryContract, slashingProposer, l1TxUtils, watchers, dateProvider);
+    }
+    constructor(config, slashFactoryContract, slashingProposer, l1TxUtils, watchers, dateProvider, log = createLogger('slasher')){
+        this.config = config;
+        this.slashFactoryContract = slashFactoryContract;
+        this.slashingProposer = slashingProposer;
+        this.l1TxUtils = l1TxUtils;
+        this.watchers = watchers;
+        this.dateProvider = dateProvider;
+        this.log = log;
+        this.monitoredPayloads = [];
+        this.unwatchCallbacks = [];
+    }
+    //////////////////// Public methods ////////////////////
+    async start() {
+        this.log.info('Starting Slasher client...');
+        // detect when new payloads are created
+        this.unwatchCallbacks.push(this.watchSlashFactoryEvents());
+        // detect when a proposal is executable
+        this.unwatchCallbacks.push(this.slashingProposer.listenToExecutableProposals(this.executeRoundIfAgree.bind(this)));
+        // detect when a proposal is executed
+        this.unwatchCallbacks.push(this.slashingProposer.listenToProposalExecuted(this.proposalExecuted.bind(this)));
+        // start each watcher, who will signal the slasher client when they want to slash
+        const wantToSlashCb = this.wantToSlash.bind(this);
+        for (const watcher of this.watchers){
+            if (watcher.start) {
+                await watcher.start();
+            }
+            watcher.on(WANT_TO_SLASH_EVENT, wantToSlashCb);
+            this.unwatchCallbacks.push(()=>watcher.removeListener(WANT_TO_SLASH_EVENT, wantToSlashCb));
+        }
+    }
+    /**
+   * 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.
+   */ async stop() {
+        this.log.debug('Stopping Slasher client...');
+        for (const cb of this.unwatchCallbacks){
+            cb();
+        }
+        for (const watcher of this.watchers){
+            if (watcher.stop) {
+                await watcher.stop();
+            }
+        }
+        this.log.info('Slasher client stopped.');
+    }
+    /**
+   * Get the payload to slash
+   *
+   * @param _slotNumber the current slot number (unused)
+   * @returns the payload to slash or undefined if there is no payload to slash
+   */ getSlashPayload(_slotNumber) {
+        if (this.config.slashOverridePayload && !this.config.slashOverridePayload.isZero()) {
+            this.log.info(`Overriding slash payload to: ${this.config.slashOverridePayload.toString()}`);
+            return Promise.resolve(this.config.slashOverridePayload);
+        }
+        const currentTimeSeconds = this.dateProvider.now() / 1000;
+        this.filterExpiredPayloads(currentTimeSeconds, this.config.slashPayloadTtlSeconds);
+        if (this.monitoredPayloads.length === 0) {
+            this.log.debug('No monitored payloads, returning undefined');
+            return Promise.resolve(undefined);
+        }
+        const selectedPayload = this.monitoredPayloads[0];
+        this.log.info('selectedPayload', selectedPayload);
+        return Promise.resolve(selectedPayload.payloadAddress);
+    }
+    /**
+   * Get the list of monitored payloads
+   *
+   * Useful for tests.
+   *
+   * @returns the list of monitored payloads
+   */ getMonitoredPayloads() {
+        return this.monitoredPayloads;
+    }
+    //////////////////// Private methods ////////////////////
+    /**
+   * This is called when a watcher emits WANT_TO_SLASH_EVENT.
+   *
+   * @param args - the arguments from the watcher, including the validators, amounts, and offenses
+   */ wantToSlash(args) {
+        // TODO(#14489): need to sort the payloads by attester address
+        this.log.info('Wants to slash', args);
+        this.l1TxUtils.sendAndMonitorTransaction({
+            to: this.slashFactoryContract.address,
+            data: encodeFunctionData({
+                abi: SlashFactoryAbi,
+                functionName: 'createSlashPayload',
+                args: [
+                    args.validators,
+                    args.amounts,
+                    args.offenses.map((offense)=>BigInt(offense))
+                ]
+            })
+        })// note, we don't need to monitor the logs here,
+        // it is handled by watchSlashFactoryEvents
+        .catch((e)=>{
+            this.log.error('Error slashing', e);
+        });
+    }
+    /**
+   * Watch for new payloads created by the slash factory
+   *
+   * Whenever a log has events, we iterate over them and convert them to MonitoredSlashPayloads
+   *
+   * We then add the payloads to the list of monitored payloads if we agree with them
+   *
+   * @returns a callback to remove the watcher
+   */ watchSlashFactoryEvents() {
+        return this.slashFactoryContract.watchEvent.SlashPayloadCreated({
+            onLogs: (logs)=>{
+                for (const payload of this.factoryEventsToMonitoredPayloads(logs)){
+                    this.log.info('Slash payload created', payload);
+                    this.addMonitoredPayload(payload).catch((e)=>{
+                        this.log.error('Error adding monitored payload', e);
+                    });
+                }
+                this.sortMonitoredPayloads();
+            }
+        });
+    }
+    /**
+   * Convert a list of factory events to an iterable of monitored payloads
+   *
+   * @param args
+   * @returns the list of monitored payloads
+   */ *factoryEventsToMonitoredPayloads(args) {
+        for (const event of args){
+            if (!event.args) {
+                continue;
+            }
+            const args = event.args;
+            if (!args.payloadAddress || !args.validators || !args.amounts || !args.offences) {
+                continue;
+            }
+            yield {
+                payloadAddress: EthAddress.fromString(args.payloadAddress),
+                validators: args.validators.map(EthAddress.fromString),
+                amounts: args.amounts,
+                offenses: args.offences.map((offense)=>bigIntToOffence(offense)),
+                observedAtSeconds: this.dateProvider.now() / 1000,
+                totalAmount: args.amounts.reduce((acc, amount)=>acc + amount, BigInt(0))
+            };
+        }
+    }
+    /**
+   * Add a payload to the list of monitored payloads if we agree with it
+   *
+   * @param payload
+   */ async addMonitoredPayload(payload) {
+        if (await this.doIAgreeWithPayload(payload)) {
+            this.log.info('Adding monitored payload', payload);
+            this.monitoredPayloads.push(payload);
+        } else {
+            this.log.info('Disagreeing with payload', payload);
+        }
+    }
+    /**
+   * Check if we agree with a payload
+   *
+   * We check each offense and validator pair against the watchers
+   *
+   * @param payload
+   * @returns true if any watcher agrees with the payload, false otherwise
+   */ async doIAgreeWithPayload(payload) {
+        // zip offenses and validators together
+        const offensesAndValidators = payload.offenses.map((offense, index)=>({
+                offense,
+                validator: payload.validators[index],
+                amount: payload.amounts[index]
+            }));
+        // check each offense
+        for (const offenseAndValidator of offensesAndValidators){
+            const watcherResponses = await Promise.all(this.watchers.map((watcher)=>watcher.shouldSlash(offenseAndValidator.validator.toString(), offenseAndValidator.amount, offenseAndValidator.offense)));
+            // if no watcher agrees, return false
+            if (watcherResponses.every((response)=>!response)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+   * Sort the monitored payloads by total amount in descending order
+   */ sortMonitoredPayloads() {
+        this.monitoredPayloads.sort((a, b)=>{
+            const diff = b.totalAmount - a.totalAmount;
+            return diff > 0n ? 1 : -1;
+        });
+    }
+    /**
+   * Filter out payloads that have expired
+   *
+   * @param currentTimeSeconds
+   * @param payloadTtlSeconds
+   */ filterExpiredPayloads(currentTimeSeconds, payloadTtlSeconds) {
+        this.monitoredPayloads = this.monitoredPayloads.filter((payload)=>{
+            return payload.observedAtSeconds + payloadTtlSeconds > currentTimeSeconds;
+        });
+    }
+    /**
+   * Execute a round if we agree with the proposal.
+   *
+   * Bound to the slashing proposer contract's listenToExecutableProposals method in the constructor.
+   *
+   * @param {proposal: `0x${string}`; round: bigint} param0
+   */ async executeRoundIfAgree({ proposal, round }) {
+        const payload = EthAddress.fromString(proposal);
+        if (!this.monitoredPayloads.find((p)=>p.payloadAddress.equals(payload))) {
+            this.log.debug('Round executable, but we disagree', {
+                proposal,
+                round
+            });
+            return;
+        }
+        const nextRound = round + 1n;
+        this.log.info(`Waiting for round ${nextRound} to be reached`);
+        await this.slashingProposer.waitForRound(nextRound, this.config.slashProposerRoundPollingIntervalSeconds);
+        this.log.info('Executing round', {
+            proposal,
+            round
+        });
+        await this.slashingProposer.executeRound(this.l1TxUtils, round).then(()=>{
+            this.log.info('Round executed', {
+                round
+            });
+        }).catch((err)=>{
+            if (err instanceof ProposalAlreadyExecutedError) {
+                this.log.debug('Round already executed', {
+                    round
+                });
+                return;
+            }
+            throw err;
+        });
+    }
+    /**
+   * Handler for when a proposal is executed.
+   *
+   * Removes the first matching payload from the list of monitored payloads.
+   *
+   * Bound to the slashing proposer contract's listenToProposalExecuted method in the constructor.
+   *
+   * @param {round: bigint; proposal: `0x${string}`} param0
+   */ proposalExecuted({ round, proposal }) {
+        this.log.info('Proposal executed', {
+            round,
+            proposal
+        });
+        const index = this.monitoredPayloads.findIndex((p)=>p.payloadAddress.equals(EthAddress.fromString(proposal)));
+        if (index === -1) {
+            return;
+        }
+        this.monitoredPayloads.splice(index, 1);
+    }
+}

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@aztec/slasher",
+  "version": "0.87.2-nightly.20250524",
+  "type": "module",
+  "exports": {
+    ".": "./dest/index.js",
+    "./config": "./dest/config.js"
+  },
+  "inherits": [
+    "../package.common.json"
+  ],
+  "scripts": {
+    "build": "yarn clean && tsc -b",
+    "build:dev": "tsc -b --watch",
+    "clean": "rm -rf ./dest .tsbuildinfo",
+    "bb": "node --no-warnings ./dest/bb/index.js",
+    "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}"
+  },
+  "jest": {
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.[cm]?js$": "$1"
+    },
+    "testRegex": "./src/.*\\.test\\.(js|mjs|ts)$",
+    "rootDir": "./src",
+    "transform": {
+      "^.+\\.tsx?$": [
+        "@swc/jest",
+        {
+          "jsc": {
+            "parser": {
+              "syntax": "typescript",
+              "decorators": true
+            },
+            "transform": {
+              "decoratorVersion": "2022-03"
+            }
+          }
+        }
+      ]
+    },
+    "extensionsToTreatAsEsm": [
+      ".ts"
+    ],
+    "reporters": [
+      "default"
+    ],
+    "testTimeout": 120000,
+    "setupFiles": [
+      "../../foundation/src/jest/setup.mjs"
+    ]
+  },
+  "dependencies": {
+    "@aztec/epoch-cache": "0.87.2-nightly.20250524",
+    "@aztec/ethereum": "0.87.2-nightly.20250524",
+    "@aztec/foundation": "0.87.2-nightly.20250524",
+    "@aztec/l1-artifacts": "0.87.2-nightly.20250524",
+    "@aztec/stdlib": "0.87.2-nightly.20250524",
+    "@aztec/telemetry-client": "0.87.2-nightly.20250524",
+    "source-map-support": "^0.5.21",
+    "tslib": "^2.4.0",
+    "viem": "2.23.7",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.5.0",
+    "@types/jest": "^29.5.0",
+    "@types/node": "^22.15.17",
+    "@types/source-map-support": "^0.5.10",
+    "jest": "^29.5.0",
+    "jest-mock-extended": "^3.0.3",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.3.3"
+  },
+  "files": [
+    "dest",
+    "src",
+    "!*.test.*"
+  ],
+  "types": "./dest/index.d.ts",
+  "engines": {
+    "node": ">=20.10"
+  }
+}

package/src/config.ts

@@ -0,0 +1,118 @@
+import type { ConfigMappingsType } from '@aztec/foundation/config';
+import { bigintConfigHelper, booleanConfigHelper, numberConfigHelper } from '@aztec/foundation/config';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import type { TypedEventEmitter } from '@aztec/foundation/types';
+
+export enum Offence {
+  UNKNOWN = 0,
+  EPOCH_PRUNE = 1,
+  INACTIVITY = 2,
+}
+
+export const OffenceToBigInt: Record<Offence, bigint> = {
+  [Offence.UNKNOWN]: 0n,
+  [Offence.EPOCH_PRUNE]: 1n,
+  [Offence.INACTIVITY]: 2n,
+};
+
+export function bigIntToOffence(offense: bigint): Offence {
+  switch (offense) {
+    case 0n:
+      return Offence.UNKNOWN;
+    case 1n:
+      return Offence.EPOCH_PRUNE;
+    case 2n:
+      return Offence.INACTIVITY;
+    default:
+      throw new Error(`Unknown offence: ${offense}`);
+  }
+}
+
+export const WANT_TO_SLASH_EVENT = 'wantToSlash' as const;
+
+export interface WantToSlashArgs {
+  validators: `0x${string}`[] | readonly `0x${string}`[];
+  amounts: bigint[];
+  offenses: Offence[];
+}
+
+// Event map for specific, known events of a watcher
+export interface WatcherEventMap {
+  [WANT_TO_SLASH_EVENT]: (args: WantToSlashArgs) => void;
+}
+
+export type WatcherEmitter = TypedEventEmitter<WatcherEventMap>;
+
+export type CheckSlashFn = (validator: `0x${string}`, amount: bigint, offense: Offence) => Promise<boolean>;
+
+export type Watcher = WatcherEmitter & {
+  shouldSlash: CheckSlashFn;
+  start?: () => Promise<void>;
+  stop?: () => Promise<void>;
+};
+
+export interface SlasherConfig {
+  // New configurations based on design doc
+  slashOverridePayload?: EthAddress;
+  slashPayloadTtlSeconds: number; // TTL for payloads, in seconds
+  slashPruneCreate: boolean;
+  slashPrunePenalty: bigint;
+  slashPruneSignal: boolean;
+  slashInactivityCreateTargetPercentage: number; // 0-1, 0.9 means 90%
+  slashInactivityCreatePenalty: bigint;
+  slashInactivitySignalTargetPercentage: number; // 0-1, 0.6 means 60%
+  slashProposerRoundPollingIntervalSeconds: number;
+  // Consider adding: slashInactivityCreateEnabled: boolean;
+}
+
+export const DefaultSlasherConfig: SlasherConfig = {
+  slashInactivityCreatePenalty: 1n,
+  slashInactivityCreateTargetPercentage: 0.9,
+  slashInactivitySignalTargetPercentage: 0.6,
+  slashPayloadTtlSeconds: 60 * 60 * 24, // 1 day
+  slashPruneCreate: false,
+  slashPrunePenalty: 1n,
+  slashPruneSignal: true,
+  slashOverridePayload: undefined,
+  slashProposerRoundPollingIntervalSeconds: 12,
+};
+
+export const slasherConfigMappings: ConfigMappingsType<SlasherConfig> = {
+  slashOverridePayload: {
+    description: 'An Ethereum address for a slash payload to vote for unconditionally.',
+    parseEnv: (val: string) => (val ? EthAddress.fromString(val) : undefined),
+    defaultValue: DefaultSlasherConfig.slashOverridePayload,
+  },
+  slashPayloadTtlSeconds: {
+    description: 'Time-to-live for slash payloads in seconds.',
+    ...numberConfigHelper(DefaultSlasherConfig.slashPayloadTtlSeconds),
+  },
+  slashPruneCreate: {
+    description: 'Enable creation of slash payloads for pruned epochs.',
+    ...booleanConfigHelper(DefaultSlasherConfig.slashPruneCreate),
+  },
+  slashPrunePenalty: {
+    description: 'Penalty amount for slashing validators of a pruned epoch.',
+    ...bigintConfigHelper(DefaultSlasherConfig.slashPrunePenalty),
+  },
+  slashPruneSignal: {
+    description: 'Enable voting for slash payloads for pruned epochs.',
+    ...booleanConfigHelper(DefaultSlasherConfig.slashPruneSignal),
+  },
+  slashInactivityCreateTargetPercentage: {
+    description: 'Missed attestation percentage to trigger creation of inactivity slash payload (0-100).',
+    ...numberConfigHelper(DefaultSlasherConfig.slashInactivityCreateTargetPercentage),
+  },
+  slashInactivityCreatePenalty: {
+    description: 'Penalty amount for slashing an inactive validator.',
+    ...bigintConfigHelper(DefaultSlasherConfig.slashInactivityCreatePenalty),
+  },
+  slashInactivitySignalTargetPercentage: {
+    description: 'Missed attestation percentage to trigger voting for an inactivity slash payload (0-100).',
+    ...numberConfigHelper(DefaultSlasherConfig.slashInactivitySignalTargetPercentage),
+  },
+  slashProposerRoundPollingIntervalSeconds: {
+    description: 'Polling interval for slashing proposer round in seconds.',
+    ...numberConfigHelper(DefaultSlasherConfig.slashProposerRoundPollingIntervalSeconds),
+  },
+};

package/src/epoch_prune_watcher.ts

@@ -0,0 +1,94 @@
+import { EpochCache } from '@aztec/epoch-cache';
+import { type Logger, createLogger } from '@aztec/foundation/log';
+import { type L2BlockSourceEvent, type L2BlockSourceEventEmitter, L2BlockSourceEvents } from '@aztec/stdlib/block';
+
+import EventEmitter from 'node:events';
+import type { Hex } from 'viem';
+
+import { Offence, WANT_TO_SLASH_EVENT, type WantToSlashArgs, type Watcher, type WatcherEmitter } from './config.js';
+
+export class EpochPruneWatcher extends (EventEmitter as new () => WatcherEmitter) implements Watcher {
+  private log: Logger = createLogger('epoch-prune-watcher');
+
+  // Keep track of pruned epochs we've seen to their committee
+  private prunedEpochs: Map<bigint, `0x${string}`[]> = new Map();
+  // Only keep track of the last N pruned epochs
+  private maxPrunedEpochs = 100;
+
+  constructor(
+    private l2BlockSource: L2BlockSourceEventEmitter,
+    private epochCache: EpochCache,
+    private penalty: bigint,
+  ) {
+    super();
+    this.log.info('EpochPruneWatcher initialized');
+  }
+
+  public start() {
+    this.l2BlockSource.on(L2BlockSourceEvents.L2PruneDetected, this.handlePruneL2Blocks.bind(this));
+    return Promise.resolve();
+  }
+
+  public stop() {
+    this.l2BlockSource.removeListener(L2BlockSourceEvents.L2PruneDetected, this.handlePruneL2Blocks.bind(this));
+    return Promise.resolve();
+  }
+
+  // TODO(#14407), TODO(#14408)
+  // We should only be slashing due to prune if:
+  // - the data was not available (#14407)
+  // - OR the data was available and the epoch could have been proven (#14408)
+  private handlePruneL2Blocks(event: L2BlockSourceEvent): void {
+    const { epochNumber } = event;
+    this.log.info(`Detected chain prune. Attempting to create slash for epoch ${epochNumber}`, event);
+
+    this.getValidatorsForEpoch(epochNumber)
+      .then(validators => {
+        const args = this.validatorsToSlashingArgs(validators);
+
+        if (args) {
+          this.addToPrunedEpochs(epochNumber, validators);
+          this.emit(WANT_TO_SLASH_EVENT, args);
+        }
+      })
+      .catch(error => {
+        this.log.error('Error getting validators for epoch', error);
+      });
+  }
+
+  private addToPrunedEpochs(epochNumber: bigint, validators: Hex[]) {
+    this.prunedEpochs.set(epochNumber, validators);
+    if (this.prunedEpochs.size > this.maxPrunedEpochs) {
+      this.prunedEpochs.delete(this.prunedEpochs.keys().next().value!);
+    }
+  }
+
+  private async getValidatorsForEpoch(epochNumber: bigint): Promise<`0x${string}`[]> {
+    const { committee } = await this.epochCache.getCommitteeForEpoch(epochNumber);
+    return committee.map(v => v.toString());
+  }
+
+  private validatorsToSlashingArgs(validators: `0x${string}`[]): WantToSlashArgs | undefined {
+    if (validators.length === 0) {
+      this.log.debug('No validators found for epoch, skipping slash creation.');
+      return undefined;
+    }
+    const amounts = Array(validators.length).fill(this.penalty);
+    const offenses = Array(validators.length).fill(Offence.EPOCH_PRUNE);
+    return { validators, amounts, offenses };
+  }
+
+  private wantToSlashForEpoch(validator: `0x${string}`, amount: bigint, epochNumber: bigint): boolean {
+    return this.prunedEpochs.get(epochNumber)?.includes(validator) ?? false;
+  }
+
+  public shouldSlash(validator: `0x${string}`, amount: bigint, _offense: Offence): Promise<boolean> {
+    for (const epoch of this.prunedEpochs.keys()) {
+      if (this.wantToSlashForEpoch(validator, amount, epoch)) {
+        return Promise.resolve(true);
+      }
+    }
+
+    return Promise.resolve(false);
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './config.js';
+export * from './epoch_prune_watcher.js';
+export * from './slasher_client.js';