Add plan capabilities to miniscript

Add a `plan` module that contains utilities to calculate the
cheapest spending path given an AssetProvider (that could
keys, preimages, or timelocks). Adds a `get_plan` method on the
various descriptor types.

Co-authored-by: Daniela Brozzoni <danielabrozzoni@protonmail.com>

Author: afilini

src/descriptor/bare.rs

@@ -14,8 +14,11 @@ use bitcoin::script::{self, PushBytes};
 use bitcoin::{Address, Network, ScriptBuf};
 
 use super::checksum::{self, verify_checksum};
+use crate::descriptor::DefiniteDescriptorKey;
 use crate::expression::{self, FromTree};
 use crate::miniscript::context::{ScriptContext, ScriptContextError};
+use crate::miniscript::satisfy::{Placeholder, Satisfaction, Witness};
+use crate::plan::AssetProvider;
 use crate::policy::{semantic, Liftable};
 use crate::prelude::*;
 use crate::util::{varint_len, witness_to_scriptsig};
@@ -135,6 +138,30 @@ impl<Pk: MiniscriptKey + ToPublicKey> Bare<Pk> {
     }
 }
 
+impl Bare<DefiniteDescriptorKey> {
+    /// Returns a plan if the provided assets are sufficient to produce a non-malleable satisfaction
+    pub fn get_plan_satisfaction<P>(
+        &self,
+        provider: &P,
+    ) -> Satisfaction<Placeholder<DefiniteDescriptorKey>>
+    where
+        P: AssetProvider<DefiniteDescriptorKey>,
+    {
+        self.ms.build_template(provider)
+    }
+
+    /// Returns a plan if the provided assets are sufficient to produce a malleable satisfaction
+    pub fn get_plan_satisfaction_mall<P>(
+        &self,
+        provider: &P,
+    ) -> Satisfaction<Placeholder<DefiniteDescriptorKey>>
+    where
+        P: AssetProvider<DefiniteDescriptorKey>,
+    {
+        self.ms.build_template_mall(provider)
+    }
+}
+
 impl<Pk: MiniscriptKey> fmt::Debug for Bare<Pk> {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         write!(f, "{:?}", self.ms)
@@ -312,6 +339,45 @@ impl<Pk: MiniscriptKey + ToPublicKey> Pkh<Pk> {
     }
 }
 
+impl Pkh<DefiniteDescriptorKey> {
+    /// Returns a plan if the provided assets are sufficient to produce a non-malleable satisfaction
+    pub fn get_plan_satisfaction<P>(
+        &self,
+        provider: &P,
+    ) -> Satisfaction<Placeholder<DefiniteDescriptorKey>>
+    where
+        P: AssetProvider<DefiniteDescriptorKey>,
+    {
+        let stack = if provider.lookup_ecdsa_sig(&self.pk) {
+            let stack = vec![
+                Placeholder::EcdsaSigPk(self.pk.clone()),
+                Placeholder::Pubkey(self.pk.clone(), BareCtx::pk_len(&self.pk)),
+            ];
+            Witness::Stack(stack)
+        } else {
+            Witness::Unavailable
+        };
+
+        Satisfaction {
+            stack,
+            has_sig: true,
+            relative_timelock: None,
+            absolute_timelock: None,
+        }
+    }
+
+    /// Returns a plan if the provided assets are sufficient to produce a malleable satisfaction
+    pub fn get_plan_satisfaction_mall<P>(
+        &self,
+        provider: &P,
+    ) -> Satisfaction<Placeholder<DefiniteDescriptorKey>>
+    where
+        P: AssetProvider<DefiniteDescriptorKey>,
+    {
+        self.get_plan_satisfaction(provider)
+    }
+}
+
 impl<Pk: MiniscriptKey> fmt::Debug for Pkh<Pk> {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         write!(f, "pkh({:?})", self.pk)

src/descriptor/key.rs

@@ -721,6 +721,41 @@ impl DescriptorPublicKey {
             }
         }
     }
