Welcome to the `ethstaker-deposit-cli`!

The ethstaker-deposit-cli is a command-line tool used to generate validator keys forked from Ethereum's staking-deposit-cli with more functionality and improved performance.

Security reports

The project has been through various security audits over the years. You can find them here:

March 4, 2026: Security assessment report by Trail of Bits
December 13, 2024: Security assessment report by Trail of Bits
September 4, 2020: Security assessment report by Trail of Bits of the original staking-deposit-cli project

This tool generates and/or utilizes mnemonics and validator key material. Both are highly sensitive materials, and their exposure could lead to the loss or theft of funds, as well as the compromise of privacy. Users must take appropriate measures to secure this information.

Here are some core recommendations:

Use this tool offline: We highly recommend using this tool in an offline environment, preferably air-gapped, using a live USB such as Tails.
Avoid using passwords or mnemonics as command line arguments: When executing any command, you will be prompted for the necessary arguments. This prevents the arguments from being stored in your command history which could create an attack vector.
Do not expose or share any material: This tool generates and uses critically secure material that should not be shared or exposed. There is an abundance of thieves that use malicious links and scam tactics to get you to expose sensitive material. Be sure to triple check any tools or websites you are using and remain vigilant.
Create backups of your mnemonic: The mnemonic generated by this tool is essential for your operation and success as a validator. Losing this mnemonic can result in significant financial loss. Carefully follow the instructions when creating a mnemonic, ensure you make a backup copy, and store it in a secure location. For long-term protection, consider using products like CryptoSteel and ColdTi, which offer resistance to the elements.

Getting Started

If you want to start creating validator keys, please follow the Quick Setup Instructions or if you would like to run locally, view the Local Development Instructions.

The general usage of the CLI is:

./deposit [OPTIONS] COMMAND [ARGS]

Command Options

Each CLI command has a number of command options that can be provided:

--language: The language you wish to use the CLI in. Options: العربية, ελληνικά, English, Deutsch, Français, Bahasa melayu, Italiano, 日本語, 한국어, Português do Brasil, român, Türkçe, 简体中文. Default to English.
--non_interactive: Run CLI in non-interactive mode. This will skip all confirmation and internet connectivity checks.
--ignore_connectivity: Skip internet connectivity check and warning.

Commands

You are not required to specify each argument when executing the command. We will prompt you for each argument for security purposes.

If there is a specific command you would like to understand more, please choose from the following list:

new-mnemonic: Used to generate a new mnemonic, validator keys, and deposit file. It is not recommended to use this command if you have existing validators.
existing-mnemonic: Provide a mnemonic to regenerate validator keys or create new ones.
generate-bls-to-execution-change: Add a withdrawal address to a validator that does not currently have one. It is required to have the corresponding mnemonic.
generate-bls-to-execution-change-keystore: Sign an update withdrawal credentials message using your validator keystore.
exit-transaction-keystore: Generate an exit message using the keystore of your validators.
exit-transaction-mnemonic: Generate an exit message using the mnemonic of your validators.
partial-deposit: Generate a deposit file with an existing validator key. Can be used to initiate a validator or deposit to an existing validator.
test-keystore: Verify access to the provided keystore file by attempting to decrypt with the provided keystore password.

Canonical Deposit Contract and Launchpad

Ethstaker 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 Hoodi testnet
- Deposit address: 0x00000000219ab540356cBB839Cbe05303d7705Fa
- Launchpad
Plataberget testnet
- Deposit address: 0x00000000219ab540356cBB839Cbe05303d7705Fa
- Validator deposits via Dora
- Plataberget is expected to be shut down by the end of 2026.
Gnosis mainnet
- Deposit address: 0x0B98057eA310F4d31F2a452B414647007d1645d9
- Gnosis Beacon Chain deposit UI
Chiado testnet
- Deposit address: 0xb97036A26259B7147018913bD58a774cf91acf25
- Gnosis Beacon Chain deposit UI

Contributing

This project is open-source and welcomes contributions from the community. If you would like to contribute to the ethstaker-deposit-cli, please read the Local Development Instructions, fork the project, and create a pull request with a description of the changes you have made and why.

Support

If you encounter any issues or have questions while using the ethstaker-deposit-cli, please contact us on the Ethstaker discord.

Quick Setup

This guide will walk you through the steps to download and set up the ethstaker-deposit-cli for your operating system.

Build requirements

Step 1: Download the Latest Release

Download binary executable file

Navigate to the Releases page of the ethstaker-deposit-cli repository.
Download the corresponding file for your operating system:
- Windows: Look for a file with windows in the name.
- MacOS: Look for a file with darwin in the name.
- Linux: Look for a file with linux in the name.
Extract the contents of the zipped file
Open a terminal or command prompt and navigate to the extracted folder

For other installation options, including building with python or virtualenv and docker image instructions, go here

Step 2: Verify the Installation

Make sure you have the GitHub CLI installed.
Verify the attestation against the corresponding file but be sure to replace the contents with the exact file name:

