1 of 100

Live

ETH Liquid Staking Documentation

Liquid Collective is a decentralized liquid staking protocol. Multi-chain capable, Liquid Collective launched Ethereum liquid staking first and aims to implement liquid staking for other networks in the future.

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

For general Liquid Collective documentation, visit Liquid Collective's core documentation here.

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.

When a user deposits a token (ETH) into the Liquid Collective protocol, they receive a liquid staking token, that evidences legal and beneficial ownership of the staked ETH as well as any network rewards that accrue to the staked ETH, minus protocol service fees and network slashing penalties, if any. The receipt token can be transferred, stored, traded, and utilized in decentralized finance (DeFi) or supported decentralized apps (dapps).

LsETH is able to represent both staked ETH and any network rewards earned by following the , supporting LsETH's composability while providing participants with the ability to control their network reward flow
Liquid Collective offers to every participant via the to mitigate the risk of Node Operator failures and network outages
Liquid Collective's reduces correlation by spreading stake round-robin across a distributed network of Node Operators

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

Overview

Roles & Staking Infrastructure

The roles in Liquid Collective's Ethereum implementation, and staking infrastructure overview.

Key roles in Liquid Collective

The teams building and operating Liquid Collective work together to ensure the smooth functioning of the protocol and provide a seamless and secure Ethereum staking experience. You can learn more about Liquid Collective's approach to working with these roles in our post.

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.

In the Liquid Collective protocol's Platforms are also referred to as Allowlisters, as Platforms that enable minting and redemption currently function as the agents responsible for adding users to the Allowlist.

You can learn more about Liquid Collective Platforms in the .

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.

Examples of Liquid Collective Service Providers include , , , and Hypernative.

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.

You can learn more about Liquid Collective Node Operators in the .

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.

Oracles report to Liquid Collective's core contract on the balance of underlying staked tokens plus accrued staking rewards, minus any slashing penalties. This information informs for deposit and withdrawal (when supported, after withdrawals are enabled on Ethereum), alongside supporting DeFi reporting.

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.

Node Operators in Liquid Collective's active set also support the protocol's by providing coverage for deductibles, up to a cap, against slashing incidents and missed rewards incurred due to the fault of their infrastructure.

You can find in-depth technical documentation on Liquid Collective's Ethereum validator infrastructure in .

Architecture

Liquid Collective's protocol architecture on Ethereum

Smart Contracts

River

Staking Amounts

Users can deposit and stake any amount of ETH

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.

Each staker retains legal and beneficial ownership of an amount of ETH that is equivalent to the amount of ETH that was deposited by the staker, as evidenced by its LsETH receipt token. Receipt tokens like LsETH evidence legal and beneficial ownership of the deposited token, and ownership of the token is maintained throughout the life of the receipt token.

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.

Slashing Coverage

Three layers of slashing coverage are available for every participant staking through the Liquid Collective protocol

Slashing Coverage enables certain Liquid Collective partners to reimburse LsETH holders following a slashing incident. Liquid Collective's Slashing Coverage Program is included in the ; as such, participation in the program requires no further action than holding LsETH.

includes three layers of coverage: Nexus Mutual Coverage, the Slashing Coverage Treasury, and the Node Operator Commitment. The program covers both network-wide events—such as network outages—and node operator failures.

Permissioning

Provide users with protections over protocol access for compliance, while ensuring composability with the rest of the DeFi ecosystem

Liquid Collective is designed to provide users with protections over protocol access via know-your-customer (KYC) and anti-money-laundering (AML) verification, while still ensuring composability with the rest of the DeFi ecosystem.

This facilitates compliance by providing the level of counterparty risk management required for enterprises and institutions to participate in staking on the protocol.

The Liquid Collective protocol:

Requires users to be on the Allowlist before they can deposit ETH or redeem LsETH

Protocol Metadata

Liquid Collective protocol metadata

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.

Below is an example of an RPC call to get Liquid Collective metadata URI using

Deployment Addresses

Liquid Collective deployment addresses

Contract

Mainnet

Hoodi

Tokenomics

LsETH (cToken)

Liquid Staked ETH, Liquid Collective's liquid staking token

LsETH is a fungible receipt token based on the Ethereum ERC-20 cToken model. When a user deposits ETH to the Liquid Collective protocol, they receive an equivalent amount of LsETH that evidences their legal and beneficial ownership of the deposited ETH, as well as any network rewards that accrue to the ETH as a result of staking minus protocol service fees and network slashing penalties, if any.

Ethereum mainnet: Verify the LsETH token address on Etherscan here. The LsETH contract address is: 0x8c1BEd5b9a0928467c9B1341Da1D7BD5e10b6549

Base L2: Verify the . The LsETH contract address is: 0xB29749498954A3A821ec37BdE86e386dF3cE30B6

LsETH User Agreement

By obtaining LsETH, participants agree to the terms of the , which remains in effect for as long as the participant holds LsETH.

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.

To ensure open transparency into the agreement's terms, the LsETH User Agreement is additionally both encoded into the metadata of the LsETH smart contract and stored on-chain in IPFS .

You can learn more about the LsETH User Agreement and its innovations in our .

cToken

LsETH implements the , which uses a floating conversion rate—a.k.a. the protocol conversion rate—between a receipt token (e.g. LsETH) and the staked tokens to reflect the value of accrued network rewards, penalties, and fees associated with the staked tokens.

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

At first deposit, the conversionRate is set to 1.

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?

DISCLAIMER: This information is intended for informational purposes only and is not, and shall not be construed, to be any form of tax advice. All liquid staking participants are strongly encouraged to consult with their tax advisers to fully understand the tax implications of staking and liquid staking.

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.

Node Operations

Validator Infrastructure

Decentralized set of approved enterprise-grade Node Operators reduces the risks of validator operations

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).

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.

To see a step by step workflow for the Node Operator CLI, check out the guide.

Oracles

Oracle Infrastructure

Oracle operations on Liquid Collective report on consensus layer data

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.

In the current deployment, this interval is configured so consensus layer data is reported approximately every 24 hours.

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.

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.

Platforms

Platform Operations

Platforms provide a seamless on-ramp and access for users to interact with the Liquid Collective protocol.

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

The Liquid Collective protocol currently uses Alluvial's API services to facilitate Platform onboarding. Platform guides can be found in the .

Platforms offering KYC procedures for their users may submit user wallet addresses using the to register the addresses with the Liquid Collective Allowlist contract.

Technical Reference

Smart Contracts

Administrable

Alluvial Finance Inc.

Administrable

This contract handles the administration of the contracts

Methods

Initializable

Alluvial Finance Inc.

Initializable

This contract ensures that initializers are called only once per version

Events

ProtocolMetrics

Methods

getRate

Returns

Name

Type

Description

initProtocolMetricsV1

Parameters

Name

Type

Description

Events

Initialize

Emitted when the contract is properly initialized

Parameters

Name

Type

Description

Errors

InvalidInitialization

An error occurred during the initialization

Parameters

Name

Type

Description

InvalidZeroAddress

The address is zero

Components

UserDepositManagerV1

Alluvial Finance Inc.

User Deposit Manager (v1)

This contract handles the inbound transfers cases or the explicit submissions

Methods

deposit

Explicit deposit method to mint on msg.sender

depositAndTransfer

Explicit deposit method to mint on msg.sender and transfer to _recipient

Parameters

Name

Type

Description

Events

UserDeposit

User deposited ETH in the system

Parameters

Name

Type

Description

Errors

EmptyDeposit

And empty deposit attempt was made

InvalidCall

The call was invalid

InvalidZeroAddress

The address is zero

Interfaces