+
+    /// Whether this key is the "parent" of a [`DefiniteDescriptorKey`]
+    ///
+    /// The key is considered "parent" if it represents the non-derived version of a definite key,
+    /// meaning it contains a wildcard where the definite key has a definite derivation number.
+    ///
+    /// If `self` is a single key or doesn't contain any wildcards, the definite key will have to
+    /// be exactly the same.
+    ///
+    /// Returns the derivation path to apply to `self` to obtain the definite key.
+    pub fn is_parent(&self, definite_key: &DefiniteDescriptorKey) -> Option<bip32::DerivationPath> {
+        // If the key is `Single` or it's an `XPub` with no wildcard it will match the definite key
+        // exactly, so we try this check first
+        if self == &definite_key.0 {
+            return Some(bip32::DerivationPath::default());
+        }
+
+        match (self, &definite_key.0) {
+            (DescriptorPublicKey::XPub(self_xkey), DescriptorPublicKey::XPub(definite_xkey))
+                if definite_xkey.derivation_path.len() > 0 =>
+            {
+                let definite_path_len = definite_xkey.derivation_path.len();
+                if self_xkey.origin == definite_xkey.origin
+                    && self_xkey.xkey == definite_xkey.xkey
+                    && self_xkey.derivation_path.as_ref()
+                        == &definite_xkey.derivation_path[..(definite_path_len - 1)]
+                {
+                    Some(vec![definite_xkey.derivation_path[definite_path_len - 1]].into())
+                } else {
+                    None
+                }
+            }
+            _ => None,
+        }
+    }
 }
 
 impl FromStr for DescriptorSecretKey {

src/descriptor/mod.rs

@@ -22,7 +22,8 @@ use bitcoin::{secp256k1, Address, Network, Script, ScriptBuf, TxIn, Witness};
 use sync::Arc;
 
 use self::checksum::verify_checksum;
-use crate::miniscript::{Legacy, Miniscript, Segwitv0};
+use crate::miniscript::{satisfy, Legacy, Miniscript, Segwitv0};
+use crate::plan::{AssetProvider, Plan};
 use crate::prelude::*;
 use crate::{
     expression, hash256, miniscript, BareCtx, Error, ForEachKey, MiniscriptKey, Satisfier,
@@ -476,7 +477,7 @@ impl<Pk: MiniscriptKey + ToPublicKey> Descriptor<Pk> {
             Descriptor::Wpkh(ref wpkh) => wpkh.get_satisfaction(satisfier),
             Descriptor::Wsh(ref wsh) => wsh.get_satisfaction(satisfier),
             Descriptor::Sh(ref sh) => sh.get_satisfaction(satisfier),
-            Descriptor::Tr(ref tr) => tr.get_satisfaction(satisfier),
+            Descriptor::Tr(ref tr) => tr.get_satisfaction(&satisfier),
         }
     }
 
@@ -493,7 +494,7 @@ impl<Pk: MiniscriptKey + ToPublicKey> Descriptor<Pk> {
             Descriptor::Wpkh(ref wpkh) => wpkh.get_satisfaction_mall(satisfier),
             Descriptor::Wsh(ref wsh) => wsh.get_satisfaction_mall(satisfier),
             Descriptor::Sh(ref sh) => sh.get_satisfaction_mall(satisfier),
-            Descriptor::Tr(ref tr) => tr.get_satisfaction_mall(satisfier),
+            Descriptor::Tr(ref tr) => tr.get_satisfaction_mall(&satisfier),
         }
     }
 
@@ -511,6 +512,60 @@ impl<Pk: MiniscriptKey + ToPublicKey> Descriptor<Pk> {
     }
 }
 
+impl Descriptor<DefiniteDescriptorKey> {
+    /// Returns a plan if the provided assets are sufficient to produce a non-malleable satisfaction
+    pub fn get_plan<P>(self, provider: &P) -> Option<Plan>
+    where
+        P: AssetProvider<DefiniteDescriptorKey>,
+    {
+        let satisfaction = match self {
+            Descriptor::Bare(ref bare) => bare.get_plan_satisfaction(provider),
+            Descriptor::Pkh(ref pkh) => pkh.get_plan_satisfaction(provider),
+            Descriptor::Wpkh(ref wpkh) => wpkh.get_plan_satisfaction(provider),
+            Descriptor::Wsh(ref wsh) => wsh.get_plan_satisfaction(provider),
+            Descriptor::Sh(ref sh) => sh.get_plan_satisfaction(provider),
+            Descriptor::Tr(ref tr) => tr.get_plan_satisfaction(provider),
+        };
+
+        if let satisfy::Witness::Stack(stack) = satisfaction.stack {
+            Some(Plan {
+                descriptor: self,
+                template: stack,
+                absolute_timelock: satisfaction.absolute_timelock.map(Into::into),
+                relative_timelock: satisfaction.relative_timelock,
+            })
+        } else {
+            None
+        }
+    }
+
+    /// Returns a plan if the provided assets are sufficient to produce a malleable satisfaction
+    pub fn get_plan_mall<P>(self, provider: &P) -> Option<Plan>
+    where
+        P: AssetProvider<DefiniteDescriptorKey>,
+    {
+        let satisfaction = match self {
+            Descriptor::Bare(ref bare) => bare.get_plan_satisfaction_mall(provider),
+            Descriptor::Pkh(ref pkh) => pkh.get_plan_satisfaction_mall(provider),
+            Descriptor::Wpkh(ref wpkh) => wpkh.get_plan_satisfaction_mall(provider),
+            Descriptor::Wsh(ref wsh) => wsh.get_plan_satisfaction_mall(provider),
+            Descriptor::Sh(ref sh) => sh.get_plan_satisfaction_mall(provider),
+            Descriptor::Tr(ref tr) => tr.get_plan_satisfaction_mall(provider),
+        };
+
+        if let satisfy::Witness::Stack(stack) = satisfaction.stack {
+            Some(Plan {
+                descriptor: self,
+                template: stack,
+                absolute_timelock: satisfaction.absolute_timelock.map(Into::into),
+                relative_timelock: satisfaction.relative_timelock,
+            })
+        } else {
+            None
+        }
+    }
+}
+
 impl<P, Q> TranslatePk<P, Q> for Descriptor<P>
 where
     P: MiniscriptKey,

