Guide to Configuring Withdrawal Credentials on Ethereum

12 min readApr 11, 2023

Last updated: 14-April-2024

This is a step-by-step guide to configure withdrawal credentials for validators on the Ethereum blockchain.

Disclaimer

This article (the guide) is for informational purposes only and does not constitute professional advice. The author does not guarantee accuracy of the information in this article and the author is not responsible for any damages or losses incurred by following this article. A full disclaimer can be found at the bottom of this page — please read it before continuing.

Acknowledgements
Support
Prerequisites
Requirements
Overview
Step 1 — Determine Validator Status
Step 2 — Gather Validator Information
Step 3 — Gather Required Software
Step 4 — Generate the Signed Message
Step 5 — Submit the Signed Message for Broadcast
Step 6 — The Good Stuff
Final Remarks and Recommended Next Steps
Full Disclaimer

Acknowledgements

Thanks to the EthStaker Admins and Educators, the Ethereum Execution and Consensus Client teams, the Ethereum core developers and researchers, and the Ethereum staking community for all of their amazing contributions, feedback, and support.

Support

For technical support reach out to:

The EthStaker community on Reddit or Discord. Knowledgeable and friendly community passionate about staking on Ethereum.

Prerequisites

This guide assumes some knowledge of Ethereum, ETH, and staking ETH and also assumes that you are in possession of an active Ethereum staking validator.

Requirements

The following are required to complete this guide:

A machine connected to the internet to gather validator data and download required software.
An air-gapped machine where the software can be run (strongly recommended). If you don’t have one you can create one using a USB drive on any computer that is disconnected from the internet.
A USB drive to move data and software from the connected machine to the air-gapped machine.

Overview

On April 12, 2023 the Shanghai & Capella hard fork was successfully executed, enabling withdrawal functionality for stakers on the Ethereum network.

Withdrawals in this context are either ETH staking rewards, paid out regularly for performing validator duties, or the ETH staking deposit if the validator is exited.

NOTE: These withdrawals are different to the fee recipient which was enabled after The Merge for receiving rewards (tips) for prioritizing block production.

To enable withdrawals for your validator you must set withdrawal credentials (also known as a withdrawal address) for your validator.

The conceptual flow through the guide is:

Determine if your validator withdrawal credentials have been set
If not, gather the necessary validator information to set it
Generate a signed message with the validator information
Broadcast the signed message to update the validator

Let’s get started!

Step 1 — Determine Validator Status

If your validator withdrawal credentials have already been set (if you used the eth1_withdrawal_address flag when creating it) there is nothing more to do and you can stop here. If you are unsure, check by replacing <YourEthDepositAddress> in the link below with the Eth address you used to deposit your 32 ETH in the Ethereum staking deposit contract.

https://beaconcha.in/validators/deposits?q=<YourEthDepositAddress>

A table of validators (if you have more than one) will show. The Withdrawal Credential column indicates the status of each validator.

If the Withdrawal Credential column shows 0x01 in green text (also known as “type 1”), the withdrawal credentials have been set. You have nothing more to do. Thanks for reading!

If the Withdrawal Credential column shows 0x00 in yellow text (also known as “type 0”), they withdrawal credentials MAY NOT have been set. To further verify, click on each Validator Key.

If the withdrawal credential has been updated, it will confirm that on the Deposits tab. If all of your validators are updated, you have nothing more to do. Thanks for reading!

If one or more of your validators have not been updated, the Deposit tab will look like below. Read on.

Step 2 — Gather Validator Information

Information about each validator is required to set the withdrawal credentials.

The index position of the validator.
The index number of the validator.
The old BLS withdrawal credentials of the validator.
The Eth1 address for the new withdrawal credentials.
The mnemonic used to create the validator.

We will go though each item in detail.

As you go thorough these next sections, save the validator information to a text file so you can reference it later. However, DO NOT save your mnemonic to the text file.

Index Position of the Validator

When you first created the validator it was assigned an index position. If you created a single validator, the index position is 0. If you created more than one, it will be a sequence of numbers starting from 0.

The index position is used to indicate which validators you want to set withdrawal credentials for. For example, if you created 3 validators and you want to generate withdrawal credentials for all 3, the index position would be 0. If you want to generate withdrawal credentials for the second one, the index position would be 1. If you want to generate withdrawal credentials for the last 2 of 3 validators, it would also be 1.

