Lido Staking Vaults (stVaults): Technical Design and Architecture

TL;DR

It's an evolving (Work-In-Progress) draft of the Lido stVaults tech design document, which covers a high-level technical description of stVaults' design principles, architecture, and mechanics.

It's not a product or goals doc, although they are briefly mentioned to give context. More detailed tech reference follow-up docs and materials will be presented later.

1. Abstract

Lido Staking Vaults (stVaults) are modular primitives that seamlessly connect stakers, node operators, and protocols, settle fee structure, validation setup, and optimize risk/reward. All this is done while preserving decentralization, security, and access to stETH liquidity.

2. Goals

The stVaults aim to:

1. Allow customization of risk-reward profiles of liquid staking without compromising stETH token stability and fungibility.
2. Align better with node operators who want to participate in Lido protocol and bring their clients.
3. Facilitate the creation of new structured products and integrations.

It reflects the goals stated in the Hasu's 2nd GOOSE voted-in proposal and provides the backbone for creating the various product lines for the staking.

3. Architecture

3.1 Key design principles

There are significant changes in the current Lido protocol contracts (named Lido Core from now on for simplicity) and logic related to stVaults introduction, so it's important to outline the primary constraints that remain in place:

1. stVaults do not increase risks for stETH holders
2. stETH token remains fungible and 1:1 redeemable to ETH through the Lido Core
3. The introduction of stVaults has no negative impact on stETH rewards

So, it remains the key priority to maintain the stability and security of the Lido Core and the whole Lido staking infrastructure.

The secondary goal is to maintain the balance between the security and agility of the setup. To achieve this, there are two different layers:

• Essential: Stable foundational contracts required to establish a secure relationship between Lido Core and stVaults.
• Advanced: Interchangeable and more complex code built on top of Essential components, offering improved user experience and additional features.

3.2 What is a Staking Vault?

A stVault is an essential smart contract that implements non-custodial delegated liquid staking with a single node operator (or DVT NO cluster) and is connected to the Lido infrastructure, which provides the ability to mint stETH on behalf of this vault.

Using stVault, one can:

• Stake their funds without giving up the custody directly with their preferred node operator.
• Accumulate staking rewards and tap into various block proposing and validation flavors.
• Mint stETH against the stVault's staked and unstaked ether.
• Integrate protocols and risk curators atop building up structured products.

To cover the risks of maintaining the custom staking setup for stETH holders, stETH is minted not in a 1:1 ratio like the Lido Core allows, but with some reserve margin (named Reserve Ratio or RR), determined by the risk parameters and limits. When stETH is minted, the respective amount is locked for withdrawal from the vault. The locked amount is nominated in stETH shares whilst shares balance increases daily along with the stETH rebase (with the same rate plus fees). To unlock ether for withdrawal, the vault must burn the necessary amount of stETH.

3.3 Essential Parts

1. StakingVault (stVault):

   • An isolated smart contract representing a separate staking position managed by the vault owner.
   • The owner can fund it, withdraw ether, and mint/burn stETH via the VaultHub.
   • A designated node operator deposits or voluntarily exits validators of the vault.
   • The chosen node operator cannot be changed.

2. VaultHub:

   • A central integration point connecting stVaults with the Lido Core protocol.
   • Handles vault connections, mints/burns stETH on behalf of the stVault, locks/unlocks ether in the vault.
   • Includes a rebalancing mechanism to maintain vault health under extreme conditions.

3. Oracle integration: Lido AccountingOracle provides balances of vaults' validators as part of the daily report, as well as some historical data required for vault accounting.

   • Charges the Lido protocol treasury fee.

4. Predeposit Guarantee (PDG):

   • Mitigates deposit frontrunning vulnerabilities described in LIP-5.
   • Uses a mechanism distinct from the Deposit Security Module adopted by Lido Core.

stVault state

Each StakingVault has two important parameters that define its state and determine its lifecycle: valuation and locked.

• valuation: The estimated total of all the vault's validator balances plus any ETH held by the vault contract itself (based on Oracle-provided data).
• locked: The amount of ETH on this vault that is blocked from withdrawal. This amount backs the stETH tokens minted via this stVault.

If locked > valuation, the StakingVault cannot mint stETH, withdraw ETH, or deposit new validators.

Additionally, to control stETH minting, VaultHub tracks these parameters for each stVault:

• sharesMinted: The current amount of stETH shares minted on behalf of the vault.
• reserveRatio (RR): The percentage of the vault's ETH that must be kept as a reserve for minted stETH (e.g., if reserveRatio is 30%, 100 ETH in the vault can only mint 70 stETH).
• reserveRatioThreshold: The minimum percentage of the vault's valuation that must remain locked to avoid force rebalancing. The invariant is reserveRatioThreshold < reserveRatio.
• shareLimit: The total cap on stETH shares that can be minted by a stVault.

Diagram. Vault valuation breakdown

3.4 Flows

Staking and Unstaking

1. Funding

   • The vault owner calls fund() to send ETH to the stVault.
   • Increases the vault's valuation.

2. Depositing Validators

   • The node operator calls depositToBeaconChain() using predeposit guarantee to create or top up a validator.
   • Can be done in batches.
   • Uses 0x02 withdrawal credentials pointing to the vault's address.
   • Does not change valuation.
   • Reverts if locked > valuation.

3. Collecting Rewards and Withdrawals

   • Validator fee recipient can be set to the vault address.
   • Increases the vault's balance but not reflected in valuation until reported by the Oracle.

4. Exiting Validators

   • The vault owner can call askValidatorsForExit() to ask for a voluntary exit.
   • The node operator, vault owner, or VaultHub (under extreme conditions) can call requestValidatorWithdrawal() to request EIP-7002 "triggerable withdrawal".
   • Once exited, the validator's balance is transferred to the vault.
   • Partial withdrawals may also be requested.

5. Withdrawing

   • The vault owner calls withdraw() to take out any amount of unlocked ETH (i.e., valuation - locked) from the vault's balance.
   • Exiting validators or partial withdrawals are necessary to withdraw staked ETH.

Accessing stETH

1. Minting
   

   • The vault owner calls mint() on the VaultHub to mint stETH on behalf of the vault.
   • Increases the vault's sharesMinted.
   • Corresponding ETH (increased on RR) is locked in the vault, preventing it from being withdrawn.
   • The minting capacity is limited by current valuation, sharesMinted, shareLimit, and reserveRatio

2. Burning
   

   • The vault owner calls burn() on the VaultHub to burn stETH on behalf of the vault.
   • Decreases the vault's sharesMinted.
   • The locked amount gets reduced with the next Oracle report.

3. Rebalancing
   

   • Reduces both sharesMinted and valuation simultaneously by taking ETH from the vault, submitting it 1:1 for stETH via Lido Core, and then burning it on behalf of the vault.
   • Improves vault health at the cost of reducing its valuation.
   • Requires validators to be exited or partially withdrawn if staked ETH is intended to be used.
   • Can be performed by the vault owner or executed permissionlessly if the vault's reserveRatioThreshold is breached.

Accounting

The accounting flow of stVaults is performed by the Lido AccountingOracle and does the following:

1. Updates valuation
   • Reflects the changes of the vault's ether balances, staked or unstaked.
   • Required to confirm that stETH minted is sufficiently backed (including RR).

NOTE: The precise and immediate valuation

$V_{precise}$ of the vault on the given block can be presented as:

$$V_{precise}=C{L}_{balance}+E{L}_{balance}$$ where

$C{L}_{balance}$ is the sum of all validator's balances that have withdrawal credentials set to the vault, and

$E{L}_{balance}$ is the balance of the vault contract itself.

However, validators' balances are not immediately available on the execution layer, which makes the Oracle valuation inherently out of sync, although one can estimate it:

$$V=V_i+\delta -{\delta }_i+(X_i)$$

where:

• $V_i$ is vault's valuation brought in the i the Oracle report
• $\delta$ is the difference between cumulative deposits to and cumulative withdrawals from the vault stored in the contract
• ${\delta }_i$ is the historical value of this difference that was actual on the slot of the i Oracle report
• $X_i$ is the unknown difference of the vault's CL balance accumulated since the I the Oracle report. In this model, we assume that the reserveRatio is chosen so that reserve covers
  $X_i$ if it's negative and prevents minted stETH insolvency. Therefore, the valuation of the vault can be calculated as:
  $$V=V_i+\delta -{\delta }_i$$ given that reserveRatio is chosen accordingly to prevent negative discrepancies from influencing stETH holders' risk profile.

2. Adjusts locked

   • locked ETH grows as minted shares appreciate from stETH positive rebasing.
   • locked ETH decreases if stETH was burned on behalf of the vault prior to the current Oracle report and/or stETH negative rebasing.

