Add Invoice Commitment Hash (On-Chain Anchor)

[Olowodarey]

This PR implements an immutable on-chain commitment hash for invoices, providing a minimal anchor to off-chain invoice data (PDF hash, ERP ID, etc.) without requiring a full oracle implementation at MVP stage.

Changes

Core Implementation

• Added commitment field to EscrowData: New BytesN<32> field stores SHA-256 hash of off-chain invoice data
• Updated create_escrow function: Now accepts a commitment parameter that is set at creation and remains immutable
• Enhanced escrow_created event: Includes the commitment hash for indexers to track and verify invoice data

Technical Details

• Type: BytesN<32> - Fixed-size 32-byte array for SHA-256 hashes (gas/storage efficient)
• Immutability: Set once at creation, cannot be modified throughout escrow lifecycle
• Event Emission: Commitment included in escrow_created event for off-chain indexing

Test Coverage

Added comprehensive test suite covering:

• ✅ Creating escrow with commitment hash
• ✅ Commitment immutability verification
• ✅ Commitment included in creation event
• ✅ Different commitments for different invoices
• ✅ Commitment persistence through full lifecycle (Created → Funded → Settled)
• ✅ All existing tests updated to include commitment parameter

Testing

# All tests pass
cargo test
# 52 tests in invoice-escrow
# 11 tests in payment-distributor
# 3 integration tests

# Code quality checks pass
cargo fmt --check
cargo clippy -- -D warnings

Documentation

• Updated function documentation for create_escrow to describe commitment parameter
• Added inline comments explaining commitment field purpose and constraints
• Test helper function test_commitment() demonstrates proper usage

Migration Notes

Breaking Change: Existing create_escrow calls must be updated to include the commitment parameter.

Example:

// Before
escrow.create_escrow(
    &invoice_id,
    &seller,
    &debtor,
    &face_value,
    &purchase_price,
    &due_date,
    &payment_token,
    &invoice_token,
);

// After
escrow.create_escrow(
    &invoice_id,
    &seller,
    &debtor,
    &face_value,
    &purchase_price,
    &due_date,
    &payment_token,
    &invoice_token,
    &commitment_hash, // New: BytesN<32>
);

Acceptance Criteria

• New field on EscrowData for commitment bytes (32-byte fixed size)
• Set at creation, immutable after create
• Event includes commitment for indexers
• Unit tests: create with commitment, verify immutability
• Gas/storage conscious: uses fixed-size BytesN<32> over dynamic strings
• No unwrap() in production contract paths
• cargo test passes locally
• cargo fmt and cargo clippy -D warnings pass

Future Enhancements

This minimal on-chain anchor enables future verification features:

• Off-chain indexers can track commitment hashes
• Future oracle integration can verify invoice data against commitment
• Supports dispute resolution by proving invoice authenticity

closes #3
closes #4
closes #40
closes #42

[drips-wave]

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