RiverV1

Kiln

River (v1)

This contract merges all the manager contracts and implements all the virtual methods stitching all components together.

1. Operators add BLS Public Keys of validators running in their infrastructure.

2. User deposits ETH to the system and gets LsTokens minted in exchange.

3. Upon deposit, the system verifies if the User is allowed to depositby querying the Allowlist.

4. When the system has enough funds to deposit validators, keys are pulled from the Operators Registry.

5. The deposit data is computed and the validators are funded via the OfficialDeposit contract.

6. Oracles report the total balance of the running validators and the total countof running validators.

7. The running validators propose blocks that reward the EL Fee Recipient. The funds are pulled back in the system.

Methods

DEPOSIT_SIZE

function DEPOSIT_SIZE() external view returns (uint256)

Size of a deposit in ETH

Returns

Name	Type	Description
_0	uint256	undefined

PUBLIC_KEY_LENGTH

function PUBLIC_KEY_LENGTH() external view returns (uint256)

Size of a BLS Public key in bytes

Returns

Name	Type	Description
_0	uint256	undefined

SIGNATURE_LENGTH

function SIGNATURE_LENGTH() external view returns (uint256)

Size of a BLS Signature in bytes

Returns

Name	Type	Description
_0	uint256	undefined

acceptAdmin

function acceptAdmin() external nonpayable

Accept the transfer of ownership

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

allowance

function allowance(address _owner, address _spender) external view returns (uint256)

Retrieve the allowance value for a spender

Parameters

Name	Type	Description
_owner	address	Address that issued the allowance
_spender	address	Address that received the allowance

Returns

Name	Type	Description
_0	uint256	The allowance in shares for a given spender

approve

function approve(address _spender, uint256 _value) external nonpayable returns (bool)

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
_spender	address	Address that is allowed to spend the tokens
_value	uint256	The allowed amount in shares, will override previous value

Returns

Name	Type	Description
_0	bool	True if success

balanceOf

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

Retrieve the balance of an account

Parameters

Name	Type	Description
_owner	address	Address to be checked

Returns

Name	Type	Description
_0	uint256	The balance of the account in shares

balanceOfUnderlying

function balanceOfUnderlying(address _owner) external view returns (uint256)

Retrieve the underlying asset balance of an account

Parameters

Name	Type	Description
_owner	address	Address to be checked

Returns

Name	Type	Description
_0	uint256	The underlying balance of the account

decimals

function decimals() external pure returns (uint8)

Retrieve the decimal count

Returns

Name	Type	Description
_0	uint8	The decimal count

decreaseAllowance

function decreaseAllowance(address _spender, uint256 _subtractableValue) external nonpayable returns (bool)

Decrease allowance to another account

Parameters

Name	Type	Description
_spender	address	Spender that receives the allowance
_subtractableValue	uint256	Amount of shares to subtract

Returns

Name	Type	Description
_0	bool	True if success

deposit

function deposit() external payable

Explicit deposit method to mint on msg.sender

depositAndTransfer

function depositAndTransfer(address _recipient) external payable

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

Parameters

Name	Type	Description
_recipient	address	Address receiving the minted LsETH

depositToConsensusLayer

function depositToConsensusLayer(uint256 _maxCount) external nonpayable

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

Parameters

Name	Type	Description
_maxCount	uint256	The maximum amount of validator keys to fund

getAdmin

function getAdmin() external view returns (address)

Retrieves the current admin address

Returns

Name	Type	Description
_0	address	The admin address

getAllowlist

function getAllowlist() external view returns (address)

Retrieve the allowlist address

Returns

Name	Type	Description
_0	address	The allowlist address

getBalanceToDeposit

function getBalanceToDeposit() external view returns (uint256)

Returns the amount of pending ETH

Returns

Name	Type	Description
_0	uint256	The amount of pending ETH

getCLValidatorCount

function getCLValidatorCount() external view returns (uint256)

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

Returns

Name	Type	Description
_0	uint256	The CL validator count

getCLValidatorTotalBalance

function getCLValidatorTotalBalance() external view returns (uint256)

Get CL validator total balance

Returns

Name	Type	Description
_0	uint256	The CL Validator total balance

getCollector

function getCollector() external view returns (address)

Retrieve the collector address

Returns

Name	Type	Description
_0	address	The collector address

getCoverageFund

function getCoverageFund() external view returns (address)

Retrieve the coverage fund

Returns

Name	Type	Description
_0	address	The coverage fund address

getDepositedValidatorCount

function getDepositedValidatorCount() external view returns (uint256)

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

Returns

Name	Type	Description
_0	uint256	The deposited validator count

getELFeeRecipient

function getELFeeRecipient() external view returns (address)

Retrieve the execution layer fee recipient

Returns

Name	Type	Description
_0	address	The execution layer fee recipient address

getGlobalFee

