→ updated on 02/27/2023: added a section for generating a voluntary exit message without a mnemonic / offline computer (with ethdo v1.28.4+)

With the upcoming Shanghai/Capella network upgrade, the Ethereum validator lifecycle will be formally closed. Although the exit process itself had been specified all along, it is worth reviewing it once again, adding the final piece of the puzzle to it: withdrawals🦉

Additionally, about 60% of all mainnet validators will have to rotate their withdrawal credentials if they wish to receive their accrued rewards & their deposit, eventually.

Stakers will need to touch their mnemonic in order to generate the necessary BLS-to-Execution message. On this occasion they may as well consider preparing a voluntary exit message in advance.

A voluntary exit message (VEM) for a given validator requires a signature and thus accessibility to its private validator key. Node operators usually follow the official exit documentation provided by their clients of choice - but what if the the node and the expected keystores are not at hand?

A VEM can be generated in advance as described in the following tutorial and, for example, be backed up as a .json file on an arbitrary hard drive.

First, let’s think of a few scenarios for (unslashed) validators which lack their private validator key, but instead are equipped with a voluntary exit message in advance:

• The validator operator is not able to access and maintain the node for the foreseeable future anymore (e.g. suddenly passed away)

It should be better practice to provide their heirs with a way to exit and withdraw the staked ETH without too much technical knowledge.

Customers of (semi-)custodial staking providers (32ETH tranches) must trust their node operator to properly handle their private signing key(s). Even if the withdrawal credentials point at a customer controlled address, staking-as-a-service providers technically can reduce the trust assumptions even further. Customers should ask their providers for a prepared exit message for their validator(s).

The mechanism is comparable to an escape hatch for Layer-2 protocols: if the staking provider were to disappear, a customer can independently initiate an exit.

• The node has been physically stolen, hacked, lost or is inaccessible for other reasons.

A race starts to not let the attacker slash the validator (although the attacker has little incentive to do so, there is an increased risk for a signer slashing)

Assuming an empty exit queue, it may take just 4 epochs (~26 minutes) between submitting a prepared exit message to the network and the validator being exited. (see schematic overview below)

Once exited, a validator is exempted from all consensus duties and the risk of committing a slashable offense is eliminated.

-- As an in-depth analysis of the exit process is out of scope for this post, feel free to refer to primary sources on how withdrawals / exits work in detail --

👉 note and very important caveat 👈

That means, VEMs signed for the (previous) Altair fork specifications are valid in both Altair and Bellatrix (the subsequent upgrade), but will become invalid in Capella (the upcoming upgrade). As a result, stakers may wish to refresh their stored exit messages after every upgrade (or every other one at a minimum).

thanks to @benjaminion_xyz for this critical hint

UPDATE

Feel free to follow-up on discussions and change requests to remove the expiry date for voluntary exit messages as soon as the next network upgrade (Deneb).

⚠️ As an imminent precaution, generating and submitting VEMs as well as BLS-to-Execution change messages should be practiced on testnets! ⚠️

• Before Goerli, Zhejiang testnet is a great place to start. Here, the Shanghai/Capella upgrade is already live (guides: one, two, three)

Since the Ethereum Foundation maintained Staking-Deposit-CLI currently lacks the VEM generation feature, we will use ethdo - an audited, open source third party tool by well-renowned community members attestant.

Sidenote: keep your initial mnemonic secure even after the one-time withdrawal credential change - it remains a must-have for validator keystore re-creation and consequently for VEM generation as well!

The VEM generation process itself is a combined online & offline process (for mnemonic security reasons). For a high-level, conceptual overview of a possible VEM generation setup, refer to the following diagram:

• Retrieve the latest version of ethdo

• Prepare a Linux Live USB drive and copy ethdo to it (well-documented elsewhere)

• Get a hand on your (secret) mnemonic/seed phrase - operate with extra caution(!)

  check-out a similar, more detailed step-by-step guide for withdrawal credential changes by the fine folks from eth-docker.net

On an (online) computer with a beacon node attached/connected, prompt the following command in the directory at which ethdo is located:

$ ./ethdo --connection http://localhost:5052 validator exit --prepare-offline --timeout 2m --allow-insecure-connections

This command creates an offline-preparation.json file which contains information about all validators on the network. Copy it to the bootable USB drive as well (same folder as ethdo). It will be used during the offline step (2).

Alternatively using Docker:

$ touch $(pwd)/offline-preparation.json && docker run --rm -it --network=host -v $(pwd)/offline-preparation.json:/app/offline-preparation.json wealdtech/ethdo --connection 127.0.0.1:5052 validator exit --prepare-offline --timeout 2m --allow-insecure-connections

