github.com/mit-dci/lit@v0.0.0-20221102210550-8c3d3b49f2ce/btcutil/hdkeychain/doc.go (about)

     1  // Copyright (c) 2014 The btcsuite developers
     2  // Use of this source code is governed by an ISC
     3  // license that can be found in the LICENSE file.
     4  
     5  /*
     6  Package hdkeychain provides an API for bitcoin hierarchical deterministic
     7  extended keys (BIP0032).
     8  
     9  Overview
    10  
    11  The ability to implement hierarchical deterministic wallets depends on the
    12  ability to create and derive hierarchical deterministic extended keys.
    13  
    14  At a high level, this package provides support for those hierarchical
    15  deterministic extended keys by providing an ExtendedKey type and supporting
    16  functions.  Each extended key can either be a private or public extended key
    17  which itself is capable of deriving a child extended key.
    18  
    19  Determining the Extended Key Type
    20  
    21  Whether an extended key is a private or public extended key can be determined
    22  with the IsPrivate function.
    23  
    24  Transaction Signing Keys and Payment Addresses
    25  
    26  In order to create and sign transactions, or provide others with addresses to
    27  send funds to, the underlying key and address material must be accessible.  This
    28  package provides the ECPubKey, ECPrivKey, and Address functions for this
    29  purpose.
    30  
    31  The Master Node
    32  
    33  As previously mentioned, the extended keys are hierarchical meaning they are
    34  used to form a tree.  The root of that tree is called the master node and this
    35  package provides the NewMaster function to create it from a cryptographically
    36  random seed.  The GenerateSeed function is provided as a convenient way to
    37  create a random seed for use with the NewMaster function.
    38  
    39  Deriving Children
    40  
    41  Once you have created a tree root (or have deserialized an extended key as
    42  discussed later), the child extended keys can be derived by using the Child
    43  function.  The Child function supports deriving both normal (non-hardened) and
    44  hardened child extended keys.  In order to derive a hardened extended key, use
    45  the HardenedKeyStart constant + the hardened key number as the index to the
    46  Child function.  This provides the ability to cascade the keys into a tree and
    47  hence generate the hierarchical deterministic key chains.
    48  
    49  Normal vs Hardened Child Extended Keys
    50  
    51  A private extended key can be used to derive both hardened and non-hardened
    52  (normal) child private and public extended keys.  A public extended key can only
    53  be used to derive non-hardened child public extended keys.  As enumerated in
    54  BIP0032 "knowledge of the extended public key plus any non-hardened private key
    55  descending from it is equivalent to knowing the extended private key (and thus
    56  every private and public key descending from it).  This means that extended
    57  public keys must be treated more carefully than regular public keys. It is also
    58  the reason for the existence of hardened keys, and why they are used for the
    59  account level in the tree. This way, a leak of an account-specific (or below)
    60  private key never risks compromising the master or other accounts."
    61  
    62  Neutering a Private Extended Key
    63  
    64  A private extended key can be converted to a new instance of the corresponding
    65  public extended key with the Neuter function.  The original extended key is not
    66  modified.  A public extended key is still capable of deriving non-hardened child
    67  public extended keys.
    68  
    69  Serializing and Deserializing Extended Keys
    70  
    71  Extended keys are serialized and deserialized with the String and
    72  NewKeyFromString functions.  The serialized key is a Base58-encoded string which
    73  looks like the following:
    74  	public key:   xpub68Gmy5EdvgibQVfPdqkBBCHxA5htiqg55crXYuXoQRKfDBFA1WEjWgP6LHhwBZeNK1VTsfTFUHCdrfp1bgwQ9xv5ski8PX9rL2dZXvgGDnw
    75  	private key:  xprv9uHRZZhk6KAJC1avXpDAp4MDc3sQKNxDiPvvkX8Br5ngLNv1TxvUxt4cV1rGL5hj6KCesnDYUhd7oWgT11eZG7XnxHrnYeSvkzY7d2bhkJ7
    76  
    77  Network
    78  
    79  Extended keys are much like normal Bitcoin addresses in that they have version
    80  bytes which tie them to a specific network.  The SetNet and IsForNet functions
    81  are provided to set and determinine which network an extended key is associated
    82  with.
    83  */
    84  package hdkeychain