Improve multi-protocol commitment error types

commit_verify/src/mpc/block.rs

@@ -37,16 +37,43 @@ use crate::mpc::{
 };
 use crate::{Conceal, LIB_NAME_COMMIT_VERIFY};
 
-/// commitment under protocol id {_0} is absent from the known part of a given
+/// commitment under protocol id {0} is absent from the known part of a given
 /// LNPBP-4 Merkle block.
 #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug, Display, Error)]
 #[display(doc_comments)]
 pub struct LeafNotKnown(ProtocolId);
 
-/// attempt to merge unrelated LNPBP-4 proof.
+/// the provided merkle proof protocol id {protocol_id} position {actual}
+/// doesn't match the expected position {expected} within the tree of width
+/// {width}.
 #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug, Display, Error)]
 #[display(doc_comments)]
-pub struct UnrelatedProof;
+#[cfg_attr(
+    feature = "serde",
+    derive(Serialize, Deserialize),
+    serde(crate = "serde_crate", rename_all = "camelCase")
+)]
+pub struct InvalidProof {
+    protocol_id: ProtocolId,
+    expected: u16,
+    actual: u16,
+    width: u16,
+}
+
+#[derive(Copy, Clone, Eq, PartialEq, Hash, Debug, Display, Error, From)]
+#[display(doc_comments)]
+pub enum MergeError {
+    #[from]
+    #[display(inner)]
+    InvalidProof(InvalidProof),
+
+    /// attempt to merge two unrelated LNPBP-4 blocks with different Merkle
+    /// roots (base {base_root}, merged-in {merged_root}).
+    UnrelatedBlocks {
+        base_root: Commitment,
+        merged_root: Commitment,
+    },
+}
 
 /// LNPBP-4 Merkle tree node.
 #[derive(Copy, Clone, PartialEq, Eq, Hash, Debug)]
@@ -164,13 +191,19 @@ impl MerkleBlock {
         proof: &MerkleProof,
         protocol_id: ProtocolId,
         message: Message,
-    ) -> Result<Self, UnrelatedProof> {
+    ) -> Result<Self, InvalidProof> {
         let path = proof.as_path();
         let mut pos = proof.pos;
         let mut width = proof.width() as u16;
 
-        if protocol_id_pos(protocol_id, width) != pos {
-            return Err(UnrelatedProof);
+        let expected = protocol_id_pos(protocol_id, width);
+        if expected != pos {
+            return Err(InvalidProof {
+                protocol_id,
+                expected,
+                actual: pos,
+                width,
+            });
         }
 
         let mut dir = Vec::with_capacity(path.len());
@@ -338,20 +371,22 @@ impl MerkleBlock {
         proof: &MerkleProof,
         protocol_id: ProtocolId,
         message: Message,
-    ) -> Result<u16, UnrelatedProof> {
+    ) -> Result<u16, MergeError> {
         let block = MerkleBlock::with(proof, protocol_id, message)?;
         self.merge_reveal(block)
     }
 
     /// Merges two merkle blocks together, joining revealed information from
     /// each one of them.
-    pub fn merge_reveal(&mut self, other: MerkleBlock) -> Result<u16, UnrelatedProof> {
+    pub fn merge_reveal(&mut self, other: MerkleBlock) -> Result<u16, MergeError> {
         let orig = self.clone();
-
         let base_root = self.commitment_id();
-
-        if base_root != other.commitment_id() {
-            return Err(UnrelatedProof);
+        let merged_root = other.commitment_id();
+        if base_root != merged_root {
+            return Err(MergeError::UnrelatedBlocks {
+                base_root,
+                merged_root,
+            });
         }
 
         let mut cross_section =
@@ -580,7 +615,7 @@ impl MerkleProof {
         &self,
         protocol_id: ProtocolId,
         message: Message,
-    ) -> Result<Commitment, UnrelatedProof> {
+    ) -> Result<Commitment, InvalidProof> {
         let block = MerkleBlock::with(self, protocol_id, message)?;
         Ok(block.commitment_id())
     }

commit_verify/src/mpc/mod.rs

@@ -28,7 +28,7 @@ mod tree;
 mod block;
 
 pub use atoms::{Commitment, Leaf, MerkleBuoy, Message, MessageMap, MultiSource, ProtocolId};
-pub use block::{LeafNotKnown, MerkleBlock, MerkleProof, UnrelatedProof};
+pub use block::{InvalidProof, LeafNotKnown, MergeError, MerkleBlock, MerkleProof};
 #[cfg(feature = "rand")]
 pub use tree::Error;
 pub use tree::MerkleTree;