@aztec/slasher 0.0.1-fake-c83136db25

package/README.md

@@ -0,0 +1,218 @@
+# Slasher
+
+## Overview
+
+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 from a given past round should be slashed (eg round N votes to slash the validators from round N-2). 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
+- Requires a slash offset to vote on validators from past rounds
+- Requires quorum to execute slashing
+- L1 contract determines which offenses reach consensus
+- Execution happens after a delay period for review
+- Slash payloads can be vetoed during the execution delay period
+
+### 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 automatic expiration
+
+#### SlasherOffensesStore
+Persistent storage for offenses. Tracks:
+- Pending offenses awaiting slashing
+- Executed offenses to prevent double slashing
+- Round-based offense organization
+- Automatic expiration of old offenses based on configurable rounds
+
+#### 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
+
+## Vetoing
+
+The slashing system includes a veto mechanism that allows designated vetoers to block slash payloads during the execution delay period. When a slash payload is ready for execution, the system first checks if it has been vetoed before proceeding.
+
+Key features:
+- Slash payloads can be vetoed by authorized addresses on the L1 slasher contract
+- Veto checks are performed automatically before execution attempts
+- The veto mechanism provides a safety valve for incorrectly proposed slashes
+
+## Slashable Offenses
+
+List of all slashable offenses in the system:
+
+### 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.  
+
+### 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
+
+### L1 System Settings (L1ContractsConfig)
+These settings are deployed with the L1 contracts and apply system-wide to the protocol:
+
+- `slashingQuorumSize`: Votes required to slash (defaults to half the validators in a round, plus one)
+- `slashingRoundSizeInEpochs`: Number of epochs per slashing round
+- `slashingOffsetInRounds`: How many rounds to look back for offenses (tally model)
+- `slashingExecutionDelayInRounds`: Rounds to wait before execution
+- `slashingLifetimeInRounds`: Maximum age of executable rounds
+- `slashingAmounts`: Valid values for each individual slash (tally model)
+
+Considerations:
+
+- The `slashingQuorumSize` should be more than half and less than the total number of validators in a round, so that we require a majority to slash. The number of validators in a round is the committee size times the number of epochs in a round.
+- The bigger a `slashingRoundSizeInEpochs`, the bigger the upper bound on the quorum size. This increases security, as we need more validators to agree before slashing. However, it also makes slashing slower, and more expensive to execute in terms of gas in the tally model.
+- The `slashingOffsetInRounds` is required because the validators in a given slashing round must vote for _past_ offenses. Otherwise, if someone commits an offense near the end of a round, they can get away with their offense without the validators being able to collect enough votes to slash them. The offset needs to be big enough so that all offenses are discoverable, so this value should be strictly greater than the proof submission window in order to be able to slash for epoch prunes or data withholding.
+- The `slashingExecutionDelayInRounds` allows vetoers to stop an invalid slash. This should be large enough to give vetoers time to act, but strictly smaller than the validator exit window, so an offender cannot escape before they are slashed. It should also be small enough so that an offender that would be kicked out does not get picked up to be a committee member again before their slash is executed. In other words, if a validator commits a serious enough offense that we want them out of the validator set as soon as possible, the execution delay should not allow them to be chosen to participate in another committee.
+
+### Local Node Configuration (SlasherConfig)
+
+These settings are configured locally on each validator node:
+
+- `slashGracePeriodL2Slots`: Number of initial L2 slots where slashing is disabled
+- `slashOffenseExpirationRounds`: Number of rounds after which pending offenses expire
+- `slashValidatorsAlways`: Array of validator addresses that should always be slashed
+- `slashValidatorsNever`: Array of validator addresses that should never be slashed (own validator addresses are automatically added to this list)
+- `slashInactivityTargetPercentage`: Percentage of misses during an epoch to be slashed for INACTIVITY
+- `slashInactivityConsecutiveEpochThreshold`: How many consecutive inactive epochs are needed to trigger an INACTIVITY slash on a validator
+- `slashPrunePenalty`: Penalty for VALID_EPOCH_PRUNED
+- `slashDataWithholdingPenalty`: Penalty for DATA_WITHHOLDING
+- `slashInactivityPenalty`: Penalty for INACTIVITY
+- `slashBroadcastedInvalidBlockPenalty`: Penalty for BROADCASTED_INVALID_BLOCK_PROPOSAL
+- `slashProposeInvalidAttestationsPenalty`: Penalty for PROPOSED_INSUFFICIENT_ATTESTATIONS and PROPOSED_INCORRECT_ATTESTATIONS
+- `slashAttestDescendantOfInvalidPenalty`: Penalty for ATTESTED_DESCENDANT_OF_INVALID
+- `slashUnknownPenalty`: Default penalty for unknown offense types
+- `slashMaxPayloadSize`: Maximum size of slash payloads (empire model)
+- `slashMinPenaltyPercentage`: Agree to slashes if they are at least this percentage of the configured penalty (empire model)
+- `slashMaxPenaltyPercentage`: Agree to slashes if they are at most this percentage of the configured penalty (empire model)
+
+Considerations:
+
+- All penalties should map to one of the `slashingAmounts`. A penalty lower than the smallest slashing amount will not be executable, and a penalty greater than the maximum will be capped at the maximum value.
+- The `slashOffenseExpirationRounds` should be strictly larger than the `slashingOffsetInRounds`. This can be a relatively large value, as it's used only for data store cleanup.
+
+## Offenses In-Depth
+
+Details about specific offenses in the system:
+
+### Inactivity
+
+Inactivity slashing is one of the most critical, since it allows purging validators that are not fulfilling their duties, which could potentially bring the chain to a halt. This slashing must be aggressive enough to balance out the rate of the entry queue, in case the queue is filled with inactive validators. Furthermore, if enough inactive validators join the system, it may become impossible to gather enough quorum to pass any governance proposal.
+
+Inactivity slashing is handled by the `Sentinel` which monitors performance of all validators slot-by-slot. After each slot, the sentinel assigns one of the following to the block proposer for the slot:
+- `block-mined` if the block was added to L1
+- `block-proposed` if the block received at least one attestation, but didn't make it to L1
+- `block-missed` if the block received no attestations (note that we cannot rely on the P2P proposal alone since it may be invalid, unless we reexecute it)
+
+And assigns one of the following to each validator:
+- `attestation-sent` if there was a `block-proposed` or `block-mined` and an attestation from this validator was seen on either on L1 or on the P2P network
+- `attestation-missed` if there was a `block-proposed` or `block-mined` but no attestation was seen
+- none if the slot was a `block-missed`
+
+Once an epoch is proven, the sentinel computes the _proven performance_ for the epoch for each validator. Note that we wait until the epoch is proven so we know that the data for all blocks in the epoch was available, and validators who did not attest were effectively inactive. Then, for each validator such that:
+
+```
+total_failures = count(block-missed) + count(attestation-missed)
+total = count(block-*) + count(attestation-*)
+total_failures / total >= slash_inactivity_target_percentage
+```
+
+They are voted to be slashed for inactivity. Note that, if `slashInactivityConsecutiveEpochThreshold` is greater than one, we first check if the above is true for the last `threshold` times the given validator was part of a committee, and only then trigger the offense.
+
+

