Enum LockTime

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

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

• BIP-65 OP_CHECKLOCKTIMEVERIFY
• BIP-113 Median time-past as endpoint for lock-time calculations

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<Pk> Satisfier<Pk> for LockTime

where Pk: MiniscriptKey + ToPublicKey,

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

Assert whether a absolute locktime is satisfied

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

impl Clone for LockTime

fn clone(&self) -> LockTime

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for LockTime

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

Formats the value using the given formatter.

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.

fn consensus_decode_from_finite_reader<R>(reader: &mut R) -> Result<Self, Error>

where R: Read + ?Sized,

Decode Self from a size-limited reader.

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.

impl Display for LockTime

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

Formats the value using the given formatter.

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.

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.

impl Hash for LockTime

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

where __H: Hasher,

Feeds this value into the given Hasher.

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

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for LockTime

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

Tests for self and other values to be equal, and is used by ==.

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

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.

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

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.

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