Support MerkleTree v3.0: Add V3 DTOs, serialization, parsing, and tests

- Add support for MerkleTree version 3.0 with JWT-style header and protected header leaf.
- Implement `MerkleTreeV3Dto`, `MerkleTreeV3LeafDto`, `MerkleTreeV3HeaderDto`, and `MerkleTreeV3LeafHeaderDto` for v3.0 serialization/deserialization.
- Update `MerkleTree` to handle v3.0 in `ToJson`, `Parse`, and root computation, including header leaf logic and exchange document type.
- Add `ExchangeDocumentType` to `MerkleMetadata` and update version constants.
- Add `InvalidLeafHashException` for leaf hash validation errors.
- Refactor `MerkleLeaf` to use a shared hash function utility.
- Update v2.0 DTOs to use `JsonPropertyName` attributes for consistency.
- Add comprehensive tests for v3.0 in `MerkleTreeV3Tests.cs`, including roundtrip, tampering, header protection, and privacy scenarios.

Author: lukepuplett

.vscode/launch.json

@@ -0,0 +1,26 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            // Use IntelliSense to find out which attributes exist for C# debugging
+            // Use hover for the description of the existing attributes
+            // For further information visit https://github.com/dotnet/vscode-csharp/blob/main/debugger-launchjson.md
+            "name": ".NET Core Launch (console)",
+            "type": "coreclr",
+            "request": "launch",
+            "preLaunchTask": "build",
+            // If you have changed target frameworks, make sure to update the program path.
+            "program": "${workspaceFolder}/tests/Evoq.Blockchain.Tests/bin/Debug/net7.0/Evoq.Blockchain.Tests.dll",
+            "args": [],
+            "cwd": "${workspaceFolder}/tests/Evoq.Blockchain.Tests",
+            // For more information about the 'console' field, see https://aka.ms/VSCode-CS-LaunchJson-Console
+            "console": "internalConsole",
+            "stopAtEntry": false
+        },
+        {
+            "name": ".NET Core Attach",
+            "type": "coreclr",
+            "request": "attach"
+        }
+    ]
+}

.vscode/tasks.json

@@ -0,0 +1,41 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "build",
+            "command": "dotnet",
+            "type": "process",
+            "args": [
+                "build",
+                "${workspaceFolder}/Evoq.Blockchain.sln",
+                "/property:GenerateFullPaths=true",
+                "/consoleloggerparameters:NoSummary;ForceNoAlign"
+            ],
+            "problemMatcher": "$msCompile"
+        },
+        {
+            "label": "publish",
+            "command": "dotnet",
+            "type": "process",
+            "args": [
+                "publish",
+                "${workspaceFolder}/Evoq.Blockchain.sln",
+                "/property:GenerateFullPaths=true",
+                "/consoleloggerparameters:NoSummary;ForceNoAlign"
+            ],
+            "problemMatcher": "$msCompile"
+        },
+        {
+            "label": "watch",
+            "command": "dotnet",
+            "type": "process",
+            "args": [
+                "watch",
+                "run",
+                "--project",
+                "${workspaceFolder}/Evoq.Blockchain.sln"
+            ],
+            "problemMatcher": "$msCompile"
+        }
+    ]
+}

src/Evoq.Blockchain/Blockchain.Merkle/InvalidRootException.cs

@@ -41,4 +41,44 @@ public InvalidRootException(string message, Exception innerException) : base(mes
     protected InvalidRootException(SerializationInfo info, StreamingContext context) : base(info, context)
     {
     }
+}
+
+/// <summary>
+/// Exception thrown when the hash of a leaf does not match the computed hash.
+/// </summary>
+[Serializable]
+public class InvalidLeafHashException : Exception
+{
+    /// <summary>
+    /// Initializes a new instance of the InvalidLeafHashException class.
+    /// </summary>
+    public InvalidLeafHashException()
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the InvalidLeafHashException class with a specified error message.
+    /// </summary>
+    /// <param name="message">The error message that explains the reason for the exception.</param>
+    public InvalidLeafHashException(string message) : base(message)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the InvalidLeafHashException class with a specified error message and a reference to the inner exception that is the cause of this exception.
+    /// </summary>
+    /// <param name="message">The error message that explains the reason for the exception.</param>
+    /// <param name="innerException">The exception that is the cause of the current exception, or a null reference if no inner exception is specified.</param>
+    public InvalidLeafHashException(string message, Exception innerException) : base(message, innerException)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the InvalidLeafHashException class with serialized data.
+    /// </summary>
+    /// <param name="info">The SerializationInfo that holds the serialized object data about the exception being thrown.</param>
+    /// <param name="context">The StreamingContext that contains contextual information about the source or destination.</param>
+    protected InvalidLeafHashException(SerializationInfo info, StreamingContext context) : base(info, context)
+    {
+    }
 }

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

@@ -95,7 +95,7 @@ public static MerkleLeaf FromData(string contentType, Hex data)
     /// <returns>A new MerkleLeaf with the specified content type.</returns>
     public static MerkleLeaf FromData(string contentType, Hex data, Hex salt, MerkleTree.HashFunction hashFunction)
     {
-        var hash = hashFunction(Hex.Concat(data, salt).ToByteArray());
+        var hash = UseHashFunction(hashFunction, data, salt);
 
         return new MerkleLeaf(contentType, data, salt, hash);
     }
@@ -128,7 +128,7 @@ public static MerkleLeaf FromJsonValue(string fieldName, object? fieldValue, Hex
 
         var json = JsonSerializer.Serialize(jsonObject);
         var data = new Hex(System.Text.Encoding.UTF8.GetBytes(json));
-        var hash = hashFunction(Hex.Concat(data, salt).ToByteArray());
+        var hash = UseHashFunction(hashFunction, data, salt);
 
         return new MerkleLeaf(ContentTypeUtility.CreateJsonUtf8(), data, salt, hash);
     }
@@ -178,4 +178,11 @@ public override string ToString()
 
         return this.Data.ToString();
     }
+
+    //
+
+    internal static Hex UseHashFunction(MerkleTree.HashFunction hashFunction, Hex data, Hex salt)
+    {
+        return hashFunction(Hex.Concat(data, salt).ToByteArray());
+    }
 }

src/Evoq.Blockchain/Blockchain.Merkle/MerkleMetadata.cs

@@ -14,6 +14,11 @@ public static class MerkleTreeVersionStrings
     /// The version string for the Merkle tree version 2.0.
     /// </summary>
     public const string V2_0 = "MerkleTree+2.0";
+
+    /// <summary>
+    /// The version string for the Merkle tree version 3.0.
+    /// </summary>
+    public const string V3_0 = "application/merkle-exchange-3.0+json";
 }
 
 /// <summary>
@@ -46,4 +51,9 @@ public class MerkleMetadata
     /// Gets or sets the version of the Merkle tree implementation.
     /// </summary>
     public string Version { get; set; } = MerkleTreeVersionStrings.V1_0;
+
+    /// <summary>
+    /// Gets or sets the type of the document or record being exchanged in the leaf data.
+    /// </summary>
+    public string? ExchangeDocumentType { get; set; }
 }