Enum miniscript::policy::semantic::Policy

pub enum Policy<Pk: MiniscriptKey> {
    Unsatisfiable,
    Trivial,
    Key(Pk),
    After(PackedLockTime),
    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 Semantic, 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(PackedLockTime)

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>

Construct a Policy::After from n. Helper function equivalent to Policy::After(PackedLockTime::from(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,

Convert a policy using one kind of public key to another type of public key

Example

use miniscript::{bitcoin::{hashes::hash160, PublicKey}, policy::semantic::Policy, Translator};
use miniscript::translate_hash_fail;
use std::str::FromStr;
use std::collections::HashMap;
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 translator abstract String type keys to concrete bitcoin::PublicKey.
// 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.
   // also see 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: 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>

This function 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 slow for larger policies but should be sufficient for most practical policies.

impl<Pk: MiniscriptKey> Policy<Pk>

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

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

pub fn is_trivial(&self) -> bool

Helper function to detect a true/trivial policy This function only checks whether the policy is Policy::Trivial For checking if the normalized form is trivial, the caller is expected to normalize the policy first.

pub fn is_unsatisfiable(&self) -> bool

Helper function to detect a false/unsatisfiable policy This function only checks whether the policy is Policy::Unsatisfiable For checking 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>

Filter 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>

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

pub fn n_keys(&self) -> usize

Count 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>

Count the minimum number of public keys for which signatures could be used to satisfy the policy. Returns None if the policy is not satisfiable.

impl<Pk: MiniscriptKey> Policy<Pk>

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

“Sort” 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) -> boolwhere
    Pk: 'a,

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) -> boolwhere
    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>

Convert the 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) -> Selfwhere
    Self: Sized,

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere
    Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl<Pk: PartialEq + MiniscriptKey> PartialEq<Policy<Pk>> 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<Policy<Pk>> 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>