[Feature] Systematic fuzz + invariant testing across the Soroban contract suite (microloan, yield-strategy, governance, flexible, target)

[Sendi0011]

Summary

The platform moves real member funds across eight Soroban contracts (factory, rotational, flexible, target, microloan, governance, reputation, yield-strategy), yet only one of them — rotational — has fuzz tests today (smartcontract/contracts/rotational/src/fuzz_tests.rs). The rest rely on unit tests that exercise fixed happy and edge paths.

Fee math, round-shifting, loan interest and repayment, governance quorum thresholds, and reputation accounting are exactly the kinds of integer-heavy, stateful logic that dedicated property / invariant testing is built for. This issue asks for a systematic fuzz + invariant testing pass across the contract suite.

Requirements

1. Invariant tests per contract covered by the Soroban testutils fuzzer (the same harness rotational/src/fuzz_tests.rs uses). For each contract, define and assert invariants that must hold for any sequence of operations:

   • rotational (extend what exists): total contributed = sum of member contributions at all times for a round; treasury/relayer fees never exceed deposited amounts; payout always ≤ pool balance; only the current eligible member can receive a slot's payout.
   • flexible / target: aggregate balance reconciliation; withdrawals capped by balances and minimum-deposit rules.
   • microloan: total_owed and remaining are always consistent with principal + interest and are never negative; repaid amount never exceeds owed; a repaid/defaulted loan transitions correctly (no double-repay, no withdraw of others' funds).
   • governance: quorum and against-threshold math; at most MAX_ACTIVE_PROPOSALS active; a veto/decision can never be registered twice.
   • reputation: scores never overflow i128; a member's score is bounded between its floor and the values the redemptions allow.
   • yield-strategy: shares vs. underlying reconciliation (share price can never go negative or be manipulated to zero).

2. Multi-round / multi-call fuzz scenarios — sequence random valid calls (deposit, payout, withdraw, remove_member, add_member, delete round, emergency paths) for thousands of iterations and assert no panic, no invariant break, and no funds created or destroyed.

3. Boundary / overflow focus — exercise the fee bps (0 → 10000), round durations, member counts at limits, and asset amount extremes (0, 1, i128::MAX) to catch integer overflow/underflow panics that unit tests miss.

4. Deterministic + CI — make fuzz runs reproducible (fixed seed or captured case) and register them in the CI workflow so a discovered counterexample fails the build. Include the seed/hash of any found counterexample in the failure output for reproduction.

Notes / context

• Reuse the existing harness pattern in rotational/src/fuzz_tests.rs as the reference implementation and extend it to the other contracts.
• Prioritize microloan and yield-strategy first — they have the most fee/interest/redemption arithmetic and the least direct coverage.
• Do not change contract behavior as a side effect; the goal is to prove the current arithmetic is safe (and fix any real bug found, with a regression test).
• This supersedes the narrow scope of issue [Feature] Add comprehensive contract fuzz testing for fee calculation and round-shifting logic #89 (single-contract fee/round fuzz) by making it a suite-wide, invariant-based effort.

Acceptance criteria

• Invariant tests exist and pass for at least the four highest-value contracts (microloan, yield-strategy, governance, flexible/target) and extend existing rotational coverage
• Multi-call fuzz scenarios run thousands of iterations without panic or invariant break
• Boundary/overflow cases explicitly covered
• Fuzz runs are deterministic and wired into CI with a reproduction seed on failure
• Any real bug found has a regression test and a documented fix

[Clement-coder]

Hi,
I'm a full-stack software and blockchain engineer with experience delivering production-grade solutions across frontend, backend, infrastructure, analytics, and blockchain systems.
I'd like to take ownership of this issue. I've reviewed the requirements and have a clear approach for implementing a robust, scalable, and maintainable solution that satisfies all acceptance criteria. I'll ensure the implementation follows project conventions, includes comprehensive testing, and is properly documented.
I can start immediately and will provide consistent updates throughout development. Looking forward to contributing to the project.

[grantfox-oss]

🦊 GrantFox — @Clement-coder has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #262)
2. Your PR will be reviewed by the JointSave-org maintainers

Good luck! Track your progress on GrantFox.