From 735330618e5ebc2c48518d316af6b46ebfbb7e7d Mon Sep 17 00:00:00 2001
From: teor <teor@riseup.net>
Date: Fri, 1 Sep 2023 02:25:11 +1000
Subject: [PATCH] cleanup(state): Update some outdated comments in the state &
 rpcs (#7434)

* Add a module cleanup TODO

* Fix an unrelated comment

* Update the comments about the bincode legacy format
---
 zebra-rpc/src/methods.rs                                  | 2 +-
 zebra-rpc/src/methods/get_block_template_rpcs.rs          | 2 ++
 .../src/service/finalized_state/disk_format/chain.rs      | 7 +++++++
 .../src/service/finalized_state/disk_format/shielded.rs   | 8 ++++----
 4 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/zebra-rpc/src/methods.rs b/zebra-rpc/src/methods.rs
index 0f9ccd99..f0f17858 100644
--- a/zebra-rpc/src/methods.rs
+++ b/zebra-rpc/src/methods.rs
@@ -124,7 +124,7 @@ pub trait Rpc {
     ///
     /// # Parameters
     ///
-    /// - `hash|height`: (string, required) The hash or height for the block to be returned.
+    /// - `hash | height`: (string, required) The hash or height for the block to be returned.
     /// - `verbosity`: (numeric, optional, default=1) 0 for hex encoded data, 1 for a json object,
     ///     and 2 for json object with transaction data.
     ///
diff --git a/zebra-rpc/src/methods/get_block_template_rpcs.rs b/zebra-rpc/src/methods/get_block_template_rpcs.rs
index cf515cea..4e1ae2c6 100644
--- a/zebra-rpc/src/methods/get_block_template_rpcs.rs
+++ b/zebra-rpc/src/methods/get_block_template_rpcs.rs
@@ -41,6 +41,8 @@ use crate::methods::{
             check_miner_address, check_synced_to_tip, fetch_mempool_transactions,
             fetch_state_tip_and_local_time, validate_block_proposal,
         },
+        // TODO: move the types/* modules directly under get_block_template_rpcs,
+        //       and combine any modules with the same names.
         types::{
             get_block_template::GetBlockTemplate,
             get_mining_info,
diff --git a/zebra-state/src/service/finalized_state/disk_format/chain.rs b/zebra-state/src/service/finalized_state/disk_format/chain.rs
index fb3d4271..df47c595 100644
--- a/zebra-state/src/service/finalized_state/disk_format/chain.rs
+++ b/zebra-state/src/service/finalized_state/disk_format/chain.rs
@@ -31,6 +31,13 @@ impl FromDisk for ValueBalance<NonNegative> {
     }
 }
 
+// The following implementations for history trees use `serde` and
+// `bincode`. `serde` serializations depend on the inner structure of the type.
+// They should not be used in new code. (This is an issue for any derived serialization format.)
+//
+// We explicitly use `bincode::DefaultOptions`  to disallow trailing bytes; see
+// https://docs.rs/bincode/1.3.3/bincode/config/index.html#options-struct-vs-bincode-functions
+
 #[derive(serde::Serialize, serde::Deserialize)]
 struct HistoryTreeParts {
     network: Network,
diff --git a/zebra-state/src/service/finalized_state/disk_format/shielded.rs b/zebra-state/src/service/finalized_state/disk_format/shielded.rs
index 2652de96..e740c56f 100644
--- a/zebra-state/src/service/finalized_state/disk_format/shielded.rs
+++ b/zebra-state/src/service/finalized_state/disk_format/shielded.rs
@@ -96,10 +96,10 @@ impl FromDisk for orchard::tree::Root {
 }
 
 // The following implementations for the note commitment trees use `serde` and
-// `bincode` because currently the inner Merkle tree frontier (from
-// `incrementalmerkletree`) only supports `serde` for serialization. `bincode`
-// was chosen because it is small and fast. We explicitly use `DefaultOptions`
-// in particular to disallow trailing bytes; see
+// `bincode`. `serde` serializations depend on the inner structure of the type.
+// They should not be used in new code. (This is an issue for any derived serialization format.)
+//
+// We explicitly use `bincode::DefaultOptions`  to disallow trailing bytes; see
 // https://docs.rs/bincode/1.3.3/bincode/config/index.html#options-struct-vs-bincode-functions
 
 impl IntoDisk for sprout::tree::NoteCommitmentTree {