Rename "derive" things that are not doing derivation

The words "derive", "derived" and "derivable" were being used to
describe things that aren't stricly derivation. Derivation is the
process of taking cryptographic data and deterministically producing
something else given some inputs. This is how the term is used in bip32,
rust-bitcoin and more generally.

In rust-miniscript the term is also used to mean "replacing a wildcard
in a derivation path with a particular index". This can be quite
confusing. For example, `is_derivable` returns true when there is a
wildcard in the descriptor -- but it should return the opposite (given
the usual meaning)! You can't do a derivation because you don't know
the full derivation path yet (it's s got a wildcard in it). This commit
replaces all instances where "derive" is used in this way.

Author: LLFourn

examples/xpub_descriptors.rs

@@ -18,7 +18,7 @@ use std::str::FromStr;
 
 use miniscript::bitcoin::secp256k1::{Secp256k1, Verification};
 use miniscript::bitcoin::{Address, Network};
-use miniscript::{DerivedDescriptorKey, Descriptor, DescriptorPublicKey};
+use miniscript::{DefiniteDescriptorKey, Descriptor, DescriptorPublicKey};
 
 const XPUB_1: &str = "xpub661MyMwAqRbcFW31YEwpkMuc5THy2PSt5bDMsktWQcFF8syAmRUapSCGu8ED9W6oDMSgv6Zz8idoc4a6mr8BDzTJY47LJhkJ8UB7WEGuduB";
 const XPUB_2: &str = "xpub69H7F5d8KSRgmmdJg2KhpAK8SR3DjMwAdkxj3ZuxV27CprR9LgpeyGmXUbC6wb7ERfvrnKZjXoUmmDznezpbZb7ap6r1D3tgFxHmwMkQTPH";
@@ -40,7 +40,7 @@ fn p2wsh<C: Verification>(secp: &Secp256k1<C>) -> Address {
     let s = format!("wsh(sortedmulti(1,{},{}))", XPUB_1, XPUB_2);
     // let s = format!("wsh(sortedmulti(1,{},{}))", XPUB_2, XPUB_1);
 
-    let address = Descriptor::<DerivedDescriptorKey>::from_str(&s)
+    let address = Descriptor::<DefiniteDescriptorKey>::from_str(&s)
         .unwrap()
         .derived_descriptor(&secp)
         .unwrap()

src/descriptor/key.rs

@@ -72,7 +72,7 @@ pub enum SinglePubKey {
 
 /// A [`DescriptorPublicKey`] without any wildcards.
 #[derive(Debug, Eq, PartialEq, Clone, Ord, PartialOrd, Hash)]
-pub struct DerivedDescriptorKey(DescriptorPublicKey);
+pub struct DefiniteDescriptorKey(DescriptorPublicKey);
 
 impl fmt::Display for DescriptorSecretKey {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
@@ -428,15 +428,28 @@ impl DescriptorPublicKey {
         }
     }
 
-    /// Whether or not the key has a wildcards
+    /// Whether or not the key has a wildcard
+    #[deprecated(note = "use has_wildcard instead")]
     pub fn is_deriveable(&self) -> bool {
+        self.has_wildcard()
+    }
+
+    /// Whether or not the key has a wildcard
+    pub fn has_wildcard(&self) -> bool {
         match *self {
             DescriptorPublicKey::Single(..) => false,
             DescriptorPublicKey::XPub(ref xpub) => xpub.wildcard != Wildcard::None,
         }
     }
 
-    /// Derives the [`DescriptorPublicKey`] at `index` if this key is an xpub and has a wildcard.
+    #[deprecated(note = "use at_derivation_index instead")]
+    /// Deprecated name of [`at_derivation_index`].
+    pub fn derive(self, index: u32) -> DefiniteDescriptorKey {
+        self.at_derivation_index(index)
+    }
+
+    /// Replaces any wildcard (i.e. `/*`) in the key with a particular derivation index, turning it into a
+    /// *definite* key (i.e. one where all the derivation paths are set).
     ///
     /// # Returns
     ///
@@ -447,8 +460,8 @@ impl DescriptorPublicKey {
     /// # Panics
     ///
     /// If `index` ≥ 2^31
-    pub fn derive(self, index: u32) -> DerivedDescriptorKey {
-        let derived = match self {
+    pub fn at_derivation_index(self, index: u32) -> DefiniteDescriptorKey {
+        let definite = match self {
             DescriptorPublicKey::Single(_) => self,
             DescriptorPublicKey::XPub(xpub) => {
                 let derivation_path = match xpub.wildcard {
@@ -469,7 +482,7 @@ impl DescriptorPublicKey {
             }
         };
 
-        DerivedDescriptorKey::new(derived)
+        DefiniteDescriptorKey::new(definite)
             .expect("The key should not contain any wildcards at this point")
     }
 
@@ -749,7 +762,7 @@ impl MiniscriptKey for DescriptorPublicKey {
     }
 }
 
-impl DerivedDescriptorKey {
+impl DefiniteDescriptorKey {
     /// Computes the raw [`bitcoin::PublicKey`] for this descriptor key.
     ///
     /// Will return an error if the key has any hardened derivation steps
@@ -767,7 +780,7 @@ impl DerivedDescriptorKey {
     ///
     /// Returns `None` if the key contains a wildcard
     fn new(key: DescriptorPublicKey) -> Option<Self> {
-        if key.is_deriveable() {
+        if key.has_wildcard() {
             None
         } else {
             Some(Self(key))
@@ -785,26 +798,26 @@ impl DerivedDescriptorKey {
     }
 }
 
-impl FromStr for DerivedDescriptorKey {
+impl FromStr for DefiniteDescriptorKey {
     type Err = DescriptorKeyParseError;
 
     fn from_str(s: &str) -> Result<Self, Self::Err> {
         let inner = DescriptorPublicKey::from_str(s)?;
         Ok(
-            DerivedDescriptorKey::new(inner).ok_or(DescriptorKeyParseError(
+            DefiniteDescriptorKey::new(inner).ok_or(DescriptorKeyParseError(
                 "cannot parse key with a wilcard as a DerivedDescriptorKey",
             ))?,
         )
     }
 }
 
-impl fmt::Display for DerivedDescriptorKey {
+impl fmt::Display for DefiniteDescriptorKey {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         self.0.fmt(f)
     }
 }
 
-impl MiniscriptKey for DerivedDescriptorKey {
+impl MiniscriptKey for DefiniteDescriptorKey {
     // This allows us to be able to derive public keys even for PkH s
     type RawPkHash = Self;
     type Sha256 = sha256::Hash;
@@ -825,7 +838,7 @@ impl MiniscriptKey for DerivedDescriptorKey {
     }
 }
 
-impl ToPublicKey for DerivedDescriptorKey {
+impl ToPublicKey for DefiniteDescriptorKey {
     fn to_public_key(&self) -> bitcoin::PublicKey {
         let secp = Secp256k1::verification_only();
         self.0.derive_public_key(&secp).unwrap()
@@ -852,8 +865,8 @@ impl ToPublicKey for DerivedDescriptorKey {
     }
 }
 
-impl From<DerivedDescriptorKey> for DescriptorPublicKey {
-    fn from(d: DerivedDescriptorKey) -> Self {
+impl From<DefiniteDescriptorKey> for DescriptorPublicKey {
+    fn from(d: DefiniteDescriptorKey) -> Self {
         d.0
     }
 }
@@ -964,17 +977,17 @@ mod test {
         let public_key = DescriptorPublicKey::from_str("[abcdef00/0'/1']tpubDBrgjcxBxnXyL575sHdkpKohWu5qHKoQ7TJXKNrYznh5fVEGBv89hA8ENW7A8MFVpFUSvgLqc4Nj1WZcpePX6rrxviVtPowvMuGF5rdT2Vi/2").unwrap();
         assert_eq!(public_key.master_fingerprint().to_string(), "abcdef00");
         assert_eq!(public_key.full_derivation_path().to_string(), "m/0'/1'/2");
-        assert_eq!(public_key.is_deriveable(), false);
+        assert_eq!(public_key.has_wildcard(), false);
 
         let public_key = DescriptorPublicKey::from_str("[abcdef00/0'/1']tpubDBrgjcxBxnXyL575sHdkpKohWu5qHKoQ7TJXKNrYznh5fVEGBv89hA8ENW7A8MFVpFUSvgLqc4Nj1WZcpePX6rrxviVtPowvMuGF5rdT2Vi/*").unwrap();
         assert_eq!(public_key.master_fingerprint().to_string(), "abcdef00");
         assert_eq!(public_key.full_derivation_path().to_string(), "m/0'/1'");
-        assert_eq!(public_key.is_deriveable(), true);
+        assert_eq!(public_key.has_wildcard(), true);
 
         let public_key = DescriptorPublicKey::from_str("[abcdef00/0'/1']tpubDBrgjcxBxnXyL575sHdkpKohWu5qHKoQ7TJXKNrYznh5fVEGBv89hA8ENW7A8MFVpFUSvgLqc4Nj1WZcpePX6rrxviVtPowvMuGF5rdT2Vi/*h").unwrap();
         assert_eq!(public_key.master_fingerprint().to_string(), "abcdef00");
         assert_eq!(public_key.full_derivation_path().to_string(), "m/0'/1'");
-        assert_eq!(public_key.is_deriveable(), true);
+        assert_eq!(public_key.has_wildcard(), true);
     }
 
     #[test]
@@ -986,7 +999,7 @@ mod test {
         assert_eq!(public_key.to_string(), "[2cbe2a6d/0'/1']tpubDBrgjcxBxnXyL575sHdkpKohWu5qHKoQ7TJXKNrYznh5fVEGBv89hA8ENW7A8MFVpFUSvgLqc4Nj1WZcpePX6rrxviVtPowvMuGF5rdT2Vi/2");
         assert_eq!(public_key.master_fingerprint().to_string(), "2cbe2a6d");
         assert_eq!(public_key.full_derivation_path().to_string(), "m/0'/1'/2");
-        assert_eq!(public_key.is_deriveable(), false);
+        assert_eq!(public_key.has_wildcard(), false);
 
         let secret_key = DescriptorSecretKey::from_str("tprv8ZgxMBicQKsPcwcD4gSnMti126ZiETsuX7qwrtMypr6FBwAP65puFn4v6c3jrN9VwtMRMph6nyT63NrfUL4C3nBzPcduzVSuHD7zbX2JKVc/0'/1'/2'").unwrap();
         let public_key = secret_key.to_public(&secp).unwrap();

src/descriptor/mod.rs

@@ -58,7 +58,7 @@ mod checksum;
 mod key;
 
 pub use self::key::{
-    ConversionError, DerivedDescriptorKey, DescriptorKeyParseError, DescriptorPublicKey,
+    ConversionError, DefiniteDescriptorKey, DescriptorKeyParseError, DescriptorPublicKey,
     DescriptorSecretKey, DescriptorXKey, InnerXKey, SinglePriv, SinglePub, SinglePubKey, Wildcard,
 };
 
@@ -513,32 +513,44 @@ impl<Pk: MiniscriptKey> ForEachKey<Pk> for Descriptor<Pk> {
 
 impl Descriptor<DescriptorPublicKey> {
     /// Whether or not the descriptor has any wildcards
+    #[deprecated(note = "use has_wildcards instead")]
     pub fn is_deriveable(&self) -> bool {
-        self.for_any_key(|key| key.is_deriveable())
+        self.has_wildcard()
     }
 
-    /// Derives all wildcard keys in the descriptor using the supplied index
+    /// Whether or not the descriptor has any wildcards i.e. `/*`.
+    pub fn has_wildcard(&self) -> bool {
+        self.for_any_key(|key| key.has_wildcard())
+    }
+
+    /// Replaces all wildcards (i.e. `/*`) in the descriptor with a particular derivation index,
+    /// turning it into a *definite* descriptor.
     ///
-    /// Panics if given an index ≥ 2^31
+    /// # Panics
     ///
-    /// In most cases, you would want to use [`Self::derived_descriptor`] directly to obtain
-    /// a [`Descriptor<bitcoin::PublicKey>`]
-    pub fn derive(&self, index: u32) -> Descriptor<DerivedDescriptorKey> {
+    /// If index ≥ 2^31
+    pub fn at_derivation_index(&self, index: u32) -> Descriptor<DefiniteDescriptorKey> {
         struct Derivator(u32);
 
-        impl PkTranslator<DescriptorPublicKey, DerivedDescriptorKey, ()> for Derivator {
-            fn pk(&mut self, pk: &DescriptorPublicKey) -> Result<DerivedDescriptorKey, ()> {
-                Ok(pk.clone().derive(self.0))
+        impl PkTranslator<DescriptorPublicKey, DefiniteDescriptorKey, ()> for Derivator {
+            fn pk(&mut self, pk: &DescriptorPublicKey) -> Result<DefiniteDescriptorKey, ()> {
+                Ok(pk.clone().at_derivation_index(self.0))
             }
 
-            fn pkh(&mut self, pkh: &DescriptorPublicKey) -> Result<DerivedDescriptorKey, ()> {
-                Ok(pkh.clone().derive(self.0))
+            fn pkh(&mut self, pkh: &DescriptorPublicKey) -> Result<DefiniteDescriptorKey, ()> {
+                Ok(pkh.clone().at_derivation_index(self.0))
             }
         }
         self.translate_pk(&mut Derivator(index))
             .expect("BIP 32 key index substitution cannot fail")
     }
 
+    #[deprecated(note = "use at_derivation_index instead")]
+    /// Deprecated name for [`at_derivation_index`].
+    pub fn derive(&self, index: u32) -> Descriptor<DefiniteDescriptorKey> {
+        self.at_derivation_index(index)
+    }
+
     /// Convert all the public keys in the descriptor to [`bitcoin::PublicKey`] by deriving them or
     /// otherwise converting them. All [`bitcoin::XOnlyPublicKey`]s are converted to by adding a
     /// default(0x02) y-coordinate.
@@ -552,14 +564,14 @@ impl Descriptor<DescriptorPublicKey> {
     ///     .expect("Valid ranged descriptor");
     /// # let index = 42;
     /// # let secp = Secp256k1::verification_only();
-    /// let derived_descriptor = descriptor.derive(index).derived_descriptor(&secp);
+    /// let derived_descriptor = descriptor.at_derivation_index(index).derived_descriptor(&secp);
     /// # assert_eq!(descriptor.derived_descriptor(&secp, index), derived_descriptor);
     /// ```
     ///
     /// and is only here really here for backwards compatbility.
-    /// See [`derive`] and `[derived_descriptor`] for more documentation.
+    /// See [`at_derivation_index`] and `[derived_descriptor`] for more documentation.
     ///
-    /// [`derive`]: Self::derive
+    /// [`at_derivation_index`]: Self::at_derivation_index
     /// [`derived_descriptor`]: crate::DerivedDescriptor::derived_descriptor
     ///
     /// # Errors
@@ -570,7 +582,7 @@ impl Descriptor<DescriptorPublicKey> {
         secp: &secp256k1::Secp256k1<C>,
         index: u32,
     ) -> Result<Descriptor<bitcoin::PublicKey>, ConversionError> {
-        self.derive(index).derived_descriptor(&secp)
+        self.at_derivation_index(index).derived_descriptor(&secp)
     }
 
     /// Parse a descriptor that may contain secret keys
@@ -711,7 +723,7 @@ impl Descriptor<DescriptorPublicKey> {
         script_pubkey: &Script,
         range: Range<u32>,
     ) -> Result<Option<(u32, Descriptor<bitcoin::PublicKey>)>, ConversionError> {
-        let range = if self.is_deriveable() { range } else { 0..1 };
+        let range = if self.has_wildcard() { range } else { 0..1 };
 
         for i in range {
             let concrete = self.derived_descriptor(secp, i)?;
@@ -724,7 +736,7 @@ impl Descriptor<DescriptorPublicKey> {
     }
 }
 
-impl Descriptor<DerivedDescriptorKey> {
+impl Descriptor<DefiniteDescriptorKey> {
     /// Convert all the public keys in the descriptor to [`bitcoin::PublicKey`] by deriving them or
     /// otherwise converting them. All [`bitcoin::XOnlyPublicKey`]s are converted to by adding a
     /// default(0x02) y-coordinate.
@@ -740,7 +752,7 @@ impl Descriptor<DerivedDescriptorKey> {
     /// let secp = secp256k1::Secp256k1::verification_only();
     /// let descriptor = Descriptor::<DescriptorPublicKey>::from_str("tr(xpub6BgBgsespWvERF3LHQu6CnqdvfEvtMcQjYrcRzx53QJjSxarj2afYWcLteoGVky7D3UKDP9QyrLprQ3VCECoY49yfdDEHGCtMMj92pReUsQ/0/*)")
     ///     .expect("Valid ranged descriptor");
-    /// let result = descriptor.derive(0).derived_descriptor(&secp).expect("Non-hardened derivation");
+    /// let result = descriptor.at_derivation_index(0).derived_descriptor(&secp).expect("Non-hardened derivation");
     /// assert_eq!(result.to_string(), "tr(03cc8a4bc64d897bddc5fbc2f670f7a8ba0b386779106cf1223c6fc5d7cd6fc115)#6qm9h8ym");
     /// ```
     ///
@@ -754,19 +766,19 @@ impl Descriptor<DerivedDescriptorKey> {
         struct Derivator<'a, C: secp256k1::Verification>(&'a secp256k1::Secp256k1<C>);
 
         impl<'a, C: secp256k1::Verification>
-            PkTranslator<DerivedDescriptorKey, bitcoin::PublicKey, ConversionError>
+            PkTranslator<DefiniteDescriptorKey, bitcoin::PublicKey, ConversionError>
             for Derivator<'a, C>
         {
             fn pk(
                 &mut self,
-                pk: &DerivedDescriptorKey,
+                pk: &DefiniteDescriptorKey,
             ) -> Result<bitcoin::PublicKey, ConversionError> {
                 pk.derive_public_key(&self.0)
             }
 
             fn pkh(
                 &mut self,
-                pkh: &DerivedDescriptorKey,
+                pkh: &DefiniteDescriptorKey,
             ) -> Result<bitcoin::hashes::hash160::Hash, ConversionError> {
                 Ok(pkh.derive_public_key(&self.0)?.to_pubkeyhash())
             }
@@ -1597,13 +1609,13 @@ mod tests {
 
             // Same address
             let addr_one = desc_one
-                .derive(index)
+                .at_derivation_index(index)
                 .derived_descriptor(&secp_ctx)
                 .unwrap()
                 .address(bitcoin::Network::Bitcoin)
                 .unwrap();
             let addr_two = desc_two
-                .derive(index)
+                .at_derivation_index(index)
                 .derived_descriptor(&secp_ctx)
                 .unwrap()
                 .address(bitcoin::Network::Bitcoin)
@@ -1681,7 +1693,7 @@ pk(xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHW
 pk(03f28773c2d975288bc7d1d205c3748651b075fbc6610e58cddeeddf8f19405aa8))";
         let policy: policy::concrete::Policy<DescriptorPublicKey> = descriptor_str.parse().unwrap();
         let descriptor = Descriptor::new_sh(policy.compile().unwrap()).unwrap();
-        let derived_descriptor = descriptor.derive(42);
+        let definite_descriptor = descriptor.at_derivation_index(42);
 
         let res_descriptor_str = "thresh(2,\
 pk([d34db33f/44'/0'/0']xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/1/42),\
@@ -1691,7 +1703,7 @@ pk(03f28773c2d975288bc7d1d205c3748651b075fbc6610e58cddeeddf8f19405aa8))";
             res_descriptor_str.parse().unwrap();
         let res_descriptor = Descriptor::new_sh(res_policy.compile().unwrap()).unwrap();
 
-        assert_eq!(res_descriptor.to_string(), derived_descriptor.to_string());
+        assert_eq!(res_descriptor.to_string(), definite_descriptor.to_string());
     }
 
     #[test]

src/lib.rs

@@ -135,7 +135,7 @@ use std::error;
 use bitcoin::blockdata::{opcodes, script};
 use bitcoin::hashes::{hash160, ripemd160, sha256, Hash};
 
-pub use crate::descriptor::{DerivedDescriptorKey, Descriptor, DescriptorPublicKey};
+pub use crate::descriptor::{DefiniteDescriptorKey, Descriptor, DescriptorPublicKey};
 pub use crate::interpreter::Interpreter;
 pub use crate::miniscript::context::{BareCtx, Legacy, ScriptContext, Segwitv0, Tap};
 pub use crate::miniscript::decode::Terminal;