Slashing Coverage Program Summary: 3 layers of coverage

1. Nexus Mutual Coverage

2. Slashing Coverage Treasury

Liquid Collective’s Slashing Coverage Treasury allocates a percentage of all network rewards to provide coverage for slashing coverage deductibles on network-wide slashing incidents. The Treasury continues to accrue network rewards unless deployed.

3. Node Operator Commitment

Node operators supporting Liquid Collective's active set provide coverage for deductibles, up to a cap, against slashing incidents and missed rewards incurred due to the fault of their infrastructure.

Slashing Coverage Fund

The Slashing Coverage Fund is in charge of injecting coverage funds into the system. In the case of a slashing event on one of the validators of the system, the Slashing Coverage Fund can be supplied with ETH to be used to repay slashing losses. When funds are sent to the Slashing Coverage Fund, the system will attempt to pull everything until the fund is empty.

The amount pulled is always capped by the reporting upper bound, just like the execution layer fees. This means that the supplied ETH will probably be injected in the system in multiple oracle report rounds.

Slashing Coverage Fund Contract

Fund Supply

Funds are supplied to the Slashing Coverage Fund contract when a qualified slashing event has occurred.

Partners assigned with a deductible can reimburse by posting the deductible (in ETH) to Liquid Collective's CoverageFund smart contract. ETH in the CoverageFund contract are periodically pulled into the system, accounted into the Conversion Rate, and eventually introduced into the staking flow.

Liquid Collective's CoverageFund contract is designed to only accept ETH from allowlisted accounts with a specific DONATOR permission.

When pulling funds from the CoverageFund contract the system does not mint any new LsETH and so the operation results in a replacement of any shortfalls that may have occurred from a slashing event, which applies to every LsETH holder.

Fund Distribution

• No fees are taken on the received funds

• The funds are entirely distributed to LsETH holders

• No new LsETH are minted

• Funds are distributed by increasing the Conversion Rate of LsETH

Funds from the CoverageFund contract are pulled into the system upon successful Oracle reports after Execution Layer fees have been pulled and rewards have been accounted, so no fee is charged on the cover funds pulled.

The amount pulled from the CoverageFund contract respects the Conversion Rate's variation bounds, so a slashing reimbursement cannot disrupt the Conversion Rate. On every Oracle report the system accounts for network rewards (CL + EL) then collects the gross fee, then attempts to pull funds from the CoverageFund contract up to the authorized maximum to remain within Conversion Rate's variation bounds.

In other words, if ETH is available in the contract, River will attempt to pull as much ETH as possible, up to the upper bound allowed by the Oracle contract. This smoothing mechanism means that it may take multiple Oracle cycles for Slashing Coverage Funds to be pulled entirely into the system, ensuring a gradual variation of the Conversion Rate.

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.

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.

Liquid Collective allows users to deposit and stake any amount of ETH, not just 32 ETH (the minimum required to operate a full validator). Deposited ETH are gathered into an ETH smart contract account as fungible bulk. ETH in the account are regularly delegated to validators in a round-robin manner as the account reaches a balance of 32 ETH.

Self-custody

The Liquid Collective protocol is non-custodial. Deposited ETH is sent by the protocol to the Ethereum deposit contract. LsETH is also self-custodied, so LsETH holders have complete control over their LsETH and can pick any preferred custody solution.

Key roles in Liquid Collective

Platforms

Platforms provide a seamless on-ramp and access for users to interact with the Liquid Collective protocol. There are two types of Liquid Collective Platforms. Platforms either enable minting and redemption of LsETH, or enable secondary interactions.

Wallet and Custody Providers

Wallet Providers and Custody Providers offer LsETH token storage and signing infrastructure. Wallet and Custody Providers enable Platforms to easily access and distribute LsETH to their users through custody and/or embedded minting services. In some cases, these Providers and Platforms are the same entities.

Service Providers

Service Providers provide development, consulting, attestation, legal, or technological services to the Liquid Collective. Liquid Collective seeks to collaborate with existing web3 teams in the development of the protocol’s liquid staking offering.

Node Operators

Node Operators run the Ethereum validator infrastructure on Liquid Collective, registering validator keys with the protocol, performing validation duties, and earning network rewards for doing so. Liquid Collective does not run validator infrastructure, but instead delegates that critical task to proven Node Operators that meet high performance standards.

Oracle Operators

Infrastructure providers, operating a daemon app to report Ethereum consensus layer data to the Liquid Collective protocol. This data is necessary so the Liquid Collective protocol can account for the network rewards earned by validators.

Liquid Collective's Ethereum staking infrastructure

Liquid Collective is designed to provide a secure and enterprise-grade liquid staking solution which necessitates sanctions checks on the protocol’s active validator set. Liquid Collective Node Operators must meet certain protocol performance and compliance requirements, and have the capacity to scale to a large number of validator nodes.

Liquid Collective works only with security-focused Node Operators that institute best practices to generate network rewards, including:

• operating multi-region, multi-client infrastructure

• offering technical support teams

• maintaining security posturing (including double-sign protection)

To reduce the risk impact of validator operations, and to increase decentralization, Liquid Collective delegates tokens to multiple independent validator Node Operators. The staked tokens are distributed across Node Operators in a round-robin manner so that the Liquid Collective protocol is supported by a broad and dispersed active validator set. As a result, the risk is distributed, which should minimize staked ETH exposure to any one operator.

This documentation is specific to Liquid Collective's Ethereum liquid staking protocol and its ETH liquid staking token, Liquid Staked ETH (LsETH).

ETH liquid staking with Liquid Collective

Liquid staking enables participants to contribute to the security and decentralization of proof of stake networks, while providing increased liquidity and capital efficiency.

Read on for Liquid Collective's ETH liquid staking protocol documentation.

LsETH User Agreement

