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: Update your withdrawal credentials of existing validators. It is required to have the corresponding mnemonic.

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

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.

Step 1: Download the Latest Release

  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

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.

Determine which command best suites 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.

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

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 execution address for validator withdrawals.

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

Example Usage

./deposit new-mnemonic

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_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 execution address for validator withdrawals.

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

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_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: If this field is set and valid, the given Ethereum execution address will be used to create the withdrawal credentials. Otherwise it will generate withdrawal credentials with the mnemonic-derived withdrawal public key.

  • --devnet_chain_setting: The custom chain setting of a devnet or testnet. Note that it will override your --chain choice.

Example Usage

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

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.

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

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.

Example Usage

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

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

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