What Is Riptide?
Riptide is an economic stress-test framework for Solana programs. It runs your compiled program against scripted market conditions — whales concentrating positions, oracles lagging, prices shocking, withdrawal queues forming — and checks whether the properties you care about (solvency, backing, margin safety, etc.) still hold.
Instead of asking does my code compile or do unit tests pass, it asks does the economy this program defines behave how I expect when real users push on it? Every run is deterministic: same inputs and seed produce the same output, so a failure is something you can reproduce, share, and investigate.
Concepts to know
- Adapter — a TOML file that tells Riptide what your program is (bytes, IDL, accounts, actions, optional decoders) and what properties should hold (invariants).
- Harness — optional Rust setup code that runs before tick 0 to write real account bytes, SPL mints and vaults, PDAs, external accounts, or sibling programs.
- Guided simulation — optional Rust flow code under
.riptide/sim/for dynamicremaining_accounts, multi-instruction transactions, forked snapshots, and project-owned external dependency services. - Scenario — a config file describing who acts, how many ticks run, how many seeds to sweep, and what market conditions apply. One seed is one rerunnable experiment.
- Persona — a deterministic behavior policy for one class of actor (steady LP, panic whale, arb bot, liquidator). Personas live as
[personas.<slug>]blocks in the adapter and are referenced by scenario run configs. - Agent — one simulated user inside a run. The scenario's
agentsfield is a population count; each agent is assigned a persona and acts independently per tick. - Tick — one simulated step (≈ one Solana slot ≈ 400 ms simulated). Every persona evaluates and may submit an action per tick; observations and invariants are evaluated after.
- Invariant — a machine-checkable property declared on the adapter that should hold every tick (no bad debt, health factor stays above the floor). When one fires, the run records the tick and the engine exits non-zero so CI can gate on it.
- Evidence pack — what every run emits:
manifest.json,summary.md,trace.md,rerun.sh, path indexes, and a canonical hash. This is what you hand to reviewers or CI. - Studio — the localhost visual control plane started by
riptide studio. It can bootstrap a thin workspace, drive local Agent chat, inspect artifacts, queue allowlisted jobs, and open run/replay dashboards.
Quick Path
The first pass through Riptide is: install it, scaffold .riptide/ in your repo, fill the adapter, add a harness when setup needs real account bytes, use guided sims when external state must evolve during flows, smoke one seed, then run the scenario sweep or guided artifact and inspect the evidence. Open riptide studio when you want a browser surface for that loop.
Trust boundary: Riptide produces simulation evidence, not a broad review result and not a broad safety result. A run collection and pack are useful because their committed inputs, seed, invariant firings, coverage checks, trace, rerun command, and canonical hash can be inspected and rerun.
Deep Reference
These landing docs are the MVP path. The repo docs remain the source material for detailed implementation behavior, toolchain pins, and reviewer handoff mechanics.