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.
@@ -49,9 +53,9 @@ pub(crate) fn last_reserved_index(
     match conn
         .query_row(
             "SELECT address_index FROM ephemeral_addresses
-         WHERE account_id = :account_id
-         ORDER BY address_index DESC
-         LIMIT 1",
+             WHERE account_id = :account_id
+             ORDER BY address_index DESC
+             LIMIT 1",
             named_params![":account_id": account_id.0],
             |row| row.get::<_, i32>(0),
         )
@@ -261,9 +265,9 @@ fn ephemeral_address_check_internal<P: consensus::Parameters>(
         .0
         .query_row(
             "SELECT t.txid FROM ephemeral_addresses
-            LEFT OUTER JOIN transactions t
-            ON t.id_tx = COALESCE(used_in_tx, mined_in_tx)
-            WHERE address = :address",
+             LEFT OUTER JOIN transactions t
+             ON t.id_tx = COALESCE(used_in_tx, mined_in_tx)
+             WHERE address = :address",
             named_params![":address": address_str],
             |row| row.get::<_, Option<Vec<u8>>>(0),
         )