src/descriptor/segwitv0.rs

@@ -12,8 +12,11 @@ use bitcoin::{Address, Network, ScriptBuf};
 
 use super::checksum::{self, verify_checksum};
 use super::SortedMultiVec;
+use crate::descriptor::DefiniteDescriptorKey;
 use crate::expression::{self, FromTree};
 use crate::miniscript::context::{ScriptContext, ScriptContextError};
+use crate::miniscript::satisfy::{Placeholder, Satisfaction, Witness};
+use crate::plan::AssetProvider;
 use crate::policy::{semantic, Liftable};
 use crate::prelude::*;
 use crate::util::varint_len;
@@ -192,6 +195,36 @@ impl<Pk: MiniscriptKey + ToPublicKey> Wsh<Pk> {
     }
 }
 
+impl Wsh<DefiniteDescriptorKey> {
+    /// Returns a plan if the provided assets are sufficient to produce a non-malleable satisfaction
+    pub fn get_plan_satisfaction<P>(
+        &self,
+        provider: &P,
+    ) -> Satisfaction<Placeholder<DefiniteDescriptorKey>>
+    where
+        P: AssetProvider<DefiniteDescriptorKey>,
+    {
+        match &self.inner {
+            WshInner::SortedMulti(sm) => sm.build_template(provider),
+            WshInner::Ms(ms) => ms.build_template(provider),
+        }
+    }
+
+    /// Returns a plan if the provided assets are sufficient to produce a malleable satisfaction
+    pub fn get_plan_satisfaction_mall<P>(
+        &self,
+        provider: &P,
+    ) -> Satisfaction<Placeholder<DefiniteDescriptorKey>>
+    where
+        P: AssetProvider<DefiniteDescriptorKey>,
+    {
+        match &self.inner {
+            WshInner::SortedMulti(sm) => sm.build_template(provider),
+            WshInner::Ms(ms) => ms.build_template_mall(provider),
+        }
+    }
+}
+
 /// Wsh Inner
 #[derive(Clone, Ord, PartialOrd, Eq, PartialEq, Hash)]
 pub enum WshInner<Pk: MiniscriptKey> {
@@ -419,6 +452,45 @@ impl<Pk: MiniscriptKey + ToPublicKey> Wpkh<Pk> {
     }
 }
 
