mempool

package
v0.0.0-...-d4978fa Latest Latest
Warning

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

 Go to latest Published: Dec 1, 2019 License: Unlicense, ISC Imports: 25 Imported by: 0

README

mempool

ISC License GoDoc

Package mempool provides a policy-enforced pool of unmined bitcoin transactions.

A key responsbility of the bitcoin network is mining user-generated transactions into blocks. In order to facilitate this, the mining process relies on having a readily-available source of transactions to include in a block that is being solved.

At a high level, this package satisfies that requirement by providing an in-memory pool of fully validated transactions that can also optionally be further filtered based upon a configurable policy.

One of the policy configuration options controls whether or not "standard" transactions are accepted. In essence, a "standard" transaction is one that satisfies a fairly strict set of requirements that are largely intended to help provide fair use of the system to all users. It is important to note that what is considered a "standard" transaction changes over time. For some insight, at the time of this writing, an example of some of the criteria that are required for a transaction to be considered standard are that it is of the most-recently supported version, finalized, does not exceed a specific size, and only consists of specific script forms.

Since this package does not deal with other bitcoin specifics such as network communication and transaction relay, it returns a list of transactions that were accepted which gives the caller a high level of flexibility in how they want to proceed. Typically, this will involve things such as relaying the transactions to other peers on the network and notifying the mining process that new transactions are available.

This package has intentionally been designed so it can be used as a standalone package for any projects needing the ability create an in-memory pool of bitcoin transactions that are not only valid by consensus rules, but also adhere to a configurable policy.

Feature Overview

The following is a quick overview of the major features. It is not intended to be an exhaustive list.

  • Maintain a pool of fully validated transactions

    • Reject non-fully-spent duplicate transactions

    • Reject coinbase transactions

    • Reject double spends (both from the chain and other transactions in pool)

    • Reject invalid transactions according to the network consensus rules

    • Full script execution and validation with signature cache support

    • Individual transaction query support

  • Orphan transaction support (transactions that spend from unknown outputs)

    • Configurable limits (see transaction acceptance policy)

    • Automatic addition of orphan transactions that are no longer orphans as new transactions are added to the pool

    • Individual orphan transaction query support

  • Configurable transaction acceptance policy

    • Option to accept or reject standard transactions

    • Option to accept or reject transactions based on priority calculations

    • Rate limiting of low-fee and free transactions

    • Non-zero fee threshold

    • Max signature operations per transaction

    • Max orphan transaction size

    • Max number of orphan transactions allowed

  • Additional metadata tracking for each transaction

    • Timestamp when the transaction was added to the pool

    • Most recent block height when the transaction was added to the pool

    • The fee the transaction pays

    • The starting priority for the transaction

  • Manual control of transaction removal

    • Recursive removal of all dependent transactions

Installation and Updating

$ go get -u github.com/p9c/pod/mempool

License

Package mempool is licensed under the copyfree ISC License.

Documentation

Overview

Package mempool provides a policy-enforced pool of unmined bitcoin transactions.

A key responsbility of the bitcoin network is mining user-generated transactions into blocks. In order to facilitate this, the mining process relies on having a readily-available source of transactions to include in a block that is being solved.

At a high level, this package satisfies that requirement by providing an in-memory pool of fully validated transactions that can also optionally be further filtered based upon a configurable policy. One of the policy configuration options controls whether or not "standard" transactions are accepted. In essence, a "standard" transaction is one that satisfies a fairly strict set of requirements that are largely intended to help provide fair use of the system to all users.

It is important to note that what is considered a "standard" transaction changes over time. For some insight, at the time of this writing, an example of SOME of the criteria that are required for a transaction to be considered standard are that it is of the most-recently supported version, finalized, does not exceed a specific size, and only consists of specific script forms.

Since this package does not deal with other bitcoin specifics such as network communication and transaction relay, it returns a list of transactions that were accepted which gives the caller a high level of flexibility in how they want to proceed. Typically, this will involve things such as relaying the transactions to other peers on the network and notifying the mining process that new transactions are available.

