zebra_node_services/mempool.rs
1//! The Zebra mempool.
2//!
3//! A service that manages known unmined Zcash transactions.
4
5use std::collections::HashSet;
6
7use tokio::sync::oneshot;
8use zebra_chain::{
9 block,
10 transaction::{self, UnminedTx, UnminedTxId, VerifiedUnminedTx},
11 transparent,
12};
13
14use crate::BoxError;
15
16mod gossip;
17mod mempool_change;
18mod service_trait;
19mod transaction_dependencies;
20
21pub use self::{
22 gossip::Gossip,
23 mempool_change::{MempoolChange, MempoolChangeKind, MempoolTxSubscriber},
24 service_trait::MempoolService,
25 transaction_dependencies::TransactionDependencies,
26};
27
28/// A mempool service request.
29///
30/// Requests can query the current set of mempool transactions,
31/// queue transactions to be downloaded and verified, or
32/// run the mempool to check for newly verified transactions.
33///
34/// Requests can't modify the mempool directly,
35/// because all mempool transactions must be verified.
36#[derive(Debug, Eq, PartialEq)]
37pub enum Request {
38 /// Query all [`UnminedTxId`]s in the mempool.
39 TransactionIds,
40
41 /// Query matching [`UnminedTx`] in the mempool,
42 /// using a unique set of [`UnminedTxId`]s.
43 TransactionsById(HashSet<UnminedTxId>),
44
45 /// Query matching [`UnminedTx`] in the mempool,
46 /// using a unique set of [`transaction::Hash`]es. Pre-V5 transactions are matched
47 /// directly; V5 transaction are matched just by the Hash, disregarding
48 /// the [`AuthDigest`](zebra_chain::transaction::AuthDigest).
49 TransactionsByMinedId(HashSet<transaction::Hash>),
50
51 /// Request a [`transparent::Output`] identified by the given [`OutPoint`](transparent::OutPoint),
52 /// waiting until it becomes available if it is unknown.
53 ///
54 /// This request is purely informational, and there are no guarantees about
55 /// whether the UTXO remains unspent or is on the best chain, or any chain.
56 /// Its purpose is to allow orphaned mempool transaction verification.
57 ///
58 /// # Correctness
59 ///
60 /// Output requests should be wrapped in a timeout, so that
61 /// out-of-order and invalid requests do not hang indefinitely.
62 ///
63 /// Outdated requests are pruned on a regular basis.
64 AwaitOutput(transparent::OutPoint),
65
66 /// Request a [`VerifiedUnminedTx`] and its dependencies by its mined id.
67 TransactionWithDepsByMinedId(transaction::Hash),
68
69 /// Get all the [`VerifiedUnminedTx`] in the mempool.
70 ///
71 /// Equivalent to `TransactionsById(TransactionIds)`,
72 /// but each transaction also includes the `miner_fee` and `legacy_sigop_count` fields.
73 //
74 // TODO: make the Transactions response return VerifiedUnminedTx,
75 // and remove the FullTransactions variant
76 FullTransactions,
77
78 /// Query matching cached rejected transaction IDs in the mempool,
79 /// using a unique set of [`UnminedTxId`]s.
80 RejectedTransactionIds(HashSet<UnminedTxId>),
81
82 /// Queue a list of gossiped transactions or transaction IDs, or
83 /// crawled transaction IDs.
84 ///
85 /// The transaction downloader checks for duplicates across IDs and transactions.
86 Queue(Vec<Gossip>),
87
88 /// Check for newly verified transactions.
89 ///
90 /// The transaction downloader does not push transactions into the mempool.
91 /// So a task should send this request regularly (every 5-10 seconds).
92 ///
93 /// These checks also happen for other request variants,
94 /// but we can't rely on peers to send queries regularly,
95 /// and crawler queue requests depend on peer responses.
96 /// Also, crawler requests aren't frequent enough for transaction propagation.
97 ///
98 /// # Correctness
99 ///
100 /// This request is required to avoid hangs in the mempool.
101 ///
102 /// The queue checker task can't call `poll_ready` directly on the mempool
103 /// service, because the service is wrapped in a `Buffer`. Calling
104 /// `Buffer::poll_ready` reserves a buffer slot, which can cause hangs
105 /// when too many slots are reserved but unused:
106 /// <https://docs.rs/tower/0.4.10/tower/buffer/struct.Buffer.html#a-note-on-choosing-a-bound>
107 CheckForVerifiedTransactions,
108
109 /// Request summary statistics from the mempool for `getmempoolinfo`.
110 QueueStats,
111
112 /// Check whether a transparent output is spent in the mempool.
113 UnspentOutput(transparent::OutPoint),
114}
115
116/// A response to a mempool service request.
117///
118/// Responses can read the current set of mempool transactions,
119/// check the queued status of transactions to be downloaded and verified, or
120/// confirm that the mempool has been checked for newly verified transactions.
121#[derive(Debug)]
122pub enum Response {
123 /// Returns all [`UnminedTxId`]s from the mempool.
124 TransactionIds(HashSet<UnminedTxId>),
125
126 /// Returns matching [`UnminedTx`] from the mempool.
127 ///
128 /// Since the [`Request::TransactionsById`] request is unique,
129 /// the response transactions are also unique. The same applies to
130 /// [`Request::TransactionsByMinedId`] requests, since the mempool does not allow
131 /// different transactions with different mined IDs.
132 Transactions(Vec<UnminedTx>),
133
134 /// Response to [`Request::AwaitOutput`] with the transparent output
135 UnspentOutput(transparent::Output),
136
137 /// Response to [`Request::TransactionWithDepsByMinedId`].
138 TransactionWithDeps {
139 /// The queried transaction
140 transaction: VerifiedUnminedTx,
141 /// A list of dependencies of the queried transaction.
142 dependencies: HashSet<transaction::Hash>,
143 },
144
145 /// Returns all [`VerifiedUnminedTx`] in the mempool.
146 //
147 // TODO: make the Transactions response return VerifiedUnminedTx,
148 // and remove the FullTransactions variant
149 FullTransactions {
150 /// All [`VerifiedUnminedTx`]s in the mempool
151 transactions: Vec<VerifiedUnminedTx>,
152
153 /// All transaction dependencies in the mempool
154 transaction_dependencies: TransactionDependencies,
155
156 /// Last seen chain tip hash by mempool service
157 last_seen_tip_hash: zebra_chain::block::Hash,
158 },
159
160 /// Returns matching cached rejected [`UnminedTxId`]s from the mempool,
161 RejectedTransactionIds(HashSet<UnminedTxId>),
162
163 /// Returns a list of initial queue checks results and a oneshot receiver
164 /// for awaiting download and/or verification results.
165 ///
166 /// Each result matches the request at the corresponding vector index.
167 Queued(Vec<Result<oneshot::Receiver<Result<(), BoxError>>, BoxError>>),
168
169 /// Confirms that the mempool has checked for recently verified transactions.
170 CheckedForVerifiedTransactions,
171
172 /// Summary statistics for the mempool: count, total size, memory usage, and regtest info.
173 QueueStats {
174 /// Number of transactions currently in the mempool
175 size: usize,
176 /// Total size in bytes of all transactions
177 bytes: usize,
178 /// Estimated memory usage in bytes
179 usage: usize,
180 /// Whether all transactions have been fully notified (regtest only)
181 fully_notified: Option<bool>,
182 },
183
184 /// Returns whether a transparent output is created or spent in the mempool, if present.
185 TransparentOutput(Option<CreatedOrSpent>),
186}
187
188/// Indicates whether an output was created or spent by a mempool transaction.
189#[derive(Debug)]
190pub enum CreatedOrSpent {
191 /// An unspent output that was created by a transaction in the mempool and not spent by any other mempool tx.
192 Created {
193 /// The output
194 output: transparent::Output,
195 /// The version
196 tx_version: u32,
197 /// The last seen hash
198 last_seen_hash: block::Hash,
199 },
200 /// Indicates that an output was spent by a mempool transaction.
201 Spent,
202}