Repository navigation
Architecture Mempool
Status: implemented in hyphen-mempool. The pool is an admission and ordering
policy, not a validator.
Consensus validation happens before a transaction reaches the pool. A caller
constructs Validated only after CLSAG, TERA, MD-VRE, balance and range-proof
checks succeed; ValidatedProtocol is the equivalent token for a protocol
payload that the canonical state machine accepted at the next height. The pool
uses these tokens to keep the policy boundary explicit, but it cannot re-run the
proof systems itself.
A pool admission is therefore not a consensus endorsement. A block builder must still validate every selected transaction against the state at the block height.
MempoolConfig::new(entries) derives a bounded profile:
| Limit | Default |
|---|---|
| Entries (payments + protocol) | max_entries |
| Aggregate bytes | min(max_entries * 8 KiB, 64 MiB) |
| Protocol entries | 25% of max_entries, at least one |
| Protocol bytes | 25% of the byte budget, at least one item |
| Per-item bytes |
MAX_TRANSACTION_SIZE (2 MiB) |
| Inputs per payment | 1 024 |
| Outputs per payment | 4 096 |
| Replacement bump | 1 000 bps |
A deployment can override these with the with_* builders. A node that wants a
relay fee sets with_minimum_fee(absolute, per_byte); the reference node uses
MIN_RELAY_FEE = 10_000, MIN_RELAY_FEE_PER_BYTE = 100 and a 14-day entry TTL.
The bare Mempool::new defaults are zero so a devnet can submit zero-fee
transactions. MempoolConfig::normalized clamps inconsistent limits (per-item
above aggregate, protocol sub-pool above pool, zero input/output caps) before a
pool is constructed; validate reports the same drift when strict checking is
wanted.
Payment priority is the tuple
(fee * 1_000_000 / serialised_bytes, VRE quality, transaction hash)
The scaled fee density avoids the truncation that integer division would
introduce for small transactions. VRE quality breaks fee ties in favour of
better ring entropy. The hash makes the order total, so every node chooses the
same eviction victim. Collections are ordered (BTreeMap), not hash-seeded.
get_block_candidates and get_block_candidate_blobs emit payments best-first.
get_block_candidate_blobs_reserved(max_size, protocol_reserve) gives protocol
payloads first claim on a reserve, then fills the remaining block budget with
payments, then retries protocol payloads that did not fit the reserve. The
reference node reserves one quarter of max_block_size, so a payment-heavy pool
cannot starve state transitions. The node applies its canonical transaction
ordering before committing the block.
fee_rate_estimate(target_blocks, block_bytes) returns the lowest fee density
among the best transactions that fit the target window, rounded up to whole base
units per byte. It is a relay-policy hint, never a consensus rule.
A replacement must:
- displace every payment that shares an input key image,
- pay at least the displaced total plus the configured bump, and
- have a fee density no lower than every displaced transaction.
Failure returns ReplacementFeeTooLow and leaves the pool untouched.
When the pool is full, admission may evict the lowest-priority payments, but
only if the incoming payment is strictly better than each victim. If it cannot
make room, admission fails with FeeTooLow or Full. Protocol payloads have
their own entry and byte budget; when the aggregate pool is full they may
displace the worst payment, but they cannot consume the payment fee index.
-
insert_at/insert_protocol_atrecord an arrival timestamp. A node callsprune_expired(now)periodically; the reference node uses a 14-day TTL. -
insert/insert_protocolcarry no timestamp and never expire. They exist for embedders and tests without a clock. -
purge_confirmed(key_images)drops every payment that spends an on-chain key image, using the key-image index rather than scanning the pool. -
purge_confirmed_protocol(hashes)drops protocol payloads included in a block. -
retain(predicate)is the revalidation hook after a reorg or a parameter change. Protocol payloads have a separate lifecycle and are not passed to the payment predicate. -
retain_protocol(predicate)applies the same revalidation to WES, AetherCompute and WASM payloads. -
takereturns the removed payment;removeandremove_protocoldiscard it.
The crate is #![no_std] with alloc. It uses no OS clock, thread, hash-seed or
filesystem API. The default std feature only adds the std::error::Error
implementation for callers that want it. The transaction dependency currently
uses std, so the pool is no_std + alloc at the crate boundary, not a claim
that the whole node can link on a hosted-less target.
The PoUW search and verification path in hyphen-pow::vms is also no_std + alloc: the prime table is evaluated at compile time and the error type is
implemented manually. hyphen-pow keeps its difficulty module behind the std
feature because it uses floating-point math, which the node needs and a
consensus-light embedder does not.
- Every payment in
entrieshas exactly oneby_priorityentry. - Every input key image in a payment maps back to that payment's hash.
-
total_bytesis the sum of payment and protocol payload sizes. -
total_feesis the sum of fees of every payment currently in the pool, updated on insert, replacement, eviction, purge and clear. -
replacements,evictionsandexpirationsare cumulative counters for operators; they are not reset byclear. - Removing an entry removes its priority, bytes, and every key image whose map value still points at it.
- A failed replacement, eviction plan, or protocol plan performs no mutation.
These invariants are exercised by the unit tests, including multi-victim byte eviction, protocol eviction, replacement limits, purge indexing, expiry and the revalidation hook.
Hyphen documentation · Protocol and node · Miner · Pool · Wallet · Security reporting