keyring

README

Injective Chain Keyring Helper

Creates a new keyring from a variety of options. See ConfigOpt and related options. This keyring helper allows initializing the Cosmos SDK keyring used for signing transactions.

It allows flexibly defining a static configuration of keys, supports multiple pre-defined keys in the same keyring, and allows loading keys from a file, deriving from mnemonic, or reading plain private key bytes from a HEX string. Extremely useful for testing and local development, but also robust for production use cases.

Usage

NewCosmosKeyring(cdc codec.Codec, opts ...ConfigOpt) (sdk.AccAddress, cosmkeyring.Keyring, error)

ConfigOpts:

These options are global on the keyring level.

• WithKeyringDir option sets keyring path in the filesystem, useful when keyring backend is file.
• WithKeyringAppName option sets keyring application name (defaults to injectived)
• WithKeyringBackend sets the keyring backend. Expected values: test, file, os.
• WithUseLedger sets the option to use hardware wallet, if available on the system.

These options allow adding keys to the keyring during initialization.

• WithKey adds a single key to the keyring, without having alias name.
• WithNamedKey addes a single key to the keyring, with a name.
• WithDefaultKey sets a default key reference to use for signing (by name).

KeyConfigOpts:

These options are set per key.

• WithKeyFrom sets the key name to use for signing. Must exist in the provided keyring.
• WithKeyPassphrase sets the passphrase for keyring files. The package will fallback to os.Stdin if this option was not provided, but passphrase is required.
• WithPrivKeyHex allows specifying a private key as plain-text hex. Insecure option, use for testing only. The package will create a virtual keyring holding that key, to meet all the interfaces.
• WithMnemonic allows specifying a mnemonic phrase as plain-text hex. Insecure option, use for testing only. The package will create a virtual keyring to derive the keys and meet all the interfaces.

Examples

Initialize an in-memory keyring with a private key hex:

NewCosmosKeyring(
    cdc,
    WithKey(
        WithPrivKeyHex("e6888cb164d52e4880e08a8a5dbe69cd62f67fde3d5906f2c5c951be553b2267"),
        WithKeyFrom("sender"),
    ),
)

Initialize an in-memory keyring with a mnemonic phrase:

NewCosmosKeyring(
    s.cdc,
    WithKey(
        WithMnemonic("real simple naive ....... love"),
        WithKeyFrom("sender"),
    ),
)

Real world use case of keyring initialization from CLI flags, with a single named key set as default:

NewCosmosKeyring(
    cdc,
    WithKeyringDir(*keyringDir),
    WithKeyringAppName(*keyringAppName),
    WithKeyringBackend(Backend(*keyringBackend)),
    WithNamedKey(
        "dispatcher",
        WithKeyFrom(*dispatcherKeyFrom),
        WithKeyPassphrase(*dispatcherKeyPassphrase),
        WithPrivKeyHex(*dispatcherKeyPrivateHex),
        WithMnemonic(*dispatcherKeyMnemonic),
    ),
    WithDefaultKey(
        "dispatcher",
    ),
)

Testing

go test -v -cover

PASS
coverage: 83.1% of statements

Generating a Test Fixture

> cd testdata

> injectived keys --keyring-dir `pwd` --keyring-backend file add test

Passphrase should be test12345678 for this fixture to work.

Documentation

Index

• Variables
• func NewCosmosKeyring(cdc codec.Codec, opts ...ConfigOpt) (sdk.AccAddress, cosmkeyring.Keyring, error)
• type Backend
• type ConfigOpt
  • func WithDefaultKey(v string) ConfigOpt
  • func WithKey(opts ...KeyConfigOpt) ConfigOpt
  • func WithKeyringAppName(v string) ConfigOpt
  • func WithKeyringBackend(v Backend) ConfigOpt
  • func WithKeyringDir(v string) ConfigOpt
  • func WithNamedKey(name string, opts ...KeyConfigOpt) ConfigOpt
  • func WithUseLedger(b bool) ConfigOpt
• type KeyConfigOpt
  • func WithKeyFrom(v string) KeyConfigOpt
  • func WithKeyPassphrase(v string) KeyConfigOpt
  • func WithMnemonic(v string) KeyConfigOpt
  • func WithPrivKeyHex(v string) KeyConfigOpt

Variables

var (
	ErrCosmosKeyringCreationFailed       = errors.New("cosmos keyring creation failed")
	ErrCosmosKeyringImportFailed         = errors.New("cosmos keyring unable to import key")
	ErrDeriveFailed                      = errors.New("key derivation failed")
	ErrFailedToApplyConfigOption         = errors.New("failed to apply config option")
	ErrFailedToApplyKeyConfigOption      = errors.New("failed to apply a key config option")
	ErrFilepathIncorrect                 = errors.New("incorrect filepath")
	ErrHexFormatError                    = errors.New("hex format error")
	ErrIncompatibleOptionsProvided       = errors.New("incompatible keyring options provided")
	ErrInsufficientKeyDetails            = errors.New("insufficient cosmos key details provided")
	ErrKeyIncompatible                   = errors.New("provided key is incompatible with requested config")
	ErrKeyRecordNotFound                 = errors.New("key record not found")
	ErrPrivkeyConflict                   = errors.New("privkey conflict")
	ErrUnexpectedAddress                 = errors.New("unexpected address")
	ErrMultipleKeysWithDifferentSecurity = errors.New("key security is different: cannot mix keyring with privkeys")
)

Functions

func NewCosmosKeyring

func NewCosmosKeyring(cdc codec.Codec, opts ...ConfigOpt) (sdk.AccAddress, cosmkeyring.Keyring, error)

NewCosmosKeyring creates a new keyring from a variety of options. See ConfigOpt and related options.

Types

type Backend

type Backend string

Backend defines a known keyring backend name.

const (
	// BackendTest is a testing backend, no passphrases required.
	BackendTest Backend = "test"
	// BackendFile is a backend where keys are stored as encrypted files.
	BackendFile Backend = "file"
	// BackendOS is a backend where keys are stored in the OS key chain. Platform specific.
	BackendOS Backend = "os"
)

type ConfigOpt

type ConfigOpt func(c *cosmosKeyringConfig) error

ConfigOpt defines a known cosmos keyring option.

func WithDefaultKey

func WithDefaultKey(v string) ConfigOpt

WithDefaultKey specifies the default key (name or address) to be fetched during keyring init. This key must exist in specified keys.

func WithKey

func WithKey(opts ...KeyConfigOpt) ConfigOpt

WithKey adds an unnamed key into the keyring, based on its individual options.

func WithKeyringAppName

func WithKeyringAppName(v string) ConfigOpt

WithKeyringAppName option sets keyring application name (used by Cosmos to separate keyrings).

func WithKeyringBackend

func WithKeyringBackend(v Backend) ConfigOpt

WithKeyringBackend sets the keyring backend. Expected values: test, file, os.

func WithKeyringDir

func WithKeyringDir(v string) ConfigOpt

WithKeyringDir option sets keyring path in the filesystem, useful when keyring backend is `file`.

func WithNamedKey

func WithNamedKey(name string, opts ...KeyConfigOpt) ConfigOpt

WithNamedKey adds a key into the keyring, based on its individual options, with a given name (alias).

func WithUseLedger

func WithUseLedger(b bool) ConfigOpt

WithUseLedger sets the option to use hardware wallet, if available on the system.

type KeyConfigOpt

type KeyConfigOpt func(c *cosmosKeyConfig) error

KeyConfigOpt defines a known cosmos keyring key option.

func WithKeyFrom

func WithKeyFrom(v string) KeyConfigOpt

WithKeyFrom sets the key name to use for signing. Must exist in the provided keyring.

func WithKeyPassphrase

func WithKeyPassphrase(v string) KeyConfigOpt

WithKeyPassphrase sets the passphrase for keyring files. Insecure option, use for testing only. The package will fallback to os.Stdin if this option was not provided, but pass is required.

func WithMnemonic

func WithMnemonic(v string) KeyConfigOpt

WithMnemonic allows to specify a mnemonic pharse as plaintext. Insecure option, use for testing only. The package will create a virtual keyring to derive the keys and meet all the interfaces.

func WithPrivKeyHex

func WithPrivKeyHex(v string) KeyConfigOpt

WithPrivKeyHex allows to specify a private key as plaintext hex. Insecure option, use for testing only. The package will create a virtual keyring holding that key, to meet all the interfaces.