txpool

Documentation

Index

• Variables
• func ValidateTransaction(tx *types.Transaction, head *types.Header, signer types.Signer, ...) error
• func ValidateTransactionWithState(tx *types.Transaction, signer types.Signer, opts *ValidationOptionsWithState) error
• type AddressReserver
• type BlockChain
• type LazyResolver
• type LazyTransaction
  • func (ltx *LazyTransaction) Resolve() *types.Transaction
• type SubPool
• type TxPool
  • func New(gasTip *big.Int, chain BlockChain, subpools []SubPool) (*TxPool, error)
  • func (p *TxPool) Add(txs []*types.Transaction, local bool, sync bool) []error
  • func (p *TxPool) Close() error
  • func (p *TxPool) Content() (map[common.Address][]*types.Transaction, ...)
  • func (p *TxPool) ContentFrom(addr common.Address) ([]*types.Transaction, []*types.Transaction)
  • func (p *TxPool) Get(hash common.Hash) *types.Transaction
  • func (p *TxPool) Has(hash common.Hash) bool
  • func (p *TxPool) Locals() []common.Address
  • func (p *TxPool) Nonce(addr common.Address) uint64
  • func (p *TxPool) Pending(enforceTips bool) map[common.Address][]*LazyTransaction
  • func (p *TxPool) SetGasTip(tip *big.Int)
  • func (p *TxPool) Stats() (int, int)
  • func (p *TxPool) Status(hash common.Hash) TxStatus
  • func (p *TxPool) SubscribeTransactions(ch chan<- core.NewTxsEvent, reorgs bool) event.Subscription
  • func (p *TxPool) Sync() error
• type TxStatus
• type ValidationOptions
• type ValidationOptionsWithState

Variables

var (
	// ErrAlreadyKnown is returned if the transactions is already contained
	// within the pool.
	ErrAlreadyKnown = errors.New("already known")

	// ErrInvalidSender is returned if the transaction contains an invalid signature.
	ErrInvalidSender = errors.New("invalid sender")

	// ErrUnderpriced is returned if a transaction's gas price is below the minimum
	// configured for the transaction pool.
	ErrUnderpriced = errors.New("transaction underpriced")

	// ErrReplaceUnderpriced is returned if a transaction is attempted to be replaced
	// with a different one without the required price bump.
	ErrReplaceUnderpriced = errors.New("replacement transaction underpriced")

	// ErrAccountLimitExceeded is returned if a transaction would exceed the number
	// allowed by a pool for a single account.
	ErrAccountLimitExceeded = errors.New("account limit exceeded")

	// ErrGasLimit is returned if a transaction's requested gas limit exceeds the
	// maximum allowance of the current block.
	ErrGasLimit = errors.New("exceeds block gas limit")

	// ErrNegativeValue is a sanity error to ensure no one is able to specify a
	// transaction with a negative value.
	ErrNegativeValue = errors.New("negative value")

	// ErrOversizedData is returned if the input data of a transaction is greater
	// than some meaningful limit a user might use. This is not a consensus error
	// making the transaction invalid, rather a DOS protection.
	ErrOversizedData = errors.New("oversized data")

	// ErrFutureReplacePending is returned if a future transaction replaces a pending
	// one. Future transactions should only be able to replace other future transactions.
	ErrFutureReplacePending = errors.New("future transaction tries to replace pending")
)

Functions

func ValidateTransaction

func ValidateTransaction(tx *types.Transaction, head *types.Header, signer types.Signer, opts *ValidationOptions) error

ValidateTransaction is a helper method to check whether a transaction is valid according to the consensus rules, but does not check state-dependent validation (balance, nonce, etc).

This check is public to allow different transaction pools to check the basic rules without duplicating code and running the risk of missed updates.

func ValidateTransactionWithState

func ValidateTransactionWithState(tx *types.Transaction, signer types.Signer, opts *ValidationOptionsWithState) error

ValidateTransactionWithState is a helper method to check whether a transaction is valid according to the pool's internal state checks (balance, nonce, gaps).

This check is public to allow different transaction pools to check the stateful rules without duplicating code and running the risk of missed updates.

Types

type AddressReserver

type AddressReserver func(addr common.Address, reserve bool) error

AddressReserver is passed by the main transaction pool to subpools, so they may request (and relinquish) exclusive access to certain addresses.

type BlockChain

type BlockChain interface {
	// CurrentBlock returns the current head of the chain.
	CurrentBlock() *types.Header

	// SubscribeChainHeadEvent subscribes to new blocks being added to the chain.
	SubscribeChainHeadEvent(ch chan<- core.ChainHeadEvent) event.Subscription
}

BlockChain defines the minimal set of methods needed to back a tx pool with a chain. Exists to allow mocking the live chain out of tests.

type LazyResolver

type LazyResolver interface {
	// Get returns a transaction if it is contained in the pool, or nil otherwise.
	Get(hash common.Hash) *types.Transaction
}

LazyResolver is a minimal interface needed for a transaction pool to satisfy resolving lazy transactions. It's mostly a helper to avoid the entire sub- pool being injected into the lazy transaction.

type LazyTransaction

type LazyTransaction struct {
	Pool LazyResolver       // Transaction resolver to pull the real transaction up
	Hash common.Hash        // Transaction hash to pull up if needed
	Tx   *types.Transaction // Transaction if already resolved

	Time      time.Time // Time when the transaction was first seen
	GasFeeCap *big.Int  // Maximum fee per gas the transaction may consume
	GasTipCap *big.Int  // Maximum miner tip per gas the transaction can pay

	Gas     uint64 // Amount of gas required by the transaction
	BlobGas uint64 // Amount of blob gas required by the transaction
}

LazyTransaction contains a small subset of the transaction properties that is enough for the miner and other APIs to handle large batches of transactions; and supports pulling up the entire transaction when really needed.

func (*LazyTransaction) Resolve

func (ltx *LazyTransaction) Resolve() *types.Transaction

Resolve retrieves the full transaction belonging to a lazy handle if it is still maintained by the transaction pool.

Note, the method will *not* cache the retrieved transaction if the original pool has not cached it. The idea being, that if the tx was too big to insert originally, silently saving it will cause more trouble down the line (and indeed seems to have caused a memory bloat in the original implementation which did just that).

type SubPool

type SubPool interface {
	// Filter is a selector used to decide whether a transaction would be added
	// to this particular subpool.
	Filter(tx *types.Transaction) bool

	// Init sets the base parameters of the subpool, allowing it to load any saved
	// transactions from disk and also permitting internal maintenance routines to
	// start up.
	//
	// These should not be passed as a constructor argument - nor should the pools
	// start by themselves - in order to keep multiple subpools in lockstep with
	// one another.
	Init(gasTip *big.Int, head *types.Header, reserve AddressReserver) error

	// Close terminates any background processing threads and releases any held
	// resources.
	Close() error

	// Reset retrieves the current state of the blockchain and ensures the content
	// of the transaction pool is valid with regard to the chain state.
	Reset(oldHead, newHead *types.Header)

	// SetGasTip updates the minimum price required by the subpool for a new
	// transaction, and drops all transactions below this threshold.
	SetGasTip(tip *big.Int)

	// Has returns an indicator whether subpool has a transaction cached with the
	// given hash.
	Has(hash common.Hash) bool

	// Get returns a transaction if it is contained in the pool, or nil otherwise.
	Get(hash common.Hash) *types.Transaction

	// Add enqueues a batch of transactions into the pool if they are valid. Due
	// to the large transaction churn, add may postpone fully integrating the tx
	// to a later point to batch multiple ones together.
	Add(txs []*types.Transaction, local bool, sync bool) []error

	// Pending retrieves all currently processable transactions, grouped by origin
	// account and sorted by nonce.
	Pending(enforceTips bool) map[common.Address][]*LazyTransaction

	// SubscribeTransactions subscribes to new transaction events. The subscriber
	// can decide whether to receive notifications only for newly seen transactions
	// or also for reorged out ones.
	SubscribeTransactions(ch chan<- core.NewTxsEvent, reorgs bool) event.Subscription

	// Nonce returns the next nonce of an account, with all transactions executable
	// by the pool already applied on top.
	Nonce(addr common.Address) uint64

	// Stats retrieves the current pool stats, namely the number of pending and the
	// number of queued (non-executable) transactions.
	Stats() (int, int)

	// Content retrieves the data content of the transaction pool, returning all the
	// pending as well as queued transactions, grouped by account and sorted by nonce.
	Content() (map[common.Address][]*types.Transaction, map[common.Address][]*types.Transaction)

	// ContentFrom retrieves the data content of the transaction pool, returning the
	// pending as well as queued transactions of this address, grouped by nonce.
	ContentFrom(addr common.Address) ([]*types.Transaction, []*types.Transaction)

	// Locals retrieves the accounts currently considered local by the pool.
	Locals() []common.Address

	// Status returns the known status (unknown/pending/queued) of a transaction
	// identified by their hashes.
	Status(hash common.Hash) TxStatus
}

SubPool represents a specialized transaction pool that lives on its own (e.g. blob pool). Since independent of how many specialized pools we have, they do need to be updated in lockstep and assemble into one coherent view for block production, this interface defines the common methods that allow the primary transaction pool to manage the subpools.

type TxPool

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

TxPool is an aggregator for various transaction specific pools, collectively tracking all the transactions deemed interesting by the node. Transactions enter the pool when they are received from the network or submitted locally. They exit the pool when they are included in the blockchain or evicted due to resource constraints.

func New

func New(gasTip *big.Int, chain BlockChain, subpools []SubPool) (*TxPool, error)

New creates a new transaction pool to gather, sort and filter inbound transactions from the network.

func (*TxPool) Add

func (p *TxPool) Add(txs []*types.Transaction, local bool, sync bool) []error

Add enqueues a batch of transactions into the pool if they are valid. Due to the large transaction churn, add may postpone fully integrating the tx to a later point to batch multiple ones together.

func (*TxPool) Close

func (p *TxPool) Close() error

Close terminates the transaction pool and all its subpools.

func (*TxPool) Content

func (p *TxPool) Content() (map[common.Address][]*types.Transaction, map[common.Address][]*types.Transaction)

Content retrieves the data content of the transaction pool, returning all the pending as well as queued transactions, grouped by account and sorted by nonce.

func (*TxPool) ContentFrom

func (p *TxPool) ContentFrom(addr common.Address) ([]*types.Transaction, []*types.Transaction)

ContentFrom retrieves the data content of the transaction pool, returning the pending as well as queued transactions of this address, grouped by nonce.

func (*TxPool) Get

func (p *TxPool) Get(hash common.Hash) *types.Transaction

Get returns a transaction if it is contained in the pool, or nil otherwise.

func (*TxPool) Has

func (p *TxPool) Has(hash common.Hash) bool

Has returns an indicator whether the pool has a transaction cached with the given hash.

func (*TxPool) Locals

func (p *TxPool) Locals() []common.Address

Locals retrieves the accounts currently considered local by the pool.

func (*TxPool) Nonce

func (p *TxPool) Nonce(addr common.Address) uint64

Nonce returns the next nonce of an account, with all transactions executable by the pool already applied on top.

func (*TxPool) Pending

func (p *TxPool) Pending(enforceTips bool) map[common.Address][]*LazyTransaction

Pending retrieves all currently processable transactions, grouped by origin account and sorted by nonce.

func (*TxPool) SetGasTip

func (p *TxPool) SetGasTip(tip *big.Int)

SetGasTip updates the minimum gas tip required by the transaction pool for a new transaction, and drops all transactions below this threshold.

func (*TxPool) Stats

func (p *TxPool) Stats() (int, int)

Stats retrieves the current pool stats, namely the number of pending and the number of queued (non-executable) transactions.

func (*TxPool) Status

func (p *TxPool) Status(hash common.Hash) TxStatus

Status returns the known status (unknown/pending/queued) of a transaction identified by its hash.

func (*TxPool) SubscribeTransactions

func (p *TxPool) SubscribeTransactions(ch chan<- core.NewTxsEvent, reorgs bool) event.Subscription

SubscribeTransactions registers a subscription for new transaction events, supporting feeding only newly seen or also resurrected transactions.

func (*TxPool) Sync

func (p *TxPool) Sync() error

Sync is a helper method for unit tests or simulator runs where the chain events are arriving in quick succession, without any time in between them to run the internal background reset operations. This method will run an explicit reset operation to ensure the pool stabilises, thus avoiding flakey behavior.

Note, do not use this in production / live code. In live code, the pool is meant to reset on a separate thread to avoid DoS vectors.

type TxStatus

type TxStatus uint

TxStatus is the current status of a transaction as seen by the pool.

const (
	TxStatusUnknown TxStatus = iota
	TxStatusQueued
	TxStatusPending
	TxStatusIncluded
)

type ValidationOptions

type ValidationOptions struct {
	Config *params.ChainConfig // Chain configuration to selectively validate based on current fork rules

	Accept  uint8    // Bitmap of transaction types that should be accepted for the calling pool
	MaxSize uint64   // Maximum size of a transaction that the caller can meaningfully handle
	MinTip  *big.Int // Minimum gas tip needed to allow a transaction into the caller pool
}

ValidationOptions define certain differences between transaction validation across the different pools without having to duplicate those checks.

type ValidationOptionsWithState

type ValidationOptionsWithState struct {
	State *state.StateDB // State database to check nonces and balances against

	// FirstNonceGap is an optional callback to retrieve the first nonce gap in
	// the list of pooled transactions of a specific account. If this method is
	// set, nonce gaps will be checked and forbidden. If this method is not set,
	// nonce gaps will be ignored and permitted.
	FirstNonceGap func(addr common.Address) uint64

	// UsedAndLeftSlots is a mandatory callback to retrieve the number of tx slots
	// used and the number still permitted for an account. New transactions will
	// be rejected once the number of remaining slots reaches zero.
	UsedAndLeftSlots func(addr common.Address) (int, int)

	// ExistingExpenditure is a mandatory callback to retrieve the cumulative
	// cost of the already pooled transactions to check for overdrafts.
	ExistingExpenditure func(addr common.Address) *big.Int

	// ExistingCost is a mandatory callback to retrieve an already pooled
	// transaction's cost with the given nonce to check for overdrafts.
	ExistingCost func(addr common.Address, nonce uint64) *big.Int
}

ValidationOptionsWithState define certain differences between stateful transaction validation across the different pools without having to duplicate those checks.