function getGlobalFee() external view returns (uint256)

Get the current global fee

Returns

Name	Type	Description
_0	uint256	The global fee

getMetadataURI

function getMetadataURI() external view returns (string)

Retrieve the metadata uri string value

Returns

Name	Type	Description
_0	string	The metadata uri string value

getOperatorsRegistry

function getOperatorsRegistry() external view returns (address)

Retrieve the operators registry

Returns

Name	Type	Description
_0	address	The operators registry address

getOracle

function getOracle() external view returns (address)

Get oracle address

Returns

Name	Type	Description
_0	address	The oracle address

getPendingAdmin

function getPendingAdmin() external view returns (address)

Retrieve the current pending admin address

Returns

Name	Type	Description
_0	address	The pending admin address

getWithdrawalCredentials

function getWithdrawalCredentials() external view returns (bytes32)

Retrieve the withdrawal credentials

Returns

Name	Type	Description
_0	bytes32	The withdrawal credentials

increaseAllowance

function increaseAllowance(address _spender, uint256 _additionalValue) external nonpayable returns (bool)

Increase allowance to another account

Parameters

Name	Type	Description
_spender	address	Spender that receives the allowance
_additionalValue	uint256	Amount of shares to add

Returns

Name	Type	Description
_0	bool	True if success

initRiverV1

function initRiverV1(address _depositContractAddress, address _elFeeRecipientAddress, bytes32 _withdrawalCredentials, address _oracleAddress, address _systemAdministratorAddress, address _allowlistAddress, address _operatorRegistryAddress, address _collectorAddress, uint256 _globalFee) external nonpayable

Initializes the River system

Parameters

Name	Type	Description
_depositContractAddress	address	Address to make Consensus Layer deposits
_elFeeRecipientAddress	address	Address that receives the execution layer fees
_withdrawalCredentials	bytes32	Credentials to use for every validator deposit
_oracleAddress	address	The address of the Oracle contract
_systemAdministratorAddress	address	Administrator address
_allowlistAddress	address	Address of the allowlist contract
_operatorRegistryAddress	address	Address of the operator registry
_collectorAddress	address	Address receiving the the global fee on revenue
_globalFee	uint256	Amount retained when the ETH balance increases and sent to the collector

name

function name() external pure returns (string)

Retrieve the token name

Returns

Name	Type	Description
_0	string	The token name

proposeAdmin

function proposeAdmin(address _newAdmin) external nonpayable

Proposes a new address as admin

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

Parameters

Name	Type	Description
_newAdmin	address	New admin address

sendCoverageFunds

function sendCoverageFunds() external payable

Input for coverage funds

sendELFees

function sendELFees() external payable

Input for execution layer fee earnings

setAllowlist

function setAllowlist(address _newAllowlist) external nonpayable

Changes the allowlist address

Parameters

Name	Type	Description
_newAllowlist	address	New address for the allowlist

setCollector

function setCollector(address _newCollector) external nonpayable

Changes the collector address

Parameters

Name	Type	Description
_newCollector	address	New address for the collector

setConsensusLayerData

function setConsensusLayerData(uint256 _validatorCount, uint256 _validatorTotalBalance, bytes32 _roundId, uint256 _maxIncrease) external nonpayable

Sets the validator count and validator total balance sum reported by the oracle

Can only be called by the oracle addressThe round id is a blackbox value that should only be used to identify unique reportsWhen a report is performed, River computes the amount of fees that can be pulledfrom the execution layer fee recipient. This amount is capped by the max allowedincrease provided during the report.If the total asset balance increases (from the reported total balance and the pulled funds)we then compute the share that must be taken for the collector on the positive delta.The execution layer fees are taken into account here because they are the product ofnode operator's work, just like consensus layer fees, and both should be handled in thesame manner, as a single revenue stream for the users and the collector.

Parameters

Name	Type	Description
_validatorCount	uint256	The number of active validators on the consensus layer
_validatorTotalBalance	uint256	The balance sum of the active validators on the consensus layer
_roundId	bytes32	An identifier for this update
_maxIncrease	uint256	The maximum allowed increase in the total balance

setCoverageFund

function setCoverageFund(address _newCoverageFund) external nonpayable

Changes the coverage fund

Parameters

Name	Type	Description
_newCoverageFund	address	New address for the fund

setELFeeRecipient

function setELFeeRecipient(address _newELFeeRecipient) external nonpayable

Changes the execution layer fee recipient

Parameters

Name	Type	Description
_newELFeeRecipient	address	New address for the recipient

setGlobalFee

function setGlobalFee(uint256 newFee) external nonpayable

Changes the global fee parameter

Parameters

Name	Type	Description
newFee	uint256	New fee value

setMetadataURI

function setMetadataURI(string _metadataURI) external nonpayable

Sets the metadata uri string value