Feature Overview

The following is a quick overview of the major features. It is not intended to be an exhaustive list.

  • Maintain a pool of fully validated transactions
  • Reject non-fully-spent duplicate transactions
  • Reject coinbase transactions
  • Reject double spends (both from the chain and other transactions in pool)
  • Reject invalid transactions according to the network consensus rules
  • Full script execution and validation with signature cache support
  • Individual transaction query support
  • Orphan transaction support (transactions that spend from unknown outputs)
  • Configurable limits (see transaction acceptance policy)
  • Automatic addition of orphan transactions that are no longer orphans as new transactions are added to the pool
  • Individual orphan transaction query support
  • Configurable transaction acceptance policy
  • Option to accept or reject standard transactions
  • Option to accept or reject transactions based on priority calculations
  • Rate limiting of low-fee and free transactions
  • Non-zero fee threshold
  • Max signature operations per transaction
  • Max orphan transaction size
  • Max number of orphan transactions allowed
  • Additional metadata tracking for each transaction
  • Timestamp when the transaction was added to the pool
  • Most recent block height when the transaction was added to the pool
  • The fee the transaction pays
  • The starting priority for the transaction
  • Manual control of transaction removal
  • Recursive removal of all dependent transactions

Errors

Errors returned by this package are either the raw errors provided by underlying calls or of type mempool.RuleError. Since there are two classes of rules (mempool acceptance rules and blockchain (consensus) acceptance rules), the mempool.RuleError type contains a single Err field which will, in turn, either be a mempool.TxRuleError or a blockchain.RuleError.

The first indicates a violation of mempool acceptance rules while the latter indicates a violation of consensus acceptance rules. This allows the caller to easily 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 type asserting the Err field to one of the aforementioned types and examining their underlying ErrorCode field.

Index

Constants

View Source 
const (

	// DefaultEstimateFeeMaxRollback is the default number of rollbacks
	// allowed by the fee estimator for orphaned blocks.
	DefaultEstimateFeeMaxRollback = 2
	// DefaultEstimateFeeMinRegisteredBlocks is the default minimum number of
	// blocks which must be observed by the fee estimator before will provide
	// fee estimations.
	DefaultEstimateFeeMinRegisteredBlocks = 3
)

TODO incorporate Alex Morcos' modifications to Gavin's initial model https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2014-October/006824.html

View Source 
const (
	// DefaultBlockPrioritySize is the default size in bytes for high
	// - priority / low-fee transactions.
	// It is used to help determine which are allowed into the mempool and
	// consequently affects their relay and inclusion when generating block
	// templates.
	DefaultBlockPrioritySize = 50000
)
View Source 
const (

	// DefaultMinRelayTxFee is the minimum fee in satoshi that is required
	// for a transaction to be treated as free for relay and mining purposes.
	// It is also used to help determine if a transaction is considered dust
	// and as a base for calculating minimum required fees for larger
	// transactions.  This value is in Satoshi/1000 bytes.
	DefaultMinRelayTxFee = util.Amount(1000)
)

Variables

View Source 
var (
	// EstimateFeeDatabaseKey is the key that we use to store the fee
	// estimator in the database.
	EstimateFeeDatabaseKey = []byte("estimatefee")
)

Functions

func ErrToRejectErr 

func ErrToRejectErr(err error) (wire.RejectCode, string)

ErrToRejectErr examines the underlying type of the error and returns a reject code and string appropriate to be sent in a wire.MsgReject message.

func GetTxVirtualSize 

func GetTxVirtualSize(tx *util.Tx) int64

Types

type Config 

