> 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/reference/protocols.md).

# Protocol Integrations

> v1 hedges on **Phoenix Perps** (Ellipsis Labs) via on-chain CPI, USDC margin through **Ember**. The Phoenix/Ember CPI surface below is finalized with the integration.

The ksUSD vault interacts with external Solana protocols via CPI, all signed by the vault PDA. Keystone integrates Phoenix through the **Rise SDK** (`github.com/Ellipsis-Labs/rise-public`), borrowing its on-chain account views; other integrations construct instructions and accounts directly.

***

## Venues

| Role                    | Program / Asset                                            | Address                                        |
| ----------------------- | ---------------------------------------------------------- | ---------------------------------------------- |
| Perp venue (mainnet)    | Phoenix Perps (Ellipsis Labs)                              | `EtrnLzgbS7nMMy5fbD42kXiUzGg8XQzJ972Xtk1cjWih` |
| Margin (USDC → Phoenix) | Ember                                                      | `EMBERpYNE6ehWmXymZZS2skiFmCa9V5dp14e1iduM5qy` |
| Spot leg                | jitoSOL (LST, held for staking — **not** posted as margin) | `J1toso1uCk3RLmjorhTtrVwY9HJ7X8V9yYac6Y7kGCPn` |
| Lending / parked        | Kamino USDC reserve                                        | `D6q6wuQSrifJKZYpR1M8R4YawnLDtDsMmWM1NbBmgJ59` |
| Quote / settlement      | USDC                                                       | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` |

Keystone integrates Phoenix via on-chain CPI (PDA-signed) using the Rise SDK.

***

## Dependencies

| Protocol                          | Purpose                                                                   | Where used                                                                          |
| --------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| **Phoenix Perps** (Ellipsis Labs) | SOL-PERP short; USDC margin (posted via Ember); real two-sided funding    | `open_position`, `close_position`, `settle`, `emergency_close`, `enable_phoenix`    |
| **Ember**                         | Routes USDC → Phoenix perp margin                                         | `open_position`, `close_position` (margin post/withdraw)                            |
| **Kamino KLend**                  | USDC lending for buffer + parked + reserve capital                        | `enable_lending`, `lend_idle_usdc`, `unlend_usdc`, `lend_reserve`, `unlend_reserve` |
| **Jupiter V6**                    | All token swaps (USDC ↔ jitoSOL); off-chain quote, on-chain execution     | Every open/close path that crosses tokens                                           |
| **Pyth (pull oracles)**           | SOL/USD + jitoSOL/USD for NAV math, drawdown guard, depeg check           | `settle`, `open_*`, `close_*`, `set_oracles`                                        |
| **Jito (jitoSOL)**                | Liquid staking; held **unlevered as the spot leg** (not posted as margin) | Implicit — staking yield is embedded in the jitoSOL/SOL exchange rate               |
| **Marginfi**                      | Reserved as a second USDC lending venue (v1.1)                            | Vault fields pinned at init; not yet CPI-wired                                      |

***

## Verified mainnet addresses

| Item                                  | Address                                        |
| ------------------------------------- | ---------------------------------------------- |
| Phoenix Perps Program                 | `EtrnLzgbS7nMMy5fbD42kXiUzGg8XQzJ972Xtk1cjWih` |
| Ember Program (USDC → Phoenix margin) | `EMBERpYNE6ehWmXymZZS2skiFmCa9V5dp14e1iduM5qy` |
| Phoenix SOL-PERP market               | resolved via `PerpAssetMap` (Rise SDK)         |
| Kamino KLend Program                  | `KLend2g3cP87fffoy8q1mQqGKjrxjC8boSyAYavgmjD`  |
| Kamino Main Market                    | `7u3HeHxYDLhnCoErrtycNokbQYbWGzLs6JSDqGAv5PfF` |
| Kamino USDC Reserve                   | `D6q6wuQSrifJKZYpR1M8R4YawnLDtDsMmWM1NbBmgJ59` |
| Kamino USDT Reserve                   | `H3t6qZ1JkguCNTi9uzVKqQ7dvt2cum4XiXWom6Gn5e5S` |
| Jupiter V6 Program                    | `JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4`  |
| jitoSOL mint                          | `J1toso1uCk3RLmjorhTtrVwY9HJ7X8V9yYac6Y7kGCPn` |
| USDC mint                             | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` |

***

## CPI surface (Rust)

| Module                          | Helpers                                                                                                                                                                                                                                                                                        |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `utils::phoenix_cpi` *(target)* | Onboard trader (Rise builder path), post/withdraw USDC margin via Ember, `place_perp_order`, `cancel_orders`, settle funding, `read_phoenix_funding_rate` — built on the `phoenix-rise` account views (`TraderHeader`, `TraderPositions`, `PerpAssetMap`, `GlobalConfig`, `PermissionAccount`) |
| `utils::kamino`                 | `deposit_reserve_liquidity`, `redeem_reserve_collateral`, `refresh_reserve`                                                                                                                                                                                                                    |
| `utils::jupiter_swap`           | `route_swap`, `require_min_received`                                                                                                                                                                                                                                                           |
| `utils::oracle`                 | Pyth pull-oracle staleness + confidence wrappers, jitoSOL/SOL depeg check                                                                                                                                                                                                                      |

* Each helper threads the vault PDA signer seeds (`[b"vault", &[bump]]`)
* Phoenix account views come from the `phoenix-rise` crate (borrowed, zero-copy); Kamino returns are validated with minimal Borsh
* Offsets are hard-coded against the verified Kamino layout; Phoenix uses the Rise account definitions

***

## Off-chain account assembly

Strategy instructions take 3–5 groups of `remaining_accounts` plus a per-group count. The keeper builds these off-chain using:

* **Phoenix** — the Rise SDK (`github.com/Ellipsis-Labs/rise-public`) gives the canonical account ordering for trader onboarding, margin (Ember) deposit/withdraw, `place_perp_order`, and funding settlement.
* **Kamino** — same pattern; the `refresh_obligation` + collateral instructions take a fixed pattern documented in the Kamino IDL.
* **Jupiter** — Jupiter's `/swap-instructions` endpoint returns the swap data buffer (passed as `jupiter_swap_data`) plus the matching account list (passed in the corresponding remaining-accounts group).

See [Keeper bot](/for-operators/keeper-bot.md) for the off-chain orchestration pattern.

***

## Related

* [Whitepaper](/reference/whitepaper.md) — single-page overview of the system
* [Instructions reference](/for-developers/instructions.md) — per-instruction account-context groups
* [Quick start](/for-developers/quick-start.md)