mempool

package
v0.4.0-rc2 Latest Latest
Warning

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

 Go to latest Published: Aug 4, 2026 License: ISC Imports: 27 Imported by: 0

README

mempool

Build Status ISC License GoDoc

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

A key responsibility 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/btcsuite/btcd/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 responsibility 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 1. Reject non-fully-spent duplicate transactions 2. Reject coinbase transactions 3. Reject double spends (both from the chain and other transactions in pool) 4. Reject invalid transactions according to the network consensus rules 5. Full script execution and validation with signature cache support 6. Individual transaction query support
  • Orphan transaction support (transactions that spend from unknown outputs) 1. Configurable limits (see transaction acceptance policy) 2. Automatic addition of orphan transactions that are no longer orphans as new transactions are added to the pool 3. Individual orphan transaction query support
  • Configurable transaction acceptance policy 1. Option to accept or reject standard transactions 2. Option to accept or reject transactions based on priority calculations 3. Rate limiting of low-fee and free transactions 4. Non-zero fee threshold 5. Max signature operations per transaction 6. Max orphan transaction size 7. Max number of orphan transactions allowed
  • Additional metadata tracking for each transaction 1. Timestamp when the transaction was added to the pool 2. Most recent block height when the transaction was added to the pool 3. The fee the transaction pays 4. The starting priority for the transaction
  • Manual control of transaction removal 1. 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
	// it will provide fee estimations.
	DefaultEstimateFeeMinRegisteredBlocks = 3
)
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

	// MaxRBFSequence is the maximum sequence number an input can use to
	// signal that the transaction spending it can be replaced using the
	// Replace-By-Fee (RBF) policy.
	MaxRBFSequence = 0xfffffffd

	// MaxReplacementEvictions is the maximum number of transactions that
	// can be evicted from the mempool when accepting a transaction
	// replacement.
	MaxReplacementEvictions = 100

	// MaxMempoolAncestors is the maximum number of transactions allowed in
	// an unconfirmed dependency chain, including the transaction being
	// accepted. This matches the default Handshake mempool policy.
	MaxMempoolAncestors = 50

	// DefaultMaxMempoolSize is hsd's default aggregate mempool memory
	// estimate limit.
	DefaultMaxMempoolSize = 100 * 1000 * 1000

	// DefaultMempoolExpiry is hsd's default maximum age for an unconfirmed
	// transaction package.
	DefaultMempoolExpiry = 72 * time.Hour

	// Transactions smaller than 65 non-witness bytes are not relayed to
	// mitigate CVE-2017-12842.
	MinStandardTxNonWitnessSize = 65
)
View Source 
const (
	// MaxStandardTxSigOpsCost is the maximum signature operation cost for a
	// standard transaction. Handshake limits a transaction to one fifth of
	// the block sigop budget.
	MaxStandardTxSigOpsCost = blockchain.MaxBlockSigOpsCost / 5

	// 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 = hnsutil.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 CheckTransactionStandard 

func CheckTransactionStandard(tx *hnsutil.Tx, height int32,
	medianTimePast time.Time, minRelayTxFee hnsutil.Amount,
	maxTxVersion int32) error

CheckTransactionStandard performs a series of checks on a transaction to ensure it is a "standard" transaction. A standard transaction is one that conforms to several additional limiting cases over what is considered a "sane" transaction such as having a version in the supported range, being finalized, conforming to more stringent size constraints, having scripts of recognized forms, and not containing "dust" outputs (those that are so small it costs more to process them than they are worth).

func DisableLog 

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by default until either UseLogger or SetLogWriter are called.

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 GetDustThreshold 

func GetDustThreshold(txOut *wire.TxOut) int64

GetDustThreshold calculates the size component of the dust limit for a *wire.TxOut by taking the size of a typical spending transaction and multiplying it by 3. Handshake name covenants that carry protocol state, and native nulldata outputs, are exempt from dust policy and return zero.

func GetTxVirtualSize 

func GetTxVirtualSize(tx *hnsutil.Tx) int64

GetTxVirtualSize computes the virtual size of a given transaction. A transaction's virtual size is based off its weight, creating a discount for any witness data it contains, proportional to the current blockchain.WitnessScaleFactor value.

func IsDust 

func IsDust(txOut *wire.TxOut, minRelayTxFee hnsutil.Amount) bool

IsDust returns whether or not the passed transaction output amount is considered dust or not based on the passed minimum transaction relay fee. Dust is defined in terms of the minimum transaction relay fee. In particular, if the cost to the network to spend coins is more than 1/3 of the minimum transaction relay fee, it is considered dust.

func UseLogger 

func UseLogger(logger btclog.Logger)

UseLogger uses a specified Logger to output package logging info. This should be used in preference to SetLogWriter if the caller is also using btclog.

Types

type BtcPerKilobyte deprecated 

type BtcPerKilobyte = HNSPerKilobyte

BtcPerKilobyte is retained as an alias for source compatibility.

Deprecated: use HNSPerKilobyte.

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 *chaincfg.Params

	// FetchUtxoView defines the function to use to fetch unspent
	// transaction output information.
	FetchUtxoView func(*hnsutil.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(*hnsutil.Tx, *blockchain.UtxoViewpoint) (*blockchain.SequenceLock, error)

	// CheckTransactionNames validates Handshake name covenant transitions
	// against the current chain name state and the provided UTXO view.
	CheckTransactionNames func(*hnsutil.Tx, int32, int64, *blockchain.UtxoViewpoint) error

	// NewNameValidationView returns a stateful Handshake name-validation
	// view initialized from the current chain state.  When provided, the
	// mempool uses it to replay existing unconfirmed name transactions in
	// dependency order before validating a new transaction.
	NewNameValidationView func() (NameValidationView, 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)

	// IsAirdropSpent returns true if the airdrop bitfield position has
	// already been consumed by the active chain.  It is optional because
	// tests and non-chain-backed pools can still rely on block validation.
	IsAirdropSpent func(position 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

	// FeeEstimator provides a feeEstimator. If it is not nil, the mempool
	// records all new transactions it observes into the feeEstimator.
	FeeEstimator *FeeEstimator

	// Now supplies wall-clock time for transaction aging. It defaults to
	// time.Now and can be replaced by tests.
	Now func() time.Time
}

Config is a descriptor containing the memory pool configuration.

type DooPerByte 

type DooPerByte float64

DooPerByte is a fee rate in Handshake's base unit per byte.

func NewDooPerByte 

func NewDooPerByte(fee hnsutil.Amount, size uint32) DooPerByte

NewDooPerByte creates a DooPerByte from an Amount and a size in bytes.

func NewSatoshiPerByte deprecated 

func NewSatoshiPerByte(fee hnsutil.Amount, size uint32) DooPerByte

NewSatoshiPerByte creates a fee rate from an Amount and a size in bytes.

Deprecated: use NewDooPerByte.

func (DooPerByte) Fee 

func (rate DooPerByte) Fee(size uint32) hnsutil.Amount

Fee returns the fee for a transaction of a given size for the given fee rate.

func (DooPerByte) ToBtcPerKb deprecated 

func (rate DooPerByte) ToBtcPerKb() HNSPerKilobyte

ToBtcPerKb is retained for source compatibility. It returns Handshake's native coin per kilobyte in HNS.

Deprecated: use ToHNSPerKb.

func (DooPerByte) ToHNSPerKb 

func (rate DooPerByte) ToHNSPerKb() HNSPerKilobyte

ToHNSPerKb converts a fee rate in doo per byte to HNS per kilobyte.

type FeeEstimator 

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

FeeEstimator manages the data necessary to create fee estimations. It is safe for concurrent access.

func NewFeeEstimator 

func NewFeeEstimator(maxRollback, minRegisteredBlocks uint32) *FeeEstimator

NewFeeEstimator creates a FeeEstimator for which at most maxRollback blocks can be unregistered and which returns an error unless minRegisteredBlocks have been registered with it.

func RestoreFeeEstimator 

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

RestoreFeeEstimator takes a FeeEstimatorState that was previously returned by Save and restores it to a FeeEstimator

func (*FeeEstimator) EstimateFee 

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

EstimateFee estimates the fee in HNS per kilobyte to have a transaction confirmed a given number of blocks from now.

func (*FeeEstimator) LastKnownHeight 

func (ef *FeeEstimator) LastKnownHeight() int32

LastKnownHeight returns the height of the last block which was registered.

func (*FeeEstimator) ObserveTransaction 

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

ObserveTransaction is called when a new transaction is observed in the mempool.

func (*FeeEstimator) RegisterBlock 

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

RegisterBlock informs the fee estimator of a new block to take into account.

func (*FeeEstimator) Rollback 

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

Rollback unregisters a recently registered block from the FeeEstimator. This can be used to reverse the effect of an orphaned block on the fee estimator. The maximum number of rollbacks allowed is given by maxRollbacks.

Note: not everything can be rolled back because some transactions are deleted if they have been observed too long ago. That means the result of Rollback won't always be exactly the same as if the last block had not happened, but it should be close enough.

func (*FeeEstimator) Save 

func (ef *FeeEstimator) Save() FeeEstimatorState

Save records the current state of the FeeEstimator to a []byte that can be restored later.

type FeeEstimatorState 

type FeeEstimatorState []byte

FeeEstimatorState represents a saved FeeEstimator that can be restored with data from an earlier session of the program.

type HNSPerKilobyte 

type HNSPerKilobyte float64

HNSPerKilobyte is a fee rate in HNS per kilobyte.

type MempoolAcceptResult 

type MempoolAcceptResult struct {
	// TxFee is the fees paid in dollarydoos.
	TxFee hnsutil.Amount

	// TxSize is the virtual size(vb) of the tx.
	TxSize int64

	// conflicts is a set of transactions whose inputs are spent by this
	// transaction(RBF).
	Conflicts map[chainhash.Hash]*hnsutil.Tx

	// MissingParents is a set of outpoints that are used by this
	// transaction which cannot be found. Transaction is an orphan if any
	// of the referenced transaction outputs don't exist or are already
	// spent.
	//
	// NOTE: this field is mutually exclusive with other fields. If this
	// field is not nil, then other fields must be empty.
	MissingParents []*chainhash.Hash
	// contains filtered or unexported fields
}

MempoolAcceptResult holds the result from mempool acceptance check.

type MockTxMempool 

type MockTxMempool struct {
	mock.Mock
}

MockTxMempool is a mock implementation of the TxMempool interface.

func (*MockTxMempool) CheckMempoolAcceptance 

func (m *MockTxMempool) CheckMempoolAcceptance(
	tx *hnsutil.Tx) (*MempoolAcceptResult, error)

CheckMempoolAcceptance behaves similarly to bitcoind's `testmempoolaccept` RPC method. It will perform a series of checks to decide whether this transaction can be accepted to the mempool. If not, the specific error is returned and the caller needs to take actions based on it.

func (*MockTxMempool) CheckSpend 

func (m *MockTxMempool) CheckSpend(op wire.OutPoint) *hnsutil.Tx

CheckSpend checks whether the passed outpoint is already spent by a transaction in the mempool. If that's the case the spending transaction will be returned, if not nil will be returned.

func (*MockTxMempool) Count 

func (m *MockTxMempool) Count() int

Count returns the number of transactions in the main pool. It does not include the orphan pool.

func (*MockTxMempool) FetchTransaction 

func (m *MockTxMempool) FetchTransaction(
	txHash *chainhash.Hash) (*hnsutil.Tx, error)

FetchTransaction returns the requested transaction from the transaction pool. This only fetches from the main transaction pool and does not include orphans.

func (*MockTxMempool) HaveTransaction 

func (m *MockTxMempool) HaveTransaction(hash *chainhash.Hash) bool

HaveTransaction returns whether or not the passed transaction already exists in the main pool or in the orphan pool.

func (*MockTxMempool) LastUpdated 

func (m *MockTxMempool) LastUpdated() time.Time

LastUpdated returns the last time a transaction was added to or removed from the source pool.

func (*MockTxMempool) ProcessTransaction 

func (m *MockTxMempool) ProcessTransaction(tx *hnsutil.Tx, allowOrphan,
	rateLimit bool, tag Tag) ([]*TxDesc, error)

ProcessTransaction is the main workhorse for handling insertion of new free-standing transactions into the memory pool. It includes functionality such as rejecting duplicate transactions, ensuring transactions follow all rules, orphan transaction handling, and insertion into the memory pool.

func (*MockTxMempool) RawMempoolVerbose 

func (m *MockTxMempool) RawMempoolVerbose() map[string]*hnsjson.
	GetRawMempoolVerboseResult

RawMempoolVerbose returns all the entries in the mempool as a fully populated hnsjson result.

func (*MockTxMempool) RemoveTransaction 

func (m *MockTxMempool) RemoveTransaction(tx *hnsutil.Tx,
	removeRedeemers bool)

RemoveTransaction removes the passed transaction from the mempool. When the removeRedeemers flag is set, any transactions that redeem outputs from the removed transaction will also be removed recursively from the mempool, as they would otherwise become orphans.

func (*MockTxMempool) TxDescs 

func (m *MockTxMempool) TxDescs() []*TxDesc

TxDescs returns a slice of descriptors for all the transactions in the pool.

type NameValidationView 

type NameValidationView interface {
	ApplyTransaction(*hnsutil.Tx, int32, int64, *blockchain.UtxoViewpoint) error
}

NameValidationView validates ordered Handshake name covenant transitions against a shared chain+mempool state view.

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 HNS/kB
	// (expressed in dollarydoos) to be considered a non-zero fee.
	MinRelayTxFee hnsutil.Amount

	// RejectReplacement, if true, rejects accepting replacement
	// transactions using the Replace-By-Fee (RBF) signaling policy into
	// the mempool.
	RejectReplacement bool

	// MaxMempoolSize is the maximum aggregate memory estimate for accepted
	// transactions, claims, and airdrops.
	MaxMempoolSize uint64

	// MempoolExpiry is the maximum age for an unconfirmed transaction
	// package.
	MempoolExpiry time.Duration
}

Policy houses the policy (configuration parameters) which 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 deprecated 

type SatoshiPerByte = DooPerByte

SatoshiPerByte is retained as an alias for source compatibility.

Deprecated: use DooPerByte. Handshake's base unit is the doo, not the satoshi.

type Tag 

type Tag uint64

Tag represents an identifier to use for tagging orphan transactions. The caller may choose any scheme it desires, however it is common to use peer IDs so that orphans can be identified by which peer first relayed them.

type TxDesc 

type TxDesc struct {
	mining.TxDesc

	// StartingPriority is the priority of the transaction when it was added
	// to the pool.
	StartingPriority float64
	// contains filtered or unexported fields
}

TxDesc is a descriptor containing a transaction in the mempool along with additional metadata.

type TxMempool 

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

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

	// RawMempoolVerbose returns all the entries in the mempool as a fully
	// populated hnsjson result.
	RawMempoolVerbose() map[string]*hnsjson.GetRawMempoolVerboseResult

	// Count returns the number of transactions in the main pool. It does
	// not include the orphan pool.
	Count() int

	// FetchTransaction returns the requested transaction from the
	// transaction pool. This only fetches from the main transaction pool
	// and does not include orphans.
	FetchTransaction(txHash *chainhash.Hash) (*hnsutil.Tx, error)

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

	// ProcessTransaction is the main workhorse for handling insertion of
	// new free-standing transactions into the memory pool. It includes
	// functionality such as rejecting duplicate transactions, ensuring
	// transactions follow all rules, orphan transaction handling, and
	// insertion into the memory pool.
	//
	// It returns a slice of transactions added to the mempool. When the
	// error is nil, the list will include the passed transaction itself
	// along with any additional orphan transactions that were added as a
	// result of the passed one being accepted.
	ProcessTransaction(tx *hnsutil.Tx, allowOrphan,
		rateLimit bool, tag Tag) ([]*TxDesc, error)

	// RemoveTransaction removes the passed transaction from the mempool.
	// When the removeRedeemers flag is set, any transactions that redeem
	// outputs from the removed transaction will also be removed
	// recursively from the mempool, as they would otherwise become
	// orphans.
	RemoveTransaction(tx *hnsutil.Tx, removeRedeemers bool)

	// CheckMempoolAcceptance behaves similarly to bitcoind's
	// `testmempoolaccept` RPC method. It will perform a series of checks
	// to decide whether this transaction can be accepted to the mempool.
	// If not, the specific error is returned and the caller needs to take
	// actions based on it.
	CheckMempoolAcceptance(tx *hnsutil.Tx) (*MempoolAcceptResult, error)

	// CheckSpend checks whether the passed outpoint is already spent by
	// a transaction in the mempool. If that's the case the spending
	// transaction will be returned, if not nil will be returned.
	CheckSpend(op wire.OutPoint) *hnsutil.Tx
}

