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.
- 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.
Step 1: Download the Latest Release
-
Navigate to the Releases page of the
ethstaker-deposit-cli
repository. -
Download the corresponding file for your operating system:
- Windows: Look for a file with
windows
in the name. - MacOS: Look for a file with
darwin
in the name. - Linux: Look for a file with
linux
in the name.
- Windows: Look for a file with
-
Extract the contents of the zipped file
-
Open a terminal or command prompt and navigate to the extracted folder
Step 2: Verify the Installation
-
Make sure you have GPG installed.
-
Make sure you have the
edc-security@ethstaker.cc
public key by running
gpg --keyserver keys.openpgp.org --search-keys 'edc-security@ethstaker.cc'
- 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-***
- 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
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
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
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
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 thesigned_exit_transaction-*
JSON file.
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', '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 thesigned_exit_transaction-*
JSON file.
Example Usage
./deposit exit-transaction-mnemonic
partial-deposit
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 thedeposit-*
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
-
Clone the Repository
git clone https://github.com/eth-educators/ethstaker-deposit-cli.git
-
Navigate to the Project Directory
cd ethstaker-deposit-cli
-
Setup virtualenv (optional)
Install
venv
if not already installed, e.g. for Debian/Ubuntu:sudo apt update && sudo apt install python3-venv
Create a new virtual environment:
python3 -m venv .venv source .venv/bin/activate
-
Install Dependencies
pip3 install -r requirements.txt
-
Run the CLI
You can now run the CLI tool using the following command:
python3 -m ethstaker_deposit [OPTIONS] COMMAND [ARGS]
-
Use pre-commit for PRs
Install
pre-commit
if not already installed, e.g. for Debian/Ubuntu:sudo apt update && sudo apt install pre-commit
Enable it for your
git commit
workflow:pre-commit install
To execute tests, you will need to install the test dependencies:
python3 -m pip install -r requirements_test.txt
python3 -m pytest tests