diff --git a/docs/slashing/InstantSlasher.md b/docs/slashing/InstantSlasher.md new file mode 100644 index 00000000..e493745b --- /dev/null +++ b/docs/slashing/InstantSlasher.md @@ -0,0 +1,40 @@ +## InstantSlasher + +| File | Type | Proxy | +| -------- | -------- | -------- | +| [`InstantSlasher.sol`](../src/InstantSlasher.sol) | Implementation | No | + +The `InstantSlasher` is a concrete implementation of the `SlasherBase` contract that provides immediate execution of slashing requests without any delay or veto period. This contract should be used with caution, as slashing is a critical operation within an AVS. This implementation is reccomended if your AVS is mature, robust and the slashing conditions are well understood (i.e. those which do not arise from subjective or non-malicious reasons like a software bug) + +*As of current implementation*: +* This contract executes slashing requests immediately when initiated by the authorized slasher +* No waiting period or veto mechanism is implemented +* Each slashing request is assigned a unique ID + +--- + +### Core Functionality + +#### `fulfillSlashingRequest` +```solidity +function fulfillSlashingRequest( + IAllocationManager.SlashingParams calldata _slashingParams +) + external + virtual + override(IInstantSlasher) + onlySlasher +``` +Immediately executes a slashing request against the specified operator. + +*Entry Points*: +* External calls from the authorized slasher + +*Effects*: +* Assigns a unique ID to the slashing request +* Calls the internal `_fulfillSlashingRequest` function to execute the slashing action +* Increments the `nextRequestId` counter for future requests + +*Requirements*: +* Caller MUST be the authorized slasher (enforced by `onlySlasher` modifier) +* Slashing parameters must be valid \ No newline at end of file diff --git a/docs/slashing/SlasherBase.md b/docs/slashing/SlasherBase.md new file mode 100644 index 00000000..a498af86 --- /dev/null +++ b/docs/slashing/SlasherBase.md @@ -0,0 +1,63 @@ +## SlasherBase + +| File | Type | Proxy | +| -------- | -------- | -------- | +| [`SlasherBase.sol`](../src/base/SlasherBase.sol) | Abstract | No | + +The `SlasherBase` is an abstract contract that provides core slashing functionality intended for AVSs to inherit. It serves as the foundation for implementing slashing mechanisms that interact with EigenLayer's `AllocationManager`. There are two implementations of this contract which are the [`VetoableSlasher`](./VetoableSlasher.md) and the [`InstantSlasher`](./InstantSlasher.md). + +*As of current implementation*: +* This contract provides the base functionality for slashing operators in EigenLayer based on certain conditions +* Concrete implementations will determine when and how slashing is performed + +--- + +### Core Functionality + +#### `_fulfillSlashingRequest` +```solidity +function _fulfillSlashingRequest( + uint256 _requestId, + IAllocationManager.SlashingParams memory _params +) + internal + virtual +``` +Internal function that executes a slashing request by calling the `AllocationManager.slashOperator` method. The implementations of this contract will call this internal method. + +*Effects*: +* Calls the allocation manager to slash the specified operator +* Emits an `OperatorSlashed` event with details about the slashing action + +*Requirements*: +* The allocation manager must be properly set up +* The slashing parameters must be valid + +#### `_checkSlasher` +```solidity +function _checkSlasher( + address account +) + internal + view + virtual +``` +Internal function that verifies if an account is the authorized slasher. + +*Effects*: +* Reverts with an `OnlySlasher` error if the provided account is not the authorized slasher + +*Requirements*: +* The account must match the stored slasher address + +### Modifiers + +#### `onlySlasher` +```solidity +modifier onlySlasher() +``` +Ensures that only the authorized slasher can call certain functions. This will commonly be set as the address of the AVS `ServiceManager` which would expose a permissioned or permissionless external function to call the slashing contract. Keeping the contracts decoupled allows for easier upgrade paths. + +*Effects*: +* Calls `_checkSlasher` to verify that the caller is the authorized slasher +* Allows the function execution to proceed if the check passes \ No newline at end of file diff --git a/docs/slashing/VetoableSlasher.md b/docs/slashing/VetoableSlasher.md new file mode 100644 index 00000000..20cfe8ef --- /dev/null +++ b/docs/slashing/VetoableSlasher.md @@ -0,0 +1,102 @@ +## VetoableSlasher + +| File | Type | Proxy | +| -------- | -------- | -------- | +| [`VetoableSlasher.sol`](../src/VetoableSlasher.sol) | Implementation | No | + +The `VetoableSlasher` is a concrete implementation of the [`SlasherBase`](./SlasherBase.md) contract that adds a veto mechanism to the slashing process. This implementation introduces a waiting period during which a designated veto committee can cancel slashing requests before they are executed. This slasher implementation is recommended for AVSs to use as their systems matures, to account for slashing faults that arise from subjective conditions or non-malicious reasons such as a software bug. As the AVSs matures and the slashing conditions become well defined, the instant slasher may be a suitable contract. It is reccomended to have your veto comittee to be comprised of a set of diverse subject matter experts. + +*As of current implementation*: +* Slashing requests are queued and can only be fulfilled after a configurable veto window has passed +* A designated veto committee can cancel slashing requests during the veto window +* Slashing requests have a status that tracks their lifecycle: Requested, Cancelled, or Completed + +--- + +### Core Functionality + +#### `queueSlashingRequest` +```solidity +function queueSlashingRequest( + IAllocationManager.SlashingParams calldata params +) + external + virtual + override + onlySlasher +``` +Creates and queues a new slashing request that will be executable after the veto window has passed. + +*Entry Points*: +* External calls from the authorized slasher + +*Effects*: +* Assigns a unique ID to the slashing request +* Creates a new slashing request with the provided parameters +* Sets the request status to `Requested` +* Stores the current block number as the request block +* Emits a `SlashingRequested` event + +*Requirements*: +* Caller MUST be the authorized slasher (enforced by `onlySlasher` modifier) +* Slashing parameters must be valid + +#### `cancelSlashingRequest` +```solidity +function cancelSlashingRequest( + uint256 requestId +) + external + virtual + override + onlyVetoCommittee +``` +Allows the veto committee to cancel a pending slashing request within the veto window. + +*Entry Points*: +* External calls from the veto committee + +*Effects*: +* Changes the request status from `Requested` to `Cancelled` +* Emits a `SlashingRequestCancelled` event + +*Requirements*: +* Caller MUST be the veto committee (enforced by `onlyVetoCommittee` modifier) +* The request MUST be in the `Requested` status +* The current block number MUST be less than the request block plus the veto window + +#### `fulfillSlashingRequest` +```solidity +function fulfillSlashingRequest( + uint256 requestId +) + external + virtual + override + onlySlasher +``` +Executes a slashing request after the veto window has passed, if it has not been cancelled. + +*Entry Points*: +* External calls from the authorized slasher + +*Effects*: +* Changes the request status from `Requested` to `Completed` +* Calls the internal `_fulfillSlashingRequest` function to execute the slashing action + +*Requirements*: +* Caller MUST be the authorized slasher (enforced by `onlySlasher` modifier) +* The request MUST be in the `Requested` status +* The veto window MUST have passed (current block number >= request block + veto window) + +### Modifiers + +#### `onlyVetoCommittee` +```solidity +modifier onlyVetoCommittee() +``` +Ensures that only the veto committee can call certain functions. + +*Effects*: +* Calls `_checkVetoCommittee` to verify that the caller is the veto committee +* Allows the function execution to proceed if the check passes \ No newline at end of file