Architecture
Liquid Collective's protocol architecture on Ethereum
Last updated
Liquid Collective's protocol architecture on Ethereum
Last updated
River is the core smart contract in the protocol. River manages:
LsETH Token
User Deposits: River allows users to perform ETH deposits and receive receipt tokens (mint LsETH) in return.
Consensus Layer Deposits: River orchestrates the delegation of ETH to validators and deposits to the official Ethereum deposit contract.
The Oracle contract is responsible for feeding the River contract with the balance position of the validator nodes on the consensus layer. It relies on a set of Oracle Operators that periodically report data from the consensus layer to the execution layer; it is currently configured to report every 24 hours.
The Oracle contract helps synchronize a quorum of Oracle Operators to report the same consensus layer data. In particular, the Oracle contract makes sure that the core River contract receives data only after the Oracle contract has received identical reports from a quorum of Oracle Operators.
The Node Operators Registry:
Manages Node Operators that have been approved to receive ETH delegation
Enables Node Operators to register validators
Selects the next validators to receive delegation, attempting even distribution so all Node Operators get a fair delegation
The Allowlist contract manages the permissions of who can deposit to the protocol. The protocol requires participants to use an allowlisted wallet to deposit ETH and redeem LsETH.
The ELFeeRecipient contract is the contract that receives execution layer fees, including priority fees and MEV network rewards.
The Withdraw contract is the contract that perceives withdrawn funds resulting from both validator’s full and partial exits. All Liquid Collective validator keys have their withdrawal credentials set to the address of the Withdraw contract. Withdrawn funds are automatically pushed to the Withdraw contract by design of the Ethereum protocol. Funds on the Withdraw contract are periodically pulled by River contract on every Oracle report.
The Liquid Collective protocol smart contract was upgraded to enable LsETH redemptions in May of 2023. Liquid Collective upgradability relies on the upgradeable proxy pattern enabling any functional upgrade to the smart contracts.
In its current form, the River smart contract always sets the validator withdrawal credentials to the address of the Liquid Collective Withdraw contract, which is an upgradeable proxy Smart Contract.
Upgradability of both contracts is governed in a decentralized fashion by the protocol's administrators through the Liquid Collective DAO.
The Liquid Collective protocol’s Redemption Queue facilitates the satisfaction of redemption requests in the same order as they have been requested. The first-in-first-out Redemption Queue is intended to protect against a race for claims in the event of high withdrawal demand.
The Liquid Collective protocol’s Redemption Buffer holds ETH that is pending to be supplied for redemption satisfactions.
The Liquid Collective protocol’s Withdrawal Stack automatically facilitates the movement of ETH to the protocol’s Redemption Buffer. This ETH may be sourced by validator exits from the consensus layer or rebalanced from the protocol’s Deposit Buffer.
The Liquid Collective protocol’s Deposit Buffer holds ETH pending to be deposited to Ethereum’s consensus layer, or that can be rebalanced to the Withdrawal Stack to programmatically facilitate redemption satisfactions. This ETH may be sourced from user deposits, network rewards (consensus layer & execution layer), the protocol’s Slashing Coverage Program, or rebalanced from the protocol’s Withdrawal Stack.
