descriptor: introduce several Taproot accessors

When working with Taproot descriptors you typically need to do an
annoying (and hard to discover) `match` statement to get the `Tr`
out of the descriptor, and then call accessors on that to get the
actual data out.

Add two new methods to `Descriptor` that directly access the internal
key and the taptree. Document that the actual leaves can be obtained by
calling `.iter` on the taptree.

Next, when a user is trying to sign a Taproot branch, they need to
obtain a TapLeafHash. We have internal code which does this (which I
have pulled into a helper function since there is some room to optimize
it there..) but no exposed code, forcing the user to go digging through
the rust-bitcoin docs to figure it out (including knowing the standard
Taproot leaf version, which is an arcane detail of the sort that
Miniscript otherwise hides).

Add a new method `leaf_hash` on Taproot miniscripts, so that the user
can directly obtain the leaf hashes.

Now you can write e.g.

for script in trdesc.tap_tree_iter() {
    let leaf_hash = script.leaf_hash();
    // Do whatever you want...
}

vs the previous code which was roughly

let tr = match trdesc {
    Descriptor::Tr(ref tr) => tr,
    _ => unreachable!("I know this is a Taproot descriptor"),
};
// Or tr.tap_tree().unwrap().iter() in case you miss the weirdly-named
// Tr::iter_scripts
for script in tr.iter_scripts() {
    // Hope you know your rust-bitcoin docs by heart, and also that
    // .encode is the way to convert a Miniscript to a Script!
    let leaf_hash = TapLeafHash::from_script(
        LeafVersion::TapScript,
        script.encode(),
    );
}

Author: apoelstra

src/descriptor/mod.rs

@@ -241,6 +241,40 @@ impl<Pk: MiniscriptKey> Descriptor<Pk> {
         Ok(Descriptor::Tr(Tr::new(key, script)?))
     }
 
