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.
This commit is contained in:
Tobin C. Harding 2023-01-22 17:17:47 +11:00
parent b1490a26ea
commit a762a89b48
No known key found for this signature in database
GPG Key ID: 40BF9E4C269D6607
1 changed files with 22 additions and 6 deletions

View File

@ -321,21 +321,37 @@ impl Sequence {
/// Returns `true` if the sequence number enables absolute lock-time ([`Transaction::lock_time`]). /// Returns `true` if the sequence number enables absolute lock-time ([`Transaction::lock_time`]).
#[inline] #[inline]
pub fn enables_absolute_lock_time(&self) -> bool { 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 /// Instead of this method please consider using `!enables_absolute_lock_time` because it
/// that the transaction is finalised. /// 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]: <https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki>
#[inline] #[inline]
pub fn is_final(&self) -> bool { 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. /// 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] #[inline]
pub fn is_rbf(&self) -> bool { pub fn is_rbf(&self) -> bool {
*self < Sequence::MIN_NO_RBF *self < Sequence::MIN_NO_RBF