# 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/bitweb-project/bted/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.
GPG Verification Key
All official release tags are signed by Conformal so users can ensure the code has not been tampered with and is coming from the bitweb-project developers. To verify the signature perform the following:
-
Download the public key from the Conformal website at https://opensource.conformal.com/GIT-GPG-KEY-conformal.txt
-
Import the public key into your GPG keyring:
gpg --import GIT-GPG-KEY-conformal.txt -
Verify the release tag with the following command where
TAG_NAMEis a placeholder for the specific tag:git tag -v TAG_NAME
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.
No description provided by the author
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.
DisableLog disables all library log output.
ExtractCoinbaseHeight attempts to extract the height of the block from the scriptSig of a coinbase transaction.
ExtractWitnessCommitment attempts to locate, and return the witness commitment for a block.
GetBlockWeight computes the value of the weight metric for a given block.
GetSigOpCost returns the unified sig op cost for the passed transaction respecting current active soft-forks which modified sig op cost counting.
GetTransactionWeight computes the value of the weight metric for a given transaction.
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.
New returns a BlockChain instance using the provided configuration details.
NewMedianTime returns a new instance of concurrency-safe implementation of the MedianTimeSource interface.
NewUtxoEntry returns a new UtxoEntry built from the arguments.
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.
ValidateWitnessCommitment validates the witness commitment (if any) found within the coinbase transaction of the passed block.
# 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.
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.
CoinbaseWitnessDataLen is the required length of the only element within the coinbase's witness data if the coinbase transaction contains a witness commitment.
CoinbaseWitnessPkScriptLength is the length of the public key script containing an OP_RETURN, the WitnessMagicBytes, and the witness commitment itself.
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.
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.
ErrBlockWeightTooHigh indicates that the block's computed weight metric exceeds the maximum allowed value.
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.
ErrInvalidWitnessCommitment indicates that a block's witness commitment is not well formed.
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 either does not exist or has already been spent.
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.
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.
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.
ErrUnexpectedWitness indicates that a block includes transactions with witness data, but doesn't also have a witness commitment within the coinbase transaction.
ErrUnfinalizedTx indicates a transaction has not been finalized.
ErrWitnessCommitmentMismatch indicates that the witness commitment included in the block's coinbase transaction doesn't match the manually computed witness commitment.
MaxBlockBaseSize is the maximum number of bytes within a block which can be allocated to non-witness data.
MaxBlockSigOpsCost is the maximum number of signature operations allowed for a block.
MaxBlockWeight defines the maximum block weight, where "block weight" is interpreted as defined in BIP0141.
MaxCoinbaseScriptLen is the maximum length a coinbase script can be.
MaxOutputsPerBlock is the maximum number of transaction outputs there can be in a block of max weight size.
MaxTimeOffsetSeconds is the maximum number of seconds a block time is allowed to be ahead of the current time.
MinCoinbaseScriptLen is the minimum length a coinbase script can be.
MinTxOutputWeight is the minimum possible weight for a transaction output.
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.
WitnessScaleFactor determines the level of "discount" witness data receives compared to "base" data.
# Variables
WitnessMagicBytes is the prefix marker within the public key script of a coinbase output to indicate that this output holds the witness commitment for a block.
# 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: *bteutil.Block - NTBlockConnected: *bteutil.Block - NTBlockDisconnected: *bteutil.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.
ErrorCode identifies a kind of error.
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.