Enum bitcoin::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

Because 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.

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 = LockTime::Blocks(Height::ZERO)

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 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, Error>

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, Error>

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 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 fn is_block_height(&self) -> bool

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

pub 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();