@aztec/slasher 2.0.0-nightly.20250821 → 2.0.0-nightly.20250823

package/README.md

@@ -1,5 +1,146 @@
 # Slasher
 
-We slashin.
+## Overview
 
-See [slasher_client.ts](./src/slasher_client.ts) for more details.
+The slasher module implements validator slashing for the Aztec network. Slashing punishes validators who misbehave or are inactive by reducing their stake. This mechanism ensures network security and liveness.
+
+## Usage
+
+The slasher is integrated into the Aztec node and activates when:
+1. The node is configured as a validator
+2. The validator is selected as proposer for a slot
+3. Slashable offenses have been detected
+
+No manual intervention is required for normal operation. The slasher client handles:
+- Monitoring for offenses
+- Generating appropriate slash actions
+- Coordinating with the SequencerPublisher for L1 execution
+
+## Slashing Models
+
+The system supports two slashing models:
+
+### Tally Model
+
+_This is the model currently in use._
+
+The tally model uses consensus-based voting where proposers vote on individual validator offenses. Time is divided into rounds, and during each round, proposers submit votes indicating which validators should be slashed. Votes are encoded as bytes where each validator's vote is represented by 2 bits indicating the slash amount (0-3 slash units) for each validator. The L1 contract tallies votes and slashes validators that reach quorum.
+
+Key characteristics:
+- Proposers vote directly on validator offenses
+- Uses a slash offset to vote on validators from past rounds (e.g., round N votes on round N-2)
+- Requires quorum to execute slashing
+- L1 contract determines which offenses reach consensus
+- Execution happens after a delay period for review
+
+### Empire Model
+
+_This model was developed during an earlier iteration and later modified, but never tested in a real network. It remains in the code in case we decide to switch from the tally model in the future._
+
+The empire model piggybacks on the empire governance system and uses fixed slash payloads that are created and voted on. Proposers aggregate pending offenses and create payloads containing multiple offenses, or vote for existing payloads. The payload with the highest score (based on total offenses, votes received, and round progress) gets executed.
+
+Key characteristics:
+- Fixed payloads containing multiple offenses
+- Payload scoring system for selection
+- Requires agreement on payload contents (main reason why it was dropped in favor of the Tally model)
+
+## Architecture
+
+### Core Components
+
+#### SlasherClientInterface
+Common interface implemented by both tally and empire clients. Provides methods for:
+- `getProposerActions()`: Returns actions for the current proposer
+- `gatherOffensesForRound()`: Collects offenses for a specific round
+
+#### SlashOffensesCollector
+Collects slashable offenses from watchers and stores them in the offenses store. Features:
+- Subscribes to `WANT_TO_SLASH_EVENT` from watchers
+- Manages offense lifecycle and expiration
+
+#### SlasherOffensesStore
+Persistent storage for offenses. Tracks:
+- Pending offenses awaiting slashing
+- Executed offenses to prevent double slashing
+- Round-based offense organization
+
+#### SlashRoundMonitor
+Monitors slashing rounds and triggers actions on round transitions:
+- Tracks current round based on L2 slots
+- Emits events when rounds change
+
+#### ProposerSlashAction
+Actions returned by the slasher client to the SequencerPublisher:
+- `vote-offenses`: Vote on validator offenses (tally model)
+- `execute-slash`: Execute slashing for a round that reached quorum (tally model)
+- `create-empire-payload`: Create a new slash payload (empire model)
+- `vote-empire-payload`: Vote for an existing payload (empire model)
+- `execute-empire-payload`: Execute a payload with sufficient votes (empire model)
+
+### Integration Flow
+
+1. **Offense Detection**: Watchers monitor the network and emit `WANT_TO_SLASH_EVENT` when they detect violations
+2. **Offense Collection**: SlashOffensesCollector receives events and stores offenses in SlasherOffensesStore
+3. **Action Generation**: When a validator is proposer, the slasher client generates ProposerSlashActions
+4. **Action Execution**: SequencerPublisher receives actions and executes them on L1
+5. **Round Monitoring**: SlashRoundMonitor tracks rounds and triggers execution when conditions are met
+
+## Slashable Offenses
+
+### DATA_WITHHOLDING
+**Description**: The data required for proving an epoch was not made publicly available.  
+**Detection**: EpochPruneWatcher detects when an epoch cannot be proven due to missing data.  
+**Target**: Committee members of the affected epoch.  
+**Time Unit**: Epoch-based offense.
+
+### VALID_EPOCH_PRUNED
+**Description**: An epoch was not successfully proven within the proof submission window.  
+**Detection**: EpochPruneWatcher monitors epochs that expire without valid proofs.  
+**Target**: Committee members of the unpruned epoch.  
+**Time Unit**: Epoch-based offense.
+
+### INACTIVITY
+**Description**: A proposer failed to attest or propose blocks during their assigned slots.  
+**Detection**: Sentinel tracks validator performance and identifies validators who miss attestations beyond threshold.  
+**Target**: Individual inactive validator.  
+**Time Unit**: Epoch-based offense.
+
+### BROADCASTED_INVALID_BLOCK_PROPOSAL
+**Description**: A proposer broadcast an invalid block proposal over the p2p network.  
+**Detection**: Validators detect invalid proposals during attestation validation.  
+**Target**: Proposer who broadcast the invalid block.  
+**Time Unit**: Slot-based offense.  
+**Note**: Currently not actively monitored in production.
+
+### PROPOSED_INSUFFICIENT_ATTESTATIONS
+**Description**: A proposer submitted a block to L1 without sufficient committee attestations.  
+**Detection**: AttestationsBlockWatcher checks L1 blocks for attestation count.  
+**Target**: Block proposer.  
+**Time Unit**: Slot-based offense.
+
+### PROPOSED_INCORRECT_ATTESTATIONS
+**Description**: A proposer submitted a block to L1 with signatures from non-committee members.  
+**Detection**: AttestationsBlockWatcher validates attestation signatures against committee membership.  
+**Target**: Block proposer.  
+**Time Unit**: Slot-based offense.
+
+### ATTESTED_DESCENDANT_OF_INVALID
+**Description**: A committee member attested to a block built on top of an invalid ancestor.  
+**Detection**: AttestationsBlockWatcher tracks invalid blocks and their descendants.  
+**Target**: Committee members who attested to the descendant block.  
+**Time Unit**: Slot-based offense.
+
+## Configuration
+
+### Slasher Configuration
+- `slashGracePeriodL2Slots`: Number of initial L2 slots where slashing is disabled
+- `slashMaxPayloadSize`: Maximum size of slash payloads (empire model)
+- `slashingRoundSize`: Number of slots per slashing round
+- `slashingQuorumSize`: Votes required to slash (tally model)
+- `slashingOffsetInRounds`: How many rounds to look back for offenses (tally model)
+- `slashingExecutionDelayInRounds`: Rounds to wait before execution
+- `slashingLifetimeInRounds`: Maximum age of executable rounds
+- `slashingUnit`: Base slashing amount per unit
+
+### Environment Variables
+- `SLASHER_CLIENT_TYPE`: Select between 'tally' or 'empire' (default: 'tally')