TxMempool defines an interface that's used by other subsystems to interact with the mempool.

type TxPool 

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

TxPool is used as a source of transactions that need to be mined into blocks and relayed to other peers. It is safe for concurrent access from multiple peers.

func New 

func New(cfg *Config) *TxPool

New returns a new memory pool for validating and storing standalone transactions until they are mined into a block.

func (*TxPool) AddCoinbaseProof 

func (mp *TxPool) AddCoinbaseProof(proof mining.CoinbaseProof) (
	chainhash.Hash, error)

AddCoinbaseProof adds or replaces a linked claim or airdrop proof for future block templates. The proof is cloned before it is stored.

func (*TxPool) CheckMempoolAcceptance 

func (mp *TxPool) CheckMempoolAcceptance(tx *hnsutil.Tx) (
	*MempoolAcceptResult, error)

CheckMempoolAcceptance behaves similarly to bitcoind's `testmempoolaccept` RPC method. It will perform a series of checks to decide whether this transaction can be accepted to the mempool. If not, the specific error is returned and the caller needs to take actions based on it.

func (*TxPool) CheckSpend 

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

CheckSpend checks whether the passed outpoint is already spent by a transaction in the mempool. If that's the case the spending transaction will be returned, if not nil will be returned.

func (*TxPool) CoinbaseProofs 