potentially combine this step with generating a BLS-to-Execution message

Boot into your offline computer and generate the VEM (exit-operation.json) for each validator (index) individually, making use of your mnemonic and information from the offline-preparation.json:

$ ./ethdo validator exit --offline --mnemonic="vocal ethics ... tomato bargain" --validator=123456

This command creates an exit-operation.json file which includes a signed VEM.

→ The file may then be stored safely as preparation for scenarios as described above.

On an online computer: broadcast each validator exit message to the network

👉 This would be the required task for node operator heirs👈

They need access to the VEM, (i.e exit-operation.json) file(s) and access to a command line:

$ curl -d @exit-operation.json -H "Content-Type: application/json" -X POST https://beacon.zhejiang.ethpandaops.io/eth/v1/beacon/pool/voluntary_exits

Adjust the public beacon public API accordingly (e.g. to mainnet endpoints)

This message broadcast does not require gas (i.e. no transaction fee).

note: beaconcha.in offers a drag & drop web interface for broadcasting VEM messages, eliminating the need for command line knowledge

https://zhejiang.beaconcha.in/tools/broadcast

Alternatively, attestant has announced they will provide a mainnet endpoint in order to submit exit messages as well.

$ ./ethdo --connection http://localhost:5052 validator exit --signed-operation exit-operation.json

Alternatively using Docker:

$ docker run --rm -it --network=host -v $(pwd)/exit-operation.json:/app/exit-operation.json wealdtech/ethdo validator exit --signed-operation exit-operation.json

Adjust the Docker volumes and exit-operation files for each validator accordingly

As shown in the exit process chart at the top, the VEM will either still be processed or already be incorporated into a block.

$ curl -X GET "https://beacon.zhejiang.ethpandaops.io/eth/v1/beacon/pool/voluntary_exits" -H "accept:application/json"

Adjust the public beacon public API accordingly (e.g. to mainnet endpoints)

$ ./ethdo --connection http://localhost:5052 validator info --validator=123456

Alternatively using Docker:

$ docker run --rm -it --network=host wealdtech/ethdo --connection 127.0.0.1:5052 validator info --validator=123456

Repeated call for mainnet caution:

• Be aware that generating voluntary exit messages involves dealing with your validator mnemonic. Thus,***never* trust* instructions from a random stranger writing blogposts on mirror.xyz or elsewhere!*

  Make sure to follow official client teams instructions and guidelines whenever possible.

UPDATE

• validator signing key (and the corresponding passphrase)

• ethdo v.1.28.4+ (and a local beacon node for offline-preparation.json file)

Going this path does not require an offline computer. It allows forward-looking and anticipatory node operators to generate a VEM in advance without touching their mnemonic/seed phrase. Instead, generating a VEM only requires a validator signing key (and the corresponding passphrase).

Note: in case the staking machine and thus the validator signing key is inaccessible (think of scenario 3 mentioned earlier), follow the VEM generation process (online+offline) with an mnemonic as described above.

• Follow the 1.) Online preparation section as described above.

• Afterwards, based of the ethdo directory prompt the following command to generate a VEM (exit-operation.json) for each validator individually, making use of your signing-key.json file and information from the offline-preparation.json:

$ ./ethdo validator exit --validator=/validator_keys/keystore-m_12381_3600_1_0_0-1677445363.json --passphrase=password123 --offline

Change the keystore-directory & -filename as well as the keystore password - i.e. passphrase - accordingly. Note: the “passphrase” is NOT the mnemonic!

Alternatively using Docker:

$ touch $(pwd)/exit-operation.json && docker run --rm -it -v $(pwd)/exit-operation.json:/app/exit-operation.json -v $(pwd)/offline-preparation.json:/app/offline-preparation.json -v $(pwd)/validator_keys/keystore-m_12381_3600_1_0_0-1677445363.json:/app/keystore-m_12381_3600_1_0_0-1677445363.json wealdtech/ethdo validator exit --validator=keystore-m_12381_3600_1_0_0-1677445363.json --passphrase=password123 --offline

• Follow the 3.) Online broadcasting of VEMs to the network section as described above.

note: attestant intends to provide a way to obtain the information for the offline-preparation.json without the need for accessing a local beacon node, i.e. step 1.) may be obsolete

****

Please keep in mind this is a testnet guide that may contain mistakes and that takes shortcuts which come with trade-offs. It could quickly become outdated as it’s subject to ever evolving network and software changes.

********

This post was supported by a grant from a CLR funding round held by EthStaker, mainly matched by the EF.

