# Riptide

> Riptide is a deterministic economic stress-test framework for Solana programs. It runs your compiled SBF/BPF bytecode under LiteSVM, drives it with adversarial actors, asserts protocol invariants, and emits replayable evidence packs.

## What Riptide Is

Riptide loads your compiled Solana program bytecode (the same `.so` you would deploy) and runs it inside LiteSVM, a stripped-down execution substrate. On top of that bytecode, Riptide drives the program with scripted economic actors — borrowers, liquidators, LPs, arbitrageurs, redeemers — under explicit scenario inputs such as a baseline tick loop or lending oracle drawdown. While the simulation runs, declared invariants (collateral health, full backing, margin safety, etc.) are checked at every tick. When a run finishes (passing or failing), Riptide emits a reviewer-ready evidence pack that can be re-executed by anyone, anywhere.

The framing is deliberate:

- It does **not** ask "does my code compile?" or "do unit tests pass?" — those are answered elsewhere.
- It asks **"does the economy this program defines behave the way I expect when real users push on it?"**

Every run is deterministic. Same inputs, same seed → same canonical hash. A failure is something you can reproduce, share with reviewers, and investigate offline.

## Core Concepts

- **Adapter** — a TOML file that tells Riptide what your program is (program bytes, IDL, accounts, actions, optional decoders, observations, oracle bindings) 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.
- **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. Personas live as `[personas.<slug>]` blocks in the adapter and are referenced by scenario run configs.
- **Run collection** — what `riptide run` writes for a sweep: scenario status, verdict, confidence, coverage checks, artifact paths, and metric previews.
- **Evidence pack** — what every run emits: `manifest.json`, `summary.md`, `trace.md`, `rerun.sh`, path indexes, and a canonical hash, all hashed for reproducibility. This is what you hand to reviewers or CI.
- **Studio** — the localhost visual control plane started with `riptide studio`. It can bootstrap a thin workspace, use local Agent chat, inspect adapters/campaigns/reports/evidence, queue allowlisted jobs, and open run/replay dashboards. It is not a hosted service or generic shell.

## Documentation