func (mp *TxPool) CoinbaseProofs(nextBlockHeight int32) (
	[]mining.CoinbaseProof, error)

CoinbaseProofs returns claim and airdrop proofs to include in a block template at the provided height. Claim proofs are height-bound by their CLAIM covenant height; airdrop proofs are available until removed.

func (*TxPool) Count 

func (mp *TxPool) Count() int

Count returns the number of transactions in the main pool. It does not include the orphan pool.

This function is safe for concurrent access.

func (*TxPool) FetchCoinbaseProof 

func (mp *TxPool) FetchCoinbaseProof(hash *chainhash.Hash) (
	mining.CoinbaseProof, bool)

FetchCoinbaseProof returns a cloned claim or airdrop proof by hsd proof hash.

func (*TxPool) FetchTransaction 

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

FetchTransaction returns the requested transaction from the transaction pool. This only fetches from the main transaction pool and does not include orphans.

This function is safe for concurrent access.

func (*TxPool) HaveCoinbaseProof 

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

HaveCoinbaseProof returns whether the pool has a claim or airdrop proof with the provided hsd proof hash.

func (*TxPool) HaveTransaction 

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

HaveTransaction returns whether or not the passed transaction already exists in the main pool or in the orphan pool.

This function is safe for concurrent access.

func (*TxPool) IsOrphanInPool 

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

IsOrphanInPool returns whether or not the passed transaction already exists in the orphan pool.

This function is safe for concurrent access.

func (*TxPool) IsTransactionInPool 

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

IsTransactionInPool returns whether or not the passed transaction already exists in the main pool.

This function is safe for concurrent access.

func (*TxPool) LastUpdated 

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

LastUpdated returns the last time a transaction was added to or removed from the main pool. It does not include the orphan pool.

This function is safe for concurrent access.

func (*TxPool) MaybeAcceptTransaction 

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

MaybeAcceptTransaction is the main workhorse for handling insertion of new free-standing transactions into a memory pool. It includes functionality such as rejecting duplicate transactions, ensuring transactions follow all rules, detecting orphan transactions, and insertion into the memory pool.

If the transaction is an orphan (missing parent transactions), the transaction is NOT added to the orphan pool, but each unknown referenced parent is returned. Use ProcessTransaction instead if new orphans should be added to the orphan pool.

This function is safe for concurrent access.

func (*TxPool) MemoryUsage 

func (mp *TxPool) MemoryUsage() (uint64, uint64)

MemoryUsage returns the aggregate retained-memory estimate and configured limit for accepted transactions, claims, and airdrops.

This function is safe for concurrent access.

func (*TxPool) MiningDescs 

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

MiningDescs returns a slice of mining descriptors for all the transactions in the pool.

This is part of the mining.TxSource interface implementation and is safe for concurrent access as required by the interface contract.

func (*TxPool) ProcessOrphans 

func (mp *TxPool) ProcessOrphans(acceptedTx *hnsutil.Tx) []*TxDesc

ProcessOrphans determines if there are any orphans which depend on the passed transaction hash (it is possible that they are no longer orphans) and potentially accepts them to the memory pool. It repeats the process for the newly accepted transactions (to detect further orphans which may no longer be orphans) until there are no more.

It returns a slice of transactions added to the mempool. A nil slice means no transactions were moved from the orphan pool to the mempool.

This function is safe for concurrent access.

func (*TxPool) ProcessTransaction 

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

ProcessTransaction is the main workhorse for handling insertion of new free-standing transactions into the memory pool. It includes functionality such as rejecting duplicate transactions, ensuring transactions follow all rules, orphan transaction handling, and insertion into the memory pool.

It returns a slice of transactions added to the mempool. When the error is nil, the list will include the passed transaction itself along with any additional orphan transactions that were added as a result of the passed one being accepted.

This function is safe for concurrent access.

func (*TxPool) PruneCoinbaseProofs 

func (mp *TxPool) PruneCoinbaseProofs() (int, error)

