Enum miniscript::policy::semantic::Policy

pub enum Policy<Pk: MiniscriptKey> {
    Unsatisfiable,
    Trivial,
    Key(Pk),
    After(AbsLockTime),
    Older(Sequence),
    Sha256(Pk::Sha256),
    Hash256(Pk::Hash256),
    Ripemd160(Pk::Ripemd160),
    Hash160(Pk::Hash160),
    Threshold(usize, Vec<Policy<Pk>>),
}

Abstract policy which corresponds to the semantics of a miniscript and which allows complex forms of analysis, e.g. filtering and normalization.

Semantic policies store only hashes of keys to ensure that objects representing the same policy are lifted to the same abstract Policy, regardless of their choice of pk or pk_h nodes.

Variants

Unsatisfiable

Unsatisfiable.

Trivial

Trivially satisfiable.

Key(Pk)

Signature and public key matching a given hash is required.

After(AbsLockTime)

An absolute locktime restriction.

Older(Sequence)

A relative locktime restriction.

Sha256(Pk::Sha256)

A SHA256 whose preimage must be provided to satisfy the descriptor.

Hash256(Pk::Hash256)

A SHA256d whose preimage must be provided to satisfy the descriptor.

Ripemd160(Pk::Ripemd160)

A RIPEMD160 whose preimage must be provided to satisfy the descriptor.

Hash160(Pk::Hash160)

A HASH160 whose preimage must be provided to satisfy the descriptor.

Threshold(usize, Vec<Policy<Pk>>)

A set of descriptors, satisfactions must be provided for k of them.

Implementations

impl<Pk> Policy<Pk>

where Pk: MiniscriptKey,

pub fn after(n: u32) -> Policy<Pk>

Constructs a Policy::After from n.

Helper function equivalent to Policy::After(absolute::LockTime::from_consensus(n)).

pub fn older(n: u32) -> Policy<Pk>

Construct a Policy::Older from n.

Helper function equivalent to Policy::Older(Sequence::from_consensus(n)).

impl<Pk: MiniscriptKey> Policy<Pk>

pub fn translate_pk<Q, E, T>(&self, t: &mut T) -> Result<Policy<Q>, E>

where T: Translator<Pk, Q, E>, Q: MiniscriptKey,

Converts a policy using one kind of public key to another type of public key.

Examples

use std::collections::HashMap;
use std::str::FromStr;
use miniscript::bitcoin::{hashes::hash160, PublicKey};
use miniscript::{translate_hash_fail, policy::semantic::Policy, Translator};
let alice_pk = "02c79ef3ede6d14f72a00d0e49b4becfb152197b64c0707425c4f231df29500ee7";
let bob_pk = "03d008a849fbf474bd17e9d2c1a827077a468150e58221582ec3410ab309f5afe4";
let placeholder_policy = Policy::<String>::from_str("and(pk(alice_pk),pk(bob_pk))").unwrap();

// Information to translate abstract string type keys to concrete `bitcoin::PublicKey`s.
// In practice, wallets would map from string key names to BIP32 keys.
struct StrPkTranslator {
    pk_map: HashMap<String, bitcoin::PublicKey>
}

// If we also wanted to provide mapping of other associated types (sha256, older etc),
// we would use the general [`Translator`] trait.
impl Translator<String, bitcoin::PublicKey, ()> for StrPkTranslator {
    fn pk(&mut self, pk: &String) -> Result<bitcoin::PublicKey, ()> {
        self.pk_map.get(pk).copied().ok_or(()) // Dummy Err
    }

    // Handy macro for failing if we encounter any other fragment.
    // See also [`translate_hash_clone!`] for cloning instead of failing.
    translate_hash_fail!(String, bitcoin::PublicKey, ());
}

let mut pk_map = HashMap::new();
pk_map.insert(String::from("alice_pk"), bitcoin::PublicKey::from_str(alice_pk).unwrap());
pk_map.insert(String::from("bob_pk"), bitcoin::PublicKey::from_str(bob_pk).unwrap());
let mut t = StrPkTranslator { pk_map };

let real_policy = placeholder_policy.translate_pk(&mut t).unwrap();

let expected_policy = Policy::from_str(&format!("and(pk({}),pk({}))", alice_pk, bob_pk)).unwrap();
assert_eq!(real_policy, expected_policy);

pub fn entails(self, other: Policy<Pk>) -> Result<bool, PolicyError>

Computes whether the current policy entails the second one.

A |- B means every satisfaction of A is also a satisfaction of B.

This implementation will run slowly for larger policies but should be sufficient for most practical policies.

impl<Pk: MiniscriptKey> Policy<Pk>

pub fn normalized(self) -> Policy<Pk>

Flattens out trees of Ands and Ors; eliminate Trivial and Unsatisfiables. Does not reorder any branches; use .sort.

pub fn is_trivial(&self) -> bool

Detects a true/trivial policy.

Only checks whether the policy is Policy::Trivial, to check if the normalized form is trivial, the caller is expected to normalize the policy first.

pub fn is_unsatisfiable(&self) -> bool

Detects a false/unsatisfiable policy.

Only checks whether the policy is Policy::Unsatisfiable, to check if the normalized form is unsatisfiable, the caller is expected to normalize the policy first.

