github.com/dashpay/godash@v0.0.0-20160726055534-e038a21e0e3d/blockchain/doc.go (about)

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