The LsETH User Agreement is a legal agreement that outlines the terms and conditions of using the Liquid Collective protocol and holding LsETH. It contains important information about the protocol's token specifications and ownership characteristics, protocol service fees, slashing and slashing coverage, AML/KYC compliance, and risks associated with staking on Ethereum via the Liquid Collective protocol.

Each unit of LsETH is designed to serve as an electronic document of title to a corresponding amount of fungible ETH within the protocol. The LsETH User Agreement provides that LsETH is a cryptographic receipt that evidences legal and beneficial ownership of a corresponding amount of ETH, which is subject to increase as a result of the accrual of Ethereum network rewards.

cToken

Because of the cToken design, LsETH's Conversion Rate may fluctuate. Depositors in the cToken model do not receive more or less tokens as their staked tokens accrue network rewards or penalties. Instead, the conversion rate for each cToken owned by the depositor will increase or decrease (i.e, the LsETH will evidence legal and beneficial ownership of more or less ETH) in an amount that reflects accrued network rewards or penalties. This is in contrast to other token models, such as aTokens, which issue new net network reward tokens on a unit basis.

Conversion Rate

The internal Conversion Rate is the rate at which Liquid Collective redeems LsETH from/to ETH on deposits and redemptions. In other words, the Conversion Rate is the amount of ETH for which LsETH can be redeemed. The Conversion Rate is independent of the price at which ETH or LsETH may trade on the open market.

The value of LsETH is bound to this internal Conversion Rate which fluctuates over time according to the network rewards earned by the validators. The Conversion Rate is computed as the total balance of staked ETH over the total supply of LsETH. If accrued network rewards are greater than penalties and fees, the internal Conversion Rate will increase to reflect the net network rewards collected by the protocol.

The Conversion Rate is updated every 24 hours at Oracle Report Time, which is when Liquid Collective accounts for network rewards earned.

Formula

What can you do with LsETH?

• Hold LsETH and accrue network rewards

• Exchange LsETH for another token

• Use LsETH as collateral to participate in a wide range of DeFi and dapp activities

What are the tax implications?

While the status of liquid staking activities under the Internal Revenue Code of 1986, as amended, remains uncertain, certain market views have developed around the U.S. tax consequences of liquid staking, including the following:

• Depositing ETH and receiving LsETH may not be deemed a taxable event. Unlike a traditional token exchange (e.g., trading ETH for another token), depositing ETH may not be a token exchange because LsETH is a receipt token that evidences legal and beneficial ownership of the deposited ETH.

• Additionally, because LsETH is based on the cToken model, the accrual of network rewards may not be deemed taxable events, especially when compared to the unit incremental basis in aToken models (or standard staking) for the accrual of network rewards.

Liquid Collective users can deposit ETH to stake on Ethereum. Users can also redeem LsETH for the underlying staked ETH plus network rewards earned, and minus any fees or penalties.

Deposit and Redemption Buffers

The Liquid Collective protocol automatically maintains ETH Deposit and Redemption Buffers. These buffers are designed to ensure that flows in and out of the protocol are managed efficiently between Ethereum’s execution and consensus layers, which enables seamless redemptions of LsETH for ETH via automatic rebalancing.

The protocol’s Deposit Buffer includes ETH pending to be deposited to Ethereum’s consensus layer, while the Redemption Buffer includes ETH pending to be supplied for redemptions.

• ETH deposits enter the Deposit Buffer to be programmatically staked in Ethereum’s consensus layer

• Ethereum execution layer fees received by Liquid Collective validators automatically enter the Deposit Buffer to be programmatically staked

• Ethereum consensus layer network rewards received by Liquid Collective validators automatically enter the Deposit Buffer to be programmatically staked

• Withdrawn validator consensus layer ETH from validator full exits, or slashed validator exits, automatically enter the Redemption Buffer to fund LsETH redemptions

Queues, stacks, and buffers

In addition to the Liquid Collective protocol’s Deposit and Redemption Buffers, the protocol’s Withdrawal Stack, along with Ethereum’s activation and exit queues, play an important role in deposits and redemptions on the Liquid Collective protocol.

Visualization of Withdrawal Stack, Redemption Queue, and Deposit and Redemption Buffers

Below is a step-by-step diagram showing how a request will flow through the protocol’s buffers and stacks.

Deposit ETH

When a user deposits ETH they receive the LsETH receipt token at the current Conversion Rate, which evidences legal and beneficial ownership of the staked token, plus network rewards received and minus any fees or penalties.

Deposited ETH automatically enters the Liquid Collective protocol’s Deposit Buffer. As ETH in the Deposit Buffer reaches a fungible bulk of 32 ETH it is programmatically staked, funding new validator keys and being pushed to Etheruem’s activation queue.

LsETH are minted on deposit, so depositing does not affect the Conversion Rate.

Example

Assuming

• totalETHSupply = 125 ETH

• totalLsETHSupply = 100 LsETH

So conversionRate = 125 / 100 = 1.25

A user deposits 10 ETH and receives 10 / 1.25 = 8 LsETH

And the new conversionRate = (125+10) / (100+8) = 1.25 remains unchanged

Interface level smart contract flow

For more technical audiences, a sequence diagram showing the interaction between smart contracts is included below:

Redeem LsETH

The LsETH receipt token can be redeemed for ETH at the current Conversion Rate, to effectively withdraw the staked token plus network rewards received and minus any fees or penalties.

Three-stage redemption process

LsETH redemptions take place via a three-stage process performed programmatically by the Liquid Collective protocol:

1. Request: the LsETH holder requests a redemption via a Platform (e.g. in the Coinbase Prime app), surrendering the amount of LsETH that they would like to redeem. This LsETH will eventually be burned.

2. Satisfaction: after the protocol completes any required validator exits and the corresponding amount of ETH is withdrawn as according to the protocol Conversion Rate, the request is satisfied and can be claimed at any time.

