Merge rust-bitcoin/rust-bitcoin#4248: Alloc-free (AKA zero-copy) control block

9ea2e9262f Don't use references to `TaprootMerkleBranchBuf` (Martin Habovstiak)
c528f52894 Change `Deref::Target` of `TaprootMerkleBranchBuf` (Martin Habovstiak)
04a4efbe63 Introduce unsized `TaprootMerkleBranch` (Martin Habovstiak)
370c2597c6 Add `as_mut_slice` to `TaprootMerkleBranchBuf` (Martin Habovstiak)
33d75659da Push `merkle_branch` module one level deeper. (Martin Habovstiak)
277045bad7 Add `Buf` suffix to `TaprootMerkleBranch` (Martin Habovstiak)

Pull request description:

  This implements a bunch of changes needed to make `ControlBlock` alloc-free. In particular, this allows constructing `Witness` without the intermediate allocation. It is also a step towards having `P2TrSpend` public.

  Closes #1614

  This also intentionally does **not** address decoding of `ControlBlock` from `Witness` since I'm not sure about the API.

  Rationale for doing the `Buf` rename: while doing it with `Script` was very painful it shouldn't be here since it's not used that often and also we can just backport the first commit with deprecated type alias. I was thinking of having `TaprootMerkleBr` but it'd be inconsistent and the name is silly.

  (Also if anyone is wondering why I did this: I was too exhausted to do more important stuff but felt like doing something nice and easy like this.)

ACKs for top commit:
  tcharding:
    ACK 9ea2e9262f
  apoelstra:
    ACK 9ea2e9262fbc04ea6fad33047de0fc1ead999dc7; successfully ran local tests

Tree-SHA512: c5e3ea61d10fbe0cbce5e900943e3cef77a175a62043c500b3ff6df57a96f00692d80fb1c4dd75bca9a704201baab6ddfcc430b12c7ecabc43968198466fed9d

bitcoin/src/blockdata/witness.rs

@@ -14,8 +14,8 @@ use crate::prelude::Vec;
 #[cfg(doc)]
 use crate::script::ScriptExt as _;
 use crate::taproot::{
-    self, LeafScript, LeafVersion, TAPROOT_ANNEX_PREFIX, TAPROOT_CONTROL_BASE_SIZE,
-    TAPROOT_LEAF_MASK,
+    self, ControlBlock, LeafScript, LeafVersion, TAPROOT_ANNEX_PREFIX, TAPROOT_CONTROL_BASE_SIZE,
+    TAPROOT_LEAF_MASK, TaprootMerkleBranch,
 };
 use crate::Script;
 
@@ -135,6 +135,15 @@ crate::internal_macros::define_extension_trait! {
             witness
         }
 
+        /// Finishes constructing the P2TR script spend witness by pushing the required items.
+        fn push_p2tr_script_spend(&mut self, script: &Script, control_block: &ControlBlock<impl AsRef<TaprootMerkleBranch>>, annex: Option<&[u8]>) {
+            self.push(script.as_bytes());
+            self.push(&*control_block.encode_to_arrayvec());
+            if let Some(annex) = annex {
+                self.push(annex);
+            }
+        }
+
         /// Pushes, as a new element on the witness, an ECDSA signature.
         ///
         /// Pushes the DER encoded signature + sighash_type, requires an allocation.

bitcoin/src/taproot/merkle_branch/borrowed.rs

