Architecture

Liquid Collective's protocol architecture on Ethereum

Smart Contracts

River

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.

Oracle

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.

Node Operators Registry

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

Allowlist

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.

ELFeeRecipient

The ELFeeRecipient contract is the contract that receives execution layer fees, including priority fees and MEV network rewards.

Withdraw

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.

Upgradeability

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.

Queues, stacks, and buffers

Redemption Queue

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.

Redemption Buffer

The Liquid Collective protocol’s Redemption Buffer holds ETH that is pending to be supplied for redemption satisfactions.

Withdrawal Stack

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.

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.