tags: Engineering, Withdrawal

BLS->0x01 withdrawal credential change: start_index search

Background

Each seed phrase can be used to generate an unlimited number of (public_key, private_key) pairs. For the technically curious ones, please reference: BLS key generation. For most of the stakefish users, you only need to know this: in order to perform the BLS->0x01 withdrawal credential change, you need to control the private key for that corresponding withdrawal credential. If you know the seed phrase, you need to know the corresponding start_index to generate the (withdrawal_credential, private_key) pair.

This is why tools such as the staking-deposit-cli and Wagyu key gen ask you for a start index, as shown in the image below.

The problem

The common case is that a start_index of 0 was used at deposit time. However, we also noticed that some of our users used non-zero start_index at deposit time, and they have forgotten what start_index they used, so they struggled with the BLS->0x01 withdrawal credential change.

If you used the correct secret phrase but see this error: “Those BLS credentials do not match those we can derive from your Secret Recovery Phrase”, this documentation will likely help you resolve the issue.

This documentation contains instructions about how to figure the corresponding start_index for a withdrawal credential.

staking-deposit-cli and Wagyu key gen behavior when reusing withdrawal credentials

At stakefish, most users reused the same withdrawal credential (with start_index 0) for multiple validators. This might cause confusion when they use the staking-deposit-cli or Wagyu key gen to perform the BLS->0x01 withdrawal credential change.

When generating the BLS->0x01 change one at a time, both staking-deposit-cli and Wagyu will work as expected. However, when trying to generate multiple BLS->0x01 changes in batches, both staking-deposit-cli and Wagyu key gen make an assumption to auto-increment the start_index. If you reused withdrawal credentials across multiple validators, this assumption is incorrect. Our recommendation is to generate the BLS->0x01 change one by one. (If you are familiar with shell scripting, you can also wrap the CLI command in a for loop to generate the BLS->0x01 messages in batches.)

Instructions

Consider an example: you want to change the withdrawal credential for a validator. You have the seed phrase/mnemonic, but forgot the start_index you used.

Step 1: look up the current withdrawal credential

You can find the withdrawal credential on beaconcha.in by specifying the validator index or its public key and then clicking on the deposit tab.

As an example, see this validator.

Step 2: generate many keys

We will use the Wagyu key gen as an example, but you can also use the staking-deposit-cli to do this step.

Reminder:

• handle your secret phrase in an offline environment for maximum security.
• stakefish staff will never ask for your secret phrase or private key.

Step by step walk-through:

In the above image, we instruct Wagyu key gen to generate 100 keys starting from the start_index of 0. That is, we will generate keys corresponding to start indices 0,1,2,…,99.

After this step, continue to follow instructions to save the generated keys in a folder of your choice. Note that key generation is a computation intensive process and this will take some time.

After the key generation is done, you should see a folder with the following contents:

• 1 deposit_data-XXXXX.json file
• 100 keystore-m_XXXXX.json files

The file we will need is the deposit_data-XXXXXXX.json file. Let’s parse the content first.

• Open the deposit_data-XXXXXXX.json in your favorite text editor and copy the JSON text.
• Open a JSON parser, such as: https://jsonformatter.org/json-parser.
• Paste in the JSON text and you should see parsed result like the below.
• You can use Ctrl+F or CMD+F in your browser to search your withdrawal credential and find the corresponding start_index.

Note: the instructions above only generated 100 keys. If you used a larger start_index, you will need to generate more keys to find yours.