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.
This commit is contained in:
Erick Cestari 2025-03-31 14:01:14 -03:00
parent 436de8ef12
commit ebaf162a96
1 changed files with 21 additions and 0 deletions

View File

@ -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())
}