docs(contracts): write architecture decision record (ADR) for Merkle …

[HassanKorey]

docs(contracts): write architecture decision record (ADR) for Merkle receipt structure

Summary

This pull request introduces ADR-001-merkle-structure.md to formally document the "sorted-pair SHA-256" strategy utilized by the ReceiptAnchor and off-chain SDK for Merkle tree construction.

Without context, this specific approach can look like a non-standard deviation. The newly added ADR details:

• Mechanics: How sorting siblings before hashing deterministicly removes the need for left/right positional metadata in the proofs.
• Trade-offs: The massive benefits in terms of lower WASM instruction counts, smaller on-chain calldata footprint, and cheaper fees on Soroban compared to standard implementations.
• Security Context: Explicit justification for why sorting before hashing remains completely safe against second-preimage attacks given our strict 32-byte leaf (payment_ref) constraints.

Contract Change Safety Checklist

Please verify that your changes adhere to contract stability requirements:

• Event Shapes: Does this PR modify event topic tuples or data shapes? (Breaking change per docs/EVENTS.md)
• Storage Layout: Does this PR change storage keys or layout? (Assessed for archival & migration risks)
• Error Variants: Does this PR add or renumber contract error codes? (Client-visible breaking change)
• Changelog: Has a corresponding entry been added to CHANGELOG.md?
• Deployments: Has any impact on deployed contracts or DEPLOYMENTS.md been documented?
• Verification: Has this change been tested locally (cargo test) and/or exercised on Soroban testnet?

Related Issues

Closes #81

[drips-wave]

@HassanKorey 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

[mergekeeper]

MergeKeeper review

Scope: in scope for linked issue #81.
Verdict: clean

The ADR correctly documents the sorted-pair Merkle tree structure, mechanics, Mermaid diagram, trade-offs, and security context as requested in the issue.

Reviewed commit: 4e6db1306a7de86a9425c9fedd73e5ab5d8143d9.
CI and merge eligibility are checked separately.

[mergekeeper]

MergeKeeper merge status

Status: blocked
PR state: closed
Mergeability: unknown
Checked commit: 4e6db1306a7de86a9425c9fedd73e5ab5d8143d9.

Reason: One or more required CI checks failed.

Failing checks:

• build-wasm - view details
• clippy - view details

Next steps:

1. Open the failing check details above and fix the reported error.
2. Run the same checks locally where possible.
3. Commit and push the fix.
4. MergeKeeper will automatically re-review the updated PR.