Add a paused-state read variant of quote_route that reports whether compute_route_fee would currently succeed

[mikewheeleer]

Add a quote_route_status read that surfaces the pause gate and every guard outcome

Description

quote_route in src/lib.rs returns (fee, net) but intentionally ignores the pause switch, the min/max bounds, the liquidity floor, and the cooldown — so an integrator can get a clean quote for a route that compute_route_fee would immediately reject. The existing is_routable (issues-4) returns a single bool. This issue adds a richer quote_route_status read that returns the quote plus a typed reason code describing exactly why the live route would fail (paused, below min, above max, insufficient liquidity, cooldown, or OK), so callers can plan and explain rejections without a state-changing dry run.

Requirements and context

• Repository scope: StableRoute-Org/Stableroute-contracts only.
• Add a RouteStatus #[contracttype] enum (or a u32 reason field) covering: Ok, Paused, BelowMin, AboveMax, InsufficientLiquidity, CooldownActive, NotRegistered.
• Add quote_route_status(env, source, destination, amount) -> (i128, i128, RouteStatus) that mirrors every compute_route_fee precondition read-only — no counter, timestamp, liquidity decrement, or event writes.
• This is distinct from is_routable (single bool) and quote_route_checked (cooldown-only) by reporting the specific blocking reason across all guards including the pause gate.
• Reuse the same threshold reads as compute_route_fee so the two can never disagree.

Suggested execution

• Fork the repo and create a branch
• git checkout -b feature/contracts-quote-route-status
• Implement changes
  • Write code in: src/lib.rs — add the RouteStatus type and the quote_route_status read.
  • Write comprehensive tests in: src/lib.rs (inline #[cfg(test)] mod test) — drive each branch: paused, below min, above max, low liquidity, active cooldown (with env.ledger() control), unregistered, and the OK path; assert no state mutation occurs.
  • Add documentation: document the read and the status enum in README.md and docs/abi.md.
  • Include NatSpec-style doc comments (///) on the new type and entrypoint, matching the existing style in lib.rs.
  • Validate security assumptions: strictly read-only, no event emission, no TTL bump, no liquidity debit.
• Test and commit

Test and commit

• Run cargo fmt --all -- --check, cargo build, and cargo test.
• Cover edge cases: each blocking reason in isolation and a fully routable pair returning Ok.
• Include the full cargo test output in the PR description.

Example commit message

feat: add quote_route_status read reporting the live route gate outcome with tests and docs

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.

[gloskull]

Hi, I’d love to work on this issue. I have 4 years of experience across backend, frontend, full-stack, and smart contract development. I understand the task clearly and can deliver a clean, efficient, well-tested solution on time, with strong focus on code quality and maintainability. My PR will be submitted in under 10 hours.