docs: update Merkle tree documentation for v3.0 and blockchain attestation

Major updates to Merkle tree documentation to reflect v3.0 improvements and blockchain attestation features:

- Update README.md:
  - Clarify Merkle tree as "Merkle-Inspired Hash Set" optimized for small records
  - Add v3.0 security improvements and interoperability features
  - Add new section on blockchain attestation and verification flow
  - Update usage examples to use MerkleTreeVersionStrings.V3_0

- Update selective-disclosure.md:
  - Add detailed v3.0 security improvements section
  - Add security guarantees and processing requirements
  - Add blockchain attestation section with process and properties
  - Update examples to use v3.0 format and features
  - Enhance verification section with v3.0 specifics

- Update MerkleTree.cs:
  - Add comprehensive documentation for v3.0 features
  - Document security improvements and interoperability features
  - Add use cases section

These changes better reflect the security and interoperability improvements in v3.0, particularly around the protected header leaf and blockchain attestation capabilities.

Author: lukepuplett

docs/merkle/README.md

@@ -10,11 +10,12 @@ Documentation on our approach to selective disclosure in Merkle trees, allowing
 
 ## Key Features
 
-- **Standard Merkle Tree Implementation**: Binary tree of hashes with efficient verification
+- **Merkle-Inspired Hash Set**: Optimized for small records (less than 20 items) where most data will be revealed
 - **Automatic Random Salts**: Each leaf gets its own cryptographically secure random salt by default
 - **Selective Disclosure**: Ability to reveal only specific leaves while maintaining verifiability
 - **Flexible Serialization**: JSON representation with options for privacy and null handling
 - **Clean API Design**: Intuitive interfaces for creating, modifying, and verifying trees
+- **Version 3.0 Support**: Enhanced security with protected header leaf and JOSE-inspired format
 
 ## Security Best Practices
 
@@ -23,6 +24,10 @@ For optimal security, we've designed our Merkle tree implementation with these b
 - **Unique Random Salts**: Each leaf in the tree automatically gets its own secure random salt
 - **Salt Length**: 16 bytes (128 bits) of randomness by default
 - **Correlation Protection**: Different salt for each leaf prevents correlation attacks on identical data
+- **Protected Header**: First leaf contains cryptographically protected metadata (algorithm, leaf count, document type)
+- **Minimum Leaf Count**: All valid trees must have at least two leaves to prevent single-leaf attacks
+- **Algorithm Protection**: Hash algorithm is cryptographically bound to the tree structure
+- **Document Type Safety**: Exchange field prevents mixing different types of records
 
 ## Implementation Details
 
@@ -32,11 +37,33 @@ The Merkle tree implementation is available in the `Evoq.Blockchain.Merkle` name
 - `MerkleLeaf`: Represents a leaf node in the tree, containing data, salt, hash, and content type
 - `MerkleMetadata`: Contains metadata about the tree, such as version and hash algorithm
 
+## Version 3.0 Improvements
+
+Version 3.0 introduces significant security enhancements:
+
+1. **Security Improvements**:
+   - Protected header leaf with cryptographically secured metadata
+   - Prevention of single leaf, leaf addition/removal, and algorithm substitution attacks
+   - Document type safety through the exchange field
+   - Strict validation of header leaf and tree structure
+
+2. **Interoperability Features**:
+   - JOSE-inspired header format (alg, typ fields)
+   - Standard MIME types for structured data exchange
+   - Support for selective disclosure through private leaves
+   - Efficient proof generation with O(log n) hashes
+
+3. **Use Cases**:
+   - Selective Disclosure: Reveal specific leaves while keeping others private
+   - Document Exchange: Exchange structured data with type safety and integrity
+   - Proof Generation: Generate compact proofs for verification
+   - Private Storage: Store full structure for quick proof reissuance
+
 ## Usage
 
 ```csharp
-// Create a new tree
-var tree = new MerkleTree();
+// Create a new v3.0 tree
+var tree = new MerkleTree(MerkleTreeVersionStrings.V3_0);
 
 // Add JSON key-value pairs with automatic random salts (preferred)
 var data = new Dictionary<string, object?> { { "key1", "value1" }, { "key2", 123 } };
@@ -49,6 +76,30 @@ tree.RecomputeSha256Root();
 bool isValid = tree.VerifySha256Root();
 ```
 