@@ -0,0 +1,290 @@
+use core::borrow::{Borrow, BorrowMut};
+use internals::slice::SliceExt;
+
+use super::{DecodeError, InvalidMerkleBranchSizeError, InvalidMerkleTreeDepthError, TaprootMerkleBranchBuf, TapNodeHash, TAPROOT_CONTROL_MAX_NODE_COUNT, TAPROOT_CONTROL_NODE_SIZE};
+
+pub use privacy_boundary::TaprootMerkleBranch;
+
+/// Makes sure only the allowed conversions are accessible to external code.
+mod privacy_boundary {
+    use super::*;
+
+    /// The Merkle proof for inclusion of a tree in a Taproot tree hash.
+    #[repr(transparent)]
+    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
+    pub struct TaprootMerkleBranch([TapNodeHash]);
+
+    impl TaprootMerkleBranch {
+        /// Returns a reference to the slice of hashes.
+        #[inline]
+        pub const fn as_slice(&self) -> &[TapNodeHash] { &self.0 }
+
+        /// Returns a reference to the mutable slice of hashes.
+        #[inline]
+        pub fn as_mut_slice(&mut self) -> &mut [TapNodeHash] { &mut self.0 }
+
+        pub(super) const fn from_hashes_unchecked(hashes: &[TapNodeHash]) -> &Self {
+            unsafe {
+                &*(hashes as *const _ as *const Self)
+            }
+        }
+
+        pub(super) fn from_mut_hashes_unchecked(hashes: &mut [TapNodeHash]) -> &mut Self {
+            unsafe {
+                &mut *(hashes as *mut _ as *mut Self)
+            }
+        }
+    }
+}
+
+impl TaprootMerkleBranch {
+    /// Returns an empty branch.
+    pub const fn new() -> &'static Self {
+        Self::from_hashes_unchecked(&[])
+    }
+
+    /// Returns the number of nodes in this Merkle proof.
+    #[inline]
+    pub fn len(&self) -> usize { self.as_slice().len() }
+
+    /// Checks if this Merkle proof is empty.
+    #[inline]
+    pub fn is_empty(&self) -> bool { self.as_slice().is_empty() }
+
+    /// Creates an iterator over the node hashes.
+    #[inline]
+    pub fn iter(&self) -> core::slice::Iter<'_, TapNodeHash> { self.into_iter() }
+
+    /// Creates an iterator over the mutable node hashes.
+    #[inline]
+    pub fn iter_mut(&mut self) -> core::slice::IterMut<'_, TapNodeHash> { self.into_iter() }
+
+    /// Casts `TaprootMerkleBranch` to a byte slice.
+    pub(crate) fn as_bytes(&self) -> &[u8] {
+        let ptr = self.as_slice().as_ptr();
+        let num_bytes = self.len() * TAPROOT_CONTROL_NODE_SIZE;
+        // SAFETY:
+        // The pointer points to memory that's borrowed and the returned slice has the same
+        // lifetime. The alignment is of the types is the same (as checked in the test), the
+        // length is within the bounds - as computed above by multiplication.
+        unsafe { core::slice::from_raw_parts(ptr.cast::<u8>(), num_bytes) }
+    }
+
+    /// Serializes to a writer.
+    ///
+    /// # Returns
+    ///
+    /// The number of bytes written to the writer.
+    pub fn encode<Write: io::Write + ?Sized>(&self, writer: &mut Write) -> io::Result<usize> {
+        let bytes = self.as_bytes();
+        writer.write_all(bytes)?;
+        Ok(bytes.len())
+    }
+
+    /// Zero-copy decodes `bytes` as Taproot Merkle branch.
+    ///
+    /// Note that "decoding" is quite trivial: it only performs appropriate bound checks and casts
+    /// the reference.
+    pub fn decode(bytes: &[u8]) -> Result<&Self, DecodeError> {
+        let (nodes, remainder) = bytes.bitcoin_as_chunks();
+        if remainder.is_empty() {
+            Self::decode_exact(nodes).map_err(Into::into)
+        } else {
+            Err(InvalidMerkleBranchSizeError(bytes.len()).into())
+        }
+    }
+
+    /// Decodes a byte slice that is statically known to be multiple of 32.
+    ///
+    /// This can be used as a building block for other ways of decoding.
+    fn decode_exact(nodes: &[[u8; TAPROOT_CONTROL_NODE_SIZE]]) -> Result<&Self, InvalidMerkleTreeDepthError> {
+        // SAFETY:
+        // The lifetime of the returned reference is the same as the lifetime of the input
+        // reference, the size of `TapNodeHash` is equal to `TAPROOT_CONTROL_NODE_SIZE` and the
+        // alignment of `TapNodeHash` is equal to the alignment of `u8` (see tests below).
+        Self::from_hashes(unsafe { &*(nodes as *const _ as *const [TapNodeHash]) })
+    }
+
+    fn from_hashes(nodes: &[TapNodeHash]) -> Result<&Self, InvalidMerkleTreeDepthError>{
+        if nodes.len() <= TAPROOT_CONTROL_MAX_NODE_COUNT {
+            Ok(Self::from_hashes_unchecked(nodes))
+        } else {
+            Err(InvalidMerkleTreeDepthError(nodes.len()))
+        }
+    }
+}
+
+impl Default for &'_ TaprootMerkleBranch {
+    fn default() -> Self {
+        TaprootMerkleBranch::new()
+    }
+}
+
+impl AsRef<TaprootMerkleBranch> for TaprootMerkleBranch {
+    fn as_ref(&self) -> &TaprootMerkleBranch {
+        self
+    }
+}
+
+impl AsMut<TaprootMerkleBranch> for TaprootMerkleBranch {
+    fn as_mut(&mut self) -> &mut TaprootMerkleBranch {
+        self
+    }
+}
+
+impl AsRef<TaprootMerkleBranch> for TaprootMerkleBranchBuf {
+    fn as_ref(&self) -> &TaprootMerkleBranch {
+        // TaprootMerkleBranchBuf maintains the invariant that the node count is in range.
+        TaprootMerkleBranch::from_hashes_unchecked(self.as_slice())
+    }
+}
+
+impl AsMut<TaprootMerkleBranch> for TaprootMerkleBranchBuf {
+    fn as_mut(&mut self) -> &mut TaprootMerkleBranch {
+        // TaprootMerkleBranchBuf maintains the invariant that the node count is in range.
+        TaprootMerkleBranch::from_mut_hashes_unchecked(self.as_mut_slice())
+    }
+}
+
+impl Borrow<TaprootMerkleBranch> for TaprootMerkleBranchBuf {
+    #[inline]
+    fn borrow(&self) -> &TaprootMerkleBranch { self.as_ref() }
+}
+
+impl BorrowMut<TaprootMerkleBranch> for TaprootMerkleBranchBuf {
+    #[inline]
+    fn borrow_mut(&mut self) -> &mut TaprootMerkleBranch { self.as_mut() }
+}
+
+impl<'a> TryFrom<&'a [TapNodeHash]> for &'a TaprootMerkleBranch {
+    type Error = InvalidMerkleTreeDepthError;
+
+    fn try_from(value: &'a [TapNodeHash]) -> Result<Self, Self::Error> {
+        TaprootMerkleBranch::from_hashes(value)
+    }
+}
+
+macro_rules! impl_from_array {
+    ($($len:expr),* $(,)?) => {
+        $(
+            impl AsRef<TaprootMerkleBranch> for [TapNodeHash; $len] {
+                fn as_ref(&self) -> &TaprootMerkleBranch {
+                    #[allow(unused_comparisons)]
+                    const _: () = { assert!($len <= TAPROOT_CONTROL_MAX_NODE_COUNT) };
+                    // There's a static check to ensure correct macro usage above.
+                    TaprootMerkleBranch::from_hashes_unchecked(self)
+                }
+            }
+
+            impl AsMut<TaprootMerkleBranch> for [TapNodeHash; $len] {
+                fn as_mut(&mut self) -> &mut TaprootMerkleBranch {
+                    #[allow(unused_comparisons)]
+                    const _: () = { assert!($len <= TAPROOT_CONTROL_MAX_NODE_COUNT) };
+                    // There's a static check to ensure correct macro usage above.
+                    TaprootMerkleBranch::from_mut_hashes_unchecked(self)
+                }
+            }
+
+            impl Borrow<TaprootMerkleBranch> for [TapNodeHash; $len] {
+                fn borrow(&self) -> &TaprootMerkleBranch {
+                    self.as_ref()
+                }
+            }
+
+            impl BorrowMut<TaprootMerkleBranch> for [TapNodeHash; $len] {
+                fn borrow_mut(&mut self) -> &mut TaprootMerkleBranch {
+                    self.as_mut()
+                }
+            }
+
+            impl<'a> From<&'a [TapNodeHash; $len]> for &'a TaprootMerkleBranch {
+                #[inline]
+                fn from(branch: &'a [TapNodeHash; $len]) -> Self {
+                    branch.as_ref()
+                }
+            }
+
+            impl<'a> From<&'a mut [TapNodeHash; $len]> for &'a mut TaprootMerkleBranch {
+                #[inline]
+                fn from(branch: &'a mut [TapNodeHash; $len]) -> Self {
+                    branch.as_mut()
+                }
+            }
+        )*
+    }
+}
+
+// Implement for all values [0, 128] inclusive.
+//
+// The reason zero is included is that `TaprootMerkleBranchBuf` doesn't contain the hash of the node
+// that's being proven - it's not needed because the script is already right before control block.
+impl_from_array!(
+    0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25,
+    26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49,
+    50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73,
+    74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97,
+    98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116,
+    117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128
+);
+
+impl AsRef<[TapNodeHash]> for TaprootMerkleBranch {
+    #[inline]
+    fn as_ref(&self) -> &[TapNodeHash] { self.as_slice() }
+}
+
+impl AsMut<[TapNodeHash]> for TaprootMerkleBranch {
+    #[inline]
+    fn as_mut(&mut self) -> &mut [TapNodeHash] { self.as_mut_slice() }
+}
+
+impl Borrow<[TapNodeHash]> for TaprootMerkleBranch {
+    #[inline]
+    fn borrow(&self) -> &[TapNodeHash] { self.as_ref() }
+}
+
+impl BorrowMut<[TapNodeHash]> for TaprootMerkleBranch {
+    #[inline]
+    fn borrow_mut(&mut self) -> &mut [TapNodeHash] { self.as_mut() }
+}
+
+impl alloc::borrow::ToOwned for TaprootMerkleBranch {
+    // It could be argued that this should've been a stack-allocated type.
+    // However such type would be huge and this trait interacts with `Cow`.
+    // If someone wants to pass it around they're better off just always copying rather than using
+    // `Cow`.
+    type Owned = TaprootMerkleBranchBuf;
+
+    fn to_owned(&self) -> Self::Owned {
+        self.into()
+    }
+}
+
+impl<'a> IntoIterator for &'a TaprootMerkleBranch {
+    type IntoIter = core::slice::Iter<'a, TapNodeHash>;
+    type Item = &'a TapNodeHash;
+
+    fn into_iter(self) -> Self::IntoIter {
+        self.as_slice().iter()
+    }
+}
+
+impl<'a> IntoIterator for &'a mut TaprootMerkleBranch {
+    type IntoIter = core::slice::IterMut<'a, TapNodeHash>;
+    type Item = &'a mut TapNodeHash;
+
+    #[inline]
+    fn into_iter(self) -> Self::IntoIter { self.as_mut_slice().iter_mut() }
+}
+
+#[cfg(test)]
+mod tests {
+    #[test]
+    fn alignment() {
+        assert!(core::mem::align_of_val(super::TaprootMerkleBranch::new()) == core::mem::align_of::<u8>());
+    }
+
+    const _: () = {
+        assert!(core::mem::size_of::<super::TapNodeHash>() == super::TAPROOT_CONTROL_NODE_SIZE);
+        assert!(core::mem::align_of::<super::TapNodeHash>() == core::mem::align_of::<u8>());
+    };
+}

bitcoin/src/taproot/merkle_branch/buf.rs

@@ -1,12 +1,12 @@
 // SPDX-License-Identifier: CC0-1.0
 
-//! Contains `TaprootMerkleBranch` and its associated types.
+//! Contains `TaprootMerkleBranchBuf` and its associated types.
 
 use hashes::Hash;
 
 use super::{
-    InvalidMerkleBranchSizeError, InvalidMerkleTreeDepthError, TapNodeHash, TaprootError,
-    TAPROOT_CONTROL_MAX_NODE_COUNT, TAPROOT_CONTROL_NODE_SIZE,
+    InvalidMerkleTreeDepthError, TapNodeHash, TaprootError, TaprootMerkleBranch,
+    TAPROOT_CONTROL_MAX_NODE_COUNT,
 };
 use crate::prelude::{Borrow, BorrowMut, Box, Vec};
 
@@ -15,9 +15,9 @@ use crate::prelude::{Borrow, BorrowMut, Box, Vec};
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[cfg_attr(feature = "serde", serde(into = "Vec<TapNodeHash>"))]
 #[cfg_attr(feature = "serde", serde(try_from = "Vec<TapNodeHash>"))]
-pub struct TaprootMerkleBranch(Vec<TapNodeHash>);
+pub struct TaprootMerkleBranchBuf(Vec<TapNodeHash>);
 
