cuprate_txpool/service/
interface.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
//! Tx-pool [`service`](super) interface.
//!
//! This module contains `cuprate_txpool`'s [`tower::Service`] request and response enums.
use std::{
    collections::{HashMap, HashSet},
    sync::Arc,
};

use cuprate_types::TransactionVerificationData;

use crate::{
    tx::TxEntry,
    types::{KeyImage, TransactionBlobHash, TransactionHash},
};

//---------------------------------------------------------------------------------------------------- TxpoolReadRequest
/// The transaction pool [`tower::Service`] read request type.
#[derive(Clone)]
pub enum TxpoolReadRequest {
    /// Get the blob (raw bytes) of a transaction with the given hash.
    TxBlob(TransactionHash),

    /// Get the [`TransactionVerificationData`] of a transaction in the tx pool.
    TxVerificationData(TransactionHash),

    /// Filter (remove) all **known** transactions from the set.
    ///
    /// The hash is **not** the transaction hash, it is the hash of the serialized tx-blob.
    FilterKnownTxBlobHashes(HashSet<TransactionBlobHash>),

    /// Get some transactions for an incoming block.
    TxsForBlock(Vec<TransactionHash>),

    /// Get information on all transactions in the pool.
    Backlog,

    /// Get the number of transactions in the pool.
    Size {
        /// If this is [`true`], the size returned will
        /// include private transactions in the pool.
        include_sensitive_txs: bool,
    },
}

//---------------------------------------------------------------------------------------------------- TxpoolReadResponse
/// The transaction pool [`tower::Service`] read response type.
#[expect(clippy::large_enum_variant)]
pub enum TxpoolReadResponse {
    /// The response for [`TxpoolReadRequest::TxBlob`].
    TxBlob { tx_blob: Vec<u8>, state_stem: bool },

    /// The response for [`TxpoolReadRequest::TxVerificationData`].
    TxVerificationData(TransactionVerificationData),

    /// The response for [`TxpoolReadRequest::FilterKnownTxBlobHashes`].
    FilterKnownTxBlobHashes {
        /// The blob hashes that are unknown.
        unknown_blob_hashes: HashSet<TransactionBlobHash>,
        /// The tx hashes of the blob hashes that were known but were in the stem pool.
        stem_pool_hashes: Vec<TransactionHash>,
    },

    /// The response for [`TxpoolReadRequest::TxsForBlock`].
    TxsForBlock {
        /// The txs we had in the txpool.
        txs: HashMap<[u8; 32], TransactionVerificationData>,
        /// The indexes of the missing txs.
        missing: Vec<usize>,
    },

    /// Response to [`TxpoolReadRequest::Backlog`].
    ///
    /// The inner [`Vec`] contains information on all
    /// the transactions currently in the pool.
    Backlog(Vec<TxEntry>),

    /// Response to [`TxpoolReadRequest::Size`].
    ///
    /// The inner value is the amount of
    /// transactions currently in the pool.
    Size(usize),
}

//---------------------------------------------------------------------------------------------------- TxpoolWriteRequest
/// The transaction pool [`tower::Service`] write request type.
#[derive(Clone)]
pub enum TxpoolWriteRequest {
    /// Add a transaction to the pool.
    ///
    /// Returns [`TxpoolWriteResponse::AddTransaction`].
    AddTransaction {
        /// The tx to add.
        tx: Arc<TransactionVerificationData>,
        /// A [`bool`] denoting the routing state of this tx.
        ///
        /// [`true`] if this tx is in the stem state.
        state_stem: bool,
    },

    /// Remove a transaction with the given hash from the pool.
    RemoveTransaction(TransactionHash),

    /// Promote a transaction from the stem pool to the fluff pool.
    /// If the tx is already in the fluff pool this does nothing.
    Promote(TransactionHash),

    /// Tell the tx-pool about a new block.
    NewBlock {
        /// The spent key images in the new block.
        spent_key_images: Vec<KeyImage>,
    },
}

//---------------------------------------------------------------------------------------------------- TxpoolWriteResponse
/// The transaction pool [`tower::Service`] write response type.
#[derive(Clone, Debug, Ord, PartialOrd, Eq, PartialEq)]
pub enum TxpoolWriteResponse {
    /// Response to:
    /// - [`TxpoolWriteRequest::RemoveTransaction`]
    /// - [`TxpoolWriteRequest::Promote`]
    /// - [`TxpoolWriteRequest::NewBlock`]
    Ok,

    /// Response to [`TxpoolWriteRequest::AddTransaction`].
    ///
    /// If the inner value is [`Some`] the tx was not added to the pool as it double spends a tx with the given hash.
    AddTransaction(Option<TransactionHash>),
}