Enum bitcoin::absolute::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<Self, PrefixedHexError>

Creates a LockTime from an prefixed hex string.

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

Creates a LockTime from an unprefixed hex string.

pub fn from_consensus(n: u32) -> Self

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

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

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

Decode an object with a well-defined format.

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

Decode Self from a size-limited reader.

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

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

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

Encodes an object with a well-defined format.

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

fn eq(&self, other: &LockTime) -> 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 PartialOrd<LockTime> 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

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

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, Global>> 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 StructuralEq for LockTime

impl StructuralPartialEq for LockTime