---
title: Lido Staking Vaults (stVaults) Technical Design and Architecture
tags: Vaults
---

# 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](https://snapshot.box/#/s:lido-snapshot.eth/proposal/0xeedef9fea3d782f192410768cabaf6974da40ef36e1d22c7f8fff5fd4cfc7a59) 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](https://ethereum.org/en/staking/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](https://docs.lido.fi/guides/lido-tokens-integration-guide#steth-internals-share-mechanics) 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)*](https://github.com/lidofinance/core/blob/feat/vaults/contracts/0.8.25/vaults/StakingVault.sol):
- 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*](https://github.com/lidofinance/core/blob/feat/vaults/contracts/0.8.25/vaults/VaultHub.sol):
- 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*](https://github.com/lidofinance/core/blob/feat/vaults/contracts/0.8.25/Accounting.sol):
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)*](https://github.com/lidofinance/core/blob/predeposit-guardian/contracts/0.8.25/vaults/predeposit_guarantee/PredepositGuarantee.sol):
- Mitigates deposit frontrunning vulnerabilities described in [LIP-5](https://github.com/lidofinance/lido-improvement-proposals/blob/develop/LIPS/lip-5.md).
- 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](https://eips.ethereum.org/EIPS/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} = CL_{balance}+ EL_{balance} $$
> where $CL_{balance}$ is the sum of all validator's balances that have withdrawal credentials set to the vault, and $EL_{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 + δ - δ_i + (X_i) $$
>
> where:
> - $V_i$ is vault's valuation brought in the _i_ the Oracle report
> - $δ$ is the difference between cumulative deposits to and cumulative withdrawals from the vault stored in the contract
> - $δ_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 + δ - δ_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](https://eips.ethereum.org/EIPS/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](https://medium.com/immunefi/rocketpool-lido-frontrunning-bug-fix-postmortem-e701f26d7971), 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](https://eips.ethereum.org/EIPS/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`](https://eips.ethereum.org/EIPS/eip-7251) 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](https://docs.openzeppelin.com/contracts/5.x/api/access#AccessControl-_setRoleAdmin-bytes32-bytes32-).

*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} - δ_{l} - δ_{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 $δ_{l}$ is the in-out delta at the last report, and $δ_{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{cases}
\displaystyle
{r \times F}, & r > 0, \\
0, & \text{otherwise}.
\end{cases}
$$
where $f$ is the accumulated fee, $F$ is the normalized fee percent and satisfies $0\leq F \leq1$.

> **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](https://github.com/lidofinance/core/pull/874)
- [the Hasu's 2nd GOOSE voted-in proposal](https://snapshot.box/#/s:lido-snapshot.eth/proposal/0xeedef9fea3d782f192410768cabaf6974da40ef36e1d22c7f8fff5fd4cfc7a59)
- [EIP-7002 "Triggerable Withdrawals"](https://eips.ethereum.org/EIPS/eip-7002)
- [EIP-7251 "Increase the MAX_EFFECTIVE_BALANCE"](https://eips.ethereum.org/EIPS/eip-7251)
- [LIP-5 "Mitigations for deposit frontrunning vulnerability"](https://github.com/lidofinance/lido-improvement-proposals/blob/develop/LIPS/lip-5.md)