The value for this must be a single number (not a list of numbers).

Index Number of the Validator

Each validator is assigned an index number when it joins the beacon chain. To find the validator index number use the look-up in Step 1 to find the validator(s) associated with your ETH deposit address.

For each validator, click on the Validator Key. It will load a page that shows the validator index number at the top.

In this example, the index is 107619. If you have multiple validators, separate the validator index numbers with a comma. E.g. 107619,107620,107621.

Note: If you have more than one validator, the index numbers should be listed in the correct order or you will get an error when you submit the signed message. The correct order is the validator index numbers aligned to the deposit data files in the order they were generated when you first created the validators. Generally, if the index numbers are listed in ascending order like the example above, you probably should be good. If you get an error adjust the sequence and try again.

Old BLS Withdrawal Credentials of the Validator

This is the withdrawal credential that was originally assigned to your validator when it was created. Use the look-up in Step 1 to find the validator(s) associated with your ETH deposit address.

The Withdrawal Credential column contains the old BLS withdrawal credential for each validator. In this example, the credential is 0x009690e5d4472c7c0dbdf490425d89862535d2a52fb686333f3a0a9ff5d2125e. If you have multiple validators, separate the BLS withdrawal credentials with a comma. E.g. 0x00..,0x00..,0x00...

Eth1 Address for the New Withdrawal Credentials

This is the Eth1 address that will be the new withdrawal credentials. This must be an address that is WITHIN YOUR CONTROL. It is where all the ETH staking rewards will be sent. It is also the address where the staked ETH deposit is sent if you exit your validator.

CRITICAL — the private keys associated with this address must be within your control or you will not be able to access the withdrawn ETH. DO NOT use an exchange account address (like on Binance or Coinbase), for example.

It should be a valid Ethereum address. For example, 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045.

Mnemonic Used to Create the Validator

This is the mnemonic that was created by the staking-deposit-cli tool when you generated the validator files. You will need to provide it later when generating the signed message. DO NOT save it to the text file.

NOTE: If you have used multiple mnemonics to create your validators, you will need to gather the validator information and run through the steps to generate a signed message for each mnemonic and its associated validator(s).

That should be it. After gathering this information the resulting text file might look something like this:

Index Position: 0
Index Number: 1000,1001
Old BLS: 0x00c223a861a98d56881969d0ecf771dfd76c1b7c1d423a7f9019a44ff7aec040,0x009690e5d4472c7c0dbdf490425d89862535d2a52fb686333f3a0a9ff5d2125e
Eth1 Address: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

Save the file to the USB drive so we can copy it to the air-gapped machine later.

Step 3 — Gather Required Software

The staking-deposit-cli tool will be used to generate the signed message using the validator information gathered above. Download it, decompress it, and copy it to the USB drive.

Go here to get the Latest version and download for the required platform.

Unzip the downloaded file on Windows.
Use the following commands to download and decompress for Linux. Modify the URL below to match the download link for the latest version.

$ cd ~
$ curl -LO https://github.com/ethereum/staking-deposit-cli/releases/download/v2.5.0/staking_deposit-cli-d7b5304-linux-amd64.tar.gz
$ tar xvf staking_deposit-cli-d7b5304-linux-amd64.tar.gz
$ cd staking_deposit-cli-d7b5304-linux-amd64

Copy the file to the USB drive.

The USB drive should now contain the text file created above and the deposit or deposit.exe binary file.

Step 4 — Generate the Signed Message

Next we will generate a signed message that contains the information necessary to update the withdrawal credentials.

The staking-deposit-cli tool uses the mnemonic to sign the message. Due to the sensitive nature of the mnemonic, it is STRONGLY recommended that you run the tool on a computer that is not connected to the internet.

There are different ways to proceed; two options are provided below.

Option 1: Air-Gapped Machine (recommended) — Connect the USB drive to a fully air-gapped machine (never previously connected to a network or the internet) and copy the files to the air-gapped machine.

Option 2: Current Machine (not recommended) — Run from the current machine. An internet connection may be an opportunity to leak your mnemonic key. If a fully air-gapped machine isn’t available, disconnect the network/internet on the current machine before proceeding.

On the secure machine, run the binary file and copy/paste the data in the text file to supply the required information.

