Merge rust-bitcoin/rust-bitcoin#7050: bitcoin: Correct script integer decoding documentation
What changed, and why it matters
This commit only fixes incorrect documentation comments for two functions that decode script integers. The actual code behavior did not change; only the explanatory text was corrected to match what the code already does.
No security action needed; this is a documentation-only correction.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The patch updates doc comments in bitcoin/src/blockdata/script/push_bytes.rs for read_scriptint, read_cltv_scriptint, and ScriptIntError::NumericOverflow. It clarifies that read_scriptint accepts at most four bytes (range [-2^31+1, 2^31-1]) and read_cltv_scriptint accepts at most five bytes (range [-2^39+1, 2^39-1]), and that NumericOverflow means the encoding exceeds the method’s byte-length limit. No executable code was modified.
Changed components
bitcoin/src/blockdata/script/push_bytes.rs documentationInspect captured patch +12 / −15
### bitcoin/src/blockdata/script/push_bytes.rs
@@ -14,41 +14,37 @@ pub use primitives::script::{PushBytes, PushBytesBuf, PushBytesErrorReport};
crate::internal_macros::define_extension_trait! {
/// Extension functionality for the [`PushBytes`] type.
pub trait PushBytesExt impl for PushBytes {
- /// Decodes an integer in script(minimal CScriptNum) format.
+ /// Decodes a minimally encoded script integer using at most four bytes.
+ ///
+ /// The signed-magnitude encoding supports values in the range `[-2^31 + 1, 2^31 - 1]`.
///
/// This code is based on the
/// [`CScriptNum` constructor in Bitcoin Core](https://github.com/bitcoin/bitcoin/blob/99a4ddf5ab1b3e514d08b90ad8565827fda7b63b/src/script/script.h#L245)
///
/// # Errors
///
- /// * [`ScriptIntError::NumericOverflow`] if result is not in range [-2^39 +1...2^39 -1].
+ /// * [`ScriptIntError::NumericOverflow`] if the encoding is longer than four bytes.
/// * [`ScriptIntError::NonMinimal`] if encoding is non-minimal.
fn read_scriptint(&self) -> Result<i32, ScriptIntError> {
// Cast is safe, since the function already checks for byte length > 4
let ret = read_scriptint_internal(self, 4)?;
Ok(i32::try_from(ret).expect("4 bytes or less fits in an i32"))
}
- /// Decodes an integer in script(minimal CScriptNum) format.
+ /// Decodes a minimally encoded script integer using at most five bytes.
///
/// This is suitable to read input values for CHECKLOCKTIMEVERIFY instructions.
///
- /// Notice that this fails on overflow: the result is the same as in bitcoind, that only 4-byte
- /// signed-magnitude values may be read as numbers. They can be added or subtracted (and a long
- /// time ago, multiplied and divided), and this may result in numbers which can't be written out
- /// in 4 bytes or less. This is ok! The number just can't be read as a number again. This is a
- /// bit crazy and subtle, but it makes sense: you can load 32-bit numbers and do anything with
- /// them, which back when mult/div was allowed, could result in up to a 64-bit number. We don't
- /// want overflow since that's surprising --- and we don't want numbers that don't fit in 64
- /// bits (for efficiency on modern processors). This function will return any value up to 40
- /// bits in length. This is basically a ranged type implementation.
+ /// Unlike [`Self::read_scriptint`], this accepts signed-magnitude encodings of up to five
+ /// bytes, supporting values in the range `[-2^39 + 1, 2^39 - 1]`. The extra byte allows
+ /// positive lock times that require more than 31 bits.
///
/// This code is based on the
/// [`CScriptNum` constructor in Bitcoin Core](https://github.com/bitcoin/bitcoin/blob/99a4ddf5ab1b3e514d08b90ad8565827fda7b63b/src/script/script.h#L245)
///
/// # Errors
///
- /// * [`ScriptIntError::NumericOverflow`] if result is not in range [-2^39 +1...2^39 -1].
+ /// * [`ScriptIntError::NumericOverflow`] if the encoding is longer than five bytes.
/// * [`ScriptIntError::NonMinimal`] if encoding is non-minimal.
fn read_cltv_scriptint(&self) -> Result<i64, ScriptIntError> {
read_scriptint_internal(self, 5)
@@ -92,11 +88,12 @@ mod sealed {
impl Sealed for super::PushBytes {}
}
-/// Possible errors that can arise from [`PushBytes::read_scriptint`].
+/// Possible errors that can arise from [`PushBytes::read_scriptint`] or
+/// [`PushBytes::read_cltv_scriptint`].
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum ScriptIntError {
- /// The result is not in range [-2^31 +1...2^31 -1].
+ /// The encoding exceeds the byte-length limit of the decoding method.
NumericOverflow,
/// The resulting encoding is non-minimal.
NonMinimal,Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.