cuprate_txpool/service/
interface.rs

Help
1//! Tx-pool [`service`](super) interface.
2//!
3//! This module contains `cuprate_txpool`'s [`tower::Service`] request and response enums.
4
5use std::{
6    collections::{HashMap, HashSet},
7    num::NonZero,
8};
9
10use cuprate_types::{
11    rpc::{PoolInfo, SpentKeyImageInfo, TxInfo, TxpoolStats},
12    TransactionVerificationData, TxInPool,
13};
14
15use crate::{
16    tx::TxEntry,
17    types::{KeyImage, TransactionBlobHash, TransactionHash},
18};
19
20//---------------------------------------------------------------------------------------------------- TxpoolReadRequest
21/// The transaction pool [`tower::Service`] read request type.
22///
23/// ### `include_sensitive_txs`
24/// This field exists in many requests.
25/// If this is [`true`], the request will include private (local) transactions in the response.
26#[derive(Clone)]
27pub enum TxpoolReadRequest {
28    /// Get the blob (raw bytes) of a transaction with the given hash.
29    TxBlob(TransactionHash),
30
31    /// Get the [`TransactionVerificationData`] of a transaction in the tx pool.
32    TxVerificationData(TransactionHash),
33
34    /// Filter (remove) all **known** transactions from the set.
35    ///
36    /// The hash is **not** the transaction hash, it is the hash of the serialized tx-blob.
37    FilterKnownTxBlobHashes(HashSet<TransactionBlobHash>),
38
39    /// Get some transactions for an incoming block.
40    TxsForBlock(Vec<TransactionHash>),
41
42    /// Get information on all transactions in the pool.
43    Backlog,
44
45    /// Get the number of transactions in the pool.
46    Size { include_sensitive_txs: bool },
47
48    /// Get general information on the txpool.
49    PoolInfo {
50        include_sensitive_txs: bool,
51        /// The maximum amount of transactions to retrieve.
52        max_tx_count: usize,
53        /// Fetch transactions that start from this time.
54        ///
55        /// [`None`] means all transactions.
56        start_time: Option<NonZero<usize>>,
57    },
58
59    /// Get transactions by their hashes.
60    TxsByHash {
61        tx_hashes: Vec<[u8; 32]>,
62        include_sensitive_txs: bool,
63    },
64
65    /// Check if any individual key images of a set exist in the txpool.
66    KeyImagesSpent {
67        key_images: HashSet<[u8; 32]>,
68        include_sensitive_txs: bool,
69    },
70
71    /// Same as [`TxpoolReadRequest::KeyImagesSpent`] but with a [`Vec`].
72    ///
73    /// The response will be in the same order as the request.
74    KeyImagesSpentVec {
75        key_images: Vec<[u8; 32]>,
76        include_sensitive_txs: bool,
77    },
78
79    /// Get txpool info.
80    Pool { include_sensitive_txs: bool },
81
82    /// Get txpool stats.
83    PoolStats { include_sensitive_txs: bool },
84
85    /// Get the hashes of all transaction in the pool.
86    AllHashes { include_sensitive_txs: bool },
87}
88
89//---------------------------------------------------------------------------------------------------- TxpoolReadResponse
90/// The transaction pool [`tower::Service`] read response type.
91#[expect(clippy::large_enum_variant)]
92pub enum TxpoolReadResponse {
93    /// The response for [`TxpoolReadRequest::TxBlob`].
94    TxBlob { tx_blob: Vec<u8>, state_stem: bool },
95
96    /// The response for [`TxpoolReadRequest::TxVerificationData`].
97    TxVerificationData(TransactionVerificationData),
98
99    /// The response for [`TxpoolReadRequest::FilterKnownTxBlobHashes`].
100    FilterKnownTxBlobHashes {
101        /// The blob hashes that are unknown.
102        unknown_blob_hashes: HashSet<TransactionBlobHash>,
103        /// The tx hashes of the blob hashes that were known but were in the stem pool.
104        stem_pool_hashes: Vec<TransactionHash>,
105    },
106
107    /// The response for [`TxpoolReadRequest::TxsForBlock`].
108    TxsForBlock {
109        /// The txs we had in the txpool.
110        txs: HashMap<[u8; 32], TransactionVerificationData>,
111        /// The indexes of the missing txs.
112        missing: Vec<usize>,
113    },
114
115    /// Response to [`TxpoolReadRequest::Backlog`].
116    ///
117    /// The inner [`Vec`] contains information on all
118    /// the transactions currently in the pool.
119    Backlog(Vec<TxEntry>),
120
121    /// Response to [`TxpoolReadRequest::Size`].
122    ///
123    /// The inner value is the amount of
124    /// transactions currently in the pool.
125    Size(usize),
126
127    /// Response to [`TxpoolReadRequest::PoolInfo`].
128    PoolInfo(PoolInfo),
129
130    /// Response to [`TxpoolReadRequest::TxsByHash`].
131    TxsByHash(Vec<TxInPool>),
132
133    /// Response to [`TxpoolReadRequest::KeyImagesSpent`].
134    KeyImagesSpent(bool),
135
136    /// Response to [`TxpoolReadRequest::KeyImagesSpentVec`].
137    ///
138    /// Inner value is a `Vec` the same length as the input.
139    ///
140    /// The index of each entry corresponds with the request.
141    /// `true` means that the key image was spent.
142    KeyImagesSpentVec(Vec<bool>),
143
144    /// Response to [`TxpoolReadRequest::Pool`].
145    Pool {
146        txs: Vec<TxInfo>,
147        spent_key_images: Vec<SpentKeyImageInfo>,
148    },
149
150    /// Response to [`TxpoolReadRequest::PoolStats`].
151    PoolStats(TxpoolStats),
152
153    /// Response to [`TxpoolReadRequest::AllHashes`].
154    AllHashes(Vec<[u8; 32]>),
155}
156
157//---------------------------------------------------------------------------------------------------- TxpoolWriteRequest
158/// The transaction pool [`tower::Service`] write request type.
159#[derive(Clone)]
160pub enum TxpoolWriteRequest {
161    /// Add a transaction to the pool.
162    ///
163    /// Returns [`TxpoolWriteResponse::AddTransaction`].
164    AddTransaction {
165        /// The tx to add.
166        tx: Box<TransactionVerificationData>,
167        /// A [`bool`] denoting the routing state of this tx.
168        ///
169        /// [`true`] if this tx is in the stem state.
170        state_stem: bool,
171    },
172
173    /// Remove a transaction with the given hash from the pool.
174    RemoveTransaction(TransactionHash),
175
176    /// Promote a transaction from the stem pool to the fluff pool.
177    /// If the tx is already in the fluff pool this does nothing.
178    Promote(TransactionHash),
179
180    /// Tell the tx-pool about a new block.
181    NewBlock {
182        /// The spent key images in the new block.
183        spent_key_images: Vec<KeyImage>,
184    },
185}
186
187//---------------------------------------------------------------------------------------------------- TxpoolWriteResponse
188/// The transaction pool [`tower::Service`] write response type.
189#[derive(Clone, Debug, Ord, PartialOrd, Eq, PartialEq)]
190pub enum TxpoolWriteResponse {
191    /// Response to:
192    /// - [`TxpoolWriteRequest::RemoveTransaction`]
193    /// - [`TxpoolWriteRequest::Promote`]
194    /// - [`TxpoolWriteRequest::NewBlock`]
195    Ok,
196
197    /// Response to [`TxpoolWriteRequest::AddTransaction`].
198    ///
199    /// If the inner value is [`Some`] the tx was not added to the pool as it double spends a tx with the given hash.
200    AddTransaction(Option<TransactionHash>),
201}
cuprate_txpool/service/interface.rs

cuprate_txpool/service/
interface.rs