Parameters

Name	Type	Description
_metadataURI	string	The new metadata uri string value

setOracle

function setOracle(address _oracleAddress) external nonpayable

Set the oracle address

Parameters

Name	Type	Description
_oracleAddress	address	Address of the oracle

sharesFromUnderlyingBalance

function sharesFromUnderlyingBalance(uint256 _underlyingAssetAmount) external view returns (uint256)

Retrieve the shares count from an underlying asset amount

Parameters

Name	Type	Description
_underlyingAssetAmount	uint256	Amount of underlying asset to convert

Returns

Name	Type	Description
_0	uint256	The amount of shares worth the underlying asset amopunt

symbol

function symbol() external pure returns (string)

Retrieve the token symbol

Returns

Name	Type	Description
_0	string	The token symbol

totalSupply

function totalSupply() external view returns (uint256)

Retrieve the total token supply

Returns

Name	Type	Description
_0	uint256	The total supply in shares

totalUnderlyingSupply

function totalUnderlyingSupply() external view returns (uint256)

Retrieve the total underlying asset supply

Returns

Name	Type	Description
_0	uint256	The total underlying asset supply

transfer

function transfer(address _to, uint256 _value) external nonpayable returns (bool)

Performs a transfer from the message sender to the provided account

Parameters

Name	Type	Description
_to	address	Address receiving the tokens
_value	uint256	Amount of shares to be sent

Returns

Name	Type	Description
_0	bool	True if success

transferFrom

function transferFrom(address _from, address _to, uint256 _value) external nonpayable returns (bool)

Performs a transfer between two recipients

Parameters

Name	Type	Description
_from	address	Address sending the tokens
_to	address	Address receiving the tokens
_value	uint256	Amount of shares to be sent

Returns

Name	Type	Description
_0	bool	True if success

underlyingBalanceFromShares

function underlyingBalanceFromShares(uint256 _shares) external view returns (uint256)

Retrieve the underlying asset balance from an amount of shares

Parameters

Name	Type	Description
_shares	uint256	Amount of shares to convert

Returns

Name	Type	Description
_0	uint256	The underlying asset balance represented by the shares

Events

Approval

event Approval(address indexed owner, address indexed spender, uint256 value)

Parameters

Name	Type	Description
owner indexed	address	undefined
spender indexed	address	undefined
value	uint256	undefined

ConsensusLayerDataUpdate

event ConsensusLayerDataUpdate(uint256 validatorCount, uint256 validatorTotalBalance, bytes32 roundId)

The consensus layer data provided by the oracle has been updated

Parameters

Name	Type	Description
validatorCount	uint256	undefined
validatorTotalBalance	uint256	undefined
roundId	bytes32	undefined

FundedValidatorKey

event FundedValidatorKey(bytes publicKey)

A validator key got funded on the deposit contract

Parameters

Name	Type	Description
publicKey	bytes	undefined

Initialize

event Initialize(uint256 version, bytes cdata)

Emitted when the contract is properly initialized

Parameters

Name	Type	Description
version	uint256	undefined
cdata	bytes	undefined

PulledCoverageFunds

event PulledCoverageFunds(uint256 amount)

Funds have been pulled from the Coverage Fund

Parameters

Name	Type	Description
amount	uint256	undefined

PulledELFees

event PulledELFees(uint256 amount)

Funds have been pulled from the Execution Layer Fee Recipient

Parameters

Name	Type	Description
amount	uint256	undefined

RewardsEarned

event RewardsEarned(address indexed _collector, uint256 _oldTotalUnderlyingBalance, uint256 _oldTotalSupply, uint256 _newTotalUnderlyingBalance, uint256 _newTotalSupply)

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

Parameters

Name	Type	Description
_collector indexed	address	undefined
_oldTotalUnderlyingBalance	uint256	undefined
_oldTotalSupply	uint256	undefined
_newTotalUnderlyingBalance	uint256	undefined
_newTotalSupply	uint256	undefined

SetAdmin

event SetAdmin(address indexed admin)

The admin address changed

Parameters

Name	Type	Description
admin indexed	address	undefined

SetAllowlist

event SetAllowlist(address indexed allowlist)

The stored Allowlist has been changed

Parameters

Name	Type	Description
allowlist indexed	address	undefined

SetCollector

event SetCollector(address indexed collector)

The stored Collector has been changed

Parameters

Name	Type	Description
collector indexed	address	undefined

SetCoverageFund

event SetCoverageFund(address indexed coverageFund)

The stored Coverage Fund has been changed

Parameters

Name	Type	Description
coverageFund indexed	address	undefined

SetDepositContractAddress

event SetDepositContractAddress(address indexed depositContract)

The stored deposit contract address changed

Parameters

Name	Type	Description
depositContract indexed	address	undefined

SetELFeeRecipient

