# DeFi Wrapper Technical Design
## Abstract
DeFi Wrapper is a modular system that **uses stVaults** to enable **delegated staking with optional liquidity** and **automated looping strategies**. It lowers an entry-barrier to run individual stVaults as the end-user products that support multiple depositors and DeFi yield optimization.
## Design
**Core Use Cases:**
- **Delegated Staking with optional liquidity**: Multiple users pool ETH into a single stVault, some of them might want occasionally mint stETH for themselves to access liquidity on-demand.
- **Delegated pooled Staking without optional liquidity**: Multiple users pool ETH into a single stVault.
- **Delegated non-pooled Staking with optional liquidity**: A single user put ETH into a single stVault, and can potentially mint stETH when needed.
- **Pooled staking with automated stETH mint and optional boost**: New and existing vault users can opt into leverage staking (looping) strategy using stETH collateral on lending protocols, and by depositing borrowed ETH to the same vault.
**Unsupported Use cases**
- **Delegated Staking with optional liquidity**: Mixing users who mint stETH (and pay infra + liquidity fee) with users who only deposit ETH (expecting infra fee only) in the same vault introduces unfairness in risks, reward and fee distribution. For implementation, it is necessary to refine the LazyOracle.
- **Delegated non-pooled Staking with optional liquidity**: Technically possible by assigning FUND_ROLE per-user (whitelisting vault funders).
However, since rewards are calculated globally by LazyOracle, and there’s no mechanism to attribute rewards to specific users within the vault, this case requires offchain reward tracking.
Wrapper does not support this use case, as it’s more suited for advanced integrations or NO-managed private deployments.
**Supported Use Cases by Wrapper**
- **Delegated pooled staking**
- **Delegated pooled staking with liquidity**
- **Delegated pooled staking with automated yield-boosting strategy**
## Solution Overview
DeFi Wrapper provides pre-built modules that compose on top of stVaults through a three-layer architecture:
**Layer 1: Deposits & Withdrawals (stvToken Layer):**
- Wrapper accepts deposits from multiple users
- Fund ETH into underlying stVault and issues stvToken shares representing user's portion
- Manages withdrawal queue with validator exit coordination
Pure stvToken accounting with reward distribution through price appreciation
**Layer 2: stETH Wrapping & Unwrapping:**
- Wrapping/unwrapping stETH <-> stvToken uses vaultHub mint/burn shares
- calculateMaxMintable stETH accounting for vault's reserve ratio
**Layer 3: Strategy Delegation & Adapters:**
- Strategy adapters deployed per (vault × strategy × user) combination
- Users delegate their staking position (full or partial amount, represented with `stvToken`) to strategies for automated leverage (auto delegated on deposit)
- Strategies use stETH Wrapping & Unwrapping and Deposits & Withdrawals
- The architecture enables support for different protocols: Aave, Fluid, Gearbox, GGV via the strategy adapter interface to be shared with partners
**Layer 4: Utility Layer**
The utility layer provides essential tools and interfaces to streamline the deployment, configuration and ongoing management of the vault.
- The `DApp` provides a user-friendly interface for end-users to deposit ETH into the wrapper, view their balances, claim rewards, and manage withdrawals, without interacting directly with smart contracts or the CLI.
- The `Factory` allows a Node Operator to deploy a new vault, wrapper, distributor, and withdrawal queue in a single transaction. The system ensures all components are properly linked and configured, automatically setting up the correct roles and fee structures, minimizing manual steps and the risk of misconfiguration.
- The `CLI` is a toolkit for Node Operators and advanced users to interact with protocol contracts in a user-friendly and automated way.
## Architecture
### System Overview
### Deposits
**Purpose**: Main user interface for pooled staking
**Key Features**:
- Accepts ETH deposits from multiple users
- Issues stvToken shares
- Pools funds into underlying StakingVault
- Withdrawal queue
- Whitelist
**Deposits**
The main flow:
1. User deposit ETH to the Wrapper contract
1.1 Wrapper fund the connected stakingVault through Dashboard and mint `stvToken`
1.2 NodeOperator can pause the deposits
1.3 NodeOperator or users MUST apply a fresh report to the Vault
2. NO deposits validators through PDG, see [here](https://hackmd.io/@lido/stVaults-design#315-Essentials-PredepositGuarantee)
or through PDG [bypass](https://hackmd.io/@lido/stVaults-design#PDG-bypass-and-rewards-adjustment)
### Withdrawals and Emergency Exit
#### Withdrawal Queue System
All withdrawals must go through a queue system with specific requirements:
- **Fresh Reports Required**: Node Operators or users must provide fresh reports for withdrawals to be processed
- **Amount Limits**: MIN/MAX withdrawal limits per single request (similar to Lido Withdrawal Queue)
- **Individual Queues**: Each wrapper maintains its own withdrawal queue
- **Autonomous Management**: Node Operators autonomously regulate validator withdrawals
- **Finalization Control**: Request finalization remains under Node Operator control
#### Emergency Exit
Emergency exit functionality is available when reports are stale for extended periods, allowing users to exit without waiting for fresh reports.
> **Note**: Detailed specifications for withdrawal queue and emergency exit are available in separate technical documents:
> - [Withdrawal Queue Specification](https://hackmd.io/ZsDoWqxJRouoFQWn1mezkA)
> - [Emergency Exit Specification](https://hackmd.io/78cCnn72T86yUE8RWHH5MA)
**Reward Distribution**
The system supports two types of rewards for users:
#### 1. Staking Rewards (via LazyOracle reports)
- The LazyOracle periodically submits an aggregated report.
- The Node Operator is responsible for updating the vault’s report to maintain its “freshness.”
- Users can bring report data themselves too
- If the report is outdated, users may not be able to withdraw or receive their correct share of rewards.
#### 2. Sidecar Rewards (Obol, SSV, restaking, points, etc.)
The Sidecar Rewards system enables Wrapper participants to receive additional incentives from third-party protocols and services beyond standard staking rewards.
#### ERC20 rewards
ERC20 reward providers such as Obol, SSV allocate rewards to Withdrawal Credentials, which in our scheme is StakingVault. Therefore, it is necessary to be able to withdraw rewards from the vault for further distribution among stakers, so for that we are using `StakingVault.recoveryERC20()`
> [!WARNING]
> Providers need to be able to make permissionless claims on behalf of others.
#### Points rewards
Point-based reward systems (Symbiotic, EigenLayer, Babylon, etc.) represent a category of restaking and staking incentives. Unlike ERC20 tokens, points are typically:
- Off-chain tracked by the protocol
- Non-transferable until converted to tokens
- Time-sensitive with specific claiming windows
Points automatically accumulate on StakingVault address, and when protocols announce points → token conversion we can use standart claim→recovery→distributor scheme.
#### RewardDistributor Contract
The `Distributor` contract is a smart contract for distributing rewards (ERC-20 tokens) among Vaults Wrapper users based on their stvToken share holdings. The contract uses Merkle Tree for efficient distribution and prevents double-spending.
- **DEFAULT_ADMIN_ROLE**: Full control over the contract
- **MANAGER_ROLE**: Distribution management (adding tokens, setting Merkle root)
#### CLI
The [CLI tool](https://github.com/lidofinance/vaults-wrapper-distributor) for Distributor provides a complete set of commands for managing reward distribution, generating Merkle trees, and allowing users to claim rewards.
```bash
distribute --operator-fee=10%
```
```mermaid
sequenceDiagram
participant Sidecar as Sidecar
actor OP as Operator
participant SV as StakingVault
participant D as Distributor
participant W as Wrapper
participant CLI
participant IPFS
actor User
Note over Sidecar: Phase 1: Incentive distribution<br>reward addr: StakingVault
Sidecar->>Sidecar: distibute()
Sidecar->>Sidecar: merkleRoot()
Note over Sidecar: Phase 2: Curator claims rewards behalf the Vault
OP->>D: addToken()
D-->>OP: ok
OP->>Sidecar: claimBehalf()
Sidecar-->>SV: assets(ERC20)
OP->>SV: recoveryERC20()
SV-->>D: assets(ERC20)
Note over OP, CLI: Phase 3: Offchain reward calculation
OP->>CLI: distibute --op-fee=10% --from=2024 -to-2025
loop For each supported token in Distributor
CLI->>W: getUsers()
W-->>CLI: users
CLI->>W: getUserShares(userAddress)
W-->>CLI: User shares
end
CLI->>CLI: generated merkle tree
CLI->>IPFS: merkleTree +prevTreeCid+blockNumber
IPFS-->>CLI: CID
CLI->>D: setMerkleRoot(token, root)
Note over OP, CLI: Phase 4: Users claim rewards
User->>D: claim(token)
D-->>User: assets
```
### stETH Wrapping & Unwrapping
When using **Delegated pooled staking with liquidity** in Wrapper, the user's share of stvToken is blocked and the maximum number of stETH in the Vault is minted. In order to return the deposited ETH, the user must return stETH and go through the withdrawals procedure.
Wrapper always mint the maximum of available stETH, relative to the user's stvToken.
### Strategy Delegation & Adapters
Detailed specification for Boost and Strategy delegation you can find here:
- [Boost Strategy for DeFi Wrapper](https://hackmd.io/HmWsAh3ySq-ffps6vgovVw)
### Pause and Upgradebility
It is proposed to add levers to the DeFi Wrapper that can be used by the vault owner to mitigate negative consequences in case any threats or vulnerabilities are discovered in the protocol
Detailed description of mechanism can be found here:
- [Emergency Leverages for DeFi Wrapper](https://hackmd.io/QgDpZIohQtGxdKijB2j6fA)
## Risks
**Smart Contract Risk:**
- NO trust model
- Inflation attack on pool https://blog.openzeppelin.com/a-novel-defense-against-erc4626-inflation-attacks
- Complex interactions between wrapper, vault, and strategies
- **Mitigation**: Comprehensive testing, multiple audits
**Leverage Risk:**
- Liquidation risk if stETH/ETH ratio moves unfavorably
- **Mitigation**: Conservative health factors (150% minimum), automatic rebalancing
**Oracle Risk:**
- Dependency on LazyOracle for accurate reward calculation
- **Mitigation**: Inherit stVaults' proven oracle security model
**Mass slashing and bad debt**
- insurance playbook for NO
- rebalance issue
### Economic Risks
**Liquidity Risk:**
- Large withdrawals may require validator exits (27+ hour delay)
- **Mitigation**: Emergency exit mechanism, reserve management
**Strategy Risk:**
- External DeFi protocols may experience exploits or failures
- **Mitigation**: Strategy whitelisting, position limits, emergency pausing
**Slashing Risk:**
- Underlying validators may be slashed, affecting all users
- **Mitigation**: Inherit stVaults' slashing protections and insurance
## Useful Links
- **[stVaults Technical Design](https://hackmd.io/@lido/stVaults-design)** - Core infrastructure specification
- **[Aave V3 Documentation](https://docs.aave.com/developers/getting-started/v3-overview)** - Lending protocol integration
- **[Flashloan Best Practices](https://docs.aave.com/developers/guides/flash-loans)** - Leverage implementation patterns
- https://github.com/devdacian/ai-auditor-primers/blob/main/primers/amy.vault.erc4626.primer.md
Sign in with Wallet
Connect another wallet