Technical Documentation

The ether.fi-Liquid1 vault was adapted from the Sommelier “Cellars” infrastructure by Seven Seas (the team that built the Cellars architecture). See the Sommelier smart contract docs for more details on the original architecture.

User Interface

Depositing

When users deposit into the vault, they receive an ERC-4626 compatible token representing their position. The token is yield-bearing, meaning that the value of the position will automatically be reflected in the redemption price (in contrast with a rebasing token whose balance increases over time). LP tokens are backed 1:1 to eETH. While LP tokens are priced using the market price of eETH, the LP token price can change marginally due to volatile strategies within the vault, such as PT-eETH. Users may notice very small fluctuations in the number of LP tokens they get per asset token deposited.

Deposits are handled in the smart contract via the deposit and mint functions. Once a user receives their vault share tokens, they may use transfer and transferFrom to freely transfer the tokens.

Withdrawing

Withdrawals in ether.fi-Liquid1 are completed through the Withdrawal Queue. A user submits a withdrawal request with a deadline for the withdrawal to be completed, a discount value, and the number of shares they want to redeem.

A solver will then fulfill the withdrawal request on behalf of the user within the deadline (assuming the request can be feasibly fulfilled). The discount is meant to compensate solvers for the gas costs of fulfilling the withdraw. Users pay a very small gas fee when initiating the withdrawal but the fee for actually redeeming the shares for assets is paid by the solver.

Unfilled withdrawal requests: During the Pending Withdrawal period, if the LP token price falls below the target LP token price (what the seller has asked for from the solver), it may not be filled by the Solver and will expire at the end of the withdrawal period.

Why withdrawals are queued: There is a security benefit to forcing withdrawals to go through the Queue: by preventing round trip transactions (depositing and withdrawing in a single transaction) the vault mitigates any atomic arbitrage issues.

LP token balance changes: Liquid allocates a portion of it's funds to Pendle's PT-eETH token. PT-eETH is designed to appreciate and match the price of it's underlying asset (eETH) at maturity, although it can be volatile in short-term periods. Users may see brief fluctuations in their LP token balances due to this volatility, but if they hold their Liquid Position to maturity, their token balances will return to normal and the user will not incur any permanent loss from this.

Fees

The Liquid Vaults charge an annualized platform fee based on vault TVL. The fee is computed daily by the smart contract.

The fees are broken out below by Vault:

Liquid ETH yield - Platform 1%
Market Neutral USD - Platform 2%
Elixir Stable Vault - Platform 0%
Usual Stable Vault - Platform 2%
Eigen Restaking - Platform 0%
ETHFI Restaking - Platform 0%
UltraYield Stablecoin Vault - Platform 2%, Performance 20%

This means that for example if the vault charges a 2% platform fee, each day 2% / 365 = 0.0055% of TVL is saved in the smart contract as platform fee.

Smart Contracts & Architecture

Smart Contracts

Some of the content below is reproduced from the Sommelier docs where relevant.

Architecture

The ether.fi-Liquid1 architecture is based on a “hub-and-spoke” model with a core vault contract responsible for user interactions (minting and redeeming) and auxiliary “adaptor” contracts that enable the vault to take DeFi positions. The architecture is composed of the following 4 components:

Registry - contains global configuration data for the ether.fi-Liquid1 vault, including permissions for what adaptors and positions the vault can utilize. Owned by a Timelock (which is subsequently owned by the Admin).
PriceRouter - provides pricing information about the vault’s assets to the vault, typically using Chainlink (but in some cases Redstone). The router additionally prices complex multi-token vault positions such as LP positions.
Cellar (vault) - user-facing ERC4626 contract where strategists deploy assets to earn yield. The Strategist can make adjustments to vault positions via .
- Note: This vault departs from the ERC4626 standard of totalAssets. According to the standard, totalAssets must not revert. For this vault, totalAssets may revert. Integrators should take care to note and handle this difference.
Adaptors - integration contracts that allow the vault to interact with an external DeFi protocol. Adaptors are case-specific, and the vault may use multiple adaptors during complex DeFi operations.

Benefits to this Architecture

Increased Security: Key security features of this vault included constrained actions which limit the vault to interacting with only pre-approved protocols and assets, rebalance deviation which computes total assets before and after rebalance and reverts the transaction if the change in value exceeds a threshold, and multiple roles each with the ability to only call a subset of functions on the vault.
Off-Chain Computation: Unique architecture that allows Liquid to ingest data input from off-chain models. This keeps the strategy private as well as allows the vault to be fed information from data models.

Integrated DeFi Protocols

Pendle:

YT-eETH , PT-eETH , LP-eETH

Aave:

ETH lending

Morpho:

weETH supply/borrow

Balancer:

weETH / rETH pool , weETH / ETH pool

Aura:

weETH / rETH pool

Uniswap V3:

weETH / ETH 1bps pool , weETH / ETH 5bps pool

Convex: weETH / WETH pool

Roles

Admin

The Admin is a multi-sig consisting of members from both the strategy team and the ether.fi community. This role is meant to act as a neutral party that can quickly act during rare but time-sensitive scenarios.

Timelock

The Timelock (owned by the Admin) gates operations that are not time-sensitive. For example, adding a new position to the vault is gated by the Timelock (and hence is telegraphed in advance).

Strategist

The Strategist is responsible for submitting rebalance signals to the vault. There are significant limitations to the actions that the Strategist can take - the actions are confined to utilizing the set of adaptors and positions (gated by the Registry which is subsequently owned by the Timelock) to optimize vault performance.

Security

There are several layers of security built into the smart contracts.

Constrained actions - The vault only has the capability to interact with pre-approved protocols and assets. Rebalances can only be executed using the set of adaptors and positions in the Registry. This places a hard constraint on what actions the vault can take.
Rebalance deviation - On every rebalance, the vault computes the total assets before and after the rebalance and reverts the transaction if the change in value exceeds a threshold. This acts as a catch-all safety check on any vault operation.
Multiple roles - There are various roles each with the ability to only call a subset of functions on the vault. For example, the Strategist can only rebalance the vault but does not have access to other sensitive functions.

The system has been operating for over a year in production (on Sommelier), and has weathered several black swan market events (USDC de-peg, Curve hacks, etc.).

Audits & Code

Smart Contract Audit (January 15, 2024 to January 22, 2023): https://0xmacro.com/library/audits/sommelier-16a.html

Smart Contract Audit (January 23, 2024 to January 31, 2024.): https://0xmacro.com/library/audits/sommelier-16b.html

Smart Contract Audit (July 31, 2023 to August 4, 2023):

https://0xmacro.com/library/audits/sommelier-9.html

Redstone Oracle Pricing: https://0xmacro.com/library/audits/sommelier-12.html

Pendle Contract Audit: https://0xmacro.com/library/audits/sevenSeas-2.html

Multiple Roles Contract Audit: https://0xmacro.com/library/audits/sevenSeas-1.html

Github Source Code Audit: https://github.com/PeggyJV/cellar-contracts

PreviousCoverage for Liquid NextFAQs

Last updated 1 day ago