gh attestation verify ethstaker_deposit-cli-*******-***.*** --repo ethstaker/ethstaker-deposit-cli

This step requires you to be online. If you want to perform this offline, follow these instructions from GitHub.

You should see ✓ Verification succeeded! in the output otherwise do not continue.

Step 3: Usage

Windows users: You should replace ./deposit with deposit.exe to run properly.

MacOS users: In order to run from the terminal, you must first open the file to bypass MacOS code signing issues. Do so by right-clicking the deposit file and then selecting Open.

Linux users: 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.

Determine which command best suits what you would like to accomplish:

new-mnemonic: Used to generate a new mnemonic, validator keys, and deposit file. It is not recommended to use this command if you have existing validators.
existing-mnemonic: Provide a mnemonic to regenerate validator keys or create new ones.
generate-bls-to-execution-change: Update your withdrawal credentials of existing validators. It is required to have the corresponding mnemonic.
generate-bls-to-execution-change-keystore: Sign an update withdrawal credentials message using your validator keystore.
exit-transaction-keystore: Generate an exit message using the keystore of your validators.
exit-transaction-mnemonic: Generate an exit message using the mnemonic of your validators.
partial-deposit: Generate a partial deposit using a validator keystore.

If you encounter any issues, please check the issues page for help or to report a problem. You may also contact us on the Ethstaker discord.

Other Install Options

Linux or MacOS users

Option 1. Build `deposit-cli` with native Python

Python version checking

Ensure you are using a Python version supported by the current release:
```
python3 -V
```

Installation

Install the dependencies:

python3 -m pip install -r requirements.txt

Or use the helper script:

./deposit.sh install

Create keys and deposit_data-*.json

Run one of the following command to enter the interactive CLI:

./deposit.sh new-mnemonic

./deposit.sh existing-mnemonic

You 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>

Option 2. Build `deposit-cli` with `virtualenv`

Python version checking

Ensure you are using a Python version supported by the current release:
```
python3 -V
```

Installation

Install venv if not already installed, e.g. for Debian/Ubuntu:

sudo apt update && sudo apt install python3-venv

Create a new virtual environment:

python3 -m venv .venv
source .venv/bin/activate

and install the dependencies:

python3 -m pip install -r requirements.txt

Create keys and deposit_data-*.json

Run one of the following command to enter the interactive CLI:

python3 -m ethstaker_deposit new-mnemonic

python3 -m ethstaker_deposit existing-mnemonic

You 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>

Option 3. Use published docker image

Pull the official docker image

Run the following command to pull the latest docker image published on the Github repository:
```
docker pull ghcr.io/ethstaker/ethstaker-deposit-cli:latest
```

Create keys and deposit_data-*.json

Run the following command to enter the interactive CLI:

docker run -it --rm -v $(pwd)/validator_keys:/app/validator_keys ghcr.io/ethstaker/ethstaker-deposit-cli:latest

You can also run the tool with optional arguments:

docker run -it --rm -v $(pwd)/validator_keys:/app/validator_keys ghcr.io/ethstaker/ethstaker-deposit-cli:latest new-mnemonic --num_validators=<NUM_VALIDATORS> --mnemonic_language=english

Example for 1 validator on the Hoodi testnet using english:

docker run -it --rm -v $(pwd)/validator_keys:/app/validator_keys ghcr.io/ethstaker/ethstaker-deposit-cli:latest new-mnemonic --num_validators=1 --mnemonic_language=english --chain=hoodi

Option 4. Use local docker image

Build the docker image

Run the following command to locally build the docker image:
```
make build_docker
```

Create keys and deposit_data-*.json

Run the following command to enter the interactive CLI:

docker run -it --rm -v $(pwd)/validator_keys:/app/validator_keys ethstaker/ethstaker-deposit-cli

You can also run the tool with optional arguments:

docker run -it --rm -v $(pwd)/validator_keys:/app/validator_keys ethstaker/ethstaker-deposit-cli new-mnemonic --num_validators=<NUM_VALIDATORS> --mnemonic_language=english

Example for 1 validator on the Hoodi testnet using english:

docker run -it --rm -v $(pwd)/validator_keys:/app/validator_keys ethstaker/ethstaker-deposit-cli new-mnemonic --num_validators=1 --mnemonic_language=english --chain=hoodi

For Windows users

The helper script requires Bash. Use it from Git Bash as ./deposit.sh; from Command Prompt or PowerShell, use the direct Python commands in Option 2.

Option 1. Build `deposit-cli` with native Python

Python version checking

Ensure you are using a Python version supported by the current release (assume Python 3 is your main Python):
```
python -V
```

Installation

Install the dependencies:

python -m pip install -r requirements.txt

Or use the helper script:

./deposit.sh install

Create keys and deposit_data-*.json

Run one of the following command to enter the interactive CLI:

./deposit.sh new-mnemonic

