diff --git a/common b/common index 41353b629..26d3a5b49 160000 --- a/common +++ b/common @@ -1 +1 @@ -Subproject commit 41353b629cc037d1c949cd6992fb90f8ed957977 +Subproject commit 26d3a5b497a6f672d346da94b817753dc1622cc1 diff --git a/docs/Concepts/Withdrawals.md b/docs/Concepts/Withdrawals.md new file mode 100644 index 000000000..b63d706d3 --- /dev/null +++ b/docs/Concepts/Withdrawals.md @@ -0,0 +1,70 @@ +--- +description: Describe withdrawals +--- + +# Withdrawals + +Validators staking ether on Mainnet after [The Merge](Merge.md), accrue 2 forms of rewards: + +- Execution layer rewards paid directly to a withdrawal address (Ethereum address). +- Consensus layer rewards for performing actions each epoch. + +The [Capella network upgrade](https://notes.ethereum.org/@launchpad/withdrawals-faq#Q-What-is-ShanghaiCapella) +implements an automated process that allows a validator's rewards to be transferred +from the consensus layer to an Ethereum address on the execution layer. Before the Capella +upgrade, consensus layer rewards were locked, and unable to be transferred to an Ethereum address. + +!!! important + + When you create a validator, it's possible to set its withdrawal address to a + [BLS address](https://en.wikipedia.org/wiki/BLS_digital_signature), or an Ethereum address. Withdrawal + keys that are configured as BLS keys cannot have automated withdrawals executed for them. + + You can [update your BLS withdrawal address to an Ethereum address](../HowTo/Withdrawal-Keys.md) + after the Capella upgrade. + +You do not pay gas fees for receiving reward payments. + +## Types of withdrawals + +Two types of automated withdrawals occur once the withdrawal key is set up as an Ethereum address: +[partial withdrawals](#partial-withdrawals) and [full withdrawals](#full-withdrawals). + +### Partial withdrawals + +Partial withdrawals are for active validators that have a balance exceeding 32 ETH. +The network periodically makes transfers to the associated Ethereum address for validators with a balance +exceeding 32 ETH. This means that a validator's balance will periodically reduce to 32 ETH once Capella +becomes the active fork on the network. + +### Full withdrawals + +Full withdrawals are for validators that have exited the network, and have waited the necessary time to withdraw their funds. +For these validators, their entire balance is returned to the Ethereum address associated with the validator key. +The balance cannot be transferred until the validator key is associated with an Ethereum address. + +An exited validator cannot become active on the network again, and currently (as of Capella), +there is no mechanism for recycling the validator ID that has been exited. + +## How it works + +From the first Capella slot, block proposers provide up to 16 withdrawals per proposed block. + +Proposers start from validator 1, and find validators that qualify: must have an Ethereum address as +a withdrawal address, must have an excess balance, or have exited. + +Block proposers select the withdrawals that go into the block. In each block, up to 16 changes to withdrawal +credentials are also allowed, where an owner of a validator key can +[update their withdrawal key's Ethereum address](../HowTo/Withdrawal-Keys.md). This update is retrieved from +a pool, and the order is not guaranteed. + +## Withdrawal keys + +Withdrawal keys that are configured as [BLS keys](https://en.wikipedia.org/wiki/BLS_digital_signature) +cannot have automated withdrawals executed for them. Users must alter their credentials to specify an +Ethereum address for their withdrawal key. + +BLS withdrawal keys are prefixed with `0x00`, whereas Ethereum withdrawal keys are prefixed with a `0x01`. + +To determine the type of withdrawal key used by your validator, you can +[query your validator configuration onchain](../HowTo/Withdrawal-Keys.md#determine-the-withdrawal-key-type). diff --git a/docs/HowTo/Withdrawal-Keys.md b/docs/HowTo/Withdrawal-Keys.md new file mode 100644 index 000000000..3cbb4ce5d --- /dev/null +++ b/docs/HowTo/Withdrawal-Keys.md @@ -0,0 +1,86 @@ +--- +title: How to update your withdrawal credentials +--- + +# Update your withdrawal credentials + +When you create a validator, it’s possible to set its [withdrawal](../Concepts/Withdrawals.md) address +to a BLS address, or an Ethereum address. + +You can update your BLS withdrawal address to an Ethereum address after the Capella upgrade. + +## Determine the withdrawal address type + +**Prerequisites**: + +- Access to the beacon node API endpoint. By default this is `localhost:5051` +- Install [`curl`](https://curl.se/) and [`jq`](https://stedolan.github.io/jq/) + +The following shell script allows you to determine the withdrawal address of a given validator ID. + +=== "Script" + + ```bash + VALIDATOR= \ + curl http://localhost:5051/eth/v1/beacon/states/finalized/validators/$VALIDATOR | jq '.data | .validator.withdrawal_credentials' + ``` + +=== "Example output" + + ``` + "0x00fc40352b0a186d83267fc1342ec5da49dbb78e1099a4bd8db16d2c0d223594" + ``` + +In the script, specify the `` (for example `1`) that was provided when you joined the network. Alternatively +you can specify the validator's public key. + +In the output, the first 4 characters of the string, in this case `0x00`, indicates the key is a BLS withdrawal +key. + +## Update your withdrawal address + +### From a BLS withdrawal address to an Ethereum address + +!!! important + + Teku does not offer functionality to create a signed withdrawal credential change. + Tools such as [`ethdo`](https://github.com/wealdtech/ethdo/blob/master/docs/changingwithdrawalcredentials.md) + allow you to generate this signed message, which can be submitted directly to your beacon node if + your REST API is active. + +If your withdrawal address is a BLS key (starts with `0x00`), the Capella fork provides a process to +update your withdrawal address to a `0x01` withdrawal key (Ethereum address). +You must have the BLS withdrawal address private key, or the seed phrase (mnemonic) to sign the request +to prove that you have access to the BLS withdrawal key. + +Tools such as [ethdo](https://github.com/wealdtech/ethdo/blob/master/docs/changingwithdrawalcredentials.md) are able to sign the request correctly, +and the signed data can be submitted directly, or via your own beacon node. + +!!! important "Important information about changing withdrawal credentials" + + - Once a validator has been updated to use a `0x01` withdrawal key (Ethereum address), it cannot be changed again. + - Updating your withdrawal credentials is not available until the Capella fork is active. + - Ensure you update to the expected Ethereum address because the change is permanent. + +A maximum of 16 validator keys can update their withdrawal credentials per block, so the process may +be congested initially. If you submit a request to update your key, and it hasn't been done in a period +of time, you might consider re-submitting the request. It may take several epochs for the change to be +included in a block, depending on the number of requests in the queue. + +Query the [`bls_to_execution_changes`](https://consensys.github.io/teku/#tag/Beacon/operation/getBlsToExecutionChanges) +API see if your request is still in the pool. + +### Update your Ethereum address + +If your withdrawal credentials are set to an Ethereum address, and you wish to update it to a +different address, you'll need to create a new validator key. You can exit your current +validator key as a voluntary exit, and use the funds from the full withdrawal of that to create the +new validator key. + +The voluntary exit process takes while to complete, and the exiting validator must remain active during that +time to avoid inactivity penalties. + +!!! important + + Ensure that you own the current Ethereum address before exiting, otherwise you + will be unable to access your funds. diff --git a/mkdocs.yml b/mkdocs.yml index 18fd417ae..7f3761353 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -85,6 +85,7 @@ nav: - Prepare for The Merge: HowTo/Prepare-for-The-Merge.md - Reconstruct Historical States Service: HowTo/Reconstruct-Historical-States-Service.md - Use sentry beacon nodes: HowTo/Sentry-Nodes.md + - Update withdrawal keys: HowTo/Withdrawal-Keys.md - Troubleshoot: - Solve common problems: HowTo/Troubleshoot/Troubleshooting.md - Concepts: @@ -95,6 +96,7 @@ nav: - Node private key: Concepts/P2P-Private-Key.md - Slashing protection: Concepts/Slashing-Protection.md - Weak subjectivity: Concepts/Weak-Subjectivity.md + - Withdrawals: Concepts/Withdrawals.md - Tutorials: - External signer TLS: Tutorials/Configure-External-Signer-TLS.md - Reference: