Quickstart

Before You Start

This page assumes Riptide is installed and that you know the core concepts (adapter, scenario, persona, agent, tick, invariant). If either is new, read Install and the overview concepts first.

Initialize Your Repo

Change into your Anchor (or other Solana) program repo and run riptide init. The default command is intentionally thin: it creates the adapter placeholder, .riptide/GETTING-STARTED.md, and run-output ignore rules. It does not choose personas, scenarios, invariants, harness code, seed counts, or agent counts.

cd /path/to/your-anchor-program
riptide init

A thin init output looks like this:

riptide init: scaffolded .riptide/ for ammv2
  created .riptide/adapters/ammv2.toml
  created .riptide/GETTING-STARTED.md
  created .gitignore

Next steps:

  1. Invoke /riptide-config in your coding agent.
     It will finish the adapter, harness, scenarios, campaign readiness, and validation.

  2. Run the campaign it creates:
     riptide campaign run .riptide/campaigns/<risk>.campaign.toml

  3. Review the printed campaign root:
     riptide review <campaign-root>

The default next step is to invoke /riptide-config from your coding agent while standing in the repo. That single skill reads the program source, IDL, tests, and local fixtures; repairs the adapter; adds harness or guided-sim setup where needed; writes starter scenarios and campaign TOML; and records the exact validation commands it ran.

If you prefer a browser control plane for the same local workflow, start Studio after init:

riptide studio --workspace .

Studio can inspect the workspace, run the first-run bootstrap when .riptide/ is missing, open Agent chat for /riptide-config-style setup work, queue allowlisted Riptide jobs, and read reports. It does not replace the file review step.

The advanced questionnaire still exists as riptide init --wizard. Use it only when you explicitly want to replace the thin scaffold with questionnaire-selected starter files.

What init sets

• Program name — auto-detected from Anchor.toml when present. Used as the adapter filename and as the lookup key for riptide lint <program>.
• Adapter protocol hint — optional --protocol or --profile records the closest protocol class while keeping the default adapter on the generic SBF/IDL path for /riptide-config to finish.
• Bootstrap files — a placeholder adapter, getting-started guide, and run-output ignore rules. The untouched adapter is intentionally not lint-clean.
• Advanced starter files — only riptide init --wizard chooses personas, scenarios, invariants, seed counts, and optional harness scaffolding during init.

init writes a .gitignore entry for .riptide/runs/ and .riptide/last-run.json so run output stays out of source control. Adapter, harness, scenario, guided-sim, and campaign files created later are intentionally committed when they define the simulation.

Next Steps

/riptide-config owns the setup loop after init. It should finish with either campaign_ready = yes, bounded_ready = yes, blocked = ..., or an explicit unsupported boundary. The manual sequence below is the same shape it validates.

1. Fill in the TODO blocks in your adapter

Open .riptide/adapters/<program>.toml. The stub is intentionally not lint-clean — every block carries a TODO comment naming what belongs there. These blocks usually need real input on every adapter:

• [accounts] — declare every account the engine should track. Use kind = "agent" for per-user accounts (wallet, position, token account) and kind = "shared" for global pool / config accounts. space must match the account data size. Add decoder = "spl_token_account", decoder = "spl_mint", or a raw layout decoder when you need to observe external account bytes.
• [instructions] — verify the LHS names (deposit, borrow, …) match the actual instruction names in your IDL, and that arg mappings like amount = "amount" reference the IDL arg names exactly.
• [state_mapping] — the LHS dotted paths (pool.total_deposits, position.collateral, vault_src.amount) must match IDL account fields or declared decoder fields. The RHS keys (tvl, debt, pool.reserve_src) are what observations and invariants reference.
• [personas.*] — once your real action names are confirmed, prune any action_weights keys that don't exist as [actions.*] on the adapter.
• [[invariants]] — keep template invariants commented or tune them to real observation keys and bounds before relying on them.

Adapter mental model and every TOML block in depth: Adapter.

2. Build the program

The adapter points at the compiled .so and the JSON IDL. Build them with whatever toolchain your repo uses:

anchor build

Or cargo build-sbf plus your IDL generator. Confirm target/deploy/<program>.so and target/idl/<program>.json are present at the paths named in the adapter.

