From ebaf162a962494329c6cb5f6d375a6a4a97fe83b Mon Sep 17 00:00:00 2001 From: Erick Cestari Date: Mon, 31 Mar 2025 14:01:14 -0300 Subject: [PATCH] Add push_relative_lock_time() and deprecate push_sequence() This commit improves the script builder API to better align with Bitcoin semantics when working with relative timelocks: - Add push_relative_lock_time() method that takes a relative::LockTime parameter, which correctly represents the semantic meaning when working with CHECKSEQUENCEVERIFY - Deprecate push_sequence() in favor of push_relative_lock_time() to avoid confusion between sequence numbers and relative timelocks This addresses a potential confusion point in the API where developers might incorrectly push raw sequence numbers in scripts when what they actually need is to push a relative locktime value that will be checked against the transaction's sequence numbers by CHECKSEQUENCEVERIFY. --- bitcoin/src/blockdata/script/builder.rs | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/bitcoin/src/blockdata/script/builder.rs b/bitcoin/src/blockdata/script/builder.rs index b8a52ea91..7efacd10e 100644 --- a/bitcoin/src/blockdata/script/builder.rs +++ b/bitcoin/src/blockdata/script/builder.rs @@ -2,6 +2,8 @@ use core::fmt; +use primitives::relative; + use super::{opcode_to_verify, write_scriptint, Error, PushBytes, Script, ScriptBuf}; use crate::locktime::absolute; use crate::opcodes::all::*; @@ -115,7 +117,26 @@ impl Builder { self.push_int_unchecked(lock_time.to_consensus_u32().into()) } + /// Adds instructions to push a relative lock time onto the stack. + /// + /// This is used when creating scripts that use CHECKSEQUENCEVERIFY (CSV) to enforce + /// relative time locks. + pub fn push_relative_lock_time(self, lock_time: relative::LockTime) -> Builder { + self.push_int_unchecked(lock_time.to_consensus_u32().into()) + } + /// Adds instructions to push a sequence number onto the stack. + /// + /// # Deprecated + /// This method is deprecated in favor of `push_relative_lock_time`. + /// + /// In Bitcoin script semantics, when using CHECKSEQUENCEVERIFY, you typically + /// want to push a relative locktime value to be compared against the input's + /// sequence number, not the sequence number itself. + #[deprecated( + since = "TBD", + note = "Use push_relative_lock_time instead for working with timelocks in scripts" + )] pub fn push_sequence(self, sequence: Sequence) -> Builder { self.push_int_unchecked(sequence.to_consensus_u32().into()) }