diff --git a/bitcoin/src/blockdata/witness.rs b/bitcoin/src/blockdata/witness.rs index 89b998081..fd57da387 100644 --- a/bitcoin/src/blockdata/witness.rs +++ b/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>, 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. diff --git a/bitcoin/src/taproot/merkle_branch/borrowed.rs b/bitcoin/src/taproot/merkle_branch/borrowed.rs new file mode 100644 index 000000000..58538f09d --- /dev/null +++ b/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::(), num_bytes) } + } + + /// Serializes to a writer. + /// + /// # Returns + /// + /// The number of bytes written to the writer. + pub fn encode(&self, writer: &mut Write) -> io::Result { + 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 for TaprootMerkleBranch { + fn as_ref(&self) -> &TaprootMerkleBranch { + self + } +} + +impl AsMut for TaprootMerkleBranch { + fn as_mut(&mut self) -> &mut TaprootMerkleBranch { + self + } +} + +impl AsRef 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 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 for TaprootMerkleBranchBuf { + #[inline] + fn borrow(&self) -> &TaprootMerkleBranch { self.as_ref() } +} + +impl BorrowMut 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 { + TaprootMerkleBranch::from_hashes(value) + } +} + +macro_rules! impl_from_array { + ($($len:expr),* $(,)?) => { + $( + impl AsRef 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 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 for [TapNodeHash; $len] { + fn borrow(&self) -> &TaprootMerkleBranch { + self.as_ref() + } + } + + impl BorrowMut 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::()); + } + + const _: () = { + assert!(core::mem::size_of::() == super::TAPROOT_CONTROL_NODE_SIZE); + assert!(core::mem::align_of::() == core::mem::align_of::()); + }; +} diff --git a/bitcoin/src/taproot/merkle_branch/buf.rs b/bitcoin/src/taproot/merkle_branch/buf.rs index 657929cd3..1902d9b2a 100644 --- a/bitcoin/src/taproot/merkle_branch/buf.rs +++ b/bitcoin/src/taproot/merkle_branch/buf.rs @@ -5,8 +5,8 @@ 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}; @@ -49,17 +49,7 @@ impl TaprootMerkleBranchBuf { /// 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 { - use internals::slice::SliceExt; - let (node_hashes, remainder) = sl.bitcoin_as_chunks::(); - 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(TaprootMerkleBranchBuf(inner)) - } + TaprootMerkleBranch::decode(sl).map(alloc::borrow::ToOwned::to_owned).map_err(Into::into) } /// Constructs a new Merkle proof from list of hashes. @@ -222,6 +212,12 @@ impl BorrowMut<[TapNodeHash]> for TaprootMerkleBranchBuf { 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 `TaprootMerkleBranchBuf` (via `IntoIterator` trait). diff --git a/bitcoin/src/taproot/merkle_branch/mod.rs b/bitcoin/src/taproot/merkle_branch/mod.rs index 838fe0b6e..0fd32c259 100644 --- a/bitcoin/src/taproot/merkle_branch/mod.rs +++ b/bitcoin/src/taproot/merkle_branch/mod.rs @@ -1,9 +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 for DecodeError { + fn from(value: InvalidMerkleBranchSizeError) -> Self { + Self { + num_bytes: value.0, + } + } +} + +impl From 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 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() + } + } +} diff --git a/bitcoin/src/taproot/mod.rs b/bitcoin/src/taproot/mod.rs index 2c0a29096..619f5edc8 100644 --- a/bitcoin/src/taproot/mod.rs +++ b/bitcoin/src/taproot/mod.rs @@ -28,6 +28,10 @@ use crate::{Script, ScriptBuf}; 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; // Taproot test vectors from BIP-341 state the hashes without any reversing sha256t_tag! { @@ -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); } @@ -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 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: TaprootMerkleBranchBuf, + pub merkle_branch: Branch, } impl ControlBlock { @@ -1175,11 +1180,13 @@ impl ControlBlock { let merkle_branch = TaprootMerkleBranchBuf::decode(&sl[TAPROOT_CONTROL_BASE_SIZE..])?; Ok(ControlBlock { leaf_version, output_key_parity, internal_key, merkle_branch }) } +} +impl + ?Sized> ControlBlock { /// 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(&self, writer: &mut W) -> io::Result { + 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(&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); }