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/* 6Package blockchain implements bitcoin block handling and chain selection rules. 7 8The bitcoin block handling and chain selection rules are an integral, and quite 9likely the most important, part of bitcoin. Unfortunately, at the time of 10this writing, these rules are also largely undocumented and had to be 11ascertained from the bitcoind source code. At its core, bitcoin is a 12distributed consensus of which blocks are valid and which ones will comprise the 13main block chain (public ledger) that ultimately determines accepted 14transactions, so it is extremely important that fully validating nodes agree on 15all rules. 16 17At a high level, this package provides support for inserting new blocks into 18the block chain according to the aforementioned rules. It includes 19functionality such as rejecting duplicate blocks, ensuring blocks and 20transactions follow all rules, orphan handling, and best chain selection along 21with reorganization. 22 23Since this package does not deal with other bitcoin specifics such as network 24communication or wallets, it provides a notification system which gives the 25caller a high level of flexibility in how they want to react to certain events 26such as orphan blocks which need their parents requested and newly connected 27main chain blocks which might result in wallet updates. 28 29Bitcoin Chain Processing Overview 30 31Before a block is allowed into the block chain, it must go through an intensive 32series of validation rules. The following list serves as a general outline of 33those rules to provide some intuition into what is going on under the hood, but 34is 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 64Errors 65 66Errors returned by this package are either the raw errors provided by underlying 67calls or of type blockchain.RuleError. This allows the caller to differentiate 68between unexpected errors, such as database errors, versus errors due to rule 69violations through type assertions. In addition, callers can programmatically 70determine the specific rule violation by examining the ErrorCode field of the 71type asserted blockchain.RuleError. 72 73Bitcoin Improvement Proposals 74 75This 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*/ 81package blockchain 82