package/dest/config.d.ts

@@ -0,0 +1,6 @@
+import type { ConfigMappingsType } from '@aztec/foundation/config';
+import type { SlasherConfig } from '@aztec/stdlib/interfaces/server';
+export type { SlasherConfig };
+export declare const DefaultSlasherConfig: SlasherConfig;
+export declare const slasherConfigMappings: ConfigMappingsType<SlasherConfig>;
+//# sourceMappingURL=config.d.ts.map

package/dest/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,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,aAoBlC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,kBAAkB,CAAC,aAAa,CAyHnE,CAAC"}

package/dest/config.js

@@ -0,0 +1,134 @@
+import { DefaultL1ContractsConfig } from '@aztec/ethereum';
+import { bigintConfigHelper, booleanConfigHelper, floatConfigHelper, numberConfigHelper } from '@aztec/foundation/config';
+import { EthAddress } from '@aztec/foundation/eth-address';
+export const DefaultSlasherConfig = {
+    slashOverridePayload: undefined,
+    slashMinPenaltyPercentage: 0.5,
+    slashMaxPenaltyPercentage: 2.0,
+    slashValidatorsAlways: [],
+    slashValidatorsNever: [],
+    slashPrunePenalty: DefaultL1ContractsConfig.slashAmountSmall,
+    slashDataWithholdingPenalty: DefaultL1ContractsConfig.slashAmountSmall,
+    slashInactivityTargetPercentage: 0.9,
+    slashInactivityConsecutiveEpochThreshold: 1,
+    slashBroadcastedInvalidBlockPenalty: DefaultL1ContractsConfig.slashAmountSmall,
+    slashInactivityPenalty: DefaultL1ContractsConfig.slashAmountSmall,
+    slashProposeInvalidAttestationsPenalty: DefaultL1ContractsConfig.slashAmountSmall,
+    slashAttestDescendantOfInvalidPenalty: DefaultL1ContractsConfig.slashAmountSmall,
+    slashUnknownPenalty: DefaultL1ContractsConfig.slashAmountSmall,
+    slashOffenseExpirationRounds: 4,
+    slashMaxPayloadSize: 50,
+    slashGracePeriodL2Slots: 0,
+    slashExecuteRoundsLookBack: 4,
+    slashSelfAllowed: false
+};
+export const slasherConfigMappings = {
+    slashOverridePayload: {
+        env: 'SLASH_OVERRIDE_PAYLOAD',
+        description: 'An Ethereum address for a slash payload to vote for unconditionally.',
+        parseEnv: (val)=>val ? EthAddress.fromString(val) : undefined,
+        defaultValue: DefaultSlasherConfig.slashOverridePayload
+    },
+    slashMinPenaltyPercentage: {
+        env: 'SLASH_MIN_PENALTY_PERCENTAGE',
+        description: 'Minimum penalty percentage for slashing offenses (0.1 is 10%).',
+        ...floatConfigHelper(DefaultSlasherConfig.slashMinPenaltyPercentage)
+    },
+    slashMaxPenaltyPercentage: {
+        env: 'SLASH_MAX_PENALTY_PERCENTAGE',
+        description: 'Maximum penalty percentage for slashing offenses (2.0 is 200%).',
+        ...floatConfigHelper(DefaultSlasherConfig.slashMaxPenaltyPercentage)
+    },
+    slashValidatorsAlways: {
+        env: 'SLASH_VALIDATORS_ALWAYS',
+        description: 'Comma-separated list of validator addresses that should always be slashed.',
+        parseEnv: (val)=>val.split(',').map((addr)=>addr.trim()).filter((addr)=>addr.length > 0).map((addr)=>EthAddress.fromString(addr)),
+        defaultValue: DefaultSlasherConfig.slashValidatorsAlways
+    },
+    slashValidatorsNever: {
+        env: 'SLASH_VALIDATORS_NEVER',
+        description: 'Comma-separated list of validator addresses that should never be slashed.',
+        parseEnv: (val)=>val.split(',').map((addr)=>addr.trim()).filter((addr)=>addr.length > 0).map((addr)=>EthAddress.fromString(addr)),
+        defaultValue: DefaultSlasherConfig.slashValidatorsNever
+    },
+    slashPrunePenalty: {
+        env: 'SLASH_PRUNE_PENALTY',
+        description: 'Penalty amount for slashing validators of a valid pruned epoch (set to 0 to disable).',
+        ...bigintConfigHelper(DefaultSlasherConfig.slashPrunePenalty)
+    },
+    slashDataWithholdingPenalty: {
+        env: 'SLASH_DATA_WITHHOLDING_PENALTY',
+        description: 'Penalty amount for slashing validators for data withholding (set to 0 to disable).',
+        ...bigintConfigHelper(DefaultSlasherConfig.slashDataWithholdingPenalty)
+    },
+    slashBroadcastedInvalidBlockPenalty: {
+        env: 'SLASH_INVALID_BLOCK_PENALTY',
+        description: 'Penalty amount for slashing a validator for an invalid block proposed via p2p.',
+        ...bigintConfigHelper(DefaultSlasherConfig.slashBroadcastedInvalidBlockPenalty)
+    },
+    slashInactivityTargetPercentage: {
+        env: 'SLASH_INACTIVITY_TARGET_PERCENTAGE',
+        description: 'Missed attestation percentage to trigger creation of inactivity slash payload (0, 1]. Must be greater than 0',
+        ...floatConfigHelper(DefaultSlasherConfig.slashInactivityTargetPercentage, (v)=>{
+            if (v <= 0 || v > 1) {
+                throw new RangeError(`SLASH_INACTIVITY_TARGET_PERCENTAGE out of range. Expected (0, 1] got ${v}`);
+            }
+        })
+    },
+    slashInactivityConsecutiveEpochThreshold: {
+        env: 'SLASH_INACTIVITY_CONSECUTIVE_EPOCH_THRESHOLD',
+        description: 'Number of consecutive epochs a validator must be inactive before slashing (minimum 1).',
+        ...numberConfigHelper(DefaultSlasherConfig.slashInactivityConsecutiveEpochThreshold),
+        parseEnv: (val)=>{
+            const parsed = parseInt(val, 10);
+            if (parsed < 1) {
+                throw new RangeError(`SLASH_INACTIVITY_CONSECUTIVE_EPOCH_THRESHOLD must be at least 1 (got ${parsed})`);
+            }
+            return parsed;
+        }
+    },
+    slashInactivityPenalty: {
+        env: 'SLASH_INACTIVITY_PENALTY',
+        description: 'Penalty amount for slashing an inactive validator (set to 0 to disable).',
+        ...bigintConfigHelper(DefaultSlasherConfig.slashInactivityPenalty)
+    },
+    slashProposeInvalidAttestationsPenalty: {
+        env: 'SLASH_PROPOSE_INVALID_ATTESTATIONS_PENALTY',
+        description: 'Penalty amount for slashing a proposer that proposed invalid attestations (set to 0 to disable).',
+        ...bigintConfigHelper(DefaultSlasherConfig.slashProposeInvalidAttestationsPenalty)
+    },
+    slashAttestDescendantOfInvalidPenalty: {
+        env: 'SLASH_ATTEST_DESCENDANT_OF_INVALID_PENALTY',
+        description: 'Penalty amount for slashing a validator that attested to a descendant of an invalid block (set to 0 to disable).',
+        ...bigintConfigHelper(DefaultSlasherConfig.slashAttestDescendantOfInvalidPenalty)
+    },
+    slashUnknownPenalty: {
+        env: 'SLASH_UNKNOWN_PENALTY',
+        description: 'Penalty amount for slashing a validator for an unknown offense (set to 0 to disable).',
+        ...bigintConfigHelper(DefaultSlasherConfig.slashUnknownPenalty)
+    },
+    slashOffenseExpirationRounds: {
+        env: 'SLASH_OFFENSE_EXPIRATION_ROUNDS',
+        description: 'Number of rounds after which pending offenses expire.',
+        ...numberConfigHelper(DefaultSlasherConfig.slashOffenseExpirationRounds)
+    },
+    slashMaxPayloadSize: {
+        env: 'SLASH_MAX_PAYLOAD_SIZE',
+        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)
+    },
+    slashExecuteRoundsLookBack: {
+        env: 'SLASH_EXECUTE_ROUNDS_LOOK_BACK',
+        description: 'How many rounds to look back when searching for a round to execute.',
+        ...numberConfigHelper(DefaultSlasherConfig.slashExecuteRoundsLookBack)
+    },
+    slashSelfAllowed: {
+        description: 'Whether to allow slashes to own validators',
+        ...booleanConfigHelper(DefaultSlasherConfig.slashSelfAllowed)
+    }
+};

package/dest/empire_slasher_client.d.ts

@@ -0,0 +1,189 @@
+import { EmpireSlashingProposerContract, RollupContract, SlasherContract } 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 slasher;
+    private rollup;
+    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, slasher: SlasherContract, rollup: RollupContract, 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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"}