Obol Splits
Last updated
Last updated
Obol develops and maintains a suite of smart contracts for use with Distributed Validators and their surrounding ecosystem of decentralised infrastructure. These contracts include:
Validator Managers: Contracts used for a validator's withdrawal address, enabling ownership transfer, partial withdrawals, full exits, and operator rotation.
Reward Splitting contracts: Contracts to split ether (and tokens) across multiple entities. Developed by
Key Design Principles the Obol Smart Contract suite include are:
That they are secure. All Obol Splits products are .
They are not upgradeable.
They are self-soverign. Any permissioned actions, such as withdrawal, exit, or operator rotation, are controlled by the user, not an unaccountable set of third parties with the ability to upgrade your contracts behaviour.
They do not require a token to function.
They are oracle-free. (Unless you intend to leverage a ).
They divide the reward ether from principal ether such that staking providers can be paid a percentage of the reward they accrue for the principal provider rather than a percentage of principal and reward.
That rewards can be withdrawn in an ongoing manner without exiting the validator. (Some conditions apply).
An Obol Validator Manager (OVM) is a smart contract which manages the deposit, withdrawal, exit, and public key rotation of one or more Ethereum validators. It is deployed as the withdrawal address for a validator and supports 0x01 and 0x02 validator types.
You create a new Validator Manager contract using the by calling the ObolValidatorManagerFactory.createObolValidatorManager()
function, passing:
owner
- The address that is the ultimate administrator of this Validator Manager deployment, it manages the assignment of roles for the contract and can call all privileged methods. This address is best suited to being a multi-sig (such as a ) with a large number of signers, used only as a fallback, or it can be owned temporarily, fine grained roles can be assigned to addresses, and then the or methods can be called.
principalRecipient
- This is the address where the principal will be returned to when validators exit or a withdrawal above the principalThreshold is made. This can be changed later by the owner
or addresses with the SET_PRINCIPAL_ROLE
.
rewardRecipient
- This is the address where the accrued ether reward will be sent when distributeFunds()
is called. Usually it is a from . This address cannot be updated, instead you can specify an owner of the split, to modify the distribution percentages in future.
principalThreshold
- This is a configurable amount of Ether which dictates at what amount of value in the contract should we consider it to be principal being returned rather than reward accrued. A sensible default here is 16 ether, the threshold used in Obol's earlier . Further detail in the section.
Obol Validator Managers implement standard Role Based Access Control. The OVM has the following roles, that can be granted by the OVM owner.
CONSOLIDATION_ROLE
: Permits an address to initate a consolidation between one or more source validators and a target validator, all managed by this contract. All source and target validators must be active with a balance greater than 32 ether.
SET_PRINCIPAL_ROLE
: Permits an address to change the recipient of the principal returned when validators exit, or a withdrawal above the principalThreshold is initiated.
RECOVER_FUNDS_ROLE
: Permits an address to initiate ERC20.transfer()
calls to arbitrary external addresses, with the intent to recover otherwise stuck tokens.
The owner
address, or any address with the CONSOLIDATION_ROLE
can call the requestConsolidation()
method, to initiate a consolidation between one or more source validators and a target validator, all managed by this contract.
The owner
address, or any address with the RECOVER_FUNDS_ROLE
can call the recoverFunds()
method, to send an ERC20 token balance on the ObolValidatorManager contract to an arbitrary recipient
address.
Be cautious when interacting with unknown ERC20 addresses, they may not behave as anticipated.
Optimistic Withdrawal Recipients (OWRs) are the predecessor to Obol Validator Managers. The primary addition with Validator Managers is the role-based control over validator withdrawals, exits and consolidations.
Optimistic Withdrawal Recipients allow for the separation of reward from principal, as well as permitting the ongoing withdrawal of accruing rewards.
A principal address: The address that controls where the principal ether will be transferred post-exit.
A reward address: The address where the accruing reward ether is transferred to.
The amount of ether that makes up the principal.
This contract assumes that any ether that has appeared in its address since it was last able to do balance accounting is skimming reward from an ongoing validator (or number of validators) unless the change is > 16 ether. This means balance skimming is immediately claimable as reward, while an inflow of e.g. 31 ether is tracked as a return of principal (despite being slashed in this example).
Worst-case mass slashings can theoretically exceed 16 ether, if this were to occur, the returned principal would be misclassified as a reward, and distributed to the wrong address. This risk is the drawback that makes this contract variant 'optimistic'. If you intend to use this contract type, it is important you fully understand and accept this risk.
This contract fits both design goals and can be used with thousands of validators. It is safe to deploy an Optimistic Withdrawal Recipient with a principal higher than you actually end up using, though you should process the accrued rewards before exiting a validator or the reward recipients will be short-changed as that balance may be counted as principal instead of reward the next time the contract is updated. If you activate more validators than you specified in your contract deployment, you will record too much ether as reward and will overpay your reward address with ether that was principal ether, not earned ether. Current iterations of this contract are not designed for editing the amount of principal set.
Validators have two streams of revenue, the consensus layer rewards and the execution layer rewards. Validator Managers focus on the former, split contracts focus on the latter. They are best used in tandem.
A split, or splitter, is a set of contracts that can divide ether or an ERC20 across a number of addresses. Splits are often used in conjunction with withdrawal recipients. Execution Layer rewards for a DV are directed to a split address through the use of a fee recipient
address. Splits can be either immutable, or mutable by way of an admin address capable of updating them.
Mainnet
Hoodi
Holesky
Sepolia
Mainnet
Hoodi
Holesky
Sepolia
Mainnet
Holesky
Sepolia
Obol Splits refers to a collection of composable smart contracts that enable the splitting of validator rewards and/or principal in a non-custodial, trust-minimised manner. Obol Splits contains integrations to enable DVs within Lido with Obol Lido Splits, and Native Staking with Obol Validator Managers.
In this case, the OVM contract will not have recorded the deposit as principal to be returned, so when the validator exits, it will be sent to the reward address. Consider editing the reward address to pay 100% to the principal recipient, exiting the validator, claiming the 'rewards', and editing the reward split back to normal, before depositing through the OVM for a new validator private key that exits to the same OVM contract.
Determining if Ether returned from a validator is principal deposited or rewards accrued is difficult. Rather than introducing an off-chain proof system, or trusted oracle, Obol Splits adopt an assumption that a mass slashing so severe that the principal returned is less than 16 eth is very rare, and the outcome that would happen in that case is the rewards would be sent to the reward rather than principal address, an accepted risk. This however does impact reward claiming on very large 0x02 validators. A validator could have earned 20 ether in rewards, and if a request for withdrawal of 20 ether is processed, it would be subtracted from principal and disbursed to the principal recipient, and upon a full exit, the remaining eth beyond the principal would be sent to the rewards address. To avoid this, entities with the WITHDRAWAL_ROLE
should withdraw increments less than the principalThreshold
if they want it treated as reward, and more than principalThreshold
if they want to process it as a direct exit.
No. Any address can trigger the contracts to distribute the withdrawn/skimmed ether, they do not need to be a member of the Split either. You can set your cold wallet/custodian address as the recipient of the principal and rewards, and use any hot wallet to pay the gas fees to push the ether into the recipient address.
The most important thing to be aware of is what address is the owner of the Obol Validator Manager, whether it has assigned any other addresses any roles, and whether or not the Split contract you are using has been set up with editability and by which address. If a splitter is editable, you should understand what the address that can edit the split does. Is the editor an EOA? Who controls that address? How secure is their seed phrase? Is it a smart contract? What can that contract do? Can the controller contract be upgraded? etc. Generally, the safest thing in Obol's perspective is to use a high threshold multi-sign like a SAFE as the owner
/controller
, or to renounce ownership and control entirely, and if in future you are unhappy with the configuration, that you exit the validator and create a fresh cluster with new settings that fit your needs.
WITHDRAWAL_ROLE
: Permits an address to trigger a partial withdrawal, or full exit of all validators managed by this contract using .
Obol Validator Managers support smart contract based withdrawals. The owner
address, or any address with the WITHDRAWAL_ROLE
can call the requestWithdrawal()
method, to initiate a partial (or full) withdrawal of the balance of a validator managed by this contract.
Obol Validator Managers support smart contract based validator consolidations. This is an important feature for rotating the private keys for the validators managed by this contract. The rotation of private keys allows for the secure re-distribution of validation duties amongst new operators, without a significant period of inactivity in a normal exit and recreate flow.
An Optimistic Withdrawal Recipient takes three inputs when deployed:
The alternative is to use an splits.org , which won't allow the claiming of rewards until all principal ether has been returned, meaning validators need to be exited for operators to claim their CL rewards.
Further information about splits can be found on the splits.org team's . The addresses of their deployments can be found .
Splits can be completely edited through the use of the controller
address, however, total editability of a split is not always wanted. We recommend using a to manage the Split.
A is a common method to administrate an editable split. The most well-known deployment of this pattern is the . The SAFE can arbitrarily update the split to any set of addresses with any valid set of percentages.
The ObolValidatorManager
contract is deployed via a . The factory is deployed at the following addresses on the following chains.
The ObolLidoSplit
contract is deployed via a . The factory is deployed at the following addresses on the following chains.
The OptimisticWithdrawalRecipient
contract is deployed via a . The factory is deployed at the following addresses on the following chains.
Yes. Unless you were to decide to , Obol Splits are immutable, non-upgradeable, non-custodial, and oracle-free. Obol Validator Managers have owners and Role Based Access Control, but these are self-sovereign and up to the deployer to set and manage. There is no third party with access to or control of your validator unless you grant them such access.
Generally Obol Splits are deployed in an immutable fashion, meaning you cannot edit the percentages after deployment. However, if you were to choose to deploy a controllable splitter contract when creating your Split, then yes, the address you select as controller can update the split percentages arbitrarily. A common pattern for this use case is to use a Gnosis SAFE as the controller address for the split, giving a group of entities (usually the operators and principal provider) the ability to update the percentages if need be. A well known example of this pattern is the .
Yes, Obol Splits are licensed under GPLv3 and the source code is available .
The Obol Splits contracts have been audited, though further development has continued on the contracts since. Consult the audit results and always deploy contracts only from published .
Yes, you can view the verified contracts on Etherscan. A list of the contract deployments can be found .
Another aspect to be aware of is how the splitting of principal from rewards works using the Optimistic Withdrawal Recipient contract. There are edge cases relating to not calling the contracts periodically or ahead of a withdrawal, activating more validators than the contract was configured for, and a worst case mass slashing on the network. Consult the documentation on the contract , its audit , and follow up with the core team if you have further questions.