type Config struct {
	// Policy defines the various mempool configuration options related to
	// policy.
	Policy Policy
	// ChainParams identifies which chain parameters the txpool is associated
	// with.
	ChainParams *netparams.Params
	// FetchUtxoView defines the function to use to fetch unspent transaction
	// output information.
	FetchUtxoView func(*util.Tx) (*blockchain.UtxoViewpoint, error)
	// BestHeight defines the function to use to access the block height of
	// the current best chain.
	BestHeight func() int32
	// MedianTimePast defines the function to use in order to access the
	// median time past calculated from the point-of-view of the current
	// chain tip within the best chain.
	MedianTimePast func() time.Time
	// CalcSequenceLock defines the function to use in order to generate the
	// current sequence lock for the given transaction using the passed utxo
	// view.
	CalcSequenceLock func(*util.Tx, *blockchain.UtxoViewpoint) (*blockchain.SequenceLock, error)
	// IsDeploymentActive returns true if the target deploymentID is active,
	// and false otherwise. The mempool uses this function to gauge if
	// transactions using new to be soft-forked rules should be allowed into
	// the mempool or not.
	IsDeploymentActive func(deploymentID uint32) (bool, error)
	// SigCache defines a signature cache to use.
	SigCache *txscript.SigCache
	// HashCache defines the transaction hash mid-state cache to use.
	HashCache *txscript.HashCache
	// AddrIndex defines the optional address index instance to use for
	// indexing the unconfirmed transactions in the memory pool.
	// This can be nil if the address index is not enabled.
	AddrIndex *indexers.AddrIndex
	// FeeEstimatator provides a feeEstimator. If it is not nil,
	// the mempool records all new transactions it observes into the
	// feeEstimator.
	FeeEstimator *FeeEstimator
}

type DUOPerKilobyte 

type DUOPerKilobyte float64

type FeeEstimator 

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

func NewFeeEstimator 

func NewFeeEstimator(maxRollback, minRegisteredBlocks uint32) *FeeEstimator

func RestoreFeeEstimator 

func RestoreFeeEstimator(data FeeEstimatorState) (*FeeEstimator, error)

func (*FeeEstimator) EstimateFee 

func (ef *FeeEstimator) EstimateFee(numBlocks uint32) (DUOPerKilobyte, error)

func (*FeeEstimator) LastKnownHeight 

func (ef *FeeEstimator) LastKnownHeight() int32

func (*FeeEstimator) ObserveTransaction 

func (ef *FeeEstimator) ObserveTransaction(
	t *TxDesc)

func (*FeeEstimator) RegisterBlock 

func (ef *FeeEstimator) RegisterBlock(
	block *util.Block) error

func (*FeeEstimator) Rollback 

func (ef *FeeEstimator) Rollback(hash *chainhash.Hash) error

func (*FeeEstimator) Save 

func (ef *FeeEstimator) Save() FeeEstimatorState

type FeeEstimatorState 

type FeeEstimatorState []byte

type Policy 

type Policy struct {
	// MaxTxVersion is the transaction version that the mempool should
	// accept.  All transactions above this version are rejected as
	// non-standard.
	MaxTxVersion int32
	// DisableRelayPriority defines whether to relay free or low-fee
	// transactions that do not have enough priority to be relayed.
	DisableRelayPriority bool
	// AcceptNonStd defines whether to accept non-standard transactions.
	// If true, non-standard transactions will be accepted into the mempool.
	// Otherwise, all non-standard transactions will be rejected.
	AcceptNonStd bool
	// FreeTxRelayLimit defines the given amount in thousands of bytes per
	// minute that transactions with no fee are rate limited to.
	FreeTxRelayLimit float64
	// MaxOrphanTxs is the maximum number of orphan transactions that can be
	// queued.
	MaxOrphanTxs int
	// MaxOrphanTxSize is the maximum size allowed for orphan transactions.
	// This helps prevent memory exhaustion attacks from sending a lot of of
	// big orphans.
	MaxOrphanTxSize int
	// MaxSigOpCostPerTx is the cumulative maximum cost of all the signature
	// operations in a single transaction we will relay or mine.
	// It is a fraction of the max signature operations for a block.
	MaxSigOpCostPerTx int
	// MinRelayTxFee defines the minimum transaction fee in DUO/kB to be
	// considered a non-zero fee.
	MinRelayTxFee util.Amount
}

