Documentation
¶
Overview ¶
Package mempool implements Dingo's transaction pool. It accepts transactions from local clients (N2C) and relayed txsubmission traffic (N2N), validates them against the current ledger state, and holds them until they are included in a block or evicted.
Pool is the backend-neutral node contract. FIFO is the default backend and orders transactions by successful admission: independent submissions retain arrival order, and a duplicate refresh does not move a transaction. Mempool remains the concrete queue embedded by FIFO for source compatibility.
The FIFO backend validates every submitted transaction through the ledger package — UTxO resolution, fees, ExUnit budgets, validity interval, size, and the full UTxO validation rules enforced by the ledger package — before admitting it. Transactions outside their validity interval relative to the current tip are rejected at submission time rather than held until expiry.
Eviction and watermarks ¶
The pool uses a two-level watermark scheme:
- EvictionWatermark — above this fill level, the oldest transactions are evicted in successful-admission order to make room for new ones
- RejectionWatermark — above this fill level, new submissions are rejected outright
Eviction is oldest-first in successful-admission order. It is not driven by fee density or another priority score.
Events ¶
- MempoolAddTxEventType — a tx was admitted to the pool
- MempoolRemoveTxEventType — a tx was removed (included, evicted, or expired)
Index ¶
- Constants
- Variables
- type AddTransactionEvent
- type AdmissionHeadroom
- type FIFO
- type Implementation
- type Mempool
- func (m *Mempool) AddConsumer(connId ouroboros.ConnectionId) *MempoolConsumer
- func (m *Mempool) AddTransaction(txType uint, txBytes []byte) error
- func (m *Mempool) CapacityBytes() int64
- func (m *Mempool) Consumer(connId ouroboros.ConnectionId) *MempoolConsumer
- func (m *Mempool) GetTransaction(txHash string) (MempoolTransaction, bool)
- func (m *Mempool) RemoveConsumer(connId ouroboros.ConnectionId)
- func (m *Mempool) RemoveTransaction(txHash string)
- func (m *Mempool) RemoveTxsByHash(hashes []string)
- func (m *Mempool) Stop(ctx context.Context) error
- func (m *Mempool) Transactions() []MempoolTransaction
- type MempoolConfig
- type MempoolConsumer
- type MempoolFullError
- type MempoolTransaction
- type Pool
- type RelayConsumer
- type RemoveTransactionEvent
- type TxValidator
Constants ¶
Variables ¶
var ErrMempoolStopped = errors.New("mempool: stopped")
ErrMempoolStopped is returned when admission is attempted after shutdown.
var ErrNilValidator = errors.New("mempool: validator is nil")
ErrNilValidator is returned by runtime mempool operations that require a non-nil validator. The constructor refuses to build a Mempool without one, so seeing this in a running node is a programmer error — but returning it lets the chain-update loop log and continue rather than crash the node.
Functions ¶
This section is empty.
Types ¶
type AddTransactionEvent ¶
type AdmissionHeadroom ¶ added in v0.67.0
type AdmissionHeadroom interface {
AdmissionHeadroomBytes() int64
MaxAdmissionHeadroomBytes() int64
WaitForAdmissionHeadroom(minBytes int64, done <-chan error) bool
}
AdmissionHeadroom is the shared capability owned by #2764. Keeping it separate allows that work to land without changing the Pool contract.
type FIFO ¶ added in v0.67.0
type FIFO struct {
*Mempool
}
FIFO exposes the current ordered mempool explicitly as the FIFO backend. The embedded Mempool preserves source compatibility while production composition depends on Pool.
func NewFIFO ¶ added in v0.67.0
func NewFIFO(config MempoolConfig) (*FIFO, error)
NewFIFO constructs the FIFO backend.
func (*FIFO) AddConsumer ¶ added in v0.67.0
func (f *FIFO) AddConsumer(connId ouroboros.ConnectionId) RelayConsumer
func (*FIFO) Consumer ¶ added in v0.67.0
func (f *FIFO) Consumer(connId ouroboros.ConnectionId) RelayConsumer
func (*FIFO) Implementation ¶ added in v0.67.0
func (f *FIFO) Implementation() Implementation
type Implementation ¶ added in v0.67.0
type Implementation string
Implementation identifies a mempool storage and ordering backend.
const ( // ImplementationFIFO preserves successful-admission order. ImplementationFIFO Implementation = "fifo" )
func (Implementation) Valid ¶ added in v0.67.0
func (i Implementation) Valid() bool
Valid reports whether the implementation name is part of the stable config surface.
type Mempool ¶
func NewMempool ¶
func NewMempool(config MempoolConfig) (*Mempool, error)
func (*Mempool) AddConsumer ¶
func (m *Mempool) AddConsumer(connId ouroboros.ConnectionId) *MempoolConsumer
func (*Mempool) AddTransaction ¶
func (*Mempool) CapacityBytes ¶ added in v0.67.0
CapacityBytes returns the configured maximum mempool size in bytes.
func (*Mempool) Consumer ¶
func (m *Mempool) Consumer(connId ouroboros.ConnectionId) *MempoolConsumer
func (*Mempool) GetTransaction ¶
func (m *Mempool) GetTransaction(txHash string) (MempoolTransaction, bool)
func (*Mempool) RemoveConsumer ¶
func (m *Mempool) RemoveConsumer(connId ouroboros.ConnectionId)
func (*Mempool) RemoveTransaction ¶
func (*Mempool) RemoveTxsByHash ¶ added in v0.61.1
RemoveTxsByHash removes a batch of transactions by hash without cascading to descendants. Use after a block is confirmed: the block's outputs are now in the ledger, so chained pending transactions remain valid and must not be evicted.
func (*Mempool) Transactions ¶ added in v0.2.2
func (m *Mempool) Transactions() []MempoolTransaction
type MempoolConfig ¶ added in v0.13.0
type MempoolConfig struct {
PromRegistry prometheus.Registerer
Validator TxValidator
Logger *slog.Logger
EventBus *event.EventBus
MempoolCapacity int64
TransactionTTL time.Duration
CleanupInterval time.Duration
EvictionWatermark float64
RejectionWatermark float64
CurrentSlotFunc func() uint64 // returns current slot for early TX rejection
}
type MempoolConsumer ¶
type MempoolConsumer struct {
// contains filtered or unexported fields
}
func (*MempoolConsumer) ClearCache ¶
func (m *MempoolConsumer) ClearCache()
func (*MempoolConsumer) GetTxFromCache ¶
func (m *MempoolConsumer) GetTxFromCache(hash string) *MempoolTransaction
func (*MempoolConsumer) NextTx ¶
func (m *MempoolConsumer) NextTx(blocking bool) *MempoolTransaction
func (*MempoolConsumer) RemoveTxFromCache ¶
func (m *MempoolConsumer) RemoveTxFromCache(hash string)
type MempoolFullError ¶ added in v0.13.0
func (*MempoolFullError) Error ¶ added in v0.13.0
func (e *MempoolFullError) Error() string
type MempoolTransaction ¶
type Pool ¶ added in v0.67.0
type Pool interface {
Implementation() Implementation
Stop(ctx context.Context) error
AddTransaction(txType uint, txBytes []byte) error
GetTransaction(txHash string) (MempoolTransaction, bool)
Transactions() []MempoolTransaction
CapacityBytes() int64
RemoveTransaction(txHash string)
RemoveTxsByHash(hashes []string)
AddConsumer(connId ouroboros.ConnectionId) RelayConsumer
RemoveConsumer(connId ouroboros.ConnectionId)
Consumer(connId ouroboros.ConnectionId) RelayConsumer
}
Pool is the backend-neutral mempool contract used at the node composition boundary. Confirmed removals use RemoveTxsByHash; RemoveTransaction is for manual removal and may also remove invalid descendants.
func New ¶ added in v0.67.0
func New(implementation Implementation, config MempoolConfig) (Pool, error)
New constructs the selected mempool implementation. An empty value selects FIFO for compatibility with callers that predate configurable backends.
type RelayConsumer ¶ added in v0.67.0
type RelayConsumer interface {
NextTx(blocking bool) *MempoolTransaction
GetTxFromCache(hash string) *MempoolTransaction
ClearCache()
RemoveTxFromCache(hash string)
}
RelayConsumer is the backend-neutral cursor and advertised-transaction cache used by node-to-node TxSubmission.
type RemoveTransactionEvent ¶
type RemoveTransactionEvent struct {
Hash string
}
type TxValidator ¶ added in v0.14.0
type TxValidator interface {
ValidateTx(tx gledger.Transaction) error
ValidateTxWithOverlay(
tx gledger.Transaction,
consumedUtxos map[string]struct{},
createdUtxos map[string]lcommon.Utxo,
) error
}
TxValidator defines the interface for transaction validation needed by mempool.
Source Files