Renames the `ExtendedFullViewingKey::address` method to `find_address`.

This also adds a new semantically different `address` method which
attempts to produce an address given the specified diversifier index,
and returns `None` if that index does not produce a valid diversifier.

It is then up to the caller to search the diversifier index space if
the diversifier index that they are attempting to use does not result in
a valid diversifier.

zcash_client_backend/examples/diversify-address.rs

@@ -65,7 +65,7 @@ fn main() {
         return;
     };
 
-    let (diversifier_index, address) = extfvk.address(opts.diversifier_index).unwrap();
+    let (diversifier_index, address) = extfvk.find_address(opts.diversifier_index).unwrap();
     println!(
         "# Diversifier index: {}",
         encode_diversifier_index(&diversifier_index)

zcash_primitives/CHANGELOG.md

@@ -53,6 +53,24 @@ and this library adheres to Rust's notion of
   crate, which can be found in the `components` directory.
 - `zcash_primitives::transaction::components::Amount` now implements
   `memuse::DynamicUsage`, to enable `orchard::Bundle<_, Amount>::dynamic_usage`.
+- `zcash_primitives::zip32::diversifier` has been renamed to `find_sapling_diversifier`
+  and `sapling_diversifier` has been added. `find_sapling_diversifier` searches the
+  diversifier index space, whereas `sapling_diversifier` just attempts to use the
+  provided diversifier index and returns `None` if it does not produce a valid
+  diversifier.
+- `zcash_primitives::zip32::DiversifierKey::diversifier` has been renamed to 
+  `find_diversifier` and the `diversifier` method has new semantics.
+  `find_diversifier` searches the diversifier index space to find a diversifier
+  index which produces a valid diversifier, whereas `diversifier` just attempts
+  to use the provided diversifier index and returns `None` if it does not
+  produce a valid diversifier.
+- `zcash_primitives::zip32::ExtendedFullViewingKey::address` has been renamed
+  to `find_address` and the `address` method has new semantics. `find_address`
+  searches the diversifier index space until it obtains a valid diversifier,
+  and returns the address corresponding to that diversifier, whereas `address`
+  just attempts to create an address corresponding to the diversifier derived
+  from the provided diversifier index and returns `None` if the provide index
+  does not produce a valid diversifier.
 
 ### Changed
 - MSRV is now 1.51.0.

zcash_primitives/src/zip32.rs

@@ -155,7 +155,7 @@ impl DiversifierKey {
 
     /// Attempts to produce a diversifier at the given index. Returns None
     /// if the index does not produce a valid diversifier.
-    pub fn try_diversifier(&self, j: DiversifierIndex) -> Option<Diversifier> {
+    pub fn diversifier(&self, j: DiversifierIndex) -> Option<Diversifier> {
         let ff = FF1::<Aes256>::new(&self.0, 2).unwrap();
         Self::try_diversifier_internal(&ff, j)
     }
@@ -163,7 +163,7 @@ impl DiversifierKey {
     /// Returns the first index starting from j that generates a valid
     /// diversifier, along with the corresponding diversifier. Returns
     /// an error if the diversifier space is exhausted.
-    pub fn diversifier(
+    pub fn find_diversifier(
         &self,
         mut j: DiversifierIndex,
     ) -> Result<(DiversifierIndex, Diversifier), ()> {
@@ -439,8 +439,24 @@ impl ExtendedFullViewingKey {
         })
     }
 
-    pub fn address(&self, j: DiversifierIndex) -> Result<(DiversifierIndex, PaymentAddress), ()> {
-        let (j, d_j) = self.dk.diversifier(j)?;
+    /// Attempt to produce a payment address given the specified diversifier
+    /// index, and return None if the specified index does not produce a valid
+    /// diversifier.
+    pub fn address(&self, j: DiversifierIndex) -> Option<PaymentAddress> {
+        self.dk
+            .diversifier(j)
+            .and_then(|d_j| self.fvk.vk.to_payment_address(d_j))
+    }
+
+    /// Search the diversifier space starting at diversifier index `j` for
+    /// one which will produce a valid diversifier, and return the payment address
+    /// constructed using that diversifier along with the index at which the
+    /// valid diversifier was found.
+    pub fn find_address(
+        &self,
+        j: DiversifierIndex,
+    ) -> Result<(DiversifierIndex, PaymentAddress), ()> {
+        let (j, d_j) = self.dk.find_diversifier(j)?;
         match self.fvk.vk.to_payment_address(d_j) {
             Some(addr) => Ok((j, addr)),
             None => Err(()),
@@ -448,7 +464,7 @@ impl ExtendedFullViewingKey {
     }
 
     pub fn default_address(&self) -> Result<(DiversifierIndex, PaymentAddress), ()> {
-        self.address(DiversifierIndex::new())
+        self.find_address(DiversifierIndex::new())
     }
 }
 
@@ -518,7 +534,7 @@ mod tests {
     }
 
     #[test]
-    fn diversifier() {
+    fn find_diversifier() {
         let dk = DiversifierKey([0; 32]);
         let j_0 = DiversifierIndex::new();
         let j_1 = DiversifierIndex([1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]);
@@ -529,22 +545,22 @@ mod tests {
         let d_3 = [60, 253, 170, 8, 171, 147, 220, 31, 3, 144, 34];
 
         // j = 0
-        let (j, d_j) = dk.diversifier(j_0).unwrap();
+        let (j, d_j) = dk.find_diversifier(j_0).unwrap();
         assert_eq!(j, j_0);
         assert_eq!(d_j.0, d_0);
 
         // j = 1
-        let (j, d_j) = dk.diversifier(j_1).unwrap();
+        let (j, d_j) = dk.find_diversifier(j_1).unwrap();
         assert_eq!(j, j_3);
         assert_eq!(d_j.0, d_3);
 
         // j = 2
-        let (j, d_j) = dk.diversifier(j_2).unwrap();
+        let (j, d_j) = dk.find_diversifier(j_2).unwrap();
         assert_eq!(j, j_3);
         assert_eq!(d_j.0, d_3);
 
         // j = 3
-        let (j, d_j) = dk.diversifier(j_3).unwrap();
+        let (j, d_j) = dk.find_diversifier(j_3).unwrap();
         assert_eq!(j, j_3);
         assert_eq!(d_j.0, d_3);
     }
@@ -1050,7 +1066,7 @@ mod tests {
 
             // d0
             let mut di = DiversifierIndex::new();
-            match xfvk.dk.diversifier(di) {
+            match xfvk.dk.find_diversifier(di) {
                 Ok((l, d)) if l == di => assert_eq!(d.0, tv.d0.unwrap()),
                 Ok((_, _)) => assert!(tv.d0.is_none()),
                 Err(()) => panic!(),
@@ -1058,7 +1074,7 @@ mod tests {
 
             // d1
             di.increment().unwrap();
-            match xfvk.dk.diversifier(di) {
+            match xfvk.dk.find_diversifier(di) {
                 Ok((l, d)) if l == di => assert_eq!(d.0, tv.d1.unwrap()),
                 Ok((_, _)) => assert!(tv.d1.is_none()),
                 Err(()) => panic!(),
@@ -1066,7 +1082,7 @@ mod tests {
 
             // d2
             di.increment().unwrap();
-            match xfvk.dk.diversifier(di) {
+            match xfvk.dk.find_diversifier(di) {
                 Ok((l, d)) if l == di => assert_eq!(d.0, tv.d2.unwrap()),
                 Ok((_, _)) => assert!(tv.d2.is_none()),
                 Err(()) => panic!(),
@@ -1074,7 +1090,7 @@ mod tests {
 
             // dmax
             let dmax = DiversifierIndex([0xff; 11]);
-            match xfvk.dk.diversifier(dmax) {
+            match xfvk.dk.find_diversifier(dmax) {
                 Ok((l, d)) if l == dmax => assert_eq!(d.0, tv.dmax.unwrap()),
                 Ok((_, _)) => panic!(),
                 Err(_) => assert!(tv.dmax.is_none()),