direct

Documentation

Overview

Package direct defines an implementation of an on-disk, EIP-2335 keystore.json approach towards defining validator accounts in Prysm. A validating private key is encrypted using a passphrase and its resulting encrypted file is stored as a keystore.json file under a unique, human-readable, account namespace. This direct keymanager approach relies on storing account information on-disk, making it trivial to import, export and list all associated accounts for a user.

EIP-2335 is a keystore format defined by https://eips.ethereum.org/EIPS/eip-2335 for storing and defining encryption for BLS12-381 private keys, utilized by eth2. This keystore.json format is not compatible with the current keystore standard used in eth1 due to a lack of support for KECCAK-256. Passwords utilized for key encryptions are strings of arbitrary unicode characters. The password is first converted to its NFKD representation, stripped of control codes specified in the EIP link above, and finally the password is UTF-8 encoded.

Accounts are stored on disk according to the following structure using human-readable account namespaces as directories:

wallet-dir/
  keymanageropts.json
  personally-conscious-echidna/
    keystore.json
    deposit_data.ssz
    deposit_transaction.rlp
  shy-extroverted-robin/
    keystore.json
    deposit_data.ssz
    deposit_transaction.rlp
passwords/
  personally-conscious-echidna.pass
  shy-extroverted-robin.pass

EIP-2335 keystores are stored alongside deposit data credentials for the created validator accounts. An additional deposit_transaction.rlp file is stored under the account, containing a raw bytes eth1 transaction data ready to be used to submit a 32ETH deposit to the eth2 deposit contract for a validator. Passwords are stored in a separate directory for easy unlocking of the associated keystores by an account namespace.

This direct keymanager can be customized via a keymanageropts.json file, which has the following JSON schema as its options:

{
  direct_eip_version: string
}

Currently, the only supported value for `direct_eip_version` is "EIP-2335".

Index

• Constants
• type Config
  • func DefaultConfig() *Config
  • func UnmarshalConfigFile(r io.ReadCloser) (*Config, error)
• type EnglishMnemonicGenerator
  • func (m *EnglishMnemonicGenerator) ConfirmAcknowledgement(phrase string) error
  • func (m *EnglishMnemonicGenerator) Generate(data []byte) (string, error)
• type Keymanager
  • func NewKeymanager(ctx context.Context, wallet Wallet, cfg *Config) (*Keymanager, error)
  • func (dr *Keymanager) CreateAccount(ctx context.Context, password string) (string, error)
  • func (dr *Keymanager) FetchValidatingPublicKeys(ctx context.Context) ([][48]byte, error)
  • func (dr *Keymanager) MarshalConfigFile(ctx context.Context) ([]byte, error)
  • func (dr *Keymanager) Sign(ctx context.Context, req *validatorpb.SignRequest) (bls.Signature, error)
• type SeedPhraseFactory
• type Wallet

Constants

const (
	// DepositTransactionFileName for the encoded, eth1 raw deposit tx data
	// for a validator account.
	DepositTransactionFileName = "deposit_transaction.rlp"
	// TimestampFileName stores a timestamp for account creation as a
	// file for a direct keymanager account.
	TimestampFileName = "created_at.txt"
)

Types

type Config

type Config struct {
	EIPVersion string `json:"direct_eip_version"`
}

Config for a direct keymanager.

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig for a direct keymanager implementation.

func UnmarshalConfigFile

func UnmarshalConfigFile(r io.ReadCloser) (*Config, error)

UnmarshalConfigFile attempts to JSON unmarshal a direct keymanager configuration file into the *Config{} struct.

type EnglishMnemonicGenerator

type EnglishMnemonicGenerator struct{}

EnglishMnemonicGenerator implements methods for creating mnemonic seed phrases in english using a given source of entropy such as a private key.

func (*EnglishMnemonicGenerator) ConfirmAcknowledgement

func (m *EnglishMnemonicGenerator) ConfirmAcknowledgement(phrase string) error

ConfirmAcknowledgement displays the mnemonic phrase to the user and confirms the user has written down the phrase securely offline.

func (*EnglishMnemonicGenerator) Generate

func (m *EnglishMnemonicGenerator) Generate(data []byte) (string, error)

Generate a mnemonic seed phrase in english using a source of entropy given as raw bytes.

type Keymanager

type Keymanager struct {
	// contains filtered or unexported fields
}

Keymanager implementation for direct keystores utilizing EIP-2335.

func NewKeymanager

func NewKeymanager(ctx context.Context, wallet Wallet, cfg *Config) (*Keymanager, error)

NewKeymanager instantiates a new direct keymanager from configuration options.

func (*Keymanager) CreateAccount

func (dr *Keymanager) CreateAccount(ctx context.Context, password string) (string, error)

CreateAccount for a direct keymanager implementation. This utilizes the EIP-2335 keystore standard for BLS12-381 keystores. It stores the generated keystore.json file in the wallet and additionally generates a mnemonic for withdrawal credentials. At the end, it logs the raw deposit data hex string for users to copy.

func (*Keymanager) FetchValidatingPublicKeys

func (dr *Keymanager) FetchValidatingPublicKeys(ctx context.Context) ([][48]byte, error)

FetchValidatingPublicKeys fetches the list of public keys from the direct account keystores.

func (*Keymanager) MarshalConfigFile

func (dr *Keymanager) MarshalConfigFile(ctx context.Context) ([]byte, error)

MarshalConfigFile returns a marshaled configuration file for a direct keymanager.

func (*Keymanager) Sign

func (dr *Keymanager) Sign(ctx context.Context, req *validatorpb.SignRequest) (bls.Signature, error)

Sign signs a message using a validator key.

type SeedPhraseFactory

type SeedPhraseFactory interface {
	Generate(data []byte) (string, error)
	ConfirmAcknowledgement(phrase string) error
}

SeedPhraseFactory defines a struct which can generate new seed phrases in human-readable format from a source of entropy in raw bytes. It also provides methods for verifying a user has successfully acknowledged the mnemonic phrase and written it down offline.

type Wallet

type Wallet interface {
	AccountsDir() string
	AccountNames() ([]string, error)
	ReadPasswordForAccount(accountName string) (string, error)
	ReadFileForAccount(accountName string, fileName string) ([]byte, error)
	WriteAccountToDisk(ctx context.Context, password string) (string, error)
	WriteFileForAccount(ctx context.Context, accountName string, fileName string, data []byte) error
}

Wallet defines a struct which has capabilities and knowledge of how to read and write important accounts-related files to the filesystem. Useful for keymanager to have persistent capabilities for accounts on-disk.