🦉Update Withdrawal Keys for Ethereum Validator (BLS to Execution Change or 0x00 to 0x01) with ETHDO

A simplified guide to help you update your validators BLS 0x00 credentials to execution withdrawal 0x01 credentials using the ETHDO tool by wealdtech.

The following steps align with our mainnet guide. You may need to adjust file names and directory locations where appropriate. The core concepts remain the same.

• Greetings, fellow ETH staker! If you were staking before April 2, 2021, setting ETH withdrawal (0x01) credentials was not yet released and so, this guide is relevant for you.

• As of the Shapella upgrade, ETH validators with 0x00 credentials should update to 0x01 credentials to enable partial withdrawals, the sweeping of excess ETH > 32.

• If your validator previously voluntarily exited or you now would like to stop validator duties, you'll need to set your withdrawal credentials to fully reclaim your staked ETH.

• Your validator's mnemonic keys (the offline 24 word secrets)

• An offline air-gapped computer. Create a Linux Live USB like Ubuntu or Tails; needs a USB key.

• A ETH staking node using Ubuntu or Linux, also known as online computer.

• A USB storage key for moving files between the offline and online computer.

• Familiarize yourself with the Ethereum.org Staking Withdrawals guide.

Step 1: Prepare chain information

• If you no longer have a synced full node, use option 1.

• Option 2 uses your own consensus client to generate chain information.

Option 1: Download "offline-preparation.json" file, save to USB key, transfer to offline air-gapped computer.

1. On your online computer, open a terminal window or shell. Shortcut: CTRL + ALT + T

2. Download Ethdo v1.30.0 from Github https://github.com/wealdtech/ethdo/releases

cd ~
wget https://github.com/wealdtech/ethdo/releases/download/v1.30.0/ethdo-1.30.0-linux-amd64.tar.gz

3. Verify the checksum is valid. Located on the release page, the Checksum string is located in the corresponding sha256 file.

echo "6fbe587f522ad2eb8d6ce22dfdb15f7d163b491a670bf50e5acf12dd0f58125c ethdo-1.30.0-linux-amd64.tar.gz" | sha256sum -c

Successful verification occurs if you see "OK" in the resulting output.

ethdo-1.30.0-linux-amd64.tar.gz: OK

4. Extract ethdo.

tar -xvf ethdo-1.30.0-linux-amd64.tar.gz

5. Verify your validator's credential status with your index number. Replace<MY-VALIDATOR-INDEX> accordingly.

./ethdo validator credentials get --validator=<MY-VALIDATOR-INDEX>

BLS credentials: 0x0002a0addda8106aed690654c7af7af0bc5ccde321c8e5e2319ff432cee70396

If you have BLS credentials, continue with the rest of this guide. Otherwise, stop because ethdo will output "Ethereum execution address" and that means you've already set your withdrawal address!

6. Download pre-generated offline preparation files made daily by EthStaker.

#mainnet
wget https://files.ethstaker.cc/offline-preparation-mainnet.tar.gz
wget https://files.ethstaker.cc/offline-preparation-mainnet.tar.gz.sha256

#goerli
wget https://files.ethstaker.cc/offline-preparation-goerli.tar.gz
wget https://files.ethstaker.cc/offline-preparation-goerli.tar.gz.sha256

7. Verify the file's sha256 hash against the sha256 files to ensure correctness.

#mainnet
sha256sum offline-preparation-mainnet.tar.gz

#goerli
sha256sum offline-preparation-goerli.tar.gz

The output should match the contents of the .sha256 file. View the contents:

#mainnet
cat offline-preparation-mainnet.tar.gz.sha256

#goerli
cat offline-preparation-goerli.tar.gz.sha256

8. Extract the tar file to find offline-preparation.json

#mainnet
tar -xvf offline-preparation-mainnet.tar.gz

#goerli
tar -xvf offline-preparation-goerli.tar.gz

9. Using your USB key, copy both

• the ethdo executable

• and offline-preparation.json file

to your offline air-gapped computer.

Option 2: Generate "offline-preparation.json" file, save to USB key, transfer to offline air-gapped computer.

1. On your online computer, open a terminal window or shell. Shortcut: CTRL + ALT + T

2. Download Ethdo v1.30.0 from Github https://github.com/wealdtech/ethdo/releases

