Merge rust-bitcoin/rust-bitcoin#1575: Add documentation to `Sequence::is_final`

a762a89b48 Add documentation to Sequence::is_final (Tobin C. Harding)
b1490a26ea Move enables_absolute_lock_time method (Tobin C. Harding)

Pull request description:

  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.

  Note, this does _not_ deprecate `is_final` - while writing the notes I found the term "final" in enough official places that I think its fair game to keep the term, some things people just have to learn, we can definitely help with that learning though.

  Fix: #1198

ACKs for top commit:
  Kixunil:
    ACK a762a89b48
  apoelstra:
    ACK a762a89b48

Tree-SHA512: 895fbdce90223d90c0a68fb1e3d6b7aada4a3606d1294ea4df1f4194681a79d970b0434e7bb078f6d5cbf413b3550e72560d6d5cf811a5a959adf53f7f778ab2

bitcoin/src/blockdata/transaction.rs

@@ -318,18 +318,40 @@ impl Sequence {
     /// BIP-68 relative lock time type flag mask.
     const LOCK_TYPE_MASK: u32 = 0x00400000;
 
-    /// Retuns `true` if the sequence number indicates that the transaction is finalised.
+    /// Returns `true` if the sequence number enables absolute lock-time ([`Transaction::lock_time`]).
+    #[inline]
+    pub fn enables_absolute_lock_time(&self) -> bool {
+        *self != Sequence::MAX
+    }
+
+    /// 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]
     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
@@ -394,12 +416,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 {