- [Riptide Docs Overview](https://riptidesim.com/docs/): The entry point. Explains adapter, harness, scenario, persona, agent, tick, invariant, and evidence pack, plus the shortest path through install → init → adapter → harness → scenario sweep → evidence pack → CI handoff. Includes a "Trust Boundary" callout that frames Riptide's outputs as simulation evidence, not a broad audit or safety claim.
- [Install](https://riptidesim.com/docs/install/): Three install paths — hosted installer (`curl -fsSL https://riptide.run/install | sh`), build-from-source out of the GitHub repo, and a Docker image. Covers launcher verification with `riptide --help`, workspace checks with `riptide doctor`, and current distribution posture.
- [Quickstart](https://riptidesim.com/docs/quickstart/): Walks through using the thin `riptide init` scaffold inside your own program repo, invoking `/riptide-config` to finish adapters, harness setup, scenarios, and campaign readiness, smoking one seed, running the scaffolded scenario suite with `riptide run --adapter .riptide/adapters/<program>.toml --harness .riptide/harness`, inspecting the printed pass/fail summary, opening the local collection dashboard, and finding the evidence pack at `.riptide/pack/<run-id>/`.
- [Studio](https://riptidesim.com/docs/studio/): Documents `riptide studio`, the localhost visual control plane for local workspaces. Covers startup flags (`--workspace`, `--case-studies-root`, `--no-open`, `--host`, `--port`), first-run thin bootstrap, project registry, Agent chat for local Claude Code/Codex setup work, evidence/report browsing, dashboard drilldowns, allowlisted job queue, and the localhost/no-generic-shell trust boundary.
- [First Adapter](https://riptidesim.com/docs/first-adapter/): The adapter TOML model field-by-field — program bytes and IDL, accounts, decoder presets (`spl_token_account`, `spl_mint`) and raw layout decoders, instruction mappings, observations, inline personas, invariants, and versioned semantic overlays for the shipped protocol fixtures. Includes worked examples for IDL-backed fields and SPL-token-vault reserve observations.
- [Harness](https://riptidesim.com/docs/harness/): How to generate and fill `.riptide/harness`, a Rust pre-tick setup crate for account bytes, SPL mints and vaults, PDAs, external accounts, sibling programs, and harness-backed one-seed smokes.
- [Scenarios](https://riptidesim.com/docs/scenarios/): How to declare actors and market dynamics with `seed` or `seeds`, inline adapter persona slugs, oracle trajectories, seed sweeps, event-count math, and invariant checks.
- [Replay Artifacts](https://riptidesim.com/docs/replay-artifacts/): Anatomy of an evidence pack — `manifest.json` (run identifiers, seed, canonical hash), `summary.md` (reviewer summary), `trace.md` (technical trace), `rerun.sh` (POSIX-only deterministic rerun command), and input/output path indexes. Explains how a reviewer verifies reproducibility by re-executing `rerun.sh` and comparing canonical hashes.
- [Failure Patterns](https://riptidesim.com/docs/failure-patterns/): Pattern explainers across protocol classes — bad debt, depeg, redemption runs, cross-protocol contagion — each with a deterministic rerun and explicit claim boundaries.
- [CI Handoff](https://riptidesim.com/docs/ci-handoff/): How to wire `riptide run` into GitHub Actions or another CI, what a green workflow URL conveys, how to attach an evidence pack to a PR, and how reviewers consume the artifact.
- [FAQ](https://riptidesim.com/docs/faq/): Trust boundary discussion (Riptide does not certify a program as safe), LiteSVM caveats (no consensus, no PoH, no gossip — validator-level behavior is a separate diagnostic path), supported bundles, `.riptide` discovery semantics, and install availability.

## Adapters Catalog

Protocol fixtures and scaffolds ship as starting points. Each is a working example or template you can run or adapt, but new integrations should start as generic adapter mappings plus optional harness setup rather than one-off protocol decoders in Riptide core.

- [Adapters Catalog Index](https://riptidesim.com/adapters/): Browse all shipped adapter fixtures with declared invariants and source links.
- **Lending** — Lending stress surface for whale concentration, utilization climb, oracle lag, and bad-debt boundaries. Invariants: collateral health, LP solvency, bad debt.
- **Perpetuals** — Margin safety, funding bounds, insurance-fund pressure, and oracle-driven stress. Invariants: margin safety, funding bounds, insurance fund.
- **AMM** — Constant-product AMM adapter for reserve-pair checks, fee bounds, LP supply, and price-impact stress. Invariants: reserve pairing, fee bounds, LP supply.
- **Liquid Staking** — Pooled-stake and withdrawal-queue surface for slash, depeg, queue, and contagion replay tests. Invariants: stake pool solvency, unstake queue, slashing.
- **Stablecoin** — Collateral, stable-supply, reserve-buffer, and redemption-queue surface for backing stress. Invariants: full backing, reserve buffer, redemption queue.
- **Generic** — Bring your own invariants. The generic adapter path supports IDL-backed fields, raw byte layout decoders, SPL Token account and mint decoder presets, optional harness setup for any Solana program, and the shipped resource-grinder fixture for non-DeFi SBF/IDL coverage. Shipped protocol fixtures declare semantic overlays for `lending.v1`, `perps-margin.v1`, `amm.v1`, `lst.v1`, and `stablecoin.v1`.

## Scenarios Catalog

- [Scenarios Catalog Index](https://riptidesim.com/scenarios/): Browse shipped engine scenario configs with the exact `riptide run` command and an explanation of the experiment.
- **Lending whale shock grid** — Canonical whale-share x shock-magnitude lending demo cell for bad-debt boundary review. `riptide run lending/whale-shock-grid --serve`.
- **AMM price impact** — AMM pool-invariant and reserve-derived price-impact stress over swap-heavy liquidity pressure. `riptide run amm/price-impact`.
- **Stablecoin redemption-run sweep** — Stablecoin redemption pressure and queue formation under backing stress. `riptide run stablecoin/redemption-run-sweep`.
- **Resource-grinder sweeps** — Generic SBF/IDL scenario fixtures for botter share, marketplace saturation, and persona mix pressure. `riptide run resource-grinder/persona-mix-sweep`.
- Replay fixtures cover depeg, redemption-run, contagion, and collateral-cascade shapes through a separate deterministic replay path.

## Evidence — Case Studies

Proof-level failure-shape and incident economic-shape case studies. Each has a canonical hash, a deterministic rerun recipe, and an explicit "does not claim" boundary that distinguishes simulation evidence from historical incident reconstruction. The four named incident additions below are shape replays, not bytecode-level reproductions.

- [Case Studies Index](https://riptidesim.com/case-studies/): Browse all proof-level case studies.
- [Lending Whale Bad Debt](https://riptidesim.com/case-studies/lending-whale-bad-debt/): Models the failure geometry of Solend's June 2022 whale-risk episode — concentrated borrower exposure plus an oracle drawdown driving residual bad debt at the pool level. The replay seeds five whale borrowers (collateral=100, debt=6400 each), drives the oracle from 100 → 60 over four ticks, runs five liquidator instructions at tick 4, and observes that the strict `no_bad_debt` invariant fires with bad_debt=3600.0 against expected 0.0. Ships with a 3×3 whale-share × shock-magnitude sweep classifying cells as SAFE vs. FIRE; the unsafe boundary is the 40% shock column. **Does not claim** to reconstruct Solend's on-chain incident byte-for-byte, to model the SLND1/SLND2 governance path, or to make any safety claim about Solend, Save, Kamino, MarginFi, or any other production lending market.
- [Euler Donate and Liquidate](https://riptidesim.com/case-studies/euler-donate-and-liquidate/): Economic-shape replay of the donate-and-liquidate geometry associated with Euler's March 2023 exploit. The replay runs on Riptide's Solana toy lending fork: `donate(80)` removes collateral without an LTV recheck, liquidation follows, and `no_bad_debt` fires at tick 2 with bad_debt=4720.0. **Does not claim** to replay Euler's EVM bytecode or exploit transactions.
- [KelpDAO Unbacked rsETH](https://riptidesim.com/case-studies/kelpdao-unbacked-rseth/): Economic-shape replay of unbacked LST supply associated with KelpDAO / rsETH bridge-trust failure. The replay runs on Riptide's Solana liquid-staking toy program: `admin_mint_lst(5000)` increases LST claims without underlying assets, and `full_backing` fires at tick 1. **Does not claim** to replay EigenLayer, Kelp, rsETH, or bridge transactions.
- [Mango Oracle Pump](https://riptidesim.com/case-studies/mango-oracle-pump/): Economic-shape replay of the oracle-pump-to-underwater-borrow geometry associated with the October 2022 Mango Markets exploit. The replay runs on a Solend-shaped toy lending fork: price moves 100 → 500 → 100, borrow opens under the inflated price, and `oracle_bounds` fires at tick 2 with bad_debt=26750.0. **Does not claim** to replay Mango v3 bytecode, TWAP composition, Serum/OpenBook venue execution, or the incident slot.
- [Loopscale Collateral Mispricing](https://riptidesim.com/case-studies/loopscale-collateral-mispricing/): Economic-shape replay of inflated collateral valuation associated with Loopscale's April 2025 incident. The replay runs on a Solend-shaped toy lending fork: the borrower is healthy at oracle price 200, becomes underwater when price corrects to 100, and `collateral_health` fires at tick 2 with bad_debt=4175.0. **Does not claim** to replay Loopscale bytecode, account state, or LP-token NAV calculation.

## Evidence — Replay Gallery

Mirrored replay packs from the main Riptide repo, each with invariant fires, a trace, and a rerun script.

- [Gallery Index](https://riptidesim.com/gallery/): Browse all mirrored replay packs.
- [Lending Whale Bad Debt](https://riptidesim.com/gallery/lending-whale-bad-debt/): Failure-shape case study. `no_bad_debt` fires at tick 4 (observed bad_debt=3600.0). Canonical hash `6c59db5e…d16c4a1`.
- [Euler Donate and Liquidate](https://riptidesim.com/gallery/euler-donate-and-liquidate/): Incident economic-shape replay. `no_bad_debt` fires at tick 2 (observed bad_debt=4720.0). Canonical hash `03de00e2…14a2f8`.
- [KelpDAO Unbacked rsETH](https://riptidesim.com/gallery/kelpdao-unbacked-rseth/): Incident economic-shape replay. `full_backing` fires at tick 1. Canonical hash `ff46b6a1…8d0b09`.
- [Mango Oracle Pump](https://riptidesim.com/gallery/mango-oracle-pump/): Incident economic-shape replay. `oracle_bounds` fires at tick 2 (observed bad_debt=26750.0). Canonical hash `d2344f72…920e6`.
- [Loopscale Collateral Mispricing](https://riptidesim.com/gallery/loopscale-collateral-mispricing/): Incident economic-shape replay. `collateral_health` fires at tick 2 (observed bad_debt=4175.0). Canonical hash `d6d71b3b…86ff`.
- [Liquid Staking Depeg + Redemption Run](https://riptidesim.com/gallery/liquid-staking-depeg-redemption-run/): Slash-driven exchange-rate drop turning into a redemption run. Seven invariant firings across two declared invariants; `no_slash_during_healthy_run` fires at tick 3.
- [LST → Lending Contagion Proof](https://riptidesim.com/gallery/lst-lending-contagion-proof/): Cross-protocol contagion. An upstream liquid-staking markdown crosses an oracle boundary and becomes downstream lending bad debt.
- [Stablecoin UXD-Style Collateral Cascade](https://riptidesim.com/gallery/stablecoin-uxd-style-collateral-cascade/): Delta-neutral stablecoin failure shape — delegated-collateral hedge losses turning a fully-backed accounting surface into a redemption queue.

## How a Run Works (End-to-End)

1. **Scaffold the workspace.** Run `riptide init` to create the thin `.riptide/` bootstrap, then invoke `/riptide-config` in the repo to finish the adapter, optional harness, scenarios, invariants, and campaign readiness.
2. **Optionally open Studio.** Run `riptide studio --workspace .` for a local browser control plane. Use it to inspect the scaffold, start Agent chat, queue allowlisted runs, and read reports without leaving the repo-local file workflow.
3. **Map the program.** Fill or review the adapter TOML with the `.so`, IDL, accounts, instructions, optional decoders, observations, personas, invariants, and semantics you care about.
4. **Set up account bytes.** When zeroed bootstrap accounts are not enough, fill `.riptide/harness/src/main.rs` so SPL vaults, PDAs, external accounts, sibling programs, and per-agent accounts exist before tick 0.
5. **Declare scenarios.** Configure run configs with agents, ticks, `seed` or `seeds`, and persona slugs. One seed is one rerunnable experiment; larger seed counts run deterministic sweeps.
6. **Run.** `riptide run --adapter .riptide/adapters/<program>.toml --harness .riptide/harness --serve` validates the adapter, executes the scenario tick-by-tick under LiteSVM, checks invariants and coverage, and writes a run collection plus an evidence pack.
7. **Inspect and hand off.** Open Studio, the local collection dashboard, or the pack's `summary.md` and `trace.md`. The pack ships a `rerun.sh` that anyone can execute to verify the canonical hash matches; attach it to a PR and gate merges on invariant breaches.

## Differentiation

Riptide complements rather than replaces other Solana testing tools:

- **vs. unit tests / Mollusk** — Unit tests assert per-instruction correctness against synthetic state. Riptide asserts whole-economy invariants under multi-actor stress.
- **vs. fuzzing / Trident** — Fuzzers mutate inputs to find crashes and panics. Riptide drives actor-shaped scenarios against shared state to find economic invariant violations: insolvency, depegs, liquidation cascades.
- **vs. formal methods (e.g. QEDGen-style Lean proofs)** — Formal methods prove properties about code paths and access control. Riptide produces simulation evidence about emergent economic behavior under adversarial activity.
- **vs. audits** — Auditors reason about correctness and access control across a program. Riptide produces reviewable, rerunnable simulation artifacts. It does **not** certify a program as safe.

The intended position: one layer of evidence in a defense-in-depth stack — alongside audits, fuzzing, formal methods, and unit tests.

## Determinism Guarantees

- The engine is fully deterministic. Same bytecode + same config + same seed → same canonical hash.
- An evidence pack is seeded, hashed, and rerunnable. Divergence is reported, not silently absorbed.
- A simulation run does not depend on an LLM call. Optional local skills can help author TOML or write reports, but they are not in the run path.

## Trust Boundary (read this before citing Riptide outputs)

Riptide produces **simulation evidence**, not a broad audit result and not a broad safety result. A run collection or evidence pack is useful because its committed inputs, seed, invariant firings, coverage checks, trace, rerun command, and canonical hash can be inspected and rerun by a reviewer. It is not a certification that any program is safe in production. Case studies that resemble historical incidents, including incident economic-shape pages, **explicitly do not claim** to reconstruct the on-chain history, bytecode, transactions, or account state of those incidents unless the page says so.

## Key Facts

- Engine: deterministic, no LLM in the run path.
- Execution substrate: LiteSVM (no RPC, gossip, vote, PoH, or full consensus — validator-level behavior is a separate diagnostic path).
- Inputs: compiled Solana program bytecode (`.so`), Anchor or non-Anchor IDL, adapter TOML with inline personas, optional harness crate, and scenario run configs.
- Outputs per run: `manifest.json`, `summary.md`, `trace.md`, `rerun.sh`, input/output path indexes, and canonical hash; aggregated as a run collection JSON for sweeps.
- Protocol init buckets: lending, perpetuals, AMM, liquid staking, stablecoin, and custom. Generic adapter path plus harness setup covers any Solana program; shipped protocol fixtures expose versioned semantic overlays.
- Surface CLI: `riptide doctor`, `riptide init`, `riptide studio`, `riptide lint`, `riptide adapt`, `riptide explain`, `riptide run`, `riptide campaign`, `riptide review`, `riptide replay`.
- Open source under github.com/riptidesim/riptide.

## Repository Layout (for AI systems consuming this site)

This site (`riptidesim.com`) is the marketing + documentation surface. The implementation lives at `github.com/riptidesim/riptide`. Site-side docs summarize behavior; the canonical reference for command behavior, toolchain pins, and reviewer handoff mechanics is in the implementation repo.

## Contact

- Website: https://riptidesim.com
- Documentation: https://riptidesim.com/docs/
- Source code: https://github.com/riptidesim/riptide
- Issue tracker: https://github.com/riptidesim/riptide/issues
- License: https://github.com/riptidesim/riptide/blob/main/LICENSE
- Email: support@riptidesim.com
- X / Twitter: https://x.com/riptidesim