3. Claim: the redemption request is claimed, triggering the actual transfer of ETH to the redeemer.

Redemption architecture

When a LsETH holder requests a redemption the request is added to the protocol’s Redemption Queue. On each Oracle report, completed approximately every 24 hours, the protocol assesses the unsupplied ETH demand for redemptions.

When there is unsupplied ETH demand:

• The Liquid Collective protocol programmatically rebalance's ETH between the deposit and Redemption Buffers to preserve capital efficiency by minimizing consensus layer operations. The protocol prioritizes moving ETH from the Deposit Buffer to the Redemption Buffer to satisfy the unsupplied redemption requests.

• All Liquid Collective validator keys have their withdrawal credentials set to the address of Liquid Collective’s Withdraw contract, which is automatically pulled to the Redemption Buffer upon Oracle report. The withdrawn ETH is then used by the protocol to satisfy the unsupplied redemptions.

1. A user decides they want to redeem their LsETH for ETH via the Liquid Collective protocol

2. A user's redemption request is enqueued in the Redemption Queue pending satisfaction

3. On each Oracle report, the Liquid Collective protocol evaluates pending LsETH redemption requests and programmatically pulls any ETH from the Deposit Buffer to the Redemption Buffer to satisfy the requests

   • If the balance in the Deposit Buffer is insufficient to satisfy all pending redemption requests the Liquid Collective protocol initiates the exit of a corresponding amount of ETH by programmatically requesting Node Operators to submit validator exits

4. Any redemption request that has been satisfied by the Buffer can be immediately claimed by the user

5. For redemption requests that require a validator exit to satisfy, the validator key enters Ethereum’s exit queue, waits the full network withdrawal time, and, once exited, the validator’s ETH balance is automatically sent by Ethereum to Liquid Collective’s withdrawal address

6. On the Oracle report following the validator exit, the withdrawn ETH satisfies pending redemption requests

7. The user can now claim their ETH

Most stakers can complete this process easily via their preferred Liquid Collective Platform (e.g. in the Coinbase Prime app). At the protocol level, at a high level this request process is executed via interacting with the LsETH contract interface.

• To indicate whether the request has been satisfied, the redeem request id can be submitted along with calling the resolveRedeemRequests function to return withdrawal events corresponding to that redeem request id.

• Once satisfied, the request can be claimed by calling ClaimRedeemRequests along with the redeem request id and corresponding withdrawal event id, which returns a list of claim statuses.

Interface level smart contract flow

For more technical audiences, a sequence diagram showing the interaction between smart contracts is included below:

Redeem status matrix

Redemptions and the Conversion Rate

When users request to redeem LsETH, they will receive ETH based on the available ETH from exited validators or pending deposits, up to the user's LsETH balance multiplied by the protocol conversion rate at the time of the request. If pending deposits are insufficient to fulfill the redemption request, the protocol initiates validator exits to cover the redemption. At the time of the redemption request, the protocol assumes ownership of the user’s LsETH, and the user will no longer be eligible to receive future network rewards. Once validators have fully exited and their effective balance is available, the final ETH amount is determined by the proportion of LsETH being redeemed relative to the total ETH available to withdraw. This means the user remains exposed to penalties and slashing risks until the validators have fully exited.

Example

Assuming

• totalETHSupply = 162 ETH

• totalLsETHSupply = 108 LsETH

So conversionRate = 162 / 108 = 1.5

A user converts 8 LsETH and receives 8 * 1.5 = 12 ETH

And the new conversionRate = (162-12) / (108-8) = 1.5 remains unchanged

Interface level smart contract flow

For more technical audiences, a sequence diagram showing the interaction between smart contracts is included below:

Members

The Oracle holds a list of the Oracle Operators' members who are expected to periodically report Consensus Layer data. These addresses can be checked via an off-chain naive search request.

The Oracle contract is configured such that a representative subset of those Operators are required to report the same Consensus Layer (also referred to as Beacon Chain) data before the Oracle contract reports to the River contract.

Quorum Synchronization

The Oracle is set to report Consensus Layer data to the River contract at configurable Consensus Layer epochs. For each reporting epoch, the Oracle contract expects a quorum of Oracle Operators to report the identical Consensus Layer data before reporting to the River contract.

Epochs

The Oracle contract is configurable so data is reported from a starting epoch and then for every epoch at a given interval.

Quorum

The Oracle contract holds a configurable quorum value that indicates the minimum number of Oracle Operators that must report identical Consensus Layer data before reporting the data to the River contract.

At each reporting epoch, every Oracle Operator is expected to collect Consensus Layer data and report it to the Oracle contract through a transaction. The Oracle contract counts the reported consensus layer balance sum of Liquid Collective validators, the reported count of validators, and the number of similar reports from Oracle Operators, along with the count of report variants.

Any changes to the quorum, such as removing Oracle Operators from the members list, clears all of the reporting data for that epoch. Remaining Oracle Operators that had already submitted reports for that epoch would need to report again for the same epoch.

Once receiving a quorum of identical reports, the Oracle contract publishes the data to the River contract, at which point the River contract can compute and distribute network rewards.

Reports

The Oracle contract aims to report the following data to the River contract:

• Epoch - The epoch for which the Consensus Layer data corresponds to.

• Validators Count – The count of active Liquid Collective validators on the Consensus Layer (either in status active or active_ongoing). This is necessary so River can compute the number of validators in pending status that have been staked to on the Deposit Contract but are not yet active on the Consensus Layer.

• Validators Balance – The total ETH balance of active Liquid Collective validators on the Consensus Layer.

Sanity Checks

The Oracle contract is responsible for performing certain sanity checks on the reported data, providing a layer of security to the protocol in case Oracle Operators behave maliciously.

