mining

README

mining

Overview

This package is currently a work in progress.

Installation and Updating

$ go get -u github.com/gcash/bchd/mining

License

Package mining is licensed under the copyfree ISC License.

Documentation

Index

• Constants
• func CalcPriority(tx *wire.MsgTx, utxoView *blockchain.UtxoViewpoint, nextBlockHeight int32) float64
• func DisableLog()
• func MinimumMedianTime(chainState *blockchain.BestState) time.Time
• func UseLogger(logger bchlog.Logger)
• type BlkTmplGenerator
  • func NewBlkTmplGenerator(policy *Policy, params *chaincfg.Params, txSource TxSource, ...) *BlkTmplGenerator
  • func (g *BlkTmplGenerator) BestSnapshot() *blockchain.BestState
  • func (g *BlkTmplGenerator) NewBlockTemplate(payToAddress bchutil.Address) (*BlockTemplate, error)
  • func (g *BlkTmplGenerator) TxSource() TxSource
  • func (g *BlkTmplGenerator) UpdateBlockTime(msgBlock *wire.MsgBlock) error
  • func (g *BlkTmplGenerator) UpdateExtraNonce(msgBlock *wire.MsgBlock, blockHeight int32, extraNonce uint64) error
• type BlockTemplate
• type Policy
• type TxDesc
• type TxSorter
  • func (s TxSorter) Len() int
  • func (s TxSorter) Less(i, j int) bool
  • func (s TxSorter) Swap(i, j int)
• type TxSource

Constants

const (
	// MinHighPriority is the minimum priority value that allows a
	// transaction to be considered high priority.
	MinHighPriority = bchutil.SatoshiPerBitcoin * 144.0 / 250

	// CoinbaseFlags is added to the coinbase script of a generated block
	// and is used to monitor BIP16 support as well as blocks that are
	// generated via bchd.
	CoinbaseFlags = "/bchd/"
)

const (
	// UnminedHeight is the height used for the "block" height field of the
	// contextual transaction information provided in a transaction store
	// when it has not yet been mined into a block.
	UnminedHeight = 0x7fffffff
)

Functions

func CalcPriority

func CalcPriority(tx *wire.MsgTx, utxoView *blockchain.UtxoViewpoint, nextBlockHeight int32) float64

CalcPriority returns a transaction priority given a transaction and the sum of each of its input values multiplied by their age (# of confirmations). Thus, the final formula for the priority is: sum(inputValue * inputAge) / adjustedTxSize

func DisableLog

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by default until UseLogger is called.

func MinimumMedianTime

func MinimumMedianTime(chainState *blockchain.BestState) time.Time

MinimumMedianTime returns the minimum allowed timestamp for a block building on the end of the provided best chain. In particular, it is one second after the median timestamp of the last several blocks per the chain consensus rules.

func UseLogger

func UseLogger(logger bchlog.Logger)

UseLogger uses a specified Logger to output package logging info.

Types

type BlkTmplGenerator

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

BlkTmplGenerator provides a type that can be used to generate block templates based on a given mining policy and source of transactions to choose from. It also houses additional state required in order to ensure the templates are built on top of the current best chain and adhere to the consensus rules.

func NewBlkTmplGenerator

func NewBlkTmplGenerator(policy *Policy, params *chaincfg.Params,
	txSource TxSource, chain *blockchain.BlockChain,
	timeSource blockchain.MedianTimeSource,
	sigCache *txscript.SigCache,
	hashCache *txscript.HashCache) *BlkTmplGenerator

NewBlkTmplGenerator returns a new block template generator for the given policy using transactions from the provided transaction source.

The additional state-related fields are required in order to ensure the templates are built on top of the current best chain and adhere to the consensus rules.

func (*BlkTmplGenerator) BestSnapshot

func (g *BlkTmplGenerator) BestSnapshot() *blockchain.BestState

BestSnapshot returns information about the current best chain block and related state as of the current point in time using the chain instance associated with the block template generator. The returned state must be treated as immutable since it is shared by all callers.

This function is safe for concurrent access.

func (*BlkTmplGenerator) NewBlockTemplate

func (g *BlkTmplGenerator) NewBlockTemplate(payToAddress bchutil.Address) (*BlockTemplate, error)

NewBlockTemplate returns a new block template that is ready to be solved using the transactions from the passed transaction source pool and a coinbase that either pays to the passed address if it is not nil, or a coinbase that is redeemable by anyone if the passed address is nil. The nil address functionality is useful since there are cases such as the getblocktemplate RPC where external mining software is responsible for creating their own coinbase which will replace the one generated for the block template. Thus the need to have configured address can be avoided.

The transactions selected and included are prioritized according to several factors. First, each transaction has a priority calculated based on its value, age of inputs, and size. Transactions which consist of larger amounts, older inputs, and small sizes have the highest priority. Second, a fee per kilobyte is calculated for each transaction. Transactions with a higher fee per kilobyte are preferred. Finally, the block generation related policy settings are all taken into account.

Transactions which only spend outputs from other transactions already in the block chain are immediately added to a priority queue which either prioritizes based on the priority (then fee per kilobyte) or the fee per kilobyte (then priority) depending on whether or not the BlockPrioritySize policy setting allots space for high-priority transactions. Transactions which spend outputs from other transactions in the source pool are added to a dependency map so they can be added to the priority queue once the transactions they depend on have been included.

Once the high-priority area (if configured) has been filled with transactions, or the priority falls below what is considered high-priority, the priority queue is updated to prioritize by fees per kilobyte (then priority).

When the fees per kilobyte drop below the TxMinFreeFee policy setting, the transaction will be skipped unless the BlockMinSize policy setting is nonzero, in which case the block will be filled with the low-fee/free transactions until the block size reaches that minimum size.

Any transactions which would cause the block to exceed the BlockMaxSize policy setting, exceed the maximum allowed signature operations per block, or otherwise cause the block to be invalid are skipped.

Given the above, a block generated by this function is of the following form:

 -----------------------------------  --  --
|      Coinbase Transaction         |   |   |
|-----------------------------------|   |   |
|                                   |   |   | ----- policy.BlockPrioritySize
|   High-priority Transactions      |   |   |
|                                   |   |   |
|-----------------------------------|   | --
|                                   |   |
|                                   |   |
|                                   |   |--- policy.BlockMaxSize
|  Transactions prioritized by fee  |   |
|  until <= policy.TxMinFreeFee     |   |
|                                   |   |
|                                   |   |
|                                   |   |
|-----------------------------------|   |
|  Low-fee/Non high-priority (free) |   |
|  transactions (while block size   |   |
|  <= policy.BlockMinSize)          |   |
 -----------------------------------  --

func (*BlkTmplGenerator) TxSource

func (g *BlkTmplGenerator) TxSource() TxSource

TxSource returns the associated transaction source.

This function is safe for concurrent access.

func (*BlkTmplGenerator) UpdateBlockTime

func (g *BlkTmplGenerator) UpdateBlockTime(msgBlock *wire.MsgBlock) error

UpdateBlockTime updates the timestamp in the header of the passed block to the current time while taking into account the median time of the last several blocks to ensure the new time is after that time per the chain consensus rules. Finally, it will update the target difficulty if needed based on the new time for the test networks since their target difficulty can change based upon time.

func (*BlkTmplGenerator) UpdateExtraNonce

func (g *BlkTmplGenerator) UpdateExtraNonce(msgBlock *wire.MsgBlock, blockHeight int32, extraNonce uint64) error

UpdateExtraNonce updates the extra nonce in the coinbase script of the passed block by regenerating the coinbase script with the passed value and block height. It also recalculates and updates the new merkle root that results from changing the coinbase script.

type BlockTemplate

type BlockTemplate struct {
	// Block is a block that is ready to be solved by miners.  Thus, it is
	// completely valid with the exception of satisfying the proof-of-work
	// requirement.
	Block *wire.MsgBlock

	// Fees contains the amount of fees each transaction in the generated
	// template pays in base units.  Since the first transaction is the
	// coinbase, the first entry (offset 0) will contain the negative of the
	// sum of the fees of all other transactions.
	Fees []int64

	// SigOpCosts contains the number of signature operations each
	// transaction in the generated template performs.
	SigOpCosts []int64

	// Height is the height at which the block template connects to the main
	// chain.
	Height int32

	// ValidPayAddress indicates whether or not the template coinbase pays
	// to an address or is redeemable by anyone.  See the documentation on
	// NewBlockTemplate for details on which this can be useful to generate
	// templates without a coinbase payment address.
	ValidPayAddress bool

	// MaxBlockSize is the block size consensus rule used when creating the block
	MaxBlockSize uint32

	// MaxSigOps is the block size consensus rule used when creating the block
	MaxSigOps uint32
}

BlockTemplate houses a block that has yet to be solved along with additional details about the fees and the number of signature operations for each transaction in the block.

type Policy

type Policy struct {
	// BlockMinSize is the minimum block size to be used when generating
	// a block template.
	BlockMinSize uint32

	// BlockMaxSize is the maximum block size to be used when generating a
	// block template.
	BlockMaxSize uint32

	// BlockPrioritySize is the size in bytes for high-priority / low-fee
	// transactions to be used when generating a block template.
	BlockPrioritySize uint32

	// TxMinFreeFee is the minimum fee in Satoshi/1000 bytes that is
	// required for a transaction to be treated as free for mining purposes
	// (block template generation).
	TxMinFreeFee bchutil.Amount
}

Policy houses the policy (configuration parameters) which is used to control the generation of block templates. See the documentation for NewBlockTemplate for more details on each of these parameters are used.

type TxDesc

type TxDesc struct {
	// Tx is the transaction associated with the entry.
	Tx *bchutil.Tx

	// Added is the time when the entry was added to the source pool.
	Added time.Time

	// Height is the block height when the entry was added to the the source
	// pool.
	Height int32

	// Fee is the total fee the transaction associated with the entry pays.
	Fee int64

	// FeePerKB is the fee the transaction pays in Satoshi per 1000 bytes.
	FeePerKB int64
}

TxDesc is a descriptor about a transaction in a transaction source along with additional metadata.

type TxSorter

type TxSorter []*bchutil.Tx

TxSorter implements sort.Interface to allow a slice of block headers to be sorted by timestamp.

func (TxSorter) Len

func (s TxSorter) Len() int

Len returns the number of txs in the slice. It is part of the sort.Interface implementation.

func (TxSorter) Less

func (s TxSorter) Less(i, j int) bool

Less returns whether the txs with index i should sort before the tx with index j. It is part of the sort.Interface implementation.

func (TxSorter) Swap

func (s TxSorter) Swap(i, j int)

Swap swaps the txs at the passed indices. It is part of the sort.Interface implementation.

type TxSource

type TxSource interface {
	// LastUpdated returns the last time a transaction was added to or
	// removed from the source pool.
	LastUpdated() time.Time

	// MiningDescs returns a slice of mining descriptors for all the
	// transactions in the source pool.
	MiningDescs() []*TxDesc

	// HaveTransaction returns whether or not the passed transaction hash
	// exists in the source pool.
	HaveTransaction(hash *chainhash.Hash) bool
}

TxSource represents a source of transactions to consider for inclusion in new blocks.

The interface contract requires that all of these methods are safe for concurrent access with respect to the source.