Skip to content

Commit 6048cb6

Browse files
MadelineAuwesfloyd
MadelineAu
and
wesfloyd
authored
Redistribution for AVS developers (#492)
Co-authored-by: Wes Floyd <[email protected]>
1 parent 4c81b14 commit 6048cb6

18 files changed

+120
-60
lines changed

‎.yarn/install-state.gz

1.44 MB
Binary file not shown.

‎.yarnrc.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
nodeLinker: node-modules

‎docs/developers/Concepts/avs-keys.md

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,10 @@ sidebar_position: 6
33
title: AVS Keys
44
---
55

6-
For information on AVS key types, refer to [Keys](../../eigenlayer/concepts/keys-and-signatures).
6+
For information on AVS key types, refer to [Keys](../../eigenlayer/concepts/keys-and-signatures).
7+
8+
:::important
9+
When using Redistribution, an attacker that gains access to AVS keys for the slasher and `redistributionRecipient` can drain
10+
the entirety of Operator and Staker allocated stake for a given Operator Set.
11+
:::
12+

‎docs/developers/Concepts/avs-security-models.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,4 +22,5 @@ The list of security models is not exhaustive. The EigenLayer protocol provides
2222
AVSs have flexibility to design their protocols to slash for any reason. AVSs are encouraged to:
2323
* Create robust legibility and process around how their slashing is designed and individual slashing events.
2424
* Clearly communicate slashing design and individual slashing events to their Operator and Staker communities.
25+
* Make strong guarantees about how upstream contracts function for Redistributing Operator Sets to their Operator and Staker communities.
2526
:::

‎docs/developers/Concepts/eigenlayer-contracts/core-contracts.md

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,8 @@ The EigenLayer core contracts are documented in the [eigenlayer-contracts](https
1818
| [AllocationManager](https://github.com/Layr-Labs/eigenlayer-contracts/tree/testnet-sepolia/docs#allocationmanager) | Responsible for creating Operator Sets, and Operator registrations to Operator Sets. The Allocation Manager also tracks allocation of stake to a Operator Set, and enables AVSs to slash that stake.
1919
| [RewardsCoordinator](https://github.com/Layr-Labs/eigenlayer-contracts/tree/testnet-sepolia/docs#allocationmanager) | Enables AVSs to distribute ERC20 tokens to Operators and Restakers who delegated assets to Operators. The RewardsCoordinator tracks the rewards and enables Operators and Restakers to claim them.
2020
| [PermissionController](https://github.com/Layr-Labs/eigenlayer-contracts/tree/testnet-sepolia/docs#permissioncontroller) | Enables AVSs and operators to delegate the ability to call certain core contract functions to other addresses. For more information, refer to [User Access Management](../../../eigenlayer/concepts/uam/user-access-management.md). |
21-
| [AVSDirectory](https://github.com/Layr-Labs/eigenlayer-contracts/tree/testnet-sepolia/docs#avsdirectory) | Has been replaced by AllocationManager and will be deprecated in a future release. |
21+
| [SlashEscrowFactory](https://github.com/Layr-Labs/eigenlayer-contracts/blob/v1.5.0-rc.0/docs/core/SlashEscrowFactory.md) | Responsible for burning or redistribution of slashed funds. The SlashEscrowFactory enforces the Slash Escrow Delay, deploys the Slash Escrow clone for each slash, and releases funds from the Slash Escrow contract. For redistributed funds, called by the [`redistributionRecipient`](../slashing/slashing-concept-developers.md#redistribution-recipient) to release funds.
22+
| [AVSDirectory](https://github.com/Layr-Labs/eigenlayer-contracts/tree/testnet-sepolia/docs#avsdirectory) | Has been replaced by AllocationManager and will be deprecated in a future release. We strongly recommend existing AVSs [migrate to using Operator Sets](../../HowTo/build/operator-sets/migrate-to-operatorsets.md) on Testnet. |
2223

23-
AVSDirectory will be deprecated in a future release. We strongly recommend existing AVSs [migrate to using Operator Sets](../../HowTo/build/slashing/migrate-to-operatorsets.md)
24-
on Testnet.
25-
26-
This documentation matches the functionality available on the [Sepolia testnet](https://www.blog.eigenlayer.xyz/the-future-of-eigenlayer-testing-new-and-improved-testnets-tooling-coming-soon/). For mainnet
27-
specific documentation, refer to the `/docs` repository on the `mainnet` branch in the [eigenlayer-contracts](https://github.com/Layr-Labs/eigenlayer-contracts)
28-
repository.
24+
This documentation matches the functionality available in [v1.5.0 of the core contracts](../../../eigenlayer/releases.md). For release specific
25+
documentation for other releases, refer to the `/docs` repository on the branch for that release in the [eigenlayer-contracts](https://github.com/Layr-Labs/eigenlayer-contracts) repository.

‎docs/developers/Concepts/slashing/slashing-concept-developers.md

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,24 @@ title: Slashing
66
For information on how slashing works, refer to concept content on [Slashing](../../../eigenlayer/concepts/slashing/slashing-concept.md) and
77
[Operator Sets](../../../eigenlayer/concepts/operator-sets/operator-sets-concept).
88

9+
## Redistribution Recipient
10+
11+
:::important
12+
When using Redistribution, an attacker that gains access to AVS keys for the slasher and `redistributionRecipient` can drain
13+
the entirety of Operator and Staker allocated stake for a given Operator Set.
14+
:::
15+
16+
When creating a redistributable Operator Set, an immutable `redistributionRecipient` is specified. The `redistributionRecipient`
17+
should be:
18+
* An AVS-controlled role and signing key.
19+
* A smart contract wallet or mulit-sig to ensure enhanced security and programmability.
20+
21+
The `redistributionRecipient` address cannot be changed. While an AVS may use an upstream proxy or pass-through contract,
22+
the immutability of this address in EigenLayer means an AVS can layer additional guarantees by guarding the upgradability
23+
of the upstream contract via controls such as governance, and timelocks.
24+
925
For information on how to implement slashing, refer to:
1026
* [Implement Slashing](../../HowTo/build/slashing/implement-slashing)
11-
* [Design Operator Sets](../../HowTo/build/slashing/design-operator-set.md)
12-
* [Migrate to Operator Sets](../../HowTo/build/slashing/migrate-to-operatorsets.md)
27+
* [Design Operator Sets](../../HowTo/build/operator-sets/design-operator-set.md)
28+
* [Migrate to Operator Sets](../../HowTo/build/operator-sets/migrate-to-operatorsets.md)
1329
* [Veto Committee Design](../../HowTo/build/slashing/slashing-veto-committee-design.md)

‎docs/developers/Concepts/uam-for-avs.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ title: User Access Management
55

66
:::note
77
There is no support for setting appointees for AVSDirectory functions. The AVSDirectory method will be deprecated in a future upgrade.
8-
[All AVSs will need to migrate to Operator Sets before the upcoming deprecation of AVSDirectory](../HowTo/build/slashing/migrate-to-operatorsets.md).
8+
[All AVSs will need to migrate to Operator Sets before the upcoming deprecation of AVSDirectory](../HowTo/build/operator-sets/migrate-to-operatorsets.md).
99
:::
1010

1111
For concept material on User Access Management (UAM) and roles, refer to:
@@ -21,6 +21,7 @@ The protocol functions that an AVS can set appointees for are:
2121
* [`AllocationManager.setAVSRegistrar`](https://github.com/Layr-Labs/eigenlayer-contracts/blob/dev/docs/core/AllocationManager.md#setavsregistrar)
2222
* [`AllocationManager.updateAVSMetadataURI`](https://github.com/Layr-Labs/eigenlayer-contracts/blob/dev/docs/core/AllocationManager.md#updateavsmetadatauri)
2323
* [`AllocationManager.createOperatorSets`](https://github.com/Layr-Labs/eigenlayer-contracts/blob/dev/docs/core/AllocationManager.md#createoperatorsets)
24+
* `AllocationManager.createRedistributingOperatorSets`
2425
* [`AllocationManager.addStrategiesToOperatorSet`](https://github.com/Layr-Labs/eigenlayer-contracts/blob/dev/docs/core/AllocationManager.md#addstrategiestooperatorset)
2526
* [`AllocationManager.removeStrategiesFromOperatorSet`](https://github.com/Layr-Labs/eigenlayer-contracts/blob/dev/docs/core/AllocationManager.md#removestrategiesfromoperatorset)
2627
* [`RewardsCoordinator.createOperatorDirectedAVSRewardsSubmission`](https://github.com/Layr-Labs/eigenlayer-contracts/blob/dev/docs/core/RewardsCoordinator.md#createoperatordirectedavsrewardssubmission)

‎docs/developers/HowTo/build/operator-sets/create-operator-sets.md

Lines changed: 30 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,45 @@
11
---
2-
sidebar_position: 1
2+
sidebar_position: 2
33
title: Create Operator Sets
44
---
55

66
:::tip
77
If you're new to Operator Sets in EigenLayer, review the [Operator Sets concepts](../../../../eigenlayer/concepts/operator-sets/operator-sets-concept.md) before continuing with this topic.
88
:::
99

10-
Creating Operator Sets for an AVS is managed by the [AllocationManager core contract](../../../Concepts/eigenlayer-contracts/core-contracts.md).
10+
Creating Operator Sets for an AVS is managed by the [AllocationManager core contract](../../../Concepts/eigenlayer-contracts/core-contracts.md). Before Operator Sets can be created,
11+
[AVS metadata must be registered](../register-avs-metadata.md).
12+
1113
[Strategies](../../../../eigenlayer/concepts/operator-sets/strategies-and-magnitudes) can be added to Operator Sets when the Operator is created, or Strategies can be added to an existing Operator Set.
1214

15+
Operator Sets are either:
16+
* [Non-redistributing](#create-operator-set). Slashed funds are burnt.
17+
* [Redistributing](#create-redistributing-operator-set). Slashed funds are sent to the [`redistributionRecipient`](../../../Concepts/slashing/slashing-concept-developers.md#redistribution-recipient).
18+
19+
The Operator Set type cannot be changed.
20+
21+
## Create Operator Set
22+
1323
To create an Operator Set, call the [`createOperatorSets`](https://github.com/Layr-Labs/eigenlayer-contracts/blob/9a19503e2a4467f0be938f72e80b11768b2e47f9/docs/core/AllocationManager.md#createoperatorsets) function.
1424
To add strategies when creating an Operator Set, specify a `params` array containing the strategies.
1525

16-
On creation, an `id` is assigned to the Operator Set. Together the AVS `address` and `id` are a unique identifier for the Operator Set.
26+
On creation, an `id` is assigned to the Operator Set. Together the AVS `address` and `id` are a unique identifier for the Operator Set.
27+
For non-redistributing Operator Sets, the `redistributionRecipient` is the `DEFAULT_BURN_ADDRESS`.
28+
29+
## Create Redistributing Operator Set
30+
31+
To create a redistributing Operator Set, call the `createRedistributingOperatorSets` function.
32+
33+
To add strategies when creating an Operator Set, specify a `params` array containing the strategies.
34+
Native ETH cannot be added as a strategy for redistributing Operator Sets because redistribution of native ETH is not supported.
35+
36+
Specify the address to receive slashed funds in `redistributionRecipients`. The `redistributionRecipient` can only be set
37+
when creating the Operator Set and cannot be changed.
38+
39+
On creation, an `id` is assigned to the Operator Set. Together the AVS `address` and `id` are a unique identifier for the Operator Set.
1740

18-
Once created, [update the AVS metadata](update-avs-metadata.md) to provide information on the Operator Set to Stakers and Operators.
41+
## Complete Operator Set Configuration
1942

20-
For information on adding Strategies to an Operator Set after creation, refer to [Modify Strategy Composition](modify-strategy-composition.md).
43+
Once created:
44+
1. [Update the AVS metadata](update-avs-metadata.md) to provide information on the Operator Set to Stakers and Operators.
45+
2. If required, [add additional Strategies](modify-strategy-composition.md) to the Operator Set.

‎docs/developers/HowTo/build/slashing/design-operator-set.md renamed to ‎docs/developers/HowTo/build/operator-sets/design-operator-set.md

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,21 @@
11
---
2-
sidebar_position: 3
2+
sidebar_position: 1
33
title: Design Operator Sets
44
---
55

66
An [Operator Set](../../../../eigenlayer/concepts/operator-sets/operator-sets-concept.md) is a grouping of different types of work within a single AVS. Each AVS has at least one Operator Set. The
77
EigenLayer protocol does not enforce criteria for Operator Sets.
88

9+
## Operator Set Types
10+
11+
Operator Sets are either:
12+
* [Non-redistributing](create-operator-sets.md#create-operator-set). Slashed funds are burnt.
13+
* [Redistributing](create-operator-sets.md#create-redistributing-operator-set). Slashed funds are sent to the [`redistributionRecipient`](../../../Concepts/slashing/slashing-concept-developers.md#redistribution-recipient).
14+
15+
The Operator Set type cannot be changed.
16+
17+
## Operator Set Groupings
18+
919
Best practices for Operator Set design are to logically group AVS tasks (and verification) into separate Operator Sets.
1020
Organize your Operator Sets according to conditions for which you wish to distribute Rewards. Potential conditions include:
1121
* Unique business logic.

‎docs/developers/HowTo/build/slashing/migrate-to-operatorsets.md renamed to ‎docs/developers/HowTo/build/operator-sets/migrate-to-operatorsets.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 2
2+
sidebar_position: 5
33
title: Migrate to Operator Sets
44
---
55

‎docs/developers/HowTo/build/operator-sets/modify-strategy-composition.md

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,14 @@
11
---
2-
sidebar_position: 2
2+
sidebar_position: 4
33
title: Modify Strategy Composition
44
---
55

66
An Operator Set requires at least one [Strategy](../../../../eigenlayer/concepts/operator-sets/strategies-and-magnitudes).
77

88
To add Strategies to an existing Operator Set, call the [`addStrategiesToOperatorSet`](https://github.com/Layr-Labs/eigenlayer-contracts/blob/9a19503e2a4467f0be938f72e80b11768b2e47f9/docs/core/AllocationManager.md#addstrategiestooperatorset) function.
99

10-
To remove Strategies from an Operator Set, call the [`removeStrategiesFromOperatorSet`](https://github.com/Layr-Labs/eigenlayer-contracts/blob/9a19503e2a4467f0be938f72e80b11768b2e47f9/docs/core/AllocationManager.md#removestrategiesfromoperatorset) function.
10+
To remove Strategies from an Operator Set, call the [`removeStrategiesFromOperatorSet`](https://github.com/Layr-Labs/eigenlayer-contracts/blob/9a19503e2a4467f0be938f72e80b11768b2e47f9/docs/core/AllocationManager.md#removestrategiesfromoperatorset) function.
11+
12+
:::note
13+
The Native Eth strategy cannot be added to Redistributing Operator Sets.
14+
:::

‎docs/developers/HowTo/build/slashing/implement-slashing.md

Lines changed: 24 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 1
2+
sidebar_position: 2
33
title: Implement Slashing
44
---
55

@@ -8,35 +8,12 @@ If you're new to slashing in EigenLayer, make sure you're familiar with [Operato
88
and [Slashing](../../../../eigenlayer/concepts/slashing/slashing-concept.md) before implementing slashing.
99
:::
1010

11-
The `AllocationManager` provides the interface for the slashing function.
12-
13-
```solidity
14-
/**
15-
* @notice Called by an AVS to slash an operator in a given operator set
16-
*/
17-
18-
function slashOperator(
19-
address avs,
20-
SlashingParams calldata params
21-
) external;
22-
23-
/**
24-
* @notice Struct containing parameters to slashing
25-
* @param operator the address to slash
26-
* @param operatorSetId the ID of the operatorSet the operator is being slashed on behalf of
27-
* @param strategies the set of strategies to slash
28-
* @param wadsToSlash the parts in 1e18 to slash, this will be proportional to the operator's
29-
* slashable stake allocation for the operatorSet
30-
* @param description the description of the slashing provided by the AVS for legibility
31-
*/
32-
struct SlashingParams {
33-
address operator;
34-
uint32 operatorSetId;
35-
IStrategy[] strategies;
36-
uint256[] wadsToSlash;
37-
string description;
38-
}
39-
```
11+
:::caution
12+
The v1.5.0 Redistribution release introduced the Slash Escrow Delay. All slashed funds are held in the `SlashEscrow` contracts
13+
for the Slash Escrow Delay before being burnt or redistributed.
14+
:::
15+
16+
The [`AllocationManager`](https://github.com/Layr-Labs/eigenlayer-contracts/blob/main/src/contracts/interfaces/IAllocationManager.sol) provides the interface for the `slashOperator` function.
4017

4118
To implement slashing, AVSs specify:
4219
* Individual Operator
@@ -45,13 +22,29 @@ To implement slashing, AVSs specify:
4522
* [List of proportions (as `wads` or “parts per `1e18`”)](../../../../eigenlayer/concepts/operator-sets/strategies-and-magnitudes)
4623
* Description.
4724

48-
For example, in the `wadsToSlash` parameter:
25+
## Define Slashing Proportions
26+
27+
In the `wadsToSlash` parameter:
4928
* 8% slash is represented as `8e16`, or `80000000000000000`.
5029
* 25% slash is represented as `2.5e17` or `250000000000000000`.
5130

5231
The indexes in the two arrays must match across `strategies` and `wadsToSlash`. All Strategies supplied must be configured
5332
as part of the Operator Set.
5433

34+
For more information on how magnitudes are reduced when slashed, refer to [Magnitudes when Slashed](../../../../eigenlayer/concepts/slashing/magnitudes-when-slashed.md).
35+
36+
## Define Upstream Redistribution Contracts
37+
38+
For redistributable Operator Sets, implement upstream contracts for [`redistributionRecipient`](../../../Concepts/slashing/slashing-concept-developers.md#redistribution-recipient)
39+
to redistribute slashed funds once they have exited the protocol.
40+
41+
## Returned by `slashOperator`
42+
43+
The `slashOperator` function returns the `slashId` and number of shares slashed for each strategy. The `slashId` is
44+
incremented for an OperatorSet each time an Operator Set is slashed. Use the `slashID` to programmatically handle slashings.
45+
46+
## Slashing Event Emission
47+
5548
When a slashing occurs, one event is emitted onchain for each slashing. Emitted details identify the Operator
5649
slashed, in what Operator Set, and across which Strategies, with fields for the proportion slashed and meta-data.
5750
```

‎docs/developers/HowTo/build/slashing/slashing-veto-committee-design.md

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
sidebar_position: 4
3-
title: Design Slashing Conditions
2+
sidebar_position: 1
3+
title: Design Slashing
44
---
55

66
## Slashing Vetoes
@@ -22,3 +22,9 @@ council or multisig address for the AVS. Please see the [vetoable slasher exampl
2222
Ensure that your slashing process can be resolved within the `DEALLOCATION_DELAY` time window. This is the amount of blocks
2323
between an Operator queuing a deallocation of stake from an Operator Set for a strategy and the deallocation taking effect.
2424
This will ensure that the slashing event is carried out for the Operator before their stake is deallocated.
25+
26+
## Redistribution
27+
28+
Redistribution may enable AVSs to benefit from a theft related to slashing so additional design care must be taken to consider
29+
the incentives of all parties interacting with the redistribution. Redistribution enables more use-case opportunities
30+
but the higher risk and slash incentive must be considered for the participants running the AVS code.

‎docs/developers/HowTo/build/submit-rewards-submissions.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ title: Submit Rewards Submissions
55

66
:::important
77
`RewardsCoordinator.createAVSRewardsSubmission` and `RewardsCoordinator.createOperatorDirectedAVSRewardsSubmission` use AVSDirectory.
8-
The AVSDirectory method will be deprecated in a future upgrade. [All AVSs will need to migrate to Operator Sets before the upcoming deprecation of AVSDirectory](slashing/migrate-to-operatorsets.md).
8+
The AVSDirectory method will be deprecated in a future upgrade. [All AVSs will need to migrate to Operator Sets before the upcoming deprecation of AVSDirectory](operator-sets/migrate-to-operatorsets.md).
99

1010
If you are currently using AVSDirectory, `RewardsCoordinator.createAVSRewardsSubmission` and `RewardsCoordinator.createOperatorDirectedAVSRewardsSubmission` can continue to be used while AVSDirectory is being used.
1111
:::

‎docs/eigenlayer/concepts/operator-sets/operator-sets-concept.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ title: Operator Sets Overview
88
[ELIP-002 Slashing via Unique Stake & Operator Sets](https://github.com/eigenfoundation/ELIPs/blob/main/ELIPs/ELIP-002.md) introduced Operator Sets.
99

1010

11-
Currently, Operators register to an AVS to earn rewards in the AVSDirectory. We recommend existing AVSs [migrate to Operator Sets on testnet](../../../developers/HowTo/build/slashing/migrate-to-operatorsets.md).
11+
Currently, Operators register to an AVS to earn rewards in the AVSDirectory. We recommend existing AVSs [migrate to Operator Sets on testnet](../../../developers/HowTo/build/operator-sets/migrate-to-operatorsets.md).
1212
:::
1313

1414
Operator Sets determine which Operators secure an AVS and earn rewards. Each AVS defines one or more Operator Sets that
@@ -25,7 +25,7 @@ according to any conditions set by that AVS.
2525

2626
## For AVS Developers
2727

28-
For information on designing Operator Sets, refer to [Design Operator Sets](../../../developers/HowTo/build/slashing/design-operator-set.md).
28+
For information on designing Operator Sets, refer to [Design Operator Sets](../../../developers/HowTo/build/operator-sets/design-operator-set.md).
2929

3030
## For Operators
3131

0 commit comments

Comments
 (0)