First, the Oracle contract makes sure that the Oracle Operator's reported transactions are for the correct expected epoch.

Second, it makes sure that the validators' reported balances are coherent. In particular, the Oracle contract:

• Forbids Oracle Operators from reporting earned rewards that would exceed some configurable upper bound of APY. This upper bound takes into account the APY delta between updates extrapolated on a yearly time frame.

• Forbids Oracle Operators from reporting a balance that would have decreased more than some configurable lower bound of fees or penalties. This lower bound is based on the relative balance decrease.

The execution layer fees are taken into account in these sanity checks as they are the product of a Node Operator's work, just like consensus layer fees.

Oracle Data

The Oracle contract receives reports from the Oracle Operators and updates the following data for the River contract:

• Validators Count – The count of active Liquid Collective validators on the Consensus Layer (either in status active or posterior). This count is necessary to compute the count of Liquid Collective validators in pending status that have been funded and deposited to the Deposit Contract but are not yet active on the Consensus Layer.

• Validators Balance – The total ETH balance of active Liquid Validators on the Consensus Layer.

Each time a new report is processed, if Liquid Collective's validators have collectively earned a positive network reward, then this network reward is distributed between parties involved in the Liquid Collective protocol by increasing the Conversion Rate for LsETH.

Because of LsETH's cToken design, the Conversion Rate may fluctuate. In contrast to other token models, such as aTokens, that issue new net network reward tokens on a unit basis, stakers on the Liquid Collective protocol will not receive more or less tokens as they receive network rewards or penalties.

Instead, the Conversion Rate for each unit of LsETH owned by the depositor will increase or decrease (i.e., the LsETH will evidence legal and beneficial ownership of more or less ETH) in an amount that reflects accrued network rewards.

Protocol Service Fee

Network reward collection & Conversion Rate variation

Every day the Liquid Collective protocol accounts for Ethereum network rewards including consensus layer network rewards and execution layer fees minus possible penalties, which results in updating the data reflecting the total supply of ETH.

If network rewards have been earned on a given day, then the protocol collects the Protocol Service Fee as a percentage of the earned network rewards. The Protocol Service Fee is collected by minting LsETH, which results in an increase in the total supply of LsETH.

Under normal validator operations, the protocol earns network rewards; as such the total supply of ETH increases and the Conversion Rate increases accordingly.

Example

Assuming

• totalETHSupply = 125 ETH

• totalLsETHSupply = 100

• protocolFee = 10%

So conversionRate = 125 / 100 = 1.25

Today the protocol earns 10 ETH thus the protocol fee is 10% * 10 ETH / 1.25 = 0.8 LsETH

And the new conversionRate = (125+10) / (108+0.8) = 1.58

Calculating rewards and fees

Each time the Oracle contract reports consensus layer data to the River contract, the protocol programmatically distributes network rewards including consensus layer network rewards and execution layer fees.

Fees received by validators for the execution of transactions are distributed on the execution layer directly. The Liquid Collective protocol automatically stakes the execution layer fees to increase the protocol’s overall potential reward rate by increasing the number of validators in the protocol's active set.

Network reward computation

Each time the Oracle reports consensus layer data, the River smart contract:

• Pulls execution layer fees from the EL Fee Recipient contract

• Updates consensus layer data including the Liquid Collective active validators count and total Liquid Collective active validators balance

The network reward is computed as:

EL Fee Recipient Contract

The EL Fee Recipient Contract receives all of the execution layer fees including transaction fees and MEV priority fees. The River contract periodically pulls that ETH on every Oracle report.

Network reward distribution

If the earned reward is positive, it is distributed between:

• LsETH holders receive 85% of the network rewards, proportional to their LsETH holdings, through an accrual of the Conversion Rate

• Collector that receives the Protocol Service Fee via minting LsETH, which is currently set at 10%

Reward and penalty socialization

Liquid Collective socializes network rewards and penalties between holders proportionally to their LsETH balance. The protocol aims to enforce fairness between participants, making sure that no participant gets treated favorably compared to others.

This means that stakers on Liquid Collective are exposed to the performance of all validators across Liquid Collective as a whole.

Examples:

• If a validator receives a massive MEV network reward, then this network reward is socialized amongst every LsETH holder.

• If a validator gets slashed, then the penalty is socialized amongst every LsETH holder.

This socialization of network rewards and penalties is realized by the LsETH Conversion Rate which applies to every LsETH holder equally. Every 24 hours, Oracle reports the new balance of staked ETH across the protocol accounting for accrued network rewards and penalties, resulting in updating the Conversion Rate, which applies to every LsETH holder.

Validator Infrastructure

The Ethereum protocol requires validators to operate according to a pre-defined set of rules, and Node Operators are economically incentivized to follow those rules.

• Under proper operational conditions, validators collect network rewards by proposing blocks and signing attestations

• Under improper operational conditions, validators can miss network rewards, get penalized, or in worst case scenarios, get slashed

Liquid Collective is designed to provide a secure and enterprise-grade liquid staking solution which necessitates sanctions checks on the protocol’s active validator set. Liquid Collective works only with security-focused Node Operators that institute best practices to generate network rewards, including operating multi-region and multi-client infrastructure, technical support teams, and security posturing (including double-sign protection).

To reduce the risk impact of validator operations, and to increase decentralization, Liquid Collective delegates tokens to multiple independent validator Node Operators. The staked tokens are distributed across Node Operators in a round-robin manner so that the Liquid Collective protocol is supported by a broad and dispersed active validator set. As a result, the risk is distributed, which should minimize staked ETH exposure.

Validator Node Operations

The Operators Registry contract provides facilities for Node Operators to register and manage validator keys on the Liquid Collective protocol. River regularly delegates ETH to Node Operators by funding and depositing validator keys to the Consensus Layer.

