atlas-mempool

Summary

atlas-mempool is the transaction staging crate for the Rust workspace. It receives statelessly valid signed transactions before they are proposed, deduplicates them, tracks pending status, and exposes candidate selection for block production.

The crate uses an in-memory local mempool behind a small facade. A previous Redis-backed mempool path was removed because it did not support the sealing workflow required by block production and added O(n) remote scans to hot-path operations.

Why This Crate Exists

• keep transaction staging separate from ledger execution
• give node and admin surfaces one place to enqueue signed transactions
• prevent obvious duplicates and nonce conflicts before proposal construction
• support local development and node runtime transaction staging behind the same API

Current Role In The Workspace

atlas-mempool currently owns four main concerns:

1. a unified Mempool facade
2. local in-process transaction storage
3. admission checks such as stateless validation and timestamp windows
4. batch-oriented lifecycle operations such as sealing, marking pending, cleanup, and removal

It is not the final authority for transaction validity. The ledger still performs deeper validation later. The mempool acts as the admission and staging layer before proposal creation or relay.

Public Surface

Top-Level Modules

• core

Main Public Reexports

• Mempool
• MempoolValidationPolicy
• atlas_common::ports::MempoolPort

Important Types

• Mempool
• MempoolValidationPolicy
• LocalMempool

Important Trait Implemented

• atlas_common::ports::MempoolPort for Mempool

Key Modules

• `lib.rs`: public facade and MempoolPort implementation
• `core/mempool.rs`: unified mempool wrapper and validation policy
• `core/mempool/local.rs`: in-memory backend with pending tracking, sealing, cleanup, and committed-cache behavior
• `tests/integration.rs`: integration tests for local behavior and rejection of the removed Redis mempool backend

Inputs And Outputs

Inputs

• SignedTransaction values from REST, gRPC, admin, or runtime replay flows
• mempool validation policy for local deployments

Outputs

• accepted or rejected mempool admissions
• candidate batches for proposal construction
• pending markers for in-flight transactions
• duplicate detection results
• cleanup results for expired or stuck transactions

Internal Dependencies

Workspace Dependencies

• atlas-common

This crate sits just above the shared types layer and below the node and ledger layers.

External Dependencies That Shape The Design

• sha2 and hex for transaction hashing
• tokio for async operations
• async-trait for port implementation plumbing

Used By

These packages depend directly on atlas-mempool today:

• atlas-node-admin
• atlas-ledger
• atlas-node

Observed usage in the codebase includes:

• `runtime/builder.rs`: node runtime builds a mempool with configurable validation policy
• `transactions.rs`: REST transaction submission checks pending nonce conflicts and then adds to mempool
• `service.rs`: ledger gRPC service performs mempool admission after signature and nonce checks
• `handlers/kyc.rs`: admin KYC flows enqueue signed transactions into the mempool
• `handlers/institutions.rs`: admin institution issuance flows use nonce conflict checks and enqueue to the mempool

Backend Model

Local Backend

`local.rs` keeps transactions in process memory and adds some extra behavior:

• configurable timestamp-window enforcement
• pending tracking by tx hash
• a committed-cache with bounded history
• sealed batches for block producer handoff
• sender-focused pending queries such as get_pending_by_sender and get_max_pending_nonce_by_sender

Validation Model

The mempool performs admission checks, not full ledger execution checks.

The current admission path includes:

• SignedTransaction::validate_stateless()
• timestamp window enforcement
• duplicate prevention against the current pool
• duplicate prevention against a committed-cache

The local strict timestamp policy is roughly now - 300 to now + 300.

For tests, the local backend can disable timestamp enforcement through MempoolValidationPolicy::test_relaxed().

Testing

The crate has:

• module-local tests in the facade and backend implementations
• `integration.rs`: local integration coverage

The test coverage exercises:

• local default construction
• relaxed validation policy for tests
• duplicate handling
• pending and cleanup behavior
• Redis mempool backend rejection

Risks Or Design Tension

Admission Is Not Final Validation

The mempool runs stateless checks and lightweight timing rules, but authoritative validation still happens later in the ledger pipeline. That is the correct layering, but it can confuse readers if they expect mempool acceptance to imply full validity.

Open Questions

• should the sealed-batch concept stay local to the mempool crate, or move upward into block production orchestration

Relevant Files

• `Cargo.toml`
• `lib.rs`
• `mempool.rs`
• `local.rs`
• `integration.rs`
• `runtime/builder.rs`
• `transactions.rs`
• `service.rs`
• `handlers/kyc.rs`
• `handlers/institutions.rs`