From 8bb1751f4664bb319adc4d34f95b4450e64a85aa Mon Sep 17 00:00:00 2001 From: Alex Stokes Date: Mon, 7 Nov 2022 15:22:26 -0700 Subject: [PATCH 1/4] Add note to Capella validator guide about BLS to execution change --- specs/capella/validator.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/specs/capella/validator.md b/specs/capella/validator.md index 90176e035..9bbc8d8db 100644 --- a/specs/capella/validator.md +++ b/specs/capella/validator.md @@ -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) @@ -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. From 0f93e9aad8ae70cd6a0bdaa9779665a670182553 Mon Sep 17 00:00:00 2001 From: Alex Stokes Date: Thu, 10 Nov 2022 09:12:10 -0500 Subject: [PATCH 2/4] Update specs/capella/validator.md Co-authored-by: Hsiao-Wei Wang --- specs/capella/validator.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/capella/validator.md b/specs/capella/validator.md index 9bbc8d8db..32e26bca6 100644 --- a/specs/capella/validator.md +++ b/specs/capella/validator.md @@ -118,7 +118,7 @@ Up to `MAX_BLS_TO_EXECUTION_CHANGES`, [`BLSToExecutionChange`](./beacon-chain.md 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: +There is one prerequisite task to perform before a validator can participate 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 From be85e9356a6029287e6b9b3c02c11447b1a7e3c8 Mon Sep 17 00:00:00 2001 From: Alex Stokes Date: Thu, 10 Nov 2022 09:12:35 -0500 Subject: [PATCH 3/4] Update specs/capella/validator.md Co-authored-by: Hsiao-Wei Wang --- specs/capella/validator.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/capella/validator.md b/specs/capella/validator.md index 32e26bca6..0853d052e 100644 --- a/specs/capella/validator.md +++ b/specs/capella/validator.md @@ -141,7 +141,7 @@ The `from_bls_pubkey` is compared against the existing withdrawal credential on- 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 +Next, the validator signs the assembled `message: BLSToExecutionChange` 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). From 0e7d3555ead28fdf1f0970f1ea900938d9f7a007 Mon Sep 17 00:00:00 2001 From: Danny Ryan Date: Thu, 10 Nov 2022 11:12:33 -0700 Subject: [PATCH 4/4] minor copy edits --- specs/capella/validator.md | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/specs/capella/validator.md b/specs/capella/validator.md index 0853d052e..74bad7e6d 100644 --- a/specs/capella/validator.md +++ b/specs/capella/validator.md @@ -116,35 +116,36 @@ Up to `MAX_BLS_TO_EXECUTION_CHANGES`, [`BLSToExecutionChange`](./beacon-chain.md ## Enabling validator withdrawals -Stake belonging to validators that can safely be withdrawn from the beacon chain happens via an automatic process. +Validator balances are fully or partially withdrawn via an automatic process. -There is one prerequisite task to perform before a validator can participate in this automatic process: -ensuring the withdrawal credentials are for the execution layer, i.e. having an `ETH1_ADDRESS_WITHDRAWAL_PREFIX`. +For validators, there is one prerequisite for this automated process: +withdrawal credentials pointing to an execution layer address, 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. +If a validator has a `BLS_WITHDRAWAL_PREFIX` withdrawal credential prefix, to participate in withdrawals the validator must +create a one-time message to change their withdrawal credential from the version authenticated with a BLS key to the +version compatible with the execution layer. This message -- a `BLSToExecutionChange` -- is available starting in Capella 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. +withdrawal credentials can delay creating this message until they are ready to enable withdrawals. ### 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. +This `message` contains the `validator_index` for the validator who wishes to change their credentials, the `from_bls_pubkey` -- 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 the execution layer address to which the validator's balances will be withdrawn. -**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. +*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`. +*Warning*: This message can only be included on-chain once and is +irreversible so ensure the correctness and accessibility to `to_execution_address`. Next, the validator signs the assembled `message: BLSToExecutionChange` 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 `SignedBLSToExecutionChange` message should then 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. + +*Note*: A node *should* prioritize locally received `BLSToExecutionChange` operations to ensure these changes make it on-chain +through self published blocks even if the rest of the network censors.