- Introduction
- Tutorial for users
- Build requirements
- For Linux or MacOS users
- File Permissions
- Option 1. Download binary executable file
- Step 1. Installation
- Step 2. Create keys and
deposit_data-*.jsonlanguageArgument--non_interactiveflag--ignore_connectivityflag- Commands
new-mnemonicArgumentsexisting-mnemonicArguments- Successful message
generate-bls-to-execution-changeArgumentsgenerate-bls-to-execution-change-keystoreArgumentsexit-transaction-keystoreArgumentsexit-transaction-mnemonicArgumentspartial-depositArgumentstest-keystoreArguments
- Option 2. Build
deposit-cliwith native Python - Option 3. Build
deposit-cliwithvirtualenv - Option 4. Use published docker image
- Option 5. Use local docker image
- For Windows users
- Development
- Canonical Deposit Contract and Launchpad
ethstaker-deposit-cli is a tool for creating EIP-2335 format BLS12-381 keystores and a corresponding deposit_data*.json file for Ethereum Staking Launchpad. One can also provide a keystore file to generate a signed_exit_transaction*.json file to be broadcast at a later date to exit a validator.
- Warning: Please generate your keystores on your own safe, completely offline device.
- Warning: Please backup your mnemonic, keystores, and password securely.
Please read Launchpad Validator FAQs before generating the keys.
You can find the audit report by Trail of Bits here.
On Unix-based systems, keystores and the deposit_data*.json have 440/-r--r----- file permissions (user & group read only). This improves security by limiting which users and processes that have access to these files. If you are getting permission denied errors when handling your keystores, consider changing which user/group owns the file (with chown) or, if need be, change the file permissions with chmod.
See releases page to download and decompress the corresponding binary files.
Run the following command to enter the interactive CLI and generate keys from a new mnemonic:
./deposit new-mnemonicor run the following command to enter the interactive CLI and generate keys from an existing:
./deposit existing-mnemonicThe Launchpad offers many language/internationalization options. If you wish to select one as a CLI argument, it must be passed in before one of the commands is chosen.
| Argument | Type | Description |
|---|---|---|
--language |
String. Options: العربية, ελληνικά, English, Français, Bahasa melayu, Italiano, 日本語, 한국어, Português do Brasil, român, 简体中文. Default to English |
The language you wish to use the CLI in. |
Warning: With this flag, there will be no confirmation step(s) to verify the input value(s). This will also ignore the connectivity check. Please use it carefully.
| Argument | Type | Description |
|---|---|---|
--non_interactive |
Flag | Run CLI in non-interactive mode. |
Warning: It is strongly recommended not to use this tool with internet access. Ignoring this check can further the risk of theft and compromise of your generated key material.
| Argument | Type | Description |
|---|---|---|
--ignore_connectivity |
Flag | Skip internet connectivity check and warning. |
The CLI offers different commands depending on what you want to do with the tool.
| Command | Description |
|---|---|
new-mnemonic |
(Recommended) This command is used to generate keystores with a new mnemonic. |
existing-mnemonic |
This command is used to re-generate or derive new keys from your existing mnemonic. Use this command, if (i) you have already generated keys with this CLI before, (ii) you want to reuse your mnemonic that you know is secure that you generated elsewhere (reusing your eth wallet mnemonic .etc), or (iii) you lost your keystores and need to recover your keys. |
generate-bls-to-execution-change |
This command is used to generate BLS to execution address change message. This is used to add a withdrawal address to a validator that does not currently have one. |
generate-bls-to-execution-change-keystore |
This command is used to sign a BLS to execution address change message with the provided validator key. This is used for a proposed solution to update withdrawal credentials for users who have lost their mnemonic. |
exit-transaction-keystore |
This command is used to create an exit transaction using a keystore file. |
exit-transaction-mnemonic |
This command is used to create an exit transaction using a mnemonic phrase. |
partial-deposit |
This command is used to create a deposit file using a keystore file. |
test-keystore |
This command is used to verify access to the provided keystore file by attempting to decrypt it with the provided keystore password. |
You can use new-mnemonic --help to see all arguments. Note that if there are missing arguments that the CLI needs, it will ask you for them.
| Argument | Type | Description |
|---|---|---|
--num_validators |
Non-negative integer | The number of signing keys you want to generate. Note that the child key(s) are generated via the same master key. |
--mnemonic_language |
String. Options: 简体中文, 繁體中文, český jazyk, English, Italiano, 한국어, Português, Español. Default to English |
The language of the mnemonic word list |
--folder |
String. Pointing to ./validator_keys by default |
The folder path for the keystore(s) and deposit(s) |
--chain |
String. mainnet by default |
The chain setting for the signing domain. |
--keystore_password |
String | The password that will secure your keystores. You will need to re-enter this to decrypt them when you setup your Ethereum validators. It is recommended not to use this argument when running interactively, and wait for the CLI to ask you for your password, as otherwise it will appear in your shell history. When used in a script, please be sure to also use --non_interactive. A future version may enforce this. |
--withdrawal_address |
String. Ethereum execution address in hexadecimal encoded form | If this field is set and valid, the given execution address will be used to create the withdrawal credentials. Otherwise, it will generate withdrawal credentials with the mnemonic-derived withdrawal public key in ERC-2334 format. |
--pbkdf2 |
Flag | Will use pbkdf2 key derivation instead of scrypt for generated keystore files as defined in EIP-2335. This can be a good alternative if you intend to work with a large number of keys. |
You can use existing-mnemonic --help to see all arguments. Note that if there are missing arguments that the CLI needs, it will ask you for them.
| Argument | Type | Description |
|---|---|---|
--validator_start_index |
Non-negative integer | The index of the first validator's keys you wish to generate. If this is your first time generating keys with this mnemonic, use 0. If you have generated keys using this mnemonic before, use the next index from which you want to start generating keys from. As an example if you've generated 4 keys before (keys #0, #1, #2, #3), then enter 4 here. |
--num_validators |
Non-negative integer | The number of new signing keys you want to generate. Note that the child key(s) are generated via the same master key. |
--folder |
String. Pointing to ./validator_keys by default |
The folder path for the keystore(s) and deposit(s) |
--chain |
String. mainnet by default |
The chain setting for the signing domain. |
--keystore_password |
String | The password that will secure your keystores. You will need to re-enter this to decrypt them when you setup your Ethereum validators. It is recommended not to use this argument when running interactively, and wait for the CLI to ask you for your password, as otherwise it will appear in your shell history. When used in a script, please be sure to also use --non_interactive. A future version may enforce this. |
--withdrawal_address |
String. Ethereum execution address in hexadecimal encoded form | If this field is set and valid, the given execution address will be used to create the withdrawal credentials. Otherwise, it will generate withdrawal credentials with the mnemonic-derived withdrawal public key in ERC-2334 format. |
--pbkdf2 |
Flag | Will use pbkdf2 key derivation instead of scrypt for generated keystore files as defined in EIP-2335. This can be a good alternative if you intend to work with a large number of keys. |
You will see the following messages after successfully generated the keystore(s) and the deposit(s):
Creating your keys: [####################################] <N>/<N>
Creating your keystores: [####################################] <N>/<N>
Creating your depositdata: [####################################] <N>/<N>
Verifying your keystores: [####################################] <N>/<N>
Verifying your deposits: [####################################] <N>/<N>
Success!
Your keys can be found at: <YOUR_FOLDER_PATH>
You can use generate-bls-to-execution-change --help to see all arguments. Note that if there are missing arguments that the CLI needs, it will ask you for them.
| Argument | Type | Description |
|---|---|---|
--bls_to_execution_changes_folder |
String. Pointing to ./bls_to_execution_changes by default |
The folder path for the bls_to_execution_change-* JSON file(s) |
--chain |
String. mainnet by default |
The chain setting for the signing domain. |
--mnemonic |
String. mnemonic split by space. | The mnemonic you used to create withdrawal credentials. |
--mnemonic_password |
Optional string. Empty by default. | The mnemonic password you used in your key generation. Note: It's not the keystore password. |
--validator_start_index |
Non-negative integer | The index position for the keys to start generating withdrawal credentials in ERC-2334 format. |
--validator_indices |
String of integer(s) | A list of the chosen validator index number(s) as identified on the beacon chain. Split multiple items with whitespaces or commas. |
--bls_withdrawal_credentials_list |
String of hexstring(s). | A list of the old BLS withdrawal credentials of the given validator(s). It is for confirming you are using the correct keys. Split multiple items with whitespaces or commas. |
--withdrawal_address |
String. Ethereum execution address in hexadecimal encoded form | If this field is set and valid, the given execution address will be used to create the withdrawal credentials. Otherwise, it will generate withdrawal credentials with the mnemonic-derived withdrawal public key in ERC-2334 format. |
--devnet_chain_setting |
String. JSON string '{"network_name": "<NETWORK_NAME>", "genesis_fork_version": "<GENESIS_FORK_VERSION>", "exit_fork_version": "<EXIT_FORK_VERSION>", "genesis_validator_root": "<GENESIS_VALIDATOR_ROOT>"}' |
The custom chain setting of a devnet or testnet. Note that it will override your --chain choice. |
You can use generate-bls-to-execution-change-keystore --help to see all arguments. Note that if there are missing arguments that the CLI needs, it will ask you for them.
| Argument | Type | Description |
|---|---|---|
--chain |
String. mainnet by default |
The chain setting for the signing domain. |
--keystore |
File | The keystore file associating with the validator you wish to sign with. This keystore file should match the provided validator index. |
--keystore_password |
String | The password that is used to encrypt the provided keystore. Note: It's not your mnemonic password. |
--validator_index |
Integer | The validator index corresponding to the provided keystore. |
--withdrawal_address |
String. Ethereum execution address in hexadecimal encoded form that you wish to set as your withdrawal credentials. | |
--output_folder |
String. Pointing to ./bls_to_execution_changes_keystore by default |
The folder path for the bls_to_execution_change_keystore_signature-* JSON file |
--devnet_chain_setting |
String. JSON string '{"network_name": "<NETWORK_NAME>", "genesis_fork_version": "<GENESIS_FORK_VERSION>", "exit_fork_version": "<EXIT_FORK_VERSION>", "genesis_validator_root": "<GENESIS_VALIDATOR_ROOT>"}' |
The custom chain setting of a devnet or testnet. Note that it will override your --chain choice. |
You can use exit-transaction-keystore --help to see all arguments. Note that if there are missing arguments that the CLI needs, it will ask you for them.
| Argument | Type | Description |
|---|---|---|
--chain |
String. mainnet by default |
The chain setting for the signing domain. |
--keystore |
File | The keystore file associating with the validator you wish to exit. |
--keystore_password |
String | The password that is used to encrypt the provided keystore. Note: It's not your mnemonic password. |
--validator_index |
Integer | The validator index corresponding to the provided keystore. |
--epoch |
Optional integer. 0 by default | The epoch of when the exit transaction will be valid. The transaction will always be valid by default. |
--output_folder |
String. Pointing to ./exit_transaction by default |
The folder path for the signed_exit_transaction-* JSON file |
You can use exit-transaction-mnemonic --help to see all arguments. Note that if there are missing arguments that the CLI needs, it will ask you for them.
| Argument | Type | Description |
|---|---|---|
--chain |
String. mainnet by default |
The chain setting for the signing domain. |
--mnemonic |
String. mnemonic split by space. | The mnemonic you used during key generation. |
--mnemonic_password |
Optional string. Empty by default. | The mnemonic password you used in your key generation. Note: It's not the keystore password. |
--validator_start_index |
Non-negative integer | The index position for the keys to start generating keystores in ERC-2334 format. |
--validator_indices |
String of integer(s) | A list of the chosen validator index number(s) as identified on the beacon chain. Split multiple items with whitespaces or commas. |
--epoch |
Optional integer. 0 by default | The epoch of when the exit transaction will be valid. The transaction will always be valid by default. |
--output_folder |
String. Pointing to ./exit_transaction by default |
The folder path for the signed_exit_transaction-* JSON file |
You can use partial-deposit --help to see all arguments. Note that if there are missing arguments that the CLI needs, it will ask you for them.
| Argument | Type | Description |
|---|---|---|
--chain |
String. mainnet by default |
The chain setting for the signing domain. |
--keystore |
File | The keystore file associating with the validator you wish to deposit to. |
--keystore_password |
String | The password that is used to encrypt the provided keystore. Note: It's not your mnemonic password. |
--amount |
Float. 32 by default |
The amount you wish to deposit. Must be in ether, at least 1 ether, and can not have higher precision than 1 gwei. |
--withdrawal_address |
String. Ethereum execution address in hexadecimal encoded form | The withdrawal address of the existing validator or the desired withdrawal address. |
--output_folder |
String. Pointing to ./partial_deposit by default |
The folder path for the deposit-* JSON file |
You can use test-keystore --help to see all arguments. Note that if there are missing arguments that the CLI needs, it will ask you for them.
| Argument | Type | Description |
|---|---|---|
--keystore |
File | The keystore file you wish to verify. |
--keystore_password |
String | The password used to attempt decryption of the provided keystore file. Note: It is not your mnemonic password. |
Ensure you are using Python version >= Python3.9:
python3 -VInstall the dependencies:
pip3 install -r requirements.txtOr use the helper script:
./deposit.sh installRun one of the following command to enter the interactive CLI:
./deposit.sh new-mnemonicor
./deposit.sh existing-mnemonicYou can also run the tool with optional arguments:
./deposit.sh new-mnemonic --num_validators=<NUM_VALIDATORS> --mnemonic_language=english --chain=<CHAIN_NAME> --folder=<YOUR_FOLDER_PATH>./deposit.sh existing-mnemonic --num_validators=<NUM_VALIDATORS> --validator_start_index=<START_INDEX> --chain=<CHAIN_NAME> --folder=<YOUR_FOLDER_PATH>See here for --language arguments.
See here
See here for new-mnemonic arguments
See here for existing-mnemonic arguments
See here for generate-bls-to-execution-change arguments
See here for generate-bls-to-execution-change-keystore arguments
See here for exit-transaction-keystore arguments
See here for exit-transaction-mnemonic arguments
See here for partial-deposit arguments
See here for test-keystore arguments
See here
Ensure you are using Python version >= Python3.9:
python3 -VInstall venv if not already installed, e.g. for Debian/Ubuntu:
sudo apt update && sudo apt install python3-venvCreate a new virtual environment:
python3 -m venv .venv
source .venv/bin/activateand install the dependencies:
pip3 install -r requirements.txtRun one of the following command to enter the interactive CLI:
python3 -m ethstaker_deposit new-mnemonicor
python3 -m ethstaker_deposit existing-mnemonicYou can also run the tool with optional arguments:
python3 -m ethstaker_deposit new-mnemonic --num_validators=<NUM_VALIDATORS> --mnemonic_language=english --chain=<CHAIN_NAME> --folder=<YOUR_FOLDER_PATH>python3 -m ethstaker_deposit existing-mnemonic --num_validators=<NUM_VALIDATORS> --validator_start_index=<START_INDEX> --chain=<CHAIN_NAME> --folder=<YOUR_FOLDER_PATH>See here for --language arguments.
See here
See here for new-mnemonic arguments
See here for existing-mnemonic arguments
See here for generate-bls-to-execution-change arguments
See here for generate-bls-to-execution-change-keystore arguments
See here for exit-transaction-keystore arguments
See here for exit-transaction-mnemonic arguments
See here for partial-deposit arguments
See here for test-keystore arguments
Run the following command to pull the latest docker image published on the Github repository:
docker pull ghcr.io/eth-educators/ethstaker-deposit-cli:latestRun the following command to enter the interactive CLI:
docker run -it --rm -v $(pwd)/validator_keys:/app/validator_keys ghcr.io/eth-educators/ethstaker-deposit-cli:latestYou can also run the tool with optional arguments:
docker run -it --rm -v $(pwd)/validator_keys:/app/validator_keys ghcr.io/eth-educators/ethstaker-deposit-cli:latest new-mnemonic --num_validators=<NUM_VALIDATORS> --mnemonic_language=englishExample for 1 validator on the Holesky testnet using english:
docker run -it --rm -v $(pwd)/validator_keys:/app/validator_keys ghcr.io/eth-educators/ethstaker-deposit-cli:latest new-mnemonic --num_validators=1 --mnemonic_language=english --chain=holeskyRun the following command to locally build the docker image:
make build_dockerRun the following command to enter the interactive CLI:
docker run -it --rm -v $(pwd)/validator_keys:/app/validator_keys eth-educators/ethstaker-deposit-cliYou can also run the tool with optional arguments:
docker run -it --rm -v $(pwd)/validator_keys:/app/validator_keys eth-educators/ethstaker-deposit-cli new-mnemonic --num_validators=<NUM_VALIDATORS> --mnemonic_language=englishExample for 1 validator on the Holesky testnet using english:
docker run -it --rm -v $(pwd)/validator_keys:/app/validator_keys eth-educators/ethstaker-deposit-cli new-mnemonic --num_validators=1 --mnemonic_language=english --chain=holeskySee here
See here
See releases page to download and decompress the corresponding binary files.
Run one of the following command to enter the interactive CLI:
deposit.exe new-mnemonicor
deposit.exe existing-mnemonicYou can also run the tool with optional arguments:
deposit.exe new-mnemonic --num_validators=<NUM_VALIDATORS> --mnemonic_language=english --chain=<CHAIN_NAME> --folder=<YOUR_FOLDER_PATH>deposit.exe existing-mnemonic --num_validators=<NUM_VALIDATORS> --validator_start_index=<START_INDEX> --chain=<CHAIN_NAME> --folder=<YOUR_FOLDER_PATH>See here for --language arguments.
See here
See here for new-mnemonic arguments
See here for existing-mnemonic arguments
See here for generate-bls-to-execution-change arguments
See here for generate-bls-to-execution-change-keystore arguments
See here for exit-transaction-keystore arguments
See here for exit-transaction-mnemonic arguments
See here for partial-deposit arguments
See here for test-keystore arguments
Ensure you are using Python version >= Python12 (Assume that you've installed Python 3 as the main Python):
python -VInstall the dependencies:
pip3 install -r requirements.txtOr use the helper script:
sh deposit.sh installRun one of the following command to enter the interactive CLI:
./deposit.sh new-mnemonicor
./deposit.sh existing-mnemonicYou can also run the tool with optional arguments:
./deposit.sh new-mnemonic --num_validators=<NUM_VALIDATORS> --mnemonic_language=english --chain=<CHAIN_NAME> --folder=<YOUR_FOLDER_PATH>./deposit.sh existing-mnemonic --num_validators=<NUM_VALIDATORS> --validator_start_index=<START_INDEX> --chain=<CHAIN_NAME> --folder=<YOUR_FOLDER_PATH>See here for --language arguments.
See here
See here for new-mnemonic arguments
See here for existing-mnemonic arguments
See here for generate-bls-to-execution-change arguments
See here for generate-bls-to-execution-change-keystore arguments
See here for exit-transaction-keystore arguments
See here for exit-transaction-mnemonic arguments
See here for partial-deposit arguments
See here for test-keystore arguments
Ensure you are using Python version >= Python3.9 (Assume that you've installed Python 3 as the main Python):
python -VCreate a new virtual environment:
python3 -m venv .venv
.\.venv\Scripts\activateand install the dependencies:
pip3 install -r requirements.txtRun one of the following command to enter the interactive CLI:
python -m ethstaker_deposit new-mnemonicor
python -m ethstaker_deposit existing-mnemonicYou can also run the tool with optional arguments:
python -m ethstaker_deposit new-mnemonic --num_validators=<NUM_VALIDATORS> --mnemonic_language=english --chain=<CHAIN_NAME> --folder=<YOUR_FOLDER_PATH>python -m ethstaker_deposit existing-mnemonic --num_validators=<NUM_VALIDATORS> --validator_start_index=<START_INDEX> --chain=<CHAIN_NAME> --folder=<YOUR_FOLDER_PATH>See here for --language arguments.
See here
See here for new-mnemonic arguments
See here for existing-mnemonic arguments
See here for generate-bls-to-execution-change arguments
See here for generate-bls-to-execution-change-keystore arguments
See here for exit-transaction-keystore arguments
See here for exit-transaction-mnemonic arguments
See here for partial-deposit arguments
See here for test-keystore arguments
python3 -m pip install -r requirements.txtpython3 -m pip install -r requirements_test.txtpython3 -m pytest testspython3 -m ethstaker_deposit [OPTIONS] COMMAND [ARGS]Install pre-commit if not already installed, e.g. for Debian/Ubuntu:
sudo apt update && sudo apt install pre-commitEnable it for your git commit workflow:
pre-commit installDevelopers Only
ethstaker-deposit uses pyinstaller to create binaries. The requirements are in build_configs. Look at .github/workflows/build.yml to see it in action.
For example Linux, in your Python virtual environment:
export BUILD_FILE_NAME=ethstaker_deposit-cli-dev-linux
pip install -r ./build_configs/linux/requirements.txt
pyinstaller --distpath ./${BUILD_FILE_NAME} ./build_configs/linux/build.specEthstaker confirms the canonical Ethereum staking deposit contract addresses and launchpad URLs. Please be sure that your ETH is deposited only to this deposit contract address, depending on chain.
Depositing to the wrong address will lose you your ETH.
- Ethereum mainnet
- Deposit address: 0x00000000219ab540356cBB839Cbe05303d7705Fa
- Launchpad
- Ethereum Holešky (Holešovice) testnet
- Deposit address: 0x4242424242424242424242424242424242424242
- Launchpad