./deposit.sh existing-mnemonic

You 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>

Option 2. Build `deposit-cli` with `virtualenv`

Python version checking

Ensure you are using a Python version supported by the current release (assume Python 3 is your main Python):
```
python -V
```

Installation

Create a new virtual environment:

python3 -m venv .venv
.\.venv\Scripts\activate

and install the dependencies:

python -m pip install -r requirements.txt

Create keys and deposit_data-*.json

Run one of the following command to enter the interactive CLI:

python -m ethstaker_deposit new-mnemonic

python -m ethstaker_deposit existing-mnemonic

You 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>

new-mnemonic

Including sensitive arguments when executing CLI commands poses a security risk, as these values can be accessible through disk and shell history. This exposure can allow other users, including admins and malicious actors, to gain access to sensitive information, putting your funds at risk.

Description

Generates a new random BIP-39 mnemonic along with validator keystore and deposit files depending on how many validators you wish to create.

Optional Arguments

--mnemonic_language: The language of the BIP-39 mnemonic. Options are: 'chinese_simplified', 'chinese_traditional', 'czech', 'english', 'french', 'italian', 'japanese', 'korean', 'portuguese', 'spanish'.
--chain: The chain to use for generating the deposit data. Options are: 'mainnet', 'sepolia', 'hoodi', 'plataberget', 'ephemery', 'gnosis', or 'chiado'.
--num_validators: Number of validators to create.
--keystore_password: The password that is used to encrypt the provided keystore. Note: It's not your mnemonic password.
--withdrawal_address: The Ethereum address that will be used in withdrawal. It typically starts with '0x' followed by 40 hexadecimal characters. Please make sure you have full control over the address you choose here. Once you set a withdrawal address on chain, it cannot be changed.
--compounding / --regular-withdrawal: Generates compounding validators with 0x02 withdrawal credentials for a 2048 ETH maximum effective balance or generate regular validators with 0x01 withdrawal credentials for a 32 ETH maximum effective balance. Use of this option requires a withdrawal address. This feature is only supported on networks that have undergone the Pectra fork. Defaults to regular withdrawal.
--amount: The amount to deposit per validator in ether. Only applies to compounding validators (0x02 withdrawal credentials). Must be at least the chain's minimum deposit amount (1 ETH on mainnet) with no greater precision than 1 gwei. Defaults to the chain's minimum activation amount (32 ETH on mainnet).
--pbkdf2: Will use pbkdf2 key encryption 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, as it can improve performance. pbkdf2 encryption is, however, less secure than scrypt. You should only use this option if you understand the associated risks and have familiarity with encryption.
--folder: The folder where keystore and deposit data files will be saved.
--devnet_chain_setting: The custom chain setting of a devnet or testnet. Note that it will override your --chain choice. This should be a JSON string containing an object with the following keys: network_name, genesis_fork_version, exit_fork_version, genesis_validator_root, multiplier, min_activation_amount and min_deposit_amount.

Output files

A successful call to this command will result in one or many keystore files created, one per validator created, and one deposit data file created. Non-compounding validators always deposit the chain's minimum activation amount (32 ETH on mainnet).

Example Usage

./deposit new-mnemonic

Note

The withdrawal address must be under your control, either an EOA or a smart contract wallet. Do not use an exchange wallet. If you do not control the withdrawal address, funds cannot be recovered.

The newly generated mnemonic must be written down, on a piece of paper or transferred to steel. The application will attempt to clear the clipboard when this command finishes. If the mnemonic is lost and the validator does not have a withdrawal address, funds cannot be recovered.

For non-compounding validators, a custom deposit amount requires an existing keystore file and the partial-deposit command. Compounding validators (0x02 withdrawal credentials) can set a custom deposit amount directly using --amount.

existing-mnemonic

Description

Uses an existing BIP-39 mnemonic phrase for key generation.

Optional Arguments

--chain: The chain to use for generating the deposit data. Options are: 'mainnet', 'sepolia', 'hoodi', 'plataberget', 'ephemery', 'gnosis', or 'chiado'.
--mnemonic: The mnemonic you used to create withdrawal credentials.
--mnemonic_language: The language of your mnemonic. If this is not provided we will attempt to determine it based on the mnemonic.
--mnemonic_password: The mnemonic password you used in your key generation. Note: It's not the keystore password.
--validator_start_index: 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: Number of validators to create.
--keystore_password: The password that is used to encrypt the provided keystore. Note: It's not your mnemonic password.
--withdrawal_address: The Ethereum address that will be used in withdrawal. It typically starts with '0x' followed by 40 hexadecimal characters. Please make sure you have full control over the address you choose here. Once you set a withdrawal address on chain, it cannot be changed.
--compounding / --regular-withdrawal: Generates compounding validators with 0x02 withdrawal credentials for a 2048 ETH maximum effective balance or generate regular validators with 0x01 withdrawal credentials for a 32 ETH maximum effective balance. Use of this option requires a withdrawal address. This feature is only supported on networks that have undergone the Pectra fork. Defaults to regular withdrawal.
--amount: The amount to deposit per validator in ether. Only applies to compounding validators (0x02 withdrawal credentials). Must be at least the chain's minimum deposit amount (1 ETH on mainnet) with no greater precision than 1 gwei. Defaults to the chain's minimum activation amount (32 ETH on mainnet).
--pbkdf2: 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, as it can improve performance however it is less secure. You should only use this option if you understand the associated risks and have familiarity with encryption.
--folder: The folder where keystore and deposit data files will be saved.
--devnet_chain_setting: The custom chain setting of a devnet or testnet. Note that it will override your --chain choice. This should be a JSON string containing an object with the following keys: network_name, genesis_fork_version, exit_fork_version, genesis_validator_root, multiplier, min_activation_amount and min_deposit_amount.