IAdministrable

Alluvial Finance Inc.

Administrable Interface

This interface exposes methods to handle the ownership of the contracts

Methods

acceptAdmin

Accept the transfer of ownership

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

getAdmin

Retrieves the current admin address

Returns

Name

Type

Description

getPendingAdmin

Retrieve the current pending admin address

Returns

Name

Type

Description

proposeAdmin

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

Name

Type

Description

Events

SetAdmin

The admin address changed

Parameters

Name

Type

Description

SetPendingAdmin

The pending admin address changed

Parameters

Name

Type

Description

IRedeemManagerV1

IUserDepositManagerV1

Alluvial Finance Inc.

User Deposit Manager (v1)

This interface exposes methods to handle the inbound transfers cases or the explicit submissions

Methods

deposit

Explicit deposit method to mint on msg.sender

depositAndTransfer

Explicit deposit method to mint on msg.sender and transfer to _recipient

Parameters

Name

Type

Description

Events

UserDeposit

User deposited ETH in the system

Parameters

Name

Type

Description

Errors

EmptyDeposit

And empty deposit attempt was made

IWithdrawV1

Alluvial Finance Inc.

Withdraw Interface (V1)

This contract is in charge of holding the exit and skimming funds and allow river to pull these funds

Methods

getCredentials

Retrieve the withdrawal credentials to use

Returns

Name

Type

Description

getRiver

Retrieve the linked River address

Returns

Name

Type

Description

initializeWithdrawV1

Parameters

Name

Type

Description

pullEth

Callable by River, sends the specified amount of ETH to River

Parameters

Name

Type

Description

Events

SetRiver

Emitted when the linked River address is changed

Parameters

Name

Type

Description

ICoverageFundV1

Alluvial Finance Inc.

Coverage Fund Interface (v1)

This interface exposes methods to receive donations for the slashing coverage fund and pull the funds into river

Methods

IDepositContract

Deposit Contract Interface

This interface exposes methods to perform validator deposits

Methods

IELFeeRecipientV1

Alluvial Finance Inc.

Execution Layer Fee Recipient Interface (v1)

This interface exposes methods to receive all the execution layer fees from the proposed blocks + bribes

Methods

initELFeeRecipientV1

Initialize the fee recipient with the required arguments

Parameters

Name

Type

Description

pullELFees

Pulls ETH to the River contract

Only callable by the River contract

Parameters

Name

Type

Description

Events

SetRiver

The storage river address has changed

Parameters

Name

Type

Description

Errors

InvalidCall

The fallback has been triggered

IProtocolVersion

Methods

version

Retrieves the version of the contract

Libraries

LibBytes

Lib Bytes

This library helps manipulating bytes

Errors

SliceOutOfBounds

The slice is outside of the initial bytes bounds

SliceOverflow

The length overflows an uint

LibErrors

Lib Errors

Library of common errors

Errors

LibBasisPoints

Lib Basis Points

Holds the basis points max value

LibSanitize

Lib Sanitize

Utilities to sanitize input values

LibAdministrable

Alluvial Finance Inc.

Lib Administrable

This library handles the admin and pending admin storage vars

LibUnstructuredStorage

Lib Unstructured Storage

Utilities to work with unstructured storage

LibAllowlistMasks

Lib Allowlist Masks

Holds all the mask values

LibUint256

Lib Uint256

Utilities to perform uint operations

State

OperatorsRegistry

OperatorsV2

Operators Storage

Utility to manage the Operators in storage

Errors

OperatorNotFound

The operator was not found

Parameters

Name

Type

Description

CurrentValidatorExitsDemand

CurrentValidatorExitsDemand Storage

This value controls the current demand for exits that still need to be triggered in order to notify the operatorsUtility to manage the CurrentValidatorExitsDemand in storage

ValidatorKeys

Validator Keys Storage

Utility to manage the validator keys in storage

Errors

TotalValidatorExitsRequested

TotalValidatorExitsRequested Storage

This value is the amount of performed exit requests, only increased when there is current exit demandUtility to manage the TotalValidatorExitsRequested in storage

AllowList

AllowerAddress

Allower Address Storage

Utility to manage the Allower Address in storage

DenierAddress

Denier Address Storage

Utility to manage the Denier Address in storage

Allowlist

Allowlist Storage

Utility to manage the Allowlist mapping in storage

Oracle

LastEpochId

Last Epoch Id Storage

Utility to manage the Last Epoch Id in storage

OracleMembers

Oracle Members Storage

Utility to manage the Oracle Members in storage

There can only be up to 256 oracle members. This is due to how report statuses are stored in Reports Positions

Quorum

Quorum Storage

Utility to manage the Quorum in storage

ReportsPositions

Reports Positions Storage

Utility to manage the Reports Positions in storage

Each bit in the stored uint256 value tells if the member at a given index has reported

ReportsVariants

Reports Variants Storage

Utility to manage the Reports Variants in storage

RedeemManager

BufferedExceedingEth

Buffered Exceeding Eth storage

Redeem Manager utility to manage the exceeding ETH with a redeem request

RedeemDemand

Redeem Demand storage

Redeem Manager utility to store the current demand in LsETH

RedeemQueueV2

Redeem Manager Redeem Queue storage

Utility to manage the Redeem Queue in the Redeem Manager

WithdrawalStack

Redeem Manager Withdrawal Stack storage

Utility to manage the Withdrawal Stack in the Redeem Manager

River

AllowlistAddress

Allowlist Address Storage

Utility to manage the Allowlist Address in storage

BalanceToDeposit

BalanceToRedeem

CLSpec

Consensus Layer Spec Storage

Utility to manage the Consensus Layer Spec in storage

CLValidatorCount

Consensus Layer Validator Count Storage

Utility to manage the Consensus Layer Validator Count in storageThis state variable is deprecated and was kept due to migration logic needs

Deposits & Redemptions

Staking ETH to mint LsETH, and redeeming LsETH for ETH, on Liquid Collective

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.

Note: Depending on the amount of ETH the protocol's Deposit Buffer, a validator may need to be exited from Ethereum to service a LsETH redemption request. When a validator is exited, it is subject to the Ethereum network's variable exit and withdrawal queues, which can take minutes to days. It's recommended to review the current maximum exit queue and withdraw queue times here.

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

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

Note: Figures above are just examples and do not reflect reality or projections.

Interface level smart contract flow

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

For those that want to view a stack trace, we recommend using a tool like .

Here is a sample transaction hash on mainnet: Deposit: 0xace4dc0272645d9e0120f25a478d1b7375cc42dd4b1c0369bd00d02847e54e25 Oracle Report: 0x67d44ab16ece7c2adcc97b538359f4c21fc10a09413d7014962c5dc5b79e4cb0

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.

Redemption requests on the Liquid Collective protocol cannot be canceled once they have been made. This is because validator exits cannot be canceled on Ethereum once they have been triggered.

Three-stage redemption process

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

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.
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.
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.
If there is still unsupplied redemption demand, the protocol requests validator exits by signaling Node Operators. Upon receiving this request, the appropriate number of validators are entered to Ethereum’s exit queue, where they are subject to .
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.

A user decides they want to redeem their LsETH for ETH via the Liquid Collective protocol
A user's redemption request is enqueued in the Redemption Queue pending satisfaction
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

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.

When a redemption request is submitted by calling the requestRedeem function, a redeem request id is returned by either using the or subscribing to RequestedRedeem events.
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:

For those that want to view a stack trace, we recommend using a tool like .