-impl TaprootMerkleBranch {
+impl TaprootMerkleBranchBuf {
     /// Returns a reference to the slice of hashes.
     #[deprecated(since = "0.32.0", note = "use `as_slice` instead")]
     #[inline]
@@ -27,6 +27,10 @@ impl TaprootMerkleBranch {
     #[inline]
     pub fn as_slice(&self) -> &[TapNodeHash] { &self.0 }
 
+    /// Returns a mutable reference to the slice of hashes.
+    #[inline]
+    pub fn as_mut_slice(&mut self) -> &mut [TapNodeHash] { &mut self.0 }
+
     /// Returns the number of nodes in this Merkle proof.
     #[inline]
     pub fn len(&self) -> usize { self.0.len() }
@@ -45,17 +49,7 @@ impl TaprootMerkleBranch {
     /// The function returns an error if the number of bytes is not an integer multiple of 32 or
     /// if the number of hashes exceeds 128.
     pub fn decode(sl: &[u8]) -> Result<Self, TaprootError> {
-        use internals::slice::SliceExt;
-        let (node_hashes, remainder) = sl.bitcoin_as_chunks::<TAPROOT_CONTROL_NODE_SIZE>();
-        if !remainder.is_empty() {
-            Err(InvalidMerkleBranchSizeError(sl.len()).into())
-        } else if node_hashes.len() > TAPROOT_CONTROL_MAX_NODE_COUNT {
-            Err(InvalidMerkleTreeDepthError(sl.len() / TAPROOT_CONTROL_NODE_SIZE).into())
-        } else {
-            let inner = node_hashes.iter().copied().map(TapNodeHash::from_byte_array).collect();
-
-            Ok(TaprootMerkleBranch(inner))
-        }
+        TaprootMerkleBranch::decode(sl).map(alloc::borrow::ToOwned::to_owned).map_err(Into::into)
     }
 
     /// Constructs a new Merkle proof from list of hashes.
@@ -70,7 +64,7 @@ impl TaprootMerkleBranch {
         if collection.as_ref().len() > TAPROOT_CONTROL_MAX_NODE_COUNT {
             Err(InvalidMerkleTreeDepthError(collection.as_ref().len()))
         } else {
-            Ok(TaprootMerkleBranch(collection.into()))
+            Ok(TaprootMerkleBranchBuf(collection.into()))
         }
     }
 
@@ -92,7 +86,7 @@ impl TaprootMerkleBranch {
     }
 
     /// Appends elements to proof.
-    pub(super) fn push(&mut self, h: TapNodeHash) -> Result<(), InvalidMerkleTreeDepthError> {
+    pub(in super::super) fn push(&mut self, h: TapNodeHash) -> Result<(), InvalidMerkleTreeDepthError> {
         if self.len() >= TAPROOT_CONTROL_MAX_NODE_COUNT {
             Err(InvalidMerkleTreeDepthError(self.0.len()))
         } else {
@@ -113,7 +107,7 @@ impl TaprootMerkleBranch {
 
 macro_rules! impl_try_from {
     ($from:ty) => {
-        impl TryFrom<$from> for TaprootMerkleBranch {
+        impl TryFrom<$from> for TaprootMerkleBranchBuf {
             type Error = InvalidMerkleTreeDepthError;
 
             /// Constructs a new Merkle proof from list of hashes.
@@ -123,7 +117,7 @@ macro_rules! impl_try_from {
             /// If inner proof length is more than [`TAPROOT_CONTROL_MAX_NODE_COUNT`] (128).
             #[inline]
             fn try_from(v: $from) -> Result<Self, Self::Error> {
-                TaprootMerkleBranch::from_collection(v)
+                TaprootMerkleBranchBuf::from_collection(v)
             }
         }
     };
@@ -135,7 +129,7 @@ impl_try_from!(Box<[TapNodeHash]>);
 macro_rules! impl_try_from_array {
     ($($len:expr),* $(,)?) => {
         $(
-            impl From<[TapNodeHash; $len]> for TaprootMerkleBranch {
+            impl From<[TapNodeHash; $len]> for TaprootMerkleBranchBuf {
                 #[inline]
                 fn from(a: [TapNodeHash; $len]) -> Self {
                     Self(a.to_vec())
@@ -146,7 +140,7 @@ macro_rules! impl_try_from_array {
 }
 // Implement for all values [0, 128] inclusive.
 //
-// The reason zero is included is that `TaprootMerkleBranch` doesn't contain the hash of the node
+// The reason zero is included is that `TaprootMerkleBranchBuf` doesn't contain the hash of the node
 // that's being proven - it's not needed because the script is already right before control block.
 impl_try_from_array!(
     0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25,
@@ -157,12 +151,12 @@ impl_try_from_array!(
     117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128
 );
 
-impl From<TaprootMerkleBranch> for Vec<TapNodeHash> {
+impl From<TaprootMerkleBranchBuf> for Vec<TapNodeHash> {
     #[inline]
-    fn from(branch: TaprootMerkleBranch) -> Self { branch.0 }
+    fn from(branch: TaprootMerkleBranchBuf) -> Self { branch.0 }
 }
 
-impl IntoIterator for TaprootMerkleBranch {
+impl IntoIterator for TaprootMerkleBranchBuf {
     type IntoIter = IntoIter;
     type Item = TapNodeHash;
 
@@ -170,7 +164,7 @@ impl IntoIterator for TaprootMerkleBranch {
     fn into_iter(self) -> Self::IntoIter { IntoIter(self.0.into_iter()) }
 }
 
-impl<'a> IntoIterator for &'a TaprootMerkleBranch {
+impl<'a> IntoIterator for &'a TaprootMerkleBranchBuf {
     type IntoIter = core::slice::Iter<'a, TapNodeHash>;
     type Item = &'a TapNodeHash;
 
@@ -178,7 +172,7 @@ impl<'a> IntoIterator for &'a TaprootMerkleBranch {
     fn into_iter(self) -> Self::IntoIter { self.0.iter() }
 }
 
-impl<'a> IntoIterator for &'a mut TaprootMerkleBranch {
+impl<'a> IntoIterator for &'a mut TaprootMerkleBranchBuf {
     type IntoIter = core::slice::IterMut<'a, TapNodeHash>;
     type Item = &'a mut TapNodeHash;
 
@@ -186,41 +180,47 @@ impl<'a> IntoIterator for &'a mut TaprootMerkleBranch {
     fn into_iter(self) -> Self::IntoIter { self.0.iter_mut() }
 }
 
-impl core::ops::Deref for TaprootMerkleBranch {
-    type Target = [TapNodeHash];
+impl core::ops::Deref for TaprootMerkleBranchBuf {
+    type Target = TaprootMerkleBranch;
 
     #[inline]
-    fn deref(&self) -> &Self::Target { &self.0 }
+    fn deref(&self) -> &Self::Target { self.as_ref() }
 }
 
-impl core::ops::DerefMut for TaprootMerkleBranch {
+impl core::ops::DerefMut for TaprootMerkleBranchBuf {
     #[inline]
-    fn deref_mut(&mut self) -> &mut Self::Target { &mut self.0 }
+    fn deref_mut(&mut self) -> &mut Self::Target { self.as_mut() }
 }
 
-impl AsRef<[TapNodeHash]> for TaprootMerkleBranch {
+impl AsRef<[TapNodeHash]> for TaprootMerkleBranchBuf {
     #[inline]
     fn as_ref(&self) -> &[TapNodeHash] { &self.0 }
 }
 
-impl AsMut<[TapNodeHash]> for TaprootMerkleBranch {
+impl AsMut<[TapNodeHash]> for TaprootMerkleBranchBuf {
     #[inline]
     fn as_mut(&mut self) -> &mut [TapNodeHash] { &mut self.0 }
 }
 
-impl Borrow<[TapNodeHash]> for TaprootMerkleBranch {
+impl Borrow<[TapNodeHash]> for TaprootMerkleBranchBuf {
     #[inline]
     fn borrow(&self) -> &[TapNodeHash] { &self.0 }
 }
 
-impl BorrowMut<[TapNodeHash]> for TaprootMerkleBranch {
+impl BorrowMut<[TapNodeHash]> for TaprootMerkleBranchBuf {
     #[inline]
     fn borrow_mut(&mut self) -> &mut [TapNodeHash] { &mut self.0 }
 }
 
+impl<'a> From<&'a TaprootMerkleBranch> for TaprootMerkleBranchBuf {
+    fn from(value: &'a TaprootMerkleBranch) -> Self {
+        Self(value.as_slice().into())
+    }
+}
+
 /// Iterator over node hashes within Taproot Merkle branch.
 ///
-/// This is created by `into_iter` method on `TaprootMerkleBranch` (via `IntoIterator` trait).
+/// This is created by `into_iter` method on `TaprootMerkleBranchBuf` (via `IntoIterator` trait).
 #[derive(Clone, Debug)]
 pub struct IntoIter(alloc::vec::IntoIter<TapNodeHash>);
 

bitcoin/src/taproot/merkle_branch/mod.rs

@@ -0,0 +1,67 @@
+//! Contains `TaprootMerkleBranchBuf` and its associated types.
+
+mod buf;
+mod borrowed;
+
+pub use buf::TaprootMerkleBranchBuf;
+pub use borrowed::TaprootMerkleBranch;
+
+use core::fmt;
+use super::{
+    InvalidMerkleBranchSizeError, InvalidMerkleTreeDepthError, TapNodeHash, TaprootError,
+    TAPROOT_CONTROL_MAX_NODE_COUNT, TAPROOT_CONTROL_NODE_SIZE,
+};
+
+/// Returned when decoding of merkle branch fails.
+#[derive(Debug)]
+pub struct DecodeError {
+    /// Represents the invalid number of bytes. It may be invalid in two ways: it might not be a
+    /// multiple of 32, in which case it is guaranteed to be wrong for that reason;
+    /// only if it is a multiple of 32 do we check that it does not exceed 32 * 128, in which case
+    /// it is wrong for that reason.
+    ///
+    /// This error type is used in `Result<&TaprootMerkleBranch, DecodeError>`, so by keeping its
+    /// size down to a single `usize` (by not using enum) and considering the niche optimization on
+    /// the *fat reference* `&TaprootMerkleBranch`, the `Result` will have the same size as just
+    /// `&TaprootMerkleBranch`.
+    num_bytes: usize,
+}
+
+impl From<InvalidMerkleBranchSizeError> for DecodeError {
+    fn from(value: InvalidMerkleBranchSizeError) -> Self {
+        Self {
+            num_bytes: value.0,
+        }
+    }
+}
+
+impl From<InvalidMerkleTreeDepthError> for DecodeError {
+    fn from(value: InvalidMerkleTreeDepthError) -> Self {
+        Self {
+            num_bytes: value.0 * TAPROOT_CONTROL_NODE_SIZE,
+        }
+    }
+}
+
+impl fmt::Display for DecodeError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        if self.num_bytes % TAPROOT_CONTROL_NODE_SIZE == 0 {
+            write!(f, "the Merkle branch has {} nodes which is more than the limit {}", self.num_bytes / TAPROOT_CONTROL_NODE_SIZE, TAPROOT_CONTROL_MAX_NODE_COUNT)
+        } else {
+            write!(f, "the Merkle branch is {} bytes long which is not an integer multiple of {}", self.num_bytes, TAPROOT_CONTROL_NODE_SIZE)
+        }
+    }
+}
+
+#[cfg(feature = "std")]
+impl std::error::Error for DecodeError {}
+
+impl From<DecodeError> for TaprootError {
+    fn from(value: DecodeError) -> Self {
+        if value.num_bytes % TAPROOT_CONTROL_NODE_SIZE == 0 {
+            InvalidMerkleTreeDepthError(value.num_bytes / TAPROOT_CONTROL_NODE_SIZE).into()
+        } else {
+            InvalidMerkleBranchSizeError(value.num_bytes).into()
+        }
+    }
+}

bitcoin/src/taproot/mod.rs

@@ -27,8 +27,12 @@ use crate::{Script, ScriptBuf};
 #[doc(inline)]
 pub use crate::crypto::taproot::{SigFromSliceError, Signature};
 #[doc(inline)]
+pub use merkle_branch::TaprootMerkleBranchBuf;
+#[doc(inline)]
 pub use merkle_branch::TaprootMerkleBranch;
 
+type ControlBlockArrayVec = internals::array_vec::ArrayVec<u8, TAPROOT_CONTROL_MAX_SIZE>;
+
 // Taproot test vectors from BIP-341 state the hashes without any reversing
 sha256t_tag! {
     pub struct TapLeafTag = hash_str("TapLeaf");
@@ -53,6 +57,7 @@ hash_newtype! {
     /// Tagged hash used in Taproot trees.
     ///
     /// See BIP-340 for tagging rules.
+    #[repr(transparent)]
     pub struct TapNodeHash(sha256t::Hash<TapBranchTag>);
 }
 
@@ -190,7 +195,7 @@ pub struct LeafScript<S> {
 }
 
 // type alias for versioned tap script corresponding Merkle proof
-type ScriptMerkleProofMap = BTreeMap<(ScriptBuf, LeafVersion), BTreeSet<TaprootMerkleBranch>>;
+type ScriptMerkleProofMap = BTreeMap<(ScriptBuf, LeafVersion), BTreeSet<TaprootMerkleBranchBuf>>;
 
 /// Represents Taproot spending information.
 ///
@@ -221,7 +226,7 @@ pub struct TaprootSpendInfo {
     output_key_parity: secp256k1::Parity,
     /// The tweaked output key.
     output_key: TweakedPublicKey,
-    /// Map from (script, leaf_version) to (sets of) [`TaprootMerkleBranch`]. More than one control
+    /// Map from (script, leaf_version) to (sets of) [`TaprootMerkleBranchBuf`]. More than one control
     /// block for a given script is only possible if it appears in multiple branches of the tree. In
     /// all cases, keeping one should be enough for spending funds, but we keep all of the paths so
     /// that a full tree can be constructed again from spending data if required.
@@ -1037,7 +1042,7 @@ pub struct LeafNode {
     /// The [`TapLeaf`]
     leaf: TapLeaf,
     /// The Merkle proof (hashing partners) to get this node.
-    merkle_branch: TaprootMerkleBranch,
+    merkle_branch: TaprootMerkleBranchBuf,
 }
 
 impl LeafNode {
@@ -1132,7 +1137,7 @@ impl<'leaf> ScriptLeaf<'leaf> {
 /// Control block data structure used in Tapscript satisfaction.
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
-pub struct ControlBlock {
+pub struct ControlBlock<Branch = TaprootMerkleBranchBuf> where Branch: ?Sized {
     /// The tapleaf version.
     pub leaf_version: LeafVersion,
     /// The parity of the output key (NOT THE INTERNAL KEY WHICH IS ALWAYS XONLY).
@@ -1140,7 +1145,7 @@ pub struct ControlBlock {
     /// The internal key.
     pub internal_key: UntweakedPublicKey,
     /// The Merkle proof of a script associated with this leaf.
-    pub merkle_branch: TaprootMerkleBranch,
+    pub merkle_branch: Branch,
 }
 
 impl ControlBlock {
@@ -1172,14 +1177,16 @@ impl ControlBlock {
             &sl[1..TAPROOT_CONTROL_BASE_SIZE].try_into().expect("Slice should be exactly 32 bytes"),
         )
         .map_err(TaprootError::InvalidInternalKey)?;
-        let merkle_branch = TaprootMerkleBranch::decode(&sl[TAPROOT_CONTROL_BASE_SIZE..])?;
+        let merkle_branch = TaprootMerkleBranchBuf::decode(&sl[TAPROOT_CONTROL_BASE_SIZE..])?;
         Ok(ControlBlock { leaf_version, output_key_parity, internal_key, merkle_branch })
     }
+}
 
+impl<Branch: AsRef<TaprootMerkleBranch> + ?Sized> ControlBlock<Branch> {
     /// Returns the size of control block. Faster and more efficient than calling
     /// `Self::serialize().len()`. Can be handy for fee estimation.
     pub fn size(&self) -> usize {
-        TAPROOT_CONTROL_BASE_SIZE + TAPROOT_CONTROL_NODE_SIZE * self.merkle_branch.len()
+        TAPROOT_CONTROL_BASE_SIZE + TAPROOT_CONTROL_NODE_SIZE * self.merkle_branch.as_ref().len()
     }
 
     /// Serializes to a writer.
@@ -1188,12 +1195,26 @@ impl ControlBlock {
     ///
     /// The number of bytes written to the writer.
     pub fn encode<W: Write + ?Sized>(&self, writer: &mut W) -> io::Result<usize> {
+        self.encode_inner(move |bytes| writer.write_all(bytes))?;
+        Ok(self.size())
+    }
+
+    pub(crate) fn encode_to_arrayvec(&self) -> ControlBlockArrayVec {
+        let mut result = ControlBlockArrayVec::new();
+        self.encode_inner(|bytes| -> Result<(), core::convert::Infallible> {
+            result.extend_from_slice(bytes);
+            Ok(())
+        }).unwrap_or_else(|never| match never {});
+        result
+    }
+
+    fn encode_inner<E>(&self, mut write: impl FnMut(&[u8]) -> Result<(), E>) -> Result<(), E> {
         let first_byte: u8 =
             i32::from(self.output_key_parity) as u8 | self.leaf_version.to_consensus();
-        writer.write_all(&[first_byte])?;
-        writer.write_all(&self.internal_key.serialize())?;
-        self.merkle_branch.encode(writer)?;
-        Ok(self.size())
+        write(&[first_byte])?;
+        write(&self.internal_key.serialize())?;
+        write(self.merkle_branch.as_ref().as_bytes())?;
+        Ok(())
     }
 
     /// Serializes the control block.
@@ -1221,7 +1242,7 @@ impl ControlBlock {
         // Initially the curr_hash is the leaf hash
         let mut curr_hash = TapNodeHash::from_script(script, self.leaf_version);
         // Verify the proof
-        for elem in &self.merkle_branch {
+        for elem in self.merkle_branch.as_ref() {
             // Recalculate the curr hash as parent hash
             curr_hash = TapNodeHash::from_node_hashes(curr_hash, *elem);
         }
@@ -1923,7 +1944,7 @@ mod test {
                 .unwrap()
                 .to_byte_array(),
         );
-        let merkle_branch = TaprootMerkleBranch::from([hash1, hash2]);
+        let merkle_branch = TaprootMerkleBranchBuf::from([hash1, hash2]);
         // use serde_test to test serialization and deserialization
         serde_test::assert_tokens(
             &merkle_branch.readable(),