github.com/decred/dcrd/blockchain@v1.2.1/README.md (about)

     1  blockchain
     2  ==========
     3  
     4  [![Build Status](https://img.shields.io/travis/decred/dcrd.svg)](https://travis-ci.org/decred/dcrd)
     5  [![ISC License](https://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org)
     6  [![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](https://godoc.org/github.com/decred/dcrd/blockchain)
     7  
     8  Package blockchain implements Decred block handling and chain selection rules.
     9  The test coverage is currently only around 60%, but will be increasing over
    10  time. See `test_coverage.txt` for the gocov coverage report.  Alternatively, if
    11  you are running a POSIX OS, you can run the `cov_report.sh` script for a
    12  real-time report.  Package blockchain is licensed under the liberal ISC license.
    13  
    14  There is an associated blog post about the release of this package
    15  [here](https://blog.conformal.com/btcchain-the-bitcoin-chain-package-from-bctd/).
    16  
    17  This package has intentionally been designed so it can be used as a standalone
    18  package for any projects needing to handle processing of blocks into the decred
    19  block chain.
    20  
    21  ## Installation and Updating
    22  
    23  ```bash
    24  $ go get -u github.com/decred/dcrd/blockchain
    25  ```
    26  
    27  ## Decred Chain Processing Overview
    28  
    29  Before a block is allowed into the block chain, it must go through an intensive
    30  series of validation rules.  The following list serves as a general outline of
    31  those rules to provide some intuition into what is going on under the hood, but
    32  is by no means exhaustive:
    33  
    34   - Reject duplicate blocks
    35   - Perform a series of sanity checks on the block and its transactions such as
    36     verifying proof of work, timestamps, number and character of transactions,
    37     transaction amounts, script complexity, and merkle root calculations
    38   - Compare the block against predetermined checkpoints for expected timestamps
    39     and difficulty based on elapsed time since the checkpoint
    40   - Save the most recent orphan blocks for a limited time in case their parent
    41     blocks become available
    42   - Stop processing if the block is an orphan as the rest of the processing
    43     depends on the block's position within the block chain
    44   - Perform a series of more thorough checks that depend on the block's position
    45     within the block chain such as verifying block difficulties adhere to
    46     difficulty retarget rules, timestamps are after the median of the last
    47     several blocks, all transactions are finalized, checkpoint blocks match, and
    48     block versions are in line with the previous blocks
    49   - Determine how the block fits into the chain and perform different actions
    50     accordingly in order to ensure any side chains which have higher difficulty
    51     than the main chain become the new main chain
    52   - When a block is being connected to the main chain (either through
    53     reorganization of a side chain to the main chain or just extending the
    54     main chain), perform further checks on the block's transactions such as
    55     verifying transaction duplicates, script complexity for the combination of
    56     connected scripts, coinbase maturity, double spends, and connected
    57     transaction values
    58   - Run the transaction scripts to verify the spender is allowed to spend the
    59     coins
    60   - Insert the block into the block database
    61  
    62  ## Examples
    63  
    64  * [ProcessBlock Example](https://godoc.org/github.com/decred/dcrd/blockchain#example-BlockChain-ProcessBlock)
    65    Demonstrates how to create a new chain instance and use ProcessBlock to
    66    attempt to add a block to the chain.  This example intentionally
    67    attempts to insert a duplicate genesis block to illustrate how an invalid
    68    block is handled.
    69  
    70  * [CompactToBig Example](https://godoc.org/github.com/decred/dcrd/blockchain#example-CompactToBig)
    71    Demonstrates how to convert the compact "bits" in a block header which
    72    represent the target difficulty to a big integer and display it using the
    73    typical hex notation.
    74  
    75  * [BigToCompact Example](https://godoc.org/github.com/decred/dcrd/blockchain#example-BigToCompact)
    76    Demonstrates how to convert how to convert a target difficulty into the
    77    compact "bits" in a block header which represent that target difficulty.
    78  
    79  ## License
    80  
    81  
    82  Package blockchain is licensed under the [copyfree](http://copyfree.org) ISC
    83  License.