mining

package
v1.6.14 Latest Latest
Warning

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

 Go to latest Published: Mar 23, 2021 License: ISC Imports: 20 Imported by: 0

README

mining

Build Status ISC License Doc

Overview

This package is currently a work in progress.

License

Package mining is licensed under the copyfree ISC License.

Documentation

Overview

Package mining includes all mining and policy types, and will house all mining code in the future.

It is currently a work in progress.

Index

Constants

View Source 
const (
	// MinHighPriority is the minimum priority value that allows a
	// transaction to be considered high priority.
	MinHighPriority = vclutil.AtomsPerCoin * 144.0 / 250
)
View Source 
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
)

Variables

This section is empty.

Functions

func CalcPriority 

func CalcPriority(tx *wire.MsgTx, prioInputs PriorityInputser, nextBlockHeight int64) 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 SortParentsByVotes 

func SortParentsByVotes(txSource TxSource, currentTopBlock chainhash.Hash, blocks []chainhash.Hash, params *chaincfg.Params) []chainhash.Hash

SortParentsByVotes takes a list of block header hashes and sorts them by the number of votes currently available for them in the votes map of mempool. It then returns all blocks that are eligible to be used (have at least a majority number of votes) sorted by number of votes, descending.

This function is safe for concurrent access.

func UseLogger 

func UseLogger(logger slog.Logger)

UseLogger uses a specified Logger to output package logging info.

Types

type BgBlkTmplGenerator 

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

BgBlkTmplGenerator provides facilities for asynchronously generating block templates in response to various relevant events and allowing clients to subscribe for updates when new templates are generated as well as access the most recently-generated template in a concurrency-safe manner.

An example of some of the events that trigger a new block template to be generated are modifications to the current best chain, receiving relevant votes, and periodic timeouts to allow inclusion of new transactions.

The templates are generated based on a given block template generator instance which itself is based on a given mining policy and transaction source. See the NewBlockTemplate method for a detailed description of how the block template is generated.

The background generation makes use of three main goroutines -- a regen event queue to allow asynchronous non-blocking signalling, a regen event handler to process the aforementioned queue and react accordingly, and a subscriber notification controller. In addition, the templates themselves are generated in their own goroutines with a cancellable context.

A high level overview of the semantics are as follows:

  • Ignore all vote handling when prior to stake validation height
  • Generate templates building on the current tip at startup with a fall back to generate a template on its parent if the current tip does not receive enough votes within a timeout
  • Continue monitoring for votes on any blocks that extend said parent to potentially switch to them and generate a template building on them when possible
  • Generate new templates building on new best chain tip blocks once they have received the minimum votes after a timeout to provide the additional votes an opportunity to propagate, except when it is an intermediate block in a chain reorganization
  • In the event the current tip fails to receive the minimum number of required votes, monitor side chain blocks which are siblings of it for votes in order to potentially switch to them and generate a template building on them when possible
  • Generate new templates on blocks disconnected from the best chain tip, except when it is an intermediate block in a chain reorganization
  • Generate new templates periodically when there are new regular transactions to include
  • Bias templates towards building on the first seen block when possible in order to prevent PoW miners from being able to gain an advantage through vote withholding
  • Schedule retries in the rare event template generation fails
  • Allow clients to subscribe for updates every time a new template is successfully generated along with a reason why it was generated
  • Provide direct access to the most-recently generated template
  • Block while generating new templates that will make the current template stale (e.g. new parent or new votes)

func NewBgBlkTmplGenerator 

func NewBgBlkTmplGenerator(tg *BlkTmplGenerator, addrs []vclutil.Address, allowUnsynced bool) *BgBlkTmplGenerator

NewBgBlkTmplGenerator initializes a background block template generator with the provided parameters. The returned instance must be started with the Run method to allowing processing.

func (*BgBlkTmplGenerator) BlockAccepted 

func (g *BgBlkTmplGenerator) BlockAccepted(block *vclutil.Block)

BlockAccepted informs the background block template generator that a block has been accepted to the block chain. It is caller's responsibility to ensure this is only invoked as described.

This function is safe for concurrent access.

func (*BgBlkTmplGenerator) BlockConnected 

func (g *BgBlkTmplGenerator) BlockConnected(block *vclutil.Block)

BlockConnected informs the background block template generator that a block has been connected to the main chain. It is caller's responsibility to ensure this is only invoked as described.

This function is safe for concurrent access.

func (*BgBlkTmplGenerator) BlockDisconnected 

func (g *BgBlkTmplGenerator) BlockDisconnected(block *vclutil.Block)

BlockDisconnected informs the background block template generator that a block has been disconnected from the main chain. It is caller's responsibility to ensure this is only invoked as described.

