Extend fuzz coverage to the escrow settlement/release path

[Meshmulla]

Background

The contract suite already uses fuzz testing, but only for a couple of areas: soroban/tests/relay_contract_fuzz.rs and soroban/tests/threshold_window_fuzz.rs, both wired into the bounded Fuzz CI job. Notably absent from fuzz coverage is the escrow settlement/release path — which is arguably the single most important flow in the whole system, because it's where value actually moves. It handles accumulation of usage/locked amounts and the settlement/release that pays it out.

Settlement logic is exactly the kind of code where example-based tests, however thorough, tend to miss things: arithmetic overflow and rounding at the boundaries, unexpected orderings of operations, and state transitions that were never anticipated. Fuzzing shines here precisely because it explores the input space a human wouldn't think to enumerate.

Why this matters

A subtle bug in settlement isn't a cosmetic issue — it's a correctness-of-funds issue. Property-style fuzzing that drives randomized sequences of operations and asserts hard invariants is one of the strongest guards available against that class of bug, and running it (bounded) on every PR means regressions are caught continuously rather than discovered after deployment.

What needs to be done

• Add a fuzz target for the escrow settlement/release logic, structured like the existing fuzz files so it fits the established pattern.
• Drive randomized sequences of the relevant operations (for example: record usage / lock amounts, then settle / release) over arbitrary-but-in-range inputs, and assert the invariants that must always hold, such as:
  • balances and usage counters never go negative,
  • settling drains exactly what was owed — no residue left behind, and never double-counted,
  • state transitions are always valid, and no operation panics on any input in range.
• Wire the new target into the existing bounded Fuzz CI job with a capped iteration count, so it adds meaningful coverage without inflating CI time.

Where to look

• soroban/tests/relay_contract_fuzz.rs, soroban/tests/threshold_window_fuzz.rs — the pattern to follow
• soroban/src/ — the escrow / settlement modules under test
• .github/workflows/ci.yml — the Fuzz targets (bounded) job to add the target to

Acceptance criteria

• A fuzz target exercises the escrow settlement/release path with clearly stated invariants
• It runs in the bounded Fuzz CI job with a capped iteration count
• Any bug it uncovers is filed separately with a minimal reproduction
• CI checks must be green before the PR can be merged

Notes

Keep the per-run iteration count modest so CI stays fast; a heavier nightly/scheduled sweep can be added later as its own piece of work.

[Mac-5]

Understanding the ask: The suite has fuzz coverage in two places (relay_contract_fuzz.rs, threshold_window_fuzz.rs) but nothing exercises escrow settlement — the one path where funds actually move. I'd add a third fuzz target following the same pattern, wire it into the existing bounded CI job, and keep iteration count capped so it doesn't blow up CI time.

My approach, step by step:

Study the existing pattern first. Read both existing fuzz files closely — harness structure, how they generate arbitrary-but-bounded inputs, how invariants are asserted, and how they're capped for CI (iteration count, #[cfg] gating, etc.). Whatever conventions they use (arbtest/proptest/quickcheck, custom Arbitrary impls, a fixed seed strategy) I'll mirror exactly rather than introducing a new style.
Map the settlement/release code path. Go through soroban/src/ to find the escrow module(s): where usage/locked amounts accumulate, and where settle/release pays out. I'll note the exact state fields involved (balances, usage counters, locked amounts) and every public entrypoint that touches them, since the fuzz harness needs to call these in randomized sequences, not just once.
Design the operation sequence generator. Build an Arbitrary-style enum of operations (e.g. RecordUsage(amount), Lock(amount), Settle, Release) with in-range bounds (no absurd u128 max values that trivially overflow and tell us nothing — bounded to realistic-but-edge-adjacent ranges, plus explicit boundary values like 0 and max-in-range). Drive a random sequence of these against the contract state each fuzz iteration.
Assert the stated invariants after every operation, not just at the end:
balances and usage counters never go negative (or underflow/panic)
settlement drains exactly what was owed — no residue, no double-counting (check pre/post state deltas match expected accounting, not just "it didn't crash")
every state transition stays valid (no contract invariant like locked <= balance is ever violated mid-sequence)
no operation panics for any in-range input — I'll run with overflow checks on so silent wraparound in release mode doesn't hide behind the fuzz not crashing
Cap iterations for CI. Match whatever bound the existing two targets use (e.g. same cases/iterations constant or CI-time-based cap) so the new target adds coverage without changing the job's overall runtime meaningfully. If I need a heavier sweep later, that's explicitly out of scope per the issue notes — leave a comment pointing at a follow-up for a scheduled/nightly job.
Wire into .github/workflows/ci.yml. Add the new file to the same Fuzz targets (bounded) job, matching how the existing two are invoked (same runner step, same flags) — no new job, no new workflow.
Validate locally before opening the PR. Run the new target standalone to confirm it actually triggers real code paths (not silently passing because the harness never calls settlement), then run it against a couple of intentionally broken settlement variants (e.g. temporarily allow double-release) to confirm the invariants actually catch the break — a fuzz test that can't fail is worthless. Revert those before committing.
If the fuzzer finds a real bug, I won't fix it inline as part of this PR — I'll capture a minimal reproduction (seed/input sequence) and file it as a separate issue, per the acceptance criteria, keeping this PR scoped to adding the test infrastructure.
Keep the diff surgical: new fuzz test file + the CI workflow addition only. No refactors to the escrow module itself unless something in step 2 turns out to require a small testability hook (e.g. exposing an internal getter for assertions) — and if so, I'll call that out explicitly in the PR body rather than sneaking it in.

Deliverable: one new soroban/tests/escrow_settlement_fuzz.rs (naming to match the existing convention), a small diff to ci.yml, and a PR description spelling out the invariants tested and why they guarantee correctness-of-funds for this path.

[grantfox-oss]

🦊 GrantFox — @Mac-5 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 #31)
2. Your PR will be reviewed by the stellar-kracken maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@Mac-5's PR #33 was approved and merged by @Meshmulla.

🏆 @Mac-5: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (497 total points). Track your full progress on GrantFox.

👏 Great work, @Mac-5! Keep contributing to stellar-kracken.