# README
blockchain
Package blockchain implements bitcoin block handling and chain selection rules.
The test coverage is currently only around 60%, but will be increasing over
time. See test_coverage.txt for the gocov coverage report. Alternatively, if
you are running a POSIX OS, you can run the cov_report.sh script for a
real-time report. Package blockchain is licensed under the liberal ISC license.
There is an associated blog post about the release of this package here.
This package has intentionally been designed so it can be used as a standalone package for any projects needing to handle processing of blocks into the bitcoin block chain.
Installation and Updating
$ go get -u github.com/aviator-coding/bchd/blockchain
Bitcoin Chain Processing Overview
Before a block is allowed into the block chain, it must go through an intensive series of validation rules. The following list serves as a general outline of those rules to provide some intuition into what is going on under the hood, but is by no means exhaustive:
- Reject duplicate blocks
- Perform a series of sanity checks on the block and its transactions such as verifying proof of work, timestamps, number and character of transactions, transaction amounts, script complexity, and merkle root calculations
- Compare the block against predetermined checkpoints for expected timestamps and difficulty based on elapsed time since the checkpoint
- Save the most recent orphan blocks for a limited time in case their parent blocks become available
- Stop processing if the block is an orphan as the rest of the processing depends on the block's position within the block chain
- Perform a series of more thorough checks that depend on the block's position within the block chain such as verifying block difficulties adhere to difficulty retarget rules, timestamps are after the median of the last several blocks, all transactions are finalized, checkpoint blocks match, and block versions are in line with the previous blocks
- Determine how the block fits into the chain and perform different actions accordingly in order to ensure any side chains which have higher difficulty than the main chain become the new main chain
- When a block is being connected to the main chain (either through reorganization of a side chain to the main chain or just extending the main chain), perform further checks on the block's transactions such as verifying transaction duplicates, script complexity for the combination of connected scripts, coinbase maturity, double spends, and connected transaction values
- Run the transaction scripts to verify the spender is allowed to spend the coins
- Insert the block into the block database
Examples
-
ProcessBlock Example
Demonstrates how to create a new chain instance and use ProcessBlock to attempt to add a block to the chain. This example intentionally attempts to insert a duplicate genesis block to illustrate how an invalid block is handled. -
CompactToBig Example
Demonstrates how to convert the compact "bits" in a block header which represent the target difficulty to a big integer and display it using the typical hex notation. -
BigToCompact Example
Demonstrates how to convert a target difficulty into the compact "bits" in a block header which represent that target difficulty.
License
Package blockchain is licensed under the copyfree ISC License.
# Packages
Package fullblocktests provides a set of block consensus validation tests.
Package indexers implements optional block chain indexes.
# Functions
BigToCompact converts a whole number N to a compact representation using an unsigned 32-bit number.
BuildMerkleTreeStore creates a merkle tree from a slice of transactions, stores it using a linear array, and returns a slice of the backing array.
CalcBlockSubsidy returns the subsidy amount a block at the provided height should have.
CalcWork calculates a work value from difficulty bits.
CheckBlockSanity performs some preliminary checks on a block to ensure it is sane before continuing with block processing.
CheckProofOfWork ensures the block header bits which indicate the target difficulty is in min/max range and that the block hash is less than the target difficulty as claimed.
CheckTransactionInputs performs a series of checks on the inputs to a transaction to ensure they are valid.
CheckTransactionSanity performs some preliminary checks on a transaction to ensure it is sane.
CompactToBig converts a compact representation of a whole number N to an unsigned 32-bit number.
CountP2SHSigOps returns the number of signature operations for all input transactions which are of the pay-to-script-hash type.
CountSigOps returns the number of signature operations for all transaction input and output scripts in the provided transaction.
DeserializeOutpointKey takes in a Utxo database key and deserializes it into an outpoint.
DeserializeUtxoEntry decodes a utxo entry from the passed serialized byte slice into a new UtxoEntry using a format that is suitable for long-term storage.
DisableLog disables all library log output.
ExtractCoinbaseHeight attempts to extract the height of the block from the scriptSig of a coinbase transaction.
GetSigOps returns the unified sig op count for the passed transaction respecting current active soft-forks which modified sig op cost counting.
HashMerkleBranches takes two hashes, treated as the left and right tree nodes, and returns the hash of their concatenation.
HashToBig converts a chainhash.Hash into a big.Int that can be used to perform math comparisons.
IsCoinBase determines whether or not a transaction is a coinbase.
IsCoinBaseTx determines whether or not a transaction is a coinbase.
IsFinalizedTransaction determines whether or not a transaction is finalized.
LockTimeToSequence converts the passed relative locktime to a sequence number in accordance to BIP-68.
MaxBlockSigOps returns the maximum allowable number of signature operations in a block.
New returns a BlockChain instance using the provided configuration details.
NewMedianTime returns a new instance of concurrency-safe implementation of the MedianTimeSource interface.
NewUtxoViewpoint returns a new empty unspent transaction output view.
SequenceLockActive determines if a transaction's sequence locks have been met, meaning that all the inputs of a given transaction have reached a height or time sufficient for their relative lock-time maturity.
ShouldHaveSerializedBlockHeight determines if a block should have a serialized block height embedded within the scriptSig of its coinbase transaction.
UseLogger uses a specified Logger to output package logging info.
ValidateTransactionScripts validates the scripts for the passed transaction using multiple goroutines.
# Constants
BFFastAdd may be set to indicate that several checks can be avoided for the block since it is already known to fit into the chain due to already proving it correct links into the chain up to a known checkpoint.
BFMagneticAnomaly signals that the magnetic anomaly hardfork is active and the block should be validated according the new rule set.
BFNoDupBlockCheck signals if the block should skip existence checks.
BFNone is a convenience value to specifically indicate no flags.
BFNoPoWCheck may be set to indicate the proof of work check which ensures a block hashes to a value less than the required target will not be performed.
CheckpointConfirmations is the number of blocks before the end of the current best block chain that a good checkpoint candidate must be.
DifficultyAdjustmentWindow is the size of the window used by the DAA adjustment algorithm when calculating the current difficulty.
DifficultyDAA (Difficulty Adjustment Algorithm) is the current Bitcoin Cash difficulty algorithm in effect since Novemeber 15th, 2017.
DifficultyEDA (Emergency Difficulty Adjustment) was a short lived changed right after the August 1st, 2017 hardfork and lasted until November 15th, 2017.
DifficultyLegacy was in effect from genesis through August 1st, 2017.
ErrBadCheckpoint indicates a block that is expected to be at a checkpoint height does not match the expected one.
ErrBadCoinbaseHeight indicates the serialized block height in the coinbase transaction for version 2 and higher blocks does not match the expected value.
ErrBadCoinbaseScriptLen indicates the length of the signature script for a coinbase transaction is not within the valid range.
ErrBadCoinbaseValue indicates the amount of a coinbase value does not match the expected value of the subsidy plus the sum of all fees.
ErrBadFees indicates the total fees for a block are invalid due to exceeding the maximum possible value.
ErrBadMerkleRoot indicates the calculated merkle root does not match the expected value.
ErrBadTxInput indicates a transaction input is invalid in some way such as referencing a previous transaction outpoint which is out of range or not referencing one at all.
ErrBadTxOutValue indicates an output value for a transaction is invalid in some way such as being out of range.
ErrBlockTooBig indicates the serialized block size exceeds the maximum allowed size.
ErrBlockTooSmall indicates the serialized block size is less than the minimum allowed size.
ErrBlockVersionTooOld indicates the block version is too old and is no longer accepted since the majority of the network has upgraded to a newer version.
ErrCheckpointTimeTooOld indicates a block has a timestamp before the most recent checkpoint.
ErrDifficultyTooLow indicates the difficulty for the block is lower than the difficulty required by the most recent checkpoint.
ErrDuplicateBlock indicates a block with the same hash already exists.
ErrDuplicateTx indicates a block contains an identical transaction (or at least two transactions which hash to the same value).
ErrDuplicateTxInputs indicates a transaction references the same input more than once.
ErrFirstTxNotCoinbase indicates the first transaction in a block is not a coinbase transaction.
ErrForkTooOld indicates a block is attempting to fork the block chain before the most recent checkpoint.
ErrHighHash indicates the block does not hash to a value which is lower than the required target difficultly.
ErrImmatureSpend indicates a transaction is attempting to spend a coinbase that has not yet reached the required maturity.
ErrInvalidAncestorBlock indicates that an ancestor of this block has already failed validation.
ErrInvalidTime indicates the time in the passed block has a precision that is more than one second.
ErrInvalidTxOrder indicates the order of the transactions in the block does not follow the active transaction ordering consensus rule.
ErrMissingCoinbaseHeight indicates the coinbase transaction for a block does not start with the serialized block block height as required for version 2 and higher blocks.
ErrMissingTxOut indicates a transaction output referenced by an input that does not exist.
ErrMultipleCoinbases indicates a block contains more than one coinbase transaction.
ErrNoTransactions indicates the block does not have a least one transaction.
ErrNoTxInputs indicates a transaction does not have any inputs.
ErrNoTxOutputs indicates a transaction does not have any outputs.
ErrOverwriteTx indicates a block contains a transaction that has the same hash as a previous transaction which has not been fully spent.
ErrPrevBlockNotBest indicates that the block's previous block is not the current chain tip.
ErrPreviousBlockUnknown indicates that the previous block is not known.
ErrScriptMalformed indicates a transaction script is malformed in some way.
ErrScriptValidation indicates the result of executing transaction script failed.
ErrSpendTooHigh indicates a transaction is attempting to spend more value than the sum of all of its inputs.
ErrSpentTxOut indicates a transaction output referenced by an input that has already been spent.
ErrTimeTooNew indicates the time is too far in the future as compared the current time.
ErrTimeTooOld indicates the time is either before the median time of the last several blocks per the chain consensus rules or prior to the most recent checkpoint.
ErrTooManySigOps indicates the total number of signature operations for a transaction or block exceed the maximum allowed limits.
ErrTxTooBig indicates a transaction exceeds the maximum allowed size when serialized.
ErrTxTooManySigOps indicates a transaction exceeds the maximum allowable number of signature operations.
ErrTxTooSmall indicates a transaction is smaller than the minimum allowed size when serialized.
ErrUnexpectedDifficulty indicates specified bits do not align with the expected value either because it doesn't match the calculated valued based on difficulty regarted rules or it is out of the valid range.
ErrUnfinalizedTx indicates a transaction has not been finalized.
FlushIfNeeded is the flush mode that means a flush must be performed only if the cache is exceeding a safety threshold very close to its maximum size.
FlushPeriodic is the flush mode that means a flush can be performed when it would be almost needed.
FlushRequired is the flush mode that means a flush must be performed regardless of the cache state.
LegacyMaxBlockSize is the maximum number of bytes allowed in a block prior to the August 1st, 2018 UAHF hardfork.
MaxBlockSigOpsPerMB is the maximum number of allowed sigops allowed per one (or partial) megabyte of block size after the UAHF hard fork.
MaxCoinbaseScriptLen is the maximum length a coinbase script can be.
MaxTimeOffsetSeconds is the maximum number of seconds a block time is allowed to be ahead of the current time.
MaxTransactionSigOps is the maximum allowable number of sigops per transaction after the UAHF hard fork.
MaxTransactionSize is the maximum allowable size of a transaction after the UAHF hard fork.
MinCoinbaseScriptLen is the minimum length a coinbase script can be.
MinTransactionSize is the minimum transaction size allowed on the network after the magneticanomaly hardfork.
NTBlockAccepted indicates the associated block was accepted into the block chain.
NTBlockConnected indicates the associated block was connected to the main chain.
NTBlockDisconnected indicates the associated block was disconnected from the main chain.
ThresholdActive is the state for a deployment for all blocks after a retarget period in which the deployment was in the ThresholdLockedIn state.
ThresholdDefined is the first state for each deployment and is the state for the genesis block has by definition for all deployments.
ThresholdFailed is the state for a deployment once its expiration time has been reached and it did not reach the ThresholdLockedIn state.
ThresholdLockedIn is the state for a deployment during the retarget period which is after the ThresholdStarted state period and the number of blocks that have voted for the deployment equal or exceed the required number of votes for the deployment.
ThresholdStarted is the state for a deployment once its start time has been reached.
# Structs
BestState houses information about the current best block and other info related to the state of the main chain as it exists from the point of view of the current best block.
BlockChain provides functions for working with the bitcoin block chain.
Config is a descriptor which specifies the blockchain instance configuration.
Notification defines notification that is sent to the caller via the callback function provided during the call to New and consists of a notification type as well as associated data that depends on the type as follows: - NTBlockAccepted: *bchutil.Block - NTBlockConnected: *bchutil.Block - NTBlockDisconnected: *bchutil.Block.
RuleError identifies a rule violation.
SequenceLock represents the converted relative lock-time in seconds, and absolute block-height for a transaction input's relative lock-times.
SpentTxOut contains a spent transaction output and potentially additional contextual information such as whether or not it was contained in a coinbase transaction, the version of the transaction it was contained in, and which block height the containing transaction was included in.
UtxoEntry houses details about an individual transaction output in a utxo view such as whether or not it was contained in a coinbase tx, the height of the block that contains the tx, whether or not it is spent, its public key script, and how much it pays.
UtxoViewpoint represents a view into the set of unspent transaction outputs from a specific point of view in the chain.
# Interfaces
IndexManager provides a generic interface that the is called when blocks are connected and disconnected to and from the tip of the main chain for the purpose of supporting optional indexes.
MedianTimeSource provides a mechanism to add several time samples which are used to determine a median time which is then used as an offset to the local clock.
# Type aliases
AssertError identifies an error that indicates an internal code consistency issue and should be treated as a critical and unrecoverable error.
BehaviorFlags is a bitmask defining tweaks to the normal behavior when performing chain processing and consensus rules checks.
BlockLocator is used to help locate a specific block.
DeploymentError identifies an error that indicates a deployment ID was specified that does not exist.
The DifficultyAlgorithm specifies which algorithm to use and is passed into the calcNextRequiredDifficulty function.
ErrorCode identifies a kind of error.
FlushMode is used to indicate the different urgency types for a flush.
NotificationCallback is used for a caller to provide a callback for notifications about various chain events.
NotificationType represents the type of a notification message.
ThresholdState define the various threshold states used when voting on consensus changes.