3. Lint the adapter

Static check against the JSON IDL named in [lineage].idl_source. No build, no network, no simulation:

riptide lint <program>

Fix anything it reports before moving on.

4. Fill the harness when setup is needed

If /riptide-config creates .riptide/harness/, inspect .riptide/harness/src/main.rs before running the simulation. Use it to create SPL mints and vaults, PDAs, external account bytes, sibling programs, and any setup the adapter cannot express by itself. Then build it:

cargo build --release --quiet --manifest-path .riptide/harness/Cargo.toml

If you selected adapter-only but later discover that zeroed accounts are not enough, generate the crate at any time:

riptide harness generate --adapter .riptide/adapters/<program>.toml

Harness setup in depth: Harness.

5. Smoke one seed

Keep the first run bounded. When setup needs a harness, smoke the real run path with one seed:

riptide run --adapter .riptide/adapters/<program>.toml --harness .riptide/harness --seeds 1 --seed-root 1337

For adapter-only programs, riptide adapt is still a fast end-to-end check: it loads the TOML, validates schema and IDL bindings, fires a single write action, and checks observable state movement.

riptide adapt --adapter .riptide/adapters/<program>.toml

6. Configure the baseline scenario

Open the baseline or smoke scenario that /riptide-config created. Confirm the personas array lists the slugs you want active for that run. Adjust agents, ticks, and seeds for the first bounded smoke. A run config with "seed" runs one deterministic cell; a config with "seeds" runs a sweep. The CLI flags --seeds and --seed-root override those values without editing the file.

Scenario fields, sweeps, and the replay surface in depth: Scenarios.

7. Run your first simulation

riptide run --adapter .riptide/adapters/<program>.toml --harness .riptide/harness --serve

The run prints a verdict / confidence / coverage summary, writes .riptide/run-collection.json, and emits an evidence pack under .riptide/pack/<run-id>/.

The --serve flag

--serve is optional. When present, after the simulation finishes Riptide boots a local read-only dashboard at http://localhost:4173 that reads the run collection and lets you browse per-scenario metrics, the event trace, invariant rows, and coverage checks. The dashboard is the same surface used to review sweeps before drilling into one scenario, so it is the recommended way to inspect a multi-scenario run interactively.

Drop --serve in CI or any non-interactive context — the verdict, run collection, and evidence pack are written either way, and reviewers can still rerun the pack from rerun.sh without opening the dashboard.

Studio

riptide studio is the broader local UI. Use it when you want to browse workspaces, inspect adapters and campaigns, queue jobs, read reports, open dashboard drilldowns, or send setup tasks to a local coding agent from Agent chat.

riptide studio --workspace . --no-open

Studio binds to loopback by default and rejects non-loopback hosts. See Studio for flags, job kinds, Agent chat, and the trust boundary.

8. Iterate

Read the report the run drops. Then iterate:

• Add new scenarios under .riptide/scenarios/<name>/run-config.json.
• Tune persona weights, triggers, and persona_args in the adapter's inline [personas.*] blocks.
• Add [[invariants]] entries to the adapter as you formalize what "broken" means for your protocol.
• Extend the harness when new accounts, vaults, or external programs enter the run.

Evidence pack contents, manifest format, and the canonical-hash discipline: Replay artifacts.

Agent Skills

Two project-local skills ship with Riptide. They run in your local agent session and edit normal files. There is no endpoint config or API key.

• riptide-config — the default post-init path. It generates or repairs the adapter, harness, scenarios, invariants, guided-sim setup when needed, campaign readiness, validation, and final readiness verdict.
• riptide-narrative — synthesizes a case-study-voice narrative report from a finished run's simulation-result.json + report.md. Cites specific ticks, events, and invariant firings; writes report-narrative.md alongside the existing report.

Invoke them from a Claude Code session standing in the repo (the skill descriptions list the exact triggers each one responds to).

Health Checks

riptide doctor is a static health check — no build, no network, no simulation. It checks the local toolchain, resolves the engine binary, walks discovered adapters, and prints a pass / warn / fail table. Safe to run at any point in the loop.

riptide doctor

init also writes .riptide/GETTING-STARTED.md with the same arc as this page in prose form, scoped to the detected program name and the thin bootstrap files it created.