🏗️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.
integrator: a platform (e.g., wallet, web platform) offering staking services to their users by integrating with the On-Chain 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 On-Chain 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!)
Integration contracts
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
Under the hood, when a user stakes their ETH, the integration contract purchases shares of the vPool using the staked ETH. The integration contract then provides an interface for end-users, maintaining ownership of the vPool shares and managing balancing logic during staking and unstaking.
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, transferable or non-transferable based on the integrator's preference, represents their stake ownership and serves as the withdrawal credentials.
Integrators have full control over the token and can define the token name and symbol. For example, myETH (My Company ETH). A token is always issued, but integrators can choose between a soulbound and liquid staking token.
NOTE: the Operator Pool has no concept of tokens. The integrator contracts are where tokens are issued and managed.
Operator Pool (vPool)
Think of Operator Pools (aka vPools), as pooled staking engines, each managed by a node operator. These are sets of smart contracts that are configured to oversee the fundamental operations and lifecycle of the pool, encompassing deposits, validator activation and deactivation, reward distribution, exits, and commission management.
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 shares of the vPool will increase in value over time as rewards flow into the system.
This means that users will 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
