LogoLogo
SDKAPI
Version-v1.4.0 (current)
Version-v1.4.0 (current)
  • Learn
    • Introduction
      • Obol Collective
      • OBOL Incentives
      • Key Staking Concepts
      • Obol vs Other DV Implementations
      • Obol Splits
      • DV Launchpad
      • Frequently Asked Questions
    • Charon
      • Introduction to Charon
      • Distributed Key Generation
      • Cluster Configuration
      • Charon Networking
      • CLI Reference
    • Futher Reading
      • Ethereum and Its Relationship With DVT
      • Community Testing
      • Peer Score
      • Useful Links
  • Run a DV
    • Quickstart
      • Quickstart Overview
      • Create a DV Alone
      • Create a DV With a Group
      • Push Metrics to Obol Monitoring
    • Prepare to Run a DV
      • How and Where To Run DVs
      • Deployment Best Practices
      • Test a Cluster
    • Running a DV
      • Activate a DV
      • Update a DV
      • Monitoring Your Node
      • Claim Rewards
      • Exit a DV
    • Partner Integrations
      • Create an EigenLayer DV
      • Create a Lido CSM DV
      • DappNode
  • Advanced & Troubleshooting
    • Advanced Guides
      • Create a DV Using the SDK
      • Migrate an Existing Validator
      • Enable MEV
      • Combine DV Private Key Shares
      • Self-Host a Relay
      • Advanced Docker Configs
      • Beacon node authentication
    • Troubleshooting
      • Errors & Resolutions
      • Handling DKG Failure
      • Client Configuration
      • Test Commands
    • Security
      • Overview
      • Centralization Risks and Mitigation
      • Obol Bug Bounty Program
      • Smart Contract Audit
      • Software Development at Obol
      • Charon Threat Model
      • Contacts
  • Community & Governance
    • Governance
      • Collective Overview
      • The Token House
      • The RAF
      • Delegate Guide
      • RAF1 Guide
    • The OBOL Token
      • Token Utility
      • Token Distribution & Liquidity
      • TGE FAQ
    • Community
      • Staking Mastery Program
      • Techne
    • Contribution & Feedback
      • Filing a Bug Report
      • Documentation Standards
      • Feedback
  • Walkthrough Guides
    • Walkthroughs
      • Walkthrough Guides
  • SDK
    • Intro
    • Enumerations
      • FORK_MAPPING
    • Classes
      • Client
    • Interfaces
      • ClusterDefinition
      • RewardsSplitPayload
    • Type-Aliases
      • BuilderRegistration
      • BuilderRegistrationMessage
      • ClusterCreator
      • ClusterLock
      • ClusterOperator
      • ClusterPayload
      • ClusterValidator
      • DepositData
      • DistributedValidator
      • ETH_ADDRESS
      • OperatorPayload
      • SplitRecipient
      • TotalSplitPayload
    • Functions
      • validateClusterLock
  • API
    • What is this API?
    • System
    • Metrics
    • Cluster Definition
    • Cluster Lock
    • State
    • DV Exit
    • Cluster Effectiveness
    • Terms And Conditions
    • Techne Credentials
    • Address
    • OWR Information
  • Specification
Powered by GitBook
On this page
  • Obol Validator Managers​
  • Creation
  • Roles
  • Partial Withdrawals & Full Exits
  • Validator Consolidations
  • Token Recovery
  • Optimistic Withdrawal Recipient​
  • Split Contracts​
  • Split Controllers​
  • Deployments
  • Obol Validator Manager Factory Deployment ​
  • Obol Lido Split Factory Deployment ​
  • OWR Factory Deployment ​
  • FAQ
  • What are Obol Splits?
  • Are Obol Splits non-custodial?
  • Obol Validator Managers
  • Can I change the percentages in a split?
  • Are Obol Splits open source?
  • Are Obol Splits audited?
  • Are the Obol Splits contracts verified on Etherscan?
  • Does my cold wallet have to call the Obol Splits contracts?
  • Are there any edge cases I should be aware of when using Obol Splits?
Edit on GitHub
  1. Learn
  2. Introduction

Obol Splits

PreviousObol vs Other DV ImplementationsNextDV Launchpad

Last updated 5 days ago

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).

Obol Validator Managers

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.

Creation

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.

Roles

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.

Partial Withdrawals & Full Exits

If you request to withdraw an amount that would leave a validator with less than a 32 ETH balance, only the amount that would leave the validator with 32 ETH will be withdrawn.

If you request to partial withdraw a validators balance, the funds will be available in the OVM contract at the end of the exit queue. (Usually ~27 hours)

