Package com.privatechain.core.mempool

Class TransactionMempool

java.lang.Object
com.privatechain.core.mempool.TransactionMempool
public final class TransactionMempool extends Object
In-memory pool of submitted, unconfirmed transactions ordered by a pluggable TransactionPrioritizer (FR-MEMPOOL-01 through FR-MEMPOOL-05).

Milestone 8 wiring (T-066)

When constructed with a BlockchainEventBus the mempool automatically:

  1. Publishes a BlockchainEvent.TransactionSubmittedEvent on every successful submit(Transaction) call.
  2. Registers an internal BlockchainEventListener that listens for BlockchainEvent.BlockAddedEvent and removes all transactions that were confirmed in that block (FR-MEMPOOL-05).

Thread safety

All public methods are protected by a ReentrantLock. The event listener callback onEvent() also acquires the same lock before modifying the pool, so concurrent submissions and block-confirmations are always safe.

Usage


 TransactionMempool mempool = new TransactionMempool(
     new FeeBasedPrioritizer(), eventBus);
 mempool.start(Duration.ofMinutes(10)); // enable TTL eviction

 MempoolSubmissionResult result = mempool.submitWithValidation(tx, blockchain);
 if (result.isAccepted()) {
     // tx is in the pool and TransactionSubmittedEvent has been published
 }
Since:
1.0.0
See Also:

  • Constructor Details

  • Method Details

    • submit

      public boolean submit(Transaction transaction)
      Submits a transaction to the pool without pre-validation.

      The transaction is rejected if:

      • The pool already contains a transaction with the same ID (duplicate)
      • The pool is at capacity and the new transaction has lower priority than all existing transactions (lowest-priority eviction applies)

      On acceptance, if an event bus is wired, a BlockchainEvent.TransactionSubmittedEvent is published asynchronously.

      Parameters:
      transaction - the transaction to submit (non-null)
      Returns:
      true if the transaction was accepted; false if rejected
      Throws:
      NullPointerException - if transaction is null

    • submitWithValidation

      public MempoolSubmissionResult submitWithValidation(Transaction transaction, Blockchain chain)
      Validates and submits a transaction using the configured TransactionValidator.

      If no validator was provided at construction time, this behaves identically to submit(Transaction).

      Parameters:
      transaction - the transaction to validate and submit (non-null)
      chain - the current blockchain state used during validation (non-null)
      Returns:
      a MempoolSubmissionResult describing the outcome
      Throws:
      NullPointerException - if transaction or chain is null

    • getTopN

      public List<Transaction> getTopN(int n)
      Returns the top n transactions ordered by the configured prioritizer.

      The returned list is a snapshot; modifications to the pool do not affect it.

      Parameters:
      n - maximum number of transactions to return (≥ 0)
      Returns:
      ordered list with at most n entries
      Throws:
      IllegalArgumentException - if n is negative

    • size

      public int size()
      Returns the current number of transactions in the pool.
      Returns:
      pool size (≥ 0)

    • contains

      public boolean contains(UUID transactionId)
      Returns true if the pool contains a transaction with the given ID.
      Parameters:
      transactionId - the ID to look up (non-null)
      Returns:
      true if present
      Throws:
      NullPointerException - if transactionId is null

    • remove

      public boolean remove(UUID transactionId)
      Removes a specific transaction from the pool.
      Parameters:
      transactionId - the ID of the transaction to remove (non-null)
      Returns:
      true if the transaction was found and removed
      Throws:
      NullPointerException - if transactionId is null

    • clear

      public void clear()
      Removes all transactions from the pool.

    • evictExpired

      public void evictExpired(Duration ttl)
      Evicts transactions older than the given TTL (FR-MEMPOOL-04).

      Called automatically by the background scheduler after start(java.time.Duration) is invoked. May also be called manually for an immediate eviction pass.

      Parameters:
      ttl - the time-to-live duration (non-null, positive)
      Throws:
      NullPointerException - if ttl is null

    • start

      public void start(Duration ttl)
      Starts the background TTL eviction scheduler.

      After this call, evictExpired(Duration) is called at a fixed interval equal to ttl / 2 (minimum 10 seconds). The scheduler runs as a daemon thread and stops when stop() is called.

      Parameters:
      ttl - the time-to-live for unconfirmed transactions (non-null, positive)
      Throws:
      NullPointerException - if ttl is null
      IllegalStateException - if the scheduler is already running

    • stop

      public void stop()
      Stops the background eviction scheduler and clears the pool.

      After this call, no further automatic eviction occurs. The pool is cleared so that stale references are not retained after node shutdown.