EVM Script Factories for VaultHub and OperatorGrid

# EVM Script Factories for VaultHub and OperatorGrid ## References - [GitHub Pull Request](https://github.com/lidofinance/easy-track/pull/86) with the new factories ## Introduction This document describes the implementation details of EasyTrack EVM factories to manage instances of the VaultHub and OperatorGrid contracts. The proposed changes will grant EasyTrack's `EvmScriptExecutor` the rights to modify both the VaultHub and OperatorGrid via the introduced EVM script factories. The new VMC and VCC committees will receive the rights to initiate EasyTrack motions. The high-level overview of the management flow is presented in the below diagram. ![Diagram](https://hackmd.io/_uploads/S1J2kli2lg.jpg) ## Committees ### Vaults Connecting Committee (VCC) To offload the Lido DAO from routine operations related to the management of VaultHub and OperatorGrid contracts, it is proposed to create a specialized committee (VCC - Vaults Connecting Committee). The participants of the Vaults Connecting Committee (VCC) will form a Gnosis Safe multisig that will manage VaultHub and OperatorGrid contracts using the EasyTrack process. Participants of the Vaults Connecting Committee (VCC) will be elected by the Lido DAO. The VCC will make decisions about adding new groups/tiers or modifying parameters of existing ones based on the [Risk Framework for Vaults document](https://research.lido.fi/t/risk-assessment-framework-for-stvaults/9978). This document details the parameters and safety limits for managing Lido stVaults. ### Vaults Managing Committee (VMC) To offload the Lido DAO from routine operations related to the management of the VaultHub contract, it is proposed to create a specialized committee (VMC - Vaults Managing Committee). The participants of the Vaults Managing Committee (VMC) will form a Gnosis Safe multisig that will manage the VaultHub contract using the EasyTrack process. Participants of the Vaults Managing Committee (VMC) will be elected by the Lido DAO. The VMC will make decisions about updating share limits and fees for vaults based on the [Risk Framework for Vaults document](https://research.lido.fi/t/risk-assessment-framework-for-stvaults/9978). This document details the parameters and safety limits for managing Lido stVaults. ## Rights & Permissions For the introduced EVM script factories to operate properly, it is required to give specific roles to EasyTrack's `EvmScriptExecutor` in the respective contracts. | Role | EVM Script Factory | Methods | Committee | | --------- | --------------------------------------------- | --------------------------- | --------- | | `REGISTRY_ROLE` | [RegisterGroupsInOperatorGrid](#RegisterGroupsInOperatorGrid) | `registerGroup`, `registerTiers` | VCC | | `REGISTRY_ROLE` | [UpdateGroupsShareLimitInOperatorGrid](#UpdateGroupsShareLimitInOperatorGrid) | `updateGroupShareLimit` | VCC | | `REGISTRY_ROLE` | [RegisterTiersInOperatorGrid](#RegisterTiersInOperatorGrid) | `registerTiers` | VCC | | `REGISTRY_ROLE` | [AlterTiersInOperatorGrid](#AlterTiersInOperatorGrid) | `alterTiers` | VCC | | `REGISTRY_ROLE` | [UpdateVaultsFeesInOperatorGrid](#UpdateVaultsFeesInOperatorGrid) | `updateVaultFees` | VCC | | `REGISTRY_ROLE` | [SetJailStatusInOperatorGrid](#SetJailStatusInOperatorGrid) | `setVaultJailStatus` | VCC | | `VALIDATOR_EXIT_ROLE` | [ForceValidatorExitsInVaultHub](#ForceValidatorExitsInVaultHub) | `forceValidatorExit` | VMC | | `REDEMPTION_MASTER_ROLE` | [SetLiabilitySharesTargetInVaultHub](#SetLiabilitySharesTargetInVaultHub) | `setLiabilitySharesTarget` | VMC | | `BAD_DEBT_MASTER_ROLE` | [SocializeBadDebtInVaultHub](#SocializeBadDebtInVaultHub) | `socializeBadDebt` | VMC | ## RegisterGroupsInOperatorGrid - **inherits**: [TrustedCaller](https://github.com/lidofinance/easy-track/blob/master/specification.md#trustedcaller) - **implements**: [IEVMScriptFactory](https://github.com/lidofinance/easy-track/blob/master/specification.md#ievmscriptfactory) Allows creation of EVM script to register multiple groups and their tiers in the instance of the [`OperatorGrid`](https://github.com/lidofinance/core/blob/feat/vaults/contracts/0.8.25/vaults/OperatorGrid.sol). ### Data Types No additional data types are required, using the structs from the Operator Grid interface: ```solidity interface IOperatorGrid { struct Group { address operator; uint96 shareLimit; uint96 liabilityShares; uint256[] tierIds; } struct TierParams { uint256 shareLimit; uint256 reserveRatioBP; uint256 forcedRebalanceThresholdBP; uint256 infraFeeBP; uint256 liquidityFeeBP; uint256 reservationFeeBP; } } ``` ### Immutable Variables - `ILidoLocator lidoLocator` - address of the instance of the `LidoLocator` - `uint256 maxShareLimit` - maximum sane share limit (percent from Lido total shares) ### Methods #### createEVMScript(address,bytes) - **Arguments**: - `address _creator` - the creator of the EVM Script - `bytes memory _evmScriptCallData` - an ABI encoded tuple `(address[] nodeOperators, uint256[] shareLimits, IOperatorGrid.TierParams[][] tiers)` - **Visibility**: `external` - **Mutability**: `view` - **Modifiers**: [onlyTrustedCaller(_creator)](https://github.com/lidofinance/easy-track/blob/master/specification.md#storage-variables-3) - **Returns**: `(bytes memory)` Creates an EVM script to register multiple groups and their tiers in the instance of the [`OperatorGrid`](https://github.com/lidofinance/core/blob/feat/vaults/contracts/0.8.25/vaults/OperatorGrid.sol). This function will be called by the EasyTrack when the motion is created and then again when it is enacted. To successfully create and enact motion, the following onchain requirements must be met: 1. The node operators array **MUST NOT** be empty and its length **MUST** match the share limits and tiers arrays. 2. The node operators array **MUST** be sorted in ascending order and **MUST NOT** contain duplicate entries. 3. Each node operator **MUST NOT** be a zero address and **MUST NOT** already exist in the OperatorGrid. 4. Each node operator **MUST NOT** be equal to the `DEFAULT_TIER_OPERATOR` special address. 5. The share limits **MUST NOT** exceed a calculated maximum sane share limit. 6. The tiers array for each node operator **MUST NOT** be empty. 7. Each tier's share limit **MUST NOT** exceed the group's share limit. 8. The reserve ratio basis points **MUST NOT** be zero and **MUST NOT** exceed total basis points. 9. The forced rebalance threshold basis points **MUST NOT** be zero and **MUST** be less than the reserve ratio by 10 basis points. 10. The infrastructure fee, liquidity fee, and reservation fee basis points **MUST NOT** exceed maximum fee basis points. Note: The input data **MUST** be decoded successfully into a tuple `(address[] nodeOperators, uint256[] shareLimits, IOperatorGrid.TierParams[][] tiers)` for the function to operate correctly. #### decodeEVMScriptCallData(bytes) - **Arguments**: - `bytes memory _evmScriptCallData` - an ABI encoded tuple `(address[] nodeOperators, uint256[] shareLimits, IOperatorGrid.TierParams[][] tiers)` - **Visibility**: `external` - **Mutability**: `pure` - **Returns**: `(address[], uint256[], IOperatorGrid.TierParams[][])` Decodes `_evmScriptCallData` into tuple `(address[] nodeOperators, uint256[] shareLimits, IOperatorGrid.TierParams[][] tiers)`. ## UpdateGroupsShareLimitInOperatorGrid - **inherits**: [TrustedCaller](https://github.com/lidofinance/easy-track/blob/master/specification.md#trustedcaller) - **implements**: [IEVMScriptFactory](https://github.com/lidofinance/easy-track/blob/master/specification.md#ievmscriptfactory) Allows creation of EVM script to update share limits of multiple groups in the instance of the [`OperatorGrid`](https://github.com/lidofinance/core/blob/feat/vaults/contracts/0.8.25/vaults/OperatorGrid.sol). ### Data Types No additional data types are required, using the structs from the Operator Grid interface: ```solidity interface IOperatorGrid { struct Group { address operator; uint96 shareLimit; uint96 liabilityShares; uint256[] tierIds; } } ``` ### Immutable Variables - `ILidoLocator lidoLocator` - address of the instance of the `LidoLocator` - `uint256 maxShareLimit` - maximum sane share limit (percent from Lido total shares) ### Methods #### createEVMScript(address,bytes) - **Arguments**: - `address _creator` - the creator of the EVM Script - `bytes memory _evmScriptCallData` - an ABI encoded tuple `(address[] nodeOperators, uint256[] shareLimits)` - **Visibility**: `external` - **Mutability**: `view` - **Modifiers**: [onlyTrustedCaller(_creator)](https://github.com/lidofinance/easy-track/blob/master/specification.md#storage-variables-3) - **Returns**: `(bytes memory)` Creates an EVM script to update share limits of multiple groups in the instance of the [`OperatorGrid`](https://github.com/lidofinance/core/blob/feat/vaults/contracts/0.8.25/vaults/OperatorGrid.sol). This function will be called by the EasyTrack when the motion is created and then again when it is enacted. To successfully create and enact motion, the following onchain requirements must be met: 1. The node operators array **MUST NOT** be empty 2. The node operators array length **MUST** match the share limits array length 3. All node operator addresses **MUST NOT** be zero address 4. All share limits **MUST NOT** exceed the maximum sane share limit 5. All groups **MUST** already exist in the operator grid Note: The input data **MUST** be decoded successfully into a tuple `(address[] nodeOperators, uint256[] shareLimits)` for the function to operate correctly. #### decodeEVMScriptCallData(bytes) - **Arguments**: - `bytes memory _evmScriptCallData` - an ABI encoded tuple `(address[] nodeOperators, uint256[] shareLimits)` - **Visibility**: `external` - **Mutability**: `pure` - **Returns**: `(address[], uint256[])` Decodes `_evmScriptCallData` into tuple `(address[] nodeOperators, uint256[] shareLimits)`. ## RegisterTiersInOperatorGrid - **inherits**: [TrustedCaller](https://github.com/lidofinance/easy-track/blob/master/specification.md#trustedcaller) - **implements**: [IEVMScriptFactory](https://github.com/lidofinance/easy-track/blob/master/specification.md#ievmscriptfactory) Allows creation of EVM script to register multiple tiers for multiple groups in the instance of the [`OperatorGrid`](https://github.com/lidofinance/core/blob/feat/vaults/contracts/0.8.25/vaults/OperatorGrid.sol). ### Data Types No additional data types are required, using the structs from the Operator Grid interface: ```solidity interface IOperatorGrid { struct TierParams { uint256 shareLimit; uint256 reserveRatioBP; uint256 forcedRebalanceThresholdBP; uint256 infraFeeBP; uint256 liquidityFeeBP; uint256 reservationFeeBP; } } ``` ### Immutable Variables - `ILidoLocator lidoLocator` - address of the instance of the `LidoLocator` ### Methods #### createEVMScript(address,bytes) - **Arguments**: - `address _creator` - the creator of the EVM Script - `bytes memory _evmScriptCallData` - an ABI encoded tuple `(address[] nodeOperators, IOperatorGrid.TierParams[][] tiers)` - **Visibility**: `external` - **Mutability**: `view` - **Modifiers**: [onlyTrustedCaller(_creator)](https://github.com/lidofinance/easy-track/blob/master/specification.md#storage-variables-3) - **Returns**: `(bytes memory)` Creates an EVM script to register multiple tiers for multiple groups in the instance of the [`OperatorGrid`](https://github.com/lidofinance/core/blob/feat/vaults/contracts/0.8.25/vaults/OperatorGrid.sol). This function will be called by the EasyTrack when the motion is created and then again when it is enacted. To successfully create and enact motion, the following onchain requirements must be met: 1. The node operators array **MUST NOT** be empty 2. The node operators array length **MUST** match the tiers array length 3. All node operator addresses **MUST NOT** be zero address 4. All node operator addresses **MUST NOT** be equal to the `DEFAULT_TIER_OPERATOR` special address 5. All groups **MUST** already exist in the operator grid 6. All tiers arrays **MUST NOT** be empty 7. Each tier's share limit **MUST NOT** exceed the group's share limit 8. The reserve ratio basis points **MUST NOT** be zero and **MUST NOT** exceed total basis points 9. The forced rebalance threshold basis points **MUST NOT** be zero and **MUST** be less than the reserve ratio by 10 basis points 10. The infrastructure fee, liquidity fee, and reservation fee basis points **MUST NOT** exceed maximum fee basis points Note: The input data **MUST** be decoded successfully into a tuple `(address[] nodeOperators, IOperatorGrid.TierParams[][] tiers)` for the function to operate correctly. #### decodeEVMScriptCallData(bytes) - **Arguments**: - `bytes memory _evmScriptCallData` - an ABI encoded tuple `(address[] nodeOperators, IOperatorGrid.TierParams[][] tiers)` - **Visibility**: `external` - **Mutability**: `pure` - **Returns**: `(address[], IOperatorGrid.TierParams[][])` Decodes `_evmScriptCallData` into tuple `(address[] nodeOperators, IOperatorGrid.TierParams[][] tiers)`. ## AlterTiersInOperatorGrid - **inherits**: [TrustedCaller](https://github.com/lidofinance/easy-track/blob/master/specification.md#trustedcaller) - **implements**: [IEVMScriptFactory](https://github.com/lidofinance/easy-track/blob/master/specification.md#ievmscriptfactory) Allows creation of EVM script to alter multiple tiers in the instance of the [`OperatorGrid`](https://github.com/lidofinance/core/blob/feat/vaults/contracts/0.8.25/vaults/OperatorGrid.sol). ### Data Types No additional data types are required, using the structs from the Operator Grid interface: ```solidity interface IOperatorGrid { struct TierParams { uint256 shareLimit; uint256 reserveRatioBP; uint256 forcedRebalanceThresholdBP; uint256 infraFeeBP; uint256 liquidityFeeBP; uint256 reservationFeeBP; } } ``` ### Immutable Variables - `ILidoLocator lidoLocator` - address of the instance of the `LidoLocator` ### Methods #### createEVMScript(address,bytes) - **Arguments**: - `address _creator` - the creator of the EVM Script - `bytes memory _evmScriptCallData` - an ABI encoded tuple `(uint256[] tierIds, IOperatorGrid.TierParams[] tierParams)` - **Visibility**: `external` - **Mutability**: `view` - **Modifiers**: [onlyTrustedCaller(_creator)](https://github.com/lidofinance/easy-track/blob/master/specification.md#storage-variables-3) - **Returns**: `(bytes memory)` Creates an EVM script to alter multiple tiers in the instance of the [`OperatorGrid`](https://github.com/lidofinance/core/blob/feat/vaults/contracts/0.8.25/vaults/OperatorGrid.sol). This function will be called by the EasyTrack when the motion is created and then again when it is enacted. To successfully create and enact motion, the following onchain requirements must be met: 1. The tier IDs array **MUST NOT** be empty 2. The tier IDs array length **MUST** match the tier params array length 3. All tier IDs **MUST** exist in the operator grid 4. Each tier's share limit **MUST NOT** exceed the group's share limit 5. The reserve ratio basis points **MUST NOT** be zero and **MUST NOT** exceed total basis points 6. The forced rebalance threshold basis points **MUST NOT** be zero and **MUST** be less than the reserve ratio by 10 basis points 7. The infrastructure fee, liquidity fee, and reservation fee basis points **MUST NOT** exceed maximum fee basis points Note: The input data **MUST** be decoded successfully into a tuple `(uint256[] tierIds, IOperatorGrid.TierParams[] tierParams)` for the function to operate correctly. #### decodeEVMScriptCallData(bytes) - **Arguments**: - `bytes memory _evmScriptCallData` - an ABI encoded tuple `(uint256[] tierIds, IOperatorGrid.TierParams[] tierParams)` - **Visibility**: `external` - **Mutability**: `pure` - **Returns**: `(uint256[], IOperatorGrid.TierParams[])` Decodes `_evmScriptCallData` into tuple `(uint256[] tierIds, IOperatorGrid.TierParams[] tierParams)`. ## UpdateVaultsFeesInOperatorGrid - **inherits**: [TrustedCaller](https://github.com/lidofinance/easy-track/blob/master/specification.md#trustedcaller) - **implements**: [IEVMScriptFactory](https://github.com/lidofinance/easy-track/blob/master/specification.md#ievmscriptfactory) Allows creation of EVM script to update fees for multiple vaults in the instance of the [`OperatorGrid`](https://github.com/lidofinance/core/blob/feat/vaults/contracts/0.8.25/vaults/OperatorGrid.sol) via [VaultsAdapter](#VaultsAdapter). ### Data Types No additional data types are required, using the structs from the VaultHub interface: ```solidity interface IVaultHub { struct VaultConnection { address owner; uint96 shareLimit; uint96 vaultIndex; uint48 disconnectInitiatedTs; uint16 reserveRatioBP; uint16 forcedRebalanceThresholdBP; uint16 infraFeeBP; uint16 liquidityFeeBP; uint16 reservationFeeBP; bool isBeaconDepositsManuallyPaused; } } ``` ### Immutable Variables - `IVaultsAdapter vaultsAdapter` - address of the instance of the `VaultsAdapter` - `ILidoLocator lidoLocator` - address of the instance of the `LidoLocator` ### Methods #### createEVMScript(address,bytes) - **Arguments**: - `address _creator` - the creator of the EVM Script - `bytes memory _evmScriptCallData` - an ABI encoded tuple `(address[] vaults, uint256[] infraFeesBP, uint256[] liquidityFeesBP, uint256[] reservationFeesBP)` - **Visibility**: `external` - **Mutability**: `view` - **Modifiers**: [onlyTrustedCaller(_creator)](https://github.com/lidofinance/easy-track/blob/master/specification.md#storage-variables-3) - **Returns**: `(bytes memory)` Creates an EVM script to update fees for multiple vaults in the instance of the [`OperatorGrid`](https://github.com/lidofinance/core/blob/feat/vaults/contracts/0.8.25/vaults/OperatorGrid.sol) via [VaultsAdapter](#VaultsAdapter). This function will be called by the EasyTrack when the motion is created and then again when it is enacted. To successfully create and enact motion, the following onchain requirements must be met: 1. The vaults array **MUST NOT** be empty 2. All arrays **MUST** have the same length 3. All vault addresses **MUST NOT** be zero address 4. All fee values **MUST NOT** exceed the corresponding tier fees for each vault Additional requirements enforced by [VaultsAdapter](#VaultsAdapter): The following conditions **SHOULD** be met for each vault. If a vault does not meet these conditions, it will be skipped and a `VaultFeesUpdateFailed` event will be emitted, but the operation will continue for other vaults: 5. Each vault **SHOULD** be connected in the VaultHub and **SHOULD NOT** be pending disconnect Note: The input data **MUST** be decoded successfully into a tuple `(address[] vaults, uint256[] infraFeesBP, uint256[] liquidityFeesBP, uint256[] reservationFeesBP)` for the function to operate correctly. #### decodeEVMScriptCallData(bytes) - **Arguments**: - `bytes memory _evmScriptCallData` - an ABI encoded tuple `(address[] vaults, uint256[] infraFeesBP, uint256[] liquidityFeesBP, uint256[] reservationFeesBP)` - **Visibility**: `external` - **Mutability**: `pure` - **Returns**: `(address[], uint256[], uint256[], uint256[])` Decodes `_evmScriptCallData` into tuple `(address[] vaults, uint256[] infraFeesBP, uint256[] liquidityFeesBP, uint256[] reservationFeesBP)`. ## SetJailStatusInOperatorGrid - **inherits**: [TrustedCaller](https://github.com/lidofinance/easy-track/blob/master/specification.md#trustedcaller) - **implements**: [IEVMScriptFactory](https://github.com/lidofinance/easy-track/blob/master/specification.md#ievmscriptfactory) Allows creation of EVM script to set jail status for multiple vaults in the instance of the [`OperatorGrid`](https://github.com/lidofinance/core/blob/feat/vaults/contracts/0.8.25/vaults/OperatorGrid.sol) via [VaultsAdapter](#VaultsAdapter). ### Data Types No additional data types are required. ### Immutable Variables - `IVaultsAdapter vaultsAdapter` - address of the instance of the `VaultsAdapter` ### Methods #### createEVMScript(address,bytes) - **Arguments**: - `address _creator` - the creator of the EVM Script - `bytes memory _evmScriptCallData` - an ABI encoded tuple `(address[] vaults, bool[] jailStatuses)` - **Visibility**: `external` - **Mutability**: `view` - **Modifiers**: [onlyTrustedCaller(_creator)](https://github.com/lidofinance/easy-track/blob/master/specification.md#storage-variables-3) - **Returns**: `(bytes memory)` Creates an EVM script to set jail status for multiple vaults in the instance of the [`OperatorGrid`](https://github.com/lidofinance/core/blob/feat/vaults/contracts/0.8.25/vaults/OperatorGrid.sol) via [VaultsAdapter](#VaultsAdapter). This function will be called by the EasyTrack when the motion is created and then again when it is enacted. To successfully create and enact motion, the following onchain requirements must be met: 1. The vaults array **MUST NOT** be empty 2. The vaults array length **MUST** match the jail statuses array length 3. All vault addresses **MUST NOT** be zero address 4. All vaults **MUST** belong to the same node operator Additional requirements enforced by [VaultsAdapter](#VaultsAdapter): The following conditions **SHOULD** be met for each vault. If a vault does not meet these conditions, it will be skipped and a `VaultJailStatusUpdateFailed` event will be emitted, but the operation will continue for other vaults: 5. The new jail status **SHOULD** be different from the current status Note: The input data **MUST** be decoded successfully into a tuple `(address[] vaults, bool[] jailStatuses)` for the function to operate correctly. #### decodeEVMScriptCallData(bytes) - **Arguments**: - `bytes memory _evmScriptCallData` - an ABI encoded tuple `(address[] vaults, bool[] jailStatuses)` - **Visibility**: `external` - **Mutability**: `pure` - **Returns**: `(address[], bool[])` Decodes `_evmScriptCallData` into tuple `(address[] vaults, bool[] jailStatuses)`. ## ForceValidatorExitsInVaultHub - **inherits**: [TrustedCaller](https://github.com/lidofinance/easy-track/blob/master/specification.md#trustedcaller) - **implements**: [IEVMScriptFactory](https://github.com/lidofinance/easy-track/blob/master/specification.md#ievmscriptfactory) Allows creation of EVM script to force validator exits for multiple vaults in the instance of the [`VaultHub`](https://github.com/lidofinance/core/blob/feat/vaults/contracts/0.8.25/vaults/VaultHub.sol) via [VaultsAdapter](#VaultsAdapter). ### Data Types No additional data types are required. ### Immutable Variables - `IVaultsAdapter vaultsAdapter` - address of the instance of the `VaultsAdapter` ### Methods #### createEVMScript(address,bytes) - **Arguments**: - `address _creator` - the creator of the EVM Script - `bytes memory _evmScriptCallData` - an ABI encoded tuple `(address[] vaults, bytes[] pubkeys)` - **Visibility**: `external` - **Mutability**: `view` - **Modifiers**: [onlyTrustedCaller(_creator)](https://github.com/lidofinance/easy-track/blob/master/specification.md#storage-variables-3) - **Returns**: `(bytes memory)` Creates an EVM script to force validator exits for multiple vaults in the instance of the [`VaultHub`](https://github.com/lidofinance/core/blob/feat/vaults/contracts/0.8.25/vaults/VaultHub.sol) via [VaultsAdapter](#VaultsAdapter). This function will be called by the EasyTrack when the motion is created and then again when it is enacted. To successfully create and enact motion, the following onchain requirements must be met: 1. The vaults array **MUST NOT** be empty 2. The vaults array length **MUST** match the pubkeys array length 3. All vault addresses **MUST NOT** be zero address 4. All pubkeys arrays **MUST NOT** be empty 5. All pubkeys arrays **MUST** have a length that is a multiple of 48 bytes (the length of a single validator public key) 6. The validator exit fee **MUST NOT** exceed the validator exit fee limit set in the VaultsAdapter 7. The VaultsAdapter **MUST** have enough balance to cover the calculated withdrawal fee for the number of keys Additional requirements enforced by [VaultsAdapter](#VaultsAdapter): The following conditions **SHOULD** be met for each vault. If a vault does not meet these conditions, it will be skipped and a `ForceValidatorExitFailed` event will be emitted, but the operation will continue for other vaults: 8. Each vault **SHOULD** be connected in the VaultHub and **SHOULD NOT** be pending disconnect 9. Each vault **SHOULD** have a non-zero obligations shortfall value Note: The input data **MUST** be decoded successfully into a tuple `(address[] vaults, bytes[] pubkeys)` for the function to operate correctly. #### decodeEVMScriptCallData(bytes) - **Arguments**: - `bytes memory _evmScriptCallData` - an ABI encoded tuple `(address[] vaults, bytes[] pubkeys)` - **Visibility**: `external` - **Mutability**: `pure` - **Returns**: `(address[], bytes[])` Decodes `_evmScriptCallData` into tuple `(address[] vaults, bytes[] pubkeys)`. ## SetLiabilitySharesTargetInVaultHub - **inherits**: [TrustedCaller](https://github.com/lidofinance/easy-track/blob/master/specification.md#trustedcaller) - **implements**: [IEVMScriptFactory](https://github.com/lidofinance/easy-track/blob/master/specification.md#ievmscriptfactory) Allows creation of EVM script to set liability shares target for multiple vaults in the instance of the `VaultHub` via [VaultsAdapter](#VaultsAdapter). ### Data Types No additional data types are required. ### Immutable Variables - `IVaultsAdapter vaultsAdapter` - address of the instance of the `VaultsAdapter` ### Methods #### createEVMScript(address,bytes) - **Arguments**: - `address _creator` - the creator of the EVM Script - `bytes memory _evmScriptCallData` - an ABI encoded tuple `(address[] vaults, uint256[] liabilitySharesTargets)` - **Visibility**: `external` - **Mutability**: `view` - **Modifiers**: [onlyTrustedCaller(_creator)](https://github.com/lidofinance/easy-track/blob/master/specification.md#storage-variables-3) - **Returns**: `(bytes memory)` Creates an EVM script to set liability shares target for multiple vaults in the instance of the `VaultHub` via [VaultsAdapter](#VaultsAdapter). This function will be called by the EasyTrack when the motion is created and then again when it is enacted. To successfully create and enact motion, the following onchain requirements must be met: 1. The vaults array **MUST NOT** be empty 2. The vaults array length **MUST** match the liability shares targets array length 3. All vault addresses **MUST NOT** be zero address Additional requirements enforced by [VaultsAdapter](#VaultsAdapter): The following conditions **SHOULD** be met for each vault. If a vault does not meet these conditions, it will be skipped and a `LiabilitySharesTargetUpdateFailed` event will be emitted, but the operation will continue for other vaults: 4. Each vault **SHOULD** be connected in the VaultHub and **SHOULD NOT** be pending disconnect Note: The input data **MUST** be decoded successfully into a tuple `(address[] vaults, uint256[] liabilitySharesTargets)` for the function to operate correctly. #### decodeEVMScriptCallData(bytes) - **Arguments**: - `bytes memory _evmScriptCallData` - an ABI encoded tuple `(address[] vaults, uint256[] liabilitySharesTargets)` - **Visibility**: `external` - **Mutability**: `pure` - **Returns**: `(address[], uint256[])` Decodes `_evmScriptCallData` into tuple `(address[] vaults, uint256[] liabilitySharesTargets)`. ## SocializeBadDebtInVaultHub - **inherits**: [TrustedCaller](https://github.com/lidofinance/easy-track/blob/master/specification.md#trustedcaller) - **implements**: [IEVMScriptFactory](https://github.com/lidofinance/easy-track/blob/master/specification.md#ievmscriptfactory) Allows creation of EVM script to socialize bad debt for multiple vaults in the instance of the `VaultHub` via [VaultsAdapter](#VaultsAdapter). ### Data Types No additional data types are required. ### Immutable Variables - `IVaultsAdapter vaultsAdapter` - address of the instance of the `VaultsAdapter` ### Methods #### createEVMScript(address,bytes) - **Arguments**: - `address _creator` - the creator of the EVM Script - `bytes memory _evmScriptCallData` - an ABI encoded tuple `(address[] badDebtVaults, address[] vaultAcceptors, uint256[] maxSharesToSocialize)` - **Visibility**: `external` - **Mutability**: `view` - **Modifiers**: [onlyTrustedCaller(_creator)](https://github.com/lidofinance/easy-track/blob/master/specification.md#storage-variables-3) - **Returns**: `(bytes memory)` Creates an EVM script to socialize bad debt for multiple vaults in the instance of the `VaultHub` via [VaultsAdapter](#VaultsAdapter). This function will be called by the EasyTrack when the motion is created and then again when it is enacted. To successfully create and enact motion, the following onchain requirements must be met: 1. The bad debt vaults array **MUST NOT** be empty 2. The bad debt vaults array length **MUST** match the vault acceptors and max shares to socialize arrays length 3. All vault addresses **MUST NOT** be zero address 4. All acceptor addresses **MUST NOT** be zero address 5. Max shares to socialize values **MUST NOT** be zero 6. Each bad debt vault and its corresponding acceptor vault **MUST** belong to the same node operator Additional requirements enforced by [VaultsAdapter](#VaultsAdapter): The following conditions **SHOULD** be met for each vault pair. If a vault pair does not meet these conditions, it will be skipped and a `BadDebtSocializationFailed` event will be emitted, but the operation will continue for other vault pairs: 7. Each bad debt vault and its corresponding acceptor vault **SHOULD** be connected in the VaultHub and **SHOULD NOT** be pending disconnect Note: The input data **MUST** be decoded successfully into a tuple `(address[] badDebtVaults, address[] vaultAcceptors, uint256[] maxSharesToSocialize)` for the function to operate correctly. #### decodeEVMScriptCallData(bytes) - **Arguments**: - `bytes memory _evmScriptCallData` - an ABI encoded tuple `(address[] badDebtVaults, address[] vaultAcceptors, uint256[] maxSharesToSocialize)` - **Visibility**: `external` - **Mutability**: `pure` - **Returns**: `(address[], address[], uint256[])` Decodes `_evmScriptCallData` into tuple `(address[] badDebtVaults, address[] vaultAcceptors, uint256[] maxSharesToSocialize)`. ## VaultsAdapter - **inherits**: [TrustedCaller](https://github.com/lidofinance/easy-track/blob/master/specification.md#trustedcaller) The VaultsAdapter serves as an intermediary contract for interacting with the VaultHub and OperatorGrid from EVM Script Factories. It implements graceful error handling for batch operations, allowing other calls to continue executing even if one fails. This is crucial for maintaining the integrity of multi-vault operations in EasyTrack motions. ### Key Features - **Graceful Error Handling**: Uses try-catch mechanisms to prevent single vault failures from affecting other operations in the same batch - **Access Control**: Only the EVMScriptExecutor can call the adapter functions - **Validation Logic**: Performs pre-checks before calling VaultHub/OperatorGrid methods to emit informative events on failures - **ETH Management**: Can receive and withdraw ETH for validator exit operations - **Dynamic Contract Resolution**: Uses LidoLocator to dynamically resolve VaultHub and OperatorGrid addresses ### Immutable Variables - `ILidoLocator lidoLocator` - address of the instance of the `LidoLocator` - `address evmScriptExecutor` - address of the EVMScriptExecutor that is allowed to call adapter functions ### State Variables - `uint256 validatorExitFeeLimit` - maximum allowed fee for validator exits (can be updated by trusted caller) ### Constants - `uint256 PUBLIC_KEY_LENGTH = 48` - length of validator public keys in bytes - `address WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS = 0x00000961Ef480Eb55e80D19ad83579A64c007002` - EIP-7002 predeploy address for withdrawal requests ### Events - `VaultFeesUpdateFailed(address indexed vault, uint256 infraFeeBP, uint256 liquidityFeeBP, uint256 reservationFeeBP)` - emitted when vault fees update fails - `VaultJailStatusUpdateFailed(address indexed vault, bool isInJail)` - emitted when jail status update fails - `LiabilitySharesTargetUpdateFailed(address indexed vault, uint256 liabilitySharesTarget)` - emitted when liability shares target update fails - `BadDebtSocializationFailed(address indexed badDebtVault, address indexed vaultAcceptor, uint256 maxSharesToSocialize)` - emitted when bad debt socialization fails - `ForceValidatorExitFailed(address indexed vault, bytes pubkeys)` - emitted when validator exit fails - `ValidatorExitFeeLimitUpdated(uint256 oldFee, uint256 newFee)` - emitted when validator exit fee limit is updated ### Methods #### updateVaultFees(address, uint256, uint256, uint256) - **Arguments**: - `address _vault` - Address of the vault to update fees for - `uint256 _infraFeeBP` - New infra fee in basis points - `uint256 _liquidityFeeBP` - New liquidity fee in basis points - `uint256 _reservationFeeBP` - New reservation fee in basis points - **Visibility**: `external` - **Modifiers**: None This adapter function is needed to handle potential reverts in batch transactions—allowing other calls to continue executing even if one fails. This adapter function updates the fees for a vault in the `OperatorGrid`. It checks if the vault is connected, not pending disconnect, and if the new fees don't exceed the current fees. If any condition fails, it emits `VaultFeesUpdateFailed` instead of reverting. - **Reverts**: - If the caller is not `evmScriptExecutor` - **Emits**: - `VaultFeesUpdateFailed(address _vault, uint256 _infraFeeBP, uint256 _liquidityFeeBP, uint256 _reservationFeeBP)` if the vault is not connected or pending disconnect #### setVaultJailStatus(address, bool) - **Arguments**: - `address _vault` - Address of the vault to update jail status for - `bool _isInJail` - New jail status to set - **Visibility**: `external` - **Modifiers**: None This adapter function is needed to handle potential reverts in batch transactions—allowing other calls to continue executing even if one fails. This adapter function sets the jail status for a vault in the `OperatorGrid`. It checks if the vault is connected, not pending disconnect, and if the new status is different from the current status. If any condition fails, it emits `VaultJailStatusUpdateFailed` instead of reverting. - **Reverts**: - If the caller is not `evmScriptExecutor` - **Emits**: - `VaultJailStatusUpdateFailed(address _vault, bool _isInJail)` if the vault is not connected, pending disconnect, or the status is already the same #### setLiabilitySharesTarget(address, uint256) - **Arguments**: - `address _vault` - Address of the vault to update - `uint256 _liabilitySharesTarget` - New liability shares target value - **Visibility**: `external` - **Modifiers**: None This adapter function is needed to handle potential reverts in batch transactions—allowing other calls to continue executing even if one fails. This adapter function sets the liability shares target for a vault in the `VaultHub`. It checks if the vault is connected and not pending disconnect. If any condition fails, it emits `LiabilitySharesTargetUpdateFailed` instead of reverting. - **Reverts**: - If the caller is not `evmScriptExecutor` - **Emits**: - `LiabilitySharesTargetUpdateFailed(address _vault, uint256 _liabilitySharesTarget)` if the vault is not connected or pending disconnect #### socializeBadDebt(address, address, uint256) - **Arguments**: - `address _badDebtVault` - address of the vault that has the bad debt - `address _vaultAcceptor` - address of the vault that will accept the bad debt - `uint256 _maxSharesToSocialize` - maximum amount of shares to socialize - **Visibility**: `external` - **Modifiers**: None This adapter function is needed to handle potential reverts in batch transactions—allowing other calls to continue executing even if one fails. The function attempts to socialize bad debt for a vault by calling `vaultHub.socializeBadDebt`. The function emits `BadDebtSocializationFailed` if the call fails for any reason other than "out of gas". - **Reverts**: - If the caller is not `evmScriptExecutor` - If the socializeBadDebt call fails due to an "out of gas" error - **Emits**: - `BadDebtSocializationFailed(address _badDebtVault, address _vaultAcceptor, uint256 _maxSharesToSocialize)` if the socializeBadDebt call fails for any reason other than "out of gas" #### forceValidatorExit(address, bytes) - **Arguments**: - `address _vault` - Address of the vault to exit validators from - `bytes _pubkeys` - Public keys of the validators to exit - **Visibility**: `external` - **Modifiers**: None This adapter function is needed to handle potential reverts in batch transactions—allowing other calls to continue executing even if one fails. This adapter function forces validator exits in the `VaultHub`. It first validates that the withdrawal fee doesn't exceed the configured limit and that the contract has sufficient balance to cover the operation. It then calls `vaultHub.forceValidatorExit` with the required ETH value. - **Reverts**: - If the caller is not `evmScriptExecutor` - If the withdrawal fee exceeds `validatorExitFeeLimit` - If the contract doesn't have enough ETH balance to cover the withdrawal fees - If the forceValidatorExit call fails due to an "out of gas" error - **Emits**: - `ForceValidatorExitFailed(address _vault, bytes _pubkeys)` if the forceValidatorExit call fails for any reason other than "out of gas" #### setValidatorExitFeeLimit(uint256) - **Arguments**: - `uint256 _validatorExitFeeLimit` - new validator exit fee limit - **Visibility**: `external` - **Modifiers**: [onlyTrustedCaller](https://github.com/lidofinance/easy-track/blob/master/specification.md#storage-variables-3) Updates the maximum allowed fee for validator exits. This limit is used to prevent excessive fees from being charged during validator exit operations. - **Reverts**: - If the caller is not the trusted caller - If `_validatorExitFeeLimit` is zero - **Emits**: - `ValidatorExitFeeLimitUpdated(uint256 oldFee, uint256 newFee)` #### withdrawETH(address) - **Arguments**: - `address _recipient` - address to receive the withdrawn ETH - **Visibility**: `external` - **Modifiers**: [onlyTrustedCaller](https://github.com/lidofinance/easy-track/blob/master/specification.md#storage-variables-3) Withdraws all ETH balance from the contract to the specified recipient. This function is used to recover any remaining ETH after validator exit operations. - **Reverts**: - If the caller is not the trusted caller - If the contract has no ETH balance - If the ETH transfer fails #### receive() - **Visibility**: `external` - **Mutability**: `payable` Allows the contract to receive ETH, which is necessary for funding validator exit operations.

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.