🏗️Architecture overview
This page provides a high-level understanding and overview of the architecture of the smart contracts as it relates to pooled staking.
Introduction
Before getting started, here are a few terms we commonly use in the architecture overview.
partner: 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 partners.
integration contract: A smart contract owned and operated by the partner, serving as the primary integration point to the platform (end-user fees, commissions, node operator preferences and splits, and more!)
Integration contracts
A smart contract owned and operated by the partner, 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 partner.
Integration 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
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 partner's preference, represents their stake ownership and serves as the withdrawal credentials.
Partners 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 integration contracts are where tokens are issued and managed.
Operator Pool
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
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.
Oracle 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 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
Exiting
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)
Request exit
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.
Wait for the request to be fulfilled
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.
Withdraw the ETH
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.
Last updated
