From 3b8164139f6ecebc97b66a299b4a87c2288d8a76 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Thu, 8 May 2025 15:25:52 +1000 Subject: [PATCH] primitives: Add docs section for script hex API In an effort to bring developer attention to the myriad of APIs for parsing and formatting scripts as hex add a section to the rustodcs of `Script` and `ScriptBuf` (same text for both). --- primitives/src/script/borrowed.rs | 8 ++++++++ primitives/src/script/owned.rs | 9 +++++++++ 2 files changed, 17 insertions(+) diff --git a/primitives/src/script/borrowed.rs b/primitives/src/script/borrowed.rs index 59e4585fa..df4e2a3d1 100644 --- a/primitives/src/script/borrowed.rs +++ b/primitives/src/script/borrowed.rs @@ -49,6 +49,14 @@ internals::transparent_newtype! { /// The type is `#[repr(transparent)]` for internal purposes only! /// No consumer crate may rely on the representation of the struct! /// + /// # Hexadecimal strings + /// + /// Scripts are consensus encoded with a length prefix and as a result of this in some places in + /// the eccosystem one will encounter hex strings that include the prefix while in other places + /// the prefix is excluded. To support parsing and formatting scripts as hex we provide a bunch + /// of different APIs and trait implementations. Please see [`examples/script.rs`] for a + /// thorough example of all the APIs. + /// /// # Bitcoin Core References /// /// * [CScript definition](https://github.com/bitcoin/bitcoin/blob/d492dc1cdaabdc52b0766bf4cba4bd73178325d0/src/script/script.h#L410) diff --git a/primitives/src/script/owned.rs b/primitives/src/script/owned.rs index 1732845e0..b76d841d4 100644 --- a/primitives/src/script/owned.rs +++ b/primitives/src/script/owned.rs @@ -16,6 +16,15 @@ use crate::prelude::{Box, Vec}; /// Just as other similar types, this implements [`Deref`], so [deref coercions] apply. Also note /// that all the safety/validity restrictions that apply to [`Script`] apply to `ScriptBuf` as well. /// +/// # Hexadecimal strings +/// +/// Scripts are consensus encoded with a length prefix and as a result of this in some places in the +/// eccosystem one will encounter hex strings that include the prefix while in other places the +/// prefix is excluded. To support parsing and formatting scripts as hex we provide a bunch of +/// different APIs and trait implementations. Please see [`examples/script.rs`] for a thorough +/// example of all the APIs. +/// +/// [`examples/script.rs`]: /// [deref coercions]: https://doc.rust-lang.org/std/ops/trait.Deref.html#more-on-deref-coercion #[derive(Default, Clone, PartialOrd, Ord, PartialEq, Eq, Hash)] pub struct ScriptBuf(Vec);