go-deposit

A Golang library and CLI tool for generating validator keys and deposit data to stake on Ethereum and compatible networks. Inspired by ethereum/staking-deposit-cli.

Features

• Generate new or use existing mnemonics to create validator keys
• BLS key derivation following Ethereum 2.0 standards
• Generate password-protected keystores in EIP-2335 format
• Support for BLS locked (type 0x00) & ETH1 withdrawal addresses (type 0x01 & 0x02)
• Configurable number of validator keys and deposit amounts
• Built-in chain presets for Ethereum mainnet, sepolia, holesky and hoodi
• Support for custom chain configuration files for additional networks
• Generation of deposit_data.json for the Ethereum launchpad, prysmctl, and other tools
• Non-interactive CLI mode for automation and scripting
• Usable as a Go library for integration into other applications

Installation

Using Docker

docker pull ghcr.io/curvegrid/go-deposit:latest

Using Go Install

go install github.com/curvegrid/go-deposit/cmd/deposit@latest

From Source

1. Clone the repository:

git clone https://github.com/curvegrid/go-deposit.git
cd go-deposit

2. Build the binary:

make build

3. Install the binary:

make install

Usage

CLI tool to generate validator keys and deposit data for Ethereum and compatible networks.

Usage:
  deposit [command]

Available Commands:
  existing    Use an existing mnemonic to generate validator keys
  new         Generate a new mnemonic and validator keys

Flags:
      --amount uint                       Deposit amount in Gwei (defaults to MIN_ACTIVATION_BALANCE from config)
      --chain string                      Built-in network preset to use (mainnet, sepolia, holesky, hoodi) (default "mainnet")
      --chain-config string               Path to a custom network configuration file (overrides --chain)
  -h, --help                              help for deposit
      --mnemonic-file string              Path to file containing the mnemonic phrase
      --non-interactive                   Run in non-interactive mode
      --num-validators int                Number of validators to generate (default 1)
      --output-dir string                 Output directory for validator keys (default ".")
      --password-file string              Path to file containing the password for encrypting keystores
  -v, --version                           version for deposit
      --withdrawal-addr address           Ethereum address for withdrawals (highly recommended)
      --withdrawal-type withdrawal-type   Withdrawal type (0=BLS locked, 1=execution address, 2=compounding); required when --withdrawal-addr is set

Use "deposit [command] --help" for more information about a command.

Generate New Mnemonic

To generate a new mnemonic and validator keys:

deposit new --chain=mainnet --num-validators=1 --withdrawal-addr=0x1234567890123456789012345678901234567890 --withdrawal-type=2

Use Existing Mnemonic

The tool supports multiple secure methods for providing your existing mnemonic, prioritized in the following order:

1. Environment Variable

export DEPOSIT_MNEMONIC="your mnemonic phrase here"
deposit existing --chain=mainnet --num-validators=1 --withdrawal-addr=0x1234567890123456789012345678901234567890 --withdrawal-type=2

2. Mnemonic File

Create a file with your mnemonic and set secure permissions:

echo "your mnemonic phrase here" > mnemonic.txt
chmod 600 mnemonic.txt
deposit existing --mnemonic-file=mnemonic.txt --chain=mainnet --num-validators=1 --withdrawal-addr=0x1234567890123456789012345678901234567890 --withdrawal-type=2

The tool will warn you if the file has overly permissive permissions (> 0600).

3. Interactive Prompt

deposit existing --chain=mainnet --num-validators=1 --withdrawal-addr=0x1234567890123456789012345678901234567890 --withdrawal-type=2

The tool will securely prompt you to enter your mnemonic phrase.

Non-Interactive Mode

For automated scripts, you can use non-interactive mode. There are two secure methods to provide your password:

1. Environment Variable

export DEPOSIT_PASSWORD="your-secure-password"
deposit new --non-interactive --chain=mainnet --num-validators=1 --withdrawal-addr=0x1234567890123456789012345678901234567890 --withdrawal-type=2

2. Password File

Create a file containing your password:

echo "your-secure-password" > password.txt
chmod 600 password.txt
deposit new --non-interactive --chain=mainnet --num-validators=1 --withdrawal-addr=0x1234567890123456789012345678901234567890 --withdrawal-type=2 --password-file=password.txt

Chain Configuration

The tool supports built-in chain presets as well as custom configurations:

Using Built-in Presets

deposit new --chain=mainnet

Using Custom Configuration

You can provide a custom YAML configuration file:

deposit new --chain-config=path/to/custom/config.yaml

Output

The tool will generate the following files:

1. Validator Keystores: Password-protected keystores for each validator in EIP-2335 format
2. Deposit Data: A JSON file containing deposit data for the Ethereum launchpad

Chain Configurations

The deposit-cli uses Prysm's native configuration system for built-in networks and supports custom YAML configuration files for additional networks.

Built-in Chains

The tool includes built-in configurations for:

• mainnet: Ethereum mainnet
• sepolia: Sepolia testnet
• holesky: Holesky testnet
• hoodi: Hoodi testnet

These configurations are automatically loaded from Prysm's internal configuration system and do not require external files.

Custom Chains

You can create your own chain configuration by providing a YAML file. All amounts are specified in Gwei (1 ETH = 10⁹ Gwei). The deposit amount will default to MIN_ACTIVATION_BALANCE if not specified with the --amount flag.

Custom configuration file example:

# Custom chain configuration
PRESET_BASE: mainnet
CONFIG_NAME: "custom-chain"
GENESIS_FORK_VERSION: 0x01000000
DEPOSIT_CHAIN_ID: 1234
MIN_DEPOSIT_AMOUNT: 1000000000 # 1 ETH in gwei
MIN_ACTIVATION_BALANCE: 32000000000 # 32 ETH in gwei
MAX_EFFECTIVE_BALANCE: 32000000000 # 32 ETH in gwei
MAX_EFFECTIVE_BALANCE_ELECTRA: 2048000000000 # 2048 ETH in gwei
SLOTS_PER_EPOCH: 32
SECONDS_PER_SLOT: 12

Balance Boundaries

• Deposits must be at least MIN_DEPOSIT_AMOUNT (1 ETH)
• Standard validator deposits are typically MIN_ACTIVATION_BALANCE (32 ETH)
• Deposits above MAX_EFFECTIVE_BALANCE (32 ETH) will use Electra mode
• The absolute maximum deposit is MAX_EFFECTIVE_BALANCE_ELECTRA (2048 ETH)

Disclaimer

This tool is provided as-is without any warranties. Use at your own risk. Always verify the deposit data and key generation before using it with actual funds.

Contributing

See CONTRIBUTING.md for guidelines on contributing to this project.

License

This project is licensed under the GNU General Public License v3.0.

Credits

The Go gopher was designed by Renée French.