From b1490a26ea02b4df914f2e796ea14c9533ccd27b Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Sun, 22 Jan 2023 17:04:58 +1100 Subject: [PATCH 1/2] Move enables_absolute_lock_time method In preparation for deprecating the `is_final` method; move the `enables_absolute_lock_time` method to be directly above the `is_final` method. Refactor only, no logic changes. --- bitcoin/src/blockdata/transaction.rs | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/bitcoin/src/blockdata/transaction.rs b/bitcoin/src/blockdata/transaction.rs index 7815e038..66591a2e 100644 --- a/bitcoin/src/blockdata/transaction.rs +++ b/bitcoin/src/blockdata/transaction.rs @@ -318,6 +318,12 @@ impl Sequence { /// BIP-68 relative lock time type flag mask. const LOCK_TYPE_MASK: u32 = 0x00400000; + /// Returns `true` if the sequence number enables absolute lock-time ([`Transaction::lock_time`]). + #[inline] + pub fn enables_absolute_lock_time(&self) -> bool { + !self.is_final() + } + /// Retuns `true` if the sequence number indicates that the transaction is finalised. /// /// The sequence number being equal to 0xffffffff on all txin sequences indicates @@ -394,12 +400,6 @@ impl Sequence { } } - /// Returns `true` if the sequence number enables absolute lock-time ([`Transaction::lock_time`]). - #[inline] - pub fn enables_absolute_lock_time(&self) -> bool { - !self.is_final() - } - /// Creates a sequence from a u32 value. #[inline] pub fn from_consensus(n: u32) -> Self { From a762a89b48f5a89017e1aa196ae46f161affda26 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Sun, 22 Jan 2023 17:17:47 +1100 Subject: [PATCH 2/2] Add documentation to Sequence::is_final The term "final" is an archaic Bitcoin term however it is well used, it exists in Bitcoin Core code as well as in various bips. To help folks new to Bitcoin add documentation to the `is_final` method including historical notes. --- bitcoin/src/blockdata/transaction.rs | 28 ++++++++++++++++++++++------ 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/bitcoin/src/blockdata/transaction.rs b/bitcoin/src/blockdata/transaction.rs index 66591a2e..e608cd26 100644 --- a/bitcoin/src/blockdata/transaction.rs +++ b/bitcoin/src/blockdata/transaction.rs @@ -321,21 +321,37 @@ impl Sequence { /// Returns `true` if the sequence number enables absolute lock-time ([`Transaction::lock_time`]). #[inline] pub fn enables_absolute_lock_time(&self) -> bool { - !self.is_final() + *self != Sequence::MAX } - /// Retuns `true` if the sequence number indicates that the transaction is finalised. + /// Returns `true` if the sequence number indicates that the transaction is finalized. /// - /// The sequence number being equal to 0xffffffff on all txin sequences indicates - /// that the transaction is finalised. + /// Instead of this method please consider using `!enables_absolute_lock_time` because it + /// is equivalent and improves readability for those not steeped in Bitcoin folklore. + /// + /// ## Historical note + /// + /// The term 'final' is an archaic Bitcoin term, it may have come about because the sequence + /// number in the original Bitcoin code was intended to be incremented in order to replace a + /// transaction, so once the sequence number got to `u64::MAX` it could no longer be increased, + /// hence it was 'final'. + /// + /// + /// Some other references to the term: + /// - `CTxIn::SEQUENCE_FINAL` in the Bitcoin Core code. + /// - [BIP-112]: "BIP 68 prevents a non-final transaction from being selected for inclusion in a + /// block until the corresponding input has reached the specified age" + /// + /// [BIP-112]: #[inline] pub fn is_final(&self) -> bool { - *self == Sequence::MAX + !self.enables_absolute_lock_time() } /// Returns true if the transaction opted-in to BIP125 replace-by-fee. /// - /// Replace by fee is signaled by the sequence being less than 0xfffffffe which is checked by this method. + /// Replace by fee is signaled by the sequence being less than 0xfffffffe which is checked by + /// this method. Note, this is the highest "non-final" value (see [`Sequence::is_final`]). #[inline] pub fn is_rbf(&self) -> bool { *self < Sequence::MIN_NO_RBF