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
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
//! Unmined Zcash transaction identifiers and transactions.
//!
//! Transaction version 5 is uniquely identified by [`WtxId`] when unmined, and
//! [`struct@Hash`] in the blockchain. The effects of a v5 transaction
//! (spends and outputs) are uniquely identified by the same
//! [`struct@Hash`] in both cases.
//!
//! Transaction versions 1-4 are uniquely identified by legacy
//! [`struct@Hash`] transaction IDs, whether they have been mined or not.
//! So Zebra, and the Zcash network protocol, don't use witnessed transaction
//! IDs for them.
//!
//! Zebra's [`UnminedTxId`] and [`UnminedTx`] enums provide the correct unique
//! ID for unmined transactions. They can be used to handle transactions
//! regardless of version, and get the [`WtxId`] or [`struct@Hash`] when
//! required.

use std::{fmt, sync::Arc};

use crate::{
    amount::{Amount, NonNegative},
    serialization::ZcashSerialize,
    transaction::{
        AuthDigest, Hash,
        Transaction::{self, *},
        WtxId,
    },
};

use UnminedTxId::*;

#[cfg(any(test, feature = "proptest-impl"))]
use proptest_derive::Arbitrary;

mod zip317;

/// The minimum cost value for a transaction in the mempool.
///
/// Contributes to the randomized, weighted eviction of transactions from the
/// mempool when it reaches a max size, also based on the total cost.
///
/// > Each transaction has a cost, which is an integer defined as:
/// >
/// > max(serialized transaction size in bytes, 4000)
/// >
/// > The threshold 4000 for the cost function is chosen so that the size in bytes
/// > of a typical fully shielded Sapling transaction (with, say, 2 shielded outputs
/// > and up to 5 shielded inputs) will fall below the threshold. This has the effect
/// > of ensuring that such transactions are not evicted preferentially to typical
/// > transparent transactions because of their size.
///
/// [ZIP-401]: https://zips.z.cash/zip-0401
const MEMPOOL_TRANSACTION_COST_THRESHOLD: u64 = 4000;

/// When a transaction pays a fee less than the conventional fee,
/// this low fee penalty is added to its cost for mempool eviction.
///
/// See [VerifiedUnminedTx::eviction_weight()] for details.
const MEMPOOL_TRANSACTION_LOW_FEE_PENALTY: u64 = 16_000;

/// A unique identifier for an unmined transaction, regardless of version.
///
/// "The transaction ID of a version 4 or earlier transaction is the SHA-256d hash
/// of the transaction encoding in the pre-v5 format described above.
///
/// The transaction ID of a version 5 transaction is as defined in [ZIP-244].
///
/// A v5 transaction also has a wtxid (used for example in the peer-to-peer protocol)
/// as defined in [ZIP-239]."
/// [Spec: Transaction Identifiers]
///
/// [ZIP-239]: https://zips.z.cash/zip-0239
/// [ZIP-244]: https://zips.z.cash/zip-0244
/// [Spec: Transaction Identifiers]: https://zips.z.cash/protocol/protocol.pdf#txnidentifiers
#[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
#[cfg_attr(any(test, feature = "proptest-impl"), derive(Arbitrary))]
pub enum UnminedTxId {
    /// A legacy unmined transaction identifier.
    ///
    /// Used to uniquely identify unmined version 1-4 transactions.
    /// (After v1-4 transactions are mined, they can be uniquely identified
    /// using the same [`struct@Hash`].)
    Legacy(Hash),

    /// A witnessed unmined transaction identifier.
    ///
    /// Used to uniquely identify unmined version 5 transactions.
    /// (After v5 transactions are mined, they can be uniquely identified
    /// using only the [`struct@Hash`] in their `WtxId.id`.)
    ///
    /// For more details, see [`WtxId`].
    Witnessed(WtxId),
}

impl From<Transaction> for UnminedTxId {
    fn from(transaction: Transaction) -> Self {
        // use the ref implementation, to avoid cloning the transaction
        UnminedTxId::from(&transaction)
    }
}

impl From<&Transaction> for UnminedTxId {
    fn from(transaction: &Transaction) -> Self {
        match transaction {
            V1 { .. } | V2 { .. } | V3 { .. } | V4 { .. } => Legacy(transaction.into()),
            V5 { .. } => Witnessed(transaction.into()),
        }
    }
}

impl From<Arc<Transaction>> for UnminedTxId {
    fn from(transaction: Arc<Transaction>) -> Self {
        transaction.as_ref().into()
    }
}

impl From<WtxId> for UnminedTxId {
    fn from(wtx_id: WtxId) -> Self {
        Witnessed(wtx_id)
    }
}

impl From<&WtxId> for UnminedTxId {
    fn from(wtx_id: &WtxId) -> Self {
        (*wtx_id).into()
    }
}

impl fmt::Display for UnminedTxId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Legacy(hash) => hash.fmt(f),
            Witnessed(id) => id.fmt(f),
        }
    }
}

impl UnminedTxId {
    /// Create a new [`UnminedTxId`] using a v1-v4 legacy transaction ID.
    ///
    /// # Correctness
    ///
    /// This method must only be used for v1-v4 transaction IDs.
    /// [`struct@Hash`] does not uniquely identify unmined v5
    /// transactions.
    pub fn from_legacy_id(legacy_tx_id: Hash) -> UnminedTxId {
        Legacy(legacy_tx_id)
    }

    /// Return the unique ID that will be used if this transaction gets mined into a block.
    ///
    /// # Correctness
    ///
    /// For v1-v4 transactions, this method returns an ID which changes
    /// if this transaction's effects (spends and outputs) change, or
    /// if its authorizing data changes (signatures, proofs, and scripts).
    ///
    /// But for v5 transactions, this ID uniquely identifies the transaction's effects.
    pub fn mined_id(&self) -> Hash {
        match self {
            Legacy(legacy_id) => *legacy_id,
            Witnessed(wtx_id) => wtx_id.id,
        }
    }

    /// Returns a mutable reference to the unique ID
    /// that will be used if this transaction gets mined into a block.
    ///
    /// See [`Self::mined_id`] for details.
    #[cfg(any(test, feature = "proptest-impl"))]
    pub fn mined_id_mut(&mut self) -> &mut Hash {
        match self {
            Legacy(legacy_id) => legacy_id,
            Witnessed(wtx_id) => &mut wtx_id.id,
        }
    }

    /// Return the digest of this transaction's authorizing data,
    /// (signatures, proofs, and scripts), if it is a v5 transaction.
    pub fn auth_digest(&self) -> Option<AuthDigest> {
        match self {
            Legacy(_) => None,
            Witnessed(wtx_id) => Some(wtx_id.auth_digest),
        }
    }

    /// Returns a mutable reference to the digest of this transaction's authorizing data,
    /// (signatures, proofs, and scripts), if it is a v5 transaction.
    #[cfg(any(test, feature = "proptest-impl"))]
    pub fn auth_digest_mut(&mut self) -> Option<&mut AuthDigest> {
        match self {
            Legacy(_) => None,
            Witnessed(wtx_id) => Some(&mut wtx_id.auth_digest),
        }
    }
}

/// An unmined transaction, and its pre-calculated unique identifying ID.
///
/// This transaction has been structurally verified.
/// (But it might still need semantic or contextual verification.)
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct UnminedTx {
    /// The unmined transaction itself.
    pub transaction: Arc<Transaction>,

    /// A unique identifier for this unmined transaction.
    pub id: UnminedTxId,

    /// The size in bytes of the serialized transaction data
    pub size: usize,

    /// The conventional fee for this transaction, as defined by [ZIP-317].
    ///
    /// [ZIP-317]: https://zips.z.cash/zip-0317#fee-calculation
    pub conventional_fee: Amount<NonNegative>,
}

impl fmt::Display for UnminedTx {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("UnminedTx")
            .field("transaction", &self.transaction)
            .field("serialized_size", &self.size)
            .field("conventional_fee", &self.conventional_fee)
            .finish()
    }
}

// Each of these conversions is implemented slightly differently,
// to avoid cloning the transaction where possible.

impl From<Transaction> for UnminedTx {
    fn from(transaction: Transaction) -> Self {
        let size = transaction.zcash_serialized_size();
        let conventional_fee = zip317::conventional_fee(&transaction);

        // The borrow is actually needed to avoid taking ownership
        #[allow(clippy::needless_borrow)]
        Self {
            id: (&transaction).into(),
            size,
            conventional_fee,
            transaction: Arc::new(transaction),
        }
    }
}

