Documentation

Overview

    Package accounts implements high level Ethereum account management.

    Index

    Constants

    View Source
    const (
    	MimetypeDataWithValidator = "data/validator"
    	MimetypeTypedData         = "data/typed"
    	MimetypeClique            = "application/x-clique-header"
    	MimetypeTextPlain         = "text/plain"
    )

    Variables

    View Source
    var DefaultBaseDerivationPath = DerivationPath{0x80000000 + 44, 0x80000000 + 60, 0x80000000 + 0, 0, 0}

      DefaultBaseDerivationPath is the base path from which custom derivation endpoints are incremented. As such, the first account will be at m/44'/60'/0'/0/0, the second at m/44'/60'/0'/0/1, etc.

      View Source
      var DefaultRootDerivationPath = DerivationPath{0x80000000 + 44, 0x80000000 + 60, 0x80000000 + 0, 0}

        DefaultRootDerivationPath is the root path to which custom derivation endpoints are appended. As such, the first account will be at m/44'/60'/0'/0, the second at m/44'/60'/0'/1, etc.

        View Source
        var ErrInvalidPassphrase = errors.New("invalid password")

          ErrInvalidPassphrase is returned when a decryption operation receives a bad passphrase.

          View Source
          var ErrNotSupported = errors.New("not supported")

            ErrNotSupported is returned when an operation is requested from an account backend that it does not support.

            View Source
            var ErrUnknownAccount = errors.New("unknown account")

              ErrUnknownAccount is returned for any requested operation for which no backend provides the specified account.

              View Source
              var ErrUnknownWallet = errors.New("unknown wallet")

                ErrUnknownWallet is returned for any requested operation for which no backend provides the specified wallet.

                View Source
                var ErrWalletAlreadyOpen = errors.New("wallet already open")

                  ErrWalletAlreadyOpen is returned if a wallet is attempted to be opened the second time.

                  View Source
                  var ErrWalletClosed = errors.New("wallet closed")

                    ErrWalletClosed is returned if a wallet is attempted to be opened the secodn time.

                    View Source
                    var LegacyLedgerBaseDerivationPath = DerivationPath{0x80000000 + 44, 0x80000000 + 60, 0x80000000 + 0, 0}

                      LegacyLedgerBaseDerivationPath is the legacy base path from which custom derivation endpoints are incremented. As such, the first account will be at m/44'/60'/0'/0, the second at m/44'/60'/0'/1, etc.

                      Functions

                      func DefaultIterator

                      func DefaultIterator(base DerivationPath) func() DerivationPath

                        DefaultIterator creates a BIP-32 path iterator, which progresses by increasing the last component: i.e. m/44'/60'/0'/0/0, m/44'/60'/0'/0/1, m/44'/60'/0'/0/2, ... m/44'/60'/0'/0/N.

                        func LedgerLiveIterator

                        func LedgerLiveIterator(base DerivationPath) func() DerivationPath

                          LedgerLiveIterator creates a bip44 path iterator for Ledger Live. Ledger Live increments the third component rather than the fifth component i.e. m/44'/60'/0'/0/0, m/44'/60'/1'/0/0, m/44'/60'/2'/0/0, ... m/44'/60'/N'/0/0.

                          func NewAuthNeededError

                          func NewAuthNeededError(needed string) error

                            NewAuthNeededError creates a new authentication error with the extra details about the needed fields set.

                            func TextAndHash

                            func TextAndHash(data []byte) ([]byte, string)

                              TextAndHash is a helper function that calculates a hash for the given message that can be safely used to calculate a signature from.

                              The hash is calulcated as

                              keccak256("\x19Ethereum Signed Message:\n"${message length}${message}).
                              

                              This gives context to the signed message and prevents signing of transactions.

                              func TextHash

                              func TextHash(data []byte) []byte

                                TextHash is a helper function that calculates a hash for the given message that can be safely used to calculate a signature from.

                                The hash is calulcated as

                                keccak256("\x19Ethereum Signed Message:\n"${message length}${message}).
                                

                                This gives context to the signed message and prevents signing of transactions.

                                Types

                                type Account

                                type Account struct {
                                	Address common.Address `json:"address"` // Ethereum account address derived from the key
                                	URL     URL            `json:"url"`     // Optional resource locator within a backend
                                }

                                  Account represents an Ethereum account located at a specific location defined by the optional URL field.

                                  type AccountsByURL

                                  type AccountsByURL []Account

                                    AccountsByURL implements sort.Interface for []Account based on the URL field.

                                    func (AccountsByURL) Len

                                    func (a AccountsByURL) Len() int

                                    func (AccountsByURL) Less

                                    func (a AccountsByURL) Less(i, j int) bool

                                    func (AccountsByURL) Swap

                                    func (a AccountsByURL) Swap(i, j int)

                                    type AuthNeededError

                                    type AuthNeededError struct {
                                    	Needed string // Extra authentication the user needs to provide
                                    }

                                      AuthNeededError is returned by backends for signing requests where the user is required to provide further authentication before signing can succeed.

                                      This usually means either that a password needs to be supplied, or perhaps a one time PIN code displayed by some hardware device.

                                      func (*AuthNeededError) Error

                                      func (err *AuthNeededError) Error() string

                                        Error implements the standard error interface.

                                        type Backend

                                        type Backend interface {
                                        	// Wallets retrieves the list of wallets the backend is currently aware of.
                                        	//
                                        	// The returned wallets are not opened by default. For software HD wallets this
                                        	// means that no base seeds are decrypted, and for hardware wallets that no actual
                                        	// connection is established.
                                        	//
                                        	// The resulting wallet list will be sorted alphabetically based on its internal
                                        	// URL assigned by the backend. Since wallets (especially hardware) may come and
                                        	// go, the same wallet might appear at a different positions in the list during
                                        	// subsequent retrievals.
                                        	Wallets() []Wallet
                                        
                                        	// Subscribe creates an async subscription to receive notifications when the
                                        	// backend detects the arrival or departure of a wallet.
                                        	Subscribe(sink chan<- WalletEvent) event.Subscription
                                        }

                                          Backend is a "wallet provider" that may contain a batch of accounts they can sign transactions with and upon request, do so.

                                          type Config

                                          type Config struct {
                                          	InsecureUnlockAllowed bool // Whether account unlocking in insecure environment is allowed
                                          }

                                            Config contains the settings of the global account manager.

                                            TODO(rjl493456442, karalabe, holiman): Get rid of this when account management is removed in favor of Clef.

                                            type DerivationPath

                                            type DerivationPath []uint32

                                              DerivationPath represents the computer friendly version of a hierarchical deterministic wallet account derivaion path.

                                              The BIP-32 spec https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki defines derivation paths to be of the form:

                                              m / purpose' / coin_type' / account' / change / address_index
                                              

                                              The BIP-44 spec https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki defines that the `purpose` be 44' (or 0x8000002C) for crypto currencies, and SLIP-44 https://github.com/satoshilabs/slips/blob/master/slip-0044.md assigns the `coin_type` 60' (or 0x8000003C) to Ethereum.

                                              The root path for Ethereum is m/44'/60'/0'/0 according to the specification from https://github.com/ethereum/EIPs/issues/84, albeit it's not set in stone yet whether accounts should increment the last component or the children of that. We will go with the simpler approach of incrementing the last component.

                                              func ParseDerivationPath

                                              func ParseDerivationPath(path string) (DerivationPath, error)

                                                ParseDerivationPath converts a user specified derivation path string to the internal binary representation.

                                                Full derivation paths need to start with the `m/` prefix, relative derivation paths (which will get appended to the default root path) must not have prefixes in front of the first element. Whitespace is ignored.

                                                func (DerivationPath) MarshalJSON

                                                func (path DerivationPath) MarshalJSON() ([]byte, error)

                                                  MarshalJSON turns a derivation path into its json-serialized string

                                                  func (DerivationPath) String

                                                  func (path DerivationPath) String() string

                                                    String implements the stringer interface, converting a binary derivation path to its canonical representation.

                                                    func (*DerivationPath) UnmarshalJSON

                                                    func (path *DerivationPath) UnmarshalJSON(b []byte) error

                                                      UnmarshalJSON a json-serialized string back into a derivation path

                                                      type Manager

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

                                                        Manager is an overarching account manager that can communicate with various backends for signing transactions.

                                                        func NewManager

                                                        func NewManager(config *Config, backends ...Backend) *Manager

                                                          NewManager creates a generic account manager to sign transaction via various supported backends.

                                                          func (*Manager) Accounts

                                                          func (am *Manager) Accounts() []common.Address

                                                            Accounts returns all account addresses of all wallets within the account manager

                                                            func (*Manager) Backends

                                                            func (am *Manager) Backends(kind reflect.Type) []Backend

                                                              Backends retrieves the backend(s) with the given type from the account manager.

                                                              func (*Manager) Close

                                                              func (am *Manager) Close() error

                                                                Close terminates the account manager's internal notification processes.

                                                                func (*Manager) Config

                                                                func (am *Manager) Config() *Config

                                                                  Config returns the configuration of account manager.

                                                                  func (*Manager) Find

                                                                  func (am *Manager) Find(account Account) (Wallet, error)

                                                                    Find attempts to locate the wallet corresponding to a specific account. Since accounts can be dynamically added to and removed from wallets, this method has a linear runtime in the number of wallets.

                                                                    func (*Manager) Subscribe

                                                                    func (am *Manager) Subscribe(sink chan<- WalletEvent) event.Subscription

                                                                      Subscribe creates an async subscription to receive notifications when the manager detects the arrival or departure of a wallet from any of its backends.

                                                                      func (*Manager) Wallet

                                                                      func (am *Manager) Wallet(url string) (Wallet, error)

                                                                        Wallet retrieves the wallet associated with a particular URL.

                                                                        func (*Manager) Wallets

                                                                        func (am *Manager) Wallets() []Wallet

                                                                          Wallets returns all signer accounts registered under this account manager.

                                                                          type URL

                                                                          type URL struct {
                                                                          	Scheme string // Protocol scheme to identify a capable account backend
                                                                          	Path   string // Path for the backend to identify a unique entity
                                                                          }

                                                                            URL represents the canonical identification URL of a wallet or account.

                                                                            It is a simplified version of url.URL, with the important limitations (which are considered features here) that it contains value-copyable components only, as well as that it doesn't do any URL encoding/decoding of special characters.

                                                                            The former is important to allow an account to be copied without leaving live references to the original version, whereas the latter is important to ensure one single canonical form opposed to many allowed ones by the RFC 3986 spec.

                                                                            As such, these URLs should not be used outside of the scope of an Ethereum wallet or account.

                                                                            func (URL) Cmp

                                                                            func (u URL) Cmp(url URL) int

                                                                              Cmp compares x and y and returns:

                                                                              -1 if x <  y
                                                                               0 if x == y
                                                                              +1 if x >  y
                                                                              

                                                                              func (URL) MarshalJSON

                                                                              func (u URL) MarshalJSON() ([]byte, error)

                                                                                MarshalJSON implements the json.Marshaller interface.

                                                                                func (URL) String

                                                                                func (u URL) String() string

                                                                                  String implements the stringer interface.

                                                                                  func (URL) TerminalString

                                                                                  func (u URL) TerminalString() string

                                                                                    TerminalString implements the log.TerminalStringer interface.

                                                                                    func (*URL) UnmarshalJSON

                                                                                    func (u *URL) UnmarshalJSON(input []byte) error

                                                                                      UnmarshalJSON parses url.

                                                                                      type Wallet

                                                                                      type Wallet interface {
                                                                                      	// URL retrieves the canonical path under which this wallet is reachable. It is
                                                                                      	// user by upper layers to define a sorting order over all wallets from multiple
                                                                                      	// backends.
                                                                                      	URL() URL
                                                                                      
                                                                                      	// Status returns a textual status to aid the user in the current state of the
                                                                                      	// wallet. It also returns an error indicating any failure the wallet might have
                                                                                      	// encountered.
                                                                                      	Status() (string, error)
                                                                                      
                                                                                      	// Open initializes access to a wallet instance. It is not meant to unlock or
                                                                                      	// decrypt account keys, rather simply to establish a connection to hardware
                                                                                      	// wallets and/or to access derivation seeds.
                                                                                      	//
                                                                                      	// The passphrase parameter may or may not be used by the implementation of a
                                                                                      	// particular wallet instance. The reason there is no passwordless open method
                                                                                      	// is to strive towards a uniform wallet handling, oblivious to the different
                                                                                      	// backend providers.
                                                                                      	//
                                                                                      	// Please note, if you open a wallet, you must close it to release any allocated
                                                                                      	// resources (especially important when working with hardware wallets).
                                                                                      	Open(passphrase string) error
                                                                                      
                                                                                      	// Close releases any resources held by an open wallet instance.
                                                                                      	Close() error
                                                                                      
                                                                                      	// Accounts retrieves the list of signing accounts the wallet is currently aware
                                                                                      	// of. For hierarchical deterministic wallets, the list will not be exhaustive,
                                                                                      	// rather only contain the accounts explicitly pinned during account derivation.
                                                                                      	Accounts() []Account
                                                                                      
                                                                                      	// Contains returns whether an account is part of this particular wallet or not.
                                                                                      	Contains(account Account) bool
                                                                                      
                                                                                      	// Derive attempts to explicitly derive a hierarchical deterministic account at
                                                                                      	// the specified derivation path. If requested, the derived account will be added
                                                                                      	// to the wallet's tracked account list.
                                                                                      	Derive(path DerivationPath, pin bool) (Account, error)
                                                                                      
                                                                                      	// SelfDerive sets a base account derivation path from which the wallet attempts
                                                                                      	// to discover non zero accounts and automatically add them to list of tracked
                                                                                      	// accounts.
                                                                                      	//
                                                                                      	// Note, self derivation will increment the last component of the specified path
                                                                                      	// opposed to decending into a child path to allow discovering accounts starting
                                                                                      	// from non zero components.
                                                                                      	//
                                                                                      	// Some hardware wallets switched derivation paths through their evolution, so
                                                                                      	// this method supports providing multiple bases to discover old user accounts
                                                                                      	// too. Only the last base will be used to derive the next empty account.
                                                                                      	//
                                                                                      	// You can disable automatic account discovery by calling SelfDerive with a nil
                                                                                      	// chain state reader.
                                                                                      	SelfDerive(bases []DerivationPath, chain ethereum.ChainStateReader)
                                                                                      
                                                                                      	// SignData requests the wallet to sign the hash of the given data
                                                                                      	// It looks up the account specified either solely via its address contained within,
                                                                                      	// or optionally with the aid of any location metadata from the embedded URL field.
                                                                                      	//
                                                                                      	// If the wallet requires additional authentication to sign the request (e.g.
                                                                                      	// a password to decrypt the account, or a PIN code o verify the transaction),
                                                                                      	// an AuthNeededError instance will be returned, containing infos for the user
                                                                                      	// about which fields or actions are needed. The user may retry by providing
                                                                                      	// the needed details via SignDataWithPassphrase, or by other means (e.g. unlock
                                                                                      	// the account in a keystore).
                                                                                      	SignData(account Account, mimeType string, data []byte) ([]byte, error)
                                                                                      
                                                                                      	// SignDataWithPassphrase is identical to SignData, but also takes a password
                                                                                      	// NOTE: there's an chance that an erroneous call might mistake the two strings, and
                                                                                      	// supply password in the mimetype field, or vice versa. Thus, an implementation
                                                                                      	// should never echo the mimetype or return the mimetype in the error-response
                                                                                      	SignDataWithPassphrase(account Account, passphrase, mimeType string, data []byte) ([]byte, error)
                                                                                      
                                                                                      	// SignText requests the wallet to sign the hash of a given piece of data, prefixed
                                                                                      	// by the Ethereum prefix scheme
                                                                                      	// It looks up the account specified either solely via its address contained within,
                                                                                      	// or optionally with the aid of any location metadata from the embedded URL field.
                                                                                      	//
                                                                                      	// If the wallet requires additional authentication to sign the request (e.g.
                                                                                      	// a password to decrypt the account, or a PIN code o verify the transaction),
                                                                                      	// an AuthNeededError instance will be returned, containing infos for the user
                                                                                      	// about which fields or actions are needed. The user may retry by providing
                                                                                      	// the needed details via SignHashWithPassphrase, or by other means (e.g. unlock
                                                                                      	// the account in a keystore).
                                                                                      	//
                                                                                      	// This method should return the signature in 'canonical' format, with v 0 or 1
                                                                                      	SignText(account Account, text []byte) ([]byte, error)
                                                                                      
                                                                                      	// SignTextWithPassphrase is identical to Signtext, but also takes a password
                                                                                      	SignTextWithPassphrase(account Account, passphrase string, hash []byte) ([]byte, error)
                                                                                      
                                                                                      	// SignTx requests the wallet to sign the given transaction.
                                                                                      	//
                                                                                      	// It looks up the account specified either solely via its address contained within,
                                                                                      	// or optionally with the aid of any location metadata from the embedded URL field.
                                                                                      	//
                                                                                      	// If the wallet requires additional authentication to sign the request (e.g.
                                                                                      	// a password to decrypt the account, or a PIN code to verify the transaction),
                                                                                      	// an AuthNeededError instance will be returned, containing infos for the user
                                                                                      	// about which fields or actions are needed. The user may retry by providing
                                                                                      	// the needed details via SignTxWithPassphrase, or by other means (e.g. unlock
                                                                                      	// the account in a keystore).
                                                                                      	SignTx(account Account, tx *types.Transaction, chainID *big.Int) (*types.Transaction, error)
                                                                                      
                                                                                      	// SignTxWithPassphrase is identical to SignTx, but also takes a password
                                                                                      	SignTxWithPassphrase(account Account, passphrase string, tx *types.Transaction, chainID *big.Int) (*types.Transaction, error)
                                                                                      }

                                                                                        Wallet represents a software or hardware wallet that might contain one or more accounts (derived from the same seed).

                                                                                        type WalletEvent

                                                                                        type WalletEvent struct {
                                                                                        	Wallet Wallet          // Wallet instance arrived or departed
                                                                                        	Kind   WalletEventType // Event type that happened in the system
                                                                                        }

                                                                                          WalletEvent is an event fired by an account backend when a wallet arrival or departure is detected.

                                                                                          type WalletEventType

                                                                                          type WalletEventType int

                                                                                            WalletEventType represents the different event types that can be fired by the wallet subscription subsystem.

                                                                                            const (
                                                                                            	// WalletArrived is fired when a new wallet is detected either via USB or via
                                                                                            	// a filesystem event in the keystore.
                                                                                            	WalletArrived WalletEventType = iota
                                                                                            
                                                                                            	// WalletOpened is fired when a wallet is successfully opened with the purpose
                                                                                            	// of starting any background processes such as automatic key derivation.
                                                                                            	WalletOpened
                                                                                            
                                                                                            	// WalletDropped
                                                                                            	WalletDropped
                                                                                            )

                                                                                            type WalletsByURL

                                                                                            type WalletsByURL []Wallet

                                                                                              WalletsByURL implements sort.Interface for []Wallet based on the URL field.

                                                                                              func (WalletsByURL) Len

                                                                                              func (w WalletsByURL) Len() int

                                                                                              func (WalletsByURL) Less

                                                                                              func (w WalletsByURL) Less(i, j int) bool

                                                                                              func (WalletsByURL) Swap

                                                                                              func (w WalletsByURL) Swap(i, j int)

                                                                                              Directories

                                                                                              Path Synopsis
                                                                                              abi
                                                                                              Package abi implements the Ethereum ABI (Application Binary Interface).
                                                                                              Package abi implements the Ethereum ABI (Application Binary Interface).
                                                                                              bind
                                                                                              Package bind generates Ethereum contract Go bindings.
                                                                                              Package bind generates Ethereum contract Go bindings.
                                                                                              Package keystore implements encrypted storage of secp256k1 private keys.
                                                                                              Package keystore implements encrypted storage of secp256k1 private keys.
                                                                                              Package usbwallet implements support for USB hardware wallets.
                                                                                              Package usbwallet implements support for USB hardware wallets.
                                                                                              trezor
                                                                                              Package trezor contains the wire protocol.
                                                                                              Package trezor contains the wire protocol.