Output files

Example Usage

./deposit existing-mnemonic

Note

generate-mnemonic

Description

Generates a new random BIP-39 mnemonic. If you also want to create your validator keystore and deposit files, you should be using the new-mnemonic or the existing-mnemonic command instead. This command can be used as part of some automation where you can first generate your mnemonic with generate-mnemonic and generate the validator keystore and deposit files with existing-mnemonic without any interactive prompt.

Optional Arguments

--mnemonic_language: The language of the BIP-39 mnemonic. Options are: 'chinese_simplified', 'chinese_traditional', 'czech', 'english', 'french', 'italian', 'japanese', 'korean', 'portuguese', 'spanish'.
--output_file: An optional file path where to write the mnemonic. When used, it will write the mnemonic to the file instead of displaying the mnemonic.

Output

By default, it will output the mnemonic on the standard output, in your terminal. You can decide to output this in a file instead using the --output_file optional argument.

Example Usage

./deposit generate-mnemonic

Note

The newly generated mnemonic must be written down, on a piece of paper or transferred to steel. If the mnemonic is lost and the validator does not have a withdrawal address, funds cannot be recovered.

generate-bls-to-execution-change

Description

Generates a BLS to execution address change message. This is used to add a withdrawal address to a validator that does not currently have one.

Optional Arguments

--bls_to_execution_changes_folder: The path to store the change JSON file.
--chain: The chain to use for generating the deposit data. Options are: 'mainnet', 'sepolia', 'hoodi', 'plataberget', 'ephemery', 'gnosis', or 'chiado'.
--mnemonic: The mnemonic you used to create withdrawal credentials.
--mnemonic_language: The language of your mnemonic. If this is not provided we will attempt to determine it based on the mnemonic.
--mnemonic_password: The mnemonic password you used in your key generation. Note: It's not the keystore password.
--validator_start_index: The index position for the keys to start generating withdrawal credentials for.
--validator_indices: 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: 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: The Ethereum address that will be used in withdrawal. It typically starts with '0x' followed by 40 hexadecimal characters. Please make sure you have full control over the address you choose here. Once you set a withdrawal address on chain, it cannot be changed.
--devnet_chain_setting: The custom chain setting of a devnet or testnet. Note that it will override your --chain choice. This should be a JSON string containing an object with the following keys: network_name, genesis_fork_version, exit_fork_version, genesis_validator_root, multiplier, min_activation_amount and min_deposit_amount.

Output files

A successful call to this command will result in one BLS to Execution Change file created.

Example Usage

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

generate-bls-to-execution-change-keystore

This command is associated with the a proposed solution to update withdrawal credentials for those who are missing their mnemonic. At this point this has not been approved or implemented and there is no guarantee credentials will be modified in the future.

The project is located here if you would like to learn more.

Description

Signs a withdrawal credential update message using the provided keystore. This signature is one of the required proofs of ownership for validators who have lost or are missing their mnemonic and are unable to perform the BLS change needed to update their withdrawal credentials.

Optional Arguments

--chain: The chain to use for generating the deposit data. Options are: 'mainnet', 'sepolia', 'hoodi', 'plataberget', 'ephemery', 'gnosis', or 'chiado'.
--keystore: The keystore file associating with the validator you wish to sign with. This keystore file should match the provided validator index.
--keystore_password: The password that is used to encrypt the provided keystore. Note: It's not your mnemonic password.
--validator_index: The validator index corresponding to the provided keystore.
--withdrawal_address: The Ethereum address that will be used in withdrawal. It typically starts with '0x' followed by 40 hexadecimal characters. Please make sure you have full control over the address you choose here. Once you set a withdrawal address on chain, it cannot be changed.
--output_folder: The folder path for the bls_to_execution_change_keystore_signature-* JSON file.
--devnet_chain_setting: The custom chain setting of a devnet or testnet. Note that it will override your --chain choice. This should be a JSON string containing an object with the following keys: network_name, genesis_fork_version, exit_fork_version, genesis_validator_root, multiplier, min_activation_amount and min_deposit_amount.

Output files

A successful call to this command will result in one BLS to Execution Change Keystore file created.

