feat(rpc): expose the Ironwood note commitment tree and subtrees

Add the Ironwood read path that mirrors Orchard, so wallets and indexers
can obtain Ironwood frontiers and subtree roots after NU6.3:

- state: ReadRequest/ReadResponse IronwoodTree and IronwoodSubtrees
  variants, read::ironwood_tree / ironwood_subtrees, and the
  ZebraDb::ironwood_tree_by_hash_or_height accessor.
- rpc: an ironwood treestate in z_gettreestate (present from NU6.3), the
  ironwood pool in z_getsubtreesbyindex, and the ironwood tree size in
  verbose getblock. All are skipped/omitted when empty, so pre-NU6.3
  responses and fixtures are unchanged.

Author: upbqdn

zebra-rpc/src/methods.rs

@@ -1304,6 +1304,8 @@ where
                 transactions_request,
                 // Orchard trees
                 zebra_state::ReadRequest::OrchardTree(hash_or_height),
+                // Ironwood trees
+                zebra_state::ReadRequest::IronwoodTree(hash_or_height),
                 // Block info
                 zebra_state::ReadRequest::BlockInfo(previous_block_hash.into()),
                 zebra_state::ReadRequest::BlockInfo(hash_or_height),
@@ -1382,7 +1384,25 @@ where
                 size: orchard_tree_size,
             };
 
-            let trees = GetBlockTrees { sapling, orchard };
+            let ironwood_tree_response = futs.next().await.expect("`futs` should not be empty");
+            let zebra_state::ReadResponse::IronwoodTree(ironwood_tree) =
+                ironwood_tree_response.map_misc_error()?
+            else {
+                unreachable!("unmatched response to an IronwoodTree request");
+            };
+
+            // This could be `None` if there's a chain reorg between state queries. Before NU6.3 the
+            // Ironwood tree is empty (size 0).
+            let ironwood_tree = ironwood_tree.ok_or_misc_error("missing Ironwood tree")?;
+            let ironwood = IronwoodTrees {
+                size: ironwood_tree.count(),
+            };
+
+            let trees = GetBlockTrees {
+                sapling,
+                orchard,
+                ironwood,
+            };
 
             let block_info_response = futs.next().await.expect("`futs` should not be empty");
             let zebra_state::ReadResponse::BlockInfo(prev_block_info) =
@@ -1959,6 +1979,27 @@ where
         let (orchard_tree, orchard_root) =
             orchard.map_or((None, None), |(tree, root)| (Some(tree), Some(root)));
 
+        let ironwood = if network.is_nu_active(consensus::NetworkUpgrade::Nu6_3, height.into()) {
+            match read_state
+                .ready()
+                .and_then(|service| {
+                    service.call(zebra_state::ReadRequest::IronwoodTree(hash.into()))
+                })
+                .await
+                .map_misc_error()?
+            {
+                zebra_state::ReadResponse::IronwoodTree(tree) => {
+                    tree.map(|t| (t.to_rpc_bytes(), t.root().bytes_in_display_order().to_vec()))
+                }
+                _ => unreachable!("unmatched response to an Ironwood tree request"),
+            }
+        } else {
+            None
+        };
+        // Only present from NU6.3, so pre-NU6.3 responses keep the sprout/sapling/orchard shape.
+        let ironwood = ironwood
+            .map(|(tree, root)| Treestate::new(trees::Commitments::new(Some(root), Some(tree))));
+
         Ok(GetTreestateResponse::new(
             hash,
             height,
@@ -1968,6 +2009,7 @@ where
             None,
             Treestate::new(trees::Commitments::new(sapling_root, sapling_tree)),
             Treestate::new(trees::Commitments::new(orchard_root, orchard_tree)),
+            ironwood,
         ))
     }
 