cd ~
wget https://github.com/wealdtech/ethdo/releases/download/v1.30.0/ethdo-1.30.0-linux-amd64.tar.gz

3. Verify the checksum is valid. Located on the release page, the Checksum string is located in the corresponding sha256 file.

echo "6fbe587f522ad2eb8d6ce22dfdb15f7d163b491a670bf50e5acf12dd0f58125c ethdo-1.30.0-linux-amd64.tar.gz" | sha256sum -c

Successful verification occurs if you see "OK" in the resulting output.

ethdo-1.30.0-linux-amd64.tar.gz: OK

4. Extract ethdo.

tar -xvf ethdo-1.30.0-linux-amd64.tar.gz

5. Verify your validator's credential status with your index number. Replace<MY-VALIDATOR-INDEX> accordingly.

./ethdo validator credentials get --validator=<MY-VALIDATOR-INDEX>

BLS credentials: 0x0002a0addda8106aed690654c7af7af0bc5ccde321c8e5e2319ff432cee70396

If you have BLS credentials, continue with the rest of this guide. Otherwise, stop because ethdo will output "Ethereum execution address" and that means you've already set your withdrawal address!

6. Run the following command to call your consensus client and generate a list of active validators with relevant information for use on your offline computer. In order to generate this list from your local beacon node, ensure the REST API is enabled; otherwise the default fallback beacon node, http://mainnet-consensus.attestant.io, will be called.

./ethdo validator credentials set --prepare-offline

After a minute or two, you should see the text, "offline-preparation.json generated"

7. Using your USB key, copy both

• the ethdo executable

• and offline-preparation.json file

to your offline air-gapped computer.

Step 2: Create change credentials file

Run ethdo with your mnemonic and withdrawal address. Transfer "change-operations.json" file via USB key back to online computer.

1. On your offline air-gapped computer, disconnect any internet Ethernet cables or WiFi / bluetooth before continuing. Make sure you're truly offline!

2. Open a terminal window or shell. Shortcut: CTRL + ALT + T

3. After copying the ethdo executable and offline-preparation.json file to your offline computer's HOME directory, ensure the ethdo file has execute permissions.

chmod +x ethdo

4. This ethdo command sets your validator credentials and the output is stored in a change-operations.json file. Replace <MY MNEMONIC PHRASE> AND <MY ETH WITHDRAW ADDRESS> accordingly.

./ethdo validator credentials set --offline --mnemonic="<MY MNEMONIC PHRASE>” --withdrawal-address=<MY ETH WITHDRAW ADDRRESS>

5. After a few seconds, change-operations.json is created. It's normal for no message to be displayed.

6. Triple check the resulting file for your withdraw address.

cat change-operations.json

7. Ensure the field "to_execution_address": contains your withdraw address.

8. Using your USB key, copy

• change-operations.json file

back to your online computer.

9. Power off your offline air-gapped computer.

Step 3: Broadcast change credentials

Simply run the set command to send your change.

1. On the online computer, copy the change-operation.json to your home directory, where ethdo is also located.

2. Run the following command to broadcast your withdrawal credentials.

./ethdo validator credentials set

Congrats! Your BLS to Execution change is now pending in a queue, waiting to be included in a block.

For your information:

• Up to 16 BLS to Execution changes are included in each proposed block.

• Depending on the withdrawal queue size, your withdrawal change may take up to a few days to be finalized.

• Terminology: prefix of 0x01 = "Type 1" = execution withdrawal credentials = Withdrawals enabled

• As a partial withdrawal, periodically every few days any amount of ETH over 32 will be automatically swept to your withdrawal address.

Learn more from:

• Official Consensus Layer Withdrawal References

  • Prysm: https://docs.prylabs.network/docs/wallet/withdraw-validator

  • Nimbus: https://nimbus.guide/withdrawals.html

  • Lighthouse: https://lighthouse-book.sigmaprime.io/voluntary-exit.html#withdrawal-of-exited-funds

  • Teku: https://docs.teku.consensys.net/HowTo/Withdrawal-Keys

  • Lodestar: https://chainsafe.github.io/lodestar/reference/cli/#validator-bls-to-execution-change

• Ethdo official withdrawals guide: https://github.com/wealdtech/ethdo/blob/master/docs/changingwithdrawalcredentials.md

• Attestant's Post: https://www.attestant.io/posts/understanding-withdrawals/

