335 Core: Add Merkle Tree generation to the /analyze endpoint payload

[Chigybillionz]

Close #335

Summary

This PR implements Merkle tree root generation for the /analyze endpoint, enabling clients to optionally request cryptographic commitments of the simulated ledger state. This feature provides a verifiable representation of the contract's state snapshot for advanced auditing and verification use cases.

Root Cause

The /analyze endpoint was missing the capability to generate Merkle tree commitments from simulated ledger state. Additionally, the existing merkle_tree.rs module had syntactical errors and incomplete implementation, preventing its use.

Solution Implemented

1. Fixed merkle_tree.rs Implementation

• I rewrote the malformed MerkleTree struct with a clean, production-ready design
• Implemented deterministic SHA256-based tree construction with proper leaf pair handling
• Added support for both raw byte data and hex-encoded inputs
• Handles edge cases: empty trees, odd leaf counts, and invalid input data
• Comprehensive unit test coverage

2. Extended AnalyzeRequest

• Added optional include_merkle_tree: Option<bool> field
• Defaults to false for zero overhead on existing clients
• Allows opt-in Merkle tree generation on a per-request basis

3. Enhanced ResourceReport Response

• Added optional merkle_tree_root: Option<String> field
• Contains hex-encoded SHA256 root hash of the state snapshot
• Only populated when explicitly requested

4. Implemented Merkle Tree Generation Logic

• I added in the /analyze endpoint handler:
  • Extracts ledger entries from state_snapshot
  • Decodes hex-encoded entries to binary format
  • Generates Merkle tree from the ledger entries
  • Returns root hash as hex string
  • Comprehensive error handling with structured logging

Key Changes I Made

File	Change	Purpose
core/src/merkle_tree.rs	Complete rewrite	Fixed malformed code, implemented correct algorithm
core/src/main.rs - AnalyzeRequest	Added include_merkle_tree field	Enable opt-in tree generation
core/src/main.rs - ResourceReport	Added merkle_tree_root field	Include root in response
core/src/main.rs - analyze()	Added generation logic	Extract, hash, and return root
core/src/main.rs - to_report()	Added parameter	Pass root to response

Trade-offs and Considerations

1. Performance: Tree generation only occurs when explicitly requested, ensuring zero overhead for clients not using this feature
2. State Snapshot Requirement: Merkle tree generation requires state_snapshot to be available (optional field in simulation result). If unavailable, the feature gracefully returns None
3. Leaf Data Source: Uses all ledger entries from the state snapshot. Invalid hex entries are silently skipped; valid entries are included
4. Hash Algorithm: Uses SHA256 for consistency with industry standards and existing Soroban infrastructure
5. Odd Leaf Handling: Standard practice of duplicating the last leaf when leaf count is odd ensures deterministic results

Backward Compatibility

✅ Fully backward compatible:

• Request field is optional (defaults to false)
• Response field is optional (only included when requested)
• Zero performance impact on existing clients
• No changes to existing endpoint behavior

Testing Steps

1. Test Basic Merkle Tree Generation

curl -X POST http://localhost:8080/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "contract_id": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
    "function_name": "hello",
    "include_merkle_tree": true
  }'

 Thank you!

[drips-wave]

@Chigybillionz Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits