Architecture

Architecture overview

Instead of forking at a block hash (which Solana has no equivalent of), RustAG fetches mainnet accounts lazily on first access and tracks every local write so it knows what it may and may not refresh. A Solana client talks to a stagenet as if it were a cluster.

Request & data flow

  Solana client / wallet / Anchor / dashboard          │  JSON-RPC      WebSocket      REST          ▼                               ▼┌───────────────────────────────────────────────────────┐│ rustag-rpc  (axum)                                     ││   • JSON-RPC server   POST  /            (jsonrpc.rs)  ││   • WebSocket server  GET   /  accountSubscribe (ws.rs)││   • REST API          /api/*             (rest.rs)     ││     mounts one rustag_core::Stagenet behind RwLock     │└───────────────────────────────────────────────────────┘          │ send_transaction / get_account_info / airdrop          ▼┌───────────────────────────────────────────────────────┐│ rustag-core  (the engine)                              ││   • LiteSVM instance (execution)                       ││   • account-state machine: Unknown→Clean→Dirty/Pinned  ││   • lazy-mirror logic (pre_load_accounts_for_tx)       ││   • SQLite persistence via sqlx → survives restarts    ││   • background workers: oracle sync, metrics, realtime │└───────────────────────────────────────────────────────┘          │ getMultipleAccounts (cache miss / oracle refresh)          ▼┌───────────────────────────────────────────────────────┐│ rustag-mirror  (read-side, dependency-light)           ││   • raw JSON-RPC over reqwest (no solana-rpc-client)   ││   • MainnetMirror::fetch_multiple (≤100 keys/call)     ││   • known-program / oracle registry + RpcRateLimiter   ││   • RealtimeMirror push: accountSubscribe WS → mpsc    │└───────────────────────────────────────────────────────┘          │ HTTPS / WSS          ▼             Mainnet RPC (Helius / Triton / …)

rustag-mirror is a pure read-side that knows nothing about dirty/clean tracking — it just answers “give me the current mainnet state of these pubkeys.” All the policy (state machine, persistence, sync invariants) lives in rustag-core, and all the protocol surface lives in rustag-rpc.

What happens on a transaction

Stagenet::send_transaction runs four stages:

1. Pre-load — extract the transaction's static account keys and batch-fetch any that are not already loaded and not Dirty from mainnet via the mirror, loading them into LiteSVM as Clean (fetch failures are logged and tolerated).
2. Execute through LiteSVM with signature and blockhash checks on.
3. Track writes — derive writable accounts from the message header layout, mark them Dirty, and persist their post-state.
4. Index the transaction (signature, success, fee, compute units, programs, logs) for the dashboard and rustag logs.

For VersionedMessage::V0 transactions, prepare_accounts resolves address_table_lookups through the mirror before execution, so v0 DeFi transactions read real mainnet state instead of failing with LookupTableAccountNotFound.

Crate map

RustAG is a Cargo workspace under crates/. The dependency direction is rustag-cli → rustag-rpc → rustag-core → rustag-mirror; rustag-core re-exports the mirror surface so downstream crates have a single dependency. Every Phase 2/3 crate is pure Rust with no external service dependency.

Phase 2 & 3

Everything beyond Phase 1 is built on a single invariant: a Dirty or Pinned account is never overwritten by any sync — re-enforced on every new path, including the realtime push path.

Phase 2 features Phase 2 · Preview

• Real-time mirror (push) — a server-side accountSubscribe WebSocket (the Geyser/Yellowstone protocol) updates oracle prices sub-second, behind the realtime feature. A native Yellowstone gRPC source is a drop-in producer for the same mpsc channel.
• Activity Scheduler — recurring on-chain actions on @every / aliases / 5-field cron (Vixie semantics, no external cron crate); actions are airdrop, signed transfer, or raw-tx replay.
• Simulation framework — fork / replay / stress / compare against an isolated in-memory copy; the base is never mutated and mainnet is never touched. Reachable via POST /api/simulate and client.simulate([...]).
• Analytics — a background sampler captures TVL, transaction volume, accounts mirrored, dirty count, and slot as a queryable time-series.
• Cloud control plane (rustag-cloud) — multi-tenant orchestration; each stagenet is an isolated child process behind a reverse proxy with Bearer rk_… API-key auth and enforced cross-tenant isolation.
• GitHub Action & Anchor plugin — an ephemeral per-PR stagenet, and @rustag/anchor-plugin's rustagAnchorProvider({ preload }) / EphemeralStagenet.

let mut fork = base.fork("herd").await?;let report = rustag_sim::stress(&mut fork, "liquidations", 1_000, |i| build_tx(i)).await?;println!("success rate: {:.1}%", report.success_rate() * 100.0);

Phase 3 features Phase 3 · Experimental

Phase 3 is about trust and depth — making the output of staging something an auditor, grant committee, or CI gate can cryptographically rely on. Every artifact is byte-for-byte reproducible from public inputs.

• Verifiable attestation (rustag-attest) — a SHA-256 Merkle state_root over the pubkey-sorted account set, an Ed25519-signed manifest, and an offline rustag verify; plus a tamper-evident, hash-chained AuditLog.
• Time-travel & replay (rustag-replay) — content-addressed Checkpoints, deterministic Journal replay (verify_deterministic), Timeline diffs, and fork-of-fork Lineage with full ancestry.
• Adversarial simulation (rustag-sim) — atomic Jito-style bundles with tip accounting, deterministic invariant fuzzing (capturing the reproducing seed), a reproducible exploit-signature scanner, and a differential-execution harness.
• State / ZK compression testing (rustag-compression) — a keccak-256 ConcurrentMerkleTree matching spl-account-compression so compressed-state programs and their proofs verify deterministically off-chain.

use rustag_compression::{ConcurrentMerkleTree, keccak256, verify_path}; let mut tree = ConcurrentMerkleTree::new(14, 64).unwrap();let root = tree.append(keccak256(b"first compressed leaf")).unwrap(); let proof = tree.prove(0).unwrap();assert!(verify_path(&root, &proof.leaf, proof.leaf_index, &proof.siblings));