This function is safe for concurrent access.

func (*BgBlkTmplGenerator) ChainReorgDone 

func (g *BgBlkTmplGenerator) ChainReorgDone()

ChainReorgDone informs the background block template generator that a chain reorganization has completed. It is caller's responsibility to ensure this is only invoked as described.

func (*BgBlkTmplGenerator) ChainReorgStarted 

func (g *BgBlkTmplGenerator) ChainReorgStarted()

ChainReorgStarted informs the background block template generator that a chain reorganization has started. It is caller's responsibility to ensure this is only invoked as described.

func (*BgBlkTmplGenerator) CurrentTemplate 

func (g *BgBlkTmplGenerator) CurrentTemplate() (*BlockTemplate, error)

CurrentTemplate returns the current template associated with the background template generator along with any associated error.

NOTE: The returned template and block that it contains MUST be treated as immutable since they are shared by all callers.

NOTE: The returned template might be nil even if there is no error. It is the responsibility of the caller to properly handle nil templates.

This function is safe for concurrent access.

func (*BgBlkTmplGenerator) ForceRegen 

func (g *BgBlkTmplGenerator) ForceRegen()

ForceRegen asks the background block template generator to generate a new template, independently of most of its internal timers.

Note that there is no guarantee on whether a new template will actually be generated or when. This function does _not_ block until a new template is generated.

This function is safe for concurrent access.

func (*BgBlkTmplGenerator) Run 

func (g *BgBlkTmplGenerator) Run(ctx context.Context)

Run starts the background block template generator and all other goroutines necessary for it to function properly and blocks until the provided context is cancelled.

func (*BgBlkTmplGenerator) Subscribe 

func (g *BgBlkTmplGenerator) Subscribe() *TemplateSubscription

Subscribe subscribes a client for block template updates. The returned template subscription contains functions to retrieve a channel that produces the stream of block templates and to stop the stream when the caller no longer wishes to receive new templates.

The current template associated with the background block template generator, if any, is immediately sent to the returned subscription stream.

func (*BgBlkTmplGenerator) UpdateBlockTime 

func (g *BgBlkTmplGenerator) UpdateBlockTime(header *wire.BlockHeader) error

UpdateBlockTime updates the timestamp in the passed header 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 (*BgBlkTmplGenerator) VoteReceived 

func (g *BgBlkTmplGenerator) VoteReceived(tx *vclutil.Tx)

VoteReceived informs the background block template generator that a new vote has been received. It is the caller's responsibility to ensure this is only invoked with valid votes.

This function is safe for concurrent access.

type BlkTmplGenerator 

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

BlkTmplGenerator generates block templates based on a given mining policy and a transactions source. It also houses additional state required in order to ensure the templates adhere to the consensus rules and are built on top of the best chain tip or its parent if the best chain tip is unable to get enough votes.

See the NewBlockTemplate method for a detailed description of how the block template is generated.

func NewBlkTmplGenerator 

func NewBlkTmplGenerator(policy *Policy, txSource TxSource,
	timeSource blockchain.MedianTimeSource, sigCache *txscript.SigCache,
	subsidyCache *standalone.SubsidyCache, chainParams *chaincfg.Params,
	chain *blockchain.BlockChain, blockManager blockManagerFacade,
	miningTimeOffset int) *BlkTmplGenerator

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

func (*BlkTmplGenerator) NewBlockTemplate 

func (g *BlkTmplGenerator) NewBlockTemplate(payToAddress vclutil.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) / 2
|  Transactions prioritized by fee  |   |
|  until <= policy.TxMinFreeFee     |   |
|                                   |   |
|                                   |   |
|                                   |   |
|-----------------------------------|   |
|  Low-fee/Non high-priority (free) |   |
|  transactions (while block size   |   |
|  <= policy.BlockMinSize)          |   |
 -----------------------------------  --

Which also includes a stake tree that looks like the following: 

 -----------------------------------  --  --
|                                   |   |   |
|             Votes                 |   |   | --- >= (chaincfg.TicketsPerBlock/2) + 1
|                                   |   |   |
|-----------------------------------|   | --
|                                   |   |   |
|            Tickets                |   |   | --- <= chaincfg.MaxFreshStakePerBlock
|                                   |   |   |
|-----------------------------------|   | --
|                                   |   |
|          Revocations              |   |
|                                   |   |
 -----------------------------------  --

This function returns nil, nil if there are not enough voters on any of
the current top blocks to create a new block template.

func (*BlkTmplGenerator) UpdateBlockTime 

func (g *BlkTmplGenerator) UpdateBlockTime(header *wire.BlockHeader) error

UpdateBlockTime updates the timestamp in the passed header 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.

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

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

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

	// 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
}

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 MiningErrorCode 

type MiningErrorCode int

MiningErrorCode identifies a kind of error. 

const (
	// ErrNotEnoughVoters indicates that there were not enough voters to
	// build a block on top of HEAD.
	ErrNotEnoughVoters MiningErrorCode = iota

	// ErrFailedToGetGeneration specifies that the current generation for
	// a block could not be obtained from blockchain.
	ErrFailedToGetGeneration

	// ErrGetStakeDifficulty indicates that the current top block of the
	// blockchain could not be obtained.
	ErrGetTopBlock

	// ErrGettingDifficulty indicates that there was an error getting the
	// PoW difficulty.
	ErrGettingDifficulty

	// ErrTransactionAppend indicates there was a problem adding a msgtx
	// to a msgblock.
	ErrTransactionAppend

	// ErrTicketExhaustion indicates that there will not be enough mature
	// tickets by the end of the next ticket maturity period to progress the
	// chain.
	ErrTicketExhaustion

	// ErrCheckConnectBlock indicates that a newly created block template
	// failed blockchain.CheckConnectBlock.
	ErrCheckConnectBlock

	// ErrFraudProofIndex indicates that there was an error finding the index
	// for a fraud proof.
	ErrFraudProofIndex

	// ErrFetchTxStore indicates a transaction store failed to fetch.
	ErrFetchTxStore

	// ErrCalcCommitmentRoot indicates that creating the header commitments and
	// calculating the associated commitment root for a newly created block
	// template failed.
	ErrCalcCommitmentRoot
)

These constants are used to identify a specific RuleError.

func (MiningErrorCode) String 

func (e MiningErrorCode) String() string

String returns the MiningErrorCode as a human-readable name.

type MiningRuleError 

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

MiningRuleError 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 MiningErrorCode field to ascertain the specific reason for the rule violation.

func (MiningRuleError) Error 

func (e MiningRuleError) Error() string

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

func (MiningRuleError) GetCode 

func (e MiningRuleError) GetCode() MiningErrorCode

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

type Policy 

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

	// BlockMaxSize is the maximum block size in bytes 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 Atoms/1000 bytes that is
	// required for a transaction to be treated as free for mining purposes
	// (block template generation).
	TxMinFreeFee vclutil.Amount

	AggressiveMining bool

	// StandardVerifyFlags defines the function to retrieve the flags to
	// use for verifying scripts for the block after the current best block.
	// It must set the verification flags properly depending on the result
	// of any agendas that affect them.
	//
	// This function must be safe for concurrent access.
	StandardVerifyFlags func() (txscript.ScriptFlags, error)
}

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 PriorityInputser 

type PriorityInputser interface {
	PriorityInput(prevOut *wire.OutPoint) (blockHeight int64, amount int64, ok bool)
}

PriorityInputser defines an interface that provides access to information about an transaction output needed to calculate a priority based on the input age of a transaction. It is used within this package as a generic means to provide the block heights and amounts referenced by all of the inputs to a transaction that are needed to calculate an input age. The boolean return indicates whether or not the information for the provided outpoint was found.

type TemplateNtfn 

type TemplateNtfn struct {
	Template *BlockTemplate
	Reason   TemplateUpdateReason
}

TemplateNtfn represents a notification of a new template along with the reason it was generated. It is sent to subscribers on the channel obtained from the TemplateSubscription instance returned by Subscribe.

type TemplateSubscription 

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

TemplateSubscription defines a subscription to receive block template updates from the background block template generator. The caller must call Stop on the subscription when it is no longer needed to free resources.

NOTE: Notifications are dropped to make up for slow receivers to ensure notifications to other subscribers, as well as senders, are not blocked indefinitely. Since templates are typically only generated infrequently and receives must fall several templates behind before new ones are dropped, this should not affect callers in practice, however, if a caller wishes to guarantee that no templates are being dropped, they will need to ensure the channel is always processed quickly.

func (*TemplateSubscription) C 

func (s *TemplateSubscription) C() <-chan *TemplateNtfn

C returns a channel that produces a stream of block templates as each new template is generated. Successive calls to C return the same channel.

NOTE: Notifications are dropped to make up for slow receivers. See the template subscription type documentation for more details.

func (*TemplateSubscription) Stop 

func (s *TemplateSubscription) Stop()

Stop prevents any future template updates from being delivered and unsubscribes the associated subscription.

NOTE: The channel is not closed to prevent a read from the channel succeeding incorrectly.

type TemplateUpdateReason 

type TemplateUpdateReason int

TemplateUpdateReason represents the type of a reason why a template is being updated. 

