deposit

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 16, 2025 License: GPL-3.0 Imports: 17 Imported by: 0

README

go-deposit

GoDoc CI Go Report Card

Go Deposit Gopher

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
  1. Build the binary:
make build
  1. 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.

Documentation

Overview

Package deposit provides Ethereum-specific functionality for deposit key management

Index

Constants

View Source 
const (
	// WithdrawalKeyPath is the derivation path for ETH2.0 validator withdrawal keys
	WithdrawalKeyPath = "m/12381/3600/%d/0"
	// SigningKeyPath is the derivation path for ETH2.0 validator signing keys
	SigningKeyPath = "m/12381/3600/%d/0/0"
)
View Source 
const (
	// AddressLength is the length of a valid Ethereum address
	// Format: "0x" + 40 hex characters
	AddressLength = 42
)

Variables

This section is empty.

Functions

func ComputeDepositRoot 

func ComputeDepositRoot(pubkey []byte, withdrawalCredentials [32]byte, amount uint64, signature []byte) ([]byte, error)

ComputeDepositRoot computes the deposit data root

func DecodeForkVersion 

func DecodeForkVersion(forkVersionBytes []byte) ([4]byte, error)

DecodeForkVersion converts a byte slice fork version to bytes array

func GenerateDepositData 

func GenerateDepositData(
	keys *DerivedKeys,
	signer Signer,
	keystoreCreator KeystoreCreator,
	withdrawalCredential [32]byte,
	password string,
	config *params.BeaconChainConfig,
	depositAmount uint64,
) (*Deposit, *ValidatorKeystore, error)

GenerateDepositData creates deposit data and keystore using provided dependencies

func GenerateWithdrawalCredential 

func GenerateWithdrawalCredential(pubkey []byte, withdrawalType WithdrawalType, withdrawalAddr Address) ([32]byte, error)

GenerateWithdrawalCredential is the default implementation for generating withdrawal credentials

func GetBuiltinNetworks 

func GetBuiltinNetworks() []string

GetBuiltinNetworks returns the list of built-in network names

func IsBuiltinNetwork 

func IsBuiltinNetwork(name string) bool

IsBuiltinNetwork checks if a network name is built-in

func LoadNetworkConfig 

func LoadNetworkConfig(chain string, chainConfigPath string) (*params.BeaconChainConfig, error)

LoadNetworkConfig loads network configuration either from a built-in preset or custom file

func SignDepositData 

func SignDepositData(
	privateKey *e2types.BLSPrivateKey,
	pubkey []byte,
	withdrawalCredentials [32]byte,
	amount uint64,
	forkVersion [4]byte,
) ([]byte, []byte, error)

SignDepositData signs deposit data with the given parameters

Types

type Address 

type Address [20]byte

Address represents an Ethereum address

func MustAddress 

func MustAddress(s string) Address

MustAddress parses a string to an Address and panics on error

func (Address) IsEmpty 

func (a Address) IsEmpty() bool

IsEmpty returns true if the address is empty

func (*Address) Set 

func (a *Address) Set(s string) error

Set implements pflag.Value.

func (Address) String 

func (a Address) String() string

String implements pflag.Value.

func (Address) Type 

func (a Address) Type() string

Type implements pflag.Value.

type Deposit 

type Deposit struct {
	PublicKey             string `json:"pubkey"`
	WithdrawalCredentials string `json:"withdrawal_credentials"`
	Amount                uint64 `json:"amount"`
	Signature             string `json:"signature"`
	DepositMessageRoot    string `json:"deposit_message_root"`
	DepositDataRoot       string `json:"deposit_data_root"`
	ForkVersion           string `json:"fork_version"`
	NetworkName           string `json:"network_name"`
	DepositCLIVersion     string `json:"deposit_cli_version"`
}

Deposit represents the Ethereum 2.0 deposit data structure for JSON output

func CreateDepositData 

func CreateDepositData(
	pubkey []byte,
	withdrawalCredentials [32]byte,
	signature []byte,
	depositMessageRoot []byte,
	amount uint64,
	config *params.BeaconChainConfig,
) (*Deposit, error)

CreateDepositData creates a deposit data structure

type DerivedKeys 

type DerivedKeys struct {
	WithdrawalPrivateKey *e2types.BLSPrivateKey
	SigningPrivateKey    *e2types.BLSPrivateKey
	WithdrawalPublicKey  []byte
	SigningPublicKey     []byte
	Index                int
}

DerivedKeys contains validator signing and withdrawal keys

func DeriveKeysFromMnemonic 

func DeriveKeysFromMnemonic(mnemonic string, index int) (*DerivedKeys, error)

DeriveKeysFromMnemonic generates keys from a mnemonic using Ethereum 2.0 key derivation

type KeystoreCreator 

type KeystoreCreator func(
	keys *DerivedKeys,
	password string,
) (*ValidatorKeystore, error)

KeystoreCreator creates an encrypted keystore with the given password

type KeystoreInfo 

type KeystoreInfo struct {
	Path              string    `json:"path"`
	PublicKey         string    `json:"pubkey"`
	WithdrawalPK      string    `json:"withdrawal_pk,omitempty"`
	DepositDataPath   string    `json:"deposit_data_path,omitempty"`
	CreationTimestamp time.Time `json:"creation_timestamp"`
}

KeystoreInfo represents information about a generated keystore

type Signer 

type Signer func(
	signingPrivateKey *e2types.BLSPrivateKey,
	signingPublicKey []byte,
	withdrawalCredentials [32]byte,
	depositAmount uint64,
	forkVersion [4]byte,
) ([]byte, []byte, error)

Signer signs deposit data with the given parameters

type ValidatorKeystore 

type ValidatorKeystore struct {
	Keystore     string       `json:"keystore"`
	KeystoreInfo KeystoreInfo `json:"keystore_info"`
}

ValidatorKeystore contains keystore information

func CreateKeystore 

func CreateKeystore(keys *DerivedKeys, password string) (*ValidatorKeystore, error)

CreateKeystore is the default KeystoreCreator implementation

type WithdrawalType 

type WithdrawalType uint8

WithdrawalType represents the type of withdrawal credential 

const (
	// WithdrawTypeBLS (0x00) - BLS withdrawal credentials
	WithdrawTypeBLS WithdrawalType = iota
	// WithdrawTypeETH1 (0x01) - Regular validator withdrawal credentials with an ETH1 address
	WithdrawTypeETH1
	// WithdrawTypeCompounding (0x02) - Compounding validator withdrawal credentials with an ETH1 address
	WithdrawTypeCompounding
)

func ParseWithdrawalType 

func ParseWithdrawalType(value uint8) (WithdrawalType, error)

ParseWithdrawalType parses a uint8 to a valid WithdrawalType

func (*WithdrawalType) Set 

func (w *WithdrawalType) Set(s string) error

Set implements pflag.Value.

func (WithdrawalType) String 

func (w WithdrawalType) String() string

String implements pflag.Value.

func (WithdrawalType) Type 

func (w WithdrawalType) Type() string

Type implements pflag.Value.

Source Files

View all Source files

Directories

Path Synopsis
cmd
deposit command
Package main implements the deposit-cli command line tool for managing Ethereum validator deposits
 Package main implements the deposit-cli command line tool for managing Ethereum validator deposits
internal
test
Package test defines shared fixtures for internal testing.
 Package test defines shared fixtures for internal testing.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.