Add comment explaining push_slice()'s minimality
What the developer wrote
Authored by Nadav Ivgi
Add comment explaining push_slice()'s minimality
Following https://github.com/rust-bitcoin/rust-bitcoin/pull/5385#issuecomment-3637548949
What changed, and why it matters
This commit only adds documentation comments to two Rust source files. It does not change any executable code, so it cannot introduce or fix a security vulnerability by itself. The comments explain an existing behavior of the push_slice() function regarding how small numeric values are encoded in Bitcoin scripts.
No security action required. This is a documentation-only change. Reviewers may optionally verify that the comments accurately describe the existing implementation behavior.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The commit adds identical doc comments to Builder::push_slice() in builder.rs and ScriptBuf::push_slice() in owned.rs. The comments clarify that push_slice() may use numeric opcodes (e.g., OP_0, OP_1) when the pushed data can be exactly represented that way, and that callers who need strict push-only encoding should use push_slice_non_minimal(). The comments also warn that numeric minimality rules are not enforced and that numbers should not have leading zeros. No code logic was modified.
Changed components
bitcoin/src/blockdata/script/builder.rsbitcoin/src/blockdata/script/owned.rsInspect captured patch +20 / −0
diff --git a/bitcoin/src/blockdata/script/builder.rs b/bitcoin/src/blockdata/script/builder.rs
index ac246e4f..44a7a383 100644
--- a/bitcoin/src/blockdata/script/builder.rs
+++ b/bitcoin/src/blockdata/script/builder.rs
@@ -74,6 +74,16 @@ impl<T> Builder<T> {
}
/// Adds instructions to push some arbitrary data onto the stack.
+ ///
+ /// If the data can be exactly produced by a numeric opcode, that opcode
+ /// will be used, since its behavior is equivalent but will not violate minimality
+ /// rules. To avoid this, use [`Builder::push_slice_non_minimal`] which will always
+ /// use a push opcode.
+ ///
+ /// However, this method does *not* enforce any numeric minimality rules.
+ /// If your pushes should be interpreted as numbers, ensure your input does
+ /// not have any leading zeros. In particular, the number 0 should be encoded
+ /// as an empty string rather than as a single 0 byte.
pub fn push_slice<D: AsRef<PushBytes>>(mut self, data: D) -> Self {
self.0.push_slice(data);
self.1 = None;
diff --git a/bitcoin/src/blockdata/script/owned.rs b/bitcoin/src/blockdata/script/owned.rs
index 1d8861c3..b910dced 100644
--- a/bitcoin/src/blockdata/script/owned.rs
+++ b/bitcoin/src/blockdata/script/owned.rs
@@ -74,6 +74,16 @@ internal_macros::define_extension_trait! {
fn push_opcode(&mut self, data: Opcode) { self.as_byte_vec().push(data.to_u8()); }
/// Adds instructions to push some arbitrary data onto the stack.
+ ///
+ /// If the data can be exactly produced by a numeric opcode, that opcode
+ /// will be used, since its behavior is equivalent but will not violate minimality
+ /// rules. To avoid this, use [`ScriptBuf::push_slice_non_minimal`] which will always
+ /// use a push opcode.
+ ///
+ /// However, this method does *not* enforce any numeric minimality rules.
+ /// If your pushes should be interpreted as numbers, ensure your input does
+ /// not have any leading zeros. In particular, the number 0 should be encoded
+ /// as an empty string rather than as a single 0 byte.
fn push_slice<D: AsRef<PushBytes>>(&mut self, data: D) {
let bytes = data.as_ref().as_bytes();
if bytes.len() == 1 {
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.