impl From<&Transaction> for UnminedTx {
    fn from(transaction: &Transaction) -> Self {
        let size = transaction.zcash_serialized_size();
        let conventional_fee = zip317::conventional_fee(transaction);

        Self {
            id: transaction.into(),
            size,
            conventional_fee,
            transaction: Arc::new(transaction.clone()),
        }
    }
}

impl From<Arc<Transaction>> for UnminedTx {
    fn from(transaction: Arc<Transaction>) -> Self {
        let size = transaction.zcash_serialized_size();
        let conventional_fee = zip317::conventional_fee(&transaction);

        Self {
            id: transaction.as_ref().into(),
            size,
            conventional_fee,
            transaction,
        }
    }
}

impl From<&Arc<Transaction>> for UnminedTx {
    fn from(transaction: &Arc<Transaction>) -> Self {
        let size = transaction.zcash_serialized_size();
        let conventional_fee = zip317::conventional_fee(transaction);

        Self {
            id: transaction.as_ref().into(),
            size,
            conventional_fee,
            transaction: transaction.clone(),
        }
    }
}

/// A verified unmined transaction, and the corresponding transaction fee.
///
/// This transaction has been fully verified, in the context of the mempool.
#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(any(test, feature = "proptest-impl"), derive(Arbitrary))]
pub struct VerifiedUnminedTx {
    /// The unmined transaction.
    pub transaction: UnminedTx,

    /// The transaction fee for this unmined transaction.
    pub miner_fee: Amount<NonNegative>,

    /// The number of legacy signature operations in this transaction's
    /// transparent inputs and outputs.
    pub legacy_sigop_count: u64,
}

impl fmt::Display for VerifiedUnminedTx {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("VerifiedUnminedTx")
            .field("transaction", &self.transaction)
            .field("miner_fee", &self.miner_fee)
            .field("legacy_sigop_count", &self.legacy_sigop_count)
            .finish()
    }
}

impl VerifiedUnminedTx {
    /// Create a new verified unmined transaction from a transaction, its fee and the legacy sigop count.
    pub fn new(
        transaction: UnminedTx,
        miner_fee: Amount<NonNegative>,
        legacy_sigop_count: u64,
    ) -> Self {
        Self {
            transaction,
            miner_fee,
            legacy_sigop_count,
        }
    }

    /// The cost in bytes of the transaction, as defined in [ZIP-401].
    ///
    /// A reflection of the work done by the network in processing them (proof
    /// and signature verification; networking overheads; size of in-memory data
    /// structures).
    ///
    /// > Each transaction has a cost, which is an integer defined as:
    /// >
    /// > max(serialized transaction size in bytes, 4000)
    ///
    /// [ZIP-401]: https://zips.z.cash/zip-0401
    pub fn cost(&self) -> u64 {
        std::cmp::max(
            u64::try_from(self.transaction.size).expect("fits in u64"),
            MEMPOOL_TRANSACTION_COST_THRESHOLD,
        )
    }

    /// The computed _eviction weight_ of a verified unmined transaction as part
    /// of the mempool set, as defined in [ZIP-317] and [ZIP-401].
    ///
    /// Standard rule:
    ///
    /// > Each transaction also has an eviction weight, which is cost +
    /// > low_fee_penalty, where low_fee_penalty is 16000 if the transaction pays
    /// > a fee less than the conventional fee, otherwise 0.
    ///
    /// > zcashd and zebrad limit the size of the mempool as described in [ZIP-401].
    /// > This specifies a low fee penalty that is added to the "eviction weight" if the transaction
    /// > pays a fee less than the conventional transaction fee. This threshold is
    /// > modified to use the new conventional fee formula.
    ///
    /// [ZIP-317]: https://zips.z.cash/zip-0317#mempool-size-limiting
    /// [ZIP-401]: https://zips.z.cash/zip-0401
    pub fn eviction_weight(&self) -> u64 {
        let mut cost = self.cost();

        if self.miner_fee < self.transaction.conventional_fee {
            cost += MEMPOOL_TRANSACTION_LOW_FEE_PENALTY
        }

        cost
    }
}