3. Collects Lido protocol treasury fees

   • They are minted as stETH on the treasury address on behalf of the charged vault, increasing the sharesMinted value for that vault.

Forced rebalancing

A cornerstone principle of stVaults design is:

stETH remains fungible and redeemable at a 1:1 ratio to ETH through Lido Core.

Thus, each vault must remain solvent, preventing any vault-specific losses from spilling over to stETH holders. The mechanism to enforce this is called forced rebalancing:

• Triggered when the vault's reserve for minted stETH falls below its reserveRatioThreshold (e.g., due to slashing or prolonged penalties).
• Comprises two parts:
  1. Forced Validator Withdrawals (permissionless, via EIP-7002).
  2. Forced Rebalance (permissionless rebalancing using available vault unstaked ETH).
• Once triggered, no further deposits or withdrawals are allowed until the vault's health is restored.
• The maximum rebalancing amount (X) satisfies:
  $$\frac{(mintedShares-X)}{(valuation-X)}=1-RR$$

Predeposit Guarantee

To prevent the deposit frontrunning exploit, the StakingVault does not allow the associated node operator to directly make deposits to the beacon chain using the vault ether. Instead, this responsibility is delegated to a specialized contract, PredepositGuarantee, that discourages deposit frontrunning by having the node operator post an equivalent guarantee amount.

Diagram. Node operator deposit happy path

Through this contract, node operators make one ether predeposits to validators and lock an equivalent bonded amount. After that, the node operator must provide the proof of withdrawal credentials by utilizing the EIP-4788 beacon block root in the EVM, thereby unlocking their bonded amount. Once the validator is verified, the node operator is permitted to make full deposits of any amount to this validator. All predeposits and deposits by node operators are submitted through the PredepositGuarantee.

Diagram. Proven validator deposit flow

The complete flow of the stVault's validator deposit is as follows:

1. The node operator locks a 1 ether on the PredepositGuarantee contract as a guarantee.
2. Node operator then must submit a minimal deposit of 1 ether using the StakingVault funds through the same PredepositGuarantee contract.
3. Once the validator appears on the beacon chain, the node operator generates the proof of valid withdrawal credentials and submits it to the PredepositGuarantee, unlocking their bonded 1 ether.
4. The node operator may then make full, uncapped deposits to validators whose withdrawal credentials have been validated through the PredepositGuarantee contract.
5. In the event that a validator's withdrawal credentials are proven invalid (i.e., they do not match the StakingVault withdrawal credentials), the vault owner may withdraw the provided bonded ether.

Important to know!

• Node operator guarantee can come from a dedicated guarantor account (which trusts the operator).
• The bonded ETH from the operator or guarantor stays in the PredepositGuarantee contract; only stVault ETH ever goes to the validator.
• StakingVaults support Pectra's EIP-7251 MAX_EB right away, so 1 ETH is enough to deploy a 2048-ETH validator.
• The steps listed above are not separate transactions. All of them can be conducted in just two transactions.
• One can sequentially reuse the same posted 1 ETH guarantee to set up and prove multiple validators for the same operator.
• The contract supports batched operations.

3.5 Additional parts

Dashboard & Delegation

The delegation subsystem is an optional extension for StakingVault and deals with:

• Role-based access control (RBAC) to the StakingVault operations,
• Curator and node operator manager involvement and their optional fees,
• UX-friendly methods and various token helpers.

Architecture

StakingVault is a minimal staking primitive that manages only immediate staking operations and tracks its valuation and locked ether. It implements a simple single-owner model. The delegation system is optional and plugs into a StakingVault by taking over its ownership while the actual vault admin becomes the admin of the Delegation contract.

Diagram. Delegation access control model

Key components (in order of inheritance):

• OpenZeppelin's AccessControl that provides a basic RBAC system (using AccessControlEnumerable as the implementation),
• AccessControlConfirmable, an extension over AccessControl that adds multi-role confirmation,
• Permissions defines main permissions (AccessControl role constants) for respective StakingVault operations,
• Dashboard, user-facing contract wrapping StakingVault and VaultHub operations,
• Delegation introduces the curator and node operator manager roles and their optional fees.

Roles

With delegation plugged in, every operation in the StakingVault requires the respective role. For example, funding the StakingVault requires that the sender has the FUND_ROLE. All of these roles have their role admin.

Diagram. Role-restricted operations

Important to know!

