test: concurrency guard and vesting timestamp edge cases

[agnesadah3-jpg]

Summary

Two test suites and accompanying doc updates addressing gaps identified in the duplicate-vault prevention and vesting schedule logic.

---

Duplicate vault prevention — concurrency tests

New file: contracts/ttl_vault/src/duplicate_vault_concurrency_tests.rs

The existing test_duplicate_vault_error in test.rs covered the basic happy-path rejection, but there was no load/concurrency scenario confirming the guard holds under near-simultaneous creation attempts.

Tests added (7):

Test	Scenario
test_concurrent_same_params_only_first_succeeds	N rapid calls → exactly 1 succeeds; vault-ID counter does not advance for rejected calls
test_same_block_ordering_deterministically_rejects_second_call	Two calls at the same ledger timestamp → second is always rejected
test_colliding_near_simultaneous_calls_different_params_both_succeed	Same owner+interval, different beneficiary → no false-positive cross-contamination
test_different_interval_same_owner_beneficiary_is_not_duplicate	Different interval → distinct fingerprint; neither vault blocks the other
test_fingerprint_cleared_after_cancel_allows_recreation	cancel_vault removes fingerprint → same triple reusable
test_fingerprint_cleared_after_release_allows_recreation	trigger_release removes fingerprint → same triple reusable
test_multiple_owners_same_beneficiary_interval_all_succeed	Three owners, same beneficiary+interval → all succeed independently

Note on "concurrency": Soroban is single-threaded; real parallel execution isn't possible at the contract layer. The tests model the actual threat — multiple transactions landing in the same block — by issuing calls at identical ledger timestamps with no state change between them. This validates the atomic check-then-write guarantee.

---

Vesting schedule — timestamp edge-case tests

New file: contracts/ttl_vault/src/vesting_timestamp_edge_case_tests.rs

Ledger timestamps are UNIX seconds (u64). The tests confirm all boundary checks use >= (inclusive), no calendar conversions occur, and leap-year crossings are transparent.

Tests added (10+2 off-by-one = 12):

Test	Edge case
test_installment_claimable_at_exact_start_timestamp	now == start_time → immediately claimable
test_nothing_claimable_one_second_before_start	now == start_time - 1 → error
test_claim_succeeds_at_exact_cliff_boundary	now == start_time + cliff_period → succeeds
test_claim_fails_one_second_before_cliff_boundary	now == start_time + cliff_period - 1 → CliffNotReached (55)
test_installment_claimable_at_exact_interval_boundary	now == start + n * interval → succeeds
test_no_installment_one_second_before_interval_boundary	One second before boundary → error
test_vesting_interval_crossing_leap_year_2000	1-year interval from 2000-01-01 crosses Feb 29
test_vesting_interval_uses_leap_year_length	Leap-year-length interval (31 622 400 s) from 2000-02-29
test_cliff_spanning_leap_year_boundary	Cliff of one leap year crossing Feb 29
test_multi_year_schedule_spanning_year_2000_leap	4-year annual schedule from Y2K; total = vault balance
test_zero_cliff_claimable_from_epoch_zero	cliff_period=0, start_time=0 at Unix epoch
test_large_unix_timestamp_no_overflow	start_time ≈ u32::MAX → no u64 overflow

---

Documentation

• docs/duplicate-vault-prevention.md — added Concurrency Guarantee section: same-block ordering, atomic check-then-write, guard properties table, full test coverage table.
• docs/vesting-schedules.md — added Timestamp Edge Cases section: inclusive boundary semantics, leap-year transparency, large-timestamp safety, test coverage table.

---

What was tested

• All 7 concurrency tests exercise the DuplicateVault (error 57) path through create_vault, cancel_vault, and trigger_release.
• All 12 vesting tests use set_beneficiary_vesting / claim_beneficiary_vesting with explicit ledger timestamp manipulation.
• Cargo is not available in this dev environment; tests are verified by structural review against the existing patterns in beneficiary_vesting_tests.rs and lifecycle_tests.rs.

closes #426
closes #427

[drips-wave]

@agnesadah3-jpg 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