zakura-client-backend 0.1.0-rc2

APIs for creating shielded Zcash light clients
Documentation 
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

//! Assembling [ZIP 318] classification evidence from a decrypted transaction.
//!
//! This is the evidence source a wallet uses in production, and the only one that runs against a
//! transaction the wallet did not build. It lives here, in the backend-generic layer, rather than
//! in a store, because [`store_decrypted_tx`] is where the parsed transaction and the decrypted
//! outputs are in hand at the same moment; a store that re-derived the evidence from its own rows
//! would be a second implementation of the predicate to keep in step with this one.
//!
//! What it can observe is weaker than what the same predicate sees on an unproven transaction, for
//! a reason that is inherent rather than incidental: on chain, a zero-valued padding dummy and an
//! unrelated party's output are equally undecryptable, so no amount of work distinguishes them.
//! See [`Zip318Evidence::source_is_send_to_self`] for how the clause weakens, and [`classify`] for
//! why weakening it is sound: it admits more, never less.
//!
//! [ZIP 318]: https://zips.z.cash/zip-0318
//! [`store_decrypted_tx`]: crate::data_api::ll::wallet::store_decrypted_tx
//! [`classify`]: zcash_protocol::zip318::classify
//! [`Zip318Evidence::source_is_send_to_self`]: zcash_protocol::zip318::Zip318Evidence::source_is_send_to_self

use zcash_primitives::transaction::Transaction;
use zcash_protocol::value::Zatoshis;
use zcash_protocol::zip318::{PoolMigrationConstants, Zip318Classification, Zip318Evidence};

use crate::decrypt::{DecryptedOutput, TransferType};

/// Classifies a decrypted transaction against [ZIP 318].
///
/// `orchard_outputs` and `ironwood_outputs` are the outputs the wallet could decrypt, as
/// [`DecryptedTransaction`] reports them; an output absent from both is one the wallet cannot
/// attribute, which is not the same as one belonging to somebody else.
///
/// [ZIP 318]: https://zips.z.cash/zip-0318
/// [`DecryptedTransaction`]: crate::data_api::DecryptedTransaction
#[cfg(feature = "orchard")]
pub fn classify_decrypted_tx<AccountId, C>(
    tx: &Transaction,
    orchard_outputs: &[DecryptedOutput<(orchard::Note, orchard::ValuePool), AccountId>],
    ironwood_outputs: &[DecryptedOutput<(orchard::Note, orchard::ValuePool), AccountId>],
    constants: &C,
) -> Zip318Classification
where
    C: PoolMigrationConstants + ?Sized,
{
    zcash_protocol::zip318::classify(
        &evidence_from_decrypted_tx(tx, orchard_outputs, ironwood_outputs, constants),
        constants,
    )
}

/// The evidence behind [`classify_decrypted_tx`].
#[cfg(feature = "orchard")]
fn evidence_from_decrypted_tx<AccountId, C>(
    tx: &Transaction,
    orchard_outputs: &[DecryptedOutput<(orchard::Note, orchard::ValuePool), AccountId>],
    ironwood_outputs: &[DecryptedOutput<(orchard::Note, orchard::ValuePool), AccountId>],
    constants: &C,
) -> Zip318Evidence
where
    C: PoolMigrationConstants + ?Sized,
{
    // The expiry clause takes the height-independent form, deliberately. The reference-height form
    // cannot be evaluated before the transaction is mined, and judging it against the chain tip
    // instead would let the answer change once the transaction was mined in a later modulus period,
    // contradicting a decision already recorded.
    //
    // Neither confirmatory clause is answerable here, so both are left unanswered. Resolving the
    // anchor to a height needs the wallet's retained boundary checkpoints, and the fee needs the
    // value of inputs the wallet may not own; a store that has both may answer them and narrow the
    // result.
    Zip318Evidence::default()
        .with_source_actions(Some(action_count(
            tx.orchard_bundle().map(|b| b.actions().len()),
        )))
        .with_destination_actions(Some(action_count(
            tx.ironwood_bundle().map(|b| b.actions().len()),
        )))
        .with_other_bundles_present(Some(other_bundles_present(tx)))
        .with_source_is_send_to_self(Some(is_send_to_self(orchard_outputs)))
        .with_sole_destination_value(sole_destination_value(ironwood_outputs))
        .with_expiry_is_canonical(Some(
            constants.is_canonical_expiry_value(tx.expiry_height()),
        ))
}

/// An absent bundle contributes no actions, which is what a preparation transaction's destination
/// pool looks like.
#[cfg(feature = "orchard")]
fn action_count(bundle_actions: Option<usize>) -> usize {
    bundle_actions.unwrap_or(0)
}

/// Whether the transaction carries a transparent or Sapling bundle. No ZIP 318 transaction carries
/// either, so this is a refutation on its own.
#[cfg(feature = "orchard")]
fn other_bundles_present(tx: &Transaction) -> bool {
    tx.transparent_bundle()
        .is_some_and(|b| !b.vin.is_empty() || !b.vout.is_empty())
        || tx
            .sapling_bundle()
            .is_some_and(|b| !b.shielded_spends().is_empty() || !b.shielded_outputs().is_empty())
}

/// Whether the source-pool outputs are consistent with a send-to-self.
///
/// This is the weakened clause described in the module documentation. It cannot be "every
/// value-carrying output is internal", because the outputs the wallet cannot decrypt are exactly
/// the ones it cannot classify, and a padding dummy is one of those. What it can say is that the
/// wallet received something on its own internal address here and received nothing on an external
/// one, which is the strongest sound reading available from chain data.
#[cfg(feature = "orchard")]
fn is_send_to_self<AccountId>(
    orchard_outputs: &[DecryptedOutput<(orchard::Note, orchard::ValuePool), AccountId>],
) -> bool {
    let mut any_internal = false;
    for output in orchard_outputs {
        match output.transfer_type() {
            TransferType::AccountInternal => any_internal = true,
            // An output on one of the account's own external addresses, or one the wallet sent to
            // somebody else, both mean this is not a send-to-self.
            TransferType::Incoming | TransferType::Outgoing | TransferType::WalletInternal => {
                return false;
            }
        }
    }
    any_internal
}

/// The value of the sole destination-pool output, when the wallet can attribute exactly one.
///
/// A crossing the wallet cannot decrypt at all yields `None` (unknown), not a refutation: a
/// stranger's canonical crossing is invisible here, and claiming otherwise would be a judgement on
/// evidence we do not have.
#[cfg(feature = "orchard")]
fn sole_destination_value<AccountId>(
    ironwood_outputs: &[DecryptedOutput<(orchard::Note, orchard::ValuePool), AccountId>],
) -> Option<Zatoshis> {
    let [output] = ironwood_outputs else {
        return None;
    };

    let (note, _pool) = output.note();

    Zatoshis::from_u64(note.value().inner()).ok()
}