@@ -1979,7 +2021,7 @@ where
     ) -> Result<GetSubtreesByIndexResponse> {
         let mut read_state = self.read_state.clone();
 
-        const POOL_LIST: &[&str] = &["sapling", "orchard"];
+        const POOL_LIST: &[&str] = &["sapling", "orchard", "ironwood"];
 
         if pool == "sapling" {
             let request = zebra_state::ReadRequest::SaplingSubtrees { start_index, limit };
@@ -2020,6 +2062,33 @@ where
                 _ => unreachable!("unmatched response to a subtrees request"),
             };
 
+            let subtrees = subtrees
+                .values()
+                .map(|subtree| SubtreeRpcData {
+                    root: subtree.root.encode_hex(),
+                    end_height: subtree.end_height,
+                })
+                .collect();
+
+            Ok(GetSubtreesByIndexResponse {
+                pool,
+                start_index,
+                subtrees,
+            })
+        } else if pool == "ironwood" {
+            let request = zebra_state::ReadRequest::IronwoodSubtrees { start_index, limit };
+            let response = read_state
+                .ready()
+                .and_then(|service| service.call(request))
+                .await
+                .map_misc_error()?;
+
+            let subtrees = match response {
+                zebra_state::ReadResponse::IronwoodSubtrees(subtrees) => subtrees,
+                _ => unreachable!("unmatched response to a subtrees request"),
+            };
+
+            // Ironwood reuses the Orchard note type, so the subtree root is encoded like Orchard's.
             let subtrees = subtrees
                 .values()
                 .map(|subtree| SubtreeRpcData {
@@ -4372,23 +4441,29 @@ pub struct GetBlockTrees {
     sapling: SaplingTrees,
     #[serde(skip_serializing_if = "OrchardTrees::is_empty")]
     orchard: OrchardTrees,
+    // `default` so responses and fixtures from before Ironwood (which have no `ironwood` field)
+    // still deserialize, as the empty tree.
+    #[serde(default, skip_serializing_if = "IronwoodTrees::is_empty")]
+    ironwood: IronwoodTrees,
 }
 
 impl Default for GetBlockTrees {
     fn default() -> Self {
         GetBlockTrees {
             sapling: SaplingTrees { size: 0 },
             orchard: OrchardTrees { size: 0 },
+            ironwood: IronwoodTrees { size: 0 },
         }
     }
 }
 
 impl GetBlockTrees {
     /// Constructs a new instance of ['GetBlockTrees'].
-    pub fn new(sapling: u64, orchard: u64) -> Self {
+    pub fn new(sapling: u64, orchard: u64, ironwood: u64) -> Self {
         GetBlockTrees {
             sapling: SaplingTrees { size: sapling },
             orchard: OrchardTrees { size: orchard },
+            ironwood: IronwoodTrees { size: ironwood },
         }
     }
 
@@ -4401,6 +4476,11 @@ impl GetBlockTrees {
     pub fn orchard(self) -> u64 {
         self.orchard.size
     }
+
+    /// Returns ironwood data held by ['GetBlockTrees'].
+    pub fn ironwood(self) -> u64 {
+        self.ironwood.size
+    }
 }
 
 /// Sapling note commitment tree information.
@@ -4427,6 +4507,18 @@ impl OrchardTrees {
     }
 }
 
+/// Ironwood note commitment tree information. Ironwood reuses the Orchard tree type.
+#[derive(Copy, Clone, Default, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct IronwoodTrees {
+    size: u64,
+}
+
+impl IronwoodTrees {
+    fn is_empty(&self) -> bool {
+        self.size == 0
+    }
+}
+
 /// Build a valid height range from the given optional start and end numbers.
 ///
 /// # Parameters

zebra-rpc/src/methods/tests/vectors.rs

@@ -281,7 +281,12 @@ async fn rpc_getblock() {
     // Create empty note commitment tree information.
     let sapling = SaplingTrees { size: 0 };
     let orchard = OrchardTrees { size: 0 };
-    let trees = GetBlockTrees { sapling, orchard };
+    let ironwood = IronwoodTrees { size: 0 };
+    let trees = GetBlockTrees {
+        sapling,
+        orchard,
+        ironwood,
+    };
 
     // Make height calls with verbosity=1 and check response
     let mut prev_block_info: Option<BlockInfo> = None;

zebra-rpc/src/methods/trees.rs

@@ -88,6 +88,11 @@ pub struct GetTreestateResponse {
 
     /// A treestate containing an Orchard note commitment tree, hex-encoded.
     orchard: Treestate,
+
+    /// A treestate containing an Ironwood note commitment tree, hex-encoded. Only present from
+    /// NU6.3, so that pre-NU6.3 responses are unchanged.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    ironwood: Option<Treestate>,
 }
 
 impl GetTreestateResponse {
@@ -120,6 +125,7 @@ impl GetTreestateResponse {
             sprout: None,
             sapling,
             orchard,
+            ironwood: None,
         }
     }
 
@@ -145,6 +151,7 @@ impl Default for GetTreestateResponse {
             sprout: Default::default(),
             sapling: Default::default(),
             orchard: Default::default(),
+            ironwood: None,
         }
     }
 }

zebra-rpc/tests/serialization_tests.rs

@@ -240,6 +240,7 @@ fn test_get_block_1() -> Result<(), Box<dyn std::error::Error>> {
     let trees = block.trees();
     let trees_sapling = trees.sapling();
     let trees_orchard = trees.orchard();
+    let trees_ironwood = trees.ironwood();
     // We already tested that GetBlockHash is readable with `hash`, so we don't
     // bother unpacking it here
     let previous_block_hash = block.previous_block_hash();
@@ -269,7 +270,7 @@ fn test_get_block_1() -> Result<(), Box<dyn std::error::Error>> {
         difficulty,
         chain_supply,
         value_pools,
-        GetBlockTrees::new(trees_sapling, trees_orchard),
+        GetBlockTrees::new(trees_sapling, trees_orchard, trees_ironwood),
         previous_block_hash,
         next_block_hash,
     )));
@@ -600,6 +601,7 @@ fn test_z_get_treestate() -> Result<(), Box<dyn std::error::Error>> {
         ))),
         Treestate::new(Commitments::new(sapling_final_root, sapling_final_state)),
         Treestate::new(Commitments::new(orchard_final_root, orchard_final_state)),