Here is a sample transaction hash on mainnet: Request Redeem: 0x996bab264e831a12618c9e942b2d30a410c62db908c16efbd9fc5e44e30b1f5c Oracle Report: 0x67d44ab16ece7c2adcc97b538359f4c21fc10a09413d7014962c5dc5b79e4cb0

Redeem status matrix

Platforms can learn more about this process in the

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

Note: Figures above are just examples and do not reflect reality or projections.

Interface level smart contract flow

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

For those that want to view a stack trace, we recommend using a tool like .

Here is a sample transaction hash on mainnet: Request Redeem: 0xd8c39cf80d388c8ce55b519336b5f53074805156b5d416e96116c90dc73b2577 Oracle Report: 0x67d44ab16ece7c2adcc97b538359f4c21fc10a09413d7014962c5dc5b79e4cb0

Operate an Oracle

Operator running Oracle

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.

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:

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

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

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.

Since the Shapella fork, it has become necessary to retrieve withdrawals for all Liquid Collective validators. However, there is no available API for this task. One solution is to read all blocks, but this consumes a large number of requests. An alternative solution is to implement a stateful approach.

As a result, we have decided to introduce a new flag in the lceth CLI, --data-dir, which stores the state of withdrawals. The stored state encompasses all withdrawals and their corresponding blocks. (The estimated size of the storage is approximately 4 GB.)

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

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:

Once generated you should securely store the key file and password for later usage, as you will need it each time you will run the Oracle daemon.

Submit Oracle member

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

On-going operations

Oracle has become stateful; be sure to choose an appropriate data directory using the --data-dir flag.

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.

Top up Oracle Operator account

Before starting the daemon you should make sure that the Oracle Operator account has been topped-up with ETH so it can pay for the gas fees for the report transactions.

After starting the daemon, an Oracle Operator should make sure that the Oracle member account always has a sufficient balance of ETH to send 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

Operate Validator Nodes

This guide is intended for Node Operators participating in the Liquid Collective protocol.

Operate Validator Nodes

Node Operators are validator infrastructure providers responsible for running validator nodes on the Ethereum consensus layer in the name of the protocol. Node Operators must have the capacity to scale to a large number of validator nodes, meet certain compliance requirements, and meet certain performance requirements, including Liquid Collective's Node Operator Performance SLAs.

Node Operators receive ETH delegation from the protocol and they are remunerated proportionally to the delegation they receive.

Operate Validator Nodes

Node Operator Procedure

Node Operators interested in receiving ETH delegation should go through the following flow.

One-time protocol onboarding
1. Node operator generates Node Operator wallet
2. Node Operator address gets approved on the Node Operator registry contracts

CLI

provides various commands to facilitate Node Operators in the process of managing validator keys.

CLI is compatible with the and can be used in conjunction with it.

Installation

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

It is also possible to build the binary from sources.

Guidelines

Protocol Onboarding

Generate (or Import) Node Operator Wallet

The Node Operator needs a wallet to submit validator keys. The wallet must be approved on the Node Operator Registry Contract.

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

Once generated or imported you should securely store the key file and password for later usage, as you will need it each time you need to register keys.

It is also possible to import an existing wallet:

Approve Node Operator Wallet

A Node Operator should provide administrators with:

name: As the Node Operator will be publicly listed on the Node Operator contract
address: The Node Operator wallet address previously generated

Those values can be updated at any time after first approval.

Node Operator Index

Once approved, a Node Operator will get its operator index on the Node Operators Registry. This index will never change over time.

To get your node operator index, run the below command and find your name in the returned list.

Ongoing Operations: Pre-Registration of Validator Keys

Pre-registering validators consists of submitting new validators keys to the Node Operators registry contract so they can be picked for validation and funded.

As a Node Operator, you should typically pre-register new validators keys when:

It is the first time you pre-register keys
Most of the keys that you have pre-registered have been funded

It is the responsibility of the Node Operator to make sure validator keys are available for funding.

In the case that a Node Operator has no validator keys available, it will not receive an ETH delegation from the protocol.

Generate validator keys, deposit data and signatures

A Node Operator is responsible for generating validator keys in its own infrastructure.

For each generated key, a Node Operator is also expected to generate the corresponding DepositMessage and BLS12-381 signature as per the

Node Operators are required to set withdrawal credentials to the address of Withdrawal contract.

Per , once a Type 1 (0x01) withdrawal address is set those withdrawal credentials cannot be changed.

To get withdrawal credentials you can run:

As a result of the validator key generation, a Node Operator should obtain a JSON file matching the following format:

It is possible to use the to generate keys, which produces a file in the above format.

Configure validator exec layer fee recipient address

Node Operators are required to set the fee recipient of the validators to the ELFeeRecipient contract that is responsible to flow the execution layer network rewards to the core River contract.

To get the ELFeeRecipient address you can run:

Exec layer fee recipient address and withdrawal address are not the same.

Submit validator keys

Submit validator keys consists of sending a addValidatorKeys(...) transaction to the OperatorsRegistry contract. The transactions should be signed by the Node Operator address:

To submit validator keys you can run the following command:

The container runs with 65532:65532 and the keystore directory should be created and then chown'd to the user.

Once the transaction has been sent to the network and validated, the validator keys are listed on the Node Operators Registry contract and will be reviewed by the administrator.

Deposit and Node Activation

Node Operators should be careful that validator keys can be picked, funded, and deposited to the official Ethereum Deposit Contract at any time.

Once a validator key has been funded and deposited, it enters the activation queue. When this happens, the Node Operator should make sure that the corresponding validator key gets properly deployed to its validator infrastructure so the validator is ready when validator activation occurs.

We strongly recommend Node Operators effectively monitor the Deposit Contract, in particular watching DepositEvent to never miss an activation.

Watching the exit requests

Node Operators are responsible for exiting their own validators
Node Operators can use the provided Exit Daemon

Useful events:

FundedValidatorKeys
RequestedValidatorExits

Exit Daemon

Description

The Validator Exit Daemon is an off-chain application designed to help Liquid Collective Node Operators exit validator keys with ease.

Node Operators are responsible for exiting validator keys from the Consensus Layer, allowing withdrawn funds to be used for satisfying conversions of LsETH for ETH.

Flow

LsETH holders convert LsETH for ETH through the protocol, creating a request for ETH.
The protocol regularly rebalance's ETH positions. When it needs ETH funds to fulfill redeem demands, it withdraws funds from the Consensus Layer and signals Node Operators by emitting an event requesting validator keys to be exited. The protocol is responsible for selecting the Node Operators that need to exit keys, depending on the current validator key allocation.
Upon receiving a validator exit request event, the Node Operator exits the requested number of validator keys, which results in broadcasting ValidatorExit messages to the Consensus Layer. This step is facilitated by the Validator Exit Daemon application.

Technical considerations & assumptions:

Validator exit is triggered by broadcasting a ValidatorExit message signed with the validator's private key on the Consensus Layer.
We cannot rely on the Dual-Key exit design to also allow triggering the validator key exit from the withdrawal_credentials. Even if this option is preferred, it is not expected to be available on day 1 of the withdrawals.
Validator keys may be slashed, resulting in the keys undergoing the Consensus Layer slashing process and eventually leading to the withdrawal of funds after incurring penalties (this takes at least 36 days).

Architecture

The Validator Exit Daemon is a long-lived application containerized in a Docker image designed to be run by Node Operators in their infrastructure.

It accesses data from both the Execution Layer and Consensus Layer connected to nodes in the Node Operator infrastructure.

It assumes that Node Operators have an existing system and process in place for proceeding with validator key exits.

The Daemon can interact with the existing exit system through one or both of the following methods:

HTTP hook: Called by the Daemon each time a validator request exit event is emitted, and a validator key should be exited. Node Operators can configure the callback to match any endpoint.
API polling: The Daemon exposes an API that Node Operators can poll to retrieve the key to exit.

The Validator Exit Daemon will provide the following information to the Node Operator:

Number of validator keys to exit
Recommended keys to exit

Diagram

Sequence diagram

Dependencies

A synced Execution Layer client with a JSON-RPC endpoint enabled. All implementations are supported (Geth, Erigon, Besu, etc.)
A synced Consensus Layer client with an 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:v0.37.0

For those running kubernetes and helm you can use this image:public.ecr.aws/alluvial/helm-charts/lceth:1.3.0

Usage

API

By default, the Exit daemon exposes an API route that Node Operators can use, either in conjunction with or without the HTTP hook.

This allows an operator to retrieve the recommended keys to exit at the current time.

Operator index could be retrieved with lceth operators list

The API meets the following requirements:

Webhook

The Exit daemon can run an HTTP hook system that sends validator exit request callbacks to the operator's existing systems when it receives a Validator Exit request event from the Consensus Layer.

The Exit daemon is stateless. If the webhook is enabled, it will send a call at each start if there is a pending exit request.

Operators can customize the webhook call by providing a template for the body, endpoint, and headers, and use the following macros to pass data related to the exit event:

