Freeze unstaking coins during cooldown; close account on full unstake

[MagicalTux]

Summary

Reworks the unstake flow so that:

1. Partial unstake loses only a proportional share of immature rewards (not the whole position's).
2. Full unstake fully resets the position and closes the stake account (reclaiming rent), every time.
3. Partial unstake loses cumulated weight proportional to the unstaked ratio.
4. Coins with a pending unstake request stop earning new rewards during the cooldown.

It also makes the upgrade safe for unstake requests that are already in flight when the program is upgraded.

Behavior

Cooldown: requested coins stop earning (#4)

RequestUnstake now settles the request immediately instead of leaving the coins staked:

• The requested coins are removed from the pool's reward accounting (total_staked / sum_stake_exp) at request time, so they earn nothing during the cooldown.
• Their already-earned rewards are paid out then (auto-claim, mirroring direct Unstake); owner is now writable to receive the SOL.
• Only the token transfer is deferred to CompleteUnstake; the tokens stay in the vault until the cooldown elapses.

Partial unstake/request (#1, #3)

Weight is linear in amount for a fixed exp_start_factor, so removing amount × exp_start_factor drops weight by exactly the unstaked ratio, and the forfeited-immature-reward redistribution is scaled to the unstaked fraction. This already held for direct Unstake; it now also applies at request time.

Full unstake closes the account (#2)

A full unstake (direct Unstake or CompleteUnstake) pays out the user's rewards in full and closes the account 100% of the time. The pool holds every staker's unclaimed rewards, so a shortfall should never occur; if one ever did, the unpayable remainder is redistributed to the remaining stakers via last_synced_lamports rather than being stranded on a closed account. An optional trailing metadata account lets the close decrement member_count.

Cancel restores the position

CancelUnstakeRequest adds the frozen coins back to the active position (total_staked / sum_stake_exp restored at the original maturity) and gives the re-added tokens a fresh reward snapshot so they earn no cooldown-period rewards (mirrors add-stake). pool is now writable.

Migration safety for legacy in-flight requests

Requests created by the old code only set the request fields — they never removed the coins from the pool. The new Cancel/Complete would otherwise double-credit (Cancel) or under-remove (Complete) them. Since legacy-pending and new-pending look identical in the per-account fields, a 1-byte UserStake.unstake_request_settled marker is added (set to 1 only by the new RequestUnstake; legacy accounts deserialize it as 0, relying on realloc zero-fill like claimed_rewards_wad). Branching on it:

• Cancel — settled==1 restores to the pool; settled==0 (legacy) just clears the request, restoring nothing.
• Complete — settled==1 delivers tokens + closes; settled==0 (legacy) runs the full execute_unstake (settle + remove from pool + transfer + close), matching the pre-upgrade flow.

UserStake::LEN grows 177 → 178 (LEGACY_LEN stays 161); old 153/161/177-byte accounts are still read and lazily reallocated.

Files

• instructions/unstake.rs — extract settle_unstake_accounting + close_user_stake_account helpers; execute_unstake always closes on full unstake; optional metadata account.
• instructions/request_unstake.rs — settle + auto-pay + freeze; set unstake_request_settled = 1; owner writable.
• instructions/complete_unstake.rs — new-style: deliver + close; legacy: full execute_unstake.
• instructions/cancel_unstake.rs — restore frozen stake (new) / clear-only (legacy); pool writable.
• state.rs — unstake_request_settled field; LEN 177→178; deserialize + tests.
• error.rs — ResidualRewardsPending (defensive guard).
• lib.rs / idl.json / README.md — account tables, UserStake layout, docs.

Testing

• Rust unit tests (33) — including legacy-account deserialization classifying as settled==0.
• Rust integration tests (tests/legacy_migration.rs, ProgramTest/BanksClient) — craft the exact pre-upgrade on-chain state and verify:
  • legacy_cancel_does_not_credit_stake: legacy cancel leaves total_staked and the user's amount unchanged (no stake credited).
  • legacy_complete_full_removes_and_closes: legacy complete runs the full unstake (real Token-2022 transfer CPI), drains the vault, zeroes total_staked, and closes the account.
• TS E2E (test_staking.ts, both SPL Token and Token-2022) — new cooldown tests (frozen coins stop earning, partial-request proportional removal, full-unstake close, cancel restore); conservation/multi-phase tests adjusted to exclude refunded close rent; "cannot claim after full unstake" rewritten for auto-close.
• CI — cargo test is now run in CI (it previously only ran build-sbf + the TS suite), with protobuf-compiler installed for solana-program-test; added a concurrency group with cancel-in-progress to avoid stale runs piling up.

🤖 Generated with Claude Code