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}