fix(stake,v17): pause junior deposits while an insurance loss is outstanding (closes #149; also closes the junior side of #145)

[0x-SquidSol]

Closes #149. Also closes the junior recovery-snipe of #145 (same root cause + same gate).

What

effective_junior_balance() charges the junior tranche the pool's current net_loss = total_flushed − total_returned with no baseline for when the junior cohort began. So a junior depositing into a pool that already has an outstanding loss (borne by the global/senior cohort) instantly inherits that pre-existing loss.

PoC (verified against the v17 functions): Greg deposits 3,000,000 (non-tranche) → admin flushes 600,000 (Greg's loss is real) → admin enables tranches → Jane deposits 1,000,000 as the first junior, mints 1:1 → her stake is immediately worth 400,000 (−600,000), and Greg withdraws his full 3,000,000 (his loss evaporated onto Jane). Conservation holds globally, so no runtime check catches it.

Fix

Gate process_deposit_junior to reject (StakeError::InsuranceLossOutstanding) while total_flushed > total_returned.

• Closes both directions: First junior depositor inherits a pre-existing insurance loss (loss-inheritance side of #145; deterministic loss to honest depositors) #149 (loss-inheritance) and Tranche deposits during an outstanding recoverable loss capture the insurance recovery from incumbent LPs (generalizes #139) #145's recovery-snipe both require a junior deposit during an outstanding loss; one gate makes that unreachable.
• Junior-only: a senior deposit prices against the current marked-down senior_balance and never perturbs effective_junior_balance, so it neither inherits a loss nor needs gating (verified by all reviewers).
• Mode-1 unaffected: FlushToInsurance is mode-0 only, so total_flushed > total_returned is never true in a trading pool — the gate is inert there.
• Self-lifting / no DoS: deposits resume once insurance is fully returned; total_flushed/total_returned move only via admin Flush/Return, so there's no unprivileged way to hold the gate closed.

Why a gate, not a re-pricing

Three independent solution proposals were reviewed. The alternative — a per-cohort loss-baseline snapshot (charge junior only for losses after it joined) — keeps the junior tranche open and fairly priced during a loss, which is more flexible. But it rewrites the audited effective_junior_balance loss math, adds StakePool state + cohort-transition bookkeeping, and carries subtle policy edges (re-flush after partial recovery). That's a feature, not a security hotfix. The gate is minimal, touches none of the loss math, adds no state/layout/migration, and provably closes the vulnerability. Recommended follow-up: adopt the loss-baseline if continuous, fairly-priced junior subscriptions during an open claim are desired.

This supersedes #145's "design-call, deferred" classification: the loss-inheritance manifestation is a deterministic loss to honest depositors, not an optional pricing preference.

Verification

• cargo build --lib + cargo build-sbf: clean.
• tests/poc_junior_preexisting_loss.rs: documents the loss-reassignment math (verified against production fns) and pins the gate condition (fires while a loss is outstanding, lifts on full return).
• The handler-level revert is covered by the v17 LiteSVM e2e suite; recommend a dedicated e2e asserting DepositJunior → InsuranceLossOutstanding while total_flushed > total_returned.

[coderabbitai]

Warning

Review limit reached

@0x-SquidSol, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 30 minutes and 35 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 52888b5c-de73-4256-bef5-a84a70761f78

📥 Commits

Reviewing files that changed from the base of the PR and between 9addf4e and 636cc7c.

📒 Files selected for processing (3)

• src/error.rs
• src/processor.rs
• tests/poc_junior_preexisting_loss.rs

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[dcccrypto]

Superseded by #153 (merged) — your fix, rebased onto current main so the InsuranceLossOutstanding gate sits AFTER #148's pre_accrue_mode1 (keeping that guard intact), plus the error-codes test backfill. Your commit authorship is preserved in #153 and finding credit for #149 stands. Couldn't force-update your fork branch from here, hence the fresh PR. Thanks @0x-SquidSol!