Add property-based tests asserting refunds never exceed total funded principal

[mikewheeleer]

Add property-based tests asserting refunds never exceed total funded principal

Description

In a cancelled escrow, the sum of all per-investor refunds must never exceed funded_amount, and DistributedPrincipal must converge to exactly the total contributed when every investor refunds. The existing proptest suite covers payout rounding and the dust floor, but there is no property asserting the global refund conservation invariant across arbitrary investor sets and refund orderings.

This issue adds a proptest invariant for refund conservation.

Requirements and context

• Repository scope: Liquifact/Liquifact-contracts only.
• Generate arbitrary sets of investors with arbitrary contributions, fund, cancel, then refund in arbitrary order.
• Assert sum(refunds) == sum(contributions) once all investors refund, and DistributedPrincipal equals that sum.
• Assert no single refund exceeds the investor's recorded contribution and double-refund is impossible.
• Assert the contract token balance never goes negative during the refund sequence.
• Seed any discovered failing case into escrow/proptest-regressions.

Suggested execution

• Fork the repo and create a branch
• git checkout -b test/contracts-refund-conservation-proptest
• Implement changes
  • Write code in: no production change expected; if a defect is found, fix it in contracts/escrow/src/lib.rs.
  • Write comprehensive tests in: contracts/escrow/src/tests/properties.rs — the refund-conservation invariant.
  • Add documentation: note the conservation invariant in README.md and docs/.
  • Include NatSpec-style doc comments (///) on the property and its assumptions.
  • Validate security assumptions: no ordering of refunds can over-distribute principal.
• Test and commit

Test and commit

• Run cargo fmt --all -- --check, cargo build, and cargo test.
• Cover edge cases and failure paths: single investor, many investors, reverse-order refunds, and partial refunds.
• Include the full cargo test output and a short security notes section in the PR description.

Example commit message

test: add proptest invariant asserting refunds never exceed funded principal

Guidelines

• Minimum 95 percent test coverage for impacted modules.
• Clear, reviewer-focused documentation.
• Timeframe: 96 hours.

Community & contribution rewards

• 💬 Join the Liquifact community on Discord for questions, reviews, and faster merges: https://discord.gg/JrGPH4V3
• ⭐ This is a GrantFox OSS / Official Campaign task and may be rewarded. When your PR is merged you'll be prompted to rate the project — if this issue and the maintainers helped you ship, we'd be grateful for a 5-star rating. Clear questions in Discord and tidy, well-tested PRs are the fastest path to a merge and a reward.

[Hassanmovic98]

@Hassanmovic98 has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I will implement property-based tests to enforce the refund conservation invariant.I will add the invariant checks inside contracts/escrow/src/tests/properties.rs.The test will generate arbitrary investor sets, funding contributions, and cancellation sequences.I will assert that total refunded amounts exactly equal total initial contributions.I will verify that individual refunds never exceed a user's original deposit.The suite will explicitly check that double-refunding is structurally impossible.I will simulate arbitrary refund execution orderings to ensure absolute protection against over-distribution.I will monitor the simulated token balance to confirm it never drops below zero.I will document the refund conservation invariant in README.md and inline comments.Finally, I will run the cargo test runner to achieve 95%+ coverage.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Hassanmovic98 to this issue.

[WhitesmokeX]

@WhitesmokeX has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

hi maintainer,, kindly assign this to me

ℹ️ Repo Maintainers: To accept this application, review their application or assign @WhitesmokeX to this issue.

[drips-wave]

Congratulations, @Hassanmovic98! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @Hassanmovic98: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[brain-marchine]

Picking up GrantFox #482.

Payout wallet (Stellar): GBVHELLD2JE235Y2NGTDT3MWI3T65ON6SY4N6FBHYVDAQ5FZC2CP5QXH