zcash_client_backend: Generalize & extend wallet metadata query API

This generalizes the previous wallet metadata query API to be able to
represent more complex queries, and also to return note totals in
addition to note counts.

zcash_client_backend/CHANGELOG.md

@@ -13,6 +13,8 @@ and this library adheres to Rust's notion of
   - `WalletSummary::progress`
   - `WalletMeta`
   - `impl Default for wallet::input_selection::GreedyInputSelector`
+  - `BoundedU8`
+  - `NoteSelector`
 - `zcash_client_backend::fees`
   - `SplitPolicy`
   - `StandardFeeRule` has been moved here from `zcash_primitives::fees`. Relative

zcash_client_backend/src/data_api.rs

@@ -804,20 +804,28 @@ impl<NoteRef> SpendableNotes<NoteRef> {
 /// the wallet.
 pub struct WalletMeta {
     sapling_note_count: usize,
+    sapling_total_value: NonNegativeAmount,
     #[cfg(feature = "orchard")]
     orchard_note_count: usize,
+    #[cfg(feature = "orchard")]
+    orchard_total_value: NonNegativeAmount,
 }
 
 impl WalletMeta {
     /// Constructs a new [`WalletMeta`] value from its constituent parts.
     pub fn new(
         sapling_note_count: usize,
+        sapling_total_value: NonNegativeAmount,
         #[cfg(feature = "orchard")] orchard_note_count: usize,
+        #[cfg(feature = "orchard")] orchard_total_value: NonNegativeAmount,
     ) -> Self {
         Self {
             sapling_note_count,
+            sapling_total_value,
             #[cfg(feature = "orchard")]
             orchard_note_count,
+            #[cfg(feature = "orchard")]
+            orchard_total_value,
         }
     }
 
@@ -838,18 +846,111 @@ impl WalletMeta {
         self.sapling_note_count
     }
 
+    /// Returns the total value of Sapling notes represented by [`Self::sapling_note_count`].
+    pub fn sapling_total_value(&self) -> NonNegativeAmount {
+        self.sapling_total_value
+    }
+
     /// Returns the number of unspent Orchard notes belonging to the account for which this was
     /// generated.
     #[cfg(feature = "orchard")]
     pub fn orchard_note_count(&self) -> usize {
         self.orchard_note_count
     }
 
+    /// Returns the total value of Orchard notes represented by [`Self::orchard_note_count`].
+    #[cfg(feature = "orchard")]
+    pub fn orchard_total_value(&self) -> NonNegativeAmount {
+        self.orchard_total_value
+    }
+
     /// Returns the total number of unspent shielded notes belonging to the account for which this
     /// was generated.
     pub fn total_note_count(&self) -> usize {
         self.sapling_note_count + self.note_count(ShieldedProtocol::Orchard)
     }
+
+    /// Returns the total value of shielded notes represented by [`Self::total_note_count`]
+    pub fn total_value(&self) -> NonNegativeAmount {
+        #[cfg(feature = "orchard")]
+        let orchard_value = self.orchard_total_value;
+        #[cfg(not(feature = "orchard"))]
+        let orchard_value = NonNegativeAmount::ZERO;
+
+        (self.sapling_total_value + orchard_value).expect("Does not overflow Zcash maximum value.")
+    }
+}
+
+/// A `u8` value in the range 0..=MAX
+#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
+pub struct BoundedU8<const MAX: u8>(u8);
+
+impl<const MAX: u8> BoundedU8<MAX> {
+    /// Creates a constant `BoundedU8` from a [`u8`] value.
+    ///
+    /// Panics: if the value is outside the range `0..=100`.
+    pub const fn new_const(value: u8) -> Self {
+        assert!(value <= MAX);
+        Self(value)
+    }
+
+    /// Creates a `BoundedU8` from a [`u8`] value.
+    ///
+    /// Returns `None` if the provided value is outside the range `0..=100`.
+    pub fn new(value: u8) -> Option<Self> {
+        if value <= MAX {
+            Some(Self(value))
+        } else {
+            None
+        }
+    }
+
+    /// Returns the wrapped [`u8`] value.
+    pub fn value(&self) -> u8 {
+        self.0
+    }
+}
+
+/// A small query language for filtering notes belonging to an account.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum NoteSelector {
+    /// Selects notes having value greater than or equal to the provided value.
+    ExceedsMinValue(NonNegativeAmount),
+    /// Selects notes having value greater than or equal to the n'th percentile of previously sent
+    /// notes in the wallet. The wrapped value must be in the range `1..=100`
+    ExceedsPriorSendPercentile(BoundedU8<100>),
+    /// Selects notes having value greater than or equal to the specified percentage of the wallet
+    /// balance. The wrapped value must be in the range `1..=100`
+    ExceedsBalancePercentage(BoundedU8<100>),
+    /// A note will be selected if it satisfies both of the specified conditions.
+    ///
+    /// If it is not possible to evaluate one of the conditions (for example,
+    /// [`NoteSelector::ExceedsPriorSendPercentile`] cannot be evaluated if no sends have been
+    /// performed) then that condition will be ignored.
+    And(Box<NoteSelector>, Box<NoteSelector>),
+    /// A note will be selected if it satisfies the first condition; if it is not possible to
+    /// evaluate that condition (for example, [`NoteSelector::ExceedsPriorSendPercentile`] cannot
+    /// be evaluated if no sends have been performed) then the second condition will be used for
+    /// evaluation.
+    Attempt {
+        condition: Box<NoteSelector>,
+        fallback: Box<NoteSelector>,
+    },
+}
+
+impl NoteSelector {
+    /// Constructs a [`NoteSelector::And`] query node.
+    pub fn and(l: NoteSelector, r: NoteSelector) -> Self {
+        Self::And(Box::new(l), Box::new(r))
+    }
+
+    /// Constructs a [`NoteSelector::Attempt`] query node.
+    pub fn attempt(condition: NoteSelector, fallback: NoteSelector) -> Self {
+        Self::Attempt {
+            condition: Box::new(condition),
+            fallback: Box::new(fallback),
+        }
+    }
 }
 
 /// A trait representing the capability to query a data store for unspent transaction outputs
@@ -900,12 +1001,15 @@ pub trait InputSource {
     ///
     /// The returned metadata value must exclude:
     /// - spent notes;
-    /// - unspent notes having value less than the specified minimum value;
+    /// - unspent notes excluded by the provided selector;
     /// - unspent notes identified in the given `exclude` list.
+    ///
+    /// Implementations of this method may limit the complexity of supported queries. Such
+    /// limitations should be clearly documented for the implementing type.
     fn get_wallet_metadata(
         &self,
         account: Self::AccountId,
-        min_value: NonNegativeAmount,
+        selector: &NoteSelector,
         exclude: &[Self::NoteRef],
     ) -> Result<WalletMeta, Self::Error>;
 

zcash_client_backend/src/data_api/testing.rs

@@ -59,7 +59,6 @@ use crate::{
     ShieldedProtocol,
 };
 
-use super::error::Error;
 use super::{
     chain::{scan_cached_blocks, BlockSource, ChainState, CommitmentTreeRoot, ScanSummary},
     scanning::ScanRange,
@@ -74,6 +73,7 @@ use super::{
     WalletCommitmentTrees, WalletMeta, WalletRead, WalletSummary, WalletTest, WalletWrite,
     SAPLING_SHARD_HEIGHT,
 };
+use super::{error::Error, NoteSelector};
 
 #[cfg(feature = "transparent-inputs")]
 use {
@@ -2354,7 +2354,7 @@ impl InputSource for MockWalletDb {
     fn get_wallet_metadata(
         &self,
         _account: Self::AccountId,
-        _min_value: NonNegativeAmount,
+        _selector: &NoteSelector,
         _exclude: &[Self::NoteRef],
     ) -> Result<WalletMeta, Self::Error> {
         Err(())

zcash_client_backend/src/data_api/testing/pool.rs

@@ -362,7 +362,7 @@ pub fn send_with_multiple_change_outputs<T: ShieldedPoolTester>(
         Some(change_memo.clone().into()),
         T::SHIELDED_PROTOCOL,
         DustOutputPolicy::default(),
-        SplitPolicy::new(
+        SplitPolicy::with_min_output_value(
             NonZeroUsize::new(2).unwrap(),
             NonNegativeAmount::const_from_u64(100_0000),
         ),
@@ -465,7 +465,7 @@ pub fn send_with_multiple_change_outputs<T: ShieldedPoolTester>(
         Some(change_memo.into()),
         T::SHIELDED_PROTOCOL,
         DustOutputPolicy::default(),
-        SplitPolicy::new(
+        SplitPolicy::with_min_output_value(
             NonZeroUsize::new(8).unwrap(),
             NonNegativeAmount::const_from_u64(10_0000),
         ),

zcash_client_backend/src/fees.rs

@@ -10,13 +10,14 @@ use zcash_primitives::{
         components::{amount::NonNegativeAmount, OutPoint},
         fees::{
             transparent::{self, InputSize},
-            zip317 as prim_zip317, FeeRule,
+            zip317::{self as prim_zip317},
+            FeeRule,
         },
     },
 };
 use zcash_protocol::{PoolType, ShieldedProtocol};
 
-use crate::data_api::InputSource;
+use crate::data_api::{BoundedU8, InputSource};
 
 pub mod common;
 #[cfg(feature = "non-standard-fees")]
@@ -355,63 +356,112 @@ impl Default for DustOutputPolicy {
 #[derive(Clone, Copy, Debug)]
 pub struct SplitPolicy {
     target_output_count: NonZeroUsize,
-    min_split_output_size: NonNegativeAmount,
+    min_split_output_value: Option<NonNegativeAmount>,
+    notes_must_exceed_prior_send_percentile: Option<BoundedU8<100>>,
+    notes_must_exceed_balance_percentage: Option<BoundedU8<100>>,
 }
 
 impl SplitPolicy {
-    /// Constructs a new [`SplitPolicy`] from its constituent parts.
-    pub fn new(
+    /// In the case that no other conditions provided by the user are available to fall back on,
+    /// a default value of [`MARGINAL_FEE`] * 100 will be used as the "minimum usable note value"
+    /// when retrieving wallet metadata.
+    pub(crate) const MIN_NOTE_VALUE: NonNegativeAmount = NonNegativeAmount::const_from_u64(500000);
+
+    /// Constructs a new [`SplitPolicy`] that splits using a fixed minimum note value.
+    pub fn with_min_output_value(
         target_output_count: NonZeroUsize,
-        min_split_output_size: NonNegativeAmount,
+        min_split_output_value: NonNegativeAmount,
     ) -> Self {
         Self {
             target_output_count,
-            min_split_output_size,
+            min_split_output_value: Some(min_split_output_value),
+            notes_must_exceed_prior_send_percentile: None,
+            notes_must_exceed_balance_percentage: None,
         }
     }
 
     /// Constructs a [`SplitPolicy`] that prescribes a single output (no splitting).
     pub fn single_output() -> Self {
         Self {
             target_output_count: NonZeroUsize::MIN,
-            min_split_output_size: NonNegativeAmount::ZERO,
+            min_split_output_value: None,
+            notes_must_exceed_prior_send_percentile: None,
+            notes_must_exceed_balance_percentage: None,
         }
     }
 
     /// Returns the minimum value for a note resulting from splitting of change.
     ///
     /// If splitting change would result in notes of value less than the minimum split output size,
     /// a smaller number of splits should be chosen.
-    pub fn min_split_output_size(&self) -> NonNegativeAmount {
-        self.min_split_output_size
+    pub fn min_split_output_value(&self) -> Option<NonNegativeAmount> {
+        self.min_split_output_value
+    }
+
+    /// Returns the bound on output size that is used to evaluate against prior send behavior.
+    ///
+    /// If splitting change would result in notes of value less than the `n`'th percentile of prior
+    /// send values, a smaller number of splits should be chosen.
+    pub fn notes_must_exceed_prior_send_percentile(&self) -> Option<BoundedU8<100>> {
+        self.notes_must_exceed_prior_send_percentile
+    }
+
+    /// Returns the bound on output size that is used to evaluate against wallet balance.
+    ///
+    /// If splitting change would result in notes of value less than `n` percent of the wallet
+    /// balance, a smaller number of splits should be chosen.
+    pub fn notes_must_exceed_balance_percentage(&self) -> Option<BoundedU8<100>> {
+        self.notes_must_exceed_balance_percentage
     }
 
     /// Returns the number of output notes to produce from the given total change value, given the
-    /// number of existing unspent notes in the account and this policy.
+    /// total value and number of existing unspent notes in the account and this policy.
     pub fn split_count(
         &self,
         existing_notes: usize,
+        existing_notes_total: NonNegativeAmount,
         total_change: NonNegativeAmount,
     ) -> NonZeroUsize {
+        fn to_nonzero_u64(value: usize) -> NonZeroU64 {
+            NonZeroU64::new(u64::try_from(value).expect("usize fits into u64"))
+                .expect("NonZeroU64 input derived from NonZeroUsize")
+        }
+
         let mut split_count =
             NonZeroUsize::new(usize::from(self.target_output_count).saturating_sub(existing_notes))
                 .unwrap_or(NonZeroUsize::MIN);
 
-        loop {
-            let per_output_change = total_change.div_with_remainder(
-                NonZeroU64::new(
-                    u64::try_from(usize::from(split_count)).expect("usize fits into u64"),
-                )
-                .unwrap(),
-            );
-            if *per_output_change.quotient() >= self.min_split_output_size {
-                return split_count;
-            } else if let Some(new_count) = NonZeroUsize::new(usize::from(split_count) - 1) {
-                split_count = new_count;
-            } else {
-                // We always create at least one change output.
-                return NonZeroUsize::MIN;
+        let min_split_output_value = self.min_split_output_value.or_else(|| {
+            // If no minimum split output size is set, we choose the minimum split size to be a
+            // quarter of the average value of notes in the wallet after the transaction.
+            (existing_notes_total + total_change).map(|total| {
+                *total
+                    .div_with_remainder(to_nonzero_u64(
+                        usize::from(self.target_output_count).saturating_mul(4),
+                    ))
+                    .quotient()
+            })
+        });
+
+        if let Some(min_split_output_value) = min_split_output_value {
+            loop {
+                let per_output_change =
+                    total_change.div_with_remainder(to_nonzero_u64(usize::from(split_count)));
+                if *per_output_change.quotient() >= min_split_output_value {
+                    return split_count;
+                } else if let Some(new_count) = NonZeroUsize::new(usize::from(split_count) - 1) {
+                    split_count = new_count;
+                } else {
+                    // We always create at least one change output.
+                    return NonZeroUsize::MIN;
+                }
             }
+        } else {
+            // This is purely defensive; this case would only arise in the case that the addition
+            // of the existing notes with the total change overflows the maximum monetary amount.
+            // Since it's always safe to fall back to a single change value, this is better than a
+            // panic.
+            return NonZeroUsize::MIN;
         }
     }
 }

zcash_client_backend/src/fees/common.rs

@@ -429,8 +429,11 @@ where
             // available in the wallet, irrespective of pool. If we don't have any wallet metadata
             // available, we fall back to generating a single change output.
             let split_count = wallet_meta.map_or(NonZeroUsize::MIN, |wm| {
-                cfg.split_policy
-                    .split_count(wm.total_note_count(), proposed_change)
+                cfg.split_policy.split_count(
+                    wm.total_note_count(),
+                    wm.total_value(),
+                    proposed_change,
+                )
             });
             let per_output_change = proposed_change.div_with_remainder(
                 NonZeroU64::new(