+## Blockchain Attestation
+
+The Merkle tree implementation is designed to work seamlessly with blockchain attestations:
+
+1. **Root Hash Attestation**: The root hash of a Merkle tree can be attested on a blockchain, providing a tamper-proof record of the tree's state at a specific point in time.
+
+2. **Verification Flow**:
+   - A Merkle tree is created and its root hash is attested on the blockchain
+   - The complete tree can be shared with users or stored privately
+   - When verification is needed, the tree is parsed from JSON
+   - The parsed tree's root is verified against the attested hash on the blockchain
+
+3. **Selective Disclosure with Attestation**:
+   - Users can create selectively disclosed versions of the tree
+   - The disclosed tree maintains the same root hash
+   - Verifiers can confirm the disclosed tree matches the attested root
+
+This pattern is particularly valuable for:
+- Digital identity documents
+- Credential verification
+- Document attestation
+- Supply chain tracking
+- Any scenario requiring both privacy and verifiability
+
 For a complete usage example, see the [Complete Example section in the Selective Disclosure documentation](./selective-disclosure.md#complete-example-digital-passport).
 
 For more detailed implementation information, examine the source code in:

docs/merkle/selective-disclosure.md

@@ -21,11 +21,69 @@ In many verification scenarios, you need to prove only specific attributes (like
 
 Traditional approaches require either:
 1. Revealing the entire document (compromising privacy)
-2. Creating separate trees for each attribute (sacrificing the unified cryptographic binding)
-3. Implementing complex zero-knowledge proofs (adding significant complexity)
+1. Creating separate trees for each attribute (sacrificing the unified cryptographic binding)
+1. Implementing complex zero-knowledge proofs (adding significant complexity)
 
 Our implementation provides a clean, elegant solution to this problem through a technique we call "private leaves" - leaves whose content is withheld while their cryptographic presence is maintained.
 
+## Version 3.0 Security Improvements
+
+Version 3.0 introduces a protected header leaf that significantly enhances security by preventing several critical attacks:
+
+1. **Single Leaf Attack Prevention**
+   - The header leaf forces all valid trees to have at least two leaves
+   - This prevents an attacker from creating a single-leaf tree that matches a known root hash
+   - The header leaf must be valid JSON, making it harder to fake
+
+2. **Leaf Count Protection**
+   - The header leaf contains the exact number of leaves expected
+   - This prevents attackers from adding or removing leaves to find hash collisions
+   - The leaf count is cryptographically protected by being part of the tree structure
+
+3. **Algorithm Protection**
+   - The hash algorithm is included in the protected header leaf
+   - This prevents attackers from switching to weaker algorithms
+   - The algorithm choice is cryptographically bound to the tree structure
+
+4. **Document Type Safety**
+   - The `exchange` field specifies the type of document (e.g., "passport", "invoice")
+   - This prevents mixing different types of records in the same tree
+   - Helps prevent attacks where a proof of one document type is used as another
+
+5. **Metadata Protection**
+   - All critical metadata is stored in the first leaf of the tree
+   - This metadata is cryptographically protected by the tree's structure
+   - Makes it impossible to modify metadata without breaking the tree's integrity
+
+### Security Guarantees
+
+The v3.0 design provides security through two difficult problems for attackers:
+
+1. **Finding Private Leaf Hashes**
+   - Attackers must find correct hash values for private leaves
+   - These hashes must combine to produce the known root hash
+   - This is computationally infeasible due to the cryptographic properties of the hash function
+
+2. **Finding Data/Salt Combinations**
+   - Attackers must find data and salt combinations that either:
+     - Produce the original hash for a leaf
+     - Or produce a different hash that still solves for the root hash
+   - This is prevented by the use of cryptographically secure random salts
+
+### Processing Requirements
+
+When processing v3.0 trees, verifiers must:
+
+1. Ensure there are at least two leaf nodes
+2. Verify the first leaf contains valid JSON metadata
+3. Validate the algorithm is known, supported, and secure
+4. Confirm the leaf count matches the actual number of leaves
+5. Verify all leaf hashes can be recomputed from their data and salt
+6. Validate data formats and content (e.g., postal codes, dates)
+7. Challenge users to provide details from the original document
+
+This comprehensive validation ensures the tree's integrity and prevents various attacks while maintaining the efficiency of selective disclosure.
+
 ## Important: Security Through Unique Salts
 
 > **SECURITY BEST PRACTICE**: Each leaf in a Merkle tree should have its own unique random salt. 
@@ -41,6 +99,7 @@ We've implemented a simple yet powerful solution that enables any subset of leav
 2. **Clean Serialization**: Private leaves contain only their hash, omitting data, salt, and content type
 3. **Seamless Verification**: Standard verification algorithms still work with private leaves
 4. **Flexible Privacy Control**: Any combination of leaves can be made private or public
+5. **Efficient Proofs**: Generates compact proofs with O(log n) hashes for verification
 
 ## Implementation Details
 
@@ -95,6 +154,31 @@ This selective disclosure approach is particularly valuable for:
 2. **Credential Validation**: Verify qualifications without exposing all credential details
 3. **Document Attestation**: Cryptographically verify specific document attributes
 4. **Blockchain Applications**: Reduce on-chain data while maintaining verifiability
+5. **Private Storage**: Store full structure (data, salts, hashes) for quick proof reissuance
+
+## Blockchain Attestation
+
+The selective disclosure implementation is designed to work seamlessly with blockchain attestations:
+
+1. **Attestation Process**:
+   - Create a Merkle tree with all required data
+   - Compute and verify the root hash
+   - Attest the root hash on the blockchain
+   - Store or share the complete tree with users
+
+2. **Verification Process**:
+   - Parse the selectively disclosed tree from JSON
+   - Verify the tree's structure and integrity
+   - Compare the tree's root hash with the attested hash on the blockchain
+   - Validate the disclosed data against the attested root
+
+3. **Security Properties**:
+   - The attested root hash provides a tamper-proof record
+   - Selective disclosure maintains the same root hash
+   - The header leaf in v3.0 prevents various attacks
+   - The verification process ensures data integrity
+
+This pattern enables privacy-preserving verification while maintaining the security guarantees of blockchain attestation.
 
 ## Security Considerations
 
@@ -125,6 +209,10 @@ Let's walk through a complete example of implementing selective disclosure with
 First, we'll create a Merkle tree containing various passport data fields:
 
 ```csharp
+// Create a v3.0 tree for the passport
+var merkleTree = new MerkleTree(MerkleTreeVersionStrings.V3_0);
+merkleTree.Metadata.ExchangeDocumentType = "passport";
+
 // Passport data fields
 var passportData = new Dictionary<string, object?>
 {
@@ -160,8 +248,7 @@ var passportData = new Dictionary<string, object?>
     }
 };
 
-// Create the Merkle tree and add all fields as leaves with automatically generated random salts
-var merkleTree = new MerkleTree();
+// Add all fields as leaves with automatically generated random salts
 merkleTree.AddJsonLeaves(passportData);  // Uses random salts automatically
 
 // Compute the root hash
@@ -241,16 +328,17 @@ The resulting JSON would look like this, with private fields only showing their
     }
   ],
   "root": "0x42b0557fd2578668da8218367ef9f8f0e233a2a928a979f66c8331fda5d81af8",
-  "metadata": {
-    "hashAlgorithm": "sha256",
-    "version": "1.0"
+  "header": {
+    "typ": "application/merkle-exchange-3.0+json"
   }
 }
 ```
 
+Note that in v3.0, the header leaf (first leaf) contains protected metadata about the tree, including the hash algorithm, leaf count, and document type. This metadata is cryptographically protected by the tree's structure, preventing tampering with critical tree parameters. 
+
 ### Verifying a Tree with Private Leaves
 
-The verification process works the same way with private leaves:
+The verification process works the same way with private leaves, but with enhanced security in v3.0:
 
 ```csharp
 // Parse the selectively disclosed JSON
@@ -260,7 +348,11 @@ var parsedTree = MerkleTree.Parse(jsonWithPrivacy);
 bool isStillValid = parsedTree.VerifySha256Root(); // Should be true
 ```
 
-The verification works because when a leaf is private (has no data or salt), the verification algorithm uses the provided hash directly.
+The verification works because:
+1. When a leaf is private (has no data or salt), the verification algorithm uses the provided hash directly
+2. In v3.0, the header leaf's metadata (algorithm, leaf count, document type) is verified as part of the tree structure
+3. The parser validates that the leaf count matches the actual number of leaves
+4. The hash algorithm specified in the header leaf is used for verification
 
 ### Creating a Proof for a Specific Claim
 
@@ -289,7 +381,7 @@ 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 tree = new MerkleTree(MerkleTreeVersionStrings.V3_0);
 var hash = Hex.Parse("0x1234567890abcdef");
 var privateLeaf = tree.AddPrivateLeaf(hash);
 ```
@@ -308,6 +400,7 @@ 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
+- In v3.0, are protected by the header leaf's metadata
 
 ## Conclusion
 
@@ -319,5 +412,6 @@ The approach provides:
 2. Clean JSON representation with only the necessary data
 3. Maintained cryptographic verifiability
 4. Simple implementation using predicates
+5. Enhanced security through protected metadata in v3.0
 
 This is particularly valuable for real-world applications where selective disclosure balances privacy with verifiability needs. 

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

@@ -15,6 +15,31 @@ namespace Evoq.Blockchain.Merkle;
 /// A simple Merkle tree which can be assembled manually or parsed from a JSON string. The design forces the user
 /// to verify the root before serializing to JSON, ensuring that the tree is valid before it is saved or exchanged.
 /// If the tree fails verification, an exception can be caught and the tree root can be recomputed from the leaves.
+/// 
+/// Version 3.0 introduces a protected header leaf that provides enhanced security and interoperability:
+/// 
+/// Security Improvements:
+/// - The header leaf is part of the Merkle tree itself, making its contents (algorithm, leaf count, exchange type) 
+///   cryptographically protected by the tree's structure
+/// - Protects against leaf addition/removal attacks by including the exact leaf count
+/// - Prevents single leaf attacks by requiring a header leaf
+/// - Protects against algorithm substitution by including the hash algorithm in the protected header
+/// - Includes the type of data/record being exchanged (e.g., "invoice", "contract", "certificate") to prevent 
+///   mixing different types of records in the same tree
+/// - Uses proper MIME types for structured exchange format
+/// - Performs strict validation of the header leaf during parsing
+/// 
+/// Interoperability Features:
+/// - Uses standard MIME types (application/merkle-exchange-3.0+json) for structured data exchange
+/// - Supports selective disclosure through private leaves and makePrivate predicates
+/// - Enables efficient proof generation with O(log n) hashes for classical Merkle proofs
+/// - Maintains backward compatibility with v1.0 and v2.0 formats
+/// 
+/// Use Cases:
+/// - Selective Disclosure: Reveal specific leaves while keeping others private
+/// - Document Exchange: Exchange structured data with type safety and integrity
+/// - Proof Generation: Generate compact proofs for verification
+/// - Private Storage: Store full structure (data, salts, hashes) for quick proof reissuance
 /// </remarks>
 public class MerkleTree
 {