mempool

package
v0.70.7 Latest Latest
Warning

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

 Go to latest Published: Sep 7, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

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, evicted, or expired.

Service 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. DAG is the alternative backend. It indexes pending producers plus parent/child edges, and caches successful-admission order, which is topological because a pending parent must exist before a child can be admitted. DAG never watermark-evicts; network intake waits for admission headroom instead. Mempool remains the shared engine embedded by both backends for source compatibility.

Both backends validate 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

FIFO uses a two-level watermark scheme:

  • EvictionWatermark — above this fill level, oldest pending txs are evicted from the front of the queue; a value of 0 disables eviction entirely
  • RejectionWatermark — above this fill level, new submissions are rejected outright

When eviction is enabled, it is FIFO/oldest-first rather than priority- based. With the default configuration, Dingo instead applies backpressure at full mempool capacity and removes transactions only when they are confirmed, invalidated, or expired. DAG ignores EvictionWatermark, preserves admitted transactions, and exposes admission headroom so network intake pauses before the rejection watermark. Direct submissions above that watermark receive MempoolFullError.

Events

  • MempoolAddTxEventType — a tx was admitted to the pool
  • MempoolRemoveTxEventType — a tx was removed (included, evicted, or expired)

Index

Constants

View Source 
const (
	AddTransactionEventType    event.EventType = "mempool.add_tx"
	RemoveTransactionEventType event.EventType = "mempool.remove_tx"

	DefaultEvictionWatermark    = 0.0
	DefaultRejectionWatermark   = 1.0
	DefaultTransactionTTL       = 5 * time.Minute
	DefaultCleanupInterval      = 1 * time.Minute
	DefaultRevalidationDeltaCap = 64
	DefaultConsumerCacheSize    = 1024
)

Variables

View Source 
var ErrMempoolStopped = errors.New("mempool: stopped")

ErrMempoolStopped is returned when admission is attempted after shutdown.

View Source 
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

func RegisterDAGProvider added in v0.69.0 

func RegisterDAGProvider(host *plugin.Host) error

RegisterDAGProvider registers the dependency-indexed mempool/dag provider.

func RegisterFIFOProvider added in v0.69.0 

func RegisterFIFOProvider(host *plugin.Host) error

RegisterFIFOProvider registers the explicit mempool/fifo provider.

func RegisterProvider added in v0.68.0 

func RegisterProvider(host *plugin.Host) error

RegisterProvider registers the FIFO compatibility alias as mempool/default.

Types

type AddTransactionEvent 

type AddTransactionEvent struct {
	Hash string
	Body []byte
	Type uint
}

type AdmissionHeadroom added in v0.67.0 

type AdmissionHeadroom interface {
	AdmissionHeadroomBytes() int64
	MaxAdmissionHeadroomBytes() int64
	WaitForAdmissionHeadroom(minBytes int64, done <-chan error) bool
}

AdmissionHeadroom is an optional capability used by non-evicting backends to pause network intake before requesting transaction bodies that cannot fit.

type Consumer added in v0.68.0 

type Consumer interface {
	NextTx(bool) *MempoolTransaction
	GetTxFromCache(string) *MempoolTransaction
	ClearCache()
	RemoveTxFromCache(string)
	AcknowledgeOffered(count int)
}

Consumer is the neutral per-connection transaction cursor used by TxSubmission.

type DAG added in v0.69.0 

type DAG struct {
	*Mempool
}

DAG exposes the dependency-indexed mempool backend.

func NewDAG added in v0.69.0 

func NewDAG(config MempoolConfig) (*DAG, error)

NewDAG constructs the DAG backend.

func (*DAG) AddConsumer added in v0.69.0 

func (d *DAG) AddConsumer(connId ouroboros.ConnectionId) RelayConsumer

func (*DAG) AdmissionHeadroomBytes added in v0.69.0 

func (d *DAG) AdmissionHeadroomBytes() int64

AdmissionHeadroomBytes returns the bytes currently available before DAG admission reaches its rejection watermark.

func (*DAG) Consumer added in v0.69.0 

func (d *DAG) Consumer(connId ouroboros.ConnectionId) RelayConsumer

func (*DAG) Implementation added in v0.69.0 

func (d *DAG) Implementation() Implementation

func (*DAG) MaxAdmissionHeadroomBytes added in v0.69.0 

func (d *DAG) MaxAdmissionHeadroomBytes() int64

MaxAdmissionHeadroomBytes returns the maximum DAG admission budget.

func (*DAG) WaitForAdmissionHeadroom added in v0.69.0 

func (d *DAG) WaitForAdmissionHeadroom(
	minBytes int64,
	done <-chan error,
) bool

WaitForAdmissionHeadroom blocks network intake until the requested admission budget is available or either the connection or mempool stops.

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) AdmissionHeadroomBytes added in v0.70.0 

func (f *FIFO) AdmissionHeadroomBytes() int64

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

func (*FIFO) MaxAdmissionHeadroomBytes added in v0.70.0 

func (f *FIFO) MaxAdmissionHeadroomBytes() int64

func (*FIFO) WaitForAdmissionHeadroom added in v0.70.0 

func (f *FIFO) WaitForAdmissionHeadroom(
	minBytes int64,
	done <-chan error,
) bool

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"
	// ImplementationDAG tracks transaction dependencies explicitly and exposes
	// a deterministic topological order.
	ImplementationDAG Implementation = "dag"
)

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 

type Mempool struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

func NewMempool 

func NewMempool(config MempoolConfig) (*Mempool, error)

func (*Mempool) AddConsumer 

func (m *Mempool) AddConsumer(connId ouroboros.ConnectionId) *MempoolConsumer

func (*Mempool) AddTransaction 

func (m *Mempool) AddTransaction(txType uint, txBytes []byte) error

func (*Mempool) AdmissionHeadroomBytes added in v0.70.0 

func (m *Mempool) AdmissionHeadroomBytes() int64

func (*Mempool) CapacityBytes added in v0.67.0 

func (m *Mempool) CapacityBytes() int64

CapacityBytes returns the configured maximum mempool size in bytes.

func (*Mempool) Consumer 

func (m *Mempool) Consumer(connId ouroboros.ConnectionId) *MempoolConsumer

func (*Mempool) FindConsumer added in v0.68.0 

func (m *Mempool) FindConsumer(connId ouroboros.ConnectionId) Consumer

FindConsumer exposes Consumer through the neutral Service contract.

func (*Mempool) GetTransaction 

func (m *Mempool) GetTransaction(txHash string) (MempoolTransaction, bool)

func (*Mempool) MaxAdmissionHeadroomBytes added in v0.70.0 

func (m *Mempool) MaxAdmissionHeadroomBytes() int64

func (*Mempool) NewConsumer added in v0.68.0 

func (m *Mempool) NewConsumer(connId ouroboros.ConnectionId) Consumer

NewConsumer exposes AddConsumer through the neutral Service contract.

func (*Mempool) RemoveConsumer 

func (m *Mempool) RemoveConsumer(connId ouroboros.ConnectionId)

func (*Mempool) RemoveTransaction 

func (m *Mempool) RemoveTransaction(txHash string)

func (*Mempool) RemoveTxsByHash added in v0.61.1 

func (m *Mempool) RemoveTxsByHash(hashes []string)

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) Start added in v0.68.0 

func (m *Mempool) Start(ctx context.Context) error

Start begins the mempool background lifecycle. Construction is deliberately side-effect free so the plugin host owns startup and rollback.

func (*Mempool) Stop added in v0.18.0 

func (m *Mempool) Stop(ctx context.Context) error

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
	RevalidationDeltaCap int
	// ConsumerCacheSize bounds the number of transaction bodies retained per
	// transaction-submission consumer. Zero uses DefaultConsumerCacheSize.
	ConsumerCacheSize int
	// ConsumerCacheBytes bounds retained transaction body bytes per consumer.
	// Zero uses one quarter of MempoolCapacity.
	ConsumerCacheBytes int64
	CurrentSlotFunc    func() uint64 // returns current slot for early TX rejection
}

type MempoolConsumer 

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

func (*MempoolConsumer) AcknowledgeOffered added in v0.70.6 

func (m *MempoolConsumer) AcknowledgeOffered(count int)

AcknowledgeOffered forgets exactly the oldest count previously offered transaction bodies, in the order they were advertised. TxSubmission acks only the consumed prefix of the offered-id window; bodies for ids offered after that prefix are still eligible for the peer to request and must be preserved, so this must never clear the whole cache.

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 

type MempoolFullError struct {
	CurrentSize int
	TxSize      int
	Capacity    int64
}

func (*MempoolFullError) Error added in v0.13.0 

func (e *MempoolFullError) Error() string

type MempoolTransaction 

type MempoolTransaction struct {
	LastSeen time.Time
	Hash     string
	Cbor     []byte
	Type     uint
}

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 ProviderConfig added in v0.68.0 

type ProviderConfig struct {
	Capacity             int64   `yaml:"capacity"`
	EvictionWatermark    float64 `yaml:"evictionWatermark"`
	RejectionWatermark   float64 `yaml:"rejectionWatermark"`
	RevalidationDeltaCap int     `yaml:"revalidationDeltaCap"`
	// ConsumerCacheBytes bounds retained transaction body bytes per relay
	// consumer. Zero uses one quarter of Capacity; see
	// MempoolConfig.ConsumerCacheBytes.
	ConsumerCacheBytes int64 `yaml:"consumerCacheBytes"`
}

ProviderConfig is the canonical configuration for built-in mempool providers.

type ProviderDependencies added in v0.68.0 

type ProviderDependencies struct {
	PromRegistry    prometheus.Registerer
	Validator       TxValidator
	Logger          *slog.Logger
	EventBus        *event.EventBus
	CurrentSlotFunc func() uint64
}

ProviderDependencies are runtime dependencies assembled after ledger and database startup.

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 Service added in v0.68.0 

type Service interface {
	AddTransaction(uint, []byte) error
	GetTransaction(string) (MempoolTransaction, bool)
	Transactions() []MempoolTransaction
	RemoveTransaction(string)
	RemoveTxsByHash([]string)
	NewConsumer(ouroboros.ConnectionId) Consumer
	RemoveConsumer(ouroboros.ConnectionId)
	FindConsumer(ouroboros.ConnectionId) Consumer
	CapacityBytes() int64
}

Service is the domain-owned mempool capability consumed by node wiring, networking, forging, ledger, and APIs.

type TxValidationSessionProvider added in v0.69.0 

type TxValidationSessionProvider interface {
	WithTxValidationSession(func(
		validate func(
			tx gledger.Transaction,
			consumedUtxos map[string]struct{},
			createdUtxos map[string]lcommon.Utxo,
		) error,
		stillCurrent func() bool,
	) error) error
}

TxValidationSessionProvider optionally pins a batch of validations to one coherent ledger snapshot. LedgerState implements this interface; lightweight validators used by tests and alternate embeddings may continue to implement only TxValidator.

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

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.