fix: replace tiered second-deposit panic with typed EscrowError in fu…

[edrizxabdulganiyu-blip]

fix: replace tiered second-deposit panic with typed EscrowError in fund_with_commitment

Summary

fund_impl (reached via fund_with_commitment) previously guarded the tiered re-entry path with a
raw assert! and a panic string. Every other funding guard in the contract uses the append-only
EscrowError enum, and the SDK contract requires callers to branch on ContractError(code) — not
panic text. This PR brings the tiered second-deposit guard into line with that discipline.

Changes

escrow/src/lib.rs

• The TieredSecondDeposit = 108 variant's doc comment is expanded to a full NatSpec-style
  block: invariant rationale, affected DataKey, recommended client action (use fund() for
  follow-on principal), and explicit code-stability note.
• The ensure(&env, prev == 0, EscrowError::TieredSecondDeposit) call in fund_impl is the single
  enforcement point — guard ordering and exact trigger condition (prev != 0) are unchanged.

escrow/src/tests/funding.rs

• Upgraded two #[should_panic] tests to assert_contract_error(...,
  EscrowError::TieredSecondDeposit) so they assert the numeric code, not just any panic:

  • test_fund_with_commitment_twice_panics
  • test_fund_then_fund_with_commitment_panics

• Added 4 new edge-case tests:

┌───────────────────────────────────┬──────────────────────────────────────────────────────┐
│ Test │ What it covers │
├───────────────────────────────────┼──────────────────────────────────────────────────────┤
│ test_tiered_second_deposit_d │ Re-entry with a different lock (attempted tier │
│ ifferent_lock_rejected │ upgrade) is rejected; effective yield unchanged │
├───────────────────────────────────┼──────────────────────────────────────────────────────┤
│ test_tiered_second_deposit_z │ Re-entry with lock=0 (base-yield fallback) is also │
│ ero_lock_also_rejected │ rejected — all re-entries are blocked │
├───────────────────────────────────┼──────────────────────────────────────────────────────┤
│ test_tiered_second_deposit_g │ Guard is per-investor: Investor B's first call │
│ uard_is_per_investor │ succeeds; Investor A's second is rejected │
├───────────────────────────────────┼──────────────────────────────────────────────────────┤
│ test_follow_on_fund_after_ti │ Three consecutive fund() follow-ons preserve both │
│ ered_commitment_preserves_all_sta │ InvestorEffectiveYield and InvestorClaimNotBefore │
│ te │ │
└───────────────────────────────────┴──────────────────────────────────────────────────────┘

docs/escrow-error-messages.md

• Enriched code 108 canonical table row with full trigger condition and client action.
• Legacy panic string row updated to note the assert! origin.

docs/adr/ADR-005-tiered-yield.md

• Replaced "Panics if the investor already has a contribution" with the explicit typed-error
  reference and SDK branching note.
• Test coverage table extended from 15 to 19 entries.

Security notes

• Identical revert condition: guard fires on prev != 0, unchanged from before.
• Stable numeric code: 108 is append-only; no existing code is renumbered or removed.
• fund() follow-on unaffected: the simple_fund = true path has no ensure on prev; returning
  investors using fund() continue to work as before.
• No migration required: this is a code-only change; no stored XDR layout or DataKey variant is
  modified.

What was tested

• All existing tiered-deposit tests pass with the upgraded assertions.
• New tests cover: re-entry with different lock, re-entry with zero lock, per-investor
  isolation, and multi-leg fund() follow-on invariant preservation.

close #355

[drips-wave]

@edrizxabdulganiyu-blip 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