pub fn relative_timelocks(&self) -> Vec<u32>

Returns a list of all relative timelocks, not including 0, which appear in the policy.

pub fn absolute_timelocks(&self) -> Vec<u32>

Returns a list of all absolute timelocks, not including 0, which appear in the policy.

pub fn at_age(self, age: Sequence) -> Policy<Pk>

Filters a policy by eliminating relative timelock constraints that are not satisfied at the given age.

pub fn at_lock_time(self, n: LockTime) -> Policy<Pk>

Filters a policy by eliminating absolute timelock constraints that are not satisfied at the given n (n OP_CHECKLOCKTIMEVERIFY).

pub fn n_keys(&self) -> usize

Counts the number of public keys and keyhashes referenced in a policy. Duplicate keys will be double-counted.

pub fn minimum_n_keys(&self) -> Option<usize>

Counts the minimum number of public keys for which signatures could be used to satisfy the policy.

Returns

Returns None if the policy is not satisfiable.

impl<Pk: MiniscriptKey> Policy<Pk>

pub fn sorted(self) -> Policy<Pk>

“Sorts” a policy to bring it into a canonical form to allow comparisons.

Does not allow policies to be compared for functional equivalence; in general this appears to require Gröbner basis techniques that are not implemented.

Trait Implementations

impl<Pk: Clone + MiniscriptKey> Clone for Policy<Pk>

where Pk::Sha256: Clone, Pk::Hash256: Clone, Pk::Ripemd160: Clone, Pk::Hash160: Clone,

fn clone(&self) -> Policy<Pk>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Pk: MiniscriptKey> Debug for Policy<Pk>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<Pk: MiniscriptKey> Display for Policy<Pk>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<Pk: MiniscriptKey> ForEachKey<Pk> for Policy<Pk>

fn for_each_key<'a, F: FnMut(&'a Pk) -> bool>(&'a self, pred: F) -> bool

Run a predicate on every key in the descriptor, returning whether the predicate returned true for every key

fn for_any_key<'a, F: FnMut(&'a Pk) -> bool>(&'a self, pred: F) -> bool

where Pk: 'a,

Run a predicate on every key in the descriptor, returning whether the predicate returned true for any key

impl<Pk> FromStr for Policy<Pk>

where Pk: MiniscriptKey + FromStr, Pk::Sha256: FromStr, Pk::Hash256: FromStr, Pk::Ripemd160: FromStr, Pk::Hash160: FromStr, <Pk as FromStr>::Err: ToString, <<Pk as MiniscriptKey>::Sha256 as FromStr>::Err: ToString, <<Pk as MiniscriptKey>::Hash256 as FromStr>::Err: ToString, <<Pk as MiniscriptKey>::Ripemd160 as FromStr>::Err: ToString, <<Pk as MiniscriptKey>::Hash160 as FromStr>::Err: ToString,

type Err = Error

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Policy<Pk>, Error>

Parses a string s to return a value of this type.

impl<Pk> FromTree for Policy<Pk>

where Pk: MiniscriptKey + FromStr, Pk::Sha256: FromStr, Pk::Hash256: FromStr, Pk::Ripemd160: FromStr, Pk::Hash160: FromStr, <Pk as FromStr>::Err: ToString, <<Pk as MiniscriptKey>::Sha256 as FromStr>::Err: ToString, <<Pk as MiniscriptKey>::Hash256 as FromStr>::Err: ToString, <<Pk as MiniscriptKey>::Ripemd160 as FromStr>::Err: ToString, <<Pk as MiniscriptKey>::Hash160 as FromStr>::Err: ToString,

fn from_tree(top: &Tree<'_>) -> Result<Policy<Pk>, Error>

Extract a structure from Tree representation

impl<Pk: MiniscriptKey> Liftable<Pk> for Semantic<Pk>

fn lift(&self) -> Result<Semantic<Pk>, Error>

Converts this object into an abstract policy.

impl<Pk: Ord + MiniscriptKey> Ord for Policy<Pk>

where Pk::Sha256: Ord, Pk::Hash256: Ord, Pk::Ripemd160: Ord, Pk::Hash160: Ord,

fn cmp(&self, other: &Policy<Pk>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl<Pk: PartialEq + MiniscriptKey> PartialEq for Policy<Pk>

where Pk::Sha256: PartialEq, Pk::Hash256: PartialEq, Pk::Ripemd160: PartialEq, Pk::Hash160: PartialEq,

fn eq(&self, other: &Policy<Pk>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<Pk: PartialOrd + MiniscriptKey> PartialOrd for Policy<Pk>

where Pk::Sha256: PartialOrd, Pk::Hash256: PartialOrd, Pk::Ripemd160: PartialOrd, Pk::Hash160: PartialOrd,

fn partial_cmp(&self, other: &Policy<Pk>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<Pk: Eq + MiniscriptKey> Eq for Policy<Pk>

where Pk::Sha256: Eq, Pk::Hash256: Eq, Pk::Ripemd160: Eq, Pk::Hash160: Eq,

impl<Pk: MiniscriptKey> StructuralEq for Policy<Pk>

impl<Pk: MiniscriptKey> StructuralPartialEq for Policy<Pk>