Drafted a document for withdrawals for capella (#412)

* 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. Consensys/teku#5680 and Consensys/teku#6482

* First pass on editing the content.

Signed-off-by: bgravenorst <byron.gravenorst@consensys.net>

* Additional edits and structural changes.

Signed-off-by: bgravenorst <byron.gravenorst@consensys.net>

* Fix vale issues.

Signed-off-by: bgravenorst <byron.gravenorst@consensys.net>

* updating submodule to latest

* Update common folder.

Signed-off-by: bgravenorst <byron.gravenorst@consensys.net>

* updating submodule to latest

* updating submodule to latest

* Address reviewer feedback.

Signed-off-by: bgravenorst <byron.gravenorst@consensys.net>

* Minor update.

Signed-off-by: bgravenorst <byron.gravenorst@consensys.net>

* typo.

Signed-off-by: bgravenorst <byron.gravenorst@consensys.net>

* Address reviewer feeedback.

Signed-off-by: bgravenorst <byron.gravenorst@consensys.net>

* Fix typo.

Signed-off-by: bgravenorst <byron.gravenorst@consensys.net>

* Add sentence about BLS withdrawal keys.

Signed-off-by: bgravenorst <byron.gravenorst@consensys.net>

* Address comment.

Signed-off-by: bgravenorst <byron.gravenorst@consensys.net>

---------

Signed-off-by: bgravenorst <byron.gravenorst@consensys.net>
Co-authored-by: bgravenorst <byron.gravenorst@consensys.net>
Co-authored-by: bgravenorst <50852695+bgravenorst@users.noreply.github.com>

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

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=<VALIDATOR_INDEX> \
+    curl http://localhost:5051/eth/v1/beacon/states/finalized/validators/$VALIDATOR | jq '.data | .validator.withdrawal_credentials'
+    ```
+
+=== "Example output"
+
+    ```
+    "0x00fc40352b0a186d83267fc1342ec5da49dbb78e1099a4bd8db16d2c0d223594"
+    ```
+
+In the script, specify the `<VALIDATOR_INDEX>` (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.

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: