Fuel Core TxPool Transaction Management Features: A Complete Technical Guide

The Fuel Core TxPool supports comprehensive transaction management through configurable validation rules, resource limits, TTL-based eviction, collision detection, blacklisting, and asynchronous verification pipelines.

Fuel Core’s transaction pool (TxPool), implemented in the fuel-core repository under crates/services/txpool_v2, provides a sophisticated staging area for transactions before block inclusion. The pool’s behavior is governed by the Config structure defined in [config.rs](https://github.com/FuelLabs/fuel-core/blob/master/crates/services/txpool_v2/src/config.rs), which exposes granular controls for validation, resource allocation, and network synchronization.

UTXO Validation and Execution Controls

The TxPool validates incoming transactions against the current chain state through configurable verification layers.

Optional UTXO Validation — The utxo_validation boolean field in Config enables strict checking that each transaction’s inputs reference existing UTXOs matching stored data. When disabled, the pool accepts transactions without verifying input existence, useful for specific testing scenarios.

Syscall Allowance — The allow_syscall toggle controls whether the pool permits ECAL syscalls during transaction verification. When enabled, syscalls are allowed but ignored rather than causing rejection, providing flexibility for future protocol extensions.

Dependency Chain Limits — To prevent resource exhaustion through chained dependencies, max_txs_chain_count caps the number of transactions that can be linked together via inputs and outputs, safeguarding against pathological transaction graphs.

Resource Limits and Pool Constraints

The TxPool enforces strict resource boundaries through the PoolLimits and ServiceChannelLimits structures.

Global Pool Caps — Defined in PoolLimits, these limits restrict:

• max_txs: Maximum transaction count in the pool
• max_gas: Cumulative gas limit across all pending transactions
• max_bytes_size: Total byte size ceiling for the pool

Service Channel Throttling — ServiceChannelLimits prevents memory exhaustion by bounding pending requests:

• max_pending_write_pool_requests: Limits queued write operations
• max_pending_read_pool_requests: Limits queued read operations

Transaction Lifecycle and TTL Management

The TxPool implements sophisticated eviction policies to manage transaction staleness.

TTL Configuration — Two parameters control transaction expiration:

• ttl_check_interval: Defines the periodicity of cleanup sweeps (e.g., every 30 seconds)
• max_txs_ttl: Sets the global maximum time-to-live for any transaction before automatic removal

Pending Pool Isolation — Transactions awaiting dependencies reside in a separate pending pool with distinct parameters:

• pending_pool_tx_ttl: Shorter TTL for unready transactions (default 5 seconds)
• max_pending_pool_size_percentage: Caps pending pool size as a percentage of main pool capacity

Performance and Concurrency Configuration

The HeavyWorkConfig struct tunes the asynchronous verification pipeline for optimal throughput:

HeavyWorkConfig {
    number_threads_to_verify_transactions: 4,
    size_of_verification_queue: 200,
    number_threads_p2p_sync: 2,
    size_of_p2p_sync_queue: 200,
}

This configuration separates CPU-intensive verification work from network I/O, preventing blocking operations from stalling the pool.

Security Mechanisms and Collision Detection

Blacklist Enforcement — The BlackList struct enables operators to reject transactions referencing specific owners, UTXOs, messages, or contracts. The check_blacklisting function validates transactions against these restrictions during insertion.

Collision Management — Implemented in [collision_manager/mod.rs](https://github.com/FuelLabs/fuel-core/blob/master/crates/services/txpool_v2/src/collision_manager/mod.rs), this module detects and rejects double-spend attempts by tracking input references across the pool. When two transactions attempt to consume the same UTXO, the second submission is rejected with a collision error.

Block Production Integration

The TxPool integrates with Fuel Core’s block production through pluggable selection algorithms. The [selection_algorithms/ratio_tip_gas.rs](https://github.com/FuelLabs/fuel-core/blob/master/crates/services/txpool_v2/src/selection_algorithms/ratio_tip_gas.rs) module implements the "ratio-tip-gas" strategy, prioritizing transactions based on fee efficiency and gas limits when constructing new blocks.

P2P Network Synchronization

Peer-to-peer transaction propagation is handled in [p2p.rs](https://github.com/FuelLabs/fuel-core/blob/master/crates/services/txpool_v2/src/p2p.rs), which coordinates:

• Transaction gossip across the network
• Fetching missing transactions from peers
• Synchronizing pool state during node startup

Observability and Metrics

The metrics boolean field in Config enables Prometheus-style instrumentation of pool operations. When activated, the service exposes counters for insertion rates, rejection reasons, pool size, and TTL eviction statistics.

Summary

• Fuel Core TxPool manages transaction ingestion through the Config struct in crates/services/txpool_v2/src/config.rs
• Validation features include optional UTXO checking, syscall allowance, and dependency chain limits
• Resource guards enforce ceilings on transaction count, gas, and bytes via PoolLimits
• Lifecycle management uses configurable TTL intervals and a segregated pending pool
• Performance tuning leverages HeavyWorkConfig for multi-threaded verification and P2P sync
• Security controls comprise blacklisting and collision detection to prevent double-spends
• Block production integrates through selection algorithms like ratio-tip-gas
• Observability is available via optional Prometheus metrics

Frequently Asked Questions

What is the maximum number of transactions Fuel Core TxPool can hold?

The maximum transaction count is configurable via PoolLimits::max_txs in config.rs. Operators set this value based on available memory and performance requirements; the pool rejects new insertions once this limit is reached until space becomes available through block inclusion or TTL expiration.

How does Fuel Core prevent double-spending in the transaction pool?

The TxPool prevents double-spending through the collision manager implemented in collision_manager/mod.rs. This module maintains an index of all UTXOs referenced by pending transactions and rejects any new transaction attempting to spend inputs already tracked in the pool.

Can Fuel Core TxPool reject transactions from specific addresses?

Yes, through the blacklist functionality. The BlackList struct in config.rs accepts vectors of blocked owners, UTXOs, messages, and contracts. When check_blacklisting validates an incoming transaction, it returns an error if any input matches the blacklist criteria.

What happens to transactions that depend on unconfirmed UTXOs?

Transactions with unmet dependencies enter the pending pool, defined in pending_pool.rs. This isolated sub-pool uses shorter TTL values (pending_pool_tx_ttl) and size constraints (max_pending_pool_size_percentage) to prevent memory exhaustion while waiting for prerequisite transactions to confirm.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}