Welcome to the ethstaker-deposit-cli!

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

Important Concerns

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, Français, Bahasa melayu, Italiano, 日本語, 한국어, Português do Brasil, român, 简体中文. 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 Holešky (Holešovice) testnet
  • Deposit address: 0x4242424242424242424242424242424242424242
  • Launchpad

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

• Python 3.9+
• pip3

Step 1: Download the Latest Release

Download binary executable file

1. Navigate to the Releases page of the ethstaker-deposit-cli repository.

2. 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.

3. Extract the contents of the zipped file

4. 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

1. Make sure you have the GitHub CLI installed.

2. 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 eth-educators/ethstaker-deposit-cli

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

3. 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

1. Python version checking

   Ensure you are using Python version >= Python3.9:

   python3 -V
   

2. Installation

   Install the dependencies:

   pip3 install -r requirements.txt
   

   Or use the helper script:

   ./deposit.sh install
   

3. Create keys and deposit_data-*.json

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

   ./deposit.sh new-mnemonic
   

   or

   ./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

1. Python version checking

   Ensure you are using Python version >= Python3.9:

   python3 -V
   

2. 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:

   pip3 install -r requirements.txt
   

3. Create keys and deposit_data-*.json

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

   python3 -m ethstaker_deposit new-mnemonic
   

   or

   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

1. Pull the official docker image

   Run the following command to pull the latest docker image published on the Github repository:

   docker pull ghcr.io/eth-educators/ethstaker-deposit-cli:latest
   

2. 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/eth-educators/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/eth-educators/ethstaker-deposit-cli:latest new-mnemonic --num_validators=<NUM_VALIDATORS> --mnemonic_language=english
   

   Example 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=holesky
   

Option 4. Use local docker image

1. Build the docker image

   Run the following command to locally build the docker image:

   make build_docker
   

2. 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 eth-educators/ethstaker-deposit-cli
   

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

   Example 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=holesky
   

For Windows users

Option 1. Build deposit-cli with native Python

1. Python version checking

   Ensure you are using Python version >= Python12 (Assume that you've installed Python 3 as the main Python):

   python -V
   

2. Installation

   Install the dependencies:

   pip3 install -r requirements.txt
   

   Or use the helper script:

   sh deposit.sh install
   

3. Create keys and deposit_data-*.json

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

   ./deposit.sh new-mnemonic
   

   or

   ./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

1. Python version checking

   Ensure you are using Python version >= Python3.9 (Assume that you've installed Python 3 as the main Python):

   python -V
   

2. Installation

   Create a new virtual environment:

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

   and install the dependencies:

   pip3 install -r requirements.txt
   

3. Create keys and deposit_data-*.json

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

   python -m ethstaker_deposit new-mnemonic
   

   or

   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

Description

Generates a new 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', 'holesky', 'mekong', or 'ephemery'.

• --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 to these validators in ether denomination. Must be at least 1 ether and can not have greater precision than 1 gwei. Use of this option requires compounding validators. Defaults to 32 ether.

• --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 and genesis_validator_root.

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. The amount for each deposit in the deposit data file should always be 32 Ethers (32000000000 in GWEI) with this command.

Example Usage

./deposit new-mnemonic

Note

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

To make a deposit for a different amount other than 32 ETH, you need to have an existing keystore file or create one by using either the above command or existing-mnemonic. Then, use the partial-deposit command to specify the desired amount for each validator.

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', 'holesky', 'mekong', or 'ephemery'.

• --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 to these validators in ether denomination. Must be at least 1 ether and can not have greater precision than 1 gwei. Use of this option requires compounding validators. Defaults to 32 ether.

• --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 and genesis_validator_root.

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. The amount for each deposit in the deposit data file should always be 32 Ethers (32000000000 in GWEI) with this command.

Example Usage

./deposit existing-mnemonic

Note

To make a deposit for a different amount other than 32 ETH, you need to have an existing keystore file or create one by using either the above command or new-mnemonic. Then, use the partial-deposit command to specify the desired amount for each validator.

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', 'holesky', 'mekong', or 'ephemery'.

• --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 and genesis_validator_root.

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

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', 'holesky', 'mekong', or 'ephemery'.

• --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 and genesis_validator_root.

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', 'holesky', 'mekong', or 'ephemery'.

• --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 and genesis_validator_root.

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', 'holesky', 'mekong', or 'ephemery'.

• --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 and genesis_validator_root.

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', 'holesky', 'mekong', or 'ephemery'.

• --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 you wish to deposit in ether. Must be at least 1 and can not have precision beyond 1 gwei. Defaults to 32 ether.

• --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 and genesis_validator_root.

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

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 loosly 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":"holesky",
    "deposit_cli_version":"2.7.0"
  },
  {
    "pubkey":"86ee0b826d7d5262324ace2fba4ed5f09a1cbef80552e3d945279f19bc4118a98e9a93257eb4c7731ccc10c19835d24f",
    "withdrawal_credentials":"00daf39b8996943de9e93d417a6c5a4b958e4ae7a4d6e27f72aa08d41faa012f",
    "amount":32000000000,
    "signature":"83b227d72d9f1362d8676a61b91bb3882059e89c7d862d8030b1d37e890143869c105a78efce2a734f202da95076782219010e896ec9f8328a9e553134773626810d6c455bc1250a20e52a01684c051dd3e46151587267214cbb396673a13e89",
    "deposit_message_root":"99dbb2392fef277c15e710ca0ead058c024adce15f9e8f369bbaea939c0009ed",
    "deposit_data_root":"0fcb16fdb536b00a037a3ccde67187d21abfb726d677e40709ae6910d44377a5",
    "fork_version":"01017000",
    "network_name":"holesky",
    "deposit_cli_version":"2.7.0"
  }
]

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":"holesky",
      "genesis_validators_root":"0x9143aa7c615a7f7115e2b6aac319c03529df8242ae705fba9df39b79c59fa8b1",
      "deposit_cli_version":"0.1.4-dev"
    }
  }
]

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 loosly 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
• Python 3.9+: The programming language required to run the tool. Download Python
• pip: Package installer for Python, which is included with Python 3.9+.

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
• Python 3.9+: The programming language required to run the tool. Download Python
• Visual Studio C++: The compiler required to build some of the dependencies of the tool. Download VS C++

Local Development Steps

1. Clone the Repository

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

2. Navigate to the Project Directory

   cd ethstaker-deposit-cli
   

3. 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
   

4. Install Dependencies

   pip3 install -r requirements.txt
   

5. Run the CLI

   You can now run the CLI tool using the following command:

   python3 -m ethstaker_deposit [OPTIONS] COMMAND [ARGS]
   

6. 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
   

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

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.

1. 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.
2. 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.
3. Update ethstaker_deposit/__init__.py's __version__ variable with the new version number. Commit this change to the main branch of the main repository.
4. 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

5. Wait for all the build assets and the draft release to be created by the ci-build workflow.
6. Open the draft release and fill in the different sections correctly.
7. If this is not a production release, check the Set as a pre-release checkbox.
8. Click the Publish release button.
9. 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.
10. Update ethstaker_deposit/__init__.py's __version__ variable 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/eth-educators/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.