total_requested_exits represents the total requested exits since the beginning of the contract. It’s a incremental-only counter emitted by the RequestedValidatorExits event.
validators_to_exit (as well as validators_to_exit_pubkeys & validators_to_exit_indexes) is an array of the validators to exit at a given time. To get them, the exit daemon fetches all the keys of an operator (via the

The webhook templating imports the . Which means additional functions are available to format the output.

For instance:

using environment variables via {{env "ENV_VAR_NAME"}}

Example of webhook template:

Usage output:

ITLCV1

Alluvial Finance Inc.

TLC Interface (v1)

TLC token interface

Methods

allowance

Returns the remaining number of tokens that spender will be allowed to spend on behalf of owner through {transferFrom}. This is zero by default. This value changes when {approve} or {transferFrom} are called.

Parameters

Name

Type

Description

Returns

Name

Type

Description

approve

Sets amount as the allowance of spender over the caller's tokens. Returns a boolean value indicating whether the operation succeeded. IMPORTANT: Beware that changing an allowance with this method brings the risk that someone may use both the old and the new allowance by unfortunate transaction ordering. One possible solution to mitigate this race condition is to first reduce the spender's allowance to 0 and set the desired value afterwards: https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729 Emits an {Approval} event.

Parameters

Name

Type

Description

Returns

Name

Type

Description

balanceOf

Returns the amount of tokens owned by account.

Parameters

Name

Type

Description

Returns

Name

Type

Description

computeVestingReleasableAmount

Computes the releasable amount of tokens for a vesting schedule.

Parameters

Name

Type

Description

Returns

Name

Type

Description

computeVestingVestedAmount

Computes the vested amount of tokens for a vesting schedule.

Parameters

Name

Type

Description

Returns

Name

Type

Description

createVestingSchedule

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

Name

Type

Description

Returns

Name

Type

Description

delegate

Delegates votes from the sender to delegatee.

Parameters

Name

Type

Description

delegateBySig

Delegates votes from signer to delegatee.

Parameters

Name

Type

Description

delegateVestingEscrow

Delegate vesting escrowed tokens

Parameters

Name

Type

Description

Returns

Name

Type

Description

delegates

Returns the delegate that account has chosen.

Parameters

Name

Type

Description

Returns

Name

Type

Description

getPastTotalSupply

Returns the total supply of votes available at a specific moment in the past. If the clock() is configured to use block numbers, this will return the value at the end of the corresponding block. NOTE: This value is the sum of all available votes, which is not necessarily the sum of all delegated votes. Votes that have not been delegated are still part of total supply, even though they would not participate in a vote.

Parameters

Name

Type

Description

Returns

Name

Type

Description

getPastVotes

Returns the amount of votes that account had at a specific moment in the past. If the clock() is configured to use block numbers, this will return the value at the end of the corresponding block.

Parameters

Name

Type

Description

Returns

Name

Type

Description

getVestingSchedule

Get vesting schedule

The vesting schedule structure represents a static configuration used to compute the desired vesting details of a beneficiary at all times. The values won't change even after tokens are released. The only dynamic field of the structure is end, and is updated whenever a vesting schedule is revoked

Parameters

Name

Type

Description

Returns

Name

Type

Description

getVestingScheduleCount

Get count of vesting schedules

Returns

Name

Type

Description

getVotes

Returns the current amount of votes that account has.

Parameters

Name

Type

Description

Returns

Name

Type

Description

initTLCV1

Initializes the TLC Token

Parameters

Name

Type

Description

isGlobalUnlockedScheduleIgnored

Get vesting global unlock schedule activation status for a vesting schedule

Parameters

Name

Type

Description

Returns

Name

Type

Description

migrateVestingSchedules

Migrates the vesting schedule state structures

releaseVestingSchedule

Release vesting scheduleWhen tokens are released from the escrow, the delegated address of the escrow will see its voting power decrease.The beneficiary has to make sure its delegation parameters are set properly to be able to use/delegate the voting power of its balance.

Parameters

Name

Type

Description

Returns

Name

Type

Description

revokeVestingSchedule

Revoke vesting schedule

Parameters

Name

Type

Description

Returns

Name

Type

Description

totalSupply

Returns the amount of tokens in existence.

Returns

Name

Type

Description

transfer

Moves amount tokens from the caller's account to to. Returns a boolean value indicating whether the operation succeeded. Emits a {Transfer} event.

Parameters

Name

Type

Description

Returns

Name

Type

Description

transferFrom

Moves amount tokens from from to to using the allowance mechanism. amount is then deducted from the caller's allowance. Returns a boolean value indicating whether the operation succeeded. Emits a {Transfer} event.

Parameters

Name

Type

Description

Returns

Name

Type

Description

vestingEscrow

Get the address of the escrow for a vesting schedule

Parameters

Name

Type

Description

Returns

Name

Type

Description

Events

Approval

Emitted when the allowance of a spender for an owner is set by a call to {approve}. value is the new allowance.

Parameters

Name

Type

Description

CreatedVestingSchedule

A new vesting schedule has been created

Parameters

Name

Type

Description

DelegateChanged

Emitted when an account changes their delegate.

Parameters

Name

Type

Description

DelegateVotesChanged

Emitted when a token transfer or delegate change results in changes to a delegate's number of votes.

Parameters

Name

Type

Description

DelegatedVestingEscrow

Vesting escrow has been delegated

Parameters

Name

Type

Description

ReleasedVestingSchedule

Vesting schedule has been released

Parameters

Name

Type

Description

RevokedVestingSchedule

Vesting schedule has been revoked

Parameters

Name

Type

Description

Transfer

Emitted when value tokens are moved from one account (from) to another (to). Note that value may be zero.

Parameters

Name

Type

Description

Errors

GlobalUnlockUnderlfow

Underflow in global unlock logic (should never happen)

InvalidRevokedVestingScheduleEnd

Attempt to revoke a vesting schedule with an invalid end parameter

InvalidVestingScheduleParameter

Invalid parameter for a vesting schedule

Parameters

Name

Type

Description

UnsufficientVestingScheduleCreatorBalance

Vesting schedule creator has unsufficient balance to create vesting schedule

VestingScheduleIsLocked

The vesting schedule is locked

VestingScheduleNotRevocable

The vesting schedule is not revocable

VestingScheduleNotRevocableInPast

Attempt to revoke a schedule in the past

ZeroReleasableAmount

No token to release

OperatorsRegistryV1

Alluvial Finance Inc.

Operators Registry (v1)

This contract handles the list of operators and their keys

Methods

acceptAdmin

Accept the transfer of ownership

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

addOperator

Adds an operator to the registry

Only callable by the administrator

Parameters

Name

Type

Description

Returns

Name

Type

Description

addValidators

Adds new keys for an operator

Only callable by the administrator or the operator address

Parameters

Name

Type

Description

demandValidatorExits

Increases the exit request demand

This method is only callable by the river contract, and to actually forward the information to the node operators via event emission, the unprotected requestValidatorExits method must be called

Parameters

Name

Type

Description

forceFundedValidatorKeysEventEmission

Utility to force the broadcasting of events. Will keep its progress in storage to prevent being DoSed by the number of keys

Parameters

Name

Type

Description

getAdmin

Retrieves the current admin address

Returns

Name

Type

Description

getCurrentValidatorExitsDemand

Get the current exit request demand waiting to be triggeredThis value is the amount of exit requests that are demanded and not yet performed by the contract

Returns

Name

Type

Description

getNextValidatorsToDepositFromActiveOperators

Get the next validators that would be funded

Parameters

Name

Type

Description

Returns

Name

Type

Description

getOperator

Get operator details

Parameters

Name

Type

Description

Returns

Name

Type

Description

getOperatorCount

Get operator count

Returns

Name

Type

Description

getOperatorStoppedValidatorCount

Retrieve the stopped validator count for an operator index

Parameters

Name

Type

Description

Returns

Name

Type

Description

getPendingAdmin

Retrieve the current pending admin address

Returns

Name

Type

Description

getRiver

Retrieve the River address

Returns

Name

Type

Description

getStoppedAndRequestedExitCounts

Retrieve the total stopped and requested exit count

Returns

Name

Type

Description

getStoppedValidatorCountPerOperator

Retrieve the raw stopped validators array from storage

Returns

Name

Type

Description

getTotalStoppedValidatorCount

Retrieve the total stopped validator count

Returns

Name

Type

Description

getTotalValidatorExitsRequested

Retrieve the total requested exit countThis value is the amount of exit requests that have been performed, emitting an event for operators to catch

Returns

Name

Type

Description

getValidator

Get the details of a validator

Parameters

Name

Type

Description

Returns

Name

Type

Description

initOperatorsRegistryV1

Initializes the operators registry

Parameters

Name

Type

Description

initOperatorsRegistryV1_1

Initializes the operators registry for V1_1

listActiveOperators

Retrieve the active operator set

Returns

Name

Type

Description

pickNextValidatorsToDeposit

Retrieve validator keys based on operator statuses

Parameters

Name

Type

Description

Returns

Name

Type

Description

proposeAdmin

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

Name

Type

Description

removeValidators

Remove validator keys

Only callable by the administrator or the operator address. The indexes must be provided sorted in decreasing order and duplicate-free, otherwise the method will revert. The operator limit will be set to the lowest deleted key index if the operator's limit wasn't equal to its total key countThe operator or the admin cannot remove funded keysWhen removing validators, the indexes of specific unfunded keys can be changed in order to properly remove the keys from the storage array. Beware of this specific behavior when chaining calls as the targeted public key indexes can point to a different key after a first call was made and performed some swaps

Parameters

Name

Type

Description

reportStoppedValidatorCounts

Allows river to override the stopped validators arrayThis actions happens during the Oracle report processing

Parameters

Name

Type

Description

requestValidatorExits

Public endpoint to consume the exit request demand and perform the actual exit requestsThe selection algorithm will pick validators based on their active validator countsThis value is computed by using the count of funded keys and taking into account the stopped validator counts and exit requests

Parameters

Name

Type

Description

setOperatorAddress

Changes the operator address of an operator

Only callable by the administrator or the previous operator address

Parameters

Name

Type

Description

setOperatorLimits

Changes the operator staking limit

Only callable by the administratorThe operator indexes must be in increasing order and contain no duplicateThe limit cannot exceed the total key count of the operatorThe _indexes and _newLimits must have the same length.Each limit value is applied to the operator index at the same index in the _indexes array.

Parameters

Name

Type

Description

setOperatorName

Changes the operator name

Only callable by the administrator or the operator

Parameters

Name

Type

Description

setOperatorStatus

Changes the operator status

Only callable by the administrator

Parameters

Name

Type

Description

version

Retrieves the version of the contract

Returns

Name

Type

Description

Events

AddedOperator

A new operator has been added to the registry

Parameters

Name

Type

Description

AddedValidatorKeys

The operator or the admin added new validator keys and signatures

The public keys and signatures are concatenatedA public key is 48 bytes longA signature is 96 bytes long[P1, S1, P2, S2, ..., PN, SN] where N is the bytes length divided by (96 + 48)

Parameters

Name

Type

Description

FundedValidatorKeys

A validator key got funded on the deposit contract. This event was introduced during a contract upgrade, in order to cover all possible public keys, this event will be replayed for past funded keys in order to have a complete coverage of all the funded public keys. In this particular scenario, the deferred value will be set to true, to indicate that we are not going to have the expected additional events and side effects in the same transaction (deposit to official DepositContract etc ...) because the event was synthetically crafted.

Parameters

Name

Type

Description

Initialize

Emitted when the contract is properly initialized

Parameters

Name

Type

Description

OperatorEditsAfterSnapshot

The operator edited its keys after the snapshot block

This means that we cannot assume that its key set is checked by the snapshotThis happens only if the limit was meant to be increased

Parameters

Name

Type

Description

OperatorLimitUnchanged

The call didn't alter the limit of the operator

Parameters

Name

Type

Description

RemovedValidatorKey

The operator or the admin removed a public key and its signature from the registry

Parameters

Name

Type

Description

RequestedValidatorExits

The requested exit count has been updated

Parameters

Name

Type

Description

SetAdmin

The admin address changed

Parameters

Name

Type

Description

SetCurrentValidatorExitsDemand

The exit request demand has been updated

Parameters

Name

Type

Description

SetOperatorAddress

The operator address has been changed

Parameters

Name

Type

Description

SetOperatorLimit

The operator limit has been changed

Parameters

Name

Type

Description

SetOperatorName

The operator display name has been changed

Parameters

Name

Type

Description

SetOperatorStatus

The operator status has been changed

Parameters

Name

Type

Description

SetOperatorStoppedValidatorCount

The operator stopped validator count has been changed

Parameters

Name

Type

Description

SetPendingAdmin

The pending admin address changed

Parameters

Name

Type

Description

SetRiver

The stored river address has been changed

Parameters

Name

Type

Description

SetTotalValidatorExitsRequested

The total requested exit has been updated

Parameters

Name

Type

Description

UpdatedRequestedValidatorExitsUponStopped

The requested exit count has been update to fill the gap with the reported stopped count

Parameters

Name

Type

Description

UpdatedStoppedValidators

The stopped validator array has been changedA validator is considered stopped if exiting, exited or slashedThis event is emitted when the oracle reports new stopped validators counts

Parameters

Name

Type

Description

Errors

FundedKeyEventMigrationComplete

Emitted when the event rebroadcasting is done and we attempt to broadcast new events

InactiveOperator

The calling operator is inactive

Parameters

Name

Type

Description

InvalidArrayLengths

The provided operator and limits array have different lengths

InvalidEmptyArray

The provided operator and limits array are empty

InvalidEmptyStoppedValidatorCountsArray

Thrown when an invalid empty stopped validator array is provided

InvalidEmptyString

The string is empty

InvalidFundedKeyDeletionAttempt

A funded key deletion has been attempted

InvalidIndexOutOfBounds

The index that is removed is out of bounds

InvalidInitialization

An error occurred during the initialization

Parameters

Name

Type

Description

InvalidKeyCount

The provided key count is 0

InvalidKeysLength

The provided concatenated keys do not have the expected length

InvalidStoppedValidatorCountsSum

Thrown when the sum of stopped validators is invalid

InvalidUnsortedIndexes

The index provided are not sorted properly (descending order)

InvalidZeroAddress

The address is zero

NoExitRequestsToPerform

Thrown when no exit requests can be performed

OperatorLimitTooHigh

The value for the operator limit is too high

Parameters

Name

Type

Description

OperatorLimitTooLow

The value for the limit is too low

Parameters

Name

Type

Description

OperatorNotFound

The operator was not found

Parameters

Name

Type

Description

SliceOutOfBounds

The slice is outside of the initial bytes bounds

SliceOverflow

The length overflows an uint

StoppedValidatorCountAboveFundedCount

The provided stopped validator count of an operator is above its funded validator count

Parameters

Name

Type

Description

StoppedValidatorCountArrayShrinking

The provided stopped validator count array is shrinking

StoppedValidatorCountsDecreased

Throw when an element in the stopped validator array is decreasing

StoppedValidatorCountsTooHigh

Thrown when the number of elements in the array is too high compared to operator count

Unauthorized

The operator is unauthorized for the caller

Parameters

Name

Type

Description

UnorderedOperatorList

The provided list of operators is not in increasing order

TLCV1

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

Description of the clock

Returns

Name

Type

Description

DOMAIN_SEPARATOR

See {IERC20Permit-DOMAIN_SEPARATOR}.

Returns

Name

Type

Description

allowance

See {IERC20-allowance}.

Parameters

Name

Type

Description

Returns

Name

Type

Description

approve

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

Name

Type

Description

Returns

Name

Type

Description

balanceOf

See {IERC20-balanceOf}.

Parameters

Name

Type

Description

Returns

Name

Type

Description

checkpoints

Get the pos-th checkpoint for account.

Parameters

Name

Type

Description

Returns

Name

Type

Description

clock

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

Returns

Name

Type

Description

computeVestingReleasableAmount

Computes the releasable amount of tokens for a vesting schedule.

Parameters

Name

Type

Description

Returns

Name

Type

Description

computeVestingVestedAmount

Computes the vested amount of tokens for a vesting schedule.

Parameters

Name

Type

Description

Returns

Name

Type

Description

createVestingSchedule

Parameters

Name

Type

Description

Returns

Name

Type

Description

decimals

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

Name

Type

Description

decreaseAllowance

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

Name

Type

Description

Returns

Name

Type

Description

delegate

Delegate votes from the sender to delegatee.

Parameters

Name

Type

Description

delegateBySig

Delegates votes from signer to delegatee

Parameters

Name

Type

Description

delegateVestingEscrow

Delegate vesting escrowed tokens

Parameters

Name

Type

Description

Returns

Name

Type

Description

delegates

Get the address account is currently delegating to.

Parameters

Name

Type

Description

Returns

Name

Type

Description

eip712Domain

See {EIP-5267}. Available since v4.9.

Returns

Name

Type

Description

getPastTotalSupply

Retrieve the totalSupply at the end of timepoint. Note, this value is the sum of all balances. It is NOT the sum of all the delegated votes! Requirements: - timepoint must be in the past

Parameters

Name

Type

Description

Returns

Name

Type

Description

getPastVotes

Retrieve the number of votes for account at the end of timepoint. Requirements: - timepoint must be in the past

Parameters

Name

Type

Description

Returns

Name

Type

Description

getVestingSchedule

Get vesting schedule

The vesting schedule structure represents a static configuration used to compute the desired vesting details of a beneficiary at all times. The values won't change even after tokens are released.The only dynamic field of the structure is end, and is updated whenever a vesting schedule is revoked

Parameters

Name

Type

Description

Returns

Name

Type

Description

getVestingScheduleCount

Get count of vesting schedules

Returns

Name

Type

Description

getVotes

Gets the current votes balance for account

Parameters

Name

Type

Description

Returns

Name

Type

Description

increaseAllowance

Atomically increases 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.

Parameters

Name

Type

Description

Returns

Name

Type

Description

initTLCV1

Initializes the TLC Token

Parameters

Name

Type

Description

isGlobalUnlockedScheduleIgnored

Get vesting global unlock schedule activation status for a vesting schedule

Parameters

Name

Type

Description

Returns

Name

Type

Description

migrateVestingSchedules

Migrates the vesting schedule state structures

name

Returns the name of the token.

Returns

Name

Type

Description

nonces

See {IERC20Permit-nonces}.

Parameters

Name

Type

Description

Returns

Name

Type

Description

numCheckpoints

Get number of checkpoints for account.

Parameters

Name

Type

Description

Returns

Name

Type

Description

permit

See {IERC20Permit-permit}.

Parameters

Name

Type

Description

releaseVestingSchedule

Parameters

Name

Type

Description

Returns

Name

Type

Description

revokeVestingSchedule

Revoke vesting schedule

Parameters

Name

Type

Description

Returns

Name

Type

Description

symbol

Returns the symbol of the token, usually a shorter version of the name.

Returns

Name

Type

Description

totalSupply

See {IERC20-totalSupply}.

Returns

Name

Type

Description

transfer

See {IERC20-transfer}. Requirements: - to cannot be the zero address. - the caller must have a balance of at least amount.

Parameters

Name

Type

Description

Returns

Name

Type

Description

transferFrom

See {IERC20-transferFrom}. Emits an {Approval} event indicating the updated allowance. This is not required by the EIP. See the note at the beginning of {ERC20}. NOTE: Does not update the allowance if the current allowance is the maximum uint256. Requirements: - from and to cannot be the zero address. - from must have a balance of at least amount. - the caller must have allowance for from's tokens of at least amount.

Parameters

Name

Type

Description

Returns

Name

Type

Description

vestingEscrow

Get the address of the escrow for a vesting schedule

Parameters

Name

Type

Description

Returns

Name

Type

Description

Events

Approval

Emitted when the allowance of a spender for an owner is set by a call to {approve}. value is the new allowance.

Parameters

Name

Type

Description

CreatedVestingSchedule

A new vesting schedule has been created

Parameters

Name

Type

Description

DelegateChanged

Emitted when an account changes their delegate.

Parameters

Name

Type

Description

DelegateVotesChanged

Emitted when a token transfer or delegate change results in changes to a delegate's number of votes.

Parameters

Name

Type

Description

DelegatedVestingEscrow

Vesting escrow has been delegated

Parameters

Name

Type

Description

EIP712DomainChanged

MAY be emitted to signal that the domain could have changed.

Initialized

Triggered when the contract has been initialized or reinitialized.

Parameters

Name

Type

Description

ReleasedVestingSchedule

Vesting schedule has been released

Parameters

Name

Type

Description

RevokedVestingSchedule

Vesting schedule has been revoked

Parameters

Name

Type

Description

Transfer

Emitted when value tokens are moved from one account (from) to another (to). Note that value may be zero.

Parameters

Name

Type

Description

Errors

GlobalUnlockUnderlfow

Underflow in global unlock logic (should never happen)

InvalidRevokedVestingScheduleEnd

Attempt to revoke a vesting schedule with an invalid end parameter

InvalidVestingScheduleParameter

Invalid parameter for a vesting schedule

Parameters

Name

Type

Description

InvalidZeroAddress

The address is zero

Unauthorized

The operator is unauthorized for the caller

Parameters

Name

Type

Description

UnsufficientVestingScheduleCreatorBalance

Vesting schedule creator has unsufficient balance to create vesting schedule

VestingScheduleIsLocked

The vesting schedule is locked

VestingScheduleNotFound

The VestingSchedule was not found

Parameters

Name

Type

Description

VestingScheduleNotRevocable

The vesting schedule is not revocable

VestingScheduleNotRevocableInPast

Attempt to revoke a schedule in the past

ZeroReleasableAmount

No token to release

IRiverV1

Alluvial Finance Inc.

River Interface (v1)

The main system interface

Methods

allowance

Retrieve the allowance value for a spender

Parameters

Name

Type

Description

Returns

Name

Type

Description

approve

Approves an account for future spendings

An approved account can use transferFrom to transfer funds on behalf of the token owner

Parameters

Name

Type

Description

Returns

Name

Type

Description

balanceOf

Retrieve the balance of an account

Parameters

Name

Type

Description

Returns

Name

Type

Description

balanceOfUnderlying

Retrieve the underlying asset balance of an account

Parameters

Name

Type

Description

Returns

Name

Type

Description

claimRedeemRequests

Claims several redeem requests

Parameters

Name

Type

Description

Returns

Name

Type

Description

decimals

Retrieve the decimal count

Returns

Name

Type

Description

decreaseAllowance

Decrease allowance to another account

Parameters

Name

Type

Description

Returns

Name

Type

Description

deposit

Explicit deposit method to mint on msg.sender

depositAndTransfer

Explicit deposit method to mint on msg.sender and transfer to _recipient

Parameters

Name

Type

Description

depositToConsensusLayerWithDepositRoot

Deposits current balance to the Consensus Layer by batches of 32 ETH

Parameters

Name

Type

Description

getAllowlist

Retrieve the allowlist address

Returns

Name

Type

Description

getBalanceToDeposit

Returns the amount of ETH not yet committed for deposit

Returns

Name

Type

Description

getBalanceToRedeem

Retrieve the current balance to redeem

Returns

Name

Type

Description

getCLSpec

Retrieve the current cl spec

Returns

Name

Type

Description

getCLValidatorCount

Get CL validator count (the amount of validator reported by the oracles)

Returns

Name

Type

Description

getCLValidatorTotalBalance

Get CL validator total balance

Returns

Name

Type

Description

getCollector

Retrieve the collector address

Returns

Name

Type

Description

getCommittedBalance

Returns the amount of ETH committed for deposit

Returns

Name

Type

Description

getCoverageFund

Retrieve the coverage fund

Returns

Name

Type

Description

getCurrentEpochId

Retrieve the current epoch id based on block timestamp

Returns

Name

Type

Description

getCurrentFrame

Retrieve the current frame details

Returns

Name

Type

Description

getDailyCommittableLimits

Retrieve the configured daily committable limits

Returns

Name

Type

Description

getDepositedValidatorCount

Get the deposited validator count (the count of deposits made by the contract)

Returns

Name

Type

Description

getELFeeRecipient

Retrieve the execution layer fee recipient

Returns

Name

Type

Description

getExpectedEpochId

Retrieve expected epoch id

Returns

Name

Type

Description

getFrameFirstEpochId

Retrieve the first epoch id of the frame of the provided epoch id

Parameters

Name

Type

Description

Returns

Name

Type

Description

getGlobalFee

Get the current global fee

Returns

Name

Type

Description

getKeeper

Get the keeper address

Returns

Name

Type

Description

getLastCompletedEpochId

Retrieve the last completed epoch id

Returns

Name

Type

Description

getLastConsensusLayerReport

Retrieve the last consensus layer report

Returns

Name

Type

Description

getMetadataURI

Retrieve the metadata uri string value

Returns

Name

Type

Description

getOperatorsRegistry

Retrieve the operators registry

Returns

Name

Type

Description

getOracle

Get oracle address

Returns

Name

Type

Description

getRedeemManager

Retrieve the redeem manager

Returns

Name

Type

Description

getReportBounds

Retrieve the report bounds

Returns

Name

Type

Description

getTime

Retrieve the block timestamp

Returns

Name

Type

Description

getWithdrawalCredentials

Retrieve the withdrawal credentials

Returns

Name

Type

Description

increaseAllowance

Increase allowance to another account

Parameters

Name

Type

Description

Returns

Name

Type

Description

initRiverV1

Initializes the River system

Parameters

Name

Type

Description

initRiverV1_1

Initialized version 1.1 of the River System

Parameters

Name

Type

Description

initRiverV1_2

Initializes version 1.2 of the River System

isValidEpoch

Verifies if the provided epoch is valid

Parameters

Name

Type

Description

Returns

Name

Type

Description

name

Retrieve the token name

Returns

Name

Type

Description

requestRedeem

Performs a redeem request on the redeem manager

Parameters

Name

Type

Description

Returns

Name

Type

Description

resolveRedeemRequests

Resolves the provided redeem requests by calling the redeem manager

Parameters

Name

Type

Description

Returns

Name

Type

Description

sendCLFunds

Input for consensus layer funds, containing both exit and skimming

sendCoverageFunds

Input for coverage funds

sendELFees

Input for execution layer fee earnings

sendRedeemManagerExceedingFunds

Input for the redeem manager funds

setAllowlist

Changes the allowlist address

Parameters

Name

Type

Description

setCLSpec

Parameters

Name

Type

Description

setCollector

Changes the collector address

Parameters

Name

Type

Description

setConsensusLayerData

Parameters

Name

Type

Description

setCoverageFund

Changes the coverage fund

Parameters

Name

Type

Description

setDailyCommittableLimits

Parameters

Name

Type

Description

setELFeeRecipient

Changes the execution layer fee recipient

Parameters

Name

Type

Description

setGlobalFee

Changes the global fee parameter

Parameters

Name

Type

Description

setMetadataURI

Sets the metadata uri string value

Parameters

Name

Type

Description

setOracle

Set the oracle address

Parameters

Name

Type

Description

setReportBounds

Parameters

Name

Type

Description

sharesFromUnderlyingBalance

Retrieve the shares count from an underlying asset amount

Parameters

Name

Type

Description

Returns

Name

Type

Description

symbol

Retrieve the token symbol

Returns

Name

Type

Description

totalSupply

Retrieve the total token supply

Returns

Name

Type

Description

totalUnderlyingSupply

Retrieve the total underlying asset supply

Returns

Name

Type

Description

transfer

Performs a transfer from the message sender to the provided account

Parameters

Name

Type

Description

Returns

Name

Type

Description

transferFrom

Performs a transfer between two recipients

Parameters

Name

Type

Description

Returns

Name

Type

Description

underlyingBalanceFromShares

Retrieve the underlying asset balance from an amount of shares

Parameters

Name

Type

Description

Returns

Name

Type

Description

Events

Approval

Emitted when the allowance of a spender for an owner is set by a call to {approve}. value is the new allowance.

Parameters

Name

Type

Description

ConsensusLayerDataUpdate

The consensus layer data provided by the oracle has been updated

Parameters

Name

Type

Description

ProcessedConsensusLayerReport

The provided report has been processed

Parameters

Name

Type

Description

PulledCLFunds

Emitted when funds are pulled from the CL recipient

Parameters

Name

Type

Description

PulledCoverageFunds

Funds have been pulled from the Coverage Fund

Parameters

Name

Type

Description

PulledELFees

Funds have been pulled from the Execution Layer Fee Recipient

Parameters

Name

Type

Description

PulledRedeemManagerExceedingEth

Emitted when funds are pulled from the redeem manager

Parameters

Name

Type

Description

ReportedRedeemManager

Emitted when the redeem manager received a withdraw event report

Parameters

Name

Type

Description

RewardsEarned

The system underlying supply increased. This is a snapshot of the balances for accounting purposes

Parameters

Name

Type

Description

SetAllowlist

The stored Allowlist has been changed

Parameters

Name

Type

Description

SetBalanceCommittedToDeposit

Emitted when the balance committed to deposit

Parameters

Name

Type

Description

SetBalanceToDeposit

Emitted when the balance to deposit is updated

Parameters

Name

Type

Description

SetBalanceToRedeem

Emitted when the balance to redeem is updated

Parameters

Name

Type

Description

SetBounds

The Report Bounds are changed

Parameters

Name

Type

Description

SetCollector

The stored Collector has been changed

Parameters

Name

Type

Description

SetCoverageFund

The stored Coverage Fund has been changed

Parameters

Name

Type

Description

SetDepositContractAddress

The stored deposit contract address changed

Parameters

Name

Type

Description

SetDepositedValidatorCount

Emitted when the deposited validator count is updated

Parameters

Name

Type

Description

SetELFeeRecipient

The stored Execution Layer Fee Recipient has been changed

Parameters

Name

Type

Description

SetGlobalFee

The stored Global Fee has been changed

Parameters

Name

Type

Description

SetMaxDailyCommittableAmounts

Emitted when the daily committable limits are changed

Parameters

Name

Type

Description

SetMetadataURI

The stored Metadata URI string has been changed

Parameters

Name

Type

Description

SetOperatorsRegistry

The stored Operators Registry has been changed

Parameters

Name

Type

Description

SetOracle

The stored oracle address changed

Parameters

Name

Type

Description

SetRedeemManager

Emitted when the redeem manager address is changed

Parameters

Name

Type

Description

SetSpec

The Consensus Layer Spec is changed

Parameters

Name

Type

Description

SetTotalSupply

Emitted when the total supply is changed

Parameters

Name

Type

Description

SetWithdrawalCredentials

The stored withdrawal credentials changed

Parameters

Name

Type

Description

Transfer

Emitted when value tokens are moved from one account (from) to another (to). Note that value may be zero.

Parameters

Name

Type

Description

UserDeposit

User deposited ETH in the system

Parameters

Name

Type

Description

Errors

AllowanceTooLow

Allowance too low to perform operation

Parameters

Name

Type

Description

BalanceTooLow

Balance too low to perform operation

Denied

The access was denied

Parameters

Name

Type

Description

EmptyDeposit

And empty deposit attempt was made

ErrorOnDeposit

An error occurred during the deposit

InconsistentPublicKeys

The length of the BLS Public key is invalid during deposit

InconsistentSignatures

The length of the BLS Signature is invalid during deposit

InvalidDecreasingValidatorsExitedBalance

The total exited balance decreased

Parameters

Name

Type

Description

InvalidDecreasingValidatorsSkimmedBalance

The total skimmed balance decreased

Parameters

Name

Type

Description

InvalidDepositRoot

Invalid deposit root

InvalidEpoch

Thrown when an invalid epoch was reported

Parameters

Name

Type

Description

InvalidPublicKeyCount

The received count of public keys to deposit is invalid

InvalidPulledClFundsAmount

Thrown when the amount received from the Withdraw contract doe not match the requested amount

Parameters

Name

Type

Description

InvalidSignatureCount

The received count of signatures to deposit is invalid

InvalidValidatorCountReport

The reported validator count is invalid

Parameters

Name

Type

Description

InvalidWithdrawalCredentials

The withdrawal credentials value is null

NoAvailableValidatorKeys

The internal key retrieval returned no keys

NotEnoughFunds

Not enough funds to deposit one validator

NullTransfer

Invalid empty transfer

OnlyKeeper

TotalValidatorBalanceDecreaseOutOfBound

The balance decrease is higher than the maximum allowed by the lower bound

Parameters

Name

Type

Description

TotalValidatorBalanceIncreaseOutOfBound

The balance increase is higher than the maximum allowed by the upper bound

Parameters

Name

Type

Description

UnauthorizedTransfer

Invalid transfer recipients

Parameters

Name

Type

Description

ZeroMintedShares

The computed amount of shares to mint is 0

Live

ETH Liquid Staking Documentation

hashtagETH liquid staking with Liquid Collective

Overview

Roles & Staking Infrastructure

hashtagKey roles in Liquid Collective

hashtagPlatforms

hashtagWallet and Custody Providers

hashtagService Providers

hashtagNode Operators

hashtagOracle Operators

hashtagLiquid Collective's Ethereum staking infrastructure

Architecture

hashtagSmart Contracts

hashtagRiver

Staking Amounts

hashtagSelf-custody

Slashing Coverage

hashtag

Permissioning

Protocol Metadata

Deployment Addresses

Tokenomics

LsETH (cToken)

hashtagLsETH User Agreement

hashtagcToken

hashtagConversion Rate

hashtagFormula

hashtagWhat can you do with LsETH?

hashtagWhat are the tax implications?

Node Operations

Validator Infrastructure

hashtagValidator Infrastructure

hashtagValidator Node Operations

Oracles

Oracle Infrastructure

hashtagMembers

hashtagQuorum Synchronization

hashtagEpochs

hashtagQuorum

hashtagReports

hashtagSanity Checks

hashtagOracle Data

Platforms

Platform Operations

hashtagPlatforms that enable LsETH minting and redemption

hashtagPlatforms that enable secondary interactions

hashtagEnterprise integration APIs

Technical Reference

Smart Contracts

Administrable

hashtagMethods

Initializable

hashtagEvents

ProtocolMetrics

hashtagMethods

hashtaggetRate

hashtagReturns

hashtaginitProtocolMetricsV1

hashtagParameters

hashtagEvents

hashtagInitialize

hashtagParameters

hashtagErrors

hashtagInvalidInitialization

hashtagParameters

hashtagInvalidZeroAddress

Components

UserDepositManagerV1

hashtagMethods

hashtagdeposit

hashtagdepositAndTransfer

hashtagParameters

hashtagEvents

hashtagUserDeposit

hashtagParameters

hashtagErrors

hashtagEmptyDeposit

hashtagInvalidCall

hashtagInvalidZeroAddress

ETH liquid staking with Liquid Collective

Key roles in Liquid Collective

Platforms

Wallet and Custody Providers

Service Providers

Node Operators

Oracle Operators

Liquid Collective's Ethereum staking infrastructure

Smart Contracts

River

Self-custody

LsETH User Agreement

cToken

Conversion Rate

Formula

What can you do with LsETH?

What are the tax implications?

Validator Infrastructure

Validator Node Operations

Members

Quorum Synchronization

Epochs

Quorum

Reports

Sanity Checks

Oracle Data

Platforms that enable LsETH minting and redemption

Platforms that enable secondary interactions

Enterprise integration APIs

Methods

Events

Methods

getRate

Returns

initProtocolMetricsV1

Parameters

Events

Initialize

Parameters

Errors

InvalidInitialization

Parameters

InvalidZeroAddress

Methods

deposit

depositAndTransfer

Parameters

Events

UserDeposit

Parameters

Errors

EmptyDeposit

InvalidCall

InvalidZeroAddress

Methods

acceptAdmin

getAdmin

Returns

getPendingAdmin

Returns

proposeAdmin

Parameters

Events

SetAdmin

Parameters

SetPendingAdmin

Parameters

Methods

deposit

depositAndTransfer

Parameters

Events

UserDeposit

Parameters

Errors

EmptyDeposit

Methods

getCredentials

Returns

getRiver