From a762a89b48f5a89017e1aa196ae46f161affda26 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Sun, 22 Jan 2023 17:17:47 +1100 Subject: [PATCH] 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