+    /// For a Taproot descriptor, returns the internal key.
+    pub fn internal_key(&self) -> Option<&Pk> {
+        if let Descriptor::Tr(ref tr) = self {
+            Some(tr.internal_key())
+        } else {
+            None
+        }
+    }
+
+    /// For a Taproot descriptor, returns the [`TapTree`] describing the Taproot tree.
+    ///
+    /// To obtain the individual leaves of the tree, call [`TapTree::iter`] on the
+    /// returned value.
+    pub fn tap_tree(&self) -> Option<&TapTree<Pk>> {
+        if let Descriptor::Tr(ref tr) = self {
+            tr.tap_tree().as_ref()
+        } else {
+            None
+        }
+    }
+
+    /// For a Taproot descriptor, returns an iterator over the scripts in the Taptree.
+    ///
+    /// If the descriptor is not a Taproot descriptor, **or** if the descriptor is a
+    /// Taproot descriptor containing only a keyspend, returns an empty iterator.
+    pub fn tap_tree_iter(&self) -> tr::TapTreeIter<Pk> {
+        if let Descriptor::Tr(ref tr) = self {
+            if let Some(ref tree) = tr.tap_tree() {
+                return tree.iter();
+            }
+        }
+        tr::TapTreeIter::empty()
+    }
+
     /// Get the [DescriptorType] of [Descriptor]
     pub fn desc_type(&self) -> DescriptorType {
         match *self {

src/descriptor/tr.rs

@@ -465,6 +465,11 @@ pub struct TapTreeIter<'a, Pk: MiniscriptKey> {
     stack: Vec<(u8, &'a TapTree<Pk>)>,
 }
 
+impl<'a, Pk: MiniscriptKey> TapTreeIter<'a, Pk> {
+    /// Helper function to return an empty iterator from Descriptor::tap_tree_iter.
+    pub(super) fn empty() -> Self { Self { stack: vec![] } }
+}
+
 impl<'a, Pk> Iterator for TapTreeIter<'a, Pk>
 where
     Pk: MiniscriptKey + 'a,

src/miniscript/mod.rs

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: CC0-1.0
 
-//! # Abstract Syntax Tree
+//! Abstract Syntax Tree
 //!
 //! Defines a variety of data structures for describing Miniscript, a subset of
 //! Bitcoin Script which can be efficiently parsed and serialized from Script,
@@ -289,16 +289,27 @@ impl<Pk: MiniscriptKey, Ctx: ScriptContext> Miniscript<Pk, Ctx> {
         Ctx::max_satisfaction_size(self).ok_or(Error::ImpossibleSatisfaction)
     }
 
+    /// Helper function to produce Taproot leaf hashes
+    fn leaf_hash_internal(&self) -> TapLeafHash
+    where
+        Pk: ToPublicKey,
+    {
+        TapLeafHash::from_script(&self.encode(), LeafVersion::TapScript)
+    }
+
     /// Attempt to produce non-malleable satisfying witness for the
     /// witness script represented by the parse tree
     pub fn satisfy<S: satisfy::Satisfier<Pk>>(&self, satisfier: S) -> Result<Vec<Vec<u8>>, Error>
     where
         Pk: ToPublicKey,
     {
         // Only satisfactions for default versions (0xc0) are allowed.
-        let leaf_hash = TapLeafHash::from_script(&self.encode(), LeafVersion::TapScript);
-        let satisfaction =
-            satisfy::Satisfaction::satisfy(&self.node, &satisfier, self.ty.mall.safe, &leaf_hash);
+        let satisfaction = satisfy::Satisfaction::satisfy(
+            &self.node,
+            &satisfier,
+            self.ty.mall.safe,
+            &self.leaf_hash_internal(),
+        );
         self._satisfy(satisfaction)
     }
 
@@ -311,12 +322,11 @@ impl<Pk: MiniscriptKey, Ctx: ScriptContext> Miniscript<Pk, Ctx> {
     where
         Pk: ToPublicKey,
     {
-        let leaf_hash = TapLeafHash::from_script(&self.encode(), LeafVersion::TapScript);
         let satisfaction = satisfy::Satisfaction::satisfy_mall(
             &self.node,
             &satisfier,
             self.ty.mall.safe,
-            &leaf_hash,
+            &self.leaf_hash_internal(),
         );
         self._satisfy(satisfaction)
     }
@@ -344,8 +354,12 @@ impl<Pk: MiniscriptKey, Ctx: ScriptContext> Miniscript<Pk, Ctx> {
     where
         Pk: ToPublicKey,
     {
-        let leaf_hash = TapLeafHash::from_script(&self.encode(), LeafVersion::TapScript);
-        satisfy::Satisfaction::build_template(&self.node, provider, self.ty.mall.safe, &leaf_hash)
+        satisfy::Satisfaction::build_template(
+            &self.node,
+            provider,
+            self.ty.mall.safe,
+            &self.leaf_hash_internal(),
+        )
     }
 
     /// Attempt to produce a malleable witness template given the assets available
@@ -356,16 +370,22 @@ impl<Pk: MiniscriptKey, Ctx: ScriptContext> Miniscript<Pk, Ctx> {
     where
         Pk: ToPublicKey,
     {
-        let leaf_hash = TapLeafHash::from_script(&self.encode(), LeafVersion::TapScript);
         satisfy::Satisfaction::build_template_mall(
             &self.node,
             provider,
             self.ty.mall.safe,
-            &leaf_hash,
+            &self.leaf_hash_internal(),
         )
     }
 }
 
+impl Miniscript<<Tap as ScriptContext>::Key, Tap> {
+    /// Returns the leaf hash used within a Taproot signature for this script.
+    ///
+    /// Note that this method is only implemented for Taproot Miniscripts.
+    pub fn leaf_hash(&self) -> TapLeafHash { self.leaf_hash_internal() }
+}
+
 impl<Ctx: ScriptContext> Miniscript<Ctx::Key, Ctx> {
     /// Attempt to parse an insane(scripts don't clear sanity checks)
     /// script into a Miniscript representation.