However if you withdraw the full balance of the validator, triggering its complete exit, the Ether will be available to to the OVM contract once the validator is through the exit queue, and the skimming process has completed. (Average of ~5 Days) This could add a number of days to the wait for validator funds, and full exiting at an optimal moment could significantly shorten the duration.

function requestWithdrawal(
    bytes[] calldata pubKeys,
    uint64[] calldata amounts
  ) external payable onlyOwnerOrRoles(WITHDRAWAL_ROLE) {}
Event
  /// Emitted when a Pectra withdrawal request is done
  /// @param requester Address of the requester
  /// @param pubKey Validator public key
  /// @param amount Withdrawal amount
  event WithdrawalRequested(address indexed requester, bytes indexed pubKey, uint256 amount);

Validator Consolidations

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.

All source and target validators must be active with a balance greater than 32 ether for the consolidation to succeed. The target validator must be an 0x02 type validator, 0x01 type validators can become 0x02 type through a self consolidation, where the public key is the source and target.

  /// Request validators consolidation with the EIP7251 system contract
  /// @dev all source validators will be consolidated into the target validator
  ///      the caller must compute the fee before calling and send a sufficient msg.value amount
  ///      excess amount will be refunded
  /// @param sourcePubKeys validator public keys to be consolidated
  /// @param targetPubKey target validator public key
  function requestConsolidation(
    bytes[] calldata sourcePubKeys,
    bytes calldata targetPubKey
  ) external payable onlyOwnerOrRoles(CONSOLIDATION_ROLE) {}
Event
  /// Emitted when a Pectra consolidation request is done
  /// @param requester Address of the requester
  /// @param source Source validator public key
  /// @param target Target validator public key
  event ConsolidationRequested(address indexed requester, bytes indexed source, bytes indexed target);

Token Recovery

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.

  /// Recover non-OVM tokens to a recipient
  /// @param nonOVMToken Token to recover
  /// @param recipient Address to receive recovered token
  function recoverFunds(address nonOVMToken, address recipient) external onlyOwnerOrRoles(RECOVER_FUNDS_ROLE) {}
Event
  /// Emitted after tokens are recovered to a recipient
  /// @param nonOVMToken Recovered token (cannot be ETH)
  /// @param recipient Address receiving recovered token
  /// @param amount Amount of recovered token
  event RecoverNonOVMFunds(address indexed nonOVMToken, address indexed recipient, uint256 amount);

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.

Deployments

Chain
Address

Mainnet

Hoodi

Holesky

Sepolia

Chain
Address

Mainnet

Hoodi

Holesky

Sepolia

Chain
Address

Mainnet

Holesky

Sepolia

FAQ

What are Obol Splits?

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.

Are Obol Splits non-custodial?

Obol Validator Managers

What happens if I deposit to an OVM managed validator directly with the Ethereum deposit contract instead of through the dedicated OVM.deposit() method?

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.

What is the principal threshold for?

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.

Can I change the percentages in a split?

Are Obol Splits open source?

Are Obol Splits audited?

Are the Obol Splits contracts verified on Etherscan?

Does my cold wallet have to call the Obol Splits contracts?

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.

Are there any edge cases I should be aware of when using Obol Splits?

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.

Optimistic Withdrawal Recipient

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.

Split Contracts

Further information about splits can be found on the splits.org team's . The addresses of their deployments can be found .

Split Controllers

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.

(Gnosis) SAFE wallet

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.

Obol Validator Manager Factory Deployment

The ObolValidatorManager contract is deployed via a . The factory is deployed at the following addresses on the following chains.

Obol Lido Split Factory Deployment

The ObolLidoSplit contract is deployed via a . The factory is deployed at the following addresses on the following chains.

OWR Factory Deployment

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.

EIP7002
EIP-7002
EIP-7251
​
contract
waterfall contract
​
docs site
here
​
SAFE wallet
​
SAFE
protocol guild
​
factory contract
​
factory contract
​
factory contract
Protocol Guild
here
here
deploy an editable splitter contract
here
here
0xb1E1f5e90f4190F78182A8d5cbed774893Dd1558
0xb633CD420aF83E8A5172e299104842b63dd97ab7
0x119acd7844cbdd5fc09b1c6a4408f490c8f7f522
0x7fec4add6b5ee2b6c1cba232bc6db754794cb6df
0xca78f8fda7ec13ae246e4d4cd38b9ce25a12e64a
Splits.org
released
swapper
​
SAFE
renounceOwnership()
transferOwnership()
Pull Split
splits.org
factory
Optimistic Withdrawal Recipients
FAQ
releases
audited by high quality security teams
here
Obol Validator Manager in Tandem with an Execution Layer Fee recipient splitter contract