Before submitting validator keys for the first time, a Node Operator must complete Liquid Collective's Node Operator approval to be approved on the Operators Registry contracts. This one-time approval enables the Node Operator to register validator keys.

Generate Validator Key

For each validator key to be submitted to the Operators Registry contract, a Node Operator is required to:

• Generate the corresponding DepositMessage and BLS12-381 signature as per the Ethereum 2.0 specifications

• Set the fee recipient to the EL Fee Recipient contract, responsible for collecting execution layer network rewards

The protocol sets the validator's withdrawal credentials to the Liquid Collective Withdrawal contract address when the protocol initiates a deposit transaction for the validator.

Operator Registry Check

Once generated, the Node Operator registers one or more validator keys on the Operator Registry. The Liquid Foundation conducts a sanity check on the keys for compliance with the above requirements, before increasing the operator limit to make validator keys eligible to receive ETH to stake from the Liquid Collective protocol.

Activating Validators

Once a validator has been registered as eligible to receive ETH, its validators keys can be funded at any time. The Liquid Collective protocol regularly programmatically selects eligible validator keys, funds them, and deposits them to the official Ethereum deposit contract. Once deposited, validator keys enter the activation queue as per the standard Ethereum staking procedure.

Node Operator CLI

The Node Operator Command Line Interface is part of the tooling Liquid Collective provides to Node Operators to facilitate protocol operations. The application provides various commands to facilitate Node Operators' management of their validator keys.

Liquid Collective protocol smart contracts expose a metadata URI that resolves to an IPFS directory containing resource files about the protocol.

Metadata directory contains different public resources such as:

• Protocol Terms & Conditions

• Marketing resources such as Liquid Collective logo pack

• Security Audits reports

• etc.

Any user can access the metadata by getting the IPFS URI from the River smart contracts and then retrieving the metadata directory from IPFS.

Oracle Operators are responsible for periodically reporting consensus layer data to the Liquid Collective protocol.

In particular, they are responsible for reporting network rewards earned by validators on the consensus layer so those network rewards can be accounted for, accruing the value of the LsETH token (cToken) by increasing the Conversion Rate.

The Oracle smart contract is responsible for synchronizing Oracle Operators.

Oracle Operators

Oracle operators are responsible for periodically reporting consensus layer data to the execution layer.

In particular, they are responsible for reporting network rewards earned by validators on the consensus layer so those network rewards can be accounted for, accruing the value of the LsETH token (cToken) by increasing the Conversion Rate.

The Oracle smart contract is responsible for synchronizing Oracle operators. In particular it:

• Lists the addresses of Oracle members that are expected to report

• Sets the next target epoch to be reported by Oracle members

• Expects a quorum of Oracle members to report the same data at the target epoch before forwarding it to the River contract

Oracle reports consist of:

• The count of validators on the consensus layer

• The total balance of those validators on the consensus layer

Oracle Operator Procedure

Oracle Operators interested in participating in the Oracle set should go through the following procedure:

1. One-Time Protocol Onboarding

   1. Oracle Operator generates a wallet to be used as Operator members

   2. Oracle member address gets approved on the Oracle smart contract

2. Ongoing Operations

   1. Oracle Operator configures and runs the Oracle daemon in its infrastructure connecting self-managed Ethereum EL and CL clients

   2. Oracle Operator makes sure that the Operator member account always has a sufficient ETH balance to pay for gas fees implied by report transactions

Oracle Daemon

Description

To facilitate operations, Oracle Operators are recommended to use the Oracle daemon which is an open-source application maintained by Liquid Collective. While the Oracle daemon is recommended, it is not mandatory, and Oracle Operators can opt-out of it and use their own preferred solution.

The Oracle daemon is a long-living application that:

• Continuously listens for event logs emitted by the Operators Registry contract

• Calls the Oracle contract to get the next target epoch to report

• Exposes various metrics about the activity of the Oracle

When the target epoch to report is reached, it:

• Collects consensus layer data for the target epoch

• Generates a report from the collected data (validators count and total balance on the consensus layer)

• Sends the report transaction to the Oracle contract

The Oracle daemon can optionally run in --dry-mode in which case it does not send report transactions to the chain.

Architecture

The Oracle daemon needs to be connected to:

• Ethereum Execution Layer RPC endpoint

  • to listen for event logs emitted by the Operator registry contract (in particular events when validator keys get funded)

  • to aggregate all withdrawals data since the Shapella fork

  • to call the Oracle contract for the next epoch to report

• Ethereum Consensus Layer HTTP endpoint

  • to query validator data

The Oracle Daemon also needs access to a private key for signing report transactions. This wallet corresponds to the oracle member address that has been approved on the oracle contract.

Dependencies

• A synced Execution Layer client with JSON-RPC endpoint enabled. All implementations are supported (Geth, Erigon, Besu, etc.)

• A synced Consensus Layer client with API endpoint enabled. All implementations are supported (Prysm, Teku, Lighthouse, etc.)

Installation

The recommended installation is to use the public Docker image public.ecr.aws/alluvial/liquid-collective/lceth:latest

It is also possible to build the binary from sources and run it.

Estimated gas cost

Sending an Oracle report uses about 100,000 gas for a regular report and ~300,000 gas when reaching the quorum.

Let's estimate how much in gas fees an Oracle Operator should pay per year, considering:

• the protocol expects 1 report per day

• the average gas price is 30 gwei

• there are 5 oracle operators

• the quorum is 3

• all operators use an implementation which alternates submissions order

This means that each day there is a 2/5 probability of sending a regular report and a 1/5 probability of sending a report that reaches quorum:

(365 _ 2/5 _ 100000 + 365 _ 1/5 _ 300000) * 30 = 1 095 000 000 Gwei = 1.09 ETH / year

Guidelines

Protocol onboarding

Generate Oracle member wallet

To generate such a wallet you can use the following command:

Submit Oracle member

Submit the Oracle member address to the administrator to get it approved on the Oracle contract members list.

On-going operations

Dry-Run Mode

In dry run the Oracle daemon collects data and generates reports but does not send transactions to the Oracle contract.

It is recommended to use dry run mode when:

• You are not an Oracle Operator and you are only interested in collecting Oracle metrics data

• You are an Oracle Operator and you want to first test in dry run before running in live mode

To run the oracle in dry-run mode, you can run:

Live Mode

In live mode, the daemon runs full capabilities and sends transactions to the chain for every epoch to be reported.

In live mode, you need the daemon to have access to the Oracle member wallet that will be used to sign report transactions.

To run the daemon in live mode, you can run:

Oracle Daemon Command

Monitoring and Metrics

The Oracle service exposes a health endpoint that exposes routes for monitoring:

• /live Liveness endpoint

• /ready Readiness endpoint

• /metrics Prometheus metrics

Platforms provide a seamless on-ramp and access for users to interact with the Liquid Collective protocol. There are two types of Liquid Collective Platforms.

Platforms that enable LsETH minting and redemption

• These Platforms enable direct Liquid Collective protocol interactions, including depositing ETH to Ethereum's deposit contract and redeeming LsETH for ETH (minting and redeeming).

• They conduct know-your-customer (KYC) and anti money laundering (AML) checks on their users, and submit approved user addresses to Liquid Collective's Allowlist.

• These Platforms then provide a path to deposit and withdraw staked tokens.

In other words, KYC'd users who utilize a Platform's services can deposit to Liquid Collective and mint LsETH.

[!NOTE] Users, also called stakers, are entities interested in staking ETH using the Liquid Collective protocol to mint the LsETH receipt token in return, evidencing their legal and beneficial ownership of the staked ETH plus rewards accrued and minus any fees or penalties. Before depositing ETH and minting LsETH, a user needs to go through an effective KYC/AML and sanctions screening process. After successfully completing the KYC/AML and sanctions screening process with a Platform, the user's wallet address can be added to Liquid Collective's Allowlist smart contract, authorizing deposit and redemption transactions.

Platforms that enable secondary interactions

• These Platforms do not enable minting, redeeming, or direct Liquid Collective protocol interactions, but do enable secondary protocol interactions such as trading, lending, or other services not required to Allowlist KYC/AML wallet addresses.

• Users of these Platforms can seamlessly interact with LsETH, and may accrue Ethereum's consensus and execution layer network rewards simply by holding LsETH.

By default, LsETH holders can transfer LsETH.

Enterprise integration APIs

Alluvial Finance Inc.

Redeem Manager (v1)

This contract handles the redeem requests of all users

Methods

claimRedeemRequests

Claims the rewards of the provided redeem request ids

Parameters

Returns

claimRedeemRequests

Claims the rewards of the provided redeem request ids

Parameters

Returns

getBufferedExceedingEth

Retrieve the amount of redeemed LsETH pending to be supplied with withdrawn ETH

Returns

getRedeemDemand

Retrieve the amount of LsETH waiting to be exited

Returns

getRedeemRequestCount

Retrieve the global count of redeem requests

Returns

getRedeemRequestDetails

Retrieve the details of a specific redeem request

Parameters

Returns

getRiver

Retrieve River address

Returns

getWithdrawalEventCount

Retrieve the global count of withdrawal events

Returns

getWithdrawalEventDetails

Retrieve the details of a specific withdrawal event

Parameters

Returns

initializeRedeemManagerV1

Parameters

initializeRedeemManagerV1_2

pullExceedingEth

Pulls exceeding buffer eth

Parameters

reportWithdraw

Reports a withdraw event from River

Parameters

requestRedeem

Creates a redeem request

Parameters

Returns

requestRedeem

Creates a redeem request using msg.sender as recipient

Parameters

Returns

resolveRedeemRequests

Resolves the provided list of redeem request ids

The result is an array of equal length with ids or error code-1 means that the request is not satisfied yet-2 means that the request is out of bounds-3 means that the request has already been claimedThis call was created to be called by an off-chain interface, the output could then be used to perform the claimRewards call in a regular transaction

Parameters

Returns

version

Retrieves the version of the contract

Returns

Events

ClaimedRedeemRequest

Emitted when a redeem request claim has been processed and matched at least once and funds are sent to the recipient

Parameters

Initialize

Emitted when the contract is properly initialized

Parameters

ReportedWithdrawal

Emitted when a withdrawal event is created

Parameters

RequestedRedeem

Emitted when a redeem request is created

Parameters

SatisfiedRedeemRequest

Emitted when a redeem request has been satisfied and filled (even partially) from a withdrawal event

Parameters

SetRedeemDemand

Emitted when the redeem demand is set

Parameters

SetRiver

Emitted when the River address is set

Parameters

Errors

ClaimInitiatorIsDenied

Thrown when the claim initiator is denied

ClaimRecipientIsDenied

Thrown when the claim recipient is denied

ClaimRedeemFailed

Thrown when the payment after a claim failed

Parameters

DoesNotMatch

Thrown when the redeem request and withdrawal event are not matching during claim

Parameters

IncompatibleArrayLengths

Thrown when the provided arrays don't have matching lengths

InvalidInitialization

An error occurred during the initialization

Parameters

InvalidZeroAddress

The address is zero

InvalidZeroAmount

Thrown When a zero value is provided

RecipientIsDenied

Thrown when the recipient of redeemRequest is denied

RedeemRequestAlreadyClaimed

Thrown when the redeem request id is already claimed

Parameters

RedeemRequestOutOfBounds

Thrown when the provided redeem request id is out of bounds

Parameters

TransferError

Thrown when a transfer error occurred with LsETH

Unauthorized

The operator is unauthorized for the caller