package/dest/config.d.ts

@@ -1,25 +1,6 @@
 import type { ConfigMappingsType } from '@aztec/foundation/config';
-import { EthAddress } from '@aztec/foundation/eth-address';
-import type { TypedEventEmitter } from '@aztec/foundation/types';
 import type { SlasherConfig } from '@aztec/stdlib/interfaces/server';
-import { Offense } from '@aztec/stdlib/slashing';
 export type { SlasherConfig };
-export declare const WANT_TO_SLASH_EVENT: "wantToSlash";
-export interface WantToSlashArgs {
-    validator: EthAddress;
-    amount: bigint;
-    offense: Offense;
-}
-export interface WatcherEventMap {
-    [WANT_TO_SLASH_EVENT]: (args: WantToSlashArgs[]) => void;
-}
-export type WatcherEmitter = TypedEventEmitter<WatcherEventMap>;
-export type CheckSlashFn = (args: WantToSlashArgs) => Promise<boolean>;
-export type Watcher = WatcherEmitter & {
-    shouldSlash: CheckSlashFn;
-    start?: () => Promise<void>;
-    stop?: () => Promise<void>;
-};
 export declare const DefaultSlasherConfig: SlasherConfig;
 export declare const slasherConfigMappings: ConfigMappingsType<SlasherConfig>;
 //# sourceMappingURL=config.d.ts.map

