> For the complete documentation index, see [llms.txt](https://docs.keystonefi.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.keystonefi.xyz/changelog/versions.md).

# Version History

* Tracks meaningful releases of the ksUSD vault program + surrounding docs / scripts
* Older entries cover the legacy multi-strategy architecture, retained for reference
* Canonical product: single-vault ksUSD design as of v2.0

***

## v2.1 — Jun 2026 · *current*

**Venue pivot to Phoenix Perps + two-mode scope.** Design changes for the v1 mainnet path (docs pivoted ahead of code; see the target-architecture banners).

### Venue

* Perp venue: **Phoenix Perps (Ellipsis Labs)** — program `EtrnLzgbS7nMMy5fbD42kXiUzGg8XQzJ972Xtk1cjWih`, USDC margin via Ember, on-chain CPI via the Rise SDK.
* USDC margin posted via the **Ember** program (`EMBERpYNE6ehWmXymZZS2skiFmCa9V5dp14e1iduM5qy`); integration is on-chain CPI using the **Rise SDK** (`github.com/Ellipsis-Labs/rise-public`).

### Architecture (Path B)

* jitoSOL is held **unlevered** as the spot leg for staking yield; **USDC** is the perp margin. No LST is ever posted as perp collateral.

### Modes

* v1 ships **two modes — normal basis + parked** — with transitions **automated on-chain**: the smoothed funding signal plus a keeper **dynamic threshold with a ±3% hysteresis band** (lending-vs-staking spread, floored at 0) decides the mode and the keeper bot executes the switch, no manual intervention. The band covers the round-trip switch cost and prevents whipsaw.

### Backtest

* Headline: **−0.3% max drawdown** through the 2025–26 funding compression, with **\~5% net, fully loaded** in a thin-funding regime like today (up to \~11% when funding is rich). The normal+parked figure is already net of the 20% perf fee, the margin haircut, and trading costs. The multi-year series is a SOL-perp **proxy** (Phoenix launched Dec 2025), anchored to Binance at face value because Phoenix prices funding off CEX index feeds.

***

## v2.0 — May 2026

**The ksUSD pivot.** Wholesale repositioning and code rewrite.

### Positioning

* Current canonical framing: *"Keystone Finance is the carry coordination layer for Solana."*
* Superseded: *"Keystone Finance coordinates carry across Solana's DeFi ecosystem."*
* Earlier framings retired: "on-chain analog of a multi-strategy hedge fund", "Layer 1 / Layer 2 architecture", "three risk profiles", "monetary layer", "productive reserve asset"

### Program

* Single Anchor program: `keystone_finance` (program ID `HvsAc157bJ7Pd4uGr7xssHMifGs6RMbPu14ZMsiEABWT` on devnet)
* Single state struct: `Vault` PDA at seeds `[b"vault"]` (replaces legacy `FundState` + `PortfolioState` hierarchy)
* Single share mint: `ksUSD` (6 decimals) — replaces `ksALPHA`, `ksNEUTRAL`, `ksDEFENSE`, `ksCORE`
* Two internal modes — normal basis and idle — chosen automatically by the SOL-PERP funding rate
* An on-chain perp venue (replaces Jupiter Perps in the legacy Neutral fund)
* 29 entry points: see [Instructions](/for-developers/instructions.md)

### Fee structure

* Management fee: **0%** (was 0.5% / yr on legacy Alpha & Neutral).
* Performance fee: **20% above HWM** (unchanged).
* Reserve skim: **5% of accrued perf fees** routed to the reserve fund (new).
* Withdrawal fee: **0%** on both instant and queued paths.

### Withdrawal queue

* Two-path withdrawal: `withdraw_instant` (from liquidity buffer) and `request_withdrawal` + `process_withdrawal` (queued). Replaces the legacy single `withdraw` path.

### Backtest

* **Methodology:** daily resolution on historical SOL-perp funding as a proxy for Phoenix funding. Phoenix anchors its funding to CEX index feeds, so the proxy uses Binance funding at face value (×1.0); the old Drift calibration (2.37× on positive months) ran hot and produced the earlier \~9% figure. Mode classification uses a 7-day rolling mean with a ±3% hysteresis band. 24-month window Jul 2024 – Jun 2026.
* **Max drawdown: −0.3%** through the 2025–26 funding compression — the number to read first. **Target net APY: \~5%** in a thin-funding regime like today (up to \~11% when funding is rich), fully loaded: already net of the 20% performance fee, the perp-margin haircut, and trading costs, all baked into the backtest (no separate haircut step). Gross is \~7% (6.56%). The vault floors at USDC lending (\~4%) and adds funding on top; Phoenix pays \~0% funding right now. Full breakdown: [`reference/historical-simulation.md`](/reference/historical-simulation.md).

### Docs

* New whitepaper at `gitbook/reference/whitepaper.md` (v2.0) — single-vault design, full NAV math, security model, risk disclosures.
* Marketing site (`keystone-marketing/`) rebuilt around ksUSD with a single Performance chart sourced from the canonical backtest.
* Investor memo, PRD, and outreach summary at `docs/KSUSD_*.md` updated to v0.4.

### Breaking changes

* All legacy program IDs (`keystoneAlpha`, `keystoneDefense`, `keystoneCore`) are no longer deployed. The on-chain footprint is now one program.
* `ksCORE` / `ksALPHA` / `ksNEUTRAL` / `ksDEFENSE` mints are unsupported. Integrators should consume `ksUSD` only.
* `rebalance`, `migrate_portfolio`, and all multi-fund admin instructions are gone.

***

## Pre-pivot history (legacy)

Pre-v2.0 covered the multi-strategy design:

* **Keystone Alpha** — directional LST accumulation
* **Keystone Neutral** — basis carry on Jupiter Perps
* **Keystone Defense** — JupSOL baseline + dislocation deployment
* **Keystone Core** — portfolio orchestration with ksCORE

Detailed entries are retained in git history; active narrative is v2.0+.

**Key milestones:**

* **v1.x** — multi-strategy architecture in development; Jupiter Perps as the perp venue
* **v0.11.5** (Apr 2026) — last release of the multi-strategy design; portfolio rebalancing live on devnet
* **v0.10.0** — `deploy_capital` consolidated with auto-unpark; `unpark_capital` retired

For the historical narrative and per-version technical notes, see commits on `main` prior to the May 2026 pivot.