> 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/quick-start.md).

# Quick Start

Get the ksUSD vault running locally or talking to devnet.

***

## Prerequisites

| Tool       | Version                |
| ---------- | ---------------------- |
| Rust       | 1.79+ (rustup-managed) |
| Anchor CLI | 0.31.1+                |
| Solana CLI | 1.18+                  |
| Node.js    | 20+                    |

```bash
git clone https://github.com/kamwithak/keystone-contracts.git
cd keystone-contracts
npm install
```

***

## Program ID

| Network | Program ID                                     |
| ------- | ---------------------------------------------- |
| Devnet  | `HvsAc157bJ7Pd4uGr7xssHMifGs6RMbPu14ZMsiEABWT` |
| Mainnet | *pending audit*                                |

* Single Anchor program: `keystone_finance`
* Implements the ksUSD vault end-to-end
* 29 instructions · 39 errors · 19 events · 2 account types

***

## Build

```bash
# Rust check (fast, no BPF toolchain required)
cargo check -p keystone-finance

# Generate / refresh IDL from source (uses idl-build feature)
PATH="$HOME/.cargo/bin:$PATH" anchor idl build \
  -o target/idl/keystone_finance.json
```

* IDL: `target/idl/keystone_finance.json` — regenerated to match latest source
* TS types: `target/types/keystone_finance.ts` — derived from the IDL

***

## Initialize the devnet vault

```bash
npx tsx scripts/devnet/init.neutral.ts
```

* Creates the vault PDA at seeds `[b"vault"]`
* Generates a fresh `ksUSD` mint keypair
* Calls `initialize` with default risk parameters:
  * 10% liquidity buffer
  * 0% funding safety floor (keeper applies the dynamic threshold)
  * 20% perf fee · 5% reserve skim
  * $1M deposit cap

***

## Round-trip test

```bash
npx tsx scripts/devnet/test-roundtrip.ts
```

Exercises the user flow end-to-end against the deployed vault:

1. Verifies the vault exists; mints test USDC to the wallet if the wallet holds USDC mint authority.
2. `deposit` — USDC in, ksUSD out at $1.00 share price on first deposit.
3. `withdraw_instant` — partial redemption from the liquidity buffer.
4. `request_withdrawal` + `process_withdrawal` — queued path; verifies the request PDA is closed and rent refunded.

> Strategy paths (`open_position`, `settle`) are **not** exercised here — they require Phoenix account scaffolding. Covered by the keeper bot: [Keeper bot](/for-operators/keeper-bot.md).

***

## TypeScript client

```ts
import * as anchor from "@coral-xyz/anchor";
import { Program } from "@coral-xyz/anchor";
import { Connection, PublicKey } from "@solana/web3.js";
import idl from "../target/idl/keystone_finance.json" with { type: "json" };

const PROGRAM_ID = new PublicKey("HvsAc157bJ7Pd4uGr7xssHMifGs6RMbPu14ZMsiEABWT");
const connection = new Connection("https://api.devnet.solana.com", "confirmed");

const provider = new anchor.AnchorProvider(connection, wallet, { commitment: "confirmed" });
anchor.setProvider(provider);

const program = new Program(idl as any, provider);

const [vaultPda] = PublicKey.findProgramAddressSync(
  [Buffer.from("vault")],
  PROGRAM_ID
);

const vault = await program.account.vault.fetch(vaultPda);
```

***

## Related

* [Instructions reference](/for-developers/instructions.md) — all 29 entry points
* [Account structure](/for-developers/accounts.md) — `Vault` and `WithdrawalRequest` layouts
* [Events](/for-developers/events.md) · [Errors](/for-developers/errors.md)
* [Devnet deployment](/deployment/devnet.md)