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.

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

  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 GPG installed.

  2. Make sure you have the edc-security@ethstaker.cc public key by running

gpg --keyserver keys.openpgp.org --search-keys 'edc-security@ethstaker.cc'
  1. Verify the signature file against the corresponding file but be sure to replace the contents with the exact file name:
gpg --verify staking_deposit-cli-***.asc staking_deposit-cli-***
  1. You should see Good signature from "EDC Security <edc-security@ethstaker.cc>" 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 suites what you would like to accomplish:

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

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 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', 'holesky', etc...

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

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

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

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', 'holesky', etc...

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

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

generate-bls-to-execution-change

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 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', 'holesky', etc.

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

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', 'holesky', etc.

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

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

Creates an exit transaction using a keystore file.

Optional Arguments

  • --chain: The chain to use for generating the deposit data. Options are: 'mainnet', 'holesky', etc.

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

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

Creates an exit transaction using a mnemonic phrase.

Optional Arguments

  • --chain: The chain to use for generating the deposit data. Options are: 'mainnet', 'holesky', etc.

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

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

Creates a deposit file with an existing validator key. 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', 'holesky', etc.

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

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

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

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.

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 loosly 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_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
  1. Wait for all the build assets to be created by the ci-build workflow. Wait for the docker image to be created by the ci-docker workflow.
  2. Download all the release assets from the build process in step 5. Extract the zip files to get the actual release files. Test some of the binary assets to make sure there is no major issue with them.
  3. Draft a new release on Github.
  4. Choose the tag you created at step 4.
  5. Click the Generate release notes button. Copy the generated content to be included later.
  6. Add an interesting release title.
  7. Use the template below for the content of the release notes. Fill in the different sections correctly. Make sure all the links are updated to work with the new release including the various asset links and the docker image link. Include the generated release notes from step 9 in the All changes section.
  8. Upload all the binary assets extracted in step 6 in the draft release binaries section.
  9. If this is not a production release, check the Set as a pre-release checkbox.
  10. Click the Publish release button.
  11. 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.
  12. 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 start the release notes with this template:

# Summary

This preview release contains all the changes that were made since the original fork of the [staking-deposit-cli project](https://github.com/ethereum/staking-deposit-cli/) ([fdab65d commit](https://github.com/ethereum/staking-deposit-cli/commit/fdab65d33a63632e1935e9a9235119a46e37c221)).

Notable changes from the original project include:

- New exit commands to create an exit message and perform a voluntary exit for your validators.
- Multiprocessing support to increase the speed of processes that can be expanded to use more than a single thread or a single process. This helps with generating a large number of validator keys for instance.
- Support for more recent OSes and Python versions by default.
- A dedicated [documentation website](https://eth-educators.github.io/ethstaker-deposit-cli/).

# Known Issues

`[Remove this section if there is no known issue]`

# All changes

`[Generated release notes]`

# Building process

Release assets were built using Github Actions and [this workflow run](https://github.com/eth-educators/ethstaker-deposit-cli/actions/runs/10113717389). You can establish the provenance of this build using [our artifact attestations](https://github.com/eth-educators/ethstaker-deposit-cli/attestations).

# Binaries

Our binaries are signed with ethstaker-deposit-cli's PGP key: `54FA06FC0860FC0DCCC68E3ECE9FF2391DF26368` .

| System  | Architecture | Binary             | Checksum               | PGP Signature         |
|---------|--------------|--------------------|------------------------|-----------------------|
| Windows | x86_64       | [ethstaker_deposit-cli-c840111-windows-amd64.zip](https://github.com/eth-educators/ethstaker-deposit-cli/releases/download/v0.1.0/ethstaker_deposit-cli-c840111-windows-amd64.zip) | [sha256](https://github.com/eth-educators/ethstaker-deposit-cli/releases/download/v0.1.0/ethstaker_deposit-cli-c840111-windows-amd64.zip.sha256) | [PGP Signature](https://github.com/eth-educators/ethstaker-deposit-cli/releases/download/v0.1.0/ethstaker_deposit-cli-c840111-windows-amd64.zip.asc) |
| macOS   | x86_64       | [ethstaker_deposit-cli-c840111-darwin-amd64.tar.gz](https://github.com/eth-educators/ethstaker-deposit-cli/releases/download/v0.1.0/ethstaker_deposit-cli-c840111-darwin-amd64.tar.gz) | [sha256](https://github.com/eth-educators/ethstaker-deposit-cli/releases/download/v0.1.0/ethstaker_deposit-cli-c840111-darwin-amd64.tar.gz.sha256) | [PGP Signature](https://github.com/eth-educators/ethstaker-deposit-cli/releases/download/v0.1.0/ethstaker_deposit-cli-c840111-darwin-amd64.tar.gz.asc) |
| macOS   | aarch64      | [ethstaker_deposit-cli-c840111-darwin-arm64.tar.gz](https://github.com/eth-educators/ethstaker-deposit-cli/releases/download/v0.1.0/ethstaker_deposit-cli-c840111-darwin-arm64.tar.gz) | [sha256](https://github.com/eth-educators/ethstaker-deposit-cli/releases/download/v0.1.0/ethstaker_deposit-cli-c840111-darwin-arm64.tar.gz.sha256) | [PGP Signature](https://github.com/eth-educators/ethstaker-deposit-cli/releases/download/v0.1.0/ethstaker_deposit-cli-c840111-darwin-arm64.tar.gz.asc) |
| Linux   | x86_64       | [ethstaker_deposit-cli-c840111-linux-amd64.tar.gz](https://github.com/eth-educators/ethstaker-deposit-cli/releases/download/v0.1.0/ethstaker_deposit-cli-c840111-linux-amd64.tar.gz) | [sha256](https://github.com/eth-educators/ethstaker-deposit-cli/releases/download/v0.1.0/ethstaker_deposit-cli-c840111-linux-amd64.tar.gz.sha256) | [PGP Signature](https://github.com/eth-educators/ethstaker-deposit-cli/releases/download/v0.1.0/ethstaker_deposit-cli-c840111-linux-amd64.tar.gz.asc) |
| Linux   | aarch64      | [ethstaker_deposit-cli-c840111-linux-arm64.tar.gz](https://github.com/eth-educators/ethstaker-deposit-cli/releases/download/v0.1.0/ethstaker_deposit-cli-c840111-linux-arm64.tar.gz) | [sha256](https://github.com/eth-educators/ethstaker-deposit-cli/releases/download/v0.1.0/ethstaker_deposit-cli-c840111-linux-arm64.tar.gz.sha256) | [PGP Signature](https://github.com/eth-educators/ethstaker-deposit-cli/releases/download/v0.1.0/ethstaker_deposit-cli-c840111-linux-arm64.tar.gz.asc) |

# Docker image

| Version | Name | Package |
|---------|------|---------|
| v0.1.0  | `ghcr.io/eth-educators/ethstaker-deposit-cli:v0.1.0` | [Github Package](https://github.com/eth-educators/ethstaker-deposit-cli/pkgs/container/ethstaker-deposit-cli/249338184?tag=v0.1.0) |

## License

By downloading and using this software, you agree to the [license](LICENSE).