Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/ethereum/staking-deposit-cli

Secure key generation for deposits
https://github.com/ethereum/staking-deposit-cli
Last synced: 29 days ago
JSON representation
Secure key generation for deposits
Host: GitHub
URL: https://github.com/ethereum/staking-deposit-cli
Owner: ethereum
License: cc0-1.0
Created: 2020-02-10T08:47:18.000Z (over 4 years ago)
Default Branch: master
Last Pushed: 2024-09-11T04:17:09.000Z (about 2 months ago)
Last Synced: 2024-09-28T06:35:42.548Z (about 1 month ago)
Language: Python
Homepage:
Size: 1.04 MB
Stars: 530
Watchers: 47
Forks: 330
Open Issues: 115
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

best-of-crypto - GitHub - 60% open · ⏱️ 25.09.2023): (Smart Contract Platforms)
README

        # staking-deposit-cli

[![GitPOAP Badge](https://public-api.gitpoap.io/v1/repo/ethereum/staking-deposit-cli/badge)](https://www.gitpoap.io/gh/ethereum/staking-deposit-cli)

- [Introduction](#introduction)

- [Tutorial for users](#tutorial-for-users)

  - [Build requirements](#build-requirements)

  - [For Linux or MacOS users](#for-linux-or-macos-users)

    - [File Permissions](#file-permissions)

    - [Option 1. Download binary executable file](#option-1-download-binary-executable-file)

      - [Step 1. Installation](#step-1-installation)

      - [Step 2. Create keys and `deposit_data-*.json`](#step-2-create-keys-and-deposit_data-json)

        - [`language` Argument](#language-argument)

        - [`--non_interactive` flag](#--non_interactive-flag)

        - [Commands](#commands)

        - [`new-mnemonic` Arguments](#new-mnemonic-arguments)

        - [`existing-mnemonic` Arguments](#existing-mnemonic-arguments)

        - [Successful message](#successful-message)

        - [`generate-bls-to-execution-change` Arguments](#generate-bls-to-execution-change-arguments)

    - [Option 2. Build `deposit-cli` with native Python](#option-2-build-deposit-cli-with-native-python)

      - [Step 0. Python version checking](#step-0-python-version-checking)

      - [Step 1. Installation](#step-1-installation-1)

      - [Step 2. Create keys and `deposit_data-*.json`](#step-2-create-keys-and-deposit_data-json-1)

        - [Language Argument](#language-argument)

        - [Commands](#commands-1)

        - [Arguments](#arguments)

        - [Successful message](#successful-message-1)

    - [Option 3. Build `deposit-cli` with `virtualenv`](#option-3-build-deposit-cli-with-virtualenv)

      - [Step 0. Python version checking](#step-0-python-version-checking-1)

      - [Step 1. Installation](#step-1-installation-2)

      - [Step 2. Create keys and `deposit_data-*.json`](#step-2-create-keys-and-deposit_data-json-2)

        - [Language Argument](#language-argument-1)

        - [Commands](#commands-2)

        - [Arguments](#arguments-1)

    - [Option 4. Use Docker image](#option-4-use-docker-image)

      - [Step 1. Build the docker image](#step-1-build-the-docker-image)

      - [Step 2. Create keys and `deposit_data-*.json`](#step-2-create-keys-and-deposit_data-json-3)

        - [Arguments](#arguments-2)

        - [Successful message](#successful-message-2)

  - [For Windows users](#for-windows-users)

    - [Option 1. Download binary executable file](#option-1-download-binary-executable-file-1)

      - [Step 1. Installation](#step-1-installation-3)

      - [Step 2. Create keys and `deposit_data-*.json`](#step-2-create-keys-and-deposit_data-json-4)

        - [Language Argument](#language-argument-2)

        - [Commands](#commands-3)

        - [Arguments](#arguments-3)

    - [Option 2. Build `deposit-cli` with native Python](#option-2-build-deposit-cli-with-native-python-1)

      - [Step 0. Python version checking](#step-0-python-version-checking-2)

      - [Step 1. Installation](#step-1-installation-4)

      - [Step 2. Create keys and `deposit_data-*.json`](#step-2-create-keys-and-deposit_data-json-5)

        - [Language Argument](#language-argument-3)

        - [Commands](#commands-4)

        - [Arguments](#arguments-4)

    - [Option 3. Build `deposit-cli` with `virtualenv`](#option-3-build-deposit-cli-with-virtualenv-1)

      - [Step 0. Python version checking](#step-0-python-version-checking-3)

      - [Step 1. Installation](#step-1-installation-5)

      - [Step 2. Create keys and `deposit_data-*.json`](#step-2-create-keys-and-deposit_data-json-6)

        - [Language Argument](#language-argument-4)

        - [Commands](#commands-5)

        - [Arguments](#arguments-5)

- [Development](#development)

  - [Install basic requirements](#install-basic-requirements)

  - [Install testing requirements](#install-testing-requirements)

  - [Run tests](#run-tests)

  - [Building Binaries](#building-binaries)

      - [Mac M1 Binaries](#mac-m1-binaries)

## Introduction

`deposit-cli` is a tool for creating [EIP-2335 format](https://eips.ethereum.org/EIPS/eip-2335) BLS12-381 keystores and a corresponding `deposit_data*.json` file for [Ethereum Staking Launchpad](https://github.com/ethereum/staking-launchpad).

- **Warning: Please generate your keystores on your own safe, completely offline device.**

- **Warning: Please backup your mnemonic, keystores, and password securely.**

Please read [Launchpad Validator FAQs](https://launchpad.ethereum.org/faq#keys) before generating the keys.

You can find the audit report by Trail of Bits [here](https://github.com/trailofbits/publications/blob/master/reviews/ETH2DepositCLI.pdf).

## Tutorial for users

### Build requirements

- [Python **3.8+**](https://www.python.org/about/gettingstarted/)

- [pip3](https://pip.pypa.io/en/stable/installing/)

### For Linux or MacOS users

#### File Permissions

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

#### Option 1. Download binary executable file

##### Step 1. Installation

See [releases page](https://github.com/ethereum/staking-deposit-cli/releases) to download and decompress the corresponding binary files.

##### Step 2. Create keys and `deposit_data-*.json`

Run the following command to enter the interactive CLI and generate keys from a new mnemonic:

```sh

./deposit new-mnemonic

```

or run the following command to enter the interactive CLI and generate keys from an existing:

```sh

./deposit existing-mnemonic

```

###### `language` Argument

The Launchpad offers many language/internationalization options. If you wish to select one as a CLI argument, it must be passed in before one of the commands is chosen.

| Argument | Type | Description |

| -------- | -------- | -------- |

| `--language` | String. Options: `العربية`, `ελληνικά`, `English`, `Français`, `Bahasa melayu`, `Italiano`, `日本語`, `한국어`, `Português do Brasil`, `român`, `简体中文`. Default to `English` | The language you wish to use the CLI in. |

###### `--non_interactive` flag

**Warning: with this flag, there will be no confirmation step(s) to verify the input value(s). Please use it carefully.**

| Argument | Type | Description |

| -------- | -------- | -------- |

| `--non_interactive` | Flag | Run CLI in non-interactive mode. |

###### Commands

The CLI offers different commands depending on what you want to do with the tool.

| Command | Description |

| ------- | ----------- |

| `new-mnemonic` | (Recommended) This command is used to generate keystores with a new mnemonic. |

| `existing-mnemonic` | This command is used to re-generate or derive new keys from your existing mnemonic. Use this command, if (i) you have already generated keys with this CLI before, (ii) you want to reuse your mnemonic that you know is secure that you generated elsewhere (reusing your eth1 mnemonic .etc), or (iii) you lost your keystores and need to recover your keys. |

###### `new-mnemonic` Arguments

You can use `new-mnemonic --help` to see all arguments. Note that if there are missing arguments that the CLI needs, it will ask you for them.

| Argument | Type | Description |

| -------- | -------- | -------- |

| `--num_validators`  | Non-negative integer | The number of signing keys you want to generate. Note that the child key(s) are generated via the same master key. |

| `--mnemonic_language` | String. Options: `简体中文`, `繁體中文`, `český jazyk`, `English`, `Italiano`, `한국어`, `Português`, `Español`. Default to `English` | The language of the mnemonic word list |

| `--folder` | String. Pointing to `./validator_keys` by default | The folder path for the keystore(s) and deposit(s) |

| `--chain` | String. `mainnet` by default | The chain setting for the signing domain. |

| `--execution_address` (or `--eth1_withdrawal_address`) | String. Eth1 address in hexadecimal encoded form | If this field is set and valid, the given Eth1 address will be used to create the withdrawal credentials. Otherwise, it will generate withdrawal credentials with the mnemonic-derived withdrawal public key in [ERC-2334 format](https://eips.ethereum.org/EIPS/eip-2334#eth2-specific-parameters). |

###### `existing-mnemonic` Arguments

You can use `existing-mnemonic --help` to see all arguments. Note that if there are missing arguments that the CLI needs, it will ask you for them.

| Argument | Type | Description |

| -------- | -------- | -------- |

| `--validator_start_index` | Non-negative integer | 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 (eg, if you've generated 4 keys before (keys #0, #1, #2, #3), then enter 4 here.|

| `--num_validators`  | Non-negative integer | The number of new signing keys you want to generate. Note that the child key(s) are generated via the same master key. |

| `--folder` | String. Pointing to `./validator_keys` by default | The folder path for the keystore(s) and deposit(s) |

| `--chain` | String. `mainnet` by default | The chain setting for the signing domain. |

| `--execution_address` (or `--eth1_withdrawal_address`) | String. Eth1 address in hexadecimal encoded form | If this field is set and valid, the given Eth1 address will be used to create the withdrawal credentials. Otherwise, it will generate withdrawal credentials with the mnemonic-derived withdrawal public key in [ERC-2334 format](https://eips.ethereum.org/EIPS/eip-2334#eth2-specific-parameters). |

###### Successful message

You will see the following messages after successfully generated the keystore(s) and the deposit(s):

```text

Creating your keys:               [####################################]  /

Creating your keystores:          [####################################]  /

Creating your depositdata:        [####################################]  /

Verifying your keystores:         [####################################]  /

Verifying your deposits:          [####################################]  /

Success!

Your keys can be found at: 

```

###### `generate-bls-to-execution-change` Arguments 

You can use `bls-to-execution-change --help` to see all arguments. Note that if there are missing arguments that the CLI needs, it will ask you for them.

| Argument | Type | Description |

| -------- | -------- | -------- |

| `--bls_to_execution_changes_folder` | String. Pointing to `./bls_to_execution_changes` by default | The folder path for the `bls_to_execution_change-*` JSON file(s) |

| `--chain` | String. `mainnet` by default | The chain setting for the signing domain. |

| `--mnemonic` | String. mnemonic split by space.  | The mnemonic you used to create withdrawal credentials. |

| `--mnemonic_password` | Optional string. Empty by default. | The mnemonic password you used in your key generation. Note: It's not the keystore password. |

| `--validator_start_index` | Non-negative integer | The index position for the keys to start generating withdrawal credentials in [ERC-2334 format](https://eips.ethereum.org/EIPS/eip-2334#eth2-specific-parameters). |

| `--validator_indices` | String of integer(s) | 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` | String of hexstring(s). | 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. |

| `--execution_address` (or `--eth1_withdrawal_address`) | String. Eth1 address in hexadecimal encoded form | If this field is set and valid, the given Eth1 address will be used to create the withdrawal credentials. Otherwise, it will generate withdrawal credentials with the mnemonic-derived withdrawal public key in [ERC-2334 format](https://eips.ethereum.org/EIPS/eip-2334#eth2-specific-parameters). |

| `--devnet_chain_setting` | String. JSON string `'{"network_name": "", "genesis_fork_version": "", "genesis_validator_root": ""}'` | The custom chain setting of a devnet or testnet. Note that it will override your `--chain` choice. |

#### Option 2. Build `deposit-cli` with native Python

##### Step 0. Python version checking

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

```sh

python3 -V

```

##### Step 1. Installation

Install the dependencies:

```sh

pip3 install -r requirements.txt

python3 setup.py install

```

Or use the helper script:

```sh

./deposit.sh install

```

##### Step 2. Create keys and `deposit_data-*.json`

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

```sh

./deposit.sh new-mnemonic

```

or

```sh

./deposit.sh existing-mnemonic

```

You can also run the tool with optional arguments:

```sh

./deposit.sh new-mnemonic --num_validators= --mnemonic_language=english --chain= --folder=

```

```sh

./deposit.sh existing-mnemonic --num_validators= --validator_start_index= --chain= --folder=

```

###### Language Argument

See [here](#language_argument) for `--language` arguments.

###### Commands

See [here](#commands)

###### Arguments

See [here](#new-mnemonic-arguments) for `new-mnemonic` arguments

See [here](#existing-mnemonic-arguments) for `existing-mnemonic` arguments

See [here](#generate-bls-to-execution-change-arguments) for `generate-bls-to-execution-change` arguments

###### Successful message

See [here](#successful-message)

#### Option 3. Build `deposit-cli` with `virtualenv`

##### Step 0. Python version checking

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

```sh

python3 -V

```

##### Step 1. Installation

For the [virtualenv](https://virtualenv.pypa.io/en/latest/) users, you can create a new venv:

```sh

pip3 install virtualenv

virtualenv venv

source venv/bin/activate

```

and install the dependencies:

```sh

python3 setup.py install

pip3 install -r requirements.txt

```

##### Step 2. Create keys and `deposit_data-*.json`

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

```sh

python3 ./staking_deposit/deposit.py new-mnemonic

```

or

```sh

python3 ./staking_deposit/deposit.py existing-mnemonic

```

You can also run the tool with optional arguments:

```sh

python3 ./staking_deposit/deposit.py new-mnemonic --num_validators= --mnemonic_language=english --chain= --folder=

```

```sh

python3 ./staking_deposit/deposit.py existing-mnemonic --num_validators= --validator_start_index= --chain= --folder=

```

###### Language Argument

See [here](#language_argument) for `--language` arguments.

###### Commands

See [here](#commands)

###### Arguments

See [here](#new-mnemonic-arguments) for `new-mnemonic` arguments

See [here](#existing-mnemonic-arguments) for `existing-mnemonic` arguments

See [here](#generate-bls-to-execution-change-arguments) for `generate-bls-to-execution-change` arguments

#### Option 4. Use Docker image

##### Step 1. Build the docker image

Run the following command to locally build the docker image:

```sh

make build_docker

```

##### Step 2. Create keys and `deposit_data-*.json`

Run the following command to enter the interactive CLI:

```sh

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

```

You can also run the tool with optional arguments:

```sh

docker run -it --rm -v $(pwd)/validator_keys:/app/validator_keys ethereum/staking-deposit-cli new-mnemonic --num_validators= --mnemonic_language=english --folder=

```

Example for 1 validator on the [Prater testnet](https://prater.launchpad.ethereum.org/) using english:

```sh

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

```

###### Arguments

See [here](#arguments)

###### Successful message

See [here](#successful-message)

----

### For Windows users

#### Option 1. Download binary executable file

##### Step 1. Installation

See [releases page](https://github.com/ethereum/staking-deposit-cli/releases) to download and decompress the corresponding binary files.

##### Step 2. Create keys and `deposit_data-*.json`

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

```sh

deposit.exe new-mnemonic

```

or

```sh

deposit.exe existing-mnemonic

```

You can also run the tool with optional arguments:

```sh

deposit.exe new-mnemonic --num_validators= --mnemonic_language=english --chain= --folder=

```

```sh

deposit.exe existing-mnemonic --num_validators= --validator_start_index= --chain= --folder=

```

###### Language Argument

See [here](#language_argument) for `--language` arguments.

###### Commands

See [here](#commands)

###### Arguments

See [here](#new-mnemonic-arguments) for `new-mnemonic` arguments

See [here](#existing-mnemonic-arguments) for `existing-mnemonic` arguments

See [here](#generate-bls-to-execution-change-arguments) for `generate-bls-to-execution-change` arguments

#### Option 2. Build `deposit-cli` with native Python

##### Step 0. Python version checking

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

```sh

python -V

```

##### Step 1. Installation

Install the dependencies:

```sh

pip3 install -r requirements.txt

python setup.py install

```

Or use the helper script:

```sh

sh deposit.sh install

```

##### Step 2. Create keys and `deposit_data-*.json`

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

```sh

./deposit.sh new-mnemonic

```

or

```sh

./deposit.sh existing-mnemonic

```

You can also run the tool with optional arguments:

```sh

./deposit.sh new-mnemonic --num_validators= --mnemonic_language=english --chain= --folder=

```

```sh

./deposit.sh existing-mnemonic --num_validators= --validator_start_index= --chain= --folder=

```

###### Language Argument

See [here](#language_argument) for `--language` arguments.

###### Commands

See [here](#commands)

###### Arguments

See [here](#new-mnemonic-arguments) for `new-mnemonic` arguments

See [here](#existing-mnemonic-arguments) for `existing-mnemonic` arguments

See [here](#generate-bls-to-execution-change-arguments) for `generate-bls-to-execution-change` arguments

#### Option 3. Build `deposit-cli` with `virtualenv`

##### Step 0. Python version checking

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

```cmd

python -V

```

##### Step 1. Installation

For the [virtualenv](https://virtualenv.pypa.io/en/latest/) users, you can create a new venv:

```cmd

pip3 install virtualenv

virtualenv venv

.\venv\Scripts\activate

```

and install the dependencies:

```cmd

python setup.py install

pip3 install -r requirements.txt

```

##### Step 2. Create keys and `deposit_data-*.json`

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

```cmd

python .\staking_deposit\deposit.py new-mnemonic

```

or

```cmd

python .\staking_deposit\deposit.py existing-mnemonic

```

You can also run the tool with optional arguments:

```cmd

python .\staking_deposit\deposit.py new-mnemonic --num_validators= --mnemonic_language=english --chain= --folder=

```

```cmd

python .\staking_deposit\deposit.pyexisting-mnemonic --num_validators= --validator_start_index= --chain= --folder=

```

###### Language Argument

See [here](#language_argument) for `--language` arguments.

###### Commands

See [here](#commands)

###### Arguments

See [here](#new-mnemonic-arguments) for `new-mnemonic` arguments

See [here](#existing-mnemonic-arguments) for `existing-mnemonic` arguments

See [here](#generate-bls-to-execution-change-arguments) for `generate-bls-to-execution-change` arguments

## Development

### Install basic requirements

```sh

python3 -m pip install -r requirements.txt

python3 setup.py install

```

### Install testing requirements

```sh

python3 -m pip install -r requirements_test.txt

```

### Run tests

```sh

python3 -m pytest .

```

### Building Binaries

**Developers Only**

##### Mac M1 Binaries

👋This is not the section you are looking for.👋

If you are trying to **build the binary** on macos with an M1 Mac and you are using pyenv to manage your python version. You'll probably need to reinstall a given python version using:

```

env PYTHON_CONFIGURE_OPTS="--enable-framework" pyenv install 3.10.3

```