Add a minimum-output (slippage) guard so compute_route_fee rejects routes whose net falls below a caller floor

[mikewheeleer]

Implement a caller-supplied minimum-output guard

Description

compute_route_fee in src/lib.rs returns the fee and the caller infers net = amount - fee, but there is no way for a caller to assert a minimum acceptable net in the same call. If the per-pair fee is raised by the admin between a client's quote and its route, the caller silently pays the higher fee with no protection — the classic slippage/MEV gap. This issue adds an optional min_out parameter (or a sibling route_with_min_out) that rejects the route when the computed net falls below the caller's floor.

Requirements and context

• Repository scope: StableRoute-Org/Stableroute-contracts only.
• Add compute_route_fee_checked(env, source, destination, amount, min_out: i128) -> i128 that runs the existing validation, computes net = amount - fee, and rejects with an append-only SlippageExceeded error when net < min_out.
• Keep the original compute_route_fee unchanged for backward compatibility; the checked variant builds on the same internal logic (factor the shared body into a private helper).
• min_out <= 0 means "no floor" and must behave exactly like the unchecked path.
• Emit the existing route event; do not renumber any error.

Suggested execution

• Fork the repo and create a branch
• git checkout -b feature/contracts-33-min-out-guard
• Implement changes
  • Write code in: src/lib.rs — shared private compute helper plus compute_route_fee_checked and SlippageExceeded.
  • Write comprehensive tests in: src/lib.rs #[cfg(test)] mod test — assert net-below-floor is rejected, net-at-floor passes, and min_out <= 0 matches the unchecked result.
  • Add documentation: document the slippage-protection flow in README.md.
  • Include NatSpec-style doc comments (///) on the new entrypoint.
  • Validate security assumptions: parity between checked and unchecked fee math; no off-by-one at the floor; counter/timestamp/event semantics identical.
• Test and commit

Test and commit

• Run cargo fmt --all -- --check, cargo build, and cargo test.
• Cover edge cases and failure paths: net below floor, net exactly at floor, zero/negative floor, fee raised between quote and route.
• Include the full cargo test output and a short security notes section in the PR description (threat model + mitigations).

Example commit message

feat: add minimum-output slippage guard to route computation

Guidelines

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

Community & contribution rewards

• 💬 Join the StableRoute community on Discord for questions, reviews, and faster merges: https://discord.gg/37aCpusvx
• ⭐ 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.

[Baskarayelu]

I’d love to be assigned this issue and contribute across the relevant areas, whether it involves smart contracts, UI development, backend logic, design implementation, or overall system integration. I’m comfortable working across the full stack and can adapt to the project’s technical requirements to ensure a smooth and consistent contribution.