→ updated on 02/27/2023: added a section for generating a voluntary exit message without a mnemonic / offline computer (with ethdo v1.28.4+)

With the upcoming Shanghai/Capella network upgrade, the Ethereum validator lifecycle will be formally closed. Although the exit process itself had been specified all along, it is worth reviewing it once again, adding the final piece of the puzzle to it: withdrawals🦉

Additionally, about 60% of all mainnet validators will have to rotate their withdrawal credentials if they wish to receive their accrued rewards & their deposit, eventually.

Stakers will need to touch their mnemonic in order to generate the necessary BLS-to-Execution message. On this occasion they may as well consider preparing a voluntary exit message in advance.

A voluntary exit message (VEM) for a given validator requires a signature and thus accessibility to its private validator key. Node operators usually follow the official exit documentation provided by their clients of choice - but what if the the node and the expected keystores are not at hand?

A VEM can be generated in advance as described in the following tutorial and, for example, be backed up as a .json file on an arbitrary hard drive.

First, let’s think of a few scenarios for (unslashed) validators which lack their private validator key, but instead are equipped with a voluntary exit message in advance:

• The validator operator is not able to access and maintain the node for the foreseeable future anymore (e.g. suddenly passed away)

It should be better practice to provide their heirs with a way to exit and withdraw the staked ETH without too much technical knowledge.

Customers of (semi-)custodial staking providers (32ETH tranches) must trust their node operator to properly handle their private signing key(s). Even if the withdrawal credentials point at a customer controlled address, staking-as-a-service providers technically can reduce the trust assumptions even further. Customers should ask their providers for a prepared exit message for their validator(s).

The mechanism is comparable to an escape hatch for Layer-2 protocols: if the staking provider were to disappear, a customer can independently initiate an exit.

• The node has been physically stolen, hacked, lost or is inaccessible for other reasons.

A race starts to not let the attacker slash the validator (although the attacker has little incentive to do so, there is an increased risk for a signer slashing)

Assuming an empty exit queue, it may take just 4 epochs (~26 minutes) between submitting a prepared exit message to the network and the validator being exited. (see schematic overview below)

Once exited, a validator is exempted from all consensus duties and the risk of committing a slashable offense is eliminated.

-- As an in-depth analysis of the exit process is out of scope for this post, feel free to refer to primary sources on how withdrawals / exits work in detail --

👉 note and very important caveat 👈

That means, VEMs signed for the (previous) Altair fork specifications are valid in both Altair and Bellatrix (the subsequent upgrade), but will become invalid in Capella (the upcoming upgrade). As a result, stakers may wish to refresh their stored exit messages after every upgrade (or every other one at a minimum).

thanks to @benjaminion_xyz for this critical hint

UPDATE

Feel free to follow-up on discussions and change requests to remove the expiry date for voluntary exit messages as soon as the next network upgrade (Deneb).

⚠️ As an imminent precaution, generating and submitting VEMs as well as BLS-to-Execution change messages should be practiced on testnets! ⚠️

• Before Goerli, Zhejiang testnet is a great place to start. Here, the Shanghai/Capella upgrade is already live (guides: one, two, three)

Since the Ethereum Foundation maintained Staking-Deposit-CLI currently lacks the VEM generation feature, we will use ethdo - an audited, open source third party tool by well-renowned community members attestant.

Sidenote: keep your initial mnemonic secure even after the one-time withdrawal credential change - it remains a must-have for validator keystore re-creation and consequently for VEM generation as well!

The VEM generation process itself is a combined online & offline process (for mnemonic security reasons). For a high-level, conceptual overview of a possible VEM generation setup, refer to the following diagram:

• Retrieve the latest version of ethdo

• Prepare a Linux Live USB drive and copy ethdo to it (well-documented elsewhere)

• Get a hand on your (secret) mnemonic/seed phrase - operate with extra caution(!)

  check-out a similar, more detailed step-by-step guide for withdrawal credential changes by the fine folks from eth-docker.net

On an (online) computer with a beacon node attached/connected, prompt the following command in the directory at which ethdo is located:

$ ./ethdo --connection http://localhost:5052 validator exit --prepare-offline --timeout 2m --allow-insecure-connections

This command creates an offline-preparation.json file which contains information about all validators on the network. Copy it to the bootable USB drive as well (same folder as ethdo). It will be used during the offline step (2).

Alternatively using Docker:

$ touch $(pwd)/offline-preparation.json && docker run --rm -it --network=host -v $(pwd)/offline-preparation.json:/app/offline-preparation.json wealdtech/ethdo --connection 127.0.0.1:5052 validator exit --prepare-offline --timeout 2m --allow-insecure-connections

