# 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/p9c/chain
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.
# Packages
Package fullblocktests does a bunch of tests on blocks The vast majority of the rules tested in this package were ported from the the original Java-based 'official' block acceptance tests at https://github.com/TheBlueMatt/test-scripts as well as some additional tests available in the Core python port of the same.
No description provided by the author
Package indexers implements optional block chain indexes.
No description provided by the author
Package netsync implements a concurrency safe block syncing protocol.
Package wallettx provides ..
# Functions
No description provided by the author
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
No description provided by the author
No description provided by the author
No description provided by the author
CheckTransactionInputs performs a series of checks on the inputs to a transaction to ensure they are valid.
No description provided by the author
No description provided by the author
ContainsBlacklisted returns true if one of the given addresses is found in the transaction.
No description provided by the author
No description provided by the author
No description provided by the author
ExtractWitnessCommitment attempts to locate, and return the witness commitment for a block.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
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.
No description provided by the author
Intersects returns whether one slice of byte slices contains a match in another.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
NewBlockNode returns a new block node for the given block header and parent node, calculating the height and workSum from the respective fields on the parent.
No description provided by the author
NewUtxoViewpoint returns a new empty unspent transaction output view.
RightJustify takes a string and right justifies it by a width or crops it.
No description provided by the author
No description provided by the author
No description provided by the author
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.
ErrBlacklisted indicates a transaction contains a blacklisted address.
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
ScryptPowLimit is.
ScryptPowLimitBits is.
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
No description provided by the author
No description provided by the author
No description provided by the author
BlockNode represents a block within the block chain and is primarily used to aid in selecting the best chain to be the main chain.
No description provided by the author
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: *util.Block - NTBlockConnected: *util.Block - NTBlockDisconnected: *util.Block.
RuleError identifies a rule violation.
No description provided by the author
No description provided by the author
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.
No description provided by the author
# Type aliases
No description provided by the author
AssertError identifies an error that indicates an internal code consistency issue and should be treated as a critical and unrecoverable error.
No description provided by the author
No description provided by the author
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.
No description provided by the author
ThresholdState define the various threshold states used when voting on consensus changes.