diff --git a/docs/int/Overview.md b/docs/int/Overview.md index fea46425b8..6be6a6061a 100644 --- a/docs/int/Overview.md +++ b/docs/int/Overview.md @@ -15,7 +15,7 @@ The Obol Network consists of four core public goods: - The [Distributed Validator Launchpad](../dvl/intro), a [User Interface](https://goerli.launchpad.obol.tech/) for bootstrapping Distributed Validators - [Charon](../charon/intro), a middleware client that enables validators to run in a fault-tolerant, distributed manner -- [Obol Managers](../sc/01_introducing-obol-managers.md), a set of solidity smart contracts for the formation of Distributed Validators +- [Obol Splits](../sc/introducing-obol-splits.md), a set of solidity smart contracts for the distribution of rewards from Distributed Validators - [Obol Testnets](../testnet.md), a set of on-going public incentivized testnets that enable any sized operator to test their deployment before serving for the mainnet Obol Network ### Sustainable Public Goods diff --git a/docs/int/quickstart/group/quickstart-group-leader-creator.md b/docs/int/quickstart/group/quickstart-group-leader-creator.md index 6163d8d9cc..d39af8c2ba 100644 --- a/docs/int/quickstart/group/quickstart-group-leader-creator.md +++ b/docs/int/quickstart/group/quickstart-group-leader-creator.md @@ -146,7 +146,7 @@ You will prepare the configuration file for the distributed key generation cerem - + diff --git a/docs/sc/01_introducing-obol-managers.md b/docs/sc/introducing-obol-splits.md similarity index 52% rename from docs/sc/01_introducing-obol-managers.md rename to docs/sc/introducing-obol-splits.md index 3209b873f5..fb642befa5 100644 --- a/docs/sc/01_introducing-obol-managers.md +++ b/docs/sc/introducing-obol-splits.md @@ -1,13 +1,14 @@ --- +sidebar_position: 1 description: Smart contracts for managing Distributed Validators --- -# Obol Manager Contracts +# Obol Splits Obol develops and maintains a suite of smart contracts for use with Distributed Validators. These contracts include: - Withdrawal Recipients: Contracts used for a validator's withdrawal address. -- Split contracts: Contracts to split ether across multiple entities. Developed by [0xSplits](https://0xsplits.xyz) +- Split contracts: Contracts to split ether across multiple entities. Developed by [Splits.org](https://splits.org) - Split controllers: Contracts that can mutate a splitter's configuration. Two key goals of validator reward management are: @@ -23,58 +24,48 @@ The following sections outline different contracts that can be composed to form Validators have two streams of revenue, the consensus layer rewards and the execution layer rewards. Withdrawal Recipients focus on the former, receiving the balance skimming from a validator with >32 ether in an ongoing manner, and receiving the principal of the validator upon exit. -### Ownable Withdrawal Recipient - -```solidity title="WithdrawalRecipientOwnable.sol" -// SPDX-License-Identifier: MIT - -pragma solidity ^0.8.0; - -import "@openzeppelin/contracts/access/Ownable.sol"; - -contract WithdrawalRecipientOwnable is Ownable { - receive() external payable {} - - function withdraw(address payable recipient) public onlyOwner { - recipient.transfer(address(this).balance); - } -} - -``` - -An Ownable Withdrawal Recipient is the most basic example of a withdrawal recipient contract. It implements Open Zeppelin's `Ownable` interface and allows one address to call the `withdraw()` function, which pulls all ether from the address into the owner's address (or another address specified). This contract does no accounting on the amount of ether that is withdrawn, nor does it differentiate reward from principal. - ### Optimistic Withdrawal Recipient This is the primary withdrawal recipient Obol uses, as it allows for the separation of reward from principal, as well as permitting the ongoing withdrawal of accruing rewards. -An Optimistic Withdrawal Recipient contract takes three inputs when deployed: +An Optimistic Withdrawal Recipient [contract](https://github.com/ObolNetwork/obol-splits/blob/main/src/owr/OptimisticWithdrawalRecipient.sol) takes three inputs when deployed: - 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 it's address since it was last able to do balance accounting is reward from a successful 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). +This contract **assumes that any ether that has appeared in it's 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). :::warning 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 understand and accept this risk**, however minute. -The alternative is to use an 0xSplits waterfall contract, which won't allow the claiming of rewards until all principal ether has been pulled, meaning validators need to be exited for operators to claim their CL rewards. +The alternative is to use an splits.org [waterfall contract](https://docs.splits.org/core/waterfall), 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. ::: This contract fits both design goals and can be used with thousands of validators. If you deploy an Optimistic Withdrawal Recipient with a principal higher than you actually end up using, nothing goes wrong. 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. +#### OWR Factory Deployment + +The OptimisticWithdrawalRecipient contract is deployed via a [factory contract](https://github.com/ObolNetwork/obol-splits/blob/main/src/owr/OptimisticWithdrawalRecipientFactory.sol). The factory is deployed at the following addresses on the following chains. + +| Chain | Address | +|---------|-------------------------------------------------------------------------------------------------------------------------------| +| Mainnet | [0x119acd7844cbdd5fc09b1c6a4408f490c8f7f522](https://etherscan.io/address/0x119acd7844cbdd5fc09b1c6a4408f490c8f7f522) | +| Goerli | [0xe9557FCC055c89515AE9F3A4B1238575Fcd80c26](https://goerli.etherscan.io/address/0xe9557FCC055c89515AE9F3A4B1238575Fcd80c26) | +| Holesky | | +| Sepolia | [0xca78f8fda7ec13ae246e4d4cd38b9ce25a12e64a](https://sepolia.etherscan.io/address/0xca78f8fda7ec13ae246e4d4cd38b9ce25a12e64a) | + ### Exitable Withdrawal Recipient A much awaited feature for proof of stake Ethereum is the ability to trigger the exit of a validator with only the withdrawal address. This is tracked in [EIP-7002](https://eips.ethereum.org/EIPS/eip-7002). Support for this feature will be inheritable in all other withdrawal recipient contracts. This will mitigate the risk to a principal provider of funds being stuck, or a validator being irrecoverably offline. ## Split Contracts -A split, or splitter, is a set of contracts that can divide ether or an ERC20 across a number of addresses. Splits are 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. +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. -Further information about splits can be found on the 0xSplits team's [docs site](https://docs.0xsplits.xyz/). +Further information about splits can be found on the splits.org team's [docs site](https://docs.splits.org/). The addresses of their deployments can be found [here](https://docs.splits.org/core/split#addresses). ## Split Controllers @@ -86,4 +77,13 @@ A [SAFE](https://safe.global/) is a common method to administrate a mutable spli ### Immutable Split Controller -This is a contract that updates one split configuration with another, exactly once. Only a permissioned address can trigger the change. This contract is suitable for changing a split at an unknown point in future to a configuration pre-defined at deployment. +This is a [contract](https://github.com/ObolNetwork/obol-splits/blob/main/src/controllers/ImmutableSplitController.sol) that updates one split configuration with another, exactly once. Only a permissioned address can trigger the change. This contract is suitable for changing a split at an unknown point in future to a configuration pre-defined at deployment. + +The Immutable Split Controller [factory contract](https://github.com/ObolNetwork/obol-splits/blob/main/src/controllers/ImmutableSplitControllerFactory.sol) can be found at the following addresses: + +| Chain | Address | +|---------|-------------------------------------------------------------------------------------------------------------------------------| +| Mainnet | | +| Goerli | [0x64a2c4A50B1f46c3e2bF753CFe270ceB18b5e18f](https://goerli.etherscan.io/address/0x64a2c4A50B1f46c3e2bF753CFe270ceB18b5e18f) | +| Holesky | | +| Sepolia | | \ No newline at end of file diff --git a/docs/sec/ev-assessment.md b/docs/sec/ev-assessment.md index 1c63b2bc48..429c3f1ffa 100644 --- a/docs/sec/ev-assessment.md +++ b/docs/sec/ev-assessment.md @@ -66,7 +66,7 @@ Obol’s product consists of three main components, each run by its own team: a - [DV Launchpad](../dvl/intro.md): A webapp to create and manage distributed validators. - [Charon](../charon/intro.md): A middleware client that enables operators to run distributed validators. -- [Solidity](../sc/01_introducing-obol-managers.md): Withdrawal and fee recipient contracts for use with distributed validators. +- [Solidity](../sc/introducing-obol-splits.md): Withdrawal and fee recipient contracts for use with distributed validators. ## Analysis - Cluster Setup and DKG diff --git a/docs/sec/overview.md b/docs/sec/overview.md index 09cf2afa20..17a81c9cc5 100644 --- a/docs/sec/overview.md +++ b/docs/sec/overview.md @@ -23,7 +23,7 @@ The completed audits reports are linked [here](https://github.com/ObolNetwork/ob - A [security assessment](https://github.com/ObolNetwork/obol-security/blob/f9d7b0ad0bb8897f74ccb34cd4bd83012ad1d2b5/audits/Sigma_Prime_Obol_Network_Charon_Security_Assessment_Report_v2_1.pdf) of Charon by [Sigma Prime](https://sigmaprime.io/). -- A [solidity audit](./smart_contract_audit) of the Obol Manager Contracts by [Zach Obront](https://zachobront.com/). +- A [solidity audit](./smart_contract_audit) of the Obol Splits contracts by [Zach Obront](https://zachobront.com/). - A second audit of Charon is planned for Q4 2023.