github.com/lbryio/lbcd@v0.22.119/blockchain/doc.go (about)

     1  // Copyright (c) 2013-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 blockchain implements bitcoin block handling and chain selection rules.
     7  
     8  The bitcoin block handling and chain selection rules are an integral, and quite
     9  likely the most important, part of bitcoin.  Unfortunately, at the time of
    10  this writing, these rules are also largely undocumented and had to be
    11  ascertained from the bitcoind source code.  At its core, bitcoin is a
    12  distributed consensus of which blocks are valid and which ones will comprise the
    13  main block chain (public ledger) that ultimately determines accepted
    14  transactions, so it is extremely important that fully validating nodes agree on
    15  all rules.
    16  
    17  At a high level, this package provides support for inserting new blocks into
    18  the block chain according to the aforementioned rules.  It includes
    19  functionality such as rejecting duplicate blocks, ensuring blocks and
    20  transactions follow all rules, orphan handling, and best chain selection along
    21  with reorganization.
    22  
    23  Since this package does not deal with other bitcoin specifics such as network
    24  communication or wallets, it provides a notification system which gives the
    25  caller a high level of flexibility in how they want to react to certain events
    26  such as orphan blocks which need their parents requested and newly connected
    27  main chain blocks which might result in wallet updates.
    28  
    29  # Bitcoin Chain Processing Overview
    30  
    31  Before a block is allowed into the block chain, it must go through an intensive
    32  series of validation rules.  The following list serves as a general outline of
    33  those rules to provide some intuition into what is going on under the hood, but
    34  is by no means exhaustive:
    35  
    36    - Reject duplicate blocks
    37    - Perform a series of sanity checks on the block and its transactions such as
    38      verifying proof of work, timestamps, number and character of transactions,
    39      transaction amounts, script complexity, and merkle root calculations
    40    - Compare the block against predetermined checkpoints for expected timestamps
    41      and difficulty based on elapsed time since the checkpoint
    42    - Save the most recent orphan blocks for a limited time in case their parent
    43      blocks become available
    44    - Stop processing if the block is an orphan as the rest of the processing
    45      depends on the block's position within the block chain
    46    - Perform a series of more thorough checks that depend on the block's position
    47      within the block chain such as verifying block difficulties adhere to
    48      difficulty retarget rules, timestamps are after the median of the last
    49      several blocks, all transactions are finalized, checkpoint blocks match, and
    50      block versions are in line with the previous blocks
    51    - Determine how the block fits into the chain and perform different actions
    52      accordingly in order to ensure any side chains which have higher difficulty
    53      than the main chain become the new main chain
    54    - When a block is being connected to the main chain (either through
    55      reorganization of a side chain to the main chain or just extending the
    56      main chain), perform further checks on the block's transactions such as
    57      verifying transaction duplicates, script complexity for the combination of
    58      connected scripts, coinbase maturity, double spends, and connected
    59      transaction values
    60    - Run the transaction scripts to verify the spender is allowed to spend the
    61      coins
    62    - Insert the block into the block database
    63  
    64  # Errors
    65  
    66  Errors returned by this package are either the raw errors provided by underlying
    67  calls or of type blockchain.RuleError.  This allows the caller to differentiate
    68  between unexpected errors, such as database errors, versus errors due to rule
    69  violations through type assertions.  In addition, callers can programmatically
    70  determine the specific rule violation by examining the ErrorCode field of the
    71  type asserted blockchain.RuleError.
    72  
    73  # Bitcoin Improvement Proposals
    74  
    75  This package includes spec changes outlined by the following BIPs:
    76  
    77  	BIP0016 (https://en.bitcoin.it/wiki/BIP_0016)
    78  	BIP0030 (https://en.bitcoin.it/wiki/BIP_0030)
    79  	BIP0034 (https://en.bitcoin.it/wiki/BIP_0034)
    80  */
    81  package blockchain