package/dest/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AASnE,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEjD,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B,eAAO,MAAM,mBAAmB,EAAG,aAAsB,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,UAAU,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB;AAGD,MAAM,WAAW,eAAe;IAC9B,CAAC,mBAAmB,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,IAAI,CAAC;CAC1D;AAED,MAAM,MAAM,cAAc,GAAG,iBAAiB,CAAC,eAAe,CAAC,CAAC;AAEhE,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,eAAe,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEvE,MAAM,MAAM,OAAO,GAAG,cAAc,GAAG;IACrC,WAAW,EAAE,YAAY,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,aAoBlC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,kBAAkB,CAAC,aAAa,CAyGnE,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAQnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAErE,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B,eAAO,MAAM,oBAAoB,EAAE,aAwBlC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,kBAAkB,CAAC,aAAa,CA4HnE,CAAC"}

package/dest/config.js

@@ -1,16 +1,14 @@
-import { NULL_KEY } from '@aztec/ethereum';
-import { SecretValue, bigintConfigHelper, booleanConfigHelper, floatConfigHelper, numberConfigHelper, secretValueConfigHelper } from '@aztec/foundation/config';
+import { bigintConfigHelper, booleanConfigHelper, floatConfigHelper, numberConfigHelper } from '@aztec/foundation/config';
 import { EthAddress } from '@aztec/foundation/eth-address';
