Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Stake any amount of ETH to one or multiple node operators through a fully onchain solution.
When you stake natively on Ethereum there is no pooling mechanisms, you simply bound 32 ETH to a validation key and pilote the stake with the validation private key. This process is complex and very expensive for most users, 99.93% of Ethereum wallets having less than 32 ETH on their balance.
Kiln Onchain Pooled Staking enables Integrators and Operators to interconnect onchain very easily in order to propose custom ETH Pooled Staking to the Integrator end users.
Easy to use - users deposit any amount of ETH and start earning rewards immediately
Transparency first - all fund of flows, from deposit, to rewards, unstaking or commission dispatching is full visible and auditable onchain
Don't trust, verify - anyone can verify the provisioned validators to be staked, pooling economics and flow of funds onchain
Integrate in a few hours - only a few contract interactions are required for the staking and unstaking flows, making it very convenient to integrate on your platform
Create a custom Liquid Staking Token or not - integrators decide wether they want their users to receive a transferable ERC20 (cToken or aToken) to represent their staked pooled position
Use one or multiple operator - integrator can choose to expose their users to one or multiple underlying node operator, in different proportions and can change this at anytime
A 2 transaction setup for Integrators - bring custom pooled staking to your platform in only a few hours
Earn more with auto-compounding - by default Kiln Onchain Pooled Staking auto-compounds rewards to make sure the pool deposit as much validators and thus earn as much rewards as possible
This documentation and vSuite Smart Contracts are under the BUSL-1.1 licence, some smart contract public interfaces are under MIT licence.
The next step would be to add an oracle member, and start using the Oracle Daemon with the oracle member private key to craft and send reports to the vPool.
By default, the pool expects at least two members before it can start operating, but Kiln runs the global oracle member, so adding one regular member will do the trick.
Remember, you can remove the global oracle member from your vPool only if you have at least 5 members in your oracle quorum, and if you toggle the ejection flag.
The call is pretty simple, and should be performed by the vFactory admin
You can find the oracle daemon inside the operatord
repository. It contains all the daemons that an operator might need to run.
The oracle daemon is configured using a config.yaml
file. Let's start by creating a directory for the oracle daemon:
And then, create ~/oracle_datadir/config.yaml
, here's how it should look for one oracle member
name
is for logging purposes
private-key
is the private key of the member that you wish to run
pool
is the address of the vPool
you wish to report for
nexus
is the address of the Nexus
contract
purchase
is set to true
if the member will also participate in performing the purchaseValidators
call on the vPool
maxTxCostWei
is the maximum allowed cost of a tx in wei
It might take a bit of time to sync, but anything pulled from EL/CL that we'll need to reuse is stored inside the sqlite
database that will be created. This would greatly speedup possible restarts.
You should now ping Kiln to make sure that the global oracle member is running on their end. If that's the case, we should see oracle reports being posted
Validator owner can exit and withdraw its staked balance at anytime.
The unstaking process happens in two steps:
Validator owner needs to request the exit of the validator through a smart contract call. This will emit an onchain event to notify the operator to perform the validator exit. Once the validator exit is performed by the operator, the validator join the Ethereum protocol exit queue before being fully withdrawn to the Kiln Onchain Dedicated corresponding CL Recipient address. This process can take from a couple days to weeks depending on the protocol activit.
Once the full balance of the validator has been withdraw to the corresponding CL Recipient address, the validator owner can perform a usual rewards claim contract call to receive its funds. Note that no commission is taken on the staked principal (32 ETH) when withdrawing it.
To stake, it is required to deposit any multiple of 32 ETH to the Staking Contract. The deposited ETH will be used by the Staking Contract to fund available validation keys registered by the Operator(s). There is 2 ways to do this:
Transfer the multiple of 32 ETH to the Staking Contract address
Call the deposit()
function of the Staking Contract
Both will fund the validators by depositing them on the official Staking Contract and will set the owner of the validator in the Contract to the wallet which signed the deposit or transfer transaction.
Due to gas cost limitation, it is not recommended to deposit more than 40 validators (ie more than 1280 ETH) at once.
A validator(s) owner can claim the accrued EL and CL (Post-Shanghai) rewards on the Staking contract for its validator(s). When withdrawing available rewards, the commission dispatch is performed to the different partners defined in the contract (globalFee and operatorFee).
withdrawCLFee(bytes _publicKey)
performs commission dispatching on the available CL Recipient balance of the validator (accrued through EL fees earn when a block is proposed with or without MEV) and sends the rest to the validator owner. Pre-Shanghai this function reverts.
withdrawELFee(bytes _publicKey)
performs commission dispatching on the available EL Recipient balance of the validator (accrued through EL fees earn when a block is proposed with or without MEV) and sends the rest to the validator owner.
withdraw()
performs both of the above (reverts pre-Shanghai)
These 3 functions can be called by SYS_ADMIN or the validator owner, the net available rewards will always go to the registered validator owner.
This feature is disabled by default and must be enabled by SYS_ADMIN using setWithdrawerCustomizationEnabled(true)
The owner of a validator can transfer its ownership to an other address if this feature is enabled by SYS_ADMIN. This can be done by calling the following function from the validator owner wallet:
setWithdrawer(validatorPubkey, newOwner)
After this call, newOwner
will be the recipient of redeemed net rewards of the validator validatorPubkey
and the only wallet able to trigger the exit of the validator.
Stake any multiple of 32 ETH on your own dedicated validators through a fully onchain solution.
Using Kiln Onchain Dedicated Staking smart contracts, Integrators can propose a dedicated staking offer to their users by connecting them to an Operator validator infrastructure with a fully onchain ETH staking solution.
Easy to use - users can stake any multiple of 32 ETH on dedicated validators in one transaction
Transparency first - flow of funds, from deposit, to rewards, unstaking or commission dispatching is full visible and auditable onchain
Don't trust, verify - anyone can verify that provisioned validators deposit data are valid, making the staking process more transparent and secure
Integrate in a few hours - only a few contract interactions are required for the staking and unstaking flows, making it very convenient to integrate on your platform
Use vNFT or not - integrators decide wether they want their users to receive a transferable NFT representing validator ownership
Keep user fund segregation - Kiln Onchain Dedicated ensures that a user's staked balance remains completely separated from other user funds throughout the entire process, starting from the initial deposit to the final unstaking.
Kiln Onchain dedicated solution has been in production with multiple Integrators since October 2022 and has seen more than 380K ETH deposited.
You can explore publicly these product metrics with dune dashboard.
Staking definitions.
Word/Acronym | Definition |
---|---|
Send any multiple of 32 ETH and become owner of your dedicated Ethereum validators.
The deposit flow of Kiln Onchain dedicated products is straightforward: user sends any multiple of 32 ETH, either via a transfer or contract call transaction, to the Dedicated Staking smart contract and becomes owner of dedicated validators.
During this deposit transaction, the Kiln smart contracts deposit on validators previously registered by the Operator of the contracts the user staked on. User funds end up deposited and segregated on dedicated validators.
Anyone can verify that the validation key deposit data registered by the Operator in the Smart Contract are configured properly (correct signature and withdrawal credentials for example) before depositing, making the flow as trustless and transparent as possible.
If the vNFT mode is enabled in the Integration Contract, user receives in exchange for its deposits an NFT (ERC-721) token representing the ownership of its dedicated validator.
The holder of this vNFT is considered as owner of the validator it represents, and can withdraw its rewards or unstake it. This token can also be traded, lent or sold.
Offering non-custodial ETH staking is hard, as Ethereum lacks an onchain commission system, platforms adopt two approaches: they either hold staked ETH or rewards to earn commissions, or they charge deposit fees rather than relying on staking rewards as an incentive.
Existing ETH offerings can be opaque as the complete fund flow, including deposit handling, reward management, and commission distribution, isn't solely managed through transparent smart contract logic.
Introducing new use-cases on a validator infrastructure, like solo staking, pooled staking, or validator NFTs, is challenging due to the absence of established standards for operators in these areas.
Create a custom staking offering for your platform, customizing commissions from staking rewards, distributing them to partners, seamlessly integrating multiple operators, and even issuing Liquid Staking Tokens like NFTs or ERC20 tokens to represent users' staked positions.
Kiln Onchain is an audited suite of smart contracts that eliminates these barriers, enabling integrators to offer fully branded, customisable, non-custodial Ethereum staking to end-users, whilst being able to monetise the offering. With Kiln Onchain, integrators can now prioritise user retention and earning a rewards share from offering seamless Ethereum staking.
Kiln Onchain addresses three main actors:
Integrators, such as wallets or exchanges, that want to create a custom staking solutions for their users. This may involve solo staking with one operator or proposing their own Liquid Staking Token with 2 operators.
Operators are Ethereum validator providers who integrate their validator infrastructure via smart contracts, enabling them to offer staking services like pooling or dedicated staking, and accept deposits from multiple Integrators.
Stakers are ETH holders seeking to engage in Ethereum protocol staking, and they can choose between pooled solutions or dedicated staking. Throughout the entire staking process, they retain custody of their assets, ensuring a fully transparent and auditable fund flow.
Kiln Onchain offers a suite of smart contracts designed to allow integrators to accommodate a wide range of use cases within native and pooled staking. Currently, there are four distinct options available:
Dedicated Validators: Native ETH protocol staking in batches of 32 ETH, providing a dedicated and secure staking solution.
Validator NFT: Same as ‘Dedicated Validators’, but with the ability to generate an NFT that represents ownership and withdrawal credentials of the validator.
Kiln Staking Pool: Enables integrators to offer services that allow staking any amount of ETH, without the issuance of a transferrable receipt token.
Kiln Liquid Staking Pool: Same as Kiln Staking Pooling but with the ability to issue a custom transferrable receipt token that represents the withdrawal credentials and the ownership of the users stake.
There are multiple ways Integrators can propose staking to their users (Stakers) through the Onchain platform (pooled, dedicated, ...), but the underlying principles remain the same across all the components of this product:
Transparency: deposits, commissions dispatching or exits, everything happens onchain and is easy to track via Event emissions and simple view functions everyone can call.
Security: staking through this audited solution is designed to be non-custodial (* some parts will be upgradable for a certain timeframe), and a lot of onchain and offchain safety guards are in place to protect users funds and rewards.
Flexibility: integrators have the choice between multiple staking integration types and can create their custom offering with or without liquidity tokens, or with one or multiple operators.
Kiln Onchain is under the BUSL-1.1 licence, some smart contract public interfaces are under MIT licence.
When a user stakes, their position proportionally increases in value as staking rewards are generated by the operator pool validators.
Users deploy ETH through the integrator's smart contract, which then forwards the ETH to one or multiple operator pools, depending on the configuration. This approach offers flexibility in structuring staking offerings, such as:
A single node operator with a 15% end-user fee.
Three operators with a 10/40/50% allocation and a total 17% end-user fee.
During the staking transaction, the user receives a receipt token representing their staked position within the integration contract. The integration contract, in turn, holds a proportional stake in the Node Operator Pool, based on the amount of ETH deployed through it.
The user's receipt tokens can be either soulbound or transferable (e.g., cToken or aToken), depending on the integrator's choice during contract setup. The value of staked positions is determined by the underlying value of the operator pool, with an internal exchange rate that updates daily to reflect validator rewards. This exchange rate is purely technical and used exclusively between the smart contracts.
Staking fees are automatically calculated by the smart contracts based on the rewards generated, ensuring a seamless experience for the end user, who only deals with net values.
User can request to exit their staked position anytime.
It’s important to note that all staked positions are 100% collateralized, with ETH primarily held in active validators. Any remaining ETH may be in the operator pool, awaiting deposit into new validators.
Exiting a validator to access the underlying 32 ETH is not instantaneous; it requires the validator to go through the protocol's exit process and enter an exit queue. Consequently, a user exiting their staked position involves a two-step process:
Requesting exit: Users first signal their intent to exit by interacting with the integration contract, which locks their receipt tokens and places them in the exit queue of the operator pool contract. Each pool has its own exit queue, and an integration contract can be linked to multiple operator pools.
Receiving an exit ticket: A ticket, representing the user's position in the exit queue, is minted as an NFT. This ticket reflects the user's place in the queue until their ETH are available to withdraw.
Under normal conditions, with the pool generating rewards and receiving new deposits, it generally takes about 1-4 days for exited ETH to become available for withdrawal. However, in cases where exit demand significantly exceeds the available ETH, the process may be delayed. This delay is influenced by the Ethereum validator exit and withdrawal queue, which typically takes several days but can extend significantly longer in extreme cases.
When the pooling contract receives ETH to fulfill exit requests, it creates a 'cask' that corresponds to the received ETH and the current exit queue demand.
The exit queue functions as a system where users receive a ticket to retrieve their ETH. This ETH is periodically allocated to the queue in the form of casks. The queue operates on a first-come, first-served basis, without discrimination or favoritism towards any user or scenario.
When casks arrive, users must still claim their ETH. This is due to Solidity's limitations on the number of actions that can be performed in a single transaction. Consequently, a cask may fulfill one or multiple tickets at once. The smart contract cannot iterate through all tickets in a single transaction due to the potentially high and variable number of tickets.
Tickets can have several statuses:
unfulfillable
: the ticket is waiting for a cask to arrive and fulfill its exit request.
partially fulfillable
: the ticket has one or several casks partially fulfilling its exit request, this means that the ticket can be claimed, but this action will result in getting an updated ticket with the remaining amount yet to be claimed.
fulfillable
: the ticket has one or several casks completely fulfilling its exit request. Claiming this ticket will retrieve the funds and burn the ticket.
In the example above, we can see that:
Tickets #0
and #1
are currently fulfillable
by cask #0
.
Ticket #2
is currently partially fulfillable
by cask #1
Ticket #3
is unfulfillable
.
Keep in mind that both of these queues can grow independently, and the goal of the pooling contract is to provide casks to make the cask queue grow and reach the same height as the ticket queue, making all ticket fulfillable
Rewards are received by a recipient address controlled by the Smart Contract and can be claimed by the validator owner.
For every validator deposited validators in the Onchain Dedicated smart contracts, there is a deterministically generated Ethereum address, controlled by the contract, set as withdrawal credentials of the validator.
This recipient address receives all the Consensus Layer rewards of the validator it is associated to. It also receives the unstaked amount upon exiting the validator.
Only the registered owner of the validator can claim this recipient address' balance.
Upon claiming their rewards, validator owners trigger commission dispatching, a process which sends the net rewards to the validator owner address and the remaining value to the different partners involved in the staking offering.
Staking
The act of bonding ETH tokens to a validator through a deposit process. In return, the validator earns rewards derived from protocol inflation and transaction fees, distributed to the validator withdrawal credentials and fee recipients.
GRR
Gross Rewards Rate - represents the annualized proportion of rewards earned in relation to the total staked amount, expressed as a percentage and exclusive of fees.
NRR
Net Rewards Rate - represents the annualized proportion of rewards earned in relation to the total staked amount, expressed as a percentage and inclusive of fees.
Dedicated / Solo Staking
When stakers deposit multiples of 32 ETH in return for launching their own dedicated validator(s). Rewards generated by the validator are exclusively for the staker and not shared with others.
Pooled Staking
Stakers who want to stake any amount of ETH join a staking pool by contributing their ETH to a common pool. This pool aggregates the ETH from multiple participants which in turn creates validators that are shared by the pool.
Integrator
A platform, whether custodial or not, that offers a staking service to its users.
Operator
An infrastructure provider, such as Kiln or Coinbase Cloud, running Ethereum validators.
LST / Liquid Staking Token
A Liquidity token (ERC20, ERC115 or ERC721) used to wrap a staked position, enabling easy transferability and composability on other smart contract platforms.
Integrating Kiln Onchain gives integrators total control over the staking experience. This includes designing the user experience, integration with native workflows, end-user fees, and the selection of node operators.
This comprehensive guide equips you with all the essentials to initiate the integration process.
The Operator Pool requires offchain information to update pooling metrics like Operator Pool value and exchange rate, to take into account rewards generated by the pool validators.
This data is called an oracle report and is submitted by whitelisted Oracles to the Operator Pool smart contract, once every 24 hours. If all the Oracle quorum agrees on the same report, this one is processed by the Operator pool.
This means that user position values, and exit requests are processed on a 24 hours basis if oracles generate valid reports.
An oracle report consists of data like total ETH staked, total ETH currently in the protocol Exit Queue, total validators staked, total validators exited and strategy inputs to tell the pool to either accelerate user exits time or increase new validator deposits.
Using this data, Operator pool will perform multiple state transitions to:
deposit new validators
answer the exit demand in the exit queue
compute relevant staking fees
update the Operator pool exchange rate to take into account new rewards
exit validators if needed to match the user exit demand in the pool exit queue
You can find the report data and all Operator Pool metrics on our dune dashboard.
This page provides an overview of the various contract interactions when staking.
The examples below when calling smart contract functions (e.g. stake()) are done using cast,
a cli tool, only as an illustration of how the transactions or view calls should be performed.
All of the contract calls below are for: Liquid20C, Liquid20A & Native20 contracts
Integrating Kiln into native workflow will require a mix of smart contract calls and TheGraph queries:
Smart contract
Our smart contract ABI's can be found here and the contract address will be provided by Kiln once it is deployed.
The Graph
Use the credentials provided by Kiln if using the public instance, or your own credentials if you are hosting your own instance.
Action | How to... | Description |
---|---|---|
Get the historical reward rate of the pool (last week, month, 3 months, 6 months, All Time).
Stake any amount of ETH into the pool.
Get a list of all deposits / stakes made from a wallet
Current value of stake(s)
Get the current underlying value of a wallet's staked position. Includes original stake + accrued rewards.
Get the historical reward rate of the wallet's staked position.
Unstake
Initiate an exit (or unstake) of a wallet's full or partial staked position.
Unstake status
Get the current status of a wallet's exit request.
Withdraw unstaked ETH
Claim unstaked ETH once the exit request has been fulfilled.
Learn more about your integration contract along with the choice of receipt tokens available to you.
The integration contract will be deployed by Kiln, but then owned and operated by the integrator. This provides integrators with complete control over the user experience and the staking product being distributed to their end users.
Integrators can do the following:
Users receive a receipt token representing their staked position. Integrators must decide on the token type upfront (soulbound or liquid), as it cannot be set or changed later. Kiln deploys the correct integration contract based on this initial decision.
Integrators can customise the below token attributes. Both attributes will be displayed on Etherscan and ERC20/ERC1155 compatible interfaces:
token symbol: e.g. cbETH, cdcETH, psETH
token name: e.g. Pooled Staked ETH, Coinbase Wallet ETH
Integrators need to choose the token type they wish to include in the staking product being offered to their end users.
Below is a comparison and summary of token types, highlighting differences in integration approaches, capabilities, and end-user experiences.
NOTE: Commonly, start with Native20 (non-transferrable tokens). Consider an optional upgrade to Liquid20 later; connect with us for details on the upgrade path and associated considerations.
contract expose the exact same view methods as Liquid20C
without the transfer
and approve
methods. It looks like a token, but cannot behave like one.
Liquid20A
an ERC20
rebase token.
the quantity of tokens held in the users wallet will increase each time rewards are distributed. Rebase tokens maintain a fixed exchange rate but the quantity of tokens issued increases to reflect earned rewards.
Liquid20C
standard ERC20
token
The quantity of tokens held in the users wallet do not change, however their value increases each time rewards are distributed.
Feature | Native20 | Liquid20A | Liquid20C | Native1155 | Liquid1155 |
---|---|---|---|---|---|
Parameter | Description | |
---|---|---|
Parameter | Description | |
---|---|---|
Stake any amount
✅
✅
✅
✅
✅
Commission taken onchain
✅
✅
✅
✅
✅
Multi commission recipients
✅
✅
✅
✅
✅
Users chooses pool
❌
❌
❌
✅
✅
Integrator chooses pool (sets % distribution across pools)
✅
✅
✅
❌
❌
Transfers
❌
✅
✅
❌
✅
NOTES
aToken
cToken
ERC1555 compliant
admin
address
Admin wallet address
pools
address[]
List of pool addresses
poolFees
uint256[]
List of fee for each pool in basis points
poolPercentages
uint256[]
Share of new stake to go to each pool, in basis points, must add up to 10 000
commissionRecipients
address[]
List of address of commission beneficiaries
commissionDistribution
uint256[]
Share of each beneficiary, in basis points, must add up to 10 000
name
string
ERC-20 style display name
symbol
string
ERC-20 style display symbol
admin
address
Admin wallet address
pools
address[]
List of pool addresses
poolFees
uint256[]
List of fee for each pool in basis points
commissionRecipients
address[]
List of address of commission beneficiaries
commissionDistribution
uint256[]
Share of each beneficiary, in basis points, must add up to 10 000
baseUri
string
Uri from which to pull the metadata
name
string
ERC-20 style display name
symbol
string
ERC-20 style display symbol
The Operator can generate new validation keys and upload their deposit data to the Staking Contract to make them available to fund. Note that they need to be approved by SYS_ADMIN before being able to be funded.
The Staking Contract generates deterministically CL / EL Recipient addresses from the validator public key. To know the withdrawal_credentials of the validators to generate (ie their CL Recipient), the recommended setup is:
Generate a new validation key
call the getCLFeeRecipient(bytes calldata _publicKey)
view function with the validator public key as parameter
Re-create the signature of the validator deposit data with the address outputed during step 2 as withdrawal_credentials
Once the keys are generated with the proper withdrawal_credentials, they can be registered on the Deposit Contract with:
OPERATOR calls addValidators(uint256 _operatorIndex, uint256 _keyCount, bytes calldata _publicKeys, bytes calldata _signatures)
to upload multiple public keys and their signatures
SYS_ADMIN can approve the keys uploaded by the OPERATOR with the following call:
setOperatorLimit(uint256 _operatorIndex, uint256 _limit)
to set the new number of approved keys for the operator _operatorIndex
It is recommended that the SYS_ADMIN verifies the validation keys before approving them (no duplicates, valid signatures etc). To do so Kiln provides a verification utility available here.
At any point in time, a validator owner (ie staker) can notify onchain the operator that it wants to exit a validator.
When doing the requestValidatorsExit
function call, the validator owner emits one event per validator exit request.
This event is as follow:
event ExitRequest(address caller, bytes pubkey)
where caller
is the validator owner address and pubkey
the validator public key to exit. This event is emitted only if the caller is the owner of the validator registered in the Smart Contract
It is expected that Operators watch for these events and trigger accordingly the exit of the requested validators within 48 hours.
Before diving straight into integrating, think about the user experience and all the key workflows you should consider as part of your integration. Here is a non-exhaustive list to help plan your user experience.
Feature in 'Earn' dashboard or integrate into existing workflows.
Emphasize ETH staking as a new product for heightened awareness.
Clearly display the reward rate for informed user decision-making. It is not static.
Set a practical minimum (e.g. 0.1 or 0.05 ETH) to avoid the staking tx costing more than the stake itself.
Alert users if the cost of the transaction is high relative to the amount being staked
Clarify if users must read and accept your Terms and Conditions.
Consider displaying estimated rewards based on the current reward rate, as some integrators do.
Provide users with an estimate of when their stake begins earning rewards.
Include a link to the 'staking request' transaction on Etherscan for transparency.
Display the user's staked ETH amount and current value
Consider showing historical reward data e.g. yesterday, last week, last month
Simplify 'stake more' or 'unstake' options for user convenience.
Enable users to request full or partial unstake.
Highlight that unstaking may take several days; the ETH is not immediately available.
For each exit request, show users an estimate
If unstaking too early, caution about potential network fee implications.
Include a link to the 'unstaking request' transaction on Etherscan for transparency.
Display 'unstake request' status and estimated time.
Alert the user to the fact that they have ETH to be claimed.
Include a link to the 'claim ETH' transaction on Etherscan for transparency.
Think about how you handle the integration contract being paused?
Stakers will not be able to stake (transactions will revert), so it's better to think about how to gracefully handle these situations before they happen.
This page provides a high-level understanding and overview of the architecture of the smart contracts as it relates to pooled staking.
Before getting started, here are a few terms we commonly use in the architecture overview.
integrator: a platform (e.g., wallet, web platform) offering staking services to their users by integrating with the Onchain platform.
operator: a node operator or validator infrastructure provider (e.g., Kiln or Coinbase Cloud) that owns and operates Ethereum validators for staking services on the Onchain platform.
operator pool: also known as a 'vPool', it is a set of smart contracts serving as the 'pooled staking engine,' with each one owned and operated by a node operator. One vPool can serve multiple integrators.
integration contract: A smart contract owned and operated by the integrator, serving as the primary integration point to the platform (end-user fees, commissions, node operator preferences and splits, and more!)
A smart contract owned and operated by the integrator, serving as the primary integration point for their users to the platform. These contracts manage end-user fees, commissions, node operator preference and split, and can be paused to prevent deposits at the discretion of the integrator.
Integrator contracts can connect to multiple Operator Pools to enable validator set diversification. They can be configured to allocate the desired balance across each operator, allowing for configurations such as 50/50, 60/40, 80/20, etc., tailored to specific requirements.
Under the hood, when a user deploys their ETH, the integration contract forwards the ETH to the operator pool. Users are abstracted from the underlying technical complexity of the platform, receiving a ERC-20 token in their wallet when they stake ETH. This token, soulbound or transferable based on the integrator's preference, represents their stake ownership and serves as the withdrawal credentials.
Integrators have full control over the can customise the token and define the token name and symbol. For example, myETH (My Company ETH).
NOTE: the Operator Pool has no concept of tokens. The integrator contracts are where tokens are issued and managed.
Think of Operator Pools as pooled staking engines, each owned by a node operator but entirely managed by smart contract logic. These sets of smart contracts handle all fundamental operations and lifecycle tasks of the pool, including deposits, validator activation and deactivation, reward distribution, exits, and management of staking fees.
Every Operator Pool can allow one or more integration contracts to connect and deposit ETH, allowing simple validator set diversification.
Rewards are generated by all of the validators supporting the pool, and are recycled back into the pool.
The value of the pool is recalculated daily via the receipt of oracle reports and the value of the operator pool will increase in value over time as rewards flow into the system.
This means that users will typically see the value of their staked position increase on daily basis.
An oracle report consists of data like total ETH staked, total ETH currently in the protocol Exit Queue, total validators staked, total validators exited and strategy inputs to tell the pool to either accelerate user exits time or increase new validator deposits.
Using this data, Operator pool will perform multiple state transitions to:
deposit new validators
answer the exit demand in the exit queue
compute operator commission
update the Operator pool shares exchange rate with ETH to take into account new rewards
exit validators if needed to match the user exit demand in the pool exit queue
Users can request to exit any amount of ETH up to the total value of their staked position. That is, they can request a full or partial exit.
Exiting, or withdrawing ETH, from the pool is a three staged process:
Request exit (requires user tx)
Wait for the request to be fulfilled
Withdraw the ETH (requires user tx)
Issue a request to withdraw an amount of ETH from the pool. After the transaction is confirmed and executed, an 'exit queue ticket' is issued, which is a soulbound NFT token representing the withdrawal request.
Exit requests are processed on a daily basis via the receipt of Oracle reports.
Fulfilling exit requests involves two scenarios::
ETH from deposits not yet staked and generated rewards.
The next oracle report on the pool (daily on mainnet) will process the exit.
ETH from validator exits
Where exit demand significantly surpasses available ETH, validator exits become necessary.
In this case, the validator must complete the full exit and withdrawal process, and then await the subsequent oracle report. This process generally takes between 2-10 days but may extend further, depending on the dynamics of the Ethereum exit queue.
Under normal conditions, with the pool earning rewards and incoming liquidity from deposits, it will take approximately 1-4 days for the user's exited ETH to become available for withdrawal.
Once fulfilled, the exited ETH is available to be withdrawn by the user.
When the ETH is available, the user will need to perform a 'claim transaction' during which the NFT will be burned in exchange for the ETH.
To gain access to TheGraph, contact Kiln and you will receive credentials to Kiln's TheGraph instance. Feel free to also host the subgraph on your end, allowing you to run the queries locally. During this guide, we will often use TheGraph queries to verify that specific actions had the expected outcome.
The easiest way to interact with TheGraph is by visiting the web query builder.
To test it, you can try a simple query to retrieve the address of the vTreasury that was deployed alongside your vFactory:
And if everything goes well, you should have a response looking like this (you should have an empty array of pools as no vPool was deployed yet)
You're now ready to follow the guide and run the queries when needed !
This page describes the roles needed to operate the integration contracts
The integration contract requires two essential admin roles, established during deployment but modifiable later.
These roles, assigned to unique addresses, are strongly recommended to be behind a multi-sig or MPC wallet for enhanced security and flexibility.
Role name | Setup | Actions |
---|---|---|
Role name | Setup | Actions |
---|---|---|
Role | Description |
---|---|
Kiln recommends that the PROXY_ADMIN is setup as a multi-sig between multiple parties inside the Integrator entity or including trusted third parties.
Contract | Action | Description | Regularity |
---|---|---|---|
Kiln recommends that the SYS_ADMIN is setup as a multi-sig between multiple parties inside the Integrator entity or including trusted third parties.
Contract | Action | Description | Regularity |
---|---|---|---|
Kiln recommends that the OPERATOR is setup as a hot wallet for use in scripts and automation.
It's rights are limited to changing the validators list, changes must then be approved by the admin.
The address can be changed by OPERATOR_FEE_RECIPIENT
Kiln recommends that the OPERATOR_FEE_RECIPIENT is setup as a multi-sig between multiple parties inside the Operator entity, this is where the operator fee will flow to.
The is a three-stage process:
user requests an exit or unstake (user tx)
exit request is processed and ETH is sourced to pay for the exit
user claims exited ETH (user tx)
When user request an exit, they burn their shares (receipt tokens in their wallet) in exchange for one or exit queue tickets.
These tickets have a status based on wether or not they can be claimed (user is able to claim their ETH), which depends on the liquidity provided to the exit queues by the vPools.
You can find more details about tickets and casks .
Used to request an exit (unstake) of any amount of ETH, up to the maximum user balance.
When initiating an exit, you must specify the quantity of integration tokens to exit. Subsequently, the integration contract will generate one or several tickets in the associated vPool exit queues.
This can only be executed by calling a smart contract method:
Used to retrieve all exit queue tickets for a user, providing the status of each ticket. This information enables you to inform the user about the availability of their exited ETH for claiming. Additionally, you have the option to permit users to claim a portion of their exit request if it is partially fulfilled, with the ability to claim the remainder once it becomes available.
Using The Graph
Query
Example results
Here you will retrieve all the different exit tickets of an account.
ticketId
is the id of the ticket, and also the id of the NFT representing this ticket
size
is the size of the ticket in vPool Shares (not ETH !)
maxExitable
is the maximum amount of eth that can be retrieved by the ticket. Shares locked inside tickets are not earning rewards anymore.
fulfillableAmount
is the amount of vPool shares that are currently fulfillable
fulfillableBy
is a list of casks that fulfill a ticket
exitQueue.address
is the address of the exit queue contract where the ticket is held
To retrieve the status of the ticket, it's pretty simple:
unfulfillable
when fulfillableAmount
is 0
partially fulfillable
when fulfillableAmount
< size
fulfillable
when fulfillableAmount
= size
Used to claim the ETH of a user who has requested to exit the pool.
You can use TheGraph query above to retrieve all the required information. In the case where we would want to claim all the tickets from the example query above (assuming we would have a new cask with id 1
that fulfills all the tickets), the transaction would look like
You must pass only one cask ID per ticket, if the ticket is matched by more than one cask, pass the lowest cask id and the code will automatically claim on all the casks matching the ticket
The last step is deploying an integration contract and connecting it to your vPool
.
The deployment of integration contracts is covered on .
You should new be able to stake on your integration contract and purchase validator on your vPool
once 32 ETH is reached
To facilitate your usage of the integration contracts your can find the ABIs
of the integration contracts on .
Once your vPool
has accumulated 32 ETH and your oracle has reported you should be able to call :
This should not revert and a deposit should have happened.
Afterwards you should be able to monitor the growth of your position upon every oracle report.
Kiln aims to provide a secured and enhanced experience of staking through the different Kiln On-Chain smart contract platforms.
On-Chain products have been audited multiple time by various security firms and are under exhaustive monitoring and security practices to limit security risks as much as possible.
Resource | Link |
---|
Security firm | Audit link | Scope | Date |
---|
A $1,000,000 max bounty program is live since 21 August 2023. All bug reports must come with a working PoC impacting asset listed in the "Assets in Scope" section of the program which only addresses smart contracts.
Kiln is SOC 2 Type I and SOC 2 Type II certified and has been undergoing multiple penetration testings and audits from third parties.
Immunefi
A $500,000 max bounty program is live since September 9th 2024. All bug reports must come with a working PoC impacting asset listed in the "Assets in Scope" section of the program which only addresses smart contracts.
To deploy a new vPool, you need to perform a transaction from the ADMIN
address of your vFactory.
The transaction should be made to the Nexus contract. This contract is the entry point of the system, it's mainly used to deploy new instances of contract, but once contracts are deployed, they do not rely on it anymore.
For this guide, the transactions are made with Of course, any tool able to craft the transactions would do the job, we will provide the contract ABIs as we move forward in the guide.
We need to call the spawnPool
method on the Nexus contract.
Several parameters are required to spawn a pool:
Let's go through all of them one by one:
epochsPerFrame
: an oracle quorum will need to run and report some important consensus layer data to the vPool contract. This parameter will control at which rate the reports will be made (reports are made at the beginning of every frame). On mainnet, we suggest setting this value to 225
(24 hours), and on testnet we can use something lower like 15
(1h30).
operatorFeeBps
: Every time the oracle will report, possible rewards will be received by the pool. The operator can take a cut on these rewards in the form of shares of the vPool. These shares will be sent automatically to the vTreasury contract of the operator. This value is in basis points ( [0, 10000] )
factory
: The address of the vFactory on which this vPool will be plugged.
reportBounds
: To ensure the validity of the reported data, some reporting bounds are configured to prevent reports that would be reporting values out of bounds. The first value of the bound array if the upperBound
, this value is the maximum apy
authorized, in basis point. Setting it to 1000
means that the oracle report will make sure that the accrued rewards are not exceeding 10%
apy. The second value is the coverageUpperBound
. The vPool has the ability to pull funds from a special recipient called the vCoverageRecipient
. This recipient will be used only in the case of loss of funds due to slashing. The coverageUpperBound
is a boost applied to the upperBound
only usable for coverage funds. This would ensure that coverage funds are pulled quickly into the system. The third value is the lowerBound
. This value is relative to the total underlying supply, setting it to 100
means that the report balance shouldn't decrease by 1%
of the total underlying supply or more. You can see these bounds as additional safety nets that would prevent invalid reports from going through as exceeding these bounds should not happen based on how the consensus layer works, the rewards rate, and how penalties could be applied.
initialExtraData
: This argument is sent to the vFactory whenever a validator is purchased. This is an arbitrary metadata field that will be emitted with the event of funding on the vFactory. Feel free to use this value as you want as it has no impact on the behavior of the vPool. You can leave it empty if needed.
exitQueueImageUrl
: This argument is used for the exit queue tickets. They are represented as NFTs, and this argument configures the image field in their metadata. You can use Kiln's endpoint (wip) or build your own and serve the image that you want.
We can now perform the transaction to spawn a new vPool instance
You have now deployed your vPool alongside all its required contracts. Let's recap what each contract does:
vPool
: the main pooling contract, receives deposits of any size and creates shares of the pool in exchange.
vWithdrawalRecipient
: this contract's address is set as the withdrawal credential on the pool validators. It will be in charge of retrieving the consensus layer funds coming to the system, and will be called by the vPool contract to send the funds.
vExecLayerRecipient
: this contract's address is set as the fee recipient on the pool validators. It will be in charge of retrieving all the block proposal related fees that happen directly on the execution layer, and will be called by the vPool contract to send the funds.
vCoverageRecipient
: this contract holds funds provided by configured donors. In case of slashing losses, funds from this contract can be used to repay the loss. Pulled funds are not accounted in revenue, so no commission will be taken on these funds.
vOracleAggregator
: this contract holds a list of quorum members that have to vote on a report. Once a quorum is met for a specific report value, the report is forwarded to the vPool contract. The contract cannot work if only one member is present in the quorum, this is why Kiln runs what is called the global oracle member, a member that is present by default in every vOracleAggregator contract, and makes sure bootstrapping happens as expected. This global oracle member can be ejected if and only if the contract has 5+ oracle members registered and the ejection flag is set to true
vExitQueue
: this contract is in charge of processing the exit requests of the vPool share holders. In exchange of shares, a recipient will receive an NFT representing its future claim. Based on the demand in the exit queue contract, vPool will emit events that signal the possible need for an exit to the node operator
For both the oracle reporting and the exit queue events, Kiln provides the operatord
tool, that holds the daemons to perform the oracle reports automatically (start-oracle)
and to catch exit requests and forward them to a custom webhook endpoint (start-exit-daemon
). The configuration of both of these daemons is covered later in this guide.
In the unlikely event that Kiln becomes insolvent, we have a business continuity and disaster recovery plan which we were certified for as part of our successful SOC 2 Type II audits.
B2B customers of Kiln can retrieve pre-signed Ethereum validator exit messages which enables them to unilaterally unstake.
We also have an involving exiting all validators or transferring validation keys in case Kiln can no longer operate the service.
Contract | Action | Description | Regularity |
---|---|---|---|
Contract | Action | Description | Regularity |
---|---|---|---|
Security firm | Audit link | Date |
---|
Certifications and audits reports are available upon request .
PROXY_ADMIN
Responsible for upgrades operations (pause/unpause/add new logic or fix contract data/freeze contract upgrades)
SYS_ADMIN
Responsible for Operation administration: set commissions, add / remove Operator(s), approve / remove Operator validation keys before they are funded
OPERATOR (can be multiple)
Add / Remove validation key deposit data
StakingContract
pause
pause Staking Contract (no non-view functions can be called)
Exception
StakingContract
unpause
unpause Staking Contract
Exception
StakingContract
changeAdmin
change PROXY_ADMIN address
Exception
StakingContract
upgradeTo
change implementation address
Exception
StakingContract
upgradeToAndCall
change implentation address and performs an additional setup call
Exception
StakingContract
setWithdrawerCustomizationEnabled
Enable or disable the ability for users to modify their withdrawer address
Exception
StakingContract
setTreasury
Set new treasury recipient address
Rare
StakingContract
transferOwnership
Set new SYS_ADMIN
Exception
StakingContract
addOperator
Register Operator address and commission recipient address
At Setup time
StakingContract
setOperatorLimit
Set Operator number of keys to be exposed to the end users for deposit
Often
StakingContract
deactivateOperator
Deactivate operator, its commission recipient and key limit
Exception
StakingContract
activateOperator
Activate operator, without changing the 0 limit
Exception
StakingContract
setOperatorFee
Change the operator fee
Rare
StakingContract
setGlobalFee
Change the Global fee
Rare
StakingContract
setDepositsStopped
Pause or Resume the deposit feature
Exception
StakingContract
batchWithdrawCLFee
Withdraw CL Recipients of multiple staked positions
Rare
StakingContract
batchWithdrawELFee
Withdraw EL Recipients of multiple staked positions
Rare
StakingContract
withdrawELFee
Withdraw EL Recipient of a staked position
Rare
StakingContract
withdrawCLFee
Withdraw CL Recipient of a staked position
Rare
StakingContract
addValidators
Add new validator deposit data to be approved by the SYS_ADMIN
1/mth (depends on the deposit volume)
StakingContract
removeValidators
Remove validators that are not funded
Exception
StakingContract
setOperatorAddresses
Change Operator Address and/or Operator Commission recipient address
Exception
Staking of any kind is never risk-free.
Don’t invest unless you’re prepared to lose all the money you invest. This is a high-risk investment and you should not expect to be protected if something goes wrong. Take 2 mins to learn more
Slashing Risk: Staking assets carries the risk of loss if your validator(s), or validators in a staking pool, incur network penalties.
Smart Contract Risk: smart contracts may contain vulnerabilities that can impact the security and functionality of the staking service, putting your funds at risk.
Protocol Risks: Protocols, including updates they deploy, can introduce bugs or vulnerabilities to the staking protocol putting your funds at risk.
Liquidity Constraints: Staking ETH locks funds, potentially risking liquidity if needed urgently or in changing market conditions; assess your liquidity needs.
Staking Reward Variation: Staking rewards are determined by the protocol and can fluctuate, with no guarantee of future returns.
Validators face staking penalties, which can result in up to a 100% loss of their staked ETH if they fail to fulfil their responsibilities.
When you stake with this service, Kiln will operate validator(s) on your behalf. If these validators are incorrectly operated, it is possible for a portion of the ETH you have staked to be slashed, meaning they are destroyed by the protocol.
Please read this article to learn more about Kiln monitoring and slashing and downtime mitigation.
It is important to acknowledge the inherent risk that the Kiln smart contracts may contain vulnerabilities or bugs.
Our smart contracts have undergone comprehensive audits conducted by industry leaders such as Spearbit and the Ledger Donjon. Access reports and read more about our security practices here and here.
Ethereum, a rapidly evolving technology developed by a decentralized collective, operates independently of any central authority such as Kiln. It is important to note that, due to its nascent stage, Ethereum may contain potential errors or vulnerabilities. Consequently, these vulnerabilities could pose a slashing risk to the network.
When you stake your ETH, it becomes locked in the staking process for a certain period of time, during which it is not readily available for immediate use or trading. This lack of liquidity can pose a risk if you need to access your ETH quickly or if market conditions change unfavorably during the staking period. It's important to consider this liquidity risk and assess your own needs for liquidity before engaging in native Ethereum staking.
Additionally, it's important to be aware of the bonding and unbonding periods involved in the staking process. These periods refer to the time it takes for validators to enter and exit the system, as well as the withdrawal queue duration, during which your validator will not be earning any rewards.
Before staking, it is highly recommended to familiarize yourself with these processes. You can find more detailed information in the documentation that follows.
Kiln is a technology services provider that operates a validator on your behalf on the Ethereum blockchain. It enables access to the staking process as defined by the Ethereum protocol developers and does not possess the ability to influence or modify its implementation.
Rewards are not guaranteed.
We invite you to read this informative article that provides insights into the expected staking rewards on the Ethereum network. It covers the various types of rewards and their characteristics in detail.
In summary, Ethereum staking offers two types of rewards: consensus layer and execution layer rewards.
Execution layer rewards tend to be less frequent but more substantial in value. On the other hand, consensus layer rewards are received more frequently but are relatively smaller in amount. These rewards become available for claiming once they have been "skimmed" or "withdrawn" by the protocol, which typically takes around five days.
It's important to note that all staking rewards are generated by the Ethereum protocol itself and are not determined or influenced by Kilnv or any other entity.
Guide to deploy an integration contract and connecting it to a vPool
.
You can ask Kiln to deploy an integration contract for you or deploy it yourself.
If you want to deploy it yourself ask Kiln to give the right to deploy using the IntegrationFactory
and give us the address you want as deployer
.
Kiln or your can deploy an Integration contract using a deployer
account on the IntegrationFactory:
These function use the following structs:
Let's go through all of them one by one:
Common parameters :
name
: An ERC-20 style display name of the token.
symbol
: an ERC-20 style display symbol of the token.
admin
: The address of the admin. This account can change the fees, and commissionRecipient
as well as add pools and enable/disable them.
pools
: List of underlying pools addresses. Those are the pools to which the staked funds will flow to. You must provide at least one pool.
poolFees
: List of fee for each pool, in basis points. Must be the same length as pools
. The fee for a single pool must not exceed maxCommissionBps
.
commissionRecipients
: List of addresses to which the accumulated integrator fee will be dispatched.
commissionDistribution
: List of the share of the fee each commissionRecipient
will receive, in basis points, must add up to 10 000. Must be the the same length as commissionRecipients
.
maxCommissionBps
: A limit on the pool fee given at initialization so the stakers can be sure the fee will never go above a certain level.
poolPercentages
: The desired repartitions of ETH between the pools. In basis points, must add up to 10 000. Must be the same length as pools
. This can be changed by the admin
.
monoTicketThreshold
: A value that modify the behaviour of requestExit()
when the contract is connected to multiple pools, when exiting we want to limit the number of tickets minted for gas efficiency but we also want to limit the imbalance caused by not exiting through all the pools using the the configured poolPercentages
.
If a user requests the exit of an ETH amount below monoTicketThreshold
the code will try to exit through only one pool if possible thus minting only one ticket hence the name monoTicketThreshold
. This value can be changed later on by the admin
as the TVL grows and the pools can support bigger exit without significant imbalance.
If you are using Kiln's pool ask us to allow your contract to deposit to our pool.
If you manage your pool, allow your integration contract to deposit on the vPool
by calling this function :
Used to retrieve the historical reward rate of the pool so that it can be displayed to your users in your native workflow.
The pool reward rate can only ever be based on a rolling historical average (we can never predict the future rate). The data returned includes the average of the last week, last month, last 3 months, last 6 months and 'all time'.
It is up to you to choose the which historical rolling average to use, but most integrators currently use the last week.
TIP: you need to convert the results to a percentage (%). For example:
'All Time' Gross Reward Rate returns: 26478817328005117
Convert to %
26478817328005117 / 10^18 =
.02647 (2.647%)
Using The Graph
Query
Example results
Used to retrieve the rewards of the given user based on their staked position
TIP: the result is in wei, you need to convert it to ETH. For example:
allTimeRewards = 46478817328005117
Convert to ETH
46478817328005117 / 10^18 = 0.046478817
ETH
allTimeRewards
= ((sharesBalance * totalUnderlyingSupply) / totalSupply) - adjustedTotalDeposited
Using The Graph
Query
Example results
Used to stake any amount of ETH into the pool.
This can only be executed by calling a smart contract method:
Used to find the amount of shares for a given wallet from the integration contract
Using the smart contract view methods
Allows you to obtain the value (in ETH) of the users current staked position
For example, consider the scenario where a user staked 12 ETH several months ago. Every time they visit your app, you want to showcase the current value of the staked position accounting for the accrued value from staking rewards over time.
You can simply query the smart contract with the users wallet.
Using the smart contract view methods
Using TheGraph queries
TheGraph queries
This process is gas intensive and a Merkle Tree based solution is currently being worked on that would only require an update + approval of the tree root, drastically reducing the gas cost to add keys.
Now that we have the exact address of the vPool and its vWithdrawalRecipient, we can start creating validation keys for its withdrawal credentials and upload them to the vFactory.
The vFactory stores keys in separated Withdrawal Channels. Only two types of Withdrawal Channels exist:
Withdrawal Channel != 0: The withdrawal channel value is the actual withdrawal credential of the keys inside the channel. In the case of the vPool, keys are added on a withdrawal channel that is equal to the withdrawal credential of the vWithdrawalRecipient
Withdrawal Channel == 0: This special withdrawal channel holds keys with each its own withdrawal recipient, handled by the vFactory. This means that the generation of these keys is a bit different as the address of the withdrawal recipient is deterministic and based on the validator public. We won't use this channel for the vPool.
We will need both the withdrawal credential and the vWithdrawalRecipient address for the next step
For our example, we'll use the official deposit cli to generate 10 keys for the pool.
And once done, you can check the generated deposit_data
file to make sure that all keys:
have the same withdrawal credential
the value is the proper one
We can now verify our deposit data to make sure it's valid. The tool we're going to use ensures that the key has no duplicates inside the vFactory and ensures that the signature associated with the public key is valid.
You should retrieve the vsuite-utils
repository, and have golang
installed for the next step.
Clone vsuite-utils
and run:
It should directly tell you if there is any error in the deposit_data
, otherwise we're clear to advance to the next step: submitting the keys
We can now convert the generated deposit_data
into calldata for the submit transaction.
When keys are approved, authorized depositors on the withdrawal channel will be able to fund them. This means that it is a very critical action, that only the ADMIN
of the vFactory can perform. We suggest using a multisig where a quorum of members will be able to run the verification script on their end to ensure that the current keys of the channel are valid.
The approve
method of the vFactory is able to change the staking limit of several withdrawal channels at once.
The parameters are the following ones:
withdrawalChannels
: The list of withdrawal channels that we will approve
limits
: The staking limits of the withdrawal channels, at the same indexes
snapshots
: This parameter will ensure that the approval only passes if there has been no modification to the channel since the provided snapshot block number. When perform the off-chain verifications, quorum members should use the same snapshot block number to perform their verifications.
Once we know all the keys are valid, we can approve them ! In the following example we use cast but only as illustration for testnet, we strongly recommend using a strong multisig on mainnet for this purpose.
The vFactory is now ready for the vPool to purchase up to 10 validators !
Handling exit requests
As the channels can automatically select a number of validators that should be stopped, the "Exit Daemon" is here to signal the exit requests on a given vFactory.
This utility is a REST endpoint and also a webhook for the operators to automate exit flow of the validators.
📝 You will run one Exit Daemon for one vFactory
You can find the exit daemon inside the operatord
repository.
The daemon is configured using a config.yaml
file, the same as the Oracle Daemon.
You have the option to either incorporate the following lines into a new configuration file or append them to the existing Oracle Daemon configuration file:
factory
: Address of the operator vFactory (mandatory).
hook-endpoint
: REST endpoint that will be called (POST) when a report is available (optional).
Then, we can run the exit daemon by running:
execution-node-url
is an rpc endpoint on the execution layer (geth, erigon, etc...).
consensus-node-url
is an rpc endpoint on the consensus layer (prysm, lighthouse, etc...).
config-file
is the path to the file we configured above.
At every epoch (finalized), if exits are needed, the Exit Daemon craft a report for each withdrawal channel associated with the specified vFactory.
A report follows this JSON structure:
epoch
: Epoch of the report
withdrawalChannel
: Withdrawal channel id.
lastRequestTxHash
: TX hash of the latest SetExitTotal event.
validatorCountToExit
: Delta between the requested and actual exited validators.
totalCurrentlyExited
: Total exited validators for the withdrawal channel.
suggestedValidatorExits
: Lists suggested validators, providing their index and public key, that are eligible for exit. The suggested validators for exit are those with the oldest activationEpoch
.
exitableValidators
: Complete list of index / public Keys of all the currently exitable validators of the withdrawal channel.
The last (up to date) reports can be accessed using the REST API.
Every epoch, the daemon has the capability to forward the reports to an endpoint.
As outlined in the configuration, you can specify a hook-endpoint
in the configuration file. This endpoint will be triggered with a POST request when a report becomes available.
To illustrate its operation, we've created a demo server:
The demo server accepts these reports and displays the corresponding JSON data in the terminal. It provides access to these reports via the /report
route.
Source Code (Smart Contracts only) |
Ledger Live mainnet |
Ledger Live testnet |
Other mainnet and testnet deployments |
not available | July 21st 2022 March 15th 2023 |
July 22nd 2022 |
July 27th 2023 |
not available | July 21st 2022 March 15th 2023 |
July 27th 2023 |
SYS_ADMIN
multi-sig or MPC wallet
pausing deposits
changing SYS_ADMIN
modifying end user fee (aka commission)
modifying commission split and recipients
modifying operator pools
modifying weighting across operator pools,
when connected to two or more pools
PROXY_ADMIN
multi-sig or MPC wallet
pausing and resume contract
changing PROXY_ADMIN
upgrading implementation contract
TheGraph indexes data from the smart contracts to facilitate easier access. You can use it to understand what happens live during this guide.
To gain access to TheGraph, contact Kiln and you will receive credentials to Kiln's TheGraph instance. Feel free to also host the subgraph on your end, allowing you to run the queries locally. During this guide, we will often use TheGraph queries to verify that specific actions had the expected outcome.
The easiest way to interact with TheGraph is by visiting the web query builder.
To test it, you can try a simple query to retrieve all the deposits made by an address on an integration contract (Native20,Liquid20A or Liquid20C):
And if everything goes well, you should have a response looking like this if the wallet made some deposits.
You're now ready to follow the guide and run the queries when needed !
If you are interacting with the smart contracts using javascript (e.g. web3.js or ethers.js) you need the contract ABI and its address.
The ABI is used to encode the interface of a smart contract in a format understandable to your user interface.
Audit report is available upon request .
Smart Contract | Link |
---|---|
V2 Contract (Mainnet)
V2 Contract (Testnet)
V1 Contract (Mainnet - Deprecated)
Consensus Layer Fee Dispatcher
Consensus Layer Fee Dispatcher (testnet)
Consensus Layer Fee Dispatcher Proxy
Consensus Layer Fee Dispatcher Proxy (testnet)
Execution Layer Fee Dispatcher
Execution Layer Fee Dispatcher (testnet)
Execution Layer Fee Dispatcher Proxy
Execution Layer Fee Dispatcher Proxy (testnet)
Fee Recipient
Fee Recipient (testnet)
Staking Contract
Staking Contract (testnet)
Staking Contract Ledger Live Proxy
Staking Contract Ledger Enterprise Proxy
Staking Contract Enzyme Proxy
Staking Contract Kiln Proxy
Staking Contract Safe{Wallet}
Staking Contract Consensys/Metamask
Staking Contract Proxy (testnet)
Nexus
Factory (Coinbase Cloud)
Pool (Coinbase Cloud Pool)
Oracle Aggregator (Coinbase Cloud Pool)
Pool (Coinbase Cloud Pool)
Oracle Aggregator (Coinbase Cloud Pool)
Factory (Kiln)
Pool (Kiln Pool)
Oracle Aggregator (Kiln Pool)
factoryHatcher
treasuryHatcher
poolHatcher
withdrawalRecipientHatcher
execLayerRecipientHatcher
coverageRecipientHatcher
oracleAggregatorHatcher
exitQueueHatcher
ONTO Wallet Staked ETH (owsETH)
Staking Rewards Partial ETH (srpETH)
On-Chain Staked Ethereum (ocsETH)
CDP Staked ETH (CDPstakedETH)
Coinbase Wallet Staked ETH (cbwsETH)
CoolWallet Staked ETH (cwstETH)
Crypto.com Defi Wallet ETH (cdwETH)
Walletverse Staked ETH (wvETH)
Giddy Wallet Staked ETH (GiddyETH)
Pooled Staked ETH (psETH)
Bitnovo Staked ETH (bnETH)
CDP Staked ETH (CDPstakedETH)
Dakota Kiln Staked ETH (dkETH)
MEW_Coinbase Staked ETH (MEWcbETH)
Veno Kiln staked ETH (VenoKilnETH)