On Linux:

$ sudo ./deposit generate-bls-to-execution-change

On Windows:

deposit.exe generate-bls-to-execution-change

Provide your language preference.

Choose the network. Mainnet is for production, others are testnets.

Enter your Mnemonic.

Enter the Index Position.

Enter the Validator Number(s).

Enter the Old BLS Withdrawal Credentials.

Enter the Eth1 address that will be the new withdrawal address.

Enter it again and be ABSOLUTELY SURE it’s correct. Once set, it cannot be updated or changed.

Success!

NOTE: There is validation at this step to ensure the Old BLS Withdrawal Credentials were created by the mnemonic you provided. If they do not match, the process will fail. E.g. “[Error] The given withdrawal credentials does not match the old BLS withdrawal credentials that mnemonic generated.” Make sure you provided the correct mnemonic and you typed it correctly.

The SignedBLSToExecutionChange JSON file is created at the specified location. The contents of the directory are shown below.

The file contains the credential change data for each validator. It is signed, so you should not manually modify any of the contents.

Check it carefully, particularly the "to_execution_address”. If you notice an error, delete the JSON file and go through the process of generating it again with the correct values.

If you ran this from an air-gapped machine, copy the SignedBLSToExecutionChange JSON file onto the USB drive.

Step 5 — Submit the Signed Message for Broadcast

Connect the USB drive with the SignedBLSToExecutionChange JSON file created above to a machine that has internet access.

The Beaconcha.in crew have kindly provided a utility to submit withdrawal credential changes for broadcast to the beacon chain. If you are submitting a signed message for mainnet then go here in a browser:

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

If you are submitting for a testnet, then adjust the URL to the appropriate testnet name.

NOTE: As a final CAUTION— once the withdrawal credentials are set, they can never be changed again. You should make absolutely sure the withdrawal address is correct before you submit.

Provide the JSON file as prompted, and after carefully checking everything again, click on the Submit & Broadcast button.

NOTE: There is additional validation at this point to ensure the old BLS withdrawal credentials provided match the validator Index. If they do not match, submission will not work. E.g. “fromBLSPubkey do not match withdrawalCredentials for validator with index 1000”. Go back and regenerate the signed message JSON file with the correct values.

If your request was received successfully, a receipt will be displayed.

You now have provided a signed message to update your validator withdrawal credentials. It will be broadcast (at the earliest opportunity) over the beacon chain. Probably a good time to get a fresh beverage and hydrate.

Congratulations: Your validator(s) will soon be 0x01 and that is awesome!

Step 6 — The Good Stuff

Once the withdrawal credentials have been set there are a few things you can check. In the link below, replace <YourValidatorIndex> with the index of your validator.

https://beaconcha.in/validator/<YourValidatorIndex>

The Deposits tab will confirm the withdrawal credentials have been successfully changed.

The Withdrawals tab will will show the pending ETH rewards and an approximate time to payout.

That’s it!

Final Remarks and Recommended Next Steps

Thanks for the opportunity. Hopefully this guide was helpful for you.

Next steps

Read more about withdrawals here and here and here.
Get familiar with beaconcha.in so you can monitor your validators
Use the beaconcha.in mobile app to monitor your validators
Join the Ethstaker Discord for important notifications
Share feedback on Discord (somer112), Twitter, or Reddit
Help others on the EthStaker Discord or EthStaker Reddit
Share this guide with your friends!
Tips appreciated:
- somer.eth
- 0x32B74B90407309F6637245292cd90347DE658A37

Full Disclaimer

This article (the guide) is for informational purposes only and does not constitute professional advice. The author does not warrant or guarantee the accuracy, integrity, quality, completeness, currency, or validity of any information in this article. All information herein is provided “as is” without warranty of any kind and is subject to change at any time without notice. The author disclaims all express, implied, and statutory warranties of any kind, including warranties as to accuracy, timeliness, completeness, or fitness of the information in this article for any particular purpose. The author is not responsible for any direct, indirect, incidental, consequential or any other damages arising out of or in connection with the use of this article or in reliance on the information available on this article. This includes any personal injury, business interruption, loss of use, lost data, lost profits, or any other pecuniary loss, whether in an action of contract, negligence, or other misuse, even if the author has been informed of the possibility.