• The Delegation contract includes functions for batch-granting and batch-revoking roles;
• Some operations (like rebalance) can be pre-funded if ether is > attached to the transaction and the sender has FUND_ROLE.

Multi-role confirmation

The multi-role confirmation mechanism restricts some administrative actions, thus preventing unilateral decisions. This means that a member of each of the required roles must send the transaction with the same parameters within a configurable duration (lifetime).

Diagram. Example of a multi-role confirmation process

Performance fees

The StakingVault intentionally does not include any accounting for extraneous fees (e.g., node operator, curator, reward share) to allow for flexibility in different setups. Instead, this logic was implemented in Delegation with room for configuration. Curator and node operator are unique entities that do not have respective operations in the underlying StakingVault. Instead, they are each eligible for a fee taken as a portion of the StakingVault's rewards.

The performance fee calculation is as follows:

1. Calculate the total rewards

   $$r=V_l-V_c-{\delta }_l-{\delta }_c$$ Where
   $r$ is the total rewards,
   $V_l$ is the vault valuation at the last report,
   $V_c$ is the vault valuation when the fee was last claimed, and
   ${\delta }_l$ is the in-out delta at the last report, and
   ${\delta }_c$ is the in-out delta when the fee was last claimed.

2. Multiply the total rewards by the fee percentage. If

   $r$ is zero or less, the accumulated fee will be zero.
   $$f=\{\begin{array}{ll}{\displaystyle r\times F,}& r>0,\\ 0,& \text{otherwise}.\end{array}$$ where
   $f$ is the accumulated fee,
   $F$ is the normalized fee percent and satisfies
   $0\le F\le 1$.

Important to know!

• Before setting a new fee, the accumulated fee must be claimed. Otherwise, the transaction will revert;
• Fee percentages are represented in basis points, with 1 point equivalent to 0.01% and 10000 to 100%.

4 Risks

Stakers and ecosystem participants are advised to carefully consider these risks and conduct their own research before participating in stVaults.

4.1 Ecosystem risks

1. Stake concentration: Mitigated through stVault permissionless creation, risk parameters, and limits, balancing for a diverse node operator participation.
2. Token insolvency: Addressed via risk parameters to maintain a reasonable reserve margin for minted stETH alongside local and global limits for the max mintable stETH through the stVaults.

4.2 Risks for stVaults stakers

1. Deposit Frontrunning: Mitigated through the PredepositGuarantee module.
2. Forced rebalancing: Managed with deterministic rules, policies, and continuous monitoring.
3. Slashing Risk: While mitigated through careful node operator selection and monitoring, the possibility of intentional misbehavior or technical issues remains.
4. Liquidity Risk: Potential challenges in converting large amounts of stETH to ETH quickly for Lido Core, especially during market stress, would require stETH redemptions through stVaults.
5. Interoperability risks: Integration with other DeFi protocols may introduce additional complexities and potential vulnerabilities.

4.3 Inherited Risks

1. Ethereum Risks: Issues with the Ethereum network, such as consensus failures or major protocol changes, could impact stVault operations.
2. Lido Infrastructure Risks:
   • stETH Market Price: Stakers risk an exchange price of stETH lower than the inherent value due to prolonged withdrawal times, expecting validator exits and making arbitrage and risk-free market-making impossible.
   • Smart Contract Security: There is an inherent risk that Lido could contain a smart contract vulnerability or bug; to minimize this risk, the Lido protocol codebase remains open-source, reviewed, audited, rolled out on testnets, and covered by extensive tests and a bug bounty program.
   • Oracle failures and data manipulation: Oracle may affect protocol's accounting state by bringing malformed data, the risk is mitigated with a consensus mechanisms for the oracle committee and smart contract safety nets.
   • Correlated in-protocol mass-slashing: In case of mass-slashing events in Lido Core, the bunker mode activates to socialize conversion rate losses among stETH holders.
   • Governance risks: The protocol is maintained and upgraded by the LDO tokenholders. The mitigation of governance risks includes a two-phase voting system, a public delegate voting platform, and an anticipated 2025 H1 Dual Governance activation.

5. Useful Links

• stVaults PR on GH
• the Hasu's 2nd GOOSE voted-in proposal
• EIP-7002 "Triggerable Withdrawals"
• EIP-7251 "Increase the MAX_EFFECTIVE_BALANCE"
• LIP-5 "Mitigations for deposit frontrunning vulnerability"