Example Usage

./deposit generate-bls-to-execution-change-keystore

exit-transaction-keystore

Description

Creates an exit transaction using a keystore file.

Optional Arguments

--chain: The chain to use for generating the deposit data. Options are: 'mainnet', 'sepolia', 'hoodi', 'plataberget', 'ephemery', 'gnosis', or 'chiado'.
--keystore: The keystore file associating with the validator you wish to exit.
--keystore_password: The password that is used to encrypt the provided keystore. Note: It's not your mnemonic password.
--validator_index: The validator index corresponding to the provided keystore.
--epoch: The epoch of when the exit transaction will be valid. The transaction will always be valid by default.
--output_folder: The folder path for the signed_exit_transaction-* JSON file.
--devnet_chain_setting: The custom chain setting of a devnet or testnet. Note that it will override your --chain choice. This should be a JSON string containing an object with the following keys: network_name, genesis_fork_version, exit_fork_version, genesis_validator_root, multiplier, min_activation_amount and min_deposit_amount.

Output files

A successful call to this command will result in one Signed Exit Transaction file created.

Example Usage

./deposit exit-transaction-keystore --keystore /path/to/keystore.json

exit-transaction-mnemonic

Description

Creates an exit transaction using a mnemonic phrase.

Optional Arguments

--chain: The chain to use for generating the deposit data. Options are: 'mainnet', 'sepolia', 'hoodi', 'plataberget', 'ephemery', 'gnosis', or 'chiado'.
--mnemonic: The mnemonic you used during key generation.
--mnemonic_language: The language of your mnemonic. If this is not provided we will attempt to determine it based on the mnemonic.
--mnemonic_password: The mnemonic password you used in your key generation. Note: It's not the keystore password.
--validator_start_index: The index position for the keys to start generating keystores in ERC-2334 format format.
--validator_indices: A list of the chosen validator index number(s) as identified on the beacon chain. Split multiple items with whitespaces or commas.
--epoch: The epoch of when the exit transaction will be valid. The transaction will always be valid by default.
--output_folder: The folder path for the signed_exit_transaction-* JSON file.
--devnet_chain_setting: The custom chain setting of a devnet or testnet. Note that it will override your --chain choice. This should be a JSON string containing an object with the following keys: network_name, genesis_fork_version, exit_fork_version, genesis_validator_root, multiplier, min_activation_amount and min_deposit_amount.

Output files

A successful call to this command will result in one or more Signed Exit Transaction files created.

Example Usage

./deposit exit-transaction-mnemonic

partial-deposit

Description

Creates a deposit file with an existing validator key. A validator key can be created using the new-mnemonic or the existing-mnemonic commands. Can be used to initiate a validator or deposit to an existing validator. If you wish to create a validator with 0x00 credentials, you must use the new-mnemonic or the existing-mnemonic command.

Optional Arguments

--chain: The chain to use for generating the deposit data. Options are: 'mainnet', 'sepolia', 'hoodi', 'plataberget', 'ephemery', 'gnosis', or 'chiado'.
--keystore: The keystore file associating with the validator you wish to deposit to.
--keystore_password: The password that is used to encrypt the provided keystore. Note: It's not your mnemonic password.
--amount: The amount to deposit per validator in ether. Must be at least the chain's minimum deposit amount (1 ETH on mainnet) with no greater precision than 1 gwei. Defaults to the chain's minimum activation amount (32 ETH on mainnet).
--withdrawal_address: The withdrawal address of the existing validator or the desired withdrawal address.
--compounding / --regular-withdrawal: Generates compounding validators with 0x02 withdrawal credentials for a 2048 ETH maximum effective balance or generate regular validators with 0x01 withdrawal credentials for a 32 ETH maximum effective balance. Use of this option requires a withdrawal address. This feature is only supported on networks that have undergone the Pectra fork. Defaults to regular withdrawal.
--output_folder: The folder path for the deposit-* JSON file.
--devnet_chain_setting: The custom chain setting of a devnet or testnet. Note that it will override your --chain choice. This should be a JSON string containing an object with the following keys: network_name, genesis_fork_version, exit_fork_version, genesis_validator_root, multiplier, min_activation_amount and min_deposit_amount.

Output file

A successful call to this command will result in one deposit data file created.

Example Usage

./deposit partial-deposit --keystore /path/to/keystore.json

test-keystore

Description

Will verify access to the provided keystore file by attempting to decrypt it with the provided keystore password.

Optional Arguments

--keystore: The keystore file you wish to verify.
--keystore_password: The password used to attempt decryption of the provided keystore file. Note: It is not your mnemonic password.

Example Usage

./deposit test-keystore --keystore /path/to/keystore.json

Fully Automatic Key Generation

Description

ethstaker-deposit-cli supports generating keys via script, and no prompts will be shown. This is achieved by using the generate-mnemonic command followed by the existing-mnemonic command. Of necessity, the keystore password and mnemonic will be on command line with this workflow. Ensure these secrets are properly safeguarded.