PruneCoinbaseProofs removes stored coinbase proofs that are no longer eligible to be mined at the current chain tip.

func (*TxPool) PruneInvalidNameTransactions 

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

PruneInvalidNameTransactions removes mempool transactions whose Handshake covenant transitions are no longer valid against the current chain state.

func (*TxPool) RawMempoolVerbose 

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

RawMempoolVerbose returns all the entries in the mempool as a fully populated hnsjson result.

This function is safe for concurrent access.

func (*TxPool) RemoveCoinbaseProof 

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

RemoveCoinbaseProof removes the proof with the provided proof hash from the pool. It returns whether a proof was removed.

func (*TxPool) RemoveCoinbaseProofs 

func (mp *TxPool) RemoveCoinbaseProofs(coinbaseTx *hnsutil.Tx) int

RemoveCoinbaseProofs removes claim and airdrop proofs consumed by the passed coinbase transaction. It returns the number of stored proofs removed.

func (*TxPool) RemoveDoubleSpends 

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

RemoveDoubleSpends removes all transactions which spend outputs spent by the passed transaction from the memory pool. Removing those transactions then leads to removing all transactions which rely on them, recursively. This is necessary when a block is connected to the main chain because the block may contain transactions which were previously unknown to the memory pool.

This function is safe for concurrent access.

func (*TxPool) RemoveNameConflicts 

func (mp *TxPool) RemoveNameConflicts(tx *hnsutil.Tx)

RemoveNameConflicts removes transactions from the mempool which mutate the same Handshake name as the passed transaction. This is necessary when a block is connected to the main chain because name operations such as OPEN do not necessarily conflict by input outpoint.

func (*TxPool) RemoveOrphan 

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

RemoveOrphan removes the passed orphan transaction from the orphan pool and previous orphan index.

This function is safe for concurrent access.

func (*TxPool) RemoveOrphansByTag 

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

RemoveOrphansByTag removes all orphan transactions tagged with the provided identifier.

This function is safe for concurrent access.

func (*TxPool) RemoveTransaction 

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

RemoveTransaction removes the passed transaction from the mempool. When the removeRedeemers flag is set, any transactions that redeem outputs from the removed transaction will also be removed recursively from the mempool, as they would otherwise become orphans.

This function is safe for concurrent access.

func (*TxPool) TxDescs 

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

TxDescs returns a slice of descriptors for all the transactions in the pool. The descriptors are to be treated as read only.

This function is safe for concurrent access.

func (*TxPool) TxHashes 

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

TxHashes returns a slice of hashes for all the transactions in the memory pool.

This function is safe for concurrent access.

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.