potentially combine this step with generating a BLS-to-Execution message

Boot into your offline computer and generate the VEM (exit-operation.json) for each validator (index) individually, making use of your mnemonic and information from the offline-preparation.json:

$ ./ethdo validator exit --offline --mnemonic="vocal ethics ... tomato bargain" --validator=123456

This command creates an exit-operation.json file which includes a signed VEM.

→ The file may then be stored safely as preparation for scenarios as described above.

On an online computer: broadcast each validator exit message to the network

👉 This would be the required task for node operator heirs👈

They need access to the VEM, (i.e exit-operation.json) file(s) and access to a command line:

$ curl -d @exit-operation.json -H "Content-Type: application/json" -X POST https://beacon.zhejiang.ethpandaops.io/eth/v1/beacon/pool/voluntary_exits

Adjust the public beacon public API accordingly (e.g. to mainnet endpoints)

This message broadcast does not require gas (i.e. no transaction fee).

note: beaconcha.in offers a drag & drop web interface for broadcasting VEM messages, eliminating the need for command line knowledge

https://zhejiang.beaconcha.in/tools/broadcast

Alternatively, attestant has announced they will provide a mainnet endpoint in order to submit exit messages as well.

$ ./ethdo --connection http://localhost:5052 validator exit --signed-operation exit-operation.json

Alternatively using Docker:

$ docker run --rm -it --network=host -v $(pwd)/exit-operation.json:/app/exit-operation.json wealdtech/ethdo validator exit --signed-operation exit-operation.json

Adjust the Docker volumes and exit-operation files for each validator accordingly

As shown in the exit process chart at the top, the VEM will either still be processed or already be incorporated into a block.

$ curl -X GET "https://beacon.zhejiang.ethpandaops.io/eth/v1/beacon/pool/voluntary_exits" -H "accept:application/json"

Adjust the public beacon public API accordingly (e.g. to mainnet endpoints)

$ ./ethdo --connection http://localhost:5052 validator info --validator=123456

Alternatively using Docker:

$ docker run --rm -it --network=host wealdtech/ethdo --connection 127.0.0.1:5052 validator info --validator=123456

Repeated call for mainnet caution:

• Be aware that generating voluntary exit messages involves dealing with your validator mnemonic. Thus,***never* trust* instructions from a random stranger writing blogposts on mirror.xyz or elsewhere!*

  Make sure to follow official client teams instructions and guidelines whenever possible.

UPDATE

• validator signing key (and the corresponding passphrase)

• ethdo v.1.28.4+ (and a local beacon node for offline-preparation.json file)

Going this path does not require an offline computer. It allows forward-looking and anticipatory node operators to generate a VEM in advance without touching their mnemonic/seed phrase. Instead, generating a VEM only requires a validator signing key (and the corresponding passphrase).

Note: in case the staking machine and thus the validator signing key is inaccessible (think of scenario 3 mentioned earlier), follow the VEM generation process (online+offline) with an mnemonic as described above.

• Follow the 1.) Online preparation section as described above.

• Afterwards, based of the ethdo directory prompt the following command to generate a VEM (exit-operation.json) for each validator individually, making use of your signing-key.json file and information from the offline-preparation.json:

$ ./ethdo validator exit --validator=/validator_keys/keystore-m_12381_3600_1_0_0-1677445363.json --passphrase=password123 --offline

Change the keystore-directory & -filename as well as the keystore password - i.e. passphrase - accordingly. Note: the “passphrase” is NOT the mnemonic!

Alternatively using Docker:

$ touch $(pwd)/exit-operation.json && docker run --rm -it -v $(pwd)/exit-operation.json:/app/exit-operation.json -v $(pwd)/offline-preparation.json:/app/offline-preparation.json -v $(pwd)/validator_keys/keystore-m_12381_3600_1_0_0-1677445363.json:/app/keystore-m_12381_3600_1_0_0-1677445363.json wealdtech/ethdo validator exit --validator=keystore-m_12381_3600_1_0_0-1677445363.json --passphrase=password123 --offline

• Follow the 3.) Online broadcasting of VEMs to the network section as described above.

note: attestant intends to provide a way to obtain the information for the offline-preparation.json without the need for accessing a local beacon node, i.e. step 1.) may be obsolete

****

Please keep in mind this is a testnet guide that may contain mistakes and that takes shortcuts which come with trade-offs. It could quickly become outdated as it’s subject to ever evolving network and software changes.

********

This post was supported by a grant from a CLR funding round held by EthStaker, mainly matched by the EF.