Parameters

WithdrawalEventOutOfBounds

Thrown when the withdrawal request id if out of bounds

Parameters

WithdrawalExceedsRedeemDemand

Thrown when the provided withdrawal event exceeds the redeem demand

Parameters

Alluvial Finance Inc.

Execution Layer Fee Recipient (v1)

This contract receives all the execution layer fees from the proposed blocks + bribes

Methods

initELFeeRecipientV1

function initELFeeRecipientV1(address _riverAddress) external nonpayable

Initialize the fee recipient with the required arguments

Parameters

pullELFees

function pullELFees(uint256 _maxAmount) external nonpayable

Pulls ETH to the River contract

Only callable by the River contract

Parameters

version

function version() external pure returns (string)

Retrieves the version of the contract

Returns

Events

Initialize

event Initialize(uint256 version, bytes cdata)

Emitted when the contract is properly initialized

Parameters

SetRiver

event SetRiver(address indexed river)

The storage river address has changed

Parameters

Errors

InvalidCall

error InvalidCall()

The fallback has been triggered

InvalidInitialization

error InvalidInitialization(uint256 version, uint256 expectedVersion)

An error occurred during the initialization

Parameters

InvalidZeroAddress

error InvalidZeroAddress()

The address is zero

Unauthorized

error Unauthorized(address caller)

The operator is unauthorized for the caller

Parameters

Figment

Firewall

This contract accepts calls to admin-level functions of an underlying contract, and ensures the caller holds an appropriate role for calling that function. There are two roles:

• An Admin can call anything

• An Executor can call specific functions

The list of function is customizable. Random callers cannot call anything through this contract, even if the underlying function is unpermissioned in the underlying contract. Calls to non-admin functions should be called at the underlying contract directly.

Methods

acceptAdmin

function acceptAdmin() external nonpayable

Accept the transfer of ownership

Only callable by the pending admin. Resets the pending admin if successful.

allowExecutor

function allowExecutor(bytes4 _functionSelector, bool _executorCanCall) external nonpayable

Sets the permission for a function selector

Parameters

destination

function destination() external view returns (address)

Retrieve the destination address

Returns

executor

function executor() external view returns (address)

Retrieve the executor address

Returns

executorCanCall

function executorCanCall(bytes4) external view returns (bool)

Returns true if the executor is allowed to perform a call on the given selector

Parameters

Returns

getAdmin

function getAdmin() external view returns (address)

Retrieves the current admin address

Returns

getPendingAdmin

function getPendingAdmin() external view returns (address)

Retrieve the current pending admin address

Returns

proposeAdmin

function proposeAdmin(address _newAdmin) external nonpayable

Proposes a new address as admin

This security prevents setting an invalid address as an admin. The pending admin has to claim its ownership of the contract, and prove that the new address is able to perform regular transactions.

Parameters

setExecutor

function setExecutor(address _newExecutor) external nonpayable

Sets the executor address

Parameters

version

function version() external pure returns (string)

Retrieves the version of the contract

Returns

Events

SetAdmin

event SetAdmin(address indexed admin)

The admin address changed

Parameters

SetDestination

event SetDestination(address indexed destination)

The stored destination address has been changed

Parameters

SetExecutor

event SetExecutor(address indexed executor)

The stored executor address has been changed

Parameters

SetExecutorPermissions

event SetExecutorPermissions(bytes4 selector, bool status)

The storage permission for a selector has been changed

Parameters

SetPendingAdmin

event SetPendingAdmin(address indexed pendingAdmin)

The pending admin address changed

Parameters

Errors

InvalidZeroAddress

error InvalidZeroAddress()

The address is zero

Unauthorized

error Unauthorized(address caller)

The operator is unauthorized for the caller

Parameters

Alluvial Finance Inc.

Coverage Fund (v1)

This contract receive donations for the slashing coverage fund and pull the funds into riverThis contract acts as a temporary buffer for funds that should be pulled in case of a loss of money on the consensus layer due to slashing events.There is no fee taken on these funds, they are entirely distributed to the LsETH holders, and no shares will get minted.Funds will be distributed by increasing the underlying value of every LsETH share.The fund will be called on every report and if eth is available in the contract, River will attempt to pull as much ETH as possible. This maximum is defined by the upper bound allowed by the Oracle. This means that it might take multiple reports for funds to be pulled entirely into the system due to this upper bound, ensuring a lower secondary market impact.The value provided to this contract is computed off-chain and provided manually by Alluvial or any authorized insurance entity.The Coverage funds are pulled upon an oracle report, after the ELFees have been pulled in the system, if there is a margin left before crossing the upper bound. The reason behind this is to favor the revenue stream, that depends on market and network usage, while the coverage fund will be pulled after the revenue stream, and there won't be any commission on the eth pulled.Once a Slashing event occurs, the team will do its best to inject the recovery funds in at maximum 365 days. The entities allowed to donate are selected by the team. It will mainly be treasury entities or insurance protocols able to fill this coverage fund properly.

Methods

donate

function donate() external payable

Donates ETH to the coverage fund contract

initCoverageFundV1

function initCoverageFundV1(address _riverAddress) external nonpayable

Initialize the coverage fund with the required arguments

Parameters

pullCoverageFunds

function pullCoverageFunds(uint256 _maxAmount) external nonpayable

Pulls ETH into the River contract

Only callable by the River contract

Parameters

version

function version() external pure returns (string)

Retrieves the version of the contract

Returns

Events

Donate

event Donate(address indexed donator, uint256 amount)

A donation has been made to the coverage fund

Parameters

Initialize

event Initialize(uint256 version, bytes cdata)

Emitted when the contract is properly initialized

Parameters

SetRiver

event SetRiver(address indexed river)

The storage river address has changed

Parameters

Errors

EmptyDonation

error EmptyDonation()

