From 06cb862615f8a27eb538f8a1583837dc95203004 Mon Sep 17 00:00:00 2001 From: Paul Harris Date: Tue, 6 Dec 2022 12:21:40 +1000 Subject: [PATCH 01/15] Drafted a document for withdrawals for capella Hopefully this is a good start for documenting the capella upgrade and what users need to know. I referenced ethdo, which is a tool we don't maintain, but it's also the only tool i know of at the moment that has this functionality... The capella upgrade is not set to release on a specific date yet, but this kind of concept document will start being useful very soon. ref. https://github.com/ConsenSys/teku/issues/5680 and https://github.com/ConsenSys/teku/issues/6482 --- docs/HowTo/Withdrawals.md | 133 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 docs/HowTo/Withdrawals.md diff --git a/docs/HowTo/Withdrawals.md b/docs/HowTo/Withdrawals.md new file mode 100644 index 000000000..3231af5c4 --- /dev/null +++ b/docs/HowTo/Withdrawals.md @@ -0,0 +1,133 @@ +# Withdrawals + +## Overview +Validators who stake ether on mainnet, as of the `Bellatrix` upgrade, accrue 2 forms of reward: +- EL (Execution-layer) rewards payed directly to an eth1address for block inclusion +- CL (Consensus-layer) rewards for performing actions each epoch, to the CL validator balance. + +Prior to the Capella upgrade, the balances of Consensus-layer validator keys was locked away, and not able to be transferred back to an `eth1Address` (ethereum address). + +The Capella upgrade implements an automated process which allows the funds of validator keys to be deposited to an `eth1Address`. + +## Types of withdrawal +There are two types of withdrawals, and both are automated and require no user interaction once the withdrawal key has been setup as an `eth1Address`. + +### Partial Withdrawals +_Partial withdrawals_ concern validators who are active on the network and have a balance exceeding 32ETH. +Periodically, a deposit will be made to the associated `eth1Address` for any balance exceeding 32ETH +associated with the validator key. This means that a validators balance will periodically reduce to +32ETH once capella becomes the active fork on the network. + +### Full Withdrawals +_Full withdrawals_ concern validators who are exited from the network, and have waited the nessesary time to be withdrawable. +For these validators, their entire balance is returned to the `eth1Address` associated with the validator key. +The balance cannot be transferred until the validator key is associated with an `eth1Address`. + +Once a validator is exited, it will not 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 +Starting from the first capella slot, block proposers will start providing up to 16 withdrawals per block proposed. + +Proposers will start from validator 1, and find validators that qualify (must have an `eth1Address`, must have an excess balance or be exited). +On mainnet, with 32 slots per epoch, this equates to 512 withdrawals per epoch if all slots are producing blocks. + +Block proposers need to select the withdrawals that go into the block in a predictable mechanism to be able to follow the chain correctly. + +Each block, up to 16 changes to withdrawal credentials are also allowed, where an owner of a validator key is able to update their +withdrawal key to an `eth1Address`. This change is taken from a pool, and the order is not guaranteed, it will depend on a number of factors. + +## Withdrawal Keys +There are two types of withdrawal keys that a validator may have been configured with when they were setup. + +It has been possible to setup a validator key that has a withdrawal address of an `eth1Address` for a while now, +and many users may find that their validator key is already configured with an `eth1Address` +for the withdrawal key. The withdrawal keys that are configured in this way are prefixed with a `0x01` code. + +BLS Keys are prefixed by `0x00`. These keys are not able to have automated withdrawals run on them. +If the owner of the validator key wishes to get rewards from a validator key that has `0x00` withdrawal credentials, +they need to alter their credentials to specify an eth1 address for their withdrawal key. + +To determine the type of withdrawal key in use by your validator, if you are unsure, +it is possible to query your validator configuration on chain. The following script will allow +you to determine the withdrawal key of a given validator id. + +__NOTE__ + - This query runs against the beacon-api on your localhost:5051, so would require that to be accessible. + - Change `VALIDATOR` to the validator index to query + - Requires `curl` and `jq` to be installed and in the path. +``` + VALIDATOR=1 \ + curl http://localhost:5051/eth/v1/beacon/states/finalized/validators?id=$VALIDATOR \ + |jq '.data | .[] | .validator.withdrawal_credentials' +``` +This will output a string like: +``` +"0x00fc40352b0a186d83267fc1342ec5da49dbb78e1099a4bd8db16d2c0d223594" +``` +The first 4 characters of the string, in this case `0x00`, indicate that a BLS withdrawal key is in use by validator 1 on the network (goerli in this example). + +## Updating Withdrawal keys + +If your withdrawal address is a BLS key (starts with `0x00`), the Capella fork comes with +a process to allow you to update your withdrawal address to a `0x01` withdrawal key. +This will require either your withdrawal key or the seed phrase (mnemonic) of your withdrawal key, +in order to sign the request to prove that you have access to the BLS Withdrawal key. + +Because of the requirement for access to the withdrawal key for signing, Teku does not offer a utility to generate a signed request. + +Tools such as [ethdo](https://github.com/wealdtech/ethdo) are able to sign the request correctly, +and the signed data can be submitted directly, or via your own beacon node. + +Per block, 16 validator keys can update withdrawal credentials, 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. + +__NOTE__ +- Once a validator has been updated to use a `0x01` withdrawal key, it cannot be changed again. +- Submitting a change to withdrawal credentials is not available until the capella fork is active. +- Users should ensure that they are updating to the expected `eth1Address`, as this change is permanent. +- The address will get funds directly deposited for 0 gas, but as part of that transaction no EVM code will be executed. + +## Frequently asked questions +___ + +_Question:_ What type of withdrawal key is in use by my validator? + +_Answer:_ [Withdrawal-keys] details how you might look at your current validator setup to check your withdrawal key. +____ + +_Question:_ I've updated my BLS withdrawal key to an `eth1Address`, can I choose how often i get deposits? + +_Answer:_ The process is automated and block proposers are required to add deposits when it is your turn, +there is no way to delay them once your `eth1Address` has been setup. + +---- + +_Question:_ I've set my `eth1Address` to the wrong thing, what now? + +_Answer:_ There is no way to update it a second time to a different address, your change is permanent once it's been made, +and that `eth1Address` will permanently receive funds from that validator key. + +____ + +_Question:_ I believe my key has been compromised, and need to get my withdrawal credentials updated as soon as possible. + +_Answer:_ Try to get in as early as possible submitting your bls_to_withdrawal change, as if your key has been +compromised and the other party manages to update first, they will permanently get all withdrawals. +____ + +_Question:_ I've submitted a request to change my withdrawal key to an `eth1Address`, and it was accepted, but it's been a while, and my credentials haven't been updated yet. + +_Answer:_ You could query the pool of your beacon-node and see if your request is still in the pool - `/eth/v1/beacon/pool/bls_to_execution_changes`. +If the request is still in that pool, then you still have a good chance of your previous request being processed. If it is not in the queue, you can re-submit the same signed +change you submitted earlier. +---- +_Question:_ My validator key is associated to an `eth1Address` I own, and it's all working, but I need to now change +the `eth1Address` where the funds are being deposited, due to change of circumstance. How do I do that? + +_Answer:_ To change `eth1Address` you will 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. +Please note that the voluntary exit process does take time, and the exiting validator should remain active during that time to avoid inactivity penalties. +---- + From 2d11f804bec9c7f046c612fc1df42d7e6b125ae5 Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Tue, 10 Jan 2023 18:52:40 +1000 Subject: [PATCH 02/15] First pass on editing the content. Signed-off-by: bgravenorst --- docs/HowTo/Withdrawals.md | 87 ++++++++++++++++++++++----------------- 1 file changed, 50 insertions(+), 37 deletions(-) diff --git a/docs/HowTo/Withdrawals.md b/docs/HowTo/Withdrawals.md index 3231af5c4..6fab256aa 100644 --- a/docs/HowTo/Withdrawals.md +++ b/docs/HowTo/Withdrawals.md @@ -1,56 +1,69 @@ # Withdrawals -## Overview -Validators who stake ether on mainnet, as of the `Bellatrix` upgrade, accrue 2 forms of reward: -- EL (Execution-layer) rewards payed directly to an eth1address for block inclusion -- CL (Consensus-layer) rewards for performing actions each epoch, to the CL validator balance. +Validators staking ether on Mainnet after The Merge, accrue 2 forms of rewards: -Prior to the Capella upgrade, the balances of Consensus-layer validator keys was locked away, and not able to be transferred back to an `eth1Address` (ethereum address). +- Execution layer rewards payed directly to an Ethereum address. +- Consensus layer rewards for performing actions each epoch. -The Capella upgrade implements an automated process which allows the funds of validator keys to be deposited to an `eth1Address`. +Before the Capella upgrade, consensus layer rewards were locked away, and +unable to be transferred to an Ethereum address. The Capella upgrade implements an automated +process that allows a validator's funds to be deposited to an Ethereum address. -## Types of withdrawal -There are two types of withdrawals, and both are automated and require no user interaction once the withdrawal key has been setup as an `eth1Address`. +!!! note + + Teku provides multiple methods to allow you to + [specify an Ethereum address to store your validator's rewards](Prepare-for-The-Merge.md#configure-the-fee-recipient). + +## Types of withdrawals + +There are two types of automated withdrawals that occur once the +[withdrawal key is set up as an Ethereum address](Prepare-for-The-Merge.md#configure-the-fee-recipient). ### Partial Withdrawals -_Partial withdrawals_ concern validators who are active on the network and have a balance exceeding 32ETH. -Periodically, a deposit will be made to the associated `eth1Address` for any balance exceeding 32ETH -associated with the validator key. This means that a validators balance will periodically reduce to -32ETH once capella becomes the active fork on the network. + +Partial withdrawals are for active validators that have a balance exceeding 32 ETH. +The network periodically makes deposits 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_ concern validators who are exited from the network, and have waited the nessesary time to be withdrawable. -For these validators, their entire balance is returned to the `eth1Address` associated with the validator key. -The balance cannot be transferred until the validator key is associated with an `eth1Address`. -Once a validator is exited, it will not become active on the network again, and currently (as of capella) there is no mechanism -for recycling the validator id that has been exited. +Full withdrawals are for validators that have exited the network, and have waited the nessesary 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 -Starting from the first capella slot, block proposers will start providing up to 16 withdrawals per block proposed. -Proposers will start from validator 1, and find validators that qualify (must have an `eth1Address`, must have an excess balance or be exited). -On mainnet, with 32 slots per epoch, this equates to 512 withdrawals per epoch if all slots are producing blocks. +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, must +have an excess balance, or have exited. On Mainnet, with 32 slots per epoch, this equates to 512 withdrawals +per epoch if all slots are producing blocks. + +Block proposers select the withdrawals that go into the block using a predictable mechanism to follow +the chain correctly. + +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. This change is taken from a pool, and +the order is not guaranteed. -Block proposers need to select the withdrawals that go into the block in a predictable mechanism to be able to follow the chain correctly. +## Withdrawal keys -Each block, up to 16 changes to withdrawal credentials are also allowed, where an owner of a validator key is able to update their -withdrawal key to an `eth1Address`. This change is taken from a pool, and the order is not guaranteed, it will depend on a number of factors. +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 +ETH1 address for their withdrawal key. -## Withdrawal Keys -There are two types of withdrawal keys that a validator may have been configured with when they were setup. +BLS withdrawal keys are prefixed with `0x00`, whereas ETH1 withdrawal keys are prefixed with a `0x01`. -It has been possible to setup a validator key that has a withdrawal address of an `eth1Address` for a while now, -and many users may find that their validator key is already configured with an `eth1Address` -for the withdrawal key. The withdrawal keys that are configured in this way are prefixed with a `0x01` code. +To determine the type of withdrawal key used by your validator, you can query your validator configuration +onchain. -BLS Keys are prefixed by `0x00`. These keys are not able to have automated withdrawals run on them. -If the owner of the validator key wishes to get rewards from a validator key that has `0x00` withdrawal credentials, -they need to alter their credentials to specify an eth1 address for their withdrawal key. +### Determine the withdrawal key type -To determine the type of withdrawal key in use by your validator, if you are unsure, -it is possible to query your validator configuration on chain. The following script will allow -you to determine the withdrawal key of a given validator id. +The following script allows you to determine the withdrawal key of a given validator ID. __NOTE__ - This query runs against the beacon-api on your localhost:5051, so would require that to be accessible. @@ -67,7 +80,7 @@ This will output a string like: ``` The first 4 characters of the string, in this case `0x00`, indicate that a BLS withdrawal key is in use by validator 1 on the network (goerli in this example). -## Updating Withdrawal keys +### Update your withdrawal key If your withdrawal address is a BLS key (starts with `0x00`), the Capella fork comes with a process to allow you to update your withdrawal address to a `0x01` withdrawal key. @@ -76,10 +89,10 @@ in order to sign the request to prove that you have access to the BLS Withdrawal Because of the requirement for access to the withdrawal key for signing, Teku does not offer a utility to generate a signed request. -Tools such as [ethdo](https://github.com/wealdtech/ethdo) are able to sign the request correctly, +Tools such as [ethdo](https://github.com/wealdtech/ethdo) are able to sign the request correctly, and the signed data can be submitted directly, or via your own beacon node. -Per block, 16 validator keys can update withdrawal credentials, so the process may be congested initially. +Per block, 16 validator keys can update withdrawal credentials, 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. From c0527fe70333eed1436f800c7b83d7e37ed042eb Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Tue, 17 Jan 2023 08:51:20 +1000 Subject: [PATCH 03/15] Additional edits and structural changes. Signed-off-by: bgravenorst --- docs/Concepts/Withdrawals.md | 68 ++++++++++++++++ docs/HowTo/Withdrawal-Keys.md | 85 ++++++++++++++++++++ docs/HowTo/Withdrawals.md | 146 ---------------------------------- mkdocs.yml | 2 + 4 files changed, 155 insertions(+), 146 deletions(-) create mode 100644 docs/Concepts/Withdrawals.md create mode 100644 docs/HowTo/Withdrawal-Keys.md delete mode 100644 docs/HowTo/Withdrawals.md diff --git a/docs/Concepts/Withdrawals.md b/docs/Concepts/Withdrawals.md new file mode 100644 index 000000000..6cab31918 --- /dev/null +++ b/docs/Concepts/Withdrawals.md @@ -0,0 +1,68 @@ +--- +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 upgrade 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 currently possible to set its withdrawal address to a + [BLS address](https://en.wikipedia.org/wiki/BLS_digital_signature), or an Ethereum address. After + the Capella fork, users must use an Ethereum address as their withdrawal address to allow automatics + transfers. + + You can [update your BLS withdrawal address to an Ethereum address](../HowTo/Withdrawal-Keys.md). + +## Types of withdrawals + +There are two types of automated withdrawals that 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, 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 ETH1 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..971c50169 --- /dev/null +++ b/docs/HowTo/Withdrawal-Keys.md @@ -0,0 +1,85 @@ +--- +title: How to update your withdrawal credentials +--- + +# Update your withdrawal credentials + +When you create a validator, it’s currently possible to set its [withdrawal](../Concepts/Withdrawals.md) address +to a BLS address, or an Ethereum address. After the Capella fork, users must use an Ethereum address as their withdrawal +address to allow automatics transfers. + +## 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 update your withdrawal key from a BLS withdrawal address to + an Ethereum address. Use a tool like [`ethdo`](https://github.com/wealdtech/ethdo/blob/master/docs/changingwithdrawalcredentials.md) + instead. + +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. + - The updated address will receive a direct deposited for 0 gas, but no EVM code will be executed + as part of the transaction. + +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 + +To update an Ethereum 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, or have access to the current Ethereum address before exiting, otherwise you + will be unable to access your funds. diff --git a/docs/HowTo/Withdrawals.md b/docs/HowTo/Withdrawals.md deleted file mode 100644 index 6fab256aa..000000000 --- a/docs/HowTo/Withdrawals.md +++ /dev/null @@ -1,146 +0,0 @@ -# Withdrawals - -Validators staking ether on Mainnet after The Merge, accrue 2 forms of rewards: - -- Execution layer rewards payed directly to an Ethereum address. -- Consensus layer rewards for performing actions each epoch. - -Before the Capella upgrade, consensus layer rewards were locked away, and -unable to be transferred to an Ethereum address. The Capella upgrade implements an automated -process that allows a validator's funds to be deposited to an Ethereum address. - -!!! note - - Teku provides multiple methods to allow you to - [specify an Ethereum address to store your validator's rewards](Prepare-for-The-Merge.md#configure-the-fee-recipient). - -## Types of withdrawals - -There are two types of automated withdrawals that occur once the -[withdrawal key is set up as an Ethereum address](Prepare-for-The-Merge.md#configure-the-fee-recipient). - -### Partial Withdrawals - -Partial withdrawals are for active validators that have a balance exceeding 32 ETH. -The network periodically makes deposits 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 nessesary 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, must -have an excess balance, or have exited. On Mainnet, with 32 slots per epoch, this equates to 512 withdrawals -per epoch if all slots are producing blocks. - -Block proposers select the withdrawals that go into the block using a predictable mechanism to follow -the chain correctly. - -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. This change is taken 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 -ETH1 address for their withdrawal key. - -BLS withdrawal keys are prefixed with `0x00`, whereas ETH1 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. - -### Determine the withdrawal key type - -The following script allows you to determine the withdrawal key of a given validator ID. - -__NOTE__ - - This query runs against the beacon-api on your localhost:5051, so would require that to be accessible. - - Change `VALIDATOR` to the validator index to query - - Requires `curl` and `jq` to be installed and in the path. -``` - VALIDATOR=1 \ - curl http://localhost:5051/eth/v1/beacon/states/finalized/validators?id=$VALIDATOR \ - |jq '.data | .[] | .validator.withdrawal_credentials' -``` -This will output a string like: -``` -"0x00fc40352b0a186d83267fc1342ec5da49dbb78e1099a4bd8db16d2c0d223594" -``` -The first 4 characters of the string, in this case `0x00`, indicate that a BLS withdrawal key is in use by validator 1 on the network (goerli in this example). - -### Update your withdrawal key - -If your withdrawal address is a BLS key (starts with `0x00`), the Capella fork comes with -a process to allow you to update your withdrawal address to a `0x01` withdrawal key. -This will require either your withdrawal key or the seed phrase (mnemonic) of your withdrawal key, -in order to sign the request to prove that you have access to the BLS Withdrawal key. - -Because of the requirement for access to the withdrawal key for signing, Teku does not offer a utility to generate a signed request. - -Tools such as [ethdo](https://github.com/wealdtech/ethdo) are able to sign the request correctly, -and the signed data can be submitted directly, or via your own beacon node. - -Per block, 16 validator keys can update withdrawal credentials, 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. - -__NOTE__ -- Once a validator has been updated to use a `0x01` withdrawal key, it cannot be changed again. -- Submitting a change to withdrawal credentials is not available until the capella fork is active. -- Users should ensure that they are updating to the expected `eth1Address`, as this change is permanent. -- The address will get funds directly deposited for 0 gas, but as part of that transaction no EVM code will be executed. - -## Frequently asked questions -___ - -_Question:_ What type of withdrawal key is in use by my validator? - -_Answer:_ [Withdrawal-keys] details how you might look at your current validator setup to check your withdrawal key. -____ - -_Question:_ I've updated my BLS withdrawal key to an `eth1Address`, can I choose how often i get deposits? - -_Answer:_ The process is automated and block proposers are required to add deposits when it is your turn, -there is no way to delay them once your `eth1Address` has been setup. - ----- - -_Question:_ I've set my `eth1Address` to the wrong thing, what now? - -_Answer:_ There is no way to update it a second time to a different address, your change is permanent once it's been made, -and that `eth1Address` will permanently receive funds from that validator key. - -____ - -_Question:_ I believe my key has been compromised, and need to get my withdrawal credentials updated as soon as possible. - -_Answer:_ Try to get in as early as possible submitting your bls_to_withdrawal change, as if your key has been -compromised and the other party manages to update first, they will permanently get all withdrawals. -____ - -_Question:_ I've submitted a request to change my withdrawal key to an `eth1Address`, and it was accepted, but it's been a while, and my credentials haven't been updated yet. - -_Answer:_ You could query the pool of your beacon-node and see if your request is still in the pool - `/eth/v1/beacon/pool/bls_to_execution_changes`. -If the request is still in that pool, then you still have a good chance of your previous request being processed. If it is not in the queue, you can re-submit the same signed -change you submitted earlier. ----- -_Question:_ My validator key is associated to an `eth1Address` I own, and it's all working, but I need to now change -the `eth1Address` where the funds are being deposited, due to change of circumstance. How do I do that? - -_Answer:_ To change `eth1Address` you will 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. -Please note that the voluntary exit process does take time, and the exiting validator should remain active during that time to avoid inactivity penalties. ----- - diff --git a/mkdocs.yml b/mkdocs.yml index 53bd06a8b..2206cf057 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -83,6 +83,7 @@ nav: - Migrate database: HowTo/Migrate-Database.md - Prepare for The Merge: HowTo/Prepare-for-The-Merge.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: @@ -93,6 +94,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: From 419e8bcf4ecc00a4c8db0376bda5aebd05c6d042 Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Wed, 18 Jan 2023 06:46:18 +1000 Subject: [PATCH 04/15] Fix vale issues. Signed-off-by: bgravenorst --- common | 2 +- docs/Concepts/Withdrawals.md | 5 ++--- docs/HowTo/Withdrawal-Keys.md | 2 +- 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/common b/common index 41353b629..cb6d6f332 160000 --- a/common +++ b/common @@ -1 +1 @@ -Subproject commit 41353b629cc037d1c949cd6992fb90f8ed957977 +Subproject commit cb6d6f332ec31a8c87b93418aae86b25bc00370e diff --git a/docs/Concepts/Withdrawals.md b/docs/Concepts/Withdrawals.md index 6cab31918..6f4ee076e 100644 --- a/docs/Concepts/Withdrawals.md +++ b/docs/Concepts/Withdrawals.md @@ -24,9 +24,8 @@ upgrade, consensus layer rewards were locked, and unable to be transferred to an ## Types of withdrawals -There are two types of automated withdrawals that occur once the -withdrawal key is set up as an Ethereum address: [partial withdrawals](#partial-withdrawals) and -[full withdrawals](#full-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 diff --git a/docs/HowTo/Withdrawal-Keys.md b/docs/HowTo/Withdrawal-Keys.md index 971c50169..4c817772a 100644 --- a/docs/HowTo/Withdrawal-Keys.md +++ b/docs/HowTo/Withdrawal-Keys.md @@ -24,7 +24,7 @@ The following shell script allows you to determine the withdrawal address of a g curl http://localhost:5051/eth/v1/beacon/states/finalized/validators/$VALIDATOR | jq '.data | .validator.withdrawal_credentials' ``` -=== "Example output +=== "Example output" ``` "0x00fc40352b0a186d83267fc1342ec5da49dbb78e1099a4bd8db16d2c0d223594" From 5fca7761286914d52cce625609a6a82e5689e1aa Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Wed, 18 Jan 2023 07:21:36 +1000 Subject: [PATCH 05/15] updating submodule to latest --- common | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/common b/common index cb6d6f332..41353b629 160000 --- a/common +++ b/common @@ -1 +1 @@ -Subproject commit cb6d6f332ec31a8c87b93418aae86b25bc00370e +Subproject commit 41353b629cc037d1c949cd6992fb90f8ed957977 From 083c54491e28c3894429b9d8df329a5165ef502f Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Wed, 18 Jan 2023 07:29:17 +1000 Subject: [PATCH 06/15] Update common folder. Signed-off-by: bgravenorst --- common | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/common b/common index 41353b629..25575bfda 160000 --- a/common +++ b/common @@ -1 +1 @@ -Subproject commit 41353b629cc037d1c949cd6992fb90f8ed957977 +Subproject commit 25575bfda9c05411a0215173133c84a9e8437e08 From 801060a2e121a6dfdba6e18d60995797fcd0cea5 Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Wed, 25 Jan 2023 11:49:55 +1000 Subject: [PATCH 07/15] updating submodule to latest --- common | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/common b/common index 25575bfda..41353b629 160000 --- a/common +++ b/common @@ -1 +1 @@ -Subproject commit 25575bfda9c05411a0215173133c84a9e8437e08 +Subproject commit 41353b629cc037d1c949cd6992fb90f8ed957977 From f5a0382a4f17ff882d1a15ade9275295d7df7099 Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Wed, 25 Jan 2023 12:12:47 +1000 Subject: [PATCH 08/15] updating submodule to latest --- common | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/common b/common index 41353b629..26d3a5b49 160000 --- a/common +++ b/common @@ -1 +1 @@ -Subproject commit 41353b629cc037d1c949cd6992fb90f8ed957977 +Subproject commit 26d3a5b497a6f672d346da94b817753dc1622cc1 From 81ef051c712356cb3945ca37238cd337f84e4d91 Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Wed, 25 Jan 2023 12:42:21 +1000 Subject: [PATCH 09/15] Address reviewer feedback. Signed-off-by: bgravenorst --- docs/Concepts/Withdrawals.md | 9 +++++---- docs/HowTo/Withdrawal-Keys.md | 11 +++++------ 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/Concepts/Withdrawals.md b/docs/Concepts/Withdrawals.md index 6f4ee076e..8b8ad4751 100644 --- a/docs/Concepts/Withdrawals.md +++ b/docs/Concepts/Withdrawals.md @@ -16,11 +16,12 @@ upgrade, consensus layer rewards were locked, and unable to be transferred to an !!! important When you create a validator, it's currently possible to set its withdrawal address to a - [BLS address](https://en.wikipedia.org/wiki/BLS_digital_signature), or an Ethereum address. After - the Capella fork, users must use an Ethereum address as their withdrawal address to allow automatics - transfers. + [BLS address](https://en.wikipedia.org/wiki/BLS_digital_signature), or an Ethereum address. - You can [update your BLS withdrawal address to an Ethereum address](../HowTo/Withdrawal-Keys.md). + 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 diff --git a/docs/HowTo/Withdrawal-Keys.md b/docs/HowTo/Withdrawal-Keys.md index 4c817772a..f3ce6cae9 100644 --- a/docs/HowTo/Withdrawal-Keys.md +++ b/docs/HowTo/Withdrawal-Keys.md @@ -42,9 +42,10 @@ key. !!! important - Teku does not offer functionality to update your withdrawal key from a BLS withdrawal address to - an Ethereum address. Use a tool like [`ethdo`](https://github.com/wealdtech/ethdo/blob/master/docs/changingwithdrawalcredentials.md) - instead. + 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). @@ -59,8 +60,6 @@ and the signed data can be submitted directly, or via your own beacon node. - 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. - - The updated address will receive a direct deposited for 0 gas, but no EVM code will be executed - as part of the transaction. 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 @@ -81,5 +80,5 @@ time to avoid inactivity penalties. !!! important - Ensure that you own, or have access to the current Ethereum address before exiting, otherwise you + Ensure that you own the current Ethereum address before exiting, otherwise you will be unable to access your funds. From 3a377af5eeeea5956552108e7435181631eab47f Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Mon, 30 Jan 2023 09:09:27 +1000 Subject: [PATCH 10/15] Minor update. Signed-off-by: bgravenorst --- docs/HowTo/Withdrawal-Keys.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/HowTo/Withdrawal-Keys.md b/docs/HowTo/Withdrawal-Keys.md index f3ce6cae9..673124542 100644 --- a/docs/HowTo/Withdrawal-Keys.md +++ b/docs/HowTo/Withdrawal-Keys.md @@ -71,7 +71,8 @@ API see if your request is still in the pool. ### Update your Ethereum address -To update an Ethereum address, you'll need to create a new validator key. You can exit your current +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 currentg validator key as a voluntary exit, and use the funds from the full withdrawal of that to create the new validator key. From fbf4d19055c3cab568d9e8c61bc11be4d56405ad Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Mon, 30 Jan 2023 09:11:09 +1000 Subject: [PATCH 11/15] typo. Signed-off-by: bgravenorst --- docs/HowTo/Withdrawal-Keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/HowTo/Withdrawal-Keys.md b/docs/HowTo/Withdrawal-Keys.md index 673124542..8dd0b1aa8 100644 --- a/docs/HowTo/Withdrawal-Keys.md +++ b/docs/HowTo/Withdrawal-Keys.md @@ -72,7 +72,7 @@ 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 currentg +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. From 108f2668e3ed49aa8bcabd50e47186ae270fb245 Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Mon, 30 Jan 2023 09:51:01 +1000 Subject: [PATCH 12/15] Address reviewer feeedback. Signed-off-by: bgravenorst --- docs/Concepts/Withdrawals.md | 5 +++-- docs/HowTo/Withdrawal-Keys.md | 7 ++++--- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/Concepts/Withdrawals.md b/docs/Concepts/Withdrawals.md index 8b8ad4751..55a21528b 100644 --- a/docs/Concepts/Withdrawals.md +++ b/docs/Concepts/Withdrawals.md @@ -9,13 +9,14 @@ Validators staking ether on Mainnet after [The Merge](Merge.md), accrue 2 forms - Execution layer rewards paid directly to a withdrawal address (Ethereum address). - Consensus layer rewards for performing actions each epoch. -The Capella upgrade implements an automated process that allows a validator's rewards to be transferred +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 currently possible to set its withdrawal address to a + 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. You can [update your BLS withdrawal address to an Ethereum address](../HowTo/Withdrawal-Keys.md) diff --git a/docs/HowTo/Withdrawal-Keys.md b/docs/HowTo/Withdrawal-Keys.md index 8dd0b1aa8..3cbb4ce5d 100644 --- a/docs/HowTo/Withdrawal-Keys.md +++ b/docs/HowTo/Withdrawal-Keys.md @@ -4,9 +4,10 @@ title: How to update your withdrawal credentials # Update your withdrawal credentials -When you create a validator, it’s currently possible to set its [withdrawal](../Concepts/Withdrawals.md) address -to a BLS address, or an Ethereum address. After the Capella fork, users must use an Ethereum address as their withdrawal -address to allow automatics transfers. +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 From 08ee7c8a836eb1252f49850774adca5befc69d6d Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Mon, 30 Jan 2023 09:56:26 +1000 Subject: [PATCH 13/15] Fix typo. Signed-off-by: bgravenorst --- docs/Concepts/Withdrawals.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Concepts/Withdrawals.md b/docs/Concepts/Withdrawals.md index 55a21528b..e8337cefc 100644 --- a/docs/Concepts/Withdrawals.md +++ b/docs/Concepts/Withdrawals.md @@ -63,7 +63,7 @@ Withdrawal keys that are configured as [BLS keys](https://en.wikipedia.org/wiki/ 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 ETH1 withdrawal keys are prefixed with a `0x01`. +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). From 2ea3471f641ba7fc1241b0b68299e1b9e5cb4254 Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Mon, 30 Jan 2023 12:30:56 +1000 Subject: [PATCH 14/15] Add sentence about BLS withdrawal keys. Signed-off-by: bgravenorst --- docs/Concepts/Withdrawals.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/Concepts/Withdrawals.md b/docs/Concepts/Withdrawals.md index e8337cefc..926e61e45 100644 --- a/docs/Concepts/Withdrawals.md +++ b/docs/Concepts/Withdrawals.md @@ -17,7 +17,8 @@ upgrade, consensus layer rewards were locked, and unable to be transferred to an !!! 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. + [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. From f3cbcf2515635150f822003cba5b412212d6c0c0 Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Tue, 31 Jan 2023 12:25:55 +1000 Subject: [PATCH 15/15] Address comment. Signed-off-by: bgravenorst --- docs/Concepts/Withdrawals.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Concepts/Withdrawals.md b/docs/Concepts/Withdrawals.md index 926e61e45..b63d706d3 100644 --- a/docs/Concepts/Withdrawals.md +++ b/docs/Concepts/Withdrawals.md @@ -50,8 +50,8 @@ there is no mechanism for recycling the validator ID that has been exited. 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, must -have an excess balance, or have exited. +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