blockdag

package
v0.0.7-dev Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 15, 2019 License: ISC Imports: 29 Imported by: 0

README

blockchain

Build Status ISC License GoDoc

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/daglabs/btcd/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 btcsuite 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_NAME is a placeholder for the specific tag:

    git tag -v TAG_NAME

License

Package blockchain is licensed under the copyfree ISC License.

Documentation

Overview

Package blockdag implements bitcoin block handling and chain selection rules.

The bitcoin block handling and chain selection rules are an integral, and quite likely the most important, part of bitcoin. Unfortunately, at the time of this writing, these rules are also largely undocumented and had to be ascertained from the bitcoind source code. At its core, bitcoin is a distributed consensus of which blocks are valid and which ones will comprise the main block chain (public ledger) that ultimately determines accepted transactions, so it is extremely important that fully validating nodes agree on all rules.

At a high level, this package provides support for inserting new blocks into the block chain according to the aforementioned rules. It includes functionality such as rejecting duplicate blocks, ensuring blocks and transactions follow all rules, orphan handling, and best chain selection along with reorganization.

Since this package does not deal with other bitcoin specifics such as network communication or wallets, it provides a notification system which gives the caller a high level of flexibility in how they want to react to certain events such as orphan blocks which need their parents requested and newly connected main chain blocks which might result in wallet updates.

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

Errors

Errors returned by this package are either the raw errors provided by underlying calls or of type blockchain.RuleError. This allows the caller to differentiate between unexpected errors, such as database errors, versus errors due to rule violations through type assertions. In addition, callers can programmatically determine the specific rule violation by examining the ErrorCode field of the type asserted blockchain.RuleError.

Bitcoin Improvement Proposals

This package includes spec changes outlined by the following BIPs: 

BIP0016 (https://en.bitcoin.it/wiki/BIP_0016)
BIP0030 (https://en.bitcoin.it/wiki/BIP_0030)
BIP0034 (https://en.bitcoin.it/wiki/BIP_0034)

Index

Examples

Constants

View Source 
const (
	// MaxSigOpsPerBlock is the maximum number of signature operations
	// allowed for a block.  It is a fraction of the max block payload size.
	MaxSigOpsPerBlock = wire.MaxBlockPayload / 50

	// MaxTimeOffsetSeconds is the maximum number of seconds a block time
	// is allowed to be ahead of the current time.  This is currently 2
	// hours.
	MaxTimeOffsetSeconds = 2 * 60 * 60

	// MinCoinbaseScriptLen is the minimum length a coinbase script can be.
	MinCoinbaseScriptLen = 2

	// MaxCoinbaseScriptLen is the maximum length a coinbase script can be.
	MaxCoinbaseScriptLen = 100

	// MaxOutputsPerBlock is the maximum number of transaction outputs there
	// can be in a block of max size.
	MaxOutputsPerBlock = wire.MaxBlockPayload / wire.MinTxOutPayload
)
View Source 
const CheckpointConfirmations = 2016

CheckpointConfirmations is the number of blocks before the end of the current best block chain that a good checkpoint candidate must be.

View Source 
const (

	// FinalityInterval is the interval that determines the finality window of the DAG.
	FinalityInterval = 100
)

Variables

View Source 
var OpTrueScript = []byte{txscript.OpTrue}

OpTrueScript is script returning TRUE

Functions

func CalcBlockSubsidy 

func CalcBlockSubsidy(height int32, dagParams *dagconfig.Params) uint64

CalcBlockSubsidy returns the subsidy amount a block at the provided height should have. This is mainly used for determining how much the coinbase for newly generated blocks awards as well as validating the coinbase for blocks has the expected value.

The subsidy is halved every SubsidyReductionInterval blocks. Mathematically this is: baseSubsidy / 2^(height/SubsidyReductionInterval)

At the target block generation rate for the main network, this is approximately every 4 years.

func CheckTransactionInputsAndCalulateFee 

func CheckTransactionInputsAndCalulateFee(tx *util.Tx, txHeight int32, utxoSet UTXOSet, dagParams *dagconfig.Params, fastAdd bool) (
	txFeeInSatoshi uint64, err error)

CheckTransactionInputsAndCalulateFee performs a series of checks on the inputs to a transaction to ensure they are valid. An example of some of the checks include verifying all inputs exist, ensuring the block reward seasoning requirements are met, detecting double spends, validating all values and fees are in the legal range and the total output amount doesn't exceed the input amount. As it checks the inputs, it also calculates the total fees for the transaction and returns that value.

NOTE: The transaction MUST have already been sanity checked with the CheckTransactionSanity function prior to calling this function.

func CheckTransactionSanity 

func CheckTransactionSanity(tx *util.Tx, subnetworkID *subnetworkid.SubnetworkID, isFeeTransaction bool) error

CheckTransactionSanity performs some preliminary checks on a transaction to ensure it is sane. These checks are context free.

func CountP2SHSigOps 

func CountP2SHSigOps(tx *util.Tx, isBlockReward bool, utxoSet UTXOSet) (int, error)

CountP2SHSigOps returns the number of signature operations for all input transactions which are of the pay-to-script-hash type. This uses the precise, signature operation counting mechanism from the script engine which requires access to the input transaction scripts.

func CountSigOps 

func CountSigOps(tx *util.Tx) int

CountSigOps returns the number of signature operations for all transaction input and output scripts in the provided transaction. This uses the quicker, but imprecise, signature operation counting mechanism from txscript.

func ExtractCoinbaseHeight 

func ExtractCoinbaseHeight(coinbaseTx *util.Tx) (int32, error)

ExtractCoinbaseHeight attempts to extract the height of the block from the scriptSig of a coinbase transaction.

func GetVirtualFromParentsForTest 

func GetVirtualFromParentsForTest(dag *BlockDAG, parentHashes []*daghash.Hash) (*virtualBlock, error)

GetVirtualFromParentsForTest generates a virtual block with the given parents.

func HashMerkleBranches 

func HashMerkleBranches(left *daghash.Hash, right *daghash.Hash) *daghash.Hash

HashMerkleBranches takes two hashes, treated as the left and right tree nodes, and returns the hash of their concatenation. This is a helper function used to aid in the generation of a merkle tree.

func IsBlockReward 

func IsBlockReward(tx *util.Tx) bool

IsBlockReward determines whether or not a transaction is a block reward (a fee transaction or block reward)

func IsCoinBase 

func IsCoinBase(tx *util.Tx) bool

IsCoinBase determines whether or not a transaction is a coinbase. A coinbase is a special transaction created by miners that has no inputs. This is represented in the block dag by a transaction with a single input that has a previous output transaction index set to the maximum value along with a zero hash.

func IsFeeTransaction 

func IsFeeTransaction(tx *util.Tx) bool

IsFeeTransaction determines whether or not a transaction is a fee transaction. A fee transaction is a special transaction created by miners that distributes fees to the previous blocks' miners. Each input of the fee transaction should set index to maximum value and reference the relevant block id, instead of previous transaction id.

func IsFinalizedTransaction 

func IsFinalizedTransaction(tx *util.Tx, blockHeight int32, blockTime time.Time) bool

IsFinalizedTransaction determines whether or not a transaction is finalized.

func LockTimeToSequence 

func LockTimeToSequence(isSeconds bool, locktime uint64) uint64

LockTimeToSequence converts the passed relative locktime to a sequence number in accordance to BIP-68. See: https://github.com/bitcoin/bips/blob/master/bip-0068.mediawiki

  • (Compatibility)

func SequenceLockActive 

func SequenceLockActive(sequenceLock *SequenceLock, blockHeight int32,
	medianTimePast time.Time) bool

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.

func SetVirtualForTest 

func SetVirtualForTest(dag *BlockDAG, virtual *virtualBlock) *virtualBlock

SetVirtualForTest replaces the dag's virtual block. This function is used for test purposes only

func TxToSubnetworkID 

func TxToSubnetworkID(tx *wire.MsgTx) (*subnetworkid.SubnetworkID, error)

TxToSubnetworkID creates a subnetwork ID from a subnetwork registry transaction

func ValidateTransactionScripts 

func ValidateTransactionScripts(tx *util.Tx, utxoSet UTXOSet, flags txscript.ScriptFlags, sigCache *txscript.SigCache) error

ValidateTransactionScripts validates the scripts for the passed transaction using multiple goroutines.

Types

type AssertError 

type AssertError string

AssertError identifies an error that indicates an internal code consistency issue and should be treated as a critical and unrecoverable error.

func (AssertError) Error 

func (e AssertError) Error() string

Error returns the assertion error as a human-readable string and satisfies the error interface.

type BehaviorFlags 

type BehaviorFlags uint32

BehaviorFlags is a bitmask defining tweaks to the normal behavior when performing chain processing and consensus rules checks. 

const (
	// 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.  This is primarily used for headers-first mode.
	BFFastAdd BehaviorFlags = 1 << iota

	// 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.
	BFNoPoWCheck

	// BFNone is a convenience value to specifically indicate no flags.
	BFNone BehaviorFlags = 0
)

type BlockDAG 

type BlockDAG struct {
	SubnetworkStore *SubnetworkStore
	// contains filtered or unexported fields
}

BlockDAG provides functions for working with the bitcoin block chain. It includes functionality such as rejecting duplicate blocks, ensuring blocks follow all rules, orphan handling, checkpoint handling, and best chain selection with reorganization.

func DAGSetup 

func DAGSetup(dbName string, config Config) (*BlockDAG, func(), error)

DAGSetup is used to create a new db and chain instance with the genesis block already inserted. In addition to the new chain instance, it returns a teardown function the caller should invoke when done testing to clean up.

func New 

func New(config *Config) (*BlockDAG, error)

New returns a BlockDAG instance using the provided configuration details.

func (*BlockDAG) BlockByHash 

func (dag *BlockDAG) BlockByHash(hash *daghash.Hash) (*util.Block, error)

BlockByHash returns the block from the main chain with the given hash with the appropriate chain height set.

This function is safe for concurrent access.

func (*BlockDAG) BlockCount 

func (dag *BlockDAG) BlockCount() uint64

BlockCount returns the number of blocks in the DAG

func (*BlockDAG) BlockExists 

func (dag *BlockDAG) BlockExists(hash *daghash.Hash) (bool, error)

BlockExists determines whether a block with the given hash exists in the DAG.

This function is safe for concurrent access.

func (*BlockDAG) BlockHeightByHash 

func (dag *BlockDAG) BlockHeightByHash(hash *daghash.Hash) (int32, error)

BlockHeightByHash returns the height of the block with the given hash in the DAG.

This function is safe for concurrent access.

func (*BlockDAG) BlockLocatorFromHash 

func (dag *BlockDAG) BlockLocatorFromHash(hash *daghash.Hash) BlockLocator

BlockLocatorFromHash traverses the selected parent chain of the given block hash until it finds a block that exists in the virtual's selected parent chain, and then it returns its block locator. See BlockLocator for details on the algorithm used to create a block locator.

In addition to the general algorithm referenced above, this function will return the block locator for the selected tip if the passed hash is not currently known.

This function is safe for concurrent access.

func (*BlockDAG) CalcNextBlockVersion 

func (dag *BlockDAG) CalcNextBlockVersion() (int32, error)

CalcNextBlockVersion calculates the expected version of the block after the end of the current best chain based on the state of started and locked in rule change deployments.

This function is safe for concurrent access.

func (*BlockDAG) CalcNextRequiredDifficulty 

func (dag *BlockDAG) CalcNextRequiredDifficulty(timestamp time.Time) (uint32, error)

CalcNextRequiredDifficulty calculates the required difficulty for the block after the end of the current best chain based on the difficulty retarget rules.

This function is safe for concurrent access.

func (*BlockDAG) CalcPastMedianTime 

func (dag *BlockDAG) CalcPastMedianTime() time.Time

CalcPastMedianTime returns the past median time of the DAG.

func (*BlockDAG) CalcSequenceLock 

func (dag *BlockDAG) CalcSequenceLock(tx *util.Tx, utxoSet UTXOSet, mempool bool) (*SequenceLock, error)

CalcSequenceLock computes a relative lock-time SequenceLock for the passed transaction using the passed UTXOSet to obtain the past median time for blocks in which the referenced inputs of the transactions were included within. The generated SequenceLock lock can be used in conjunction with a block height, and adjusted median block time to determine if all the inputs referenced within a transaction have reached sufficient maturity allowing the candidate transaction to be included in a block.

This function is safe for concurrent access.

func (*BlockDAG) CheckBlockSanity 

func (dag *BlockDAG) CheckBlockSanity(block *util.Block, powLimit *big.Int,
	timeSource MedianTimeSource) error

CheckBlockSanity performs some preliminary checks on a block to ensure it is sane before continuing with block processing. These checks are context free.

func (*BlockDAG) CheckConnectBlockTemplate 

func (dag *BlockDAG) CheckConnectBlockTemplate(block *util.Block) error

CheckConnectBlockTemplate fully validates that connecting the passed block to the DAG does not violate any consensus rules, aside from the proof of work requirement. The block must connect to the current tip of the main dag.

func (*BlockDAG) CheckConnectBlockTemplateWithLock 

func (dag *BlockDAG) CheckConnectBlockTemplateWithLock(block *util.Block) error

CheckConnectBlockTemplateWithLock fully validates that connecting the passed block to the DAG does not violate any consensus rules, aside from the proof of work requirement.

This function is safe for concurrent access.

func (*BlockDAG) Checkpoints 

func (dag *BlockDAG) Checkpoints() []dagconfig.Checkpoint

Checkpoints returns a slice of checkpoints (regardless of whether they are already known). When there are no checkpoints for the chain, it will return nil.

This function is safe for concurrent access.

func (*BlockDAG) ChildHashesByHash 

func (dag *BlockDAG) ChildHashesByHash(hash *daghash.Hash) ([]*daghash.Hash, error)

ChildHashesByHash returns the child hashes of the block with the given hash in the DAG.

This function is safe for concurrent access.

func (*BlockDAG) CurrentBits 

func (dag *BlockDAG) CurrentBits() uint32

CurrentBits returns the bits of the tip with the lowest bits, which also means it has highest difficulty.

func (*BlockDAG) GetOrphanMissingAncestorHashes 

func (dag *BlockDAG) GetOrphanMissingAncestorHashes(hash *daghash.Hash) ([]*daghash.Hash, error)

GetOrphanMissingAncestorHashes returns all of the missing parents in the orphan's sub-DAG

This function is safe for concurrent access.

func (*BlockDAG) GetTopHeaders 

func (dag *BlockDAG) GetTopHeaders(startHash *daghash.Hash) ([]*wire.BlockHeader, error)

GetTopHeaders returns the top wire.MaxBlockHeadersPerMsg block headers ordered by height.

func (*BlockDAG) GetUTXOEntry 

func (dag *BlockDAG) GetUTXOEntry(outPoint wire.OutPoint) (*UTXOEntry, bool)

GetUTXOEntry returns the requested unspent transaction output. The returned instance must be treated as immutable since it is shared by all callers.

This function is safe for concurrent access. However, the returned entry (if any) is NOT.

func (*BlockDAG) HasCheckpoints 

func (dag *BlockDAG) HasCheckpoints() bool

HasCheckpoints returns whether this BlockDAG has checkpoints defined.

This function is safe for concurrent access.

func (*BlockDAG) HaveBlock 

func (dag *BlockDAG) HaveBlock(hash *daghash.Hash) (bool, error)

HaveBlock returns whether or not the DAG instance has the block represented by the passed hash. This includes checking the various places a block can be in, like part of the DAG or the orphan pool.

This function is safe for concurrent access.

func (*BlockDAG) HaveBlocks 

func (dag *BlockDAG) HaveBlocks(hashes []*daghash.Hash) (bool, error)

HaveBlocks returns whether or not the DAG instances has all blocks represented by the passed hashes. This includes checking the various places a block can be in, like part of the DAG or the orphan pool.

This function is safe for concurrent access.

func (*BlockDAG) HeaderByHash 

func (dag *BlockDAG) HeaderByHash(hash *daghash.Hash) (*wire.BlockHeader, error)

HeaderByHash returns the block header identified by the given hash or an error if it doesn't exist.

func (*BlockDAG) Height 

func (dag *BlockDAG) Height() int32

Height returns the height of the highest tip in the DAG

func (*BlockDAG) HeightToHashRange 

func (dag *BlockDAG) HeightToHashRange(startHeight int32,
	endHash *daghash.Hash, maxResults int) ([]*daghash.Hash, error)

HeightToHashRange returns a range of block hashes for the given start height and end hash, inclusive on both ends. The hashes are for all blocks that are ancestors of endHash with height greater than or equal to startHeight. The end hash must belong to a block that is known to be valid.

This function is safe for concurrent access.

func (*BlockDAG) HighestTipHash 

func (dag *BlockDAG) HighestTipHash() *daghash.Hash

HighestTipHash returns the hash of the highest tip. This function is a placeholder for places that aren't DAG-compatible, and it's needed to be removed in the future

func (*BlockDAG) IntervalBlockHashes 

func (dag *BlockDAG) IntervalBlockHashes(endHash *daghash.Hash, interval int,
) ([]*daghash.Hash, error)

IntervalBlockHashes returns hashes for all blocks that are ancestors of endHash where the block height is a positive multiple of interval.

This function is safe for concurrent access.

func (*BlockDAG) IsCheckpointCandidate 

func (dag *BlockDAG) IsCheckpointCandidate(block *util.Block) (bool, error)

IsCheckpointCandidate returns whether or not the passed block is a good checkpoint candidate.

The factors used to determine a good checkpoint are:

  • The block must be in the main chain
  • The block must be at least 'CheckpointConfirmations' blocks prior to the current end of the main chain
  • The timestamps for the blocks before and after the checkpoint must have timestamps which are also before and after the checkpoint, respectively (due to the median time allowance this is not always the case)
  • The block must not contain any strange transaction such as those with nonstandard scripts

The intent is that candidates are reviewed by a developer to make the final decision and then manually added to the list of checkpoints for a network.

This function is safe for concurrent access.

func (*BlockDAG) IsCurrent 

func (dag *BlockDAG) IsCurrent() bool

IsCurrent returns whether or not the chain believes it is current. Several factors are used to guess, but the key factors that allow the chain to believe it is current are:

  • Latest block height is after the latest checkpoint (if enabled)
  • Latest block has a timestamp newer than 24 hours ago

This function is safe for concurrent access.

func (*BlockDAG) IsDeploymentActive 

func (dag *BlockDAG) IsDeploymentActive(deploymentID uint32) (bool, error)

IsDeploymentActive returns true if the target deploymentID is active, and false otherwise.

This function is safe for concurrent access.

func (*BlockDAG) IsInSelectedPathChain 

func (dag *BlockDAG) IsInSelectedPathChain(blockHash *daghash.Hash) bool

IsInSelectedPathChain returns whether or not a block hash is found in the selected path

func (*BlockDAG) IsKnownOrphan 

func (dag *BlockDAG) IsKnownOrphan(hash *daghash.Hash) bool

IsKnownOrphan returns whether the passed hash is currently a known orphan. Keep in mind that only a limited number of orphans are held onto for a limited amount of time, so this function must not be used as an absolute way to test if a block is an orphan block. A full block (as opposed to just its hash) must be passed to ProcessBlock for that purpose. However, calling ProcessBlock with an orphan that already exists results in an error, so this function provides a mechanism for a caller to intelligently detect *recent* duplicate orphans and react accordingly.

This function is safe for concurrent access.

func (*BlockDAG) LastFinalityPointHash 

func (dag *BlockDAG) LastFinalityPointHash() *daghash.Hash

LastFinalityPointHash returns the hash of the last finality point

func (*BlockDAG) LatestBlockLocator 

func (dag *BlockDAG) LatestBlockLocator() BlockLocator

LatestBlockLocator returns a block locator for the latest known tip of the main (best) chain.

This function is safe for concurrent access.

func (*BlockDAG) LatestCheckpoint 

func (dag *BlockDAG) LatestCheckpoint() *dagconfig.Checkpoint

LatestCheckpoint returns the most recent checkpoint (regardless of whether it is already known). When there are no defined checkpoints for the active chain instance, it will return nil.

This function is safe for concurrent access.

func (*BlockDAG) LocateBlocks 

func (dag *BlockDAG) LocateBlocks(locator BlockLocator, hashStop *daghash.Hash, maxHashes uint32) []*daghash.Hash

LocateBlocks returns the hashes of the blocks after the first known block in the locator until the provided stop hash is reached, or up to the provided max number of block hashes.

In addition, there are two special cases:

  • When no locators are provided, the stop hash is treated as a request for that block, so it will either return the stop hash itself if it is known, or nil if it is unknown
  • When locators are provided, but none of them are known, hashes starting after the genesis block will be returned

This function is safe for concurrent access.

func (*BlockDAG) LocateHeaders 

func (dag *BlockDAG) LocateHeaders(locator BlockLocator, hashStop *daghash.Hash) []*wire.BlockHeader

LocateHeaders returns the headers of the blocks after the first known block in the locator until the provided stop hash is reached, or up to a max of wire.MaxBlockHeadersPerMsg headers.

In addition, there are two special cases:

  • When no locators are provided, the stop hash is treated as a request for that header, so it will either return the header for the stop hash itself if it is known, or nil if it is unknown
  • When locators are provided, but none of them are known, headers starting after the genesis block will be returned

This function is safe for concurrent access.

func (*BlockDAG) NextBlockFeeTransaction 

func (dag *BlockDAG) NextBlockFeeTransaction() (*wire.MsgTx, error)

NextBlockFeeTransaction prepares the fee transaction for the next mined block

This function MUST be called with the DAG read-lock held

func (*BlockDAG) NextBlockFeeTransactionWithLock 

func (dag *BlockDAG) NextBlockFeeTransactionWithLock() (*wire.MsgTx, error)

NextBlockFeeTransactionWithLock prepares the fee transaction for the next mined block

This function CAN'T be called with the DAG lock not held.

func (*BlockDAG) ProcessBlock 

func (dag *BlockDAG) ProcessBlock(block *util.Block, flags BehaviorFlags) (bool, error)

ProcessBlock is the main workhorse for handling insertion of new blocks into the block chain. It includes functionality such as rejecting duplicate blocks, ensuring blocks follow all rules, orphan handling, and insertion into the block DAG.

When no errors occurred during processing, the first return value indicates whether or not the block is an orphan.

This function is safe for concurrent access.

Example

This example demonstrates how to create a new chain instance and use ProcessBlock to attempt to add a block to the chain. As the package overview documentation describes, this includes all of the Bitcoin consensus rules. This example intentionally attempts to insert a duplicate genesis block to illustrate how an invalid block is handled. 

package main

import (
	"fmt"
	"os"
	"path/filepath"

	"github.com/daglabs/btcd/blockdag"
	"github.com/daglabs/btcd/dagconfig"
	"github.com/daglabs/btcd/database"
	"github.com/daglabs/btcd/util"

	_ "github.com/daglabs/btcd/database/ffldb"
)

func main() {
	// Create a new database to store the accepted blocks into.  Typically
	// this would be opening an existing database and would not be deleting
	// and creating a new database like this, but it is done here so this is
	// a complete working example and does not leave temporary files laying
	// around.
	dbPath := filepath.Join(os.TempDir(), "exampleprocessblock")
	_ = os.RemoveAll(dbPath)
	db, err := database.Create("ffldb", dbPath, dagconfig.MainNetParams.Net)
	if err != nil {
		fmt.Printf("Failed to create database: %v\n", err)
		return
	}
	defer os.RemoveAll(dbPath)
	defer db.Close()

	// Create a new BlockDAG instance using the underlying database for
	// the main bitcoin network.  This example does not demonstrate some
	// of the other available configuration options such as specifying a
	// notification callback and signature cache.  Also, the caller would
	// ordinarily keep a reference to the median time source and add time
	// values obtained from other peers on the network so the local time is
	// adjusted to be in agreement with other peers.
	chain, err := blockdag.New(&blockdag.Config{
		DB:         db,
		DAGParams:  &dagconfig.MainNetParams,
		TimeSource: blockdag.NewMedianTime(),
	})
	if err != nil {
		fmt.Printf("Failed to create chain instance: %v\n", err)
		return
	}

	// Process a block.  For this example, we are going to intentionally
	// cause an error by trying to process the genesis block which already
	// exists.
	genesisBlock := util.NewBlock(dagconfig.MainNetParams.GenesisBlock)
	isOrphan, err := chain.ProcessBlock(genesisBlock,
		blockdag.BFNone)
	if err != nil {
		fmt.Printf("Failed to process block: %v\n", err)
		return
	}
	fmt.Printf("Block accepted. Is it an orphan?: %v", isOrphan)

}

Output:

Failed to process block: already have block 6477863f190fac902e556da4671c7537da4fe367022b1f00fa5270e0d073cc08

func (*BlockDAG) RLock 

func (dag *BlockDAG) RLock()

RLock locks the DAG's UTXO set for reading.

func (*BlockDAG) RUnlock 

func (dag *BlockDAG) RUnlock()

RUnlock unlocks the DAG's UTXO set for reading.

func (*BlockDAG) SelectedTipHash 

func (dag *BlockDAG) SelectedTipHash() *daghash.Hash

SelectedTipHash returns the hash of the current selected tip for the DAG. It will return nil if there is no tip.

This function is safe for concurrent access.

func (*BlockDAG) SelectedTipHeader 

func (dag *BlockDAG) SelectedTipHeader() *wire.BlockHeader

SelectedTipHeader returns the header of the current selected tip for the DAG. It will return nil if there is no tip.

This function is safe for concurrent access.

func (*BlockDAG) SubnetworkID 

func (dag *BlockDAG) SubnetworkID() *subnetworkid.SubnetworkID

SubnetworkID returns the node's subnetwork ID

func (*BlockDAG) Subscribe 

func (dag *BlockDAG) Subscribe(callback NotificationCallback)

Subscribe to block chain notifications. Registers a callback to be executed when various events take place. See the documentation on Notification and NotificationType for details on the types and contents of notifications.

func (*BlockDAG) ThresholdState 

func (dag *BlockDAG) ThresholdState(deploymentID uint32) (ThresholdState, error)

ThresholdState returns the current rule change threshold state of the given deployment ID for the block AFTER the end of the current best chain.

This function is safe for concurrent access.

func (*BlockDAG) TipHashes 

func (dag *BlockDAG) TipHashes() []*daghash.Hash

TipHashes returns the hashes of the DAG's tips

func (*BlockDAG) UTXOSet 

func (dag *BlockDAG) UTXOSet() *FullUTXOSet

UTXOSet returns the DAG's UTXO set

type BlockHeap 

type BlockHeap struct {
	// contains filtered or unexported fields
}

BlockHeap represents a mutable heap of Blocks, sorted by their height

func NewDownHeap 

func NewDownHeap() BlockHeap

NewDownHeap initializes and returns a new BlockHeap

func NewUpHeap 

func NewUpHeap() BlockHeap

NewUpHeap initializes and returns a new BlockHeap

func (BlockHeap) Len 

func (bh BlockHeap) Len() int

Len returns the length of this heap

func (BlockHeap) Push 

func (bh BlockHeap) Push(block *blockNode)

Push pushes the block onto the heap

type BlockLocator 

type BlockLocator []*daghash.Hash

BlockLocator is used to help locate a specific block. The algorithm for building the block locator is to add the hashes in reverse order until the genesis block is reached. In order to keep the list of locator hashes to a reasonable number of entries, first the most recent previous 12 block hashes are added, then the step is doubled each loop iteration to exponentially decrease the number of hashes as a function of the distance from the block being located.

For example, assume a block chain with a side chain as depicted below: 

genesis -> 1 -> 2 -> ... -> 15 -> 16  -> 17  -> 18
                              \-> 16a -> 17a

The block locator for block 17a would be the hashes of blocks: [17a 16a 15 14 13 12 11 10 9 8 7 6 4 genesis]

type BlockTxsAcceptanceData 

type BlockTxsAcceptanceData []TxAcceptanceData

BlockTxsAcceptanceData stores all transactions in a block with an indication if they were accepted or not by some other block

type Config 

type Config struct {
	// DB defines the database which houses the blocks and will be used to
	// store all metadata created by this package such as the utxo set.
	//
	// This field is required.
	DB database.DB

	// Interrupt specifies a channel the caller can close to signal that
	// long running operations, such as catching up indexes or performing
	// database migrations, should be interrupted.
	//
	// This field can be nil if the caller does not desire the behavior.
	Interrupt <-chan struct{}

	// DAGParams identifies which DAG parameters the DAG is associated
	// with.
	//
	// This field is required.
	DAGParams *dagconfig.Params

	// Checkpoints hold caller-defined checkpoints that should be added to
	// the default checkpoints in DAGParams.  Checkpoints must be sorted
	// by height.
	//
	// This field can be nil if the caller does not wish to specify any
	// checkpoints.
	Checkpoints []dagconfig.Checkpoint

	// TimeSource defines the median time source to use for things such as
	// block processing and determining whether or not the chain is current.
	//
	// The caller is expected to keep a reference to the time source as well
	// and add time samples from other peers on the network so the local
	// time is adjusted to be in agreement with other peers.
	TimeSource MedianTimeSource

	// SigCache defines a signature cache to use when when validating
	// signatures.  This is typically most useful when individual
	// transactions are already being validated prior to their inclusion in
	// a block such as what is usually done via a transaction memory pool.
	//
	// This field can be nil if the caller is not interested in using a
	// signature cache.
	SigCache *txscript.SigCache

	// IndexManager defines an index manager to use when initializing the
	// chain and connecting and disconnecting blocks.
	//
	// This field can be nil if the caller does not wish to make use of an
	// index manager.
	IndexManager IndexManager

	// SubnetworkID identifies which subnetwork the DAG is associated
	// with.
	//
	// This field is required.
	SubnetworkID *subnetworkid.SubnetworkID
}

Config is a descriptor which specifies the blockchain instance configuration.

type DeploymentError 

type DeploymentError uint32

DeploymentError identifies an error that indicates a deployment ID was specified that does not exist.

func (DeploymentError) Error 

func (e DeploymentError) Error() string

Error returns the assertion error as a human-readable string and satisfies the error interface.

type DiffUTXOSet 

type DiffUTXOSet struct {
	UTXODiff *UTXODiff
	// contains filtered or unexported fields
}

DiffUTXOSet represents a utxoSet with a base fullUTXOSet and a UTXODiff

func NewDiffUTXOSet 

func NewDiffUTXOSet(base *FullUTXOSet, diff *UTXODiff) *DiffUTXOSet

NewDiffUTXOSet Creates a new utxoSet based on a base fullUTXOSet and a UTXODiff

func (*DiffUTXOSet) AddTx 

func (dus *DiffUTXOSet) AddTx(tx *wire.MsgTx, blockHeight int32) bool

AddTx adds a transaction to this utxoSet and returns true iff it's valid in this UTXO's context

func (*DiffUTXOSet) Get 

func (dus *DiffUTXOSet) Get(outPoint wire.OutPoint) (*UTXOEntry, bool)

Get returns the UTXOEntry associated with provided outPoint in this UTXOSet. Returns false in second output if this UTXOEntry was not found

func (*DiffUTXOSet) String 

func (dus *DiffUTXOSet) String() string

func (*DiffUTXOSet) WithDiff 

func (dus *DiffUTXOSet) WithDiff(other *UTXODiff) (UTXOSet, error)

WithDiff return a new utxoSet which is a diffFrom between this and another utxoSet

type ErrorCode 

type ErrorCode int

ErrorCode identifies a kind of error. 

const (
	// ErrDuplicateBlock indicates a block with the same hash already
	// exists.
	ErrDuplicateBlock ErrorCode = iota

	// ErrBlockTooBig indicates the serialized block size exceeds the
	// maximum allowed size.
	ErrBlockTooBig

	// 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.
	ErrBlockVersionTooOld

	// ErrInvalidTime indicates the time in the passed block has a precision
	// that is more than one second.  The chain consensus rules require
	// timestamps to have a maximum precision of one second.
	ErrInvalidTime

	// 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.
	ErrTimeTooOld

	// ErrTimeTooNew indicates the time is too far in the future as compared
	// the current time.
	ErrTimeTooNew

	// ErrNoParents indicates that the block is missing parents
	ErrNoParents

	// ErrWrongParentsOrder indicates that the block's parents are not ordered by hash, as expected
	ErrWrongParentsOrder

	// ErrDifficultyTooLow indicates the difficulty for the block is lower
	// than the difficulty required by the most recent checkpoint.
	ErrDifficultyTooLow

	// 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.
	ErrUnexpectedDifficulty

	// ErrHighHash indicates the block does not hash to a value which is
	// lower than the required target difficultly.
	ErrHighHash

	// ErrBadMerkleRoot indicates the calculated merkle root does not match
	// the expected value.
	ErrBadMerkleRoot

	// ErrBadCheckpoint indicates a block that is expected to be at a
	// checkpoint height does not match the expected one.
	ErrBadCheckpoint

	// ErrForkTooOld indicates a block is attempting to fork the block chain
	// before the most recent checkpoint.
	ErrForkTooOld

	// ErrCheckpointTimeTooOld indicates a block has a timestamp before the
	// most recent checkpoint.
	ErrCheckpointTimeTooOld

	// ErrNoTransactions indicates the block does not have a least one
	// transaction.  A valid block must have at least the coinbase
	// transaction.
	ErrNoTransactions

	// ErrNoTxInputs indicates a transaction does not have any inputs.  A
	// valid transaction must have at least one input.
	ErrNoTxInputs

	// ErrTxTooBig indicates a transaction exceeds the maximum allowed size
	// when serialized.
	ErrTxTooBig

	// ErrBadTxOutValue indicates an output value for a transaction is
	// invalid in some way such as being out of range.
	ErrBadTxOutValue

	// ErrDuplicateTxInputs indicates a transaction references the same
	// input more than once.
	ErrDuplicateTxInputs

	// 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.
	ErrBadTxInput

	// ErrMissingTxOut indicates a transaction output referenced by an input
	// either does not exist or has already been spent.
	ErrMissingTxOut

	// ErrUnfinalizedTx indicates a transaction has not been finalized.
	// A valid block may only contain finalized transactions.
	ErrUnfinalizedTx

	// ErrDuplicateTx indicates a block contains an identical transaction
	// (or at least two transactions which hash to the same value).  A
	// valid block may only contain unique transactions.
	ErrDuplicateTx

	// ErrOverwriteTx indicates a block contains a transaction that has
	// the same hash as a previous transaction which has not been fully
	// spent.
	ErrOverwriteTx

	// ErrImmatureSpend indicates a transaction is attempting to spend a
	// block reward that has not yet reached the required maturity.
	ErrImmatureSpend

	// ErrSpendTooHigh indicates a transaction is attempting to spend more
	// value than the sum of all of its inputs.
	ErrSpendTooHigh

	// ErrBadFees indicates the total fees for a block are invalid due to
	// exceeding the maximum possible value.
	ErrBadFees

	// ErrTooManySigOps indicates the total number of signature operations
	// for a transaction or block exceed the maximum allowed limits.
	ErrTooManySigOps

	// ErrFirstTxNotCoinbase indicates the first transaction in a block
	// is not a coinbase transaction.
	ErrFirstTxNotCoinbase

	// ErrMultipleCoinbases indicates a block contains more than one
	// coinbase transaction.
	ErrMultipleCoinbases

	// ErrBadCoinbaseScriptLen indicates the length of the signature script
	// for a coinbase transaction is not within the valid range.
	ErrBadCoinbaseScriptLen

	// ErrBadCoinbaseValue indicates the amount of a coinbase value does
	// not match the expected value of the subsidy plus the sum of all fees.
	ErrBadCoinbaseValue

	// 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.
	ErrMissingCoinbaseHeight

	// ErrBadCoinbaseHeight indicates the serialized block height in the
	// coinbase transaction for version 2 and higher blocks does not match
	// the expected value.
	ErrBadCoinbaseHeight

	// ErrSecondTxNotFeeTransaction indicates the second transaction in
	// a block is not a fee transaction.
	ErrSecondTxNotFeeTransaction

	// ErrBadFeeTransaction indicates that the block's fee transaction is not build as expected
	ErrBadFeeTransaction

	// ErrMultipleFeeTransactions indicates a block contains more than one
	// fee transaction.
	ErrMultipleFeeTransactions

	// ErrScriptMalformed indicates a transaction script is malformed in
	// some way.  For example, it might be longer than the maximum allowed
	// length or fail to parse.
	ErrScriptMalformed

	// ErrScriptValidation indicates the result of executing transaction
	// script failed.  The error covers any failure when executing scripts
	// such signature verification failures and execution past the end of
	// the stack.
	ErrScriptValidation

	// ErrParentBlockUnknown indicates that the parent block is not known.
	ErrParentBlockUnknown

	// ErrInvalidAncestorBlock indicates that an ancestor of this block has
	// already failed validation.
	ErrInvalidAncestorBlock

	// ErrParentBlockNotCurrentTips indicates that the block's parents are not the
	// current tips. This is not a block validation rule, but is required
	// for block proposals submitted via getblocktemplate RPC.
	ErrParentBlockNotCurrentTips

	// ErrWithDiff indicates that there was an error with UTXOSet.WithDiff
	ErrWithDiff

	// ErrFinality indicates that a block doesn't adhere to the finality rules
	ErrFinality

	// ErrTransactionsNotSorted indicates that transactions in block are not
	// sorted by subnetwork
	ErrTransactionsNotSorted

	// ErrInvalidGas transaction wants to use more GAS than allowed
	// by subnetwork
	ErrInvalidGas

	// ErrInvalidPayload transaction includes a payload in a subnetwork that doesn't allow
	// a Payload
	ErrInvalidPayload

	// ErrInvalidPayloadHash invalid hash of transaction's payload
	ErrInvalidPayloadHash

	// ErrSubnetwork indicates that a block doesn't adhere to the subnetwork
	// registry rules
	ErrSubnetworkRegistry
)

These constants are used to identify a specific RuleError.

func (ErrorCode) String 

func (e ErrorCode) String() string

String returns the ErrorCode as a human-readable name.

type FullUTXOSet 

type FullUTXOSet struct {
	// contains filtered or unexported fields
}

FullUTXOSet represents a full list of transaction outputs and their values

func NewFullUTXOSet 

func NewFullUTXOSet() *FullUTXOSet

NewFullUTXOSet creates a new utxoSet with full list of transaction outputs and their values

func (*FullUTXOSet) AddTx 

func (fus *FullUTXOSet) AddTx(tx *wire.MsgTx, blockHeight int32) bool

AddTx adds a transaction to this utxoSet and returns true iff it's valid in this UTXO's context

func (*FullUTXOSet) Get 

func (fus *FullUTXOSet) Get(outPoint wire.OutPoint) (*UTXOEntry, bool)

Get returns the UTXOEntry associated with the given OutPoint, and a boolean indicating if such entry was found

func (FullUTXOSet) String 

func (uc FullUTXOSet) String() string

func (*FullUTXOSet) WithDiff 

func (fus *FullUTXOSet) WithDiff(other *UTXODiff) (UTXOSet, error)

WithDiff returns a utxoSet which is a diff between this and another utxoSet

type IndexManager 

type IndexManager interface {
	// Init is invoked during chain initialize in order to allow the index
	// manager to initialize itself and any indexes it is managing.  The
	// channel parameter specifies a channel the caller can close to signal
	// that the process should be interrupted.  It can be nil if that
	// behavior is not desired.
	Init(database.DB, *BlockDAG, <-chan struct{}) error

	// ConnectBlock is invoked when a new block has been connected to the
	// DAG.
	ConnectBlock(database.Tx, *util.Block, *BlockDAG, MultiBlockTxsAcceptanceData) error
}

IndexManager provides a generic interface that is called when blocks are connected and disconnected to and from the tip of the main chain for the purpose of supporting optional indexes.

type MedianTimeSource 

type MedianTimeSource interface {
	// AdjustedTime returns the current time adjusted by the median time
	// offset as calculated from the time samples added by AddTimeSample.
	AdjustedTime() time.Time

	// AddTimeSample adds a time sample that is used when determining the
	// median time of the added samples.
	AddTimeSample(id string, timeVal time.Time)

	// Offset returns the number of seconds to adjust the local clock based
	// upon the median of the time samples added by AddTimeData.
	Offset() time.Duration
}

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.

func NewMedianTime 

func NewMedianTime() MedianTimeSource

NewMedianTime returns a new instance of concurrency-safe implementation of the MedianTimeSource interface. The returned implementation contains the rules necessary for proper time handling in the chain consensus rules and expects the time samples to be added from the timestamp field of the version message received from remote peers that successfully connect and negotiate.

type MerkleTree 

type MerkleTree []*daghash.Hash

MerkleTree holds the hashes of a merkle tree

func BuildHashMerkleTreeStore 

func BuildHashMerkleTreeStore(transactions []*util.Tx) MerkleTree

BuildHashMerkleTreeStore creates a merkle tree from a slice of transactions, based on their hash. See `buildMerkleTreeStore` for more info.

func BuildIDMerkleTreeStore 

func BuildIDMerkleTreeStore(transactions []*util.Tx) MerkleTree

BuildIDMerkleTreeStore creates a merkle tree from a slice of transactions, based on their ID. See `buildMerkleTreeStore` for more info.

func (MerkleTree) Root 

func (mt MerkleTree) Root() *daghash.Hash

Root returns the root of the merkle tree

type MultiBlockTxsAcceptanceData 

type MultiBlockTxsAcceptanceData map[daghash.Hash]BlockTxsAcceptanceData

MultiBlockTxsAcceptanceData stores data about which transactions were accepted by a block It's a map from the block's blues block IDs to the transaction acceptance data

type Notification 

type Notification struct {
	Type NotificationType
	Data interface{}
}

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:

  • Added: *util.Block

type NotificationCallback 

type NotificationCallback func(*Notification)

NotificationCallback is used for a caller to provide a callback for notifications about various chain events.

type NotificationType 

type NotificationType int

NotificationType represents the type of a notification message. 

const (
	// NTBlockAdded indicates the associated block was added into
	// the blockDAG.
	NTBlockAdded NotificationType = iota
)

Constants for the type of a notification message.

func (NotificationType) String 

func (n NotificationType) String() string

String returns the NotificationType in human-readable form.

type RuleError 

type RuleError struct {
	ErrorCode   ErrorCode // Describes the kind of error
	Description string    // Human readable description of the issue
}

RuleError identifies a rule violation. It is used to indicate that processing of a block or transaction failed due to one of the many validation rules. The caller can use type assertions to determine if a failure was specifically due to a rule violation and access the ErrorCode field to ascertain the specific reason for the rule violation.

func (RuleError) Error 

func (e RuleError) Error() string

Error satisfies the error interface and prints human-readable errors.

type SequenceLock 

type SequenceLock struct {
	Seconds     int64
	BlockHeight int32
}

SequenceLock represents the converted relative lock-time in seconds, and absolute block-height for a transaction input's relative lock-times. According to SequenceLock, after the referenced input has been confirmed within a block, a transaction spending that input can be included into a block either after 'seconds' (according to past median time), or once the 'BlockHeight' has been reached.

type SubnetworkStore 

type SubnetworkStore struct {
	// contains filtered or unexported fields
}

SubnetworkStore stores the subnetworks data

func (*SubnetworkStore) GasLimit 

func (s *SubnetworkStore) GasLimit(subnetworkID *subnetworkid.SubnetworkID) (uint64, error)

GasLimit returns the gas limit of a registered subnetwork. If the subnetwork does not exist this method returns an error.

type ThresholdState 

type ThresholdState byte

ThresholdState define the various threshold states used when voting on consensus changes. 

const (
	// ThresholdDefined is the first state for each deployment and is the
	// state for the genesis block has by definition for all deployments.
	ThresholdDefined ThresholdState = iota

	// ThresholdStarted is the state for a deployment once its start time
	// has been reached.
	ThresholdStarted

	// 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.
	ThresholdLockedIn

	// ThresholdActive is the state for a deployment for all blocks after a
	// retarget period in which the deployment was in the ThresholdLockedIn
	// state.
	ThresholdActive

	// ThresholdFailed is the state for a deployment once its expiration
	// time has been reached and it did not reach the ThresholdLockedIn
	// state.
	ThresholdFailed
)

These constants are used to identify specific threshold states.

func (ThresholdState) String 

func (t ThresholdState) String() string

String returns the ThresholdState as a human-readable name.

type TxAcceptanceData 

type TxAcceptanceData struct {
	Tx         *util.Tx
	IsAccepted bool
}

TxAcceptanceData stores a transaction together with an indication if it was accepted or not by some block

type UTXODiff 

type UTXODiff struct {
	// contains filtered or unexported fields
}

UTXODiff represents a diff between two UTXO Sets.

func NewUTXODiff 

func NewUTXODiff() *UTXODiff

NewUTXODiff creates a new, empty utxoDiff

func (*UTXODiff) AddEntry 

func (d *UTXODiff) AddEntry(outpoint wire.OutPoint, entry *UTXOEntry)

AddEntry adds an UTXOEntry to the diff

func (*UTXODiff) RemoveTxOuts 

func (d *UTXODiff) RemoveTxOuts(tx *wire.MsgTx)

RemoveTxOuts marks the transaction's outputs to removal

func (UTXODiff) String 

func (d UTXODiff) String() string

func (*UTXODiff) WithDiff 

func (d *UTXODiff) WithDiff(diff *UTXODiff) (*UTXODiff, error)

WithDiff applies provided diff to this diff, creating a new utxoDiff, that would be the result if first d, and than diff were applied to the same base

WithDiff follows a set of rules represented by the following 3 by 3 table: 

|           | this      |           |

---------+-----------+-----------+-----------+----------- 

|           | toAdd     | toRemove  | None

---------+-----------+-----------+-----------+----------- other | toAdd | X | - | toAdd ---------+-----------+-----------+-----------+----------- 

| toRemove  | -         | X         | toRemove

---------+-----------+-----------+-----------+----------- 

| None      | toAdd     | toRemove  | -

Key: - Don't add anything to the result X Return an error toAdd Add the UTXO into the toAdd collection of the result toRemove Add the UTXO into the toRemove collection of the result

Examples:

  1. This diff contains a UTXO in toAdd, and the other diff contains it in toRemove WithDiff results in nothing being added
  2. This diff contains a UTXO in toRemove, and the other diff does not contain it WithDiff results in the UTXO being added to toRemove

type UTXOEntry 

type UTXOEntry struct {
	// contains filtered or unexported fields
}

UTXOEntry houses details about an individual transaction output in a utxo set such as whether or not it was contained in a block reward 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.

func NewUTXOEntry 

func NewUTXOEntry(txOut *wire.TxOut, isBlockReward bool, blockHeight int32) *UTXOEntry

NewUTXOEntry creates a new utxoEntry representing the given txOut

func (*UTXOEntry) Amount 

func (entry *UTXOEntry) Amount() uint64

Amount returns the amount of the output.

func (*UTXOEntry) BlockHeight 

func (entry *UTXOEntry) BlockHeight() int32

BlockHeight returns the height of the block containing the output.

func (*UTXOEntry) IsBlockReward 

func (entry *UTXOEntry) IsBlockReward() bool

IsBlockReward returns whether or not the output was contained in a block reward transaction.

func (*UTXOEntry) PkScript 

func (entry *UTXOEntry) PkScript() []byte

PkScript returns the public key script for the output.

type UTXOSet 

type UTXOSet interface {
	fmt.Stringer

	WithDiff(utxoDiff *UTXODiff) (UTXOSet, error)

	AddTx(tx *wire.MsgTx, blockHeight int32) (ok bool)

	Get(outPoint wire.OutPoint) (*UTXOEntry, bool)
	// contains filtered or unexported methods
}

UTXOSet represents a set of unspent transaction outputs Every DAG has exactly one fullUTXOSet. When a new block arrives, it is validated and applied to the fullUTXOSet in the following manner: 1. Get the block's PastUTXO: 2. Add all the block's transactions to the block's PastUTXO 3. For each of the block's parents, 3.1. Rebuild their utxoDiff 3.2. Set the block as their diffChild 4. Create and initialize a new virtual block 5. Get the new virtual's PastUTXO 6. Rebuild the utxoDiff for all the tips 7. Convert (meld) the new virtual's diffUTXOSet into a fullUTXOSet. This updates the DAG's fullUTXOSet

Source Files

View all Source files

Directories

Path Synopsis
Package fullblocktests provides a set of block consensus validation tests.
 Package fullblocktests provides a set of block consensus validation tests.
Package indexers implements optional block chain indexes.
 Package indexers implements optional block chain indexes.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.