feat: Add oracle reroute example

[petarvujovic98]

TL;DR

Upgrades simulator-api and simulator-client to v0.17.0 from the git source and rewrites the counterfactual_flow example to use account overrides with a time-shifted schedule instead of a discovery-based program upgrade hook.

What changed?

simulator-api and simulator-client are now pulled from the nitro-stream git repository at a pinned revision rather than from crates.io. The new versions add spl-token-2022-interface, spl-token-interface, thiserror, uuid, solana-account-decoder, and solana-sdk-ids as dependencies, and pull in tonic, axum, hyper-timeout, matchit, pin-project, httpdate, and uuid transitively.

The counterfactual_flow example is substantially reworked:

• The previous approach paused on BPF Loader Upgrade events and injected a replacement transaction. That discovery-based flow, along with discovery.rs, is removed.
• The new approach uses account overrides: the venue's oracle, curve, or fee account is rewritten per slot using real captured states on a shifted schedule. --lag K posts the state from slot s-K at slot s, pricing the cost of staleness, while --lead K posts a future state — with caveats for venues that stamp their own last-update slot into the account.
• Three subcommands replace the single command: capture records the account's per-slot states to JSONL via subscribe_account_diffs, run executes one session with optional overrides, and compare runs an unmodified baseline alongside the modified world and produces a per-leg delta report with median, mean, and p90 bps statistics.
• --filter-mint and --filter-pool flags scope which swaps are requoted. --program-id is now optional and resolves the venue's Metis route label only when provided.
• ManagedBacktestSession replaces the manual BacktestClient session loop. ConnectionArgs centralises URL handling, resolving bare hostnames to wss:// and inferring http/https for the RPC endpoint based on the websocket scheme.
• session_id() call sites in quote_compare and regression_test are updated to use map_or_else since the return type changed.
• Unit tests cover build_shift_actions (positive and negative shifts, empty capture), delta_bps (signed scaling, zero-baseline, sub-bps precision), join_legs (key matching, zero-baseline exclusion), delta_summary (percentile correctness), and ConnectionArgs URL construction.

Documentation in both READMEs is updated to reflect the new methodology, a worked result over a SOL/USDC prop-AMM pool showing a 99.6% fill-rate collapse at four seconds of staleness, and guidance on Metis quoting non-determinism and the minimum replicate count needed to avoid false positives.

How to test?

export SIMULATOR_API_KEY=<key>
POOL=8FnX3xo2yYw3EUE6w3nQA4GfXGS9wpK6oj3veJpbFzLo
PROGRAM=BiSoNHVpsVZW2F7rx2eQ59yQwKxzU5NvBcmKshCSUypi

# Record account states across the slot range.
cargo run --bin counterfactual_flow -- capture \
  --start-slot 433838452 --slot-count 9999 \
  --account $POOL --out capture.jsonl

# Run the unmodified baseline.
cargo run --bin counterfactual_flow -- run \
  --start-slot 433838452 --slot-count 9999 \
  --account $POOL --filter-pool $POOL --program-id $PROGRAM \
  --out baseline.jsonl

# Compare baseline against the venue updating 10 slots slower.
cargo run --bin counterfactual_flow -- compare \
  --start-slot 433838452 --slot-count 9999 \
  --account $POOL --filter-pool $POOL --program-id $PROGRAM \
  --capture capture.jsonl --lag 10 \
  --report compare-report.jsonl

Run the unit tests with cargo test --bin counterfactual_flow.

Why make this change?

The discovery-based approach required a real program upgrade event in the replayed range and only allowed injecting a replacement transaction at that moment, making it impractical for testing arbitrary parameter changes. Account overrides are more general: any account the venue reads — oracle, curve, fee config — can be rewritten per slot using real, well-formed historical states on a shifted schedule. This directly quantifies the value of latency improvements and the cost of staleness without needing to construct synthetic account data or wait for an upgrade event.

[petarvujovic98]

• feat: Add setup transactions example #14
• feat: Add oracle reroute example #12 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[petarvujovic98]

This will have to be updated to the client/api version that gets published after the nitro-stream PRs land