Policy houses the policy (configuration parameters) that is used to control the mempool.

type RuleError 

type RuleError struct {
	Err error
}

RuleError identifies a rule violation. It is used to indicate that processing of a 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 use the Err field to access the underlying error, which will be either a TxRuleError or a blockchain. RuleError.

func (RuleError) Error 

func (e RuleError) Error() string

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

type SatoshiPerByte 

type SatoshiPerByte float64

func NewSatoshiPerByte 

func NewSatoshiPerByte(fee util.Amount, size uint32) SatoshiPerByte

func (SatoshiPerByte) Fee 

func (rate SatoshiPerByte) Fee(size uint32) util.Amount

func (SatoshiPerByte) ToBtcPerKb 

func (rate SatoshiPerByte) ToBtcPerKb() DUOPerKilobyte

type Tag 

type Tag uint64

type TxDesc 

type TxDesc struct {
	mining.TxDesc
	// StartingPriority is the priority of the transaction when it was added
	// to the pool.
	StartingPriority float64
}

type TxPool 

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

func New 

func New(cfg *Config) *TxPool

func (*TxPool) CheckSpend 

func (mp *TxPool) CheckSpend(op wire.OutPoint) *util.Tx

func (*TxPool) Count 

func (mp *TxPool) Count() int

func (*TxPool) FetchTransaction 

func (mp *TxPool) FetchTransaction(txHash *chainhash.Hash) (*util.Tx, error)

func (*TxPool) HaveTransaction 

func (mp *TxPool) HaveTransaction(hash *chainhash.Hash) bool

func (*TxPool) IsOrphanInPool 

func (mp *TxPool) IsOrphanInPool(hash *chainhash.Hash) bool

func (*TxPool) IsTransactionInPool 

func (mp *TxPool) IsTransactionInPool(hash *chainhash.Hash) bool

func (*TxPool) LastUpdated 

func (mp *TxPool) LastUpdated() time.Time

func (*TxPool) MaybeAcceptTransaction 

func (mp *TxPool) MaybeAcceptTransaction(b *blockchain.BlockChain,
	tx *util.Tx, isNew, rateLimit bool) ([]*chainhash.Hash, *TxDesc, error)

func (*TxPool) MiningDescs 

func (mp *TxPool) MiningDescs() []*mining.TxDesc

func (*TxPool) ProcessOrphans 

func (mp *TxPool) ProcessOrphans(b *blockchain.BlockChain, acceptedTx *util.Tx) []*TxDesc

func (*TxPool) ProcessTransaction 

func (mp *TxPool) ProcessTransaction(b *blockchain.BlockChain, tx *util.Tx,
	allowOrphan, rateLimit bool, tag Tag) ([]*TxDesc, error)

func (*TxPool) RawMempoolVerbose 

func (mp *TxPool) RawMempoolVerbose() map[string]*btcjson.GetRawMempoolVerboseResult

func (*TxPool) RemoveDoubleSpends 

func (mp *TxPool) RemoveDoubleSpends(tx *util.Tx)

func (*TxPool) RemoveOrphan 

func (mp *TxPool) RemoveOrphan(tx *util.Tx)

func (*TxPool) RemoveOrphansByTag 

func (mp *TxPool) RemoveOrphansByTag(tag Tag) uint64

func (*TxPool) RemoveTransaction 

func (mp *TxPool) RemoveTransaction(tx *util.Tx, removeRedeemers bool)

func (*TxPool) TxDescs 

func (mp *TxPool) TxDescs() []*TxDesc

func (*TxPool) TxHashes 

func (mp *TxPool) TxHashes() []*chainhash.Hash

type TxRuleError 

type TxRuleError struct {
	RejectCode  wire.RejectCode // The code to send with reject messages
	Description string          // Human readable description of the issue
}

TxRuleError identifies a rule violation. It is used to indicate that processing of a 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 (TxRuleError) Error 

func (e TxRuleError) Error() string

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

Source Files

View all Source files

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.