feat(merkle): add private leaves support - Add AddPrivateLeaf method, private leaf constructor, update ToJson, add tests and docs

Author: lukepuplett

docs/merkle/selective-disclosure.md

@@ -282,6 +282,33 @@ Predicate<MerkleLeaf> revealOnlyDateOfBirth = leaf =>
 string ageProof = merkleTree.ToJson(revealOnlyDateOfBirth);
 ```
 
+### Creating Private Leaves
+
+There are two ways to create private leaves in a Merkle tree:
+
+1. **Using AddPrivateLeaf**: Create a leaf that is private from the start:
+```csharp
+// Create a tree with a private leaf
+var tree = new MerkleTree();
+var hash = Hex.Parse("0x1234567890abcdef");
+var privateLeaf = tree.AddPrivateLeaf(hash);
+```
+
+2. **Using Selective Disclosure**: Make existing leaves private during serialization:
+```csharp
+// Create a predicate that makes certain leaves private
+Predicate<MerkleLeaf> makePrivate = leaf =>
+    leaf.TryReadText(out string text) && text.Contains("documentNumber");
+
+// Serialize with selective disclosure
+string json = tree.ToJson(makePrivate);
+```
+
+Both approaches result in leaves that:
+- Only contain their hash in the JSON output
+- Maintain the tree's verifiability
+- Preserve privacy of the leaf's data
+
 ## Conclusion
 
 Our selective disclosure implementation for Merkle trees offers a pragmatic balance between privacy and verifiability. By using a simple predicate-based approach and clean JSON serialization, we've created a solution that's easy to use, efficient to implement, and powerful in its applications.

src/Evoq.Blockchain/Blockchain.Merkle/MerkleLeaf.cs

@@ -1,10 +1,7 @@
-namespace Evoq.Blockchain.Merkle;
-
-using System;
 using System.Collections.Generic;
 using System.Text.Json;
-using Evoq.Blockchain;
 
+namespace Evoq.Blockchain.Merkle;
 /// <summary>
 /// Represents a leaf node in a Merkle tree.
 /// </summary>
@@ -19,12 +16,24 @@ public class MerkleLeaf
     /// <param name="contentType">The MIME content type of the data, including encoding information if applicable.</param>
     public MerkleLeaf(string contentType, Hex data, Hex salt, Hex hash)
     {
-        this.ContentType = contentType;
+        this.ContentType = contentType ?? string.Empty;
         this.Data = data;
         this.Salt = salt;
         this.Hash = hash;
     }
 
+    /// <summary>
+    /// Initializes a new instance of the MerkleLeaf class for a private leaf that only contains a hash.
+    /// </summary>
+    /// <param name="hash">The hash of the leaf.</param>
+    public MerkleLeaf(Hex hash)
+    {
+        this.ContentType = string.Empty;
+        this.Data = Hex.Empty;
+        this.Salt = Hex.Empty;
+        this.Hash = hash;
+    }
+
     //
 
     /// <summary>

src/Evoq.Blockchain/Blockchain.Merkle/MerkleTree.cs

@@ -151,6 +151,18 @@ public void AddLeaf(MerkleLeaf leaf)
         ((List<MerkleLeaf>)this.Leaves).Add(leaf);
     }
 
+    /// <summary>
+    /// Adds a new private leaf to the Merkle tree that only contains a hash.
+    /// </summary>
+    /// <param name="hash">The hash of the leaf.</param>
+    /// <returns>The added leaf.</returns>
+    public MerkleLeaf AddPrivateLeaf(Hex hash)
+    {
+        var leaf = new MerkleLeaf(hash);
+        this.AddLeaf(leaf);
+        return leaf;
+    }
+
     /// <summary>
     /// Verifies that the current root matches the computed root from the leaves.
     /// </summary>
@@ -303,7 +315,7 @@ public string ToJson()
     /// Converts the MerkleTree object to its JSON string representation after verifying the root.
     /// </summary>
     /// <param name="hashFunction">The hash function to use for verification.</param>
-    /// <param name="makePrivate">A predicate to determine if a leaf should be made private.</param>
+    /// <param name="makePrivate">A predicate to determine if a leaf should be made private, in addition to the leaf's own IsPrivate property.</param>
     /// <param name="options">JSON serializer options to customize the output.</param>
     /// <returns>A JSON string representation of the MerkleTree object.</returns>
     /// <exception cref="InvalidRootException">Thrown if the root verification fails.</exception>
@@ -320,17 +332,21 @@ public string ToJson(HashFunction hashFunction, Predicate<MerkleLeaf>? makePriva
         {
             WriteIndented = true,
             PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
-            Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping
+            Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
+            DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull
         };
 
+        // Combine the leaf's IsPrivate property with any additional predicate
+        Predicate<MerkleLeaf> combinedPredicate = leaf => leaf.IsPrivate || (makePrivate?.Invoke(leaf) ?? false);
+
         if (Metadata.Version == MerkleTreeVersionStrings.V1_0)
         {
-            MerkleTreeV1Dto v1 = this.ToV1Dto(makePrivate ?? (leaf => false));
+            MerkleTreeV1Dto v1 = this.ToV1Dto(combinedPredicate);
             return JsonSerializer.Serialize(v1, options);
         }
         else if (Metadata.Version == MerkleTreeVersionStrings.V2_0)
         {
-            MerkleTreeV2Dto v2 = this.ToV2Dto(makePrivate ?? (leaf => false));
+            MerkleTreeV2Dto v2 = this.ToV2Dto(combinedPredicate);
             return JsonSerializer.Serialize(v2, options);
         }
         else

tests/Evoq.Blockchain.Tests/Blockchain.Merkle/MerkleTreeV2Tests.cs

@@ -97,4 +97,82 @@ public void VersionString_ShouldNotBeEscapedInJson()
         Assert.IsFalse(json.Contains("\\u002B"),
             "Plus sign should not be escaped as Unicode in JSON output");
     }
+
+    [TestMethod]
+    public void AddPrivateLeaf_ShouldCreateLeafWithOnlyHash()
+    {
+        // Arrange
+        var tree = new MerkleTree(MerkleTreeVersionStrings.V2_0);
+        var hash = Hex.Parse("0x1234567890abcdef");
+
+        // Act
+        var leaf = tree.AddPrivateLeaf(hash);
+        tree.RecomputeSha256Root();
+
+        // Assert
+        Assert.IsTrue(leaf.IsPrivate, "Private leaf should be marked as private");
+        Assert.AreEqual(hash, leaf.Hash, "Hash should match the provided hash");
+        Assert.IsTrue(leaf.Data.IsEmpty(), "Data should be empty");
+        Assert.IsTrue(leaf.Salt.IsEmpty(), "Salt should be empty");
+        Assert.AreEqual(string.Empty, leaf.ContentType, "Content type should be empty");
+
+        // Verify the leaf is properly serialized
+        string json = tree.ToJson(MerkleTree.ComputeSha256Hash);
+
+        Console.WriteLine(json);
+
+        var jsonDoc = JsonDocument.Parse(json);
+        var leaves = jsonDoc.RootElement.GetProperty("leaves").EnumerateArray().ToArray();
+
+        Assert.AreEqual(1, leaves.Length, "Should have one leaf");
+        var leafJson = leaves[0];
+
+        Assert.IsTrue(leafJson.TryGetProperty("hash", out var hashProp), "Should have hash property");
+        Assert.AreEqual(hash.ToString(), hashProp.GetString(), "Hash should match");
+        Assert.IsFalse(leafJson.TryGetProperty("data", out _), "Should not have data property");
+        Assert.IsFalse(leafJson.TryGetProperty("salt", out _), "Should not have salt property");
+        Assert.IsFalse(leafJson.TryGetProperty("contentType", out _), "Should not have contentType property");
+    }
+
+    [TestMethod]
+    public void RoundTrip_WithPrivateLeaf_ShouldPreservePrivacy()
+    {
+        // Arrange - Create a tree with one private leaf
+        var tree = new MerkleTree(MerkleTreeVersionStrings.V2_0);
+        var hash = Hex.Parse("0x1234567890abcdef");
+        var leaf = tree.AddPrivateLeaf(hash);
+        tree.RecomputeSha256Root();
+
+        // Act - Roundtrip through JSON
+        string json = tree.ToJson();
+        var parsedTree = MerkleTree.Parse(json);
+
+        // Assert
+        Assert.AreEqual(1, parsedTree.Leaves.Count, "Should have one leaf after roundtrip");
+        var roundtrippedLeaf = parsedTree.Leaves[0];
+
+        // Verify the leaf is still private
+        Assert.IsTrue(roundtrippedLeaf.IsPrivate, "Leaf should still be private after roundtrip");
+        Assert.AreEqual(hash, roundtrippedLeaf.Hash, "Hash should be preserved");
+        Assert.IsTrue(roundtrippedLeaf.Data.IsEmpty(), "Data should still be empty");
+        Assert.IsTrue(roundtrippedLeaf.Salt.IsEmpty(), "Salt should still be empty");
+        Assert.AreEqual(string.Empty, roundtrippedLeaf.ContentType, "Content type should be empty.");
+
+        // Verify the tree still validates
+        Assert.IsTrue(parsedTree.VerifySha256Root(), "Tree should still verify after roundtrip");
+
+        // Verify the JSON still only contains the hash
+        string roundtrippedJson = parsedTree.ToJson();
+        var jsonDoc = JsonDocument.Parse(roundtrippedJson);
+        var leaves = jsonDoc.RootElement.GetProperty("leaves").EnumerateArray().ToArray();
+
+        Assert.AreEqual(1, leaves.Length, "Should have one leaf in JSON");
+        var leafJson = leaves[0];
+
+        Assert.IsTrue(leafJson.TryGetProperty("hash", out var hashProp), "Should have hash property");
+        Assert.AreEqual(hash.ToString(), hashProp.GetString(), "Hash should match");
+        Assert.IsFalse(leafJson.TryGetProperty("data", out _), "Should not have data property");
+        Assert.IsFalse(leafJson.TryGetProperty("salt", out _), "Should not have salt property");
+        Assert.IsFalse(leafJson.TryGetProperty("contentType", out _), "Should not have contentType property");
+    }
 }