Skip to main content
Version: stable (23.10.0)

Update your withdrawal credentials

When you create a validator, it’s possible to set its withdrawal address to a BLS address, or an Ethereum address.

You can update your BLS withdrawal address to an Ethereum address after the Capella upgrade.

Determine the withdrawal address type​

Prerequisites:

  • Access to the beacon node API endpoint. The default is localhost:5051.
  • curl and jq installed.

The following shell script allows you to determine the withdrawal address of a given validator ID.

VALIDATOR=<VALIDATOR_INDEX> \
curl http://localhost:5051/eth/v1/beacon/states/finalized/validators/$VALIDATOR | jq '.data | .validator.withdrawal_credentials'

In the script, specify the <VALIDATOR_INDEX> (for example, 1) that was provided when you joined the network. Alternatively, you can specify the validator's public key.

In the output, the first four characters of the string, in this case 0x00, indicates the key is a BLS withdrawal key.

Update your withdrawal address​

caution

Don't store your validator keys and withdrawal keys in the same location.

From a BLS withdrawal address to an Ethereum address​

caution

Teku doesn't offer functionality to create a signed withdrawal credential change. Tools such as staking-deposit-cli allow you to generate this signed message, which can be submitted directly to your beacon node if your REST API is active.

If your withdrawal address is a BLS key (starts with 0x00), the Capella fork provides a process to update your withdrawal address to a 0x01 withdrawal key (Ethereum address). You must have the BLS withdrawal address private key, or the seed phrase (mnemonic) to sign the request to prove that you have access to the BLS withdrawal key.

Tools such as staking-deposit-cli or ethdo can sign the request correctly. You can then submit the signed withdrawal credential change to your own beacon node using the bls_to_execution_changes API, or broadcast it using beaconcha.in.

Important information about changing withdrawal credentials
  • Once you update a validator to use a 0x01 withdrawal key (Ethereum address), you can't change it again.
  • Updating your withdrawal credentials isn't available until the Capella fork is active.
  • Ensure you update to the expected Ethereum address because the change is permanent.

A maximum of 16 validator keys can update their withdrawal credentials per block, so the process may be congested initially. If you submit a request to update your key, and it hasn't been done in a period of time, you might consider re-submitting the request. It might take several epochs for the change to be included in a block, depending on the number of requests in the queue.

Query the bls_to_execution_changes API see if your request is still in the pool.

Update your Ethereum address​

If your withdrawal credentials are set to an Ethereum address, and you wish to update it to a different address, you must create a new validator key. You can exit your current validator key as a voluntary exit, and use the funds from the full withdrawal of that to create the new validator key.

The voluntary exit process takes while to complete, and the exiting validator must remain active during that time to avoid inactivity penalties.

caution

Ensure that you own the current Ethereum address before exiting, otherwise you can't access your funds.