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
impl LockTime
pub const ZERO: 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
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>
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>
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
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>
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>
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
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
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
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
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
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
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<'de> Deserialize<'de> for LockTime
impl<'de> Deserialize<'de> for LockTime
§fn deserialize<D>(
deserializer: D
) -> Result<LockTime, <D as Deserializer<'de>>::Error>where
D: Deserializer<'de>,
fn deserialize<D>(
deserializer: D
) -> Result<LockTime, <D as Deserializer<'de>>::Error>where
D: Deserializer<'de>,
§impl PartialOrd for LockTime
impl PartialOrd for LockTime
§fn partial_cmp(&self, other: &LockTime) -> Option<Ordering>
fn partial_cmp(&self, other: &LockTime) -> Option<Ordering>
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read more§impl<Pk> Satisfier<Pk> for LockTimewhere
Pk: MiniscriptKey + ToPublicKey,
impl<Pk> Satisfier<Pk> for LockTimewhere
Pk: MiniscriptKey + ToPublicKey,
§fn check_after(&self, n: LockTime) -> bool
fn check_after(&self, n: LockTime) -> bool
§fn lookup_ecdsa_sig(&self, _: &Pk) -> Option<Signature>
fn lookup_ecdsa_sig(&self, _: &Pk) -> Option<Signature>
§fn lookup_tap_key_spend_sig(&self) -> Option<Signature>
fn lookup_tap_key_spend_sig(&self) -> Option<Signature>
§fn lookup_tap_leaf_script_sig(
&self,
_: &Pk,
_: &TapLeafHash
) -> Option<Signature>
fn lookup_tap_leaf_script_sig( &self, _: &Pk, _: &TapLeafHash ) -> Option<Signature>
§fn lookup_tap_control_block_map(
&self
) -> Option<&BTreeMap<ControlBlock, (ScriptBuf, LeafVersion)>>
fn lookup_tap_control_block_map( &self ) -> Option<&BTreeMap<ControlBlock, (ScriptBuf, LeafVersion)>>
§fn lookup_raw_pkh_pk(&self, _: &Hash) -> Option<PublicKey>
fn lookup_raw_pkh_pk(&self, _: &Hash) -> Option<PublicKey>
Pkh
, lookup corresponding bitcoin::PublicKey
§fn lookup_raw_pkh_x_only_pk(&self, _: &Hash) -> Option<XOnlyPublicKey>
fn lookup_raw_pkh_x_only_pk(&self, _: &Hash) -> Option<XOnlyPublicKey>
Pkh
, lookup corresponding bitcoin::secp256k1::XOnlyPublicKey
§fn lookup_raw_pkh_ecdsa_sig(&self, _: &Hash) -> Option<(PublicKey, Signature)>
fn lookup_raw_pkh_ecdsa_sig(&self, _: &Hash) -> Option<(PublicKey, Signature)>
§fn lookup_raw_pkh_tap_leaf_script_sig(
&self,
_: &(Hash, TapLeafHash)
) -> Option<(XOnlyPublicKey, Signature)>
fn lookup_raw_pkh_tap_leaf_script_sig( &self, _: &(Hash, TapLeafHash) ) -> Option<(XOnlyPublicKey, Signature)>
§fn lookup_sha256(&self, _: &<Pk as MiniscriptKey>::Sha256) -> Option<[u8; 32]>
fn lookup_sha256(&self, _: &<Pk as MiniscriptKey>::Sha256) -> Option<[u8; 32]>
§fn lookup_hash256(&self, _: &<Pk as MiniscriptKey>::Hash256) -> Option<[u8; 32]>
fn lookup_hash256(&self, _: &<Pk as MiniscriptKey>::Hash256) -> Option<[u8; 32]>
§fn lookup_ripemd160(
&self,
_: &<Pk as MiniscriptKey>::Ripemd160
) -> Option<[u8; 32]>
fn lookup_ripemd160( &self, _: &<Pk as MiniscriptKey>::Ripemd160 ) -> Option<[u8; 32]>
§fn lookup_hash160(&self, _: &<Pk as MiniscriptKey>::Hash160) -> Option<[u8; 32]>
fn lookup_hash160(&self, _: &<Pk as MiniscriptKey>::Hash160) -> Option<[u8; 32]>
§fn check_older(&self, _: LockTime) -> bool
fn check_older(&self, _: LockTime) -> bool
§impl Serialize for LockTime
impl Serialize for LockTime
§fn serialize<S>(
&self,
serializer: S
) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>where
S: Serializer,
fn serialize<S>(
&self,
serializer: S
) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>where
S: Serializer,
impl Copy for LockTime
impl Eq for LockTime
impl StructuralPartialEq for LockTime
Auto Trait Implementations§
impl Freeze for LockTime
impl RefUnwindSafe for LockTime
impl Send for LockTime
impl Sync for LockTime
impl Unpin for LockTime
impl UnwindSafe for LockTime
Blanket Implementations§
§impl<T, Pk> AssetProvider<Pk> for Twhere
T: Satisfier<Pk>,
Pk: MiniscriptKey + ToPublicKey,
impl<T, Pk> AssetProvider<Pk> for Twhere
T: Satisfier<Pk>,
Pk: MiniscriptKey + ToPublicKey,
§fn provider_lookup_ecdsa_sig(&self, pk: &Pk) -> bool
fn provider_lookup_ecdsa_sig(&self, pk: &Pk) -> bool
§fn provider_lookup_tap_key_spend_sig(&self, _: &Pk) -> Option<usize>
fn provider_lookup_tap_key_spend_sig(&self, _: &Pk) -> Option<usize>
§fn provider_lookup_tap_leaf_script_sig(
&self,
pk: &Pk,
leaf_hash: &TapLeafHash
) -> Option<usize>
fn provider_lookup_tap_leaf_script_sig( &self, pk: &Pk, leaf_hash: &TapLeafHash ) -> Option<usize>
§fn provider_lookup_tap_control_block_map(
&self
) -> Option<&BTreeMap<ControlBlock, (ScriptBuf, LeafVersion)>>
fn provider_lookup_tap_control_block_map( &self ) -> Option<&BTreeMap<ControlBlock, (ScriptBuf, LeafVersion)>>
§fn provider_lookup_raw_pkh_pk(&self, hash: &Hash) -> Option<PublicKey>
fn provider_lookup_raw_pkh_pk(&self, hash: &Hash) -> Option<PublicKey>
Pkh
, lookup corresponding bitcoin::PublicKey
§fn provider_lookup_raw_pkh_x_only_pk(
&self,
hash: &Hash
) -> Option<XOnlyPublicKey>
fn provider_lookup_raw_pkh_x_only_pk( &self, hash: &Hash ) -> Option<XOnlyPublicKey>
Pkh
, lookup corresponding bitcoin::secp256k1::XOnlyPublicKey