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, backup 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": "EIP-2335"
}

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

Index

• Constants
• func MarshalOptionsFile(ctx context.Context, opts *KeymanagerOpts) ([]byte, error)
• type AccountStore
• type Keymanager
  • func NewInteropKeymanager(ctx context.Context, offset uint64, numValidatorKeys uint64) (*Keymanager, error)
  • func NewKeymanager(ctx context.Context, cfg *SetupConfig) (*Keymanager, error)
  • func (dr *Keymanager) CreateAccount(ctx context.Context) ([]byte, *ethpb.Deposit_Data, error)
  • func (dr *Keymanager) DeleteAccounts(ctx context.Context, publicKeys [][]byte) error
  • func (dr *Keymanager) ExtractKeystores(ctx context.Context, publicKeys []bls.PublicKey, password string) ([]*v2keymanager.Keystore, error)
  • func (dr *Keymanager) FetchValidatingPublicKeys(ctx context.Context) ([][48]byte, error)
  • func (dr *Keymanager) ImportKeystores(ctx context.Context, keystores []*v2keymanager.Keystore, ...) error
  • func (dr *Keymanager) KeymanagerOpts() *KeymanagerOpts
  • func (dr *Keymanager) RefreshWalletPassword(ctx context.Context) error
  • func (dr *Keymanager) Sign(ctx context.Context, req *validatorpb.SignRequest) (bls.Signature, error)
  • func (dr *Keymanager) SubscribeAccountChanges(pubKeysChan chan [][48]byte) event.Subscription
  • func (dr *Keymanager) ValidatingAccountNames() ([]string, error)
• type KeymanagerOpts
  • func DefaultKeymanagerOpts() *KeymanagerOpts
  • func UnmarshalOptionsFile(r io.ReadCloser) (*KeymanagerOpts, error)
  • func (opts *KeymanagerOpts) String() string
• type SetupConfig

Constants

const (
	// KeystoreFileNameFormat exposes the filename the keystore should be formatted in.
	KeystoreFileNameFormat = "keystore-%d.json"
	// AccountsPath where all direct keymanager keystores are kept.
	AccountsPath = "accounts"
)

Functions

func MarshalOptionsFile

func MarshalOptionsFile(ctx context.Context, opts *KeymanagerOpts) ([]byte, error)

MarshalOptionsFile returns a marshaled options file for a keymanager.

Types

type AccountStore

type AccountStore struct {
	PrivateKeys [][]byte `json:"private_keys"`
	PublicKeys  [][]byte `json:"public_keys"`
}

AccountStore defines a struct containing 1-to-1 corresponding private keys and public keys for eth2 validators.

type Keymanager

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

Keymanager implementation for direct keystores utilizing EIP-2335.

func NewInteropKeymanager

func NewInteropKeymanager(ctx context.Context, offset uint64, numValidatorKeys uint64) (*Keymanager, error)

NewInteropKeymanager instantiates a new direct keymanager with the deterministically generated interop keys.

func NewKeymanager

func NewKeymanager(ctx context.Context, cfg *SetupConfig) (*Keymanager, error)

NewKeymanager instantiates a new direct keymanager from configuration options.

func (*Keymanager) CreateAccount

func (dr *Keymanager) CreateAccount(ctx context.Context) ([]byte, *ethpb.Deposit_Data, 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 withdrawal credentials. At the end, it logs the raw deposit data hex string for users to copy.

func (*Keymanager) DeleteAccounts

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

DeleteAccounts takes in public keys and removes the accounts entirely. This includes their disk keystore and cached keystore.

func (*Keymanager) ExtractKeystores

func (dr *Keymanager) ExtractKeystores(
	ctx context.Context, publicKeys []bls.PublicKey, password string,
) ([]*v2keymanager.Keystore, error)

ExtractKeystores retrieves the secret keys for specified public keys in the function input, encrypts them using the specified password, and returns their respective EIP-2335 keystores.

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) ImportKeystores

func (dr *Keymanager) ImportKeystores(
	ctx context.Context,
	keystores []*v2keymanager.Keystore,
	importsPassword string,
) error

ImportKeystores into the direct keymanager from an external source.

func (*Keymanager) KeymanagerOpts

func (dr *Keymanager) KeymanagerOpts() *KeymanagerOpts

KeymanagerOpts for the direct keymanager.

func (*Keymanager) RefreshWalletPassword

func (dr *Keymanager) RefreshWalletPassword(ctx context.Context) error

RefreshWalletPassword re-encrypts the accounts store and stores it to disk using a wallet's password which was recently changed.

func (*Keymanager) Sign

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

Sign signs a message using a validator key.

func (*Keymanager) SubscribeAccountChanges

func (dr *Keymanager) SubscribeAccountChanges(pubKeysChan chan [][48]byte) event.Subscription

SubscribeAccountChanges creates an event subscription for a channel to listen for public key changes at runtime, such as when new validator accounts are imported into the keymanager while the validator process is running.

func (*Keymanager) ValidatingAccountNames

func (dr *Keymanager) ValidatingAccountNames() ([]string, error)

ValidatingAccountNames for a direct keymanager.

type KeymanagerOpts

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

KeymanagerOpts for a direct keymanager.

func DefaultKeymanagerOpts

func DefaultKeymanagerOpts() *KeymanagerOpts

DefaultKeymanagerOpts for a direct keymanager implementation.

func UnmarshalOptionsFile

func UnmarshalOptionsFile(r io.ReadCloser) (*KeymanagerOpts, error)

UnmarshalOptionsFile attempts to JSON unmarshal a direct keymanager options file into a struct.

func (*KeymanagerOpts) String

func (opts *KeymanagerOpts) String() string

String pretty-print of a direct keymanager options.

type SetupConfig

type SetupConfig struct {
	Wallet              iface.Wallet
	Opts                *KeymanagerOpts
	SkipMnemonicConfirm bool
	Mnemonic            string
}

SetupConfig includes configuration values for initializing a keymanager, such as passwords, the wallet, and more.