Enum LockTime 

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

Available on crate feature alloc only.

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 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 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_primitives::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_primitives::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 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<Self, PrefixedHexError>

Constructs a new LockTime from a prefixed hex string.

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

Constructs a new LockTime from an unprefixed hex string.

pub fn from_consensus(n: u32) -> Self

Constructs a new 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<Self, ConversionError>

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

Note

If the current block height is h and the locktime is set to h, the transaction can be included in block h+1 or later. It is possible to broadcast the transaction at block height h.

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<Self, ConversionError>

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

Note

If the locktime is set to a timestamp T, the transaction can be included in a block only if the median time past (MTP) of the last 11 blocks is greater than T. It is possible to broadcast the transaction once the MTP is greater than T.[see BIP-113]

BIP-113 Median time-past as endpoint for lock-time calculations

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 (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<'a> Arbitrary<'a> for LockTime

Available on crate feature arbitrary only.

fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self>

Generate an arbitrary value of Self from the given unstructured data.

fn arbitrary_take_rest(u: Unstructured<'a>) -> Result<Self, Error>

Generate an arbitrary value of Self from the entirety of the given unstructured data.

fn size_hint(depth: usize) -> (usize, Option<usize>)

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself.

fn try_size_hint( depth: usize, ) -> Result<(usize, Option<usize>), MaxRecursionReached>

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself.

impl ArbitraryOrd for LockTime

Available on crate feature ordered only.

fn arbitrary_cmp(&self, other: &Self) -> Ordering

Implements a meaningless, arbitrary ordering.

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

Formats the value using the given formatter.

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

Available on crate feature serde only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for LockTime

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

Formats the value using the given formatter.

impl From<Height> for LockTime

fn from(h: Height) -> Self

Converts to this type from the input type.

impl From<Time> for LockTime

fn from(t: Time) -> Self

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<Self, Self::Err>

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

impl Hash for LockTime

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

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

Available on crate feature serde only.

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::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<Self, Self::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<Self, Self::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<Self, Self::Error>

Performs the conversion.

impl Copy for LockTime

impl Eq for LockTime

impl StructuralPartialEq for LockTime