Need extra live support?

• Find Ethstaker frens on the Ethstaker Discord!

• Use reddit: r/Ethstaker, or DMs, or r/coincashew

Like these guides?

• Support us on Gitcoin Grants: We build this guide exclusively by community support!🙏

• Feedback or pull-requests: https://github.com/coincashew/coincashew

Using my node, how can I check if my change is pending in the withdrawals queue?

Replace <MY VALIDATOR INDEX>. Adjust the REST API port number, if needed.

Lighthouse/Nimbus=5052. Prysm=3500. Lodestar=9596. Teku=5051.

curl -s "http://localhost:5052/eth/v1/beacon/pool/bls_to_execution_changes" | jq '.data | map(select(.message.validator_index=="<MY VALIDATOR INDEX>"))'

Example output:

[
  {
    "message": {
      "validator_index": "96193",
      "from_bls_pubkey": "0xb67aca71f04b673037b54009b760f1961f3836e5714141c892afdb75ec0834dce6784d9c72ed8ad7db328cff8fe9f13e",
      "to_execution_address": "0xb9d7934878b5fb9610b3fe8a5e441e8fad7e293f"
    },
    "signature": "0x988251748925e7a2966f28230c250e8c37495346d551e86fd89ea53148302b1145eb069647572801a689c9c1c5b8f2071019e652e01d92055d9aa99aa86696eb453889de38733caf2d5dce7a2786fed910365dcb7df082a62b130436fb9a1035"
  }
]

However, if the output shows [], this means your change is complete and no longer in the queue.

How much longer do I need to wait for this change to take effect?

Each block can add 16 blstoexecutionchangemessages and the time to process a BLS change depends on the size of the withdraw queue.

Find the size of the queue with the following command.

Adjust the REST API port number, if needed.

Lighthouse/Nimbus=5052. Prysm=3500. Lodestar=9596. Teku=5051.

curl -s http://localhost:5052/eth/v1/beacon/pool/bls_to_execution_changes | jq '.data | length'

How do I know the credential change worked?

Replace <MyValidatorIndex> and run the following ethdo command:

ethdo validator credentials get --validator=<MyValidatorIndex>

The resulting output will start with: Ethereum execution address

Alternatively, check your favorite beacon chain explorer such as beaconcha.in and etherscan.io for the 0x01 credentials.

I voluntary exited a while ago and don't have a synced node anymore. What are my options?

Use Ethdo on an offline computer to create the exit message, as shown in step 2 above, and then perform step 3 using the alternative broadcast method with beaconcha.in

Can I use a Gnosis Safe address as my ETH withdrawal address?

Yes -- in fact, this is also a great idea as it allows you to rotate private keys (and keep the same public address) or use other more multi-sig strategies.

reference: https://safe.global

Is the fee-recipient address the same as this withdrawal address?

They can both be set to the same ETH address; however, understand that these are independent and withdrawal credentials have a different purpose than your fee recipient, which receives transaction fee tips from proposed blocks.

Partial Withdrawals vs Full Withdrawals?

• Full validator withdrawal: To withdraw your entire stake on Ethereum and no longer perform validator duties. Exit your validator, and then after your exit request progresses through the withdraw queue while finally your full validator balance is transferred to your withdrawal address.

• Partial validator withdrawal: To withdraw your validator’s earnings only. For a validator, any amount over the initial 32 ETH deposit is the earnings and is automatically swept every few days to the withdrawal address.

I don't have a mnemonic phrase. I used a private key.

In step 2, use this credentials set command instead.

ethdo validator credentials set --private-key=<my-priv-key> --withdrawal-address=<my-eth-withdrawal-address>

I want different withdrawal addresses for each of my validators.

In step 2, use this credentials set command instead.

ethdo validator credentials set --mnemonic="<my-mnemonic-phrase>" --path='m/12381/3600/<my iTH validator>/0' --withdrawal-address=<my-eth-withdrawal-address>

Where the path is the derivation path to your withdrawal key.

• For example, m/12381/3600/i/0 is the path to a withdrawal key, where i starts at 0 for your 1st validator, 1 for your 2nd validator ...

I need to change my withdrawal address.

The only way to change withdrawal addresses is to perform a full withdrawal by exiting a validator and then, creating a new validator key as if starting the staking journey over again.