+impl Wpkh<DefiniteDescriptorKey> {
+    /// Returns a plan if the provided assets are sufficient to produce a non-malleable satisfaction
+    pub fn get_plan_satisfaction<P>(
+        &self,
+        provider: &P,
+    ) -> Satisfaction<Placeholder<DefiniteDescriptorKey>>
+    where
+        P: AssetProvider<DefiniteDescriptorKey>,
+    {
+        let stack = if provider.lookup_ecdsa_sig(&self.pk) {
+            let stack = vec![
+                Placeholder::EcdsaSigPk(self.pk.clone()),
+                Placeholder::Pubkey(self.pk.clone(), Segwitv0::pk_len(&self.pk)),
+            ];
+            Witness::Stack(stack)
+        } else {
+            Witness::Unavailable
+        };
+
+        Satisfaction {
+            stack,
+            has_sig: true,
+            relative_timelock: None,
+            absolute_timelock: None,
+        }
+    }
+
+    /// Returns a plan if the provided assets are sufficient to produce a malleable satisfaction
+    pub fn get_plan_satisfaction_mall<P>(
+        &self,
+        provider: &P,
+    ) -> Satisfaction<Placeholder<DefiniteDescriptorKey>>
+    where
+        P: AssetProvider<DefiniteDescriptorKey>,
+    {
+        self.get_plan_satisfaction(provider)
+    }
+}
+
 impl<Pk: MiniscriptKey> fmt::Debug for Wpkh<Pk> {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         write!(f, "wpkh({:?})", self.pk)

src/descriptor/sh.rs

@@ -16,8 +16,11 @@ use bitcoin::{script, Address, Network, ScriptBuf};
 
 use super::checksum::{self, verify_checksum};
 use super::{SortedMultiVec, Wpkh, Wsh};
+use crate::descriptor::DefiniteDescriptorKey;
 use crate::expression::{self, FromTree};
 use crate::miniscript::context::ScriptContext;
+use crate::miniscript::satisfy::{Placeholder, Satisfaction};
+use crate::plan::AssetProvider;
 use crate::policy::{semantic, Liftable};
 use crate::prelude::*;
 use crate::util::{varint_len, witness_to_scriptsig};
@@ -419,6 +422,39 @@ impl<Pk: MiniscriptKey + ToPublicKey> Sh<Pk> {
     }
 }
 
+impl Sh<DefiniteDescriptorKey> {
+    /// Returns a plan if the provided assets are sufficient to produce a non-malleable satisfaction
+    pub fn get_plan_satisfaction<P>(
+        &self,
+        provider: &P,
+    ) -> Satisfaction<Placeholder<DefiniteDescriptorKey>>
+    where
+        P: AssetProvider<DefiniteDescriptorKey>,
+    {
+        match &self.inner {
+            ShInner::Wsh(ref wsh) => wsh.get_plan_satisfaction(provider),
+            ShInner::Wpkh(ref wpkh) => wpkh.get_plan_satisfaction(provider),
+            ShInner::SortedMulti(ref smv) => smv.build_template(provider),
+            ShInner::Ms(ref ms) => ms.build_template(provider),
+        }
+    }
+
+    /// Returns a plan if the provided assets are sufficient to produce a malleable satisfaction
+    pub fn get_plan_satisfaction_mall<P>(
+        &self,
+        provider: &P,
+    ) -> Satisfaction<Placeholder<DefiniteDescriptorKey>>
+    where
+        P: AssetProvider<DefiniteDescriptorKey>,
+    {
+        match &self.inner {
+            ShInner::Wsh(ref wsh) => wsh.get_plan_satisfaction_mall(provider),
+            ShInner::Ms(ref ms) => ms.build_template_mall(provider),
+            _ => self.get_plan_satisfaction(provider),
+        }
+    }
+}
+
 impl<Pk: MiniscriptKey> ForEachKey<Pk> for Sh<Pk> {
     fn for_each_key<'a, F: FnMut(&'a Pk) -> bool>(&'a self, pred: F) -> bool {
         match self.inner {

src/descriptor/sortedmulti.rs

@@ -15,6 +15,8 @@ use bitcoin::script;
 use crate::miniscript::context::ScriptContext;
 use crate::miniscript::decode::Terminal;
 use crate::miniscript::limits::MAX_PUBKEYS_PER_MULTISIG;
+use crate::miniscript::satisfy::{Placeholder, Satisfaction};
+use crate::plan::AssetProvider;
 use crate::prelude::*;
 use crate::{
     errstr, expression, miniscript, policy, script_num_size, Error, ForEachKey, Miniscript,
@@ -155,6 +157,16 @@ impl<Pk: MiniscriptKey, Ctx: ScriptContext> SortedMultiVec<Pk, Ctx> {
         ms.satisfy(satisfier)
     }
 
+    /// Attempt to produce a witness template given the assets available
+    pub fn build_template<P>(&self, provider: &P) -> Satisfaction<Placeholder<Pk>>
+    where
+        Pk: ToPublicKey,
+        P: AssetProvider<Pk>,
+    {
+        let ms = Miniscript::from_ast(self.sorted_node()).expect("Multi node typecheck");
+        ms.build_template(provider)
+    }
+
     /// Size, in bytes of the script-pubkey. If this Miniscript is used outside
     /// of segwit (e.g. in a bare or P2SH descriptor), this quantity should be
     /// multiplied by 4 to compute the weight.