Apply documentation suggestions from code review.

Co-authored-by: Kris Nuttycombe <kris@nutty.land>
Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>

zcash_client_backend/CHANGELOG.md

@@ -9,8 +9,7 @@ and this library adheres to Rust's notion of
 ### Notable changes
 `zcash_client_backend` now supports TEX (transparent-source-only) addresses as specified
 in ZIP 320. Sending to one or more TEX addresses will automatically create a multi-step
-proposal that uses two transactions. This is intended to be used in conjunction with
-`zcash_client_sqlite` 0.11 or later.
+proposal that uses two transactions.
 
 In order to take advantage of this support, client wallets will need to be able to send
 multiple transactions created from `zcash_client_backend::data_api::wallet::create_proposed_transactions`.

zcash_client_backend/src/data_api/wallet.rs

@@ -604,7 +604,9 @@ where
     ParamsT: consensus::Parameters + Clone,
     FeeRuleT: FeeRule,
 {
-    // The set of transparent StepOutputs available and unused from prior steps.
+    // The set of transparent `StepOutput`s available and unused from prior steps.
+    // When a transparent `StepOutput` is created, it is added to the map. When it
+    // is consumed, it is removed from the map.
     #[cfg(feature = "transparent-inputs")]
     let mut unused_transparent_outputs = HashMap::new();
 

zcash_client_backend/src/data_api/wallet/input_selection.rs

@@ -464,6 +464,9 @@ where
                 // The ephemeral input going into transaction 1 must be able to pay that
                 // transaction's fee, as well as the TEX address payments.
 
+                // First compute the required total without providing any input value,
+                // catching the `InsufficientFunds` error to obtain the required amount
+                // given the provided change strategy.
                 let tr1_required_input_value =
                     match self.change_strategy.compute_balance::<_, DbT::NoteRef>(
                         params,
@@ -475,7 +478,7 @@ where
                         &orchard_fees::EmptyBundleView,
                         &self.dust_output_policy,
                         #[cfg(feature = "transparent-inputs")]
-                        true,
+                        true, // ignore change memo to avoid adding a change output
                         #[cfg(feature = "transparent-inputs")]
                         &[NonNegativeAmount::ZERO],
                         #[cfg(feature = "transparent-inputs")]
@@ -486,6 +489,8 @@ where
                         Err(other) => return Err(other.into()),
                     };
 
+                // Now recompute to obtain the `TransactionBalance` and verify that it
+                // fully accounts for the required fees.
                 let tr1_balance = self.change_strategy.compute_balance::<_, DbT::NoteRef>(
                     params,
                     target_height,
@@ -496,7 +501,7 @@ where
                     &orchard_fees::EmptyBundleView,
                     &self.dust_output_policy,
                     #[cfg(feature = "transparent-inputs")]
-                    true,
+                    true, // ignore change memo to avoid adding a change output
                     #[cfg(feature = "transparent-inputs")]
                     &[tr1_required_input_value],
                     #[cfg(feature = "transparent-inputs")]

zcash_client_sqlite/src/wallet/transparent/ephemeral.rs

@@ -26,6 +26,10 @@ use crate::{error::SqliteClientError, wallet::get_account, AccountId, SqlTransac
 pub(crate) const GAP_LIMIT: i32 = 20;
 
 // The custom scope used for derivation of ephemeral addresses.
+//
+// This must match the constant used in
+// `zcash_primitives::legacy::keys::AccountPubKey::derive_ephemeral_ivk`.
+//
 // TODO: consider moving this to `zcash_primitives::legacy::keys`, or else
 // provide a way to derive `ivk`s for custom scopes in general there, so that
 // the constant isn't duplicated.