Redistribution for AVS developers

.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

docs/developers/Concepts/avs-keys.md

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

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

@@ -22,4 +22,5 @@ The list of security models is not exhaustive. The EigenLayer protocol provides
 AVSs have flexibility to design their protocols to slash for any reason. AVSs are encouraged to:
 * Create robust legibility and process around how their slashing is designed and individual slashing events. 
 * Clearly communicate slashing design and individual slashing events to their Operator and Staker communities. 
+* Make strong guarantees about how upstream contracts function for Redistributing Operator Sets to their Operator and Staker communities.
 :::

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

@@ -18,11 +18,8 @@ The EigenLayer core contracts are documented in the [eigenlayer-contracts](https
 | [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.                                         
 | [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.                                           
 | [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).          |
-| [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.                                                                                                                                                           | 
+| [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.                              
+| [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.                   | 
 
-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)
-on Testnet.
-
-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
-specific documentation, refer to the `/docs` repository on the `mainnet` branch in the [eigenlayer-contracts](https://github.com/Layr-Labs/eigenlayer-contracts)
-repository.
+This documentation matches the functionality available in [v1.5.0 of the core contracts](../../../eigenlayer/releases.md). For release specific
+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

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

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

@@ -5,7 +5,7 @@ title: User Access Management
 
 :::note
 There is no support for setting appointees for AVSDirectory functions. 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](../HowTo/build/slashing/migrate-to-operatorsets.md).
+[All AVSs will need to migrate to Operator Sets before the upcoming deprecation of AVSDirectory](../HowTo/build/operator-sets/migrate-to-operatorsets.md).
 :::
 
 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:
 * [`AllocationManager.setAVSRegistrar`](https://github.com/Layr-Labs/eigenlayer-contracts/blob/dev/docs/core/AllocationManager.md#setavsregistrar)
 * [`AllocationManager.updateAVSMetadataURI`](https://github.com/Layr-Labs/eigenlayer-contracts/blob/dev/docs/core/AllocationManager.md#updateavsmetadatauri)
 * [`AllocationManager.createOperatorSets`](https://github.com/Layr-Labs/eigenlayer-contracts/blob/dev/docs/core/AllocationManager.md#createoperatorsets)
+* `AllocationManager.createRedistributingOperatorSets`
 * [`AllocationManager.addStrategiesToOperatorSet`](https://github.com/Layr-Labs/eigenlayer-contracts/blob/dev/docs/core/AllocationManager.md#addstrategiestooperatorset)
 * [`AllocationManager.removeStrategiesFromOperatorSet`](https://github.com/Layr-Labs/eigenlayer-contracts/blob/dev/docs/core/AllocationManager.md#removestrategiesfromoperatorset)
 * [`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

@@ -1,20 +1,45 @@
 ---
-sidebar_position: 1
+sidebar_position: 2
 title: Create Operator Sets
 ---
 
 :::tip
 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.
 :::
 
-Creating Operator Sets for an AVS is managed by the [AllocationManager core contract](../../../Concepts/eigenlayer-contracts/core-contracts.md).
+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,
+[AVS metadata must be registered](../register-avs-metadata.md).
+
 [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.
 
+Operator Sets are either: 
+* [Non-redistributing](#create-operator-set). Slashed funds are burnt.
+* [Redistributing](#create-redistributing-operator-set). Slashed funds are sent to the [`redistributionRecipient`](../../../Concepts/slashing/slashing-concept-developers.md#redistribution-recipient).
+
+The Operator Set type cannot be changed.
+
+## Create Operator Set
+
 To create an Operator Set, call the [`createOperatorSets`](https://github.com/Layr-Labs/eigenlayer-contracts/blob/9a19503e2a4467f0be938f72e80b11768b2e47f9/docs/core/AllocationManager.md#createoperatorsets) function.
 To add strategies when creating an Operator Set, specify a `params` array containing the strategies.
 
-On creation, an `id` is assigned to the Operator Set. Together the AVS `address` and `id` are a unique identifier for the Operator Set. 
+On creation, an `id` is assigned to the Operator Set. Together the AVS `address` and `id` are a unique identifier for the Operator Set.
+For non-redistributing Operator Sets, the `redistributionRecipient` is the `DEFAULT_BURN_ADDRESS`.
+
+## Create Redistributing Operator Set
+
+To create a redistributing Operator Set, call the `createRedistributingOperatorSets` function.
+
+To add strategies when creating an Operator Set, specify a `params` array containing the strategies.
+Native ETH cannot be added as a strategy for redistributing Operator Sets because redistribution of native ETH is not supported.
+
+Specify the address to receive slashed funds in `redistributionRecipients`.  The `redistributionRecipient` can only be set 
+when creating the Operator Set and cannot be changed. 
+
+On creation, an `id` is assigned to the Operator Set. Together the AVS `address` and `id` are a unique identifier for the Operator Set.
 
-Once created, [update the AVS metadata](update-avs-metadata.md) to provide information on the Operator Set to Stakers and Operators.
+## Complete Operator Set Configuration
 
-For information on adding Strategies to an Operator Set after creation, refer to [Modify Strategy Composition](modify-strategy-composition.md).
+Once created:
+1. [Update the AVS metadata](update-avs-metadata.md) to provide information on the Operator Set to Stakers and Operators.
+2. If required, [add additional Strategies](modify-strategy-composition.md) to the Operator Set.

docs/developers/HowTo/build/slashing/design-operator-set.md → docs/developers/HowTo/build/operator-sets/design-operator-set.md

@@ -1,11 +1,21 @@
 ---
-sidebar_position: 3
+sidebar_position: 1
 title: Design Operator Sets
 ---
 
 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 
 EigenLayer protocol does not enforce criteria for Operator Sets.
 
+## Operator Set Types
+
+Operator Sets are either:
+* [Non-redistributing](create-operator-sets.md#create-operator-set). Slashed funds are burnt.
+* [Redistributing](create-operator-sets.md#create-redistributing-operator-set). Slashed funds are sent to the [`redistributionRecipient`](../../../Concepts/slashing/slashing-concept-developers.md#redistribution-recipient).
+
+The Operator Set type cannot be changed.
+
+## Operator Set Groupings
+
 Best practices for Operator Set design are to logically group AVS tasks (and verification) into separate Operator Sets. 
 Organize your Operator Sets according to conditions for which you wish to distribute Rewards. Potential conditions include:
 * Unique business logic.

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 5
 title: Migrate to Operator Sets
 ---
 

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

@@ -1,10 +1,14 @@
 ---
-sidebar_position: 2
+sidebar_position: 4
 title: Modify Strategy Composition
 ---
 
 An Operator Set requires at least one [Strategy](../../../../eigenlayer/concepts/operator-sets/strategies-and-magnitudes).
 
 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.
 
-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.
+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.
+
+:::note
+The Native Eth strategy cannot be added to Redistributing Operator Sets.
+:::

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 1
+sidebar_position: 2
 title: Implement Slashing
 ---
 
@@ -8,35 +8,12 @@ If you're new to slashing in EigenLayer, make sure you're familiar with [Operato
 and [Slashing](../../../../eigenlayer/concepts/slashing/slashing-concept.md) before implementing slashing.
 :::
 
-The `AllocationManager` provides the interface for the slashing function.
-
-```solidity
-    /**
-     * @notice Called by an AVS to slash an operator in a given operator set
-     */
-
-    function slashOperator(
-        address avs,
-        SlashingParams calldata params
-    ) external;
-
-    /**
-     * @notice Struct containing parameters to slashing
-     * @param operator the address to slash
-     * @param operatorSetId the ID of the operatorSet the operator is being slashed on behalf of
-     * @param strategies the set of strategies to slash
-     * @param wadsToSlash the parts in 1e18 to slash, this will be proportional to the operator's
-     * slashable stake allocation for the operatorSet
-     * @param description the description of the slashing provided by the AVS for legibility
-     */
-    struct SlashingParams {
-        address operator;
-        uint32 operatorSetId;
-        IStrategy[] strategies;
-        uint256[] wadsToSlash;
-        string description;
-    }
-```
+:::caution
+The v1.5.0 Redistribution release introduced the Slash Escrow Delay. All slashed funds are held in the `SlashEscrow` contracts
+for the Slash Escrow Delay before being burnt or redistributed.
+:::
+
+The [`AllocationManager`](https://github.com/Layr-Labs/eigenlayer-contracts/blob/main/src/contracts/interfaces/IAllocationManager.sol) provides the interface for the `slashOperator` function.
 
 To implement slashing, AVSs specify:
 * Individual Operator
@@ -45,13 +22,29 @@ To implement slashing, AVSs specify:
 * [List of proportions (as `wads` or “parts per `1e18`”)](../../../../eigenlayer/concepts/operator-sets/strategies-and-magnitudes)
 * Description. 
 
-For example, in the `wadsToSlash` parameter: 
+## Define Slashing Proportions
+
+In the `wadsToSlash` parameter: 
 * 8% slash is represented as `8e16`, or `80000000000000000`. 
 * 25% slash is represented as `2.5e17` or `250000000000000000`. 
 
 The indexes in the two arrays must match across `strategies` and `wadsToSlash`. All Strategies supplied must be configured 
 as part of the Operator Set.
 
+For more information on how magnitudes are reduced when slashed, refer to [Magnitudes when Slashed](../../../../eigenlayer/concepts/slashing/magnitudes-when-slashed.md).
+
+## Define Upstream Redistribution Contracts 
+
+For redistributable Operator Sets, implement upstream contracts for [`redistributionRecipient`](../../../Concepts/slashing/slashing-concept-developers.md#redistribution-recipient)
+to redistribute slashed funds once they have exited the protocol.
+
+## Returned by `slashOperator`
+
+The `slashOperator` function returns the `slashId` and number of shares slashed for each strategy. The `slashId` is 
+incremented for an OperatorSet each time an Operator Set is slashed. Use the `slashID` to programmatically handle slashings.
+
+## Slashing Event Emission
+
 When a slashing occurs, one event is emitted onchain for each slashing. Emitted details identify the Operator
 slashed, in what Operator Set, and across which Strategies, with fields for the proportion slashed and meta-data.
 ```

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

@@ -1,6 +1,6 @@
 ---
-sidebar_position: 4
-title: Design Slashing Conditions
+sidebar_position: 1
+title: Design Slashing
 ---
 
 ## Slashing Vetoes
@@ -22,3 +22,9 @@ council or multisig address for the AVS. Please see the [vetoable slasher exampl
 Ensure that your slashing process can be resolved within the `DEALLOCATION_DELAY` time window. This is the amount of blocks
 between an Operator queuing a deallocation of stake from an Operator Set for a strategy and the deallocation taking effect. 
 This will ensure that the slashing event is carried out for the Operator before their stake is deallocated.
+
+## Redistribution
+
+Redistribution may enable AVSs to benefit from a theft related to slashing so additional design care must be taken to consider
+the incentives of all parties interacting with the redistribution. Redistribution enables more use-case opportunities 
+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

@@ -5,7 +5,7 @@ title: Submit Rewards Submissions
 
 :::important
 `RewardsCoordinator.createAVSRewardsSubmission` and `RewardsCoordinator.createOperatorDirectedAVSRewardsSubmission` use AVSDirectory. 
-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).
+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).
 
 If you are currently using AVSDirectory, `RewardsCoordinator.createAVSRewardsSubmission` and `RewardsCoordinator.createOperatorDirectedAVSRewardsSubmission` can continue to be used while AVSDirectory is being used.
 :::

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

@@ -8,7 +8,7 @@ title: Operator Sets Overview
 [ELIP-002 Slashing via Unique Stake & Operator Sets](https://github.com/eigenfoundation/ELIPs/blob/main/ELIPs/ELIP-002.md) introduced Operator Sets.
 
 
-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). 
+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). 
 :::
 
 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.
 
 ## For AVS Developers
 
-For information on designing Operator Sets, refer to [Design Operator Sets](../../../developers/HowTo/build/slashing/design-operator-set.md).
+For information on designing Operator Sets, refer to [Design Operator Sets](../../../developers/HowTo/build/operator-sets/design-operator-set.md).
 
 ## For Operators