event SetELFeeRecipient(address indexed elFeeRecipient)

The stored Execution Layer Fee Recipient has been changed

Parameters

Name	Type	Description
elFeeRecipient indexed	address	undefined

SetGlobalFee

event SetGlobalFee(uint256 fee)

The stored Global Fee has been changed

Parameters

Name	Type	Description
fee	uint256	undefined

SetMetadataURI

event SetMetadataURI(string metadataURI)

The stored Metadata URI string has been changed

Parameters

Name	Type	Description
metadataURI	string	undefined

SetOperatorsRegistry

event SetOperatorsRegistry(address indexed operatorRegistry)

The stored Operators Registry has been changed

Parameters

Name	Type	Description
operatorRegistry indexed	address	undefined

SetOracle

event SetOracle(address indexed oracleAddress)

The stored oracle address changed

Parameters

Name	Type	Description
oracleAddress indexed	address	undefined

SetPendingAdmin

event SetPendingAdmin(address indexed pendingAdmin)

The pending admin address changed

Parameters

Name	Type	Description
pendingAdmin indexed	address	undefined

SetWithdrawalCredentials

event SetWithdrawalCredentials(bytes32 withdrawalCredentials)

The stored withdrawal credentials changed

Parameters

Name	Type	Description
withdrawalCredentials	bytes32	undefined

Transfer

event Transfer(address indexed from, address indexed to, uint256 value)

Parameters

Name	Type	Description
from indexed	address	undefined
to indexed	address	undefined
value	uint256	undefined

UserDeposit

event UserDeposit(address indexed depositor, address indexed recipient, uint256 amount)

User deposited ETH in the system

Parameters

Name	Type	Description
depositor indexed	address	undefined
recipient indexed	address	undefined
amount	uint256	undefined

Errors

AllowanceTooLow

error AllowanceTooLow(address _from, address _operator, uint256 _allowance, uint256 _value)

Allowance too low to perform operation

Parameters

Name	Type	Description
_from	address	Account where funds are sent from
_operator	address	Account attempting the transfer
_allowance	uint256	Current allowance
_value	uint256	Requested transfer value in shares

BalanceTooLow

error BalanceTooLow()

Balance too low to perform operation

Denied

error Denied(address account)

The access was denied

Parameters

Name	Type	Description
account	address	The account that was denied

EmptyDeposit

error EmptyDeposit()

And empty deposit attempt was made

ErrorOnDeposit

error ErrorOnDeposit()

An error occured during the deposit

InconsistentPublicKeys

error InconsistentPublicKeys()

The length of the BLS Public key is invalid during deposit

InconsistentSignatures

error InconsistentSignatures()

The length of the BLS Signature is invalid during deposit

InvalidArgument

error InvalidArgument()

The argument was invalid

InvalidCall

error InvalidCall()

The call was invalid

InvalidEmptyString

error InvalidEmptyString()

The string is empty

InvalidFee

error InvalidFee()

The fee is invalid

InvalidInitialization

error InvalidInitialization(uint256 version, uint256 expectedVersion)

An error occured during the initialization

Parameters

Name	Type	Description
version	uint256	The version that was attempting to be initialized
expectedVersion	uint256	The version that was expected

InvalidPublicKeyCount

error InvalidPublicKeyCount()

The received count of public keys to deposit is invalid

InvalidSignatureCount

error InvalidSignatureCount()

The received count of signatures to deposit is invalid

InvalidValidatorCountReport

error InvalidValidatorCountReport(uint256 providedValidatorCount, uint256 depositedValidatorCount)

The reported validator count is invalid

Parameters

Name	Type	Description
providedValidatorCount	uint256	The received validator count value
depositedValidatorCount	uint256	The number of deposits performed by the system

InvalidWithdrawalCredentials

error InvalidWithdrawalCredentials()

The withdrawal credentials value is null

InvalidZeroAddress

error InvalidZeroAddress()

The address is zero

NoAvailableValidatorKeys

error NoAvailableValidatorKeys()

The internal key retrieval returned no keys

NotEnoughFunds

error NotEnoughFunds()

Not enough funds to deposit one validator

NullTransfer

error NullTransfer()

Invalid empty transfer

SliceOutOfBounds

error SliceOutOfBounds()

The slice is outside of the initial bytes bounds

SliceOverflow

error SliceOverflow()

The length overflows an uint

Unauthorized

error Unauthorized(address caller)

The operator is unauthorized for the caller

Parameters

Name	Type	Description
caller	address	Address performing the call

UnauthorizedTransfer

error UnauthorizedTransfer(address _from, address _to)

Invalid transfer recipients

Parameters

Name	Type	Description
_from	address	Account sending the funds in the invalid transfer
_to	address	Account receiving the funds in the invalid transfer

ZeroMintedShares

error ZeroMintedShares()

The computed amount of shares to mint is 0