A donation with 0 ETH has been performed

InvalidCall

error InvalidCall()

The fallback or receive callback has been triggered

InvalidInitialization

error InvalidInitialization(uint256 version, uint256 expectedVersion)

An error occurred during the initialization

Parameters

InvalidZeroAddress

error InvalidZeroAddress()

The address is zero

Unauthorized

error Unauthorized(address caller)

The operator is unauthorized for the caller

Parameters

Alluvial Finance Inc.

Administrable

This contract handles the administration of the contracts

Methods

acceptAdmin

function acceptAdmin() external nonpayable

Accept the transfer of ownership

Only callable by the pending admin. Resets the pending admin if successful.

getAdmin

function getAdmin() external view returns (address)

Retrieves the current admin address

Returns

getPendingAdmin

function getPendingAdmin() external view returns (address)

Retrieve the current pending admin address

Returns

proposeAdmin

function proposeAdmin(address _newAdmin) external nonpayable

Proposes a new address as admin

This security prevents setting an invalid address as an admin. The pending admin has to claim its ownership of the contract, and prove that the new address is able to perform regular transactions.

Parameters

Events

SetAdmin

event SetAdmin(address indexed admin)

The admin address changed

Parameters

SetPendingAdmin

event SetPendingAdmin(address indexed pendingAdmin)

The pending admin address changed

Parameters

Errors

InvalidZeroAddress

error InvalidZeroAddress()

The address is zero

Unauthorized

error Unauthorized(address caller)

The operator is unauthorized for the caller

Parameters

Alluvial Finance Inc.

TLC (v1)

The TLC token has a max supply of 1,000,000,000 and 18 decimal places.Upon deployment, all minted tokens are send to account provided at construction, in charge of creating the vesting schedulesThe contract is based on ERC20Votes by OpenZeppelin. Users need to delegate their voting power to someone or themselves to be able to vote.The contract contains vesting logics allowing vested users to still be able to delegate their voting power while their tokens are held in an escrow

Methods

CLOCK_MODE

function CLOCK_MODE() external view returns (string)

Description of the clock

Returns

DOMAIN_SEPARATOR

function DOMAIN_SEPARATOR() external view returns (bytes32)

See {IERC20Permit-DOMAIN_SEPARATOR}.

Returns

allowance

function allowance(address owner, address spender) external view returns (uint256)

See {IERC20-allowance}.

Parameters

Returns

approve

function approve(address spender, uint256 amount) external nonpayable returns (bool)

See {IERC20-approve}. NOTE: If amount is the maximum uint256, the allowance is not updated on transferFrom. This is semantically equivalent to an infinite approval. Requirements: - spender cannot be the zero address.

Parameters

Returns

balanceOf

function balanceOf(address account) external view returns (uint256)

See {IERC20-balanceOf}.

Parameters

Returns

checkpoints

function checkpoints(address account, uint32 pos) external view returns (struct ERC20VotesUpgradeable.Checkpoint)

Get the pos-th checkpoint for account.

Parameters

Returns

clock

function clock() external view returns (uint48)

Clock used for flagging checkpoints. Can be overridden to implement timestamp based checkpoints (and voting).

Returns

computeVestingReleasableAmount

function computeVestingReleasableAmount(uint256 _index) external view returns (uint256)

Computes the releasable amount of tokens for a vesting schedule.

Parameters

Returns

computeVestingVestedAmount

function computeVestingVestedAmount(uint256 _index) external view returns (uint256)

Computes the vested amount of tokens for a vesting schedule.

Parameters

Returns

createVestingSchedule

function createVestingSchedule(uint64 _start, uint32 _cliffDuration, uint32 _duration, uint32 _periodDuration, uint32 _lockDuration, bool _revocable, uint256 _amount, address _beneficiary, address _delegatee, bool _ignoreGlobalUnlockSchedule) external nonpayable returns (uint256)

Creates a new vesting scheduleThere may delay between the time a user should start vesting tokens and the time the vesting schedule is actually created on the contract.Typically a user joins the Liquid Collective but some weeks pass before the user gets all legal agreements in place and signed for the token grant emission to happen. In this case, the vesting schedule created for the token grant would start on the join date which is in the past.

As vesting schedules can be created in the past, this means that you should be careful when creating a vesting schedule and what duration parameters you use as this contract would allow creating a vesting schedule in the past and even a vesting schedule that has already ended.

Parameters

Returns

decimals

function decimals() external view returns (uint8)

Returns the number of decimals used to get its user representation. For example, if decimals equals 2, a balance of 505 tokens should be displayed to a user as 5.05 (505 / 10 ** 2). Tokens usually opt for a value of 18, imitating the relationship between Ether and Wei. This is the default value returned by this function, unless it's overridden. NOTE: This information is only used for display purposes: it in no way affects any of the arithmetic of the contract, including {IERC20-balanceOf} and {IERC20-transfer}.

Returns

decreaseAllowance

function decreaseAllowance(address spender, uint256 subtractedValue) external nonpayable returns (bool)

Atomically decreases the allowance granted to spender by the caller. This is an alternative to {approve} that can be used as a mitigation for problems described in {IERC20-approve}. Emits an {Approval} event indicating the updated allowance. Requirements: - spender cannot be the zero address. - spender must have allowance for the caller of at least subtractedValue.

Parameters

Returns

delegate

function delegate(address delegatee) external nonpayable

Delegate votes from the sender to delegatee.

Parameters

delegateBySig

function delegateBySig(address delegatee, uint256 nonce, uint256 expiry, uint8 v, bytes32 r, bytes32 s) external nonpayable

Delegates votes from signer to delegatee

Parameters

delegateVestingEscrow

function delegateVestingEscrow(uint256 _index, address _delegatee) external nonpayable returns (bool)

Delegate vesting escrowed tokens

Parameters

Returns