> 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/for-developers/instructions.md). # Instructions Reference The entry points exposed by the `keystone_finance` program (ksUSD vault). Grouped by caller role. > v1 hedges on Phoenix Perps (USDC margin via Ember, CPI through the Rise SDK). > Source: [`programs/keystone-finance/src/lib.rs`](https://github.com/kamwithak/keystone-contracts/tree/main/programs/keystone-finance/src/lib.rs) · IDL: `target/idl/keystone_finance.json` *** ## One-time setup (admin) | Instruction | Caller | Description | | ------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `initialize(params)` | Admin (deployer) | Creates the vault PDA at seeds `[b"vault"]` and the ksUSD share mint. Sets all risk parameters. Idempotent guard via PDA `init`. | | `enable_phoenix(subaccount_id, name)` | Admin | One-time: onboards the vault PDA as a Phoenix trader (Rise builder path) and pins the Phoenix/Ember accounts. Required before any perp position can be opened. | ### `InitializeParams` defaults | Field | Default | Meaning | | ------------------------------ | --------------------------- | ------------------------------------------------------------------------------------------------- | | `liquidity_buffer_bps` | 1\_000 (10%) | Idle USDC kept on-vault for instant withdrawals | | `funding_threshold_normal_bps` | 0 (safety floor) | On-chain floor — never short into negative funding; keeper applies the dynamic threshold above it | | `perf_fee_bps` | 2\_000 (20%) | Performance fee above HWM | | `reserve_skim_bps` | 500 (5%) | Of accrued perf fees, routed to reserve fund | | `min_dwell_seconds` | 43\_200 (12 h) | Minimum time between mode switches | | `max_swap_slippage_bps` | 50 (0.5%) | Jupiter swap slippage cap | | `emergency_close_dd_bps` | 500 (5%) | NAV drawdown from peak that trips `emergency_close` | | `deposit_cap_usdc` | 1\_000\_000\_000\_000 ($1M) | Cached-NAV cap on new deposits | | `phoenix_subaccount_id` | 0 | Phoenix subaccount index | | `phoenix_market_index` | 0 | Phoenix SOL-PERP market index | *** ## User flow (anyone) | Instruction | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `deposit(usdc_amount)` | Transfer USDC to the vault, mint ksUSD at current share price. → [Deposit](/keystone-finance/deposit.md) | | `withdraw_instant(shares)` | Burn ksUSD, receive USDC from the liquidity buffer. Reverts with `InsufficientLiquidityBuffer` if not enough idle USDC. → [Withdraw](/keystone-finance/withdraw.md) | | `request_withdrawal(shares)` | Burn ksUSD immediately, lock redemption price, create a queued `WithdrawalRequest` PDA. | | `process_withdrawal()` | Permissionless crank — fulfill a queued request, close the PDA, refund rent to the original requester. | *** ## Strategy (keeper-cranked, permissionless) All strategy instructions take a 3- to 5-group `remaining_accounts` layout. The keeper builds these off-chain (in the v1 target, with the Rise SDK + Jupiter quote API) and passes the per-group counts as u8 arguments so the handler can split safely. | Instruction | Description | | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `open_position(usdc_amount, perp_short_base_amount, jupiter_swap_data, jupiter_account_count, phoenix_deposit_account_count)` | **Normal basis open.** Split USDC → buy jitoSOL (unlevered spot leg) via Jupiter → post USDC margin on Phoenix (via Ember) → short SOL-PERP at 1× notional. | | `close_position(perp_close_account_count, settle_account_count, phoenix_withdraw_account_count, jupiter_swap_data)` | **Normal basis close.** Reduce-only long order → settle funding → withdraw USDC margin → sell jitoSOL→USDC. | | `settle()` | Read SOL-PERP funding, settle funding if a position is open, refresh peak share price, log drawdown if guard tripped. Permissionless. | | `emergency_close(perp_close_account_count, phoenix_withdraw_account_count, jupiter_swap_data)` | Force close on drawdown breach or while vault is paused. Auto-pauses vault on exit. Permissionless once tripped. | *** ## Admin | Instruction | Description | | --------------------------- | ------------------------------------------------------------------------------------- | | `set_pause(paused)` | Halt new deposits + new positions. Withdrawals from the liquidity buffer remain open. | | `update_params(args)` | Adjust risk parameters within bounds. Cannot move admin or mints. | | `transfer_admin(new_admin)` | Two-step admin handover to a multisig or successor. | | `collect_fees()` | Mint performance-fee shares (above HWM) to the treasury; route reserve skim. | *** ## Account-context groups for `remaining_accounts` Strategy instructions pack multiple downstream CPIs into one transaction. Each group's account list is documented in the handler source — link below per instruction. The Phoenix + Ember groups are assembled via the Rise SDK. | Instruction | Groups | | ----------------- | ---------------------------------------------------------------------------------------- | | `open_position` | Jupiter swap → Ember margin deposit → Phoenix place\_perp\_order | | `close_position` | place\_perp\_order (reduce-only) → settle funding → Ember margin withdraw → Jupiter swap | | `settle` | Phoenix funding / margin re-eval accounts (when position open) | | `emergency_close` | place\_perp\_order → Ember margin withdraw → Jupiter swap | See [Keeper bot](/for-operators/keeper-bot.md) for the off-chain account-assembly conventions. *** ## Errors See [Errors](/for-developers/errors.md) for the full `KsusdError` enum and exit codes.