docs: add cross chain verifier standard

[Amas-01]

PR: Document Cross Chain Verifier Standard

Closes #328

Summary

This PR adds comprehensive documentation for the Cross Chain Verifier Standard, defining how external bridges must format messages for verification on Soroban. The standard ensures interoperability between different bridge implementations and provides a consistent security model for cross-chain message verification.

Purpose

The Cross Chain Verifier contract uses Binary Merkle Tree proofs to cryptographically verify that messages occurred on source chains. Without a documented standard, bridge implementers would need to reverse-engineer the expected format, leading to:

• Inconsistent implementations
• Security vulnerabilities from malformed messages
• Difficulty auditing bridge integrations
• Lack of interoperability between bridges

This documentation solves these problems by providing a clear, complete specification.

What's Included

1. Message Structure Definition

The document defines the four required components for cross-chain message verification:

• Block Height (u32): Source chain block identifier
• Leaf Hash (BytesN<32>): SHA-256 hash of the message payload
• Merkle Proof (Vec<BytesN<32>>): Sibling hashes forming the proof path
• Proof Flags (Vec<bool>): Sibling position indicators (left/right)

2. Formatting Rules

Detailed specifications for:

• Canonical message serialization: Deterministic byte encoding
• Leaf hash computation: SHA-256 over canonical bytes
• Merkle proof construction: Binary tree traversal algorithm
• Hash combination rules: Correct concatenation order for proof verification
• Encoding requirements: Raw binary format (no hex/base64)

3. Validation Rules

Documents all validation checks performed by the verifier:

1. Structural validation: Proof and proof_flags length matching
2. State root availability: Block height must have submitted root
3. Merkle proof verification: Computed root must match stored root
4. Replay protection: Bridge contract responsibility (not verifier)
5. Payload integrity: Bridge contract responsibility (not verifier)

4. Security Considerations

Comprehensive security analysis including:

• What the verifier guarantees: Cryptographic proof, state root integrity
• What the verifier does NOT guarantee: Authenticity, replay protection, authorization
• Bridge operator responsibilities: State root accuracy, admin security, monitoring
• Security assumptions: Trusted relayers, source chain security, hash function security
• Attack vectors and mitigations: Invalid roots, replay attacks, proof manipulation
• Recommended security practices: Multi-sig admin, monitoring, rate limiting

5. Versioning and Compatibility

Forward-looking guidance on:

• Current version (1.0) specifications
• Version field in message format
• Future compatibility strategy
• Backward compatibility policy
• Deprecation process (6-18 month timeline)

6. Practical Examples

Three complete examples:

1. Simple token transfer message: Full serialization and proof construction
2. Verification computation: Step-by-step proof verification walkthrough
3. Bridge contract integration: Complete Rust implementation example

7. Implementation Checklists

Separate checklists for:

• Bridge developers: 12 implementation tasks
• Relayer operators: 10 operational tasks
• Auditors: 10 review items

Alignment with Existing Code

The documentation is based on careful analysis of:

• contracts/cross_chain_verifier/src/lib.rs: Contract implementation
• contracts/cross_chain_verifier/src/test.rs: Test cases and examples
• Existing documentation patterns in docs/ directory

All technical details match the actual contract behavior:

• Merkle proof verification algorithm matches verify_message() implementation
• Hash combination logic matches the contract's SHA-256 usage
• Validation rules match the contract's panic conditions
• Data types match Soroban SDK types

Documentation Quality

The document follows SoroScope documentation conventions:

• Clear structure: Logical sections with table of contents
• Technical precision: Exact field types, sizes, and validation rules
• Visual aids: ASCII diagrams, code examples, tree structures
• Practical focus: Implementation checklists and working examples
• Security emphasis: Dedicated security section with threat analysis
• Consistent style: Matches existing docs (ARCHITECTURE.md, IMPLEMENTATION_GUIDE.md)

File Changes

New Files

• docs/CROSS_CHAIN_VERIFIER_STANDARD.md (650+ lines)

  • Complete standard specification
  • Examples and implementation guidance
  • Security considerations and best practices

• docs/CROSS_CHAIN_VERIFIER_PR.md (this file)

  • PR description and context

Modified Files

• docs/DOCUMENTATION_INDEX.md
  • Added Cross Chain Verifier Standard to index
  • Reorganized to include "Standards & Specifications" section

Target Audience

This documentation serves multiple audiences:

1. Bridge Developers: Implementing cross-chain bridges
2. Relayer Operators: Running state root submission services
3. Security Auditors: Reviewing bridge implementations
4. Protocol Architects: Understanding cross-chain verification design
5. Integration Partners: Evaluating SoroScope for their projects

Benefits

For Bridge Implementers

• Clear specification eliminates guesswork
• Working examples accelerate development
• Security guidance prevents common vulnerabilities
• Implementation checklist ensures completeness

For the Ecosystem

• Interoperability between different bridge implementations
• Consistent security model across all bridges
• Easier auditing and security reviews
• Lower barrier to entry for new bridges

For SoroScope

• Professional documentation demonstrates maturity
• Attracts bridge developers to the platform
• Reduces support burden with self-service docs
• Establishes SoroScope as cross-chain infrastructure

Testing and Validation

The documentation has been validated against:

• ✅ Contract implementation in lib.rs
• ✅ Test cases in test.rs
• ✅ Soroban SDK types and conventions
• ✅ Existing documentation style
• ✅ Technical accuracy of Merkle proof algorithms
• ✅ SHA-256 hash computation details

Future Enhancements

The standard is designed to evolve. Potential future additions:

• Support for different hash algorithms (SHA-3, BLAKE3)
• Multi-proof batching for efficiency
• Compressed proof formats
• Cross-chain message standards (beyond just verification)
• Integration with Stellar's native bridge protocols

The versioning section provides a clear path for these enhancements without breaking existing implementations.

Compatibility Notes

This documentation describes the existing Cross Chain Verifier contract behavior. It does not introduce breaking changes or require contract modifications. Bridges can immediately use this standard to integrate with the deployed verifier.

Review Focus Areas

Reviewers should pay special attention to:

1. Technical Accuracy: Do the Merkle proof algorithms match the contract?
2. Security Completeness: Are all attack vectors documented?
3. Clarity: Can a bridge developer implement from this spec alone?
4. Examples: Are the examples correct and helpful?
5. Versioning: Is the compatibility strategy sound?

Checklist

• Documentation written and complete
• Examples tested against contract behavior
• Security considerations documented
• Implementation checklists provided
• Documentation index updated
• Follows existing documentation conventions
• Technical accuracy verified against source code
• Versioning and compatibility strategy defined

---

[drips-wave]

@Amas-01 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