Parameters are positional: --language, --non_interactive, --ignore_connectivity all come before the command.

Example Usage

./deposit --non_interactive --ignore_connectivity --language english generate-mnemonic --mnemonic_language english --output_file ./test-mnemonic.txt

This creates a file ./test-mnemonic.txt, which is used in the following step. Fill in the <> placeholders. If creating validators for the first time with this mnemonic, choose a start index of 0.

./deposit --non_interactive --ignore_connectivity --language english existing-mnemonic --compounding --amount <deposit-amount> --withdrawal_address <your-withdrawal-address> --chain mainnet --keystore_password <your-password> --num_validators <num-validators-to-create> --validator_start_index <index-to-start> --mnemonic "$(cat ./test-mnemonic.txt)"

This creates the desired number of validator keys as keystore-m_12381_3600_<index>_0_0-<timestamp>.json and a matching deposit_data-<timestamp>.json in the ./validator_keys directory. Add a --folder parameter to adjust the location of the output files.

Note

Verify Mnemonic

Description

To verify a mnemonic you recorded, you can use the existing-mnemonic command.

Example Usage

Assume you have generated keys from index 0 with the new-mnemonic command, and these are in ./validator_keys.

Generate one key, from the same index, using the existing-mnemonic command, and write the generated files into a separate directory. Then compare the pubkey. If it matches, you correctly recorded the mnemonic.

mkdir -p ./verification_key
./deposit --language english --non_interactive existing-mnemonic --withdrawal_address 0x0000000000000000000000000000000000000000 --chain mainnet --keystore_password WeWontUseThis --compounding --amount 2048 --num_validators 1 --validator_start_index 0 --folder ./verification_key

This creates one validator key as keystore-m_12381_3600_0_0_0-<timestamp>.json in the ./verification_key directory. The command will prompt you for the mnemonic. The deposit_data file won't be used, so we can safely specify a dummy withdrawal address and amount.

Either just look at the two generated files, or use jq (install it first) to generate the pubkey from each:

jq .pubkey ./validator_keys/keystore-m_12381_3600_0_0_0-<timestamp>.json
jq .pubkey ./verification_key/keystore-m_12381_3600_0_0_0-<timestamp>.json

If this pubkey matches, the same mnemonic was used both times.

Keystore file

A keystore file is created when calling the new-mnemonic or the existing-mnemonic command.

The format of the keystore file is defined in the ERC-2335: BLS12-381 Keystore document.

In the context of staking on the Ethereum blockchain, the keystore file is used to store the validator signing key and transport it across devices while being protected with a password. Once created by a tool such as ethstaker-deposit-cli, it will generally be copied on a device running a validator client to be imported by that validator client with the associated password. Once the validator signing key is available to the validator client, it generally provides all the secrets needed to perform the associated validator's duties.

Deposit Data file

A deposit data file is created when calling the new-mnemonic, the existing-mnemonic or the partial-deposit command.

The deposit data file is a JSON file that contains a list of deposits that is mostly used for the Ethereum Staking Launchpad. It is loosely based on the DepositData structure and the deposit function from the deposit smart contract.

Format

Each deposit from the list will contain this structure:

{
    "pubkey": "string",
    "withdrawal_credentials": "string",
    "amount": "number",
    "signature": "string",
    "deposit_message_root": "string",
    "deposit_data_root": "string",
    "fork_version": "string",
    "network_name": "string",
    "deposit_cli_version": "string"
}

pubkey: The validator public key value to be passed to the deposit function call.
withdrawal_credentials: The withdrawal credentials value to be passed to the deposit function call.
amount: The deposit amount to be sent with the call to the deposit function call. This should always be 32 Ethers (in GWEI, 32000000000) when performing a deposit for a validator to be activated. The unit for this value is GWEI. For partial deposits, this value can be an integer value higher or equal than 1 and generally lower than or equal to 2048 in Ethers.
signature: The signature value to be passed to the deposit function call.
deposit_message_root: A deposit message root value used for validation by the Ethereum Staking Launchpad.
deposit_data_root: The deposit data root value to be passed to the deposit function call.
fork_version: The fork version of the network that this deposit file was created for.
network_name: The network name of the network that this deposit file was created for.
deposit_cli_version: The tool version used to create this file. We are currently faking this value to work around an issue with the Launchpad.

Example

[
  {
    "pubkey":"962195958e742b8dc5b2a25adede82fc5cd661827cb1e1237025e3d7847801aa5584d5bfdc6893413264cccfbff54128",
    "withdrawal_credentials":"0007a213a9a50ddf7e00e53267af1c131ed82fec947f1c9656b54f9a20f7a87f",
    "amount":32000000000,
    "signature":"a2d56afe4540d5b506aea614848a0838b66c8707a91aa73cdb0e7b59d819f16be64881b5b621184b1668f4f1d024094a1861c5af783ded675b5763047c069c5eb805649f7c04656c96b31b0bccc34ed93c8fcd8f2e4a9e5c03453f305089d765",
    "deposit_message_root":"f9bdb1e800b8f9f0db98c77271745e3c6140f18bf420543bda84fa92c393ddc7",
    "deposit_data_root":"7cda08cd57c303f8af720b10a0852408bc31e015cb552f0029fc1024b8a1d615",
    "fork_version":"01017000",
    "network_name":"hoodi",
    "deposit_cli_version":"1.2.2"
  },
  {
    "pubkey":"86ee0b826d7d5262324ace2fba4ed5f09a1cbef80552e3d945279f19bc4118a98e9a93257eb4c7731ccc10c19835d24f",
    "withdrawal_credentials":"00daf39b8996943de9e93d417a6c5a4b958e4ae7a4d6e27f72aa08d41faa012f",
    "amount":32000000000,
    "signature":"83b227d72d9f1362d8676a61b91bb3882059e89c7d862d8030b1d37e890143869c105a78efce2a734f202da95076782219010e896ec9f8328a9e553134773626810d6c455bc1250a20e52a01684c051dd3e46151587267214cbb396673a13e89",
    "deposit_message_root":"99dbb2392fef277c15e710ca0ead058c024adce15f9e8f369bbaea939c0009ed",
    "deposit_data_root":"0fcb16fdb536b00a037a3ccde67187d21abfb726d677e40709ae6910d44377a5",
    "fork_version":"01017000",
    "network_name":"hoodi",
    "deposit_cli_version":"1.2.2"
  }
]

BLS to Execution Change file

A BLS to execution change file is created when calling the generate-bls-to-execution-change command.

The BLS to execution change file is a JSON file. It contains a list of messages to change the withdrawal credentials for one or many validators. The format of the BLS to execution change file is loosely based on the input for the POST /eth/v1/beacon/pool/bls_to_execution_changes API endpoint as defined by the Ethereum Beacon APIs. Part of this content is based on the SignedBLSToExecutionChange container as defined in the Ethereum Consensus Specifications.

Broadcasting

If you have access to a beacon node client running on your target network, you can publish these messages simply by calling the POST /eth/v1/beacon/pool/bls_to_execution_changes API endpoint and passing the content of the BLS to execution change file as the payload. You can also use the Beaconcha.in Broadcast Signed Messages tool which might be easier for most users.

Example

[
  {
    "message":{
      "validator_index":"1804776",
      "from_bls_pubkey":"0x970245df5f9cf7a082db195136a3066412b62e8bf04e21d7c3408d7fb36f34f20c4cb0883e798b82523b466f7a61c838",
      "to_execution_address":"0x4d496ccc28058b1d74b7a19541663e21154f9c84"
    },
    "signature":"0xa1e47e6b1fdf4dd5f1dd3ddb3d47d2dcf446d096d49d90afef06a38dc02fba6b4d16d1dc1184c791e54666dabb8bdedd0660bc9bb3bc5d0e592eaf5f0c978cca4fcafe4037672940d6f1a44d2a33503c30cb98ca695979b1de9e321a8a694bc2",
    "metadata":{
      "network_name":"hoodi",
      "genesis_validators_root":"0x9143aa7c615a7f7115e2b6aac319c03529df8242ae705fba9df39b79c59fa8b1",
      "deposit_cli_version":"1.2.2"
    }
  }
]

BLS to Execution Change Keystore file

A BLS to execution change keystore file is created when calling the generate-bls-to-execution-change-keystore command.

The BLS to execution change keystore file is a JSON file. The format is very similar to the BLS to execution change file but with the from_bls_pubkey and metadata attributes removed.

Utilizing

There is currently no integration with this file format with either the execution layer or beacon chain. The signature value must be provided as the keystore_signature for the Signature file.

Example

{
  "message":{
    "validator_index":"1804776",
    "to_execution_address":"0x4d496ccc28058b1d74b7a19541663e21154f9c84"
  },
  "signature":"0xa1e47e6b1fdf4dd5f1dd3ddb3d47d2dcf446d096d49d90afef06a38dc02fba6b4d16d1dc1184c791e54666dabb8bdedd0660bc9bb3bc5d0e592eaf5f0c978cca4fcafe4037672940d6f1a44d2a33503c30cb98ca695979b1de9e321a8a694bc2",
}

Signed Exit Transaction file

A signed exit transaction file is created when calling the exit-transaction-keystore or the exit-transaction-mnemonic command.

The signed exit transaction file is a JSON file. It contains a single message to exit a validator. The format of the signed exit transaction file is loosely based on the input for the POST /eth/v1/beacon/pool/voluntary_exits API endpoint as defined by the Ethereum Beacon APIs. Part of this content is based on the SignedVoluntaryExit signed envelope as defined in the Ethereum Consensus Specifications.

Broadcasting

If you have access to a beacon node client running on your target network, you can publish this message simply by calling the POST /eth/v1/beacon/pool/voluntary_exits API endpoint and passing the content of the signed exit transaction file as the payload. You can also use the Beaconcha.in Broadcast Signed Messages tool which might be easier for most users.

Example

{
  "message":{
    "epoch":"0",
    "validator_index":"1804776"
  },
  "signature":"0x97fa465cf1081755002e35fab245bd2872381b07cbfa4df245a13e3834aba83a347f5c2a36a34760e9fcc754dd862de700d103b1cb0d5d9ce293242ebf9ad44a6073e5c4794424428a8f983513d88e6ff6ddccbde7b3e0ea43554a0b856f3199"
}

Local Development Instructions

To install the ethstaker-deposit-cli, follow these steps:

Prerequisites

Ensure you have the following software installed on your system:

Git: Version control system to clone the repository. Download Git
Supported Python version: The required version is declared in pyproject.toml. Download Python
pip: Package installer for Python, which is included with Python 3.

On Windows, you'll need:

Git for Windows: Version control system to clone the repository. Configure it to associate .sh files with bash. Download GfW
Windows Terminal: Optional but recommended command line console. Configure GfW to install a Git Bash profile. Download Windows Terminal
Supported Python version: The required version is declared in pyproject.toml. Download Python
Visual Studio C++: The compiler required to build some of the dependencies of the tool. Download VS C++

Local Development Steps

Clone the Repository

git clone https://github.com/ethstaker/ethstaker-deposit-cli.git

Navigate to the Project Directory
```
cd ethstaker-deposit-cli
```
Setup virtualenv (optional)

Install venv if not already installed, e.g. for Debian/Ubuntu:
```
sudo apt update && sudo apt install python3-venv
```
Create a new virtual environment:
```
python3 -m venv .venv
source .venv/bin/activate
```

Install Dependencies

python3 -m pip install -r requirements.txt

Run the CLI

You can now run the CLI tool using the following command:
```
python3 -m ethstaker_deposit [OPTIONS] COMMAND [ARGS]
```
Use pre-commit for PRs

Install pre-commit if not already installed, e.g. for Debian/Ubuntu:
```
sudo apt update && sudo apt install pre-commit
```
Enable it for your git commit workflow:
```
pre-commit install
```
If you are using uv, you can also install it using:
```
uv sync --all-extras
uv run pre-commit install
```

To execute tests, you will need to install the test dependencies:

python3 -m pip install -r requirements.txt -r requirements_test.txt
python3 -m pytest tests

Building Local Binaries

The standalone binary targets use Python 3.14, matching the official release workflow and the Python version supported by the pinned PyInstaller toolchain.

Build a Linux or macOS binary with:

make build_linux
make build_macos

These targets look for python3.14, create or reuse the venv/ environment with that interpreter, and install the pinned build dependencies. If an existing venv/ was created with another Python version, it is recreated automatically.

If Python 3.14 is installed under a non-standard path, provide it explicitly:

make BUILD_PYTHON=/path/to/python3.14 build_linux

The general development targets, such as venv_test and venv_lint, use python3 by default. That interpreter must satisfy the requires-python range in pyproject.toml; override it with PYTHON when needed:

make PYTHON=python3.14 venv_test

The official release workflow builds binaries with Python 3.14. Windows binaries are currently built by GitHub Actions using build_configs/windows/build.spec.

Release Process Instructions

This document is meant as a guide on how to perform and publish a new release version of ethstaker-deposit-cli. It includes step by step instructions to complete the release process.

Make sure all the tests from the latest ci-runner workflow on the latest commit of the main branch are completed. Make sure all tests are passing on all the supported platforms.
Determine a new version number. Version numbers should adhere to Semantic Versioning. For any official release, it should include a major, a minor and a patch identifier like 1.0.0.
Update ethstaker_deposit/VERSION's content with the new version number. Commit this change to the main branch of the main repository.
Add a tag to the main repository for this changed version commit above. The name of this tag should be a string starting with v concatenated with the version number. With git, the main repository cloned and the commit above being the head, it can look like this:

git tag -a -m 'Version 1.0.0' v1.0.0
git push origin v1.0.0

Wait for all the build assets and the draft release to be created by the ci-build workflow.
Open the draft release and fill in the different sections correctly.
If this is not a production release, check the Set as a pre-release checkbox.
Click the Publish release button.
Determine a new dev version number. You can try to guess the next version number to the best of your ability. This will always be subject to change. Add a dev identifier to the version number to clearly indicate this is a dev version number.
Update ethstaker_deposit/VERSION's content with a new dev version number. Commit this change to the main branch.

Release Notes Template

You can find the latest release notes template on https://github.com/ethstaker/ethstaker-deposit-cli/blob/main/.github/release_template.md .

Reporting a Vulnerability

Private vulnerability reporting is enabled on the ethstaker-deposit-cli repository. Feel free to report any security vulnerability through the GitHub Report a vulnerability feature.