Skip to content

Commit

Permalink
Add note to Capella validator guide about BLS to execution change
Browse files Browse the repository at this point in the history
  • Loading branch information
ralexstokes committed Nov 7, 2022
1 parent 851b9a5 commit 8bb1751
Showing 1 changed file with 37 additions and 0 deletions.
37 changes: 37 additions & 0 deletions specs/capella/validator.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@
- [Constructing the `BeaconBlockBody`](#constructing-the-beaconblockbody)
- [ExecutionPayload](#executionpayload)
- [BLS to execution changes](#bls-to-execution-changes)
- [Enabling validator withdrawals](#enabling-validator-withdrawals)
- [Changing from BLS to execution withdrawal credentials](#changing-from-bls-to-execution-withdrawal-credentials)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->
<!-- /TOC -->
Expand Down Expand Up @@ -111,3 +113,38 @@ def prepare_execution_payload(state: BeaconState,
##### BLS to execution changes

Up to `MAX_BLS_TO_EXECUTION_CHANGES`, [`BLSToExecutionChange`](./beacon-chain.md#blstoexecutionchange) objects can be included in the `block`. The BLS to execution changes must satisfy the verification conditions found in [BLS to execution change processing](./beacon-chain.md#new-process_bls_to_execution_change).

## Enabling validator withdrawals

Stake belonging to validators that can safely be withdrawn from the beacon chain happens via an automatic process.

There is one prerequisite task to perform before a validator can particpate in this automatic process:
ensuring the withdrawal credentials are for the execution layer, i.e. having an `ETH1_ADDRESS_WITHDRAWAL_PREFIX`.

If a validator has a `BLS_WITHDRAWAL_PREFIX` withdrawal credential prefix, Capella adds the ability for a validator
to make a one-time message that changes their withdrawal credential from the version authenticated with a BLS key to the
version compatible with the execution layer.

Validators who wish to enable withdrawals **MUST** assemble, sign, and broadcast this message so that it is accepted
on the beacon chain. Validators who do not want to enable withdrawals and have the `BLS_WITHDRAWAL_PREFIX` version of
withdrawal credentials can simply wait until they are ready to create this message and will not particpate in the
automatic withdrawal process.

### Changing from BLS to execution withdrawal credentials

First, the validator must construct a valid [`BLSToExecutionChange`](./beacon-chain.md#blstoexecutionchange) `message`.
This `message` contains the `validator_index` for the validator who wishes to change their credentials, the `from_bls_pubkey` containing the BLS public key corresponding to the **withdrawal BLS secret key** used to form the `BLS_WITHDRAWAL_PREFIX` withdrawal credential, and the `to_execution_address` specifying where the validator wants stake to be withdrawn to on the execution layer.

**NOTE**: The withdrawal key pair used to construct the `BLS_WITHDRAWAL_PREFIX` withdrawal credential should be distinct from the signing key pair used to operate the validator under typical circumstances. Consult your validator deposit tooling documentation for further details if you are not aware of the difference.

The `from_bls_pubkey` is compared against the existing withdrawal credential on-chain for the given `validator_index` so
it is unlikely a validator will incorrectly specify this data; however, this message can only be issued once and is currently
irreversible once on-chain so take care with the `to_execution_address`.

Next, the validator signs the assembled `BLSToExecutionChange` `message` with the **withdrawal BLS secret key** and this
`signature` is placed into a `SignedBLSToExecutionChange` message along with the inner `BLSToExecutionChange` `message`.
Note that the `SignedBLSToExecutionChange` message should pass all of the validations in [`process_bls_to_execution_change`](./beacon-chain.md#new-process_bls_to_execution_change).

The complete `SignedBLSToExecutionChange` message can be submitted to the consensus layer network. Once included on-chain,
the withdrawal credential change takes effect. No further action is required for a validator to enter into the automated
withdrawal process.

0 comments on commit 8bb1751

Please sign in to comment.