From 8ffcd2cf30d3418ae69244f75f948d476b087125 Mon Sep 17 00:00:00 2001
From: Andrew Poelstra <apoelstra@wpsoftware.net>
Date: Thu, 1 May 2025 17:20:54 +0000
Subject: [PATCH] units: rename absolute::Time to absolute::Mtp

This is not a generic UNIX timestamp, but rather a MTP restricted to
have values between 500 million and u32::MAX. Most importantly, it is
*not* a blocktime, which is what is implied by its name and
constructors.
---
 bitcoin/src/blockdata/mod.rs         |  6 +-
 bitcoin/src/blockdata/transaction.rs |  6 +-
 primitives/src/locktime/absolute.rs  | 28 +++++----
 units/src/locktime/absolute.rs       | 85 +++++++++++++++-------------
 units/tests/api.rs                   | 10 ++--
 units/tests/serde.rs                 |  4 +-
 6 files changed, 77 insertions(+), 62 deletions(-)

diff --git a/bitcoin/src/blockdata/mod.rs b/bitcoin/src/blockdata/mod.rs
index ab3b67463..36b4ce410 100644
--- a/bitcoin/src/blockdata/mod.rs
+++ b/bitcoin/src/blockdata/mod.rs
@@ -41,7 +41,11 @@ pub mod locktime {
 
         /// Re-export everything from the `primitives::locktime::absolute` module.
         #[rustfmt::skip]        // Keep public re-exports separate.
-        pub use primitives::locktime::absolute::{ConversionError, Height, LockTime, ParseHeightError, ParseTimeError, Time};
+        pub use primitives::locktime::absolute::{ConversionError, Height, LockTime, ParseHeightError, ParseTimeError, Mtp};
+
+        #[deprecated(since = "TBD", note = "use `Mtp` instead")]
+        #[doc(hidden)]
+        pub type Time = Mtp;
 
         impl Encodable for LockTime {
             #[inline]
diff --git a/bitcoin/src/blockdata/transaction.rs b/bitcoin/src/blockdata/transaction.rs
index 258597247..ff2d7d19a 100644
--- a/bitcoin/src/blockdata/transaction.rs
+++ b/bitcoin/src/blockdata/transaction.rs
@@ -20,7 +20,7 @@ use primitives::Sequence;
 use super::Weight;
 use crate::consensus::{self, encode, Decodable, Encodable};
 use crate::internal_macros::{impl_consensus_encoding, impl_hashencode};
-use crate::locktime::absolute::{self, Height, Time};
+use crate::locktime::absolute::{self, Height, Mtp};
 use crate::prelude::{Borrow, Vec};
 use crate::script::{Script, ScriptBuf, ScriptExt as _, ScriptExtPriv as _};
 #[cfg(doc)]
@@ -295,7 +295,7 @@ pub trait TransactionExt: sealed::Sealed {
     /// By definition if the lock time is not enabled the transaction's absolute timelock is
     /// considered to be satisfied i.e., there are no timelock constraints restricting this
     /// transaction from being mined immediately.
-    fn is_absolute_timelock_satisfied(&self, height: Height, time: Time) -> bool;
+    fn is_absolute_timelock_satisfied(&self, height: Height, time: Mtp) -> bool;
 
     /// Returns `true` if this transactions nLockTime is enabled ([BIP-65]).
     ///
@@ -393,7 +393,7 @@ impl TransactionExt for Transaction {
 
     fn is_explicitly_rbf(&self) -> bool { self.input.iter().any(|input| input.sequence.is_rbf()) }
 
-    fn is_absolute_timelock_satisfied(&self, height: Height, time: Time) -> bool {
+    fn is_absolute_timelock_satisfied(&self, height: Height, time: Mtp) -> bool {
         if !self.is_lock_time_enabled() {
             return true;
         }
diff --git a/primitives/src/locktime/absolute.rs b/primitives/src/locktime/absolute.rs
index d6434ed83..6ea4d3c08 100644
--- a/primitives/src/locktime/absolute.rs
+++ b/primitives/src/locktime/absolute.rs
@@ -16,7 +16,11 @@ use crate::{absolute, Transaction};
 
 #[rustfmt::skip]                // Keep public re-exports separate.
 #[doc(inline)]
-pub use units::locktime::absolute::{ConversionError, Height, ParseHeightError, ParseTimeError, Time, LOCK_TIME_THRESHOLD};
+pub use units::locktime::absolute::{ConversionError, Height, ParseHeightError, ParseTimeError, Mtp, LOCK_TIME_THRESHOLD};
+
+#[deprecated(since = "TBD", note = "use `Mtp` instead")]
+#[doc(hidden)]
+pub type Time = Mtp;
 
 /// An absolute lock time value, representing either a block height or a UNIX timestamp (seconds
 /// since epoch).
@@ -79,7 +83,7 @@ pub enum LockTime {
     /// assert!(n.is_block_time());
     /// assert_eq!(n.to_consensus_u32(), seconds);
     /// ```
-    Seconds(Time),
+    Seconds(Mtp),
 }
 
 impl LockTime {
@@ -143,7 +147,7 @@ impl LockTime {
         if units::locktime::absolute::is_block_height(n) {
             Self::Blocks(Height::from_consensus(n).expect("n is valid"))
         } else {
-            Self::Seconds(Time::from_consensus(n).expect("n is valid"))
+            Self::Seconds(Mtp::from_consensus(n).expect("n is valid"))
         }
     }
 
@@ -192,7 +196,7 @@ impl LockTime {
     /// ```
     #[inline]
     pub fn from_time(n: u32) -> Result<Self, ConversionError> {
-        let time = Time::from_consensus(n)?;
+        let time = Mtp::from_consensus(n)?;
         Ok(LockTime::Seconds(time))
     }
 
@@ -229,7 +233,7 @@ impl LockTime {
     /// # use bitcoin_primitives::absolute;
     /// // Can be implemented if block chain data is available.
     /// fn get_height() -> absolute::Height { todo!("return the current block height") }
-    /// fn get_time() -> absolute::Time { todo!("return the current block time") }
+    /// fn get_time() -> absolute::Mtp { todo!("return the current block time") }
     ///
     /// let n = absolute::LockTime::from_consensus(741521); // `n OP_CHEKCLOCKTIMEVERIFY`.
     /// if n.is_satisfied_by(get_height(), get_time()) {
@@ -237,7 +241,7 @@ impl LockTime {
     /// }
     /// ````
     #[inline]
-    pub fn is_satisfied_by(self, height: Height, time: Time) -> bool {
+    pub fn is_satisfied_by(self, height: Height, time: Mtp) -> bool {
         use LockTime as L;
 
         match self {
@@ -317,9 +321,9 @@ impl From<Height> for LockTime {
     fn from(h: Height) -> Self { LockTime::Blocks(h) }
 }
 
-impl From<Time> for LockTime {
+impl From<Mtp> for LockTime {
     #[inline]
-    fn from(t: Time) -> Self { LockTime::Seconds(t) }
+    fn from(t: Mtp) -> Self { LockTime::Seconds(t) }
 }
 
 impl fmt::Debug for LockTime {
@@ -496,7 +500,7 @@ mod tests {
         let lock_by_height = LockTime::from(height);
 
         let t: u32 = 1_653_195_600; // May 22nd, 5am UTC.
-        let time = Time::from_consensus(t).unwrap();
+        let time = Mtp::from_consensus(t).unwrap();
 
         assert!(!lock_by_height.is_satisfied_by(height_below, time));
         assert!(lock_by_height.is_satisfied_by(height, time));
@@ -505,9 +509,9 @@ mod tests {
 
     #[test]
     fn satisfied_by_time() {
-        let time_before = Time::from_consensus(1_653_109_200).unwrap(); // "May 21th 2022, 5am UTC.
-        let time = Time::from_consensus(1_653_195_600).unwrap(); // "May 22nd 2022, 5am UTC.
-        let time_after = Time::from_consensus(1_653_282_000).unwrap(); // "May 23rd 2022, 5am UTC.
+        let time_before = Mtp::from_consensus(1_653_109_200).unwrap(); // "May 21th 2022, 5am UTC.
+        let time = Mtp::from_consensus(1_653_195_600).unwrap(); // "May 22nd 2022, 5am UTC.
+        let time_after = Mtp::from_consensus(1_653_282_000).unwrap(); // "May 23rd 2022, 5am UTC.
 
         let lock_by_time = LockTime::from(time);
 
diff --git a/units/src/locktime/absolute.rs b/units/src/locktime/absolute.rs
index 71f301e52..07569062b 100644
--- a/units/src/locktime/absolute.rs
+++ b/units/src/locktime/absolute.rs
@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: CC0-1.0
 
-//! Provides [`Height`] and [`Time`] types used by the `rust-bitcoin` `absolute::LockTime` type.
+//! Provides [`Height`] and [`Mtp`] types used by the `rust-bitcoin` `absolute::LockTime` type.
 
 use core::convert::Infallible;
 use core::fmt;
@@ -125,22 +125,29 @@ impl serde::Serialize for Height {
     }
 }
 
-/// A UNIX timestamp, seconds since epoch, guaranteed to always contain a valid time value.
+#[deprecated(since = "TBD", note = "use `Mtp` instead")]
+#[doc(hidden)]
+pub type Time = Mtp;
+
+/// The median timestamp of 11 consecutive blocks, representing "the timestamp" of the
+/// final block for locktime-checking purposes.
 ///
-/// Note that there is no manipulation of the inner value during construction or when using
-/// `to_consensus_u32()`. Said another way, `Time(x)` means 'x seconds since epoch' _not_ '(x -
-/// threshold) seconds since epoch'.
+/// Time-based locktimes are not measured against the timestamps in individual block
+/// headers, since these are not monotone and may be subject to miner manipulation.
+/// Instead, locktimes use the "median-time-past" (MTP) of the most recent 11 blocks,
+/// a quantity which is required by consensus to be monotone and which is difficult
+/// for any individual miner to manipulate.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
-pub struct Time(u32);
+pub struct Mtp(u32);
 
-impl Time {
-    /// The minimum absolute block time (Tue Nov 05 1985 00:53:20 GMT+0000).
-    pub const MIN: Self = Time(LOCK_TIME_THRESHOLD);
+impl Mtp {
+    /// The minimum MTP allowable in a locktime (Tue Nov 05 1985 00:53:20 GMT+0000).
+    pub const MIN: Self = Mtp(LOCK_TIME_THRESHOLD);
 
-    /// The maximum absolute block time (Sun Feb 07 2106 06:28:15 GMT+0000).
-    pub const MAX: Self = Time(u32::MAX);
+    /// The maximum MTP allowable in a locktime (Sun Feb 07 2106 06:28:15 GMT+0000).
+    pub const MAX: Self = Mtp(u32::MAX);
 
-    /// Constructs a new [`Time`] from a hex string.
+    /// Constructs a new [`Mtp`] from a hex string.
     ///
     /// The input string may or may not contain a typical hex prefix e.g., `0x`.
     ///
@@ -158,14 +165,14 @@ impl Time {
     /// # Examples
     ///
     /// ```rust
-    /// use bitcoin_units::locktime::absolute::Time;
+    /// use bitcoin_units::locktime::absolute::Mtp;
     ///
     /// let t: u32 = 1653195600; // May 22nd, 5am UTC.
-    /// let time = Time::from_consensus(t).expect("invalid time value");
+    /// let time = Mtp::from_consensus(t).expect("invalid time value");
     /// assert_eq!(time.to_consensus_u32(), t);
     /// ```
     #[inline]
-    pub const fn from_consensus(n: u32) -> Result<Time, ConversionError> {
+    pub const fn from_consensus(n: u32) -> Result<Mtp, ConversionError> {
         if is_block_time(n) {
             Ok(Self(n))
         } else {
@@ -173,30 +180,30 @@ impl Time {
         }
     }
 
-    /// Converts this [`Time`] to its inner `u32` value.
+    /// Converts this [`Mtp`] to its inner `u32` value.
     #[inline]
     pub const fn to_consensus_u32(self) -> u32 { self.0 }
 }
 
-impl fmt::Display for Time {
+impl fmt::Display for Mtp {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { fmt::Display::fmt(&self.0, f) }
 }
 
-crate::impl_parse_str!(Time, ParseTimeError, parser(Time::from_consensus));
+crate::impl_parse_str!(Mtp, ParseTimeError, parser(Mtp::from_consensus));
 
 #[cfg(feature = "serde")]
-impl<'de> serde::Deserialize<'de> for Time {
+impl<'de> serde::Deserialize<'de> for Mtp {
     fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
     where
         D: serde::Deserializer<'de>,
     {
         let u = u32::deserialize(deserializer)?;
-        Time::from_consensus(u).map_err(serde::de::Error::custom)
+        Mtp::from_consensus(u).map_err(serde::de::Error::custom)
     }
 }
 
 #[cfg(feature = "serde")]
-impl serde::Serialize for Time {
+impl serde::Serialize for Mtp {
     fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
     where
         S: serde::Serializer,
@@ -342,11 +349,11 @@ impl ParseError {
             E::ParseInt(ParseIntError { input, bits: _, is_signed: _, source })
                 if *source.kind() == IntErrorKind::PosOverflow =>
             {
-                // Outputs "failed to parse <input_string> as absolute Height/Time (<subject> is above limit <upper_bound>)"
+                // Outputs "failed to parse <input_string> as absolute Height/Mtp (<subject> is above limit <upper_bound>)"
                 write!(
                     f,
                     "{} ({} is above limit {})",
-                    input.display_cannot_parse("absolute Height/Time"),
+                    input.display_cannot_parse("absolute Height/Mtp"),
                     subject,
                     upper_bound
                 )
@@ -354,17 +361,17 @@ impl ParseError {
             E::ParseInt(ParseIntError { input, bits: _, is_signed: _, source })
                 if *source.kind() == IntErrorKind::NegOverflow =>
             {
-                // Outputs "failed to parse <input_string> as absolute Height/Time (<subject> is below limit <lower_bound>)"
+                // Outputs "failed to parse <input_string> as absolute Height/Mtp (<subject> is below limit <lower_bound>)"
                 write!(
                     f,
                     "{} ({} is below limit {})",
-                    input.display_cannot_parse("absolute Height/Time"),
+                    input.display_cannot_parse("absolute Height/Mtp"),
                     subject,
                     lower_bound
                 )
             }
             E::ParseInt(ParseIntError { input, bits: _, is_signed: _, source: _ }) => {
-                write!(f, "{} ({})", input.display_cannot_parse("absolute Height/Time"), subject)
+                write!(f, "{} ({})", input.display_cannot_parse("absolute Height/Mtp"), subject)
             }
             E::Conversion(value) if *value < i64::from(lower_bound) => {
                 write!(f, "{} {} is below limit {}", subject, value, lower_bound)
@@ -417,17 +424,17 @@ impl<'a> Arbitrary<'a> for Height {
 }
 
 #[cfg(feature = "arbitrary")]
-impl<'a> Arbitrary<'a> for Time {
+impl<'a> Arbitrary<'a> for Mtp {
     fn arbitrary(u: &mut Unstructured<'a>) -> arbitrary::Result<Self> {
         let choice = u.int_in_range(0..=2)?;
         match choice {
-            0 => Ok(Time::MIN),
-            1 => Ok(Time::MAX),
+            0 => Ok(Mtp::MIN),
+            1 => Ok(Mtp::MAX),
             _ => {
-                let min = Time::MIN.to_consensus_u32();
-                let max = Time::MAX.to_consensus_u32();
+                let min = Mtp::MIN.to_consensus_u32();
+                let max = Mtp::MAX.to_consensus_u32();
                 let t = u.int_in_range(min..=max)?;
-                Ok(Time::from_consensus(t).unwrap())
+                Ok(Mtp::from_consensus(t).unwrap())
             }
         }
     }
@@ -442,21 +449,21 @@ mod tests {
 
     #[test]
     fn time_from_str_hex_happy_path() {
-        let actual = Time::from_hex("0x6289C350").unwrap();
-        let expected = Time::from_consensus(0x6289_C350).unwrap();
+        let actual = Mtp::from_hex("0x6289C350").unwrap();
+        let expected = Mtp::from_consensus(0x6289_C350).unwrap();
         assert_eq!(actual, expected);
     }
 
     #[test]
     fn time_from_str_hex_no_prefix_happy_path() {
-        let time = Time::from_hex("6289C350").unwrap();
-        assert_eq!(time, Time(0x6289_C350));
+        let time = Mtp::from_hex("6289C350").unwrap();
+        assert_eq!(time, Mtp(0x6289_C350));
     }
 
     #[test]
     fn time_from_str_hex_invalid_hex_should_err() {
         let hex = "0xzb93";
-        let result = Time::from_hex(hex);
+        let result = Mtp::from_hex(hex);
         assert!(result.is_err());
     }
 
@@ -500,8 +507,8 @@ mod tests {
     #[test]
     #[cfg(feature = "serde")]
     pub fn encode_decode_time() {
-        serde_round_trip!(Time::MIN);
-        serde_round_trip!(Time::MAX);
+        serde_round_trip!(Mtp::MIN);
+        serde_round_trip!(Mtp::MAX);
     }
 
     #[test]
diff --git a/units/tests/api.rs b/units/tests/api.rs
index 46a16e422..475bd5fd2 100644
--- a/units/tests/api.rs
+++ b/units/tests/api.rs
@@ -38,7 +38,7 @@ struct Structs {
     e: BlockInterval,
     f: FeeRate,
     g: absolute::Height,
-    h: absolute::Time,
+    h: absolute::Mtp,
     i: relative::Height,
     j: relative::Time,
     k: Weight,
@@ -55,7 +55,7 @@ impl Structs {
             e: BlockInterval::MAX,
             f: FeeRate::MAX,
             g: absolute::Height::MAX,
-            h: absolute::Time::MAX,
+            h: absolute::Mtp::MAX,
             i: relative::Height::MAX,
             j: relative::Time::MAX,
             k: Weight::MAX,
@@ -85,7 +85,7 @@ struct CommonTraits {
     e: BlockInterval,
     f: FeeRate,
     g: absolute::Height,
-    h: absolute::Time,
+    h: absolute::Mtp,
     i: relative::Height,
     j: relative::Time,
     k: Weight,
@@ -174,7 +174,7 @@ fn api_can_use_all_types_from_module_fee_rate() {
 #[test]
 fn api_can_use_all_types_from_module_locktime_absolute() {
     use bitcoin_units::locktime::absolute::{
-        ConversionError, Height, ParseHeightError, ParseTimeError, Time,
+        ConversionError, Height, Mtp, ParseHeightError, ParseTimeError,
     };
 }
 
@@ -291,7 +291,7 @@ impl<'a> Arbitrary<'a> for Structs {
             e: BlockInterval::arbitrary(u)?,
             f: FeeRate::arbitrary(u)?,
             g: absolute::Height::arbitrary(u)?,
-            h: absolute::Time::arbitrary(u)?,
+            h: absolute::Mtp::arbitrary(u)?,
             i: relative::Height::arbitrary(u)?,
             j: relative::Time::arbitrary(u)?,
             k: Weight::arbitrary(u)?,
diff --git a/units/tests/serde.rs b/units/tests/serde.rs
index d807bcc76..24cf9b047 100644
--- a/units/tests/serde.rs
+++ b/units/tests/serde.rs
@@ -47,7 +47,7 @@ struct Serde {
     a: BlockHeight,
     b: BlockInterval,
     c: absolute::Height,
-    d: absolute::Time,
+    d: absolute::Mtp,
     e: relative::Height,
     f: relative::Time,
     g: Weight,
@@ -80,7 +80,7 @@ impl Serde {
             a: BlockHeight::MAX,
             b: BlockInterval::MAX,
             c: absolute::Height::MAX,
-            d: absolute::Time::MAX,
+            d: absolute::Mtp::MAX,
             e: relative::Height::MAX,
             f: relative::Time::MAX,
             g: Weight::MAX,