graph TD
    A1[HTTP API Request] --> A2{HTTP Rate Limit Check}
    A2 -->|Rate Limited| A3[HTTP 429 Error]
    A2 -->|Within Limit| A4[Parse Transaction]
    A4 --> B{Validate Transaction}

    A5[Network Gossip] --> B

    B -->|Invalid| C[Mark Invalid]
    B -->|Valid| D{Dependencies Satisfied?}
    D -->|Yes| E[Add to Pool]
    D -->|No| F[Add to Dep-Wait]
    E --> G[In Ready Pool]
    F --> H[Waiting for Dependencies]
    H -->|Dependencies Arrive| E
    G --> I[Block Builder Uses TX]
    I --> J[Move to In-Block]
    J --> K[Wait for Consensus]
    K --> L{Block Outcome}
    L -->|Immutable| M[Add to Finalized Cache]
    L -->|Stale Our Block| N[Return to Pool]
    N --> G

Overview

The Nomos mempool manages transaction hashes in memory with full transaction data in storage. It provides:

• LRU-based ready pool for transactions available to proposals
• Dependency tracking for transactions waiting on UTXOs or channel parents
• DoS protection through rate limiting and complexity bounds
• Block lifecycle handling: when we build a block, we move selected txs from Pool → In-Block (separate set, not selectable for local proposals); on finalize, we move them into finalized_cache (prevents replay of finalized transactions); on prune (our block), we return still-ready txs to Pool

Component overview

Fetch protocol (design sketch, not part of this doc)

When transaction hashes are evicted from the mempool, the corresponding transaction bodies are removed from storage to prevent unbounded growth.

• Problem: If an evicted transaction later appears in a valid block, the node cannot validate that block because it no longer has the transaction data.

• Solution: Implement a peer-to-peer fetch protocol to retrieve missing transactions:

  1. Block validation fails due to missing transaction.
  2. Request transaction from peers using the transaction hash.
  3. Peers respond with full transaction data (if they have it).
  4. Retry block validation with the retrieved transaction.

This ensures nodes can validate blocks even when they previously evicted transactions due to mempool capacity management.

Implementation sketch

Mempool structure

struct Mempool {
    // Unused, ready transactions for proposals
    pool: LruCache<TxHash, ()>,

    // Our local in-block transactions (never evicted until outcome)
    in_block: HashMap<TxHash, BlockId>,
    
    // Reverse index
    block_to_txs: HashMap<BlockId, Vec<TxHash>>,  

    // Transactions waiting for dependencies, first simple solution — as reported by consensus
    dep_wait: DepGraph,

    // Known invalid transactions (prevent reprocessing)
    invalid_cache: TtlSet<TxHash>,

    // Track finalized transactions to prevent re-adding on pruning
    finalized_cache: TtlSet<TxHash>,
}

Transaction entry point

Validation steps: