README
¶
Diffs between upstream and here
current diff: https://github.com/Stakedllc/go-eth2-wallet/compare/v1.14.2...wealdtech:go-eth2-wallet:v1.14.2 latest diff: https://github.com/Stakedllc/go-eth2-wallet/compare/v1.14.2...wealdtech:go-eth2-wallet:v1.15.1
go-eth2-wallet
Go library to provide access to Ethereum 2 wallets with advanced features.
** Please note that this library uses standards that are not yet final, and as such may result in changes that alter public and private keys. Do not use this library for production use just yet **
Table of Contents
Install
go-eth2-wallet is a standard Go module which can be installed with:
go get github.com/Stakedllc/go-eth2-wallet
Usage
Before using go-eth2-wallet it is important to understand the concepts behind it.
An account is the container for private keys. Each account is named, and contains information about the derivation of the private key: either the key itself, or information that can be passed to a third-party system to identify the key (e.g. for a hardware wallet). An account may or may not have a passphrase depending on the information stored within it.
A wallet is the container for accounts. Each wallet is named, and contains information about how to create new accounts: one wallet might create accounts by generating random keys, another might use a seed phrase to create accounts by a deterministic method. A wallet may or may not have a passphrase depending on the information stored within it.
A store is a storage system for wallets and accounts. The store allows access to wallets and accounts regardless of where they are. Stores can be local, for example on the filesystem, or remote, for example on Amazon's S3 storage. Stores have their own configuration, which may or may not include account IDs and passwords. Stores can be encrypted with a passphrase, in which case all data written to the store is encrypted prior to being written; this increases security where there are concerns about others accessing the data.
An overview of the architecture as laid out above is shown below, showing an application interacting with multiple local and remote stores:
And to recap: an application can access one or more stores. Each store contains a number of wallets, and each wallet contains a number of accounts.
The Ethereum 2 wallet is designed to be highly modular: additional stores and wallets can be added, allowing for the ability to upgrade features as required. This module hides the complexity that comes with that modularity and provides a simple unified API to handle all common (and not-so-common) wallet operations.
Stores
The following stores are available:
- filesystem: this stores wallets and accounts on the local filesystem.
- s3: this stores wallets and accounts on Amazon S3.
- scratch: this stores wallets and accounts in memory.
Please refer to the documentation for each store to understand its functionality and available options.
Wallets
The following wallet types are available:
- nd: this is a traditional non-deterministic wallet where private keys are generated randomly and have no relationship to each other.
- hd: this is a hierarchical deterministic wallet where private keys are generated based on a seed phrase and path.
- mpc: this is a multi-party computation wallet
Please refer to the documentation for each wallet type to understand its functionality and available options.
Examples
Opening an existing wallet from the default store
import (
e2wallet "github.com/Stakedllc/go-eth2-wallet"
)
func main() {
wallet, err := e2wallet.OpenWallet("my wallet")
if err != nil {
panic(err)
}
...
}
Creating a new wallet on the default store
import (
e2wallet "github.com/Stakedllc/go-eth2-wallet"
)
func main() {
wallet, err := e2wallet.CreateWallet("my wallet")
if err != nil {
panic(err)
}
...
}
Creating a new wallet on the Amazon S3 store
import (
e2wallet "github.com/Stakedllc/go-eth2-wallet"
s3 "github.com/wealdtech/go-eth2-wallet-store-s3"
)
func main() {
s3Store, err := s3.New(s3.WithPassphrase([]byte("store secret")))
if err != nil {
panic(err)
}
err = e2wallet.UseStore(s3Store)
if err != nil {
panic(err)
}
wallet, err := e2wallet.CreateWallet("my wallet")
...
}
List all wallets, and all accounts in each wallet
import (
"fmt"
e2wallet "github.com/Stakedllc/go-eth2-wallet"
)
func main() {
for wallet := range e2wallet.Wallets() {
fmt.Printf("Found wallet %s\n", wallet.Name())
for account := range wallet.Accounts() {
fmt.Printf("Wallet %s has account %s\n", wallet.Name(), account.Name())
}
}
}
Creating an account in an existing wallet
import (
e2wallet "github.com/Stakedllc/go-eth2-wallet"
)
func main() {
wallet, err := e2wallet.OpenWallet("my wallet")
if err != nil {
panic(err)
}
err = wallet.Unlock([]byte("wallet passphrase"))
if err != nil {
panic(err)
}
// Always immediately defer locking the wallet to ensure it does not remain unlocked outside of the function.
defer wallet.Lock()
account, err := wallet.CreateAccount("primary account", []byte("secret passphrase"))
if err != nil {
panic(err)
}
// Wallet should be locked as soon as unlocked operations have finished; it is safe to explicitly call wallet.Lock() as well
// as defer it as per above.
wallet.Lock()
...
}
Signing data and verifying signatures
import (
"errors"
e2wallet "github.com/Stakedllc/go-eth2-wallet"
)
func main() {
wallet, err := e2wallet.OpenWallet("my wallet")
if err != nil {
panic(err)
}
account, err := wallet.AccountByName("primary account")
if err != nil {
panic(err)
}
err = account.Unlock([]byte("my secret passphrase"))
if err != nil {
panic(err)
}
// Always immediately defer locking the wallet to ensure it does not remain unlocked outside of the function.
defer account.Lock()
signature, err := account.Sign([]byte("some data to sign"))
if err != nil {
panic(err)
}
// Wallet should be locked as soon as unlocked operations have finished; it is safe to explicitly call wallet.Lock() as well
// as defer it as per above.
account.Lock()
verified := signature.Verify([]byte("some data to sign"), account.PublicKey())
if !verified {
panic(errors.New("failed to verify signature"))
}
...
}
Maintainers
Jim McDonald: @mcdee. Max Bucci: @mbucci.
Contribute
Contributions welcome. Please check out the issues.
License
Apache-2.0 © 2019 Weald Technology Trading Ltd Apache-2.0 © 2020 Staked Securely LLC
Documentation
¶
Index ¶
- func CreateWallet(name string, opts ...Option) (wtypes.Wallet, error)
- func GetEncryptor() string
- func GetStore() string
- func ImportWallet(encryptedData []byte, passphrase []byte) (wtypes.Wallet, error)
- func OpenWallet(name string, opts ...Option) (wtypes.Wallet, error)
- func SetStore(name string, passphrase []byte) error
- func UseEncryptor(e wtypes.Encryptor) error
- func UseStore(s wtypes.Store) error
- func WalletAndAccountNames(account string) (string, string, error)
- func Wallets(opts ...Option) <-chan wtypes.Wallet
- type Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CreateWallet ¶
CreateWallet creates a wallet. If the wallet already exists an error is returned.
func GetEncryptor ¶
func GetEncryptor() string
GetEncryptor returns the name of the current encryptor.
func ImportWallet ¶
ImportWallet imports a wallet from its encrypted export.
func OpenWallet ¶
OpenWallet opens an existing wallet. If the wallet does not exist an error is returned.
func SetStore ¶
SetStore sets a store to use given its name and optional passphrase. This does not allow access to all advanced features of stores. To access these create the stores yourself and set them with `UseStore()`.
func UseEncryptor ¶
UseEncryptor sets an encryptor to use.
func WalletAndAccountNames ¶
WalletAndAccountNames breaks an account in to wallet and account names.
Types ¶
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option gives options to OpenWallet and CreateWallet.
func WithEncryptor ¶
WithEncryptor sets the encryptor for the wallet.
func WithKeyService ¶
WithKeyService sets the keyService for a multi-party wallet.
func WithPassphrase ¶
WithPassphrase sets the passphrase for the wallet.
func WithPubKey ¶
WithPubKey sets the pub key for a multi-party wallet.
Source Files