-export const WANT_TO_SLASH_EVENT = 'wantToSlash';
 export const DefaultSlasherConfig = {
     slashPayloadTtlSeconds: 60 * 60 * 24,
     slashOverridePayload: undefined,
     slashPruneEnabled: true,
     slashPrunePenalty: 1n,
     slashPruneMaxPenalty: 100n,
-    slashInvalidBlockEnabled: true,
-    slashInvalidBlockPenalty: 1n,
-    slashInvalidBlockMaxPenalty: 100n,
+    slashBroadcastedInvalidBlockEnabled: true,
+    slashBroadcastedInvalidBlockPenalty: 1n,
+    slashBroadcastedInvalidBlockMaxPenalty: 100n,
     slashInactivityEnabled: true,
     slashInactivityCreateTargetPercentage: 0.9,
     slashInactivitySignalTargetPercentage: 0.6,
@@ -20,8 +18,12 @@ export const DefaultSlasherConfig = {
     slashProposeInvalidAttestationsMaxPenalty: 100n,
     slashAttestDescendantOfInvalidPenalty: 1n,
     slashAttestDescendantOfInvalidMaxPenalty: 100n,
+    slashUnknownPenalty: 1n,
+    slashUnknownMaxPenalty: 100n,
     slashProposerRoundPollingIntervalSeconds: 12,
-    slasherPrivateKey: new SecretValue(undefined)
+    slashOffenseExpirationRounds: 4,
+    slashMaxPayloadSize: 50,
+    slashGracePeriodL2Slots: 0
 };
 export const slasherConfigMappings = {
     slashPayloadTtlSeconds: {
@@ -50,20 +52,20 @@ export const slasherConfigMappings = {
         description: 'Maximum penalty amount for slashing validators of a pruned epoch.',
         ...bigintConfigHelper(DefaultSlasherConfig.slashPruneMaxPenalty)
     },
-    slashInvalidBlockEnabled: {
+    slashBroadcastedInvalidBlockEnabled: {
         env: 'SLASH_INVALID_BLOCK_ENABLED',
         description: 'Enable creation of slash payloads for invalid blocks.',
-        ...booleanConfigHelper(DefaultSlasherConfig.slashInvalidBlockEnabled)
+        ...booleanConfigHelper(DefaultSlasherConfig.slashBroadcastedInvalidBlockEnabled)
     },
-    slashInvalidBlockPenalty: {
+    slashBroadcastedInvalidBlockPenalty: {
         env: 'SLASH_INVALID_BLOCK_PENALTY',
         description: 'Penalty amount for slashing a validator for an invalid block.',
-        ...bigintConfigHelper(DefaultSlasherConfig.slashInvalidBlockPenalty)
+        ...bigintConfigHelper(DefaultSlasherConfig.slashBroadcastedInvalidBlockPenalty)
     },
-    slashInvalidBlockMaxPenalty: {
+    slashBroadcastedInvalidBlockMaxPenalty: {
         env: 'SLASH_INVALID_BLOCK_MAX_PENALTY',
         description: 'Maximum penalty amount for slashing a validator for an invalid block.',
-        ...bigintConfigHelper(DefaultSlasherConfig.slashInvalidBlockMaxPenalty)
+        ...bigintConfigHelper(DefaultSlasherConfig.slashBroadcastedInvalidBlockMaxPenalty)
     },
     slashInactivityEnabled: {
         env: 'SLASH_INACTIVITY_ENABLED',
@@ -118,12 +120,31 @@ export const slasherConfigMappings = {
         description: 'Maximum penalty amount for slashing a validator that attested to a descendant of an invalid block.',
         ...bigintConfigHelper(DefaultSlasherConfig.slashAttestDescendantOfInvalidMaxPenalty)
     },
+    slashUnknownPenalty: {
+        env: 'SLASH_UNKNOWN_PENALTY',
+        description: 'Penalty amount for slashing a validator for an unknown offense.',
+        ...bigintConfigHelper(DefaultSlasherConfig.slashUnknownPenalty)
+    },
+    slashUnknownMaxPenalty: {
+        env: 'SLASH_UNKNOWN_MAX_PENALTY',
+        description: 'Maximum penalty amount for slashing a validator for an unknown offense.',
+        ...bigintConfigHelper(DefaultSlasherConfig.slashUnknownMaxPenalty)
+    },
     slashProposerRoundPollingIntervalSeconds: {
         description: 'Polling interval for slashing proposer round in seconds.',
         ...numberConfigHelper(DefaultSlasherConfig.slashProposerRoundPollingIntervalSeconds)
     },
-    slasherPrivateKey: {
-        description: 'Private key used for creating slash payloads.',
-        ...secretValueConfigHelper((val)=>val ? `0x${val.replace('0x', '')}` : NULL_KEY)
+    slashOffenseExpirationRounds: {
+        description: 'Number of rounds after which pending offenses expire.',
+        ...numberConfigHelper(DefaultSlasherConfig.slashOffenseExpirationRounds)
+    },
+    slashMaxPayloadSize: {
+        description: 'Maximum number of offenses to include in a single slash payload.',
+        ...numberConfigHelper(DefaultSlasherConfig.slashMaxPayloadSize)
+    },
+    slashGracePeriodL2Slots: {
+        description: 'Number of L2 slots to wait before considering a slashing offense expired.',
+        env: 'SLASH_GRACE_PERIOD_L2_SLOTS',
+        ...numberConfigHelper(DefaultSlasherConfig.slashGracePeriodL2Slots)
     }
 };

package/dest/empire_slasher_client.d.ts

@@ -0,0 +1,192 @@
+import { EmpireSlashingProposerContract } from '@aztec/ethereum';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import type { DateProvider } from '@aztec/foundation/timer';
+import type { L1RollupConstants } from '@aztec/stdlib/epoch-helpers';
+import type { SlasherConfig } from '@aztec/stdlib/interfaces/server';
+import { SlashFactoryContract } from '@aztec/stdlib/l1-contracts';
+import { type Offense, type ProposerSlashAction, type ProposerSlashActionProvider, type SlashPayload, type SlashPayloadRound } from '@aztec/stdlib/slashing';
+import { type SlashOffensesCollectorSettings } from './slash_offenses_collector.js';
+import type { SlasherClientInterface } from './slasher_client_interface.js';
+import type { SlasherOffensesStore } from './stores/offenses_store.js';
+import type { SlasherPayloadsStore } from './stores/payloads_store.js';
+import type { Watcher } from './watcher.js';
+/** Used to track executable payloads for each round */
+export type PayloadWithRound = {
+    payload: EthAddress;
+    round: bigint;
+};
+/** Node configuration for the empire slasher */
+export type EmpireSlasherConfig = SlasherConfig;
+/** Settings used in the empire slasher client, loaded from the L1 contracts during initialization */
+export type EmpireSlasherSettings = {
+    slashingExecutionDelayInRounds: number;
+    slashingPayloadLifetimeInRounds: number;
+    slashingRoundSize: number;
+    slashingQuorumSize: number;
+} & Pick<L1RollupConstants, 'epochDuration' | 'proofSubmissionEpochs' | 'l1GenesisTime' | 'slotDuration' | 'l1StartBlock' | 'ethereumSlotDuration'> & SlashOffensesCollectorSettings;
+/**
+ * The Empire Slasher client is responsible for managing slashable offenses and slash payloads
+ * using the Empire slashing model where fixed payloads are created and voted on.
+ *
+ * The client subscribes to several slash watchers that emit offenses and tracks them. When the slasher is the
+ * proposer, it aggregates pending offenses from previous rounds and creates slash payloads, or votes for previous
+ * slash payloads.
+ * Voting is handled by the sequencer publisher, the slasher client does not interact with L1 directly.
+ * The client also monitors slash payloads created by other nodes, and executes them when they become submittable.
+ *
+ * Payload creation and selection
+ * - At each L2 slot in a slashing round, the proposer for that L2 slot may vote for an existing slashing payload or
+ * create one of their own. Note that anyone can create a slash payload on L1, but nodes will only follow payloads
+ * from proposers; we could enforce this on L1, but we do not want to make any changes there if we can avoid it.
+ * - If it is the first L2 slot in the slashing round, there is nothing to vote for, so the proposer creates a slash
+ * payload and votes for it.
+ * - On their turn, each proposer computes a score for each payload in the round. This score is a function of the
+ * total offences slashed, how many votes it has received so far, and how far into the round we are. The score for a
+ * payload is zero if the proposer disagrees with it (see "agreement" below).
+ * - The proposer also computes the score for the payload they would create. If the resulting score is higher than
+ * any existing payload, it creates the payload. Otherwise, it votes for the one with the highest score.
+ *
+ * Collecting offences
+ * - Whenever a node spots a slashable offence, they store it and add it to a local collection of "pending
+ * offences". When a proposer needs to create a slash payload, they include all pending offences from previous
+ * rounds. This means an offence is **only slashable in the next round it happened** (or a future one).
+ * - Each offence also carries an epoch or block identifier, so we can differentiate two offences of the same kind by
+ * the same validator.
+ * - When a slash payload is flagged as executable (as in it got enough votes to be executed), nodes remove all
+ * slashed offences in the payload from their collection of pending offences.
+ * - Pending offences expire after a configurable time. This is to minimize divergences. For instance, a validator
+ * that has to be slashed due to inactivity 50 epochs ago will only be considered for slashing by nodes that were
+ * online 50 epochs ago. We propose using the validator exit window as expiration time, any value higher means that
+ * we may try slashing validators that have exited the set already.
+ *
+ * Agreement and scoring
+ * - A proposer will *agree* with a slash payload if it *agrees* with every offence in the payload, all
+ * *uncontroversial* offences from the past round are included, and it is below a configurable maximum size.
+ * - An *uncontroversial* offence is one where every node agrees that a slash is in order, regardless of any p2p
+ * network partitions. The only uncontroversial offence we have now is "proposing a block on L1 with invalid
+ * attestations".
+ * - A proposer will *agree* with a given offence if it is present in its list of "pending offences", and the
+ * slashing amount is within a configurable min-max range.
+ * - Slash payloads need a maximum size to ensure they can don't exceed the maximum L1 gas per tx when executed.
+ * This is configurable but depends on the L1 contracts implementation. When creating a payload, if there are too
+ * many pending offences to fit, proposers favor the offences with the highest slashing amount first, tie-breaking by
+ * choosing the most recent ones.
+ * - The scoring function will boost proposals with more agreed slashes, as well as proposals with more votes, and
+ * will disincentivize the creation of new proposals as the end of the round nears. This function will NOT be
+ * enforced on L1.
+ *
+ * Execution
+ * - Once a slash payload becomes executable, the next proposer is expected to execute it. If they don't, the
+ * following does, and so on. No gas rebate is given.
+ */
+export declare class EmpireSlasherClient implements ProposerSlashActionProvider, SlasherClientInterface {
+    private config;
+    private settings;
+    private slashFactoryContract;
+    private slashingProposer;
+    private rollupAddress;
+    private dateProvider;
+    private offensesStore;
+    private payloadsStore;
+    private log;
+    protected executablePayloads: PayloadWithRound[];
+    private unwatchCallbacks;
+    private overridePayloadActive;
+    private offensesCollector;
+    private roundMonitor;
+    constructor(config: EmpireSlasherConfig, settings: EmpireSlasherSettings, slashFactoryContract: SlashFactoryContract, slashingProposer: EmpireSlashingProposerContract, rollupAddress: EthAddress, watchers: Watcher[], dateProvider: DateProvider, offensesStore: SlasherOffensesStore, payloadsStore: SlasherPayloadsStore, log?: import("@aztec/foundation/log").Logger);
+    start(): Promise<void>;
+    /**
+     * 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.
+     */
+    stop(): Promise<void>;
+    /** Returns the current config */
+    getConfig(): EmpireSlasherConfig;
+    /**
+     * Update the config of the slasher client
+     * @param config - The new config
+     */
+    updateConfig(config: Partial<SlasherConfig>): void;
+    getSlashPayloads(): Promise<SlashPayloadRound[]>;
+    /**
+     * Triggered on a time basis when we enter a new slashing round.
+     * Clears expired payloads and offenses from stores.
+     */
+    protected handleNewRound(round: bigint): Promise<void>;
+    /**
+     * Called when we see a PayloadSubmittable event on the SlashProposer.
+     * Adds the proposal to the list of executable ones.
+     */
+    protected handleProposalExecutable(payloadAddress: EthAddress, round: bigint): Promise<void>;
+    /**
+     * Called when we see a PayloadSubmitted event on the SlashProposer.
+     * Removes the proposal from the list of executable ones.
+     */
+    protected handleProposalExecuted(payload: EthAddress, round: bigint): Promise<void>;
+    /**
+     * Called when we see a SignalCast event on the SlashProposer.
+     * Adds a vote for the given payload in the round.
+     * Retrieves the proposal if we have not seen it before.
+     */
+    protected handleProposalSignalled(payloadAddress: EthAddress, round: bigint, signaller: EthAddress): Promise<void>;
+    /**
+     * Create a slash payload for the given round from pending offenses
+     * @param round - The round to create the payload for, defaults to the current round
+     * @returns The payload data or undefined if no offenses to slash
+     */
+    gatherOffensesForRound(round?: bigint): Promise<Offense[]>;
+    /** Returns all pending offenses stored */
+    getPendingOffenses(): Promise<Offense[]>;
+    /** Get uncontroversial offenses that are expected to be present on the given round. */
+    protected getPendingUncontroversialOffensesForRound(round: bigint): Promise<Offense[]>;
+    /**
+     * Calculate score for a slash payload, bumping the votes by one, so we get the score as if we voted for it.
+     * @param payload - The payload to score
+     * @param votes - Number of votes the payload has received
+     * @returns The score for the payload
+     */
+    protected calculatePayloadScore(payload: Pick<SlashPayloadRound, 'votes' | 'slashes'>): bigint;
+    /**
+     * Get the actions the proposer should take for slashing
+     * @param slotNumber - The current slot number
+     * @returns The actions to take
+     */
+    getProposerActions(slotNumber: bigint): Promise<ProposerSlashAction[]>;
+    /** Returns an execute payload action if there are any payloads ready to be executed */
+    protected getExecutePayloadAction(slotNumber: bigint): Promise<ProposerSlashAction | undefined>;
+    /** Returns a vote or create payload action based on payload scoring */
+    protected getProposePayloadActions(slotNumber: bigint): Promise<ProposerSlashAction[]>;
+    /**
+     * Check if we agree with a payload:
+     * - We must agree with every offense in the payload
+     * - All uncontroversial offenses from past rounds must be included
+     * - Payload must be below maximum size
+     * - Slash amounts must be within acceptable ranges
+     */
+    protected agreeWithPayload(payload: SlashPayload, round: bigint, cachedUncontroversialOffenses?: Offense[]): Promise<boolean>;
+    /**
+     * Returns whether the given offense can be included in the given round.
+     * Depends on the offense round range and whether we include offenses from past rounds.
+     */
+    private isOffenseForRound;
+    /**
+     * Returns the range (inclusive) of rounds in which we could expect an offense to be found.
+     * Lower bound is determined by all offenses that should have been captured before the start of a round,
+     * which depends on the offense type (eg INACTIVITY is captured once an epoch ends, DATA_WITHHOLDING is
+     * captured after the epoch proof submission window for the epoch for which the data was withheld).
+     * Upper bound is determined by the expiration rounds for an offense, which is a config setting.
+     */
+    private getRoundRangeForOffense;
+    /** Returns the acceptable range for slash amount given a set of offenses. */
+    private getSlashAmountValidRange;
+    /**
+     * Get minimum acceptable amount for an offense type
+     */
+    private getMinAmountForOffense;
+    /**
+     * Get maximum acceptable amount for an offense type
+     */
+    private getMaxAmountForOffense;
+}
+//# sourceMappingURL=empire_slasher_client.d.ts.map

package/dest/empire_slasher_client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"empire_slasher_client.d.ts","sourceRoot":"","sources":["../src/empire_slasher_client.ts"],"names":[],"mappings":"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"}