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

     1  blockchain
     2  ==========
     3  
     4  [![Build Status](http://img.shields.io/travis/dashpay/godash.svg)]
     5  (https://travis-ci.org/dashpay/godash) [![ISC License]
     6  (http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org)
     7  [![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)]
     8  (http://godoc.org/github.com/dashpay/godash/blockchain)
     9  
    10  Package blockchain implements bitcoin block handling and chain selection rules.
    11  The test coverage is currently only around 60%, but will be increasing over
    12  time. See `test_coverage.txt` for the gocov coverage report.  Alternatively, if
    13  you are running a POSIX OS, you can run the `cov_report.sh` script for a
    14  real-time report.  Package blockchain is licensed under the liberal ISC license.
    15  
    16  There is an associated blog post about the release of this package
    17  [here](https://blog.conformal.com/btcchain-the-bitcoin-chain-package-from-bctd/).
    18  
    19  This package has intentionally been designed so it can be used as a standalone
    20  package for any projects needing to handle processing of blocks into the bitcoin
    21  block chain.
    22  
    23  ## Installation and Updating
    24  
    25  ```bash
    26  $ go get -u github.com/dashpay/godash/blockchain
    27  ```
    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  ## Examples
    65  
    66  * [ProcessBlock Example]
    67    (http://godoc.org/github.com/dashpay/godash/blockchain#example-BlockChain-ProcessBlock)  
    68    Demonstrates how to create a new chain instance and use ProcessBlock to
    69    attempt to attempt add a block to the chain.  This example intentionally
    70    attempts to insert a duplicate genesis block to illustrate how an invalid
    71    block is handled.
    72  
    73  * [CompactToBig Example]
    74    (http://godoc.org/github.com/dashpay/godash/blockchain#example-CompactToBig)  
    75    Demonstrates how to convert the compact "bits" in a block header which
    76    represent the target difficulty to a big integer and display it using the
    77    typical hex notation.
    78  
    79  * [BigToCompact Example]
    80    (http://godoc.org/github.com/dashpay/godash/blockchain#example-BigToCompact)  
    81    Demonstrates how to convert how to convert a target difficulty into the
    82    compact "bits" in a block header which represent that target difficulty.
    83  
    84  ## GPG Verification Key
    85  
    86  All official release tags are signed by Conformal so users can ensure the code
    87  has not been tampered with and is coming from the btcsuite developers.  To
    88  verify the signature perform the following:
    89  
    90  - Download the public key from the Conformal website at
    91    https://opensource.conformal.com/GIT-GPG-KEY-conformal.txt
    92  
    93  - Import the public key into your GPG keyring:
    94    ```bash
    95    gpg --import GIT-GPG-KEY-conformal.txt
    96    ```
    97  
    98  - Verify the release tag with the following command where `TAG_NAME` is a
    99    placeholder for the specific tag:
   100    ```bash
   101    git tag -v TAG_NAME
   102    ```
   103  
   104  ## License
   105  
   106  
   107  Package blockchain is licensed under the [copyfree](http://copyfree.org) ISC
   108  License.