+        obj.ironwood().clone(),
     );
 
     assert_eq!(obj, new_obj);

zebra-state/src/request.rs

@@ -1315,6 +1315,15 @@ pub enum ReadRequest {
     /// * [`ReadResponse::OrchardTree(None)`](crate::ReadResponse::OrchardTree) otherwise.
     OrchardTree(HashOrHeight),
 
+    /// Looks up an Ironwood note commitment tree either by a hash or height.
+    ///
+    /// Returns
+    ///
+    /// * [`ReadResponse::IronwoodTree(Some(Arc<NoteCommitmentTree>))`](crate::ReadResponse::IronwoodTree)
+    ///   if the corresponding block contains an Ironwood note commitment tree.
+    /// * [`ReadResponse::IronwoodTree(None)`](crate::ReadResponse::IronwoodTree) otherwise.
+    IronwoodTree(HashOrHeight),
+
     /// Returns a list of Sapling note commitment subtrees by their indexes, starting at
     /// `start_index`, and returning up to `limit` subtrees.
     ///
@@ -1343,6 +1352,20 @@ pub enum ReadRequest {
         limit: Option<NoteCommitmentSubtreeIndex>,
     },
 
+    /// Returns a list of Ironwood note commitment subtrees by their indexes, starting at
+    /// `start_index`, and returning up to `limit` subtrees.
+    ///
+    /// Returns
+    ///
+    /// * [`ReadResponse::IronwoodSubtree(BTreeMap<_, NoteCommitmentSubtreeData<_>>))`](crate::ReadResponse::IronwoodSubtrees)
+    /// * An empty list if there is no subtree at `start_index`.
+    IronwoodSubtrees {
+        /// The index of the first 2^16-leaf subtree to return.
+        start_index: NoteCommitmentSubtreeIndex,
+        /// The maximum number of subtree values to return.
+        limit: Option<NoteCommitmentSubtreeIndex>,
+    },
+
     /// Looks up the balance of a set of transparent addresses.
     ///
     /// Returns an [`Amount`](zebra_chain::amount::Amount) with the total
@@ -1471,8 +1494,10 @@ impl ReadRequest {
             ReadRequest::FindForkPoint { .. } => "find_fork_point",
             ReadRequest::SaplingTree { .. } => "sapling_tree",
             ReadRequest::OrchardTree { .. } => "orchard_tree",
+            ReadRequest::IronwoodTree { .. } => "ironwood_tree",
             ReadRequest::SaplingSubtrees { .. } => "sapling_subtrees",
             ReadRequest::OrchardSubtrees { .. } => "orchard_subtrees",
+            ReadRequest::IronwoodSubtrees { .. } => "ironwood_subtrees",
             ReadRequest::AddressBalance { .. } => "address_balance",
             ReadRequest::TransactionIdsByAddresses { .. } => "transaction_ids_by_addresses",
             ReadRequest::UtxosByAddresses(_) => "utxos_by_addresses",

zebra-state/src/response.rs

@@ -448,6 +448,9 @@ pub enum ReadResponse {
     /// Response to [`ReadRequest::OrchardTree`] with the specified Orchard note commitment tree.
     OrchardTree(Option<Arc<orchard::tree::NoteCommitmentTree>>),
 
+    /// Response to [`ReadRequest::IronwoodTree`] with the specified Ironwood note commitment tree.
+    IronwoodTree(Option<Arc<orchard::tree::NoteCommitmentTree>>),
+
     /// Response to [`ReadRequest::SaplingSubtrees`] with the specified Sapling note commitment
     /// subtrees.
     SaplingSubtrees(
@@ -460,6 +463,12 @@ pub enum ReadResponse {
         BTreeMap<NoteCommitmentSubtreeIndex, NoteCommitmentSubtreeData<orchard::tree::Node>>,
     ),
 
+    /// Response to [`ReadRequest::IronwoodSubtrees`] with the specified Ironwood note commitment
+    /// subtrees. Ironwood reuses the Orchard note type.
+    IronwoodSubtrees(
+        BTreeMap<NoteCommitmentSubtreeIndex, NoteCommitmentSubtreeData<orchard::tree::Node>>,
+    ),
+
     /// Response to [`ReadRequest::AddressBalance`] with the total balance of the addresses,
     /// and the total received funds, including change.
     AddressBalance {
@@ -594,8 +603,10 @@ impl TryFrom<ReadResponse> for Response {
             | ReadResponse::AnyChainTransactionIdsForBlock(_)
             | ReadResponse::SaplingTree(_)
             | ReadResponse::OrchardTree(_)
+            | ReadResponse::IronwoodTree(_)
             | ReadResponse::SaplingSubtrees(_)
             | ReadResponse::OrchardSubtrees(_)
+            | ReadResponse::IronwoodSubtrees(_)
             | ReadResponse::AddressBalance { .. }
             | ReadResponse::AddressesTransactionIds(_)
             | ReadResponse::AddressUtxos(_)

zebra-state/src/service.rs

@@ -1586,6 +1586,10 @@ impl Service<ReadRequest> for ReadStateService {
                 read::orchard_tree(state.latest_best_chain(), &state.db, hash_or_height),
             )),
 
+            ReadRequest::IronwoodTree(hash_or_height) => Ok(ReadResponse::IronwoodTree(
+                read::ironwood_tree(state.latest_best_chain(), &state.db, hash_or_height),
+            )),
+
             ReadRequest::SaplingSubtrees { start_index, limit } => {
                 let end_index = limit
                     .and_then(|limit| start_index.0.checked_add(limit.0))
@@ -1624,6 +1628,25 @@ impl Service<ReadRequest> for ReadStateService {
                 Ok(ReadResponse::OrchardSubtrees(orchard_subtrees))
             }
 
+            ReadRequest::IronwoodSubtrees { start_index, limit } => {
+                let end_index = limit
+                    .and_then(|limit| start_index.0.checked_add(limit.0))
+                    .map(NoteCommitmentSubtreeIndex);
+
+                let best_chain = state.latest_best_chain();
+                let ironwood_subtrees = if let Some(end_index) = end_index {
+                    read::ironwood_subtrees(best_chain, &state.db, start_index..end_index)
+                } else {
+                    // If there is no end bound, just return all the trees.
+                    // If the end bound would overflow, just returns all the trees, because that's what
+                    // `zcashd` does. (It never calculates an end bound, so it just keeps iterating until
+                    // the trees run out.)
+                    read::ironwood_subtrees(best_chain, &state.db, start_index..)
+                };
+
+                Ok(ReadResponse::IronwoodSubtrees(ironwood_subtrees))
+            }
+
             // For the get_address_balance RPC.
             ReadRequest::AddressBalance(addresses) => {
                 let (balance, received) =

zebra-state/src/service/finalized_state/zebra_db/block.rs

@@ -254,6 +254,18 @@ impl ZebraDb {
         self.orchard_tree_by_height(&height)
     }
 
+    /// Returns the Ironwood [`note commitment tree`](orchard::tree::NoteCommitmentTree) specified by
+    /// a hash or height, if it exists in the finalized state.
+    #[allow(clippy::unwrap_in_result)]
+    pub fn ironwood_tree_by_hash_or_height(
+        &self,
+        hash_or_height: HashOrHeight,
+    ) -> Option<Arc<orchard::tree::NoteCommitmentTree>> {
+        let height = hash_or_height.height_or_else(|hash| self.height(hash))?;
+
+        self.ironwood_tree_by_height(&height)
+    }
+
     // Read tip block methods
 
     /// Returns the hash of the current finalized tip block.

zebra-state/src/service/read.rs

@@ -42,7 +42,10 @@ pub use find::{
     find_chain_headers, find_fork_point, hash_by_height, height_by_hash, next_median_time_past,
     non_finalized_state_contains_block_hash, tip, tip_height, tip_with_value_balance,
 };
-pub use tree::{orchard_subtrees, orchard_tree, sapling_subtrees, sapling_tree};
+pub use tree::{
+    ironwood_subtrees, ironwood_tree, orchard_subtrees, orchard_tree, sapling_subtrees,
+    sapling_tree,
+};
 
 #[cfg(any(test, feature = "proptest-impl"))]
 #[allow(unused_imports)]