zebra_rpc/methods/
trees.rs

1//! Types and functions for note commitment tree RPCs.
2
3use derive_getters::Getters;
4use derive_new::new;
5use zebra_chain::{
6    block::Hash,
7    block::Height,
8    subtree::{NoteCommitmentSubtreeData, NoteCommitmentSubtreeIndex},
9};
10
11/// A subtree data type that can hold Sapling or Orchard subtree roots.
12pub type SubtreeRpcData = NoteCommitmentSubtreeData<String>;
13
14/// Response to a `z_getsubtreesbyindex` RPC request.
15///
16/// Contains the Sapling or Orchard pool label, the index of the first subtree in the list,
17/// and a list of subtree roots and end heights.
18#[derive(Clone, Debug, Eq, PartialEq, serde::Serialize, serde::Deserialize, Getters, new)]
19pub struct GetSubtreesByIndexResponse {
20    /// The shielded pool to which the subtrees belong.
21    //
22    // TODO: consider an enum with a string conversion?
23    pub(crate) pool: String,
24
25    /// The index of the first subtree.
26    #[getter(copy)]
27    pub(crate) start_index: NoteCommitmentSubtreeIndex,
28
29    /// A sequential list of complete subtrees, in `index` order.
30    ///
31    /// The generic subtree root type is a hex-encoded Sapling or Orchard subtree root string.
32    //
33    // TODO: is this needed?
34    //#[serde(skip_serializing_if = "Vec::is_empty")]
35    pub(crate) subtrees: Vec<SubtreeRpcData>,
36}
37
38impl Default for GetSubtreesByIndexResponse {
39    fn default() -> Self {
40        Self {
41            pool: "sapling | orchard".to_string(),
42            start_index: NoteCommitmentSubtreeIndex(u16::default()),
43            subtrees: vec![],
44        }
45    }
46}
47
48/// Response to a `z_gettreestate` RPC request.
49///
50/// Contains hex-encoded Sapling & Orchard note commitment trees and their corresponding
51/// [`struct@Hash`], [`Height`], and block time.
52///
53/// The format of the serialized trees represents `CommitmentTree`s from the crate
54/// `incrementalmerkletree` and not `Frontier`s from the same crate, even though `zebrad`'s
55/// `NoteCommitmentTree`s are implemented using `Frontier`s. Zebra follows the former format to stay
56/// consistent with `zcashd`'s RPCs.
57///
58/// The formats are semantically equivalent. The difference is that in `Frontier`s, the vector of
59/// ommers is dense (we know where the gaps are from the position of the leaf in the overall tree);
60/// whereas in `CommitmentTree`, the vector of ommers is sparse with [`None`] values in the gaps.
61///
62/// The dense format might be used in future RPCs.
63#[derive(Clone, Debug, Eq, PartialEq, serde::Serialize, serde::Deserialize, Getters, new)]
64pub struct GetTreestateResponse {
65    /// The block hash corresponding to the treestate, hex-encoded.
66    #[serde(with = "hex")]
67    #[getter(copy)]
68    hash: Hash,
69
70    /// The block height corresponding to the treestate, numeric.
71    #[getter(copy)]
72    height: Height,
73
74    /// Unix time when the block corresponding to the treestate was mined,
75    /// numeric.
76    ///
77    /// UTC seconds since the Unix 1970-01-01 epoch.
78    time: u32,
79
80    /// A treestate containing a Sapling note commitment tree, hex-encoded.
81    sapling: Treestate,
82
83    /// A treestate containing an Orchard note commitment tree, hex-encoded.
84    orchard: Treestate,
85}
86
87impl GetTreestateResponse {
88    /// Constructs [`Treestate`] from its constituent parts.
89    pub fn from_parts(
90        hash: Hash,
91        height: Height,
92        time: u32,
93        sapling: Option<Vec<u8>>,
94        orchard: Option<Vec<u8>>,
95    ) -> Self {
96        let sapling = Treestate {
97            commitments: Commitments {
98                final_state: sapling,
99            },
100        };
101        let orchard = Treestate {
102            commitments: Commitments {
103                final_state: orchard,
104            },
105        };
106
107        Self {
108            hash,
109            height,
110            time,
111            sapling,
112            orchard,
113        }
114    }
115
116    /// Returns the contents of ['GetTreeState'].
117    pub fn into_parts(self) -> (Hash, Height, u32, Option<Vec<u8>>, Option<Vec<u8>>) {
118        (
119            self.hash,
120            self.height,
121            self.time,
122            self.sapling.commitments.final_state,
123            self.orchard.commitments.final_state,
124        )
125    }
126}
127
128impl Default for GetTreestateResponse {
129    fn default() -> Self {
130        Self {
131            hash: Hash([0; 32]),
132            height: Height::MIN,
133            time: Default::default(),
134            sapling: Default::default(),
135            orchard: Default::default(),
136        }
137    }
138}
139
140/// A treestate that is included in the [`z_gettreestate`][1] RPC response.
141///
142/// [1]: https://zcash.github.io/rpc/z_gettreestate.html
143#[derive(Clone, Debug, Eq, PartialEq, serde::Serialize, serde::Deserialize, Getters, new)]
144pub struct Treestate {
145    /// Contains an Orchard or Sapling serialized note commitment tree,
146    /// hex-encoded.
147    commitments: Commitments,
148}
149
150impl Treestate {
151    /// Returns a reference to the commitments.
152    #[deprecated(note = "Use `commitments()` instead.")]
153    pub fn inner(&self) -> &Commitments {
154        self.commitments()
155    }
156}
157
158impl Default for Treestate {
159    fn default() -> Self {
160        Self {
161            commitments: Commitments { final_state: None },
162        }
163    }
164}
165
166/// A wrapper that contains either an Orchard or Sapling note commitment tree.
167///
168/// Note that in the original [`z_gettreestate`][1] RPC, [`Commitments`] also
169/// contains the field `finalRoot`. Zebra does *not* use this field.
170///
171/// [1]: https://zcash.github.io/rpc/z_gettreestate.html
172#[serde_with::serde_as]
173#[derive(Clone, Debug, Eq, PartialEq, serde::Serialize, serde::Deserialize, Getters, new)]
174pub struct Commitments {
175    /// Orchard or Sapling serialized note commitment tree, hex-encoded.
176    #[serde_as(as = "Option<serde_with::hex::Hex>")]
177    #[serde(skip_serializing_if = "Option::is_none")]
178    #[serde(rename = "finalState")]
179    final_state: Option<Vec<u8>>,
180}
181
182impl Commitments {
183    /// Returns a reference to the optional `final_state`.
184    #[deprecated(note = "Use `final_state()` instead.")]
185    pub fn inner(&self) -> &Option<Vec<u8>> {
186        &self.final_state
187    }
188}