bip32

README

go-bip32

An implementation of the BIP32 spec for Hierarchical Deterministic Bitcoin addresses as a simple Go library. The semantics of derived keys are up to the user. BIP43 and BIP44 are good schemes to implement with this library. An additional library for either or both of those on top of this library should be developed.

Example

It's very unlikely, but possible, that a given index does not produce a valid private key. Error checking is skipped in this example for brevity but should be handled in real code. In such a case, a ErrInvalidPrivateKey is returned.

ErrInvalidPrivateKey should be handled by trying the next index for a child key.

Any valid private key will have a valid public key so that Key.PublicKey() method never returns an error.

package main

import (
  "github.com/tyler-smith/go-bip32"
  "fmt"
  "log"
)

// Example address creation for a fictitious company ComputerVoice Inc. where
// each department has their own wallet to manage
func main(){
  // Generate a seed to determine all keys from.
  // This should be persisted, backed up, and secured
  seed, err := bip32.NewSeed()
  if err != nil {
    log.Fatalln("Error generating seed:", err)
  }

  // Create master private key from seed
  computerVoiceMasterKey, _ := bip32.NewMasterKey(seed)

  // Map departments to keys
  // There is a very small chance a given child index is invalid
  // If so your real program should handle this by skipping the index
  departmentKeys := map[string]*bip32.Key{}
  departmentKeys["Sales"], _ = computerVoiceMasterKey.NewChildKey(0)
  departmentKeys["Marketing"], _ = computerVoiceMasterKey.NewChildKey(1)
  departmentKeys["Engineering"], _ = computerVoiceMasterKey.NewChildKey(2)
  departmentKeys["Customer Support"], _ = computerVoiceMasterKey.NewChildKey(3)

  // Create public keys for record keeping, auditors, payroll, etc
  departmentAuditKeys := map[string]*bip32.Key{}
  departmentAuditKeys["Sales"] = departmentKeys["Sales"].PublicKey()
  departmentAuditKeys["Marketing"] = departmentKeys["Marketing"].PublicKey()
  departmentAuditKeys["Engineering"] = departmentKeys["Engineering"].PublicKey()
  departmentAuditKeys["Customer Support"] = departmentKeys["Customer Support"].PublicKey()

  // Print public keys
  for department, pubKey := range departmentAuditKeys {
    fmt.Println(department, pubKey)
  }
}

Thanks

The developers at Factom have contributed a lot to this library and have made many great improvements to it. Please check out their project(s) and give them a thanks if you use this library.

Thanks to bartekn from Stellar for some important bug catches.

Documentation

Index

• Constants
• Variables
• func NewSeed() ([]byte, error)
• type Key
  • func B58Deserialize(data string) (*Key, error)
  • func Deserialize(data []byte) (*Key, error)
  • func NewMasterKey(seed []byte) (*Key, error)
  • func (key *Key) B58Serialize() string
  • func (key *Key) NewChildKey(childIdx uint32) (*Key, error)
  • func (key *Key) PublicKey() *Key
  • func (key *Key) Serialize() ([]byte, error)
  • func (key *Key) String() string

Constants

const (
	// FirstHardenedChild is the index of the firxt "harded" child key as per the
	// bip32 spec
	FirstHardenedChild = uint32(0x80000000)

	// PublicKeyCompressedLength is the byte count of a compressed public key
	PublicKeyCompressedLength = 33
)

Variables

var (
	// PrivateWalletVersion is the version flag for serialized private keys
	PrivateWalletVersion, _ = hex.DecodeString("0488ADE4")

	// PublicWalletVersion is the version flag for serialized private keys
	PublicWalletVersion, _ = hex.DecodeString("0488B21E")

	// ErrSerializedKeyWrongSize is returned when trying to deserialize a key that
	// has an incorrect length
	ErrSerializedKeyWrongSize = errors.New("serialized keys should by exactly 82 bytes")

	// ErrHardnedChildPublicKey is returned when trying to create a harded child
	// of the public key
	ErrHardnedChildPublicKey = errors.New("can't create hardened child for public key")

	// ErrInvalidChecksum is returned when deserializing a key with an incorrect
	// checksum
	ErrInvalidChecksum = errors.New("checksum doesn't match")

	// ErrInvalidPrivateKey is returned when a derived private key is invalid
	ErrInvalidPrivateKey = errors.New("invalid private key")

	// ErrInvalidPublicKey is returned when a derived public key is invalid
	ErrInvalidPublicKey = errors.New("invalid public key")
)

var (

	// BitcoinBase58Encoding is the encoding used for bitcoin addresses
	BitcoinBase58Encoding = basen.NewEncoding("123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz")
)

Functions

func NewSeed

func NewSeed() ([]byte, error)

NewSeed returns a cryptographically secure seed

Types

type Key

type Key struct {
	Key         []byte // 33 bytes
	Version     []byte // 4 bytes
	ChildNumber []byte // 4 bytes
	FingerPrint []byte // 4 bytes
	ChainCode   []byte // 32 bytes
	Depth       byte   // 1 byte
	IsPrivate   bool   // unserialized
}

Key represents a bip32 extended key

func B58Deserialize

func B58Deserialize(data string) (*Key, error)

B58Deserialize deserializes a Key encoded in base58 encoding

func Deserialize

func Deserialize(data []byte) (*Key, error)

Deserialize a byte slice into a Key

func NewMasterKey

func NewMasterKey(seed []byte) (*Key, error)

NewMasterKey creates a new master extended key from a seed

func (*Key) B58Serialize

func (key *Key) B58Serialize() string

B58Serialize encodes the Key in the standard Bitcoin base58 encoding

func (*Key) NewChildKey

func (key *Key) NewChildKey(childIdx uint32) (*Key, error)

NewChildKey derives a child key from a given parent as outlined by bip32

func (*Key) PublicKey

func (key *Key) PublicKey() *Key

PublicKey returns the public version of key or return a copy The 'Neuter' function from the bip32 spec

func (*Key) Serialize

func (key *Key) Serialize() ([]byte, error)

Serialize a Key to a 78-byte byte slice

func (*Key) String

func (key *Key) String() string

String encodes the Key in the standard Bitcoin base58 encoding