const (
	// TURNewParent indicates the associated template has been updated because
	// it builds on a new block as compared to the previous template.
	TURNewParent TemplateUpdateReason = iota

	// TURNewVotes indicates the associated template has been updated because a
	// new vote for the block it builds on has been received.
	TURNewVotes

	// TURNewTxns indicates the associated template has been updated because new
	// non-vote transactions are available and have potentially been included.
	TURNewTxns
)

Constants for the type of template update reasons.

type TxAncestorStats 

type TxAncestorStats struct {
	// Fees is the sum of all fees of unconfirmed ancestors.
	Fees int64

	// SizeBytes is the total size of all unconfirmed ancestors.
	SizeBytes int64

	// TotalSigOps is the total number of signature operations of all ancestors.
	TotalSigOps int

	// NumAncestors is the total number of ancestors for a given transaction.
	NumAncestors int

	// NumDescendants is the total number of descendants that have ancestor
	// statistics tracked for a given transaction.
	NumDescendants int
}

TxAncestorStats is a descriptor that stores aggregated statistics for the unconfirmed ancestors of a transasction.

type TxDesc 

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

	// Type is the type of the transaction associated with the entry.
	Type stake.TxType

	// 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 source
	// pool.
	Height int64

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

	// TotalSigOps is the total signature operations for this transaction.
	TotalSigOps int

	// TxSize is the size of the transaction.
	TxSize int64
}

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

type TxMiningView 

type TxMiningView interface {
	// TxDescs returns a slice of mining descriptors for all minable
	// transactions in the source pool.
	TxDescs() []*TxDesc

	// AncestorStats returns the last known ancestor stats for the provided
	// transaction hash, and a boolean indicating whether ancestors are being
	// tracked for it.
	//
	// Calling Ancestors will update the value returned by this function to
	// reflect the newly calculated statistics for those ancestors.
	AncestorStats(txHash *chainhash.Hash) (*TxAncestorStats, bool)

	// Ancestors returns all transactions in the mining view that the provided
	// transaction hash depends on.
	Ancestors(txHash *chainhash.Hash) []*TxDesc

	// HasParents returns true if the provided transaction hash has any
	// ancestors known to the view.
	HasParents(txHash *chainhash.Hash) bool

	// Parents returns a set of transactions in the graph that the provided
	// transaction hash spends from in the view. The order of elements
	// returned is not guaranteed.
	Parents(txHash *chainhash.Hash) []*TxDesc

	// Children returns a set of transactions in the graph that spend
	// from the provided transaction hash. The order of elements
	// returned is not guaranteed.
	Children(txHash *chainhash.Hash) []*TxDesc

	// Remove causes the provided transaction to be removed from the view, if
	// it exists. The updateDescendantStats parameter indicates whether the
	// descendent transactions of the provided txHash should have their ancestor
	// stats updated within the view to account for the removal of this
	// transaction.
	Remove(txHash *chainhash.Hash, updateDescendantStats bool)

	// Reject removes and flags the provided transaction hash and all of its
	// descendants in the view as rejected.
	Reject(txHash *chainhash.Hash)

	// IsRejected checks to see if a transaction that once existed in the view
	// has been rejected.
	IsRejected(txHash *chainhash.Hash) bool
}

TxMiningView is a snapshot of the tx source.

type TxSource 

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

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

	// HaveAllTransactions returns whether or not all of the passed
	// transaction hashes exist in the source pool.
	HaveAllTransactions(hashes []chainhash.Hash) bool

	// VoteHashesForBlock returns the hashes for all votes on the provided
	// block hash that are currently available in the source pool.
	VoteHashesForBlock(hash *chainhash.Hash) []chainhash.Hash

	// VotesForBlocks returns a slice of vote descriptors for all votes on
	// the provided block hashes that are currently available in the source
	// pool.
	VotesForBlocks(hashes []chainhash.Hash) [][]VoteDesc

	// IsRegTxTreeKnownDisapproved returns whether or not the regular
	// transaction tree of the block represented by the provided hash is
	// known to be disapproved according to the votes currently in the
	// source pool.
	IsRegTxTreeKnownDisapproved(hash *chainhash.Hash) bool

	// MiningView returns a snapshot of the underlying TxSource.
	MiningView() TxMiningView
}

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.

type VoteDesc 

type VoteDesc struct {
	VoteHash       chainhash.Hash
	TicketHash     chainhash.Hash
	ApprovesParent bool
}

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

Source Files

View all Source files

Directories

Path Synopsis
Package cpuminer provides facilities for solving blocks (mining) using the CPU.
 Package cpuminer provides facilities for solving blocks (mining) using the CPU.

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.