Enum bdk_chain::bitcoin::blockdata::locktime::absolute::LockTime

pub enum LockTime {
    Blocks(Height),
    Seconds(Time),
}
Expand description

An absolute lock time value, representing either a block height or a UNIX timestamp (seconds since epoch).

Used for transaction lock time (nLockTime in Bitcoin Core and crate::Transaction::lock_time in this library) and also for the argument to opcode ’OP_CHECKLOCKTIMEVERIFY`.

§Note on ordering

Locktimes may be height- or time-based, and these metrics are incommensurate; there is no total ordering on locktimes. We therefore have implemented PartialOrd but not Ord. For crate::Transaction, which has a locktime field, we implement a total ordering to make it easy to store transactions in sorted data structures, and use the locktime’s 32-bit integer consensus encoding to order it. We also implement [ordered::ArbitraryOrd] if the “ordered” feature is enabled.

§Relevant BIPs

§Examples

// To compare absolute lock times there are various `is_satisfied_*` methods, you may also use:
let is_satisfied = match (n, lock_time) {
    (Blocks(n), Blocks(lock_time)) => n <= lock_time,
    (Seconds(n), Seconds(lock_time)) => n <= lock_time,
    _ => panic!("handle invalid comparison error"),
};

Variants§

§

Blocks(Height)

A block height lock time value.

§Examples

use bitcoin::absolute::LockTime;

let block: u32 = 741521;
let n = LockTime::from_height(block).expect("valid height");
assert!(n.is_block_height());
assert_eq!(n.to_consensus_u32(), block);
§

Seconds(Time)

A UNIX timestamp lock time value.

§Examples

use bitcoin::absolute::LockTime;

let seconds: u32 = 1653195600; // May 22nd, 5am UTC.
let n = LockTime::from_time(seconds).expect("valid time");
assert!(n.is_block_time());
assert_eq!(n.to_consensus_u32(), seconds);

Implementations§

§

impl LockTime

pub const ZERO: LockTime = _

If crate::Transaction::lock_time is set to zero it is ignored, in other words a transaction with nLocktime==0 is able to be included immediately in any block.

pub const SIZE: usize = 4usize

The number of bytes that the locktime contributes to the size of a transaction.

pub fn from_hex(s: &str) -> Result<LockTime, PrefixedHexError>

Creates a LockTime from an prefixed hex string.

pub fn from_unprefixed_hex(s: &str) -> Result<LockTime, UnprefixedHexError>

Creates a LockTime from an unprefixed hex string.

pub fn from_consensus(n: u32) -> LockTime

Constructs a LockTime from an nLockTime value or the argument to OP_CHEKCLOCKTIMEVERIFY.

§Examples

// `from_consensus` roundtrips as expected with `to_consensus_u32`.
let n_lock_time: u32 = 741521;
let lock_time = LockTime::from_consensus(n_lock_time);
assert_eq!(lock_time.to_consensus_u32(), n_lock_time);

pub fn from_height(n: u32) -> Result<LockTime, ConversionError>

Constructs a LockTime from n, expecting n to be a valid block height.

See LOCK_TIME_THRESHOLD for definition of a valid height value.

§Examples
assert!(LockTime::from_height(741521).is_ok());
assert!(LockTime::from_height(1653195600).is_err());

pub fn from_time(n: u32) -> Result<LockTime, ConversionError>

Constructs a LockTime from n, expecting n to be a valid block time.

See LOCK_TIME_THRESHOLD for definition of a valid time value.

§Examples
assert!(LockTime::from_time(1653195600).is_ok());
assert!(LockTime::from_time(741521).is_err());

pub const fn is_same_unit(&self, other: LockTime) -> bool

Returns true if both lock times use the same unit i.e., both height based or both time based.

pub const fn is_block_height(&self) -> bool

Returns true if this lock time value is a block height.

pub const fn is_block_time(&self) -> bool

Returns true if this lock time value is a block time (UNIX timestamp).

pub fn is_satisfied_by(&self, height: Height, time: Time) -> bool

Returns true if this timelock constraint is satisfied by the respective height/time.

If self is a blockheight based lock then it is checked against height and if self is a blocktime based lock it is checked against time.

A ‘timelock constraint’ refers to the n from n OP_CHEKCLOCKTIMEVERIFY, this constraint is satisfied if a transaction with nLockTime (crate::Transaction::lock_time) set to height/time is valid.

§Examples
// Can be implemented if block chain data is available.
fn get_height() -> Height { todo!("return the current block height") }
fn get_time() -> Time { todo!("return the current block time") }

let n = LockTime::from_consensus(741521); // `n OP_CHEKCLOCKTIMEVERIFY`.
if n.is_satisfied_by(get_height(), get_time()) {
    // Can create and mine a transaction that satisfies the OP_CLTV timelock constraint.
}

pub fn is_implied_by(&self, other: LockTime) -> bool

Returns true if satisfaction of other lock time implies satisfaction of this [absolute::LockTime].

A lock time can only be satisfied by n blocks being mined or n seconds passing. If you have two lock times (same unit) then the larger lock time being satisfied implies (in a mathematical sense) the smaller one being satisfied.

This function is useful if you wish to check a lock time against various other locks e.g., filtering out locks which cannot be satisfied. Can also be used to remove the smaller value of two OP_CHECKLOCKTIMEVERIFY operations within one branch of the script.

§Examples
let lock_time = LockTime::from_consensus(741521);
let check = LockTime::from_consensus(741521 + 1);
assert!(lock_time.is_implied_by(check));

pub fn to_consensus_u32(self) -> u32

Returns the inner u32 value. This is the value used when creating this LockTime i.e., n OP_CHECKLOCKTIMEVERIFY or nLockTime.

§Warning

Do not compare values return by this method. The whole point of the LockTime type is to assist in doing correct comparisons. Either use is_satisfied_by, is_satisfied_by_lock, or use the pattern below:

§Examples

let is_satisfied = match (n, lock_time) {
    (Blocks(n), Blocks(lock_time)) => n <= lock_time,
    (Seconds(n), Seconds(lock_time)) => n <= lock_time,
    _ => panic!("invalid comparison"),
};

// Or, if you have Rust 1.53 or greater
// let is_satisfied = n.partial_cmp(&lock_time).expect("invalid comparison").is_le();

Trait Implementations§

§

impl Clone for LockTime

§

fn clone(&self) -> LockTime

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
§

impl Debug for LockTime

§

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

Formats the value using the given formatter. Read more
§

impl Decodable for LockTime

§

fn consensus_decode<R>(r: &mut R) -> Result<LockTime, Error>
where R: Read + ?Sized,

Decode an object with a well-defined format. Read more
§

fn consensus_decode_from_finite_reader<R>(reader: &mut R) -> Result<Self, Error>
where R: Read + ?Sized,

Decode Self from a size-limited reader. Read more
§

impl<'de> Deserialize<'de> for LockTime

§

fn deserialize<D>( deserializer: D ) -> Result<LockTime, <D as Deserializer<'de>>::Error>
where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer. Read more
§

impl Display for LockTime

§

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

Formats the value using the given formatter. Read more
§

impl Encodable for LockTime

§

fn consensus_encode<W>(&self, w: &mut W) -> Result<usize, Error>
where W: Write + ?Sized,

Encodes an object with a well-defined format. Read more
§

impl From<AbsLockTime> for LockTime

§

fn from(lock_time: AbsLockTime) -> LockTime

Converts to this type from the input type.
§

impl From<Height> for LockTime

§

fn from(h: Height) -> LockTime

Converts to this type from the input type.
§

impl From<Time> for LockTime

§

fn from(t: Time) -> LockTime

Converts to this type from the input type.
§

impl FromStr for LockTime

§

type Err = ParseIntError

The associated error which can be returned from parsing.
§

fn from_str(s: &str) -> Result<LockTime, <LockTime as FromStr>::Err>

Parses a string s to return a value of this type. Read more
§

impl Hash for LockTime

§

fn hash<__H>(&self, state: &mut __H)
where __H: Hasher,

Feeds this value into the given Hasher. Read more
1.3.0 · source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
§

impl PartialEq for LockTime

§

fn eq(&self, other: &LockTime) -> bool

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

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 PartialOrd for LockTime

§

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

This method returns an ordering between self and other values if one exists. Read more
1.0.0 · source§

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

This method tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · source§

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

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 · source§

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

This method tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · source§

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

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

impl<Pk> Satisfier<Pk> for LockTime
where Pk: MiniscriptKey + ToPublicKey,

§

fn check_after(&self, n: LockTime) -> bool

Assert whether a absolute locktime is satisfied Read more
§

fn lookup_ecdsa_sig(&self, _: &Pk) -> Option<Signature>

Given a public key, look up an ECDSA signature with that key
§

fn lookup_tap_key_spend_sig(&self) -> Option<Signature>

Lookup the tap key spend sig
§

fn lookup_tap_leaf_script_sig( &self, _: &Pk, _: &TapLeafHash ) -> Option<Signature>

Given a public key and a associated leaf hash, look up an schnorr signature with that key
§

fn lookup_tap_control_block_map( &self ) -> Option<&BTreeMap<ControlBlock, (ScriptBuf, LeafVersion)>>

Obtain a reference to the control block for a ver and script
§

fn lookup_raw_pkh_pk(&self, _: &Hash) -> Option<PublicKey>

Given a raw Pkh, lookup corresponding bitcoin::PublicKey
§

fn lookup_raw_pkh_x_only_pk(&self, _: &Hash) -> Option<XOnlyPublicKey>

Given a raw Pkh, lookup corresponding bitcoin::secp256k1::XOnlyPublicKey
§

fn lookup_raw_pkh_ecdsa_sig(&self, _: &Hash) -> Option<(PublicKey, Signature)>

Given a keyhash, look up the EC signature and the associated key Even if signatures for public key Hashes are not available, the users can use this map to provide pkh -> pk mapping which can be useful for dissatisfying pkh.
§

fn lookup_raw_pkh_tap_leaf_script_sig( &self, _: &(Hash, TapLeafHash) ) -> Option<(XOnlyPublicKey, Signature)>

Given a keyhash, look up the schnorr signature and the associated key Even if signatures for public key Hashes are not available, the users can use this map to provide pkh -> pk mapping which can be useful for dissatisfying pkh.
§

fn lookup_sha256(&self, _: &<Pk as MiniscriptKey>::Sha256) -> Option<[u8; 32]>

Given a SHA256 hash, look up its preimage
§

fn lookup_hash256(&self, _: &<Pk as MiniscriptKey>::Hash256) -> Option<[u8; 32]>

Given a HASH256 hash, look up its preimage
§

fn lookup_ripemd160( &self, _: &<Pk as MiniscriptKey>::Ripemd160 ) -> Option<[u8; 32]>

Given a RIPEMD160 hash, look up its preimage
§

fn lookup_hash160(&self, _: &<Pk as MiniscriptKey>::Hash160) -> Option<[u8; 32]>

Given a HASH160 hash, look up its preimage
§

fn check_older(&self, _: LockTime) -> bool

Assert whether an relative locktime is satisfied Read more
§

impl Serialize for LockTime

§

fn serialize<S>( &self, serializer: S ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>
where S: Serializer,

Serialize this value into the given Serde serializer. Read more
§

impl TryFrom<&str> for LockTime

§

type Error = ParseIntError

The type returned in the event of a conversion error.
§

fn try_from(s: &str) -> Result<LockTime, <LockTime as TryFrom<&str>>::Error>

Performs the conversion.
§

impl TryFrom<Box<str>> for LockTime

§

type Error = ParseIntError

The type returned in the event of a conversion error.
§

fn try_from( s: Box<str> ) -> Result<LockTime, <LockTime as TryFrom<Box<str>>>::Error>

Performs the conversion.
§

impl TryFrom<String> for LockTime

§

type Error = ParseIntError

The type returned in the event of a conversion error.
§

fn try_from(s: String) -> Result<LockTime, <LockTime as TryFrom<String>>::Error>

Performs the conversion.
§

impl Copy for LockTime

§

impl Eq for LockTime

§

impl StructuralPartialEq for LockTime

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
§

impl<T, Pk> AssetProvider<Pk> for T
where T: Satisfier<Pk>, Pk: MiniscriptKey + ToPublicKey,

§

fn provider_lookup_ecdsa_sig(&self, pk: &Pk) -> bool

Given a public key, look up an ECDSA signature with that key, return whether we found it
§

fn provider_lookup_tap_key_spend_sig(&self, _: &Pk) -> Option<usize>

Lookup the tap key spend sig and return its size
§

fn provider_lookup_tap_leaf_script_sig( &self, pk: &Pk, leaf_hash: &TapLeafHash ) -> Option<usize>

Given a public key and a associated leaf hash, look up a schnorr signature with that key and return its size
§

fn provider_lookup_tap_control_block_map( &self ) -> Option<&BTreeMap<ControlBlock, (ScriptBuf, LeafVersion)>>

Obtain a reference to the control block for a ver and script
§

fn provider_lookup_raw_pkh_pk(&self, hash: &Hash) -> Option<PublicKey>

Given a raw Pkh, lookup corresponding bitcoin::PublicKey
§

fn provider_lookup_raw_pkh_x_only_pk( &self, hash: &Hash ) -> Option<XOnlyPublicKey>

Given a raw Pkh, lookup corresponding bitcoin::secp256k1::XOnlyPublicKey
§

fn provider_lookup_raw_pkh_ecdsa_sig(&self, hash: &Hash) -> Option<PublicKey>

Given a keyhash, look up the EC signature and the associated key. Returns the key if a signature is found. Even if signatures for public key Hashes are not available, the users can use this map to provide pkh -> pk mapping which can be useful for dissatisfying pkh.
§

fn provider_lookup_raw_pkh_tap_leaf_script_sig( &self, hash: &(Hash, TapLeafHash) ) -> Option<(XOnlyPublicKey, usize)>

Given a keyhash, look up the schnorr signature and the associated key. Returns the key and sig len if a signature is found. Even if signatures for public key Hashes are not available, the users can use this map to provide pkh -> pk mapping which can be useful for dissatisfying pkh.
§

fn provider_lookup_sha256(&self, hash: &<Pk as MiniscriptKey>::Sha256) -> bool

Given a SHA256 hash, look up its preimage, return whether we found it
§

fn provider_lookup_hash256(&self, hash: &<Pk as MiniscriptKey>::Hash256) -> bool

Given a HASH256 hash, look up its preimage, return whether we found it
§

fn provider_lookup_ripemd160( &self, hash: &<Pk as MiniscriptKey>::Ripemd160 ) -> bool

Given a RIPEMD160 hash, look up its preimage, return whether we found it
§

fn provider_lookup_hash160(&self, hash: &<Pk as MiniscriptKey>::Hash160) -> bool

Given a HASH160 hash, look up its preimage, return whether we found it
§

fn check_older(&self, s: LockTime) -> bool

Assert whether a relative locktime is satisfied
§

fn check_after(&self, l: LockTime) -> bool

Assert whether an absolute locktime is satisfied
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

§

fn equivalent(&self, key: &K) -> bool

Checks if this value is equivalent to the given key. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T> ToString for T
where T: Display + ?Sized,

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

source§

impl<T> DeserializeOwned for T
where T: for<'de> Deserialize<'de>,