From 6ce76cd7c88e10036396d44be1659a2e45ee86aa Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Tue, 15 Oct 2024 09:32:31 +1100 Subject: [PATCH] Add unstable constructor to Witness In preparation for moving the `Witness` to `primitives` we need a way to construct the `Witness` when decoding. In order to maintain the current performance and not introduce additional allocations we need to be able to construct a `Witness` from the content buffer, this leaks the implementation details of `Witness`. Add a clearly marked unstable constructor to create a `Witness` from parts. This introduces the concept of `foo__unstable` function names; add a section to the README describing unstable functions and semver guarantees. --- README.md | 7 +++++++ bitcoin/src/blockdata/witness.rs | 16 +++++++++++++++- 2 files changed, 22 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f5e09e65f..806de43bc 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,13 @@ are no plans to do so. Of course, patches to fix specific consensus incompatibil 16-bit pointer sizes are not supported and we can't promise they will be. If you care about them please let us know, so we can know how large the interest is and possibly decide to support them. +### Semver compliance + +We try hard to maintain strict semver compliance with our releases. This codebase includes some +public functions marked unstable (e.g., `pub fn foo__unstable()`). These functions do not adhere to +semver rules; use them at your own discretion. + + ## Documentation Currently can be found on [docs.rs/bitcoin](https://docs.rs/bitcoin/). Patches to add usage examples diff --git a/bitcoin/src/blockdata/witness.rs b/bitcoin/src/blockdata/witness.rs index 07cac752e..6ef97c366 100644 --- a/bitcoin/src/blockdata/witness.rs +++ b/bitcoin/src/blockdata/witness.rs @@ -193,7 +193,8 @@ impl Decodable for Witness { content.truncate(cursor); // Index space is now at the end of the Vec content.rotate_left(witness_index_space); - Ok(Witness { content, witness_elements, indices_start: cursor - witness_index_space }) + let indices_start = cursor - witness_index_space; + Ok(Witness::from_parts__unstable(content, witness_elements, indices_start)) } } } @@ -248,6 +249,19 @@ impl Witness { Witness { content: Vec::new(), witness_elements: 0, indices_start: 0 } } + /// Creates a new [`Witness`] from inner parts. + /// + /// This function leaks implementation details of the `Witness`, as such it is unstable and + /// should not be relied upon (it is primarily provided for use in `rust-bitcoin`). + /// + /// UNSTABLE: This function may change, break, or disappear in any release. + #[inline] + #[doc(hidden)] + #[allow(non_snake_case)] // Because of `__unstable`. + pub fn from_parts__unstable(content: Vec, witness_elements: usize, indices_start: usize) -> Self { + Witness { content, witness_elements, indices_start } + } + /// Creates a witness required to spend a P2WPKH output. /// /// The witness will be made up of the DER encoded signature + sighash_type followed by the