Guided Sims

When To Use Guided Sims

Use the adapter and harness path when your protocol fits static action dispatch plus deterministic setup before tick 0. Use a guided sim when the flow needs dynamic remaining_accounts, multiple instructions in one transaction, target-vs-agent routing, custom argument assembly, or an external dependency model that must evolve during the run.

Generate The Crate

Generate the crate from an IDL-backed adapter. Generated files can be refreshed later; project-owned flows, invariants, service code, and builder overrides are preserved.

riptide sim generate --adapter .riptide/adapters/<program>.toml
riptide sim refresh --adapter .riptide/adapters/<program>.toml --dir .riptide/sim

Riptide.toml

.riptide/sim/Riptide.toml declares external programs, local account snapshots, fork cache entries, metrics, regression hashing, and the current coverage guard.

[[sim.programs]]
address = "<program-id>"
program = "../target/deploy/dependency.so"
loader = "direct"

[[sim.accounts]]
address = "<account-pubkey>"
filename = "fixtures/accounts/dependency-account.json"

[[sim.fork]]
address = "<mainnet-account-pubkey>"
cluster = "mainnet"
filename = "fork-cache/mainnet/dependency-account.json"
overwrite = false

[sim.metrics]
enabled = true
filename = "artifacts/guided-sim-metrics.json"

[sim.regression]
enabled = true
accounts = ["<account-pubkey>"]
state_hashes = []

[sim.coverage]
enabled = false

Validate the manifest before running. The linter checks pubkeys, local files, base64 snapshots, duplicate addresses, cached snapshot pubkeys, unsupported loaders, and the coverage guard.

riptide sim lint .riptide/sim

Fork Cache

Guided fork support is account-snapshot caching, not a live validator fork. Cache files include address, owner, executable flag, data hash, cluster or RPC URL, fetched slot when available, and the local filename. Keep overwrite = false for stable offline reruns.

riptide sim fork --address <pubkey> --cluster devnet --out .riptide/sim/fork-cache/devnet/<pubkey>.json

Project-Owned Services

External dependency behavior belongs in your sim crate, usually under src/services/. A service can mutate generic accounts through World::mutate_account, warp time, update sysvars, or call into LiteSVM through svm_mut() when needed. Riptide core does not ship Pyth, Switchboard, OpenBook, Drift, Mango, Marinade, Whirlpool, or similar protocol layouts.

impl riptide_sim::Service for OracleService {
    fn tick(&mut self, world: &mut riptide_sim::World) {
        world.mutate_account(&self.price_account, |account| {
            account.data = self.next_price_bytes();
        }).expect("price account exists");
    }
}

Run And Review

Run with an explicit artifact directory. The runner writes guided-sim-run.json and rerun.sh; the review command reads those files without rerunning the simulation.

riptide sim run .riptide/sim --iterations 5 --flows 20 --seed deadbeef --out .riptide/sim/artifacts/run-001
riptide sim review .riptide/sim/artifacts/run-001
riptide review .riptide/sim/artifacts/run-001

Guided review summarizes retained failing seed, flow table, labelled transaction outcomes, failure reason, service ticks, regression hashes, and the rerun command. It is a guided artifact review path, not adapter campaign scheduling.

Current Gaps

• Coverage: guided-run coverage output is not emitted yet. sim.coverage.enabled = true is guarded until a coverage collector exists.
• Campaign scheduling: riptide campaign run remains the adapter/scenario campaign runner. Guided scheduling should be an explicit future command.
• Protocol-specific mocks: external layouts stay in project-owned services, not Riptide core.
• Audit boundary: a green guided sim is simulation evidence for the declared setup, not a safety certification.