> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sudont.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Dual-Engine Physics

> How Sudont uses revm for EVM simulation and LiteSVM for SVM simulation, unified under a single SimulationEngine trait.

## Overview

Sudont's Cage is a **dual-engine physics simulator**. Every transaction is dropped into a local
`revm` (EVM) or `LiteSVM` (SVM) memory sandbox before it hits the chain. Both engines are
first-class citizens.

<Note>
  A single `CanonicalIntent` carries a `vm_type` field that routes it to the correct Cage
  implementation. The architecture is unified at the type level — the Judge and the rest of the
  pipeline are completely VM-agnostic.
</Note>

***

## The SimulationEngine Trait

Defined in `sudont-types`, `SimulationEngine` is the contract both Cage implementations fulfill:

```rust title="SimulationEngine — VM-Agnostic Interface" theme={null}
/// Both EVM and SVM cages implement this trait.
pub trait SimulationEngine: Send + Sync {
    fn simulate(&self, intent: &CanonicalIntent) -> Result<SimOutcome, String>;
}
```

The `CanonicalIntent` input carries the `vm_type` discriminant:

```rust title="VmType Enum" theme={null}
pub enum VmType {
    Evm,
    Svm,
}
```

The RPC layer reads `vm_type` and dispatches to the correct `SimulationEngine` implementation
at runtime — no conditional logic needed in the Judge or policy layers.

***

## VM Implementations

<Tabs>
  <Tab title="EVM — revm (planned)">
    <Warning>
      **EVM engine is on the roadmap — Wave 14+.** The shipped private alpha is
      Solana-only via LiteSVM. The integration points described below (`revm`,
      reth-backed state, Uniswap V3, Aerodrome adapters) are the planned design and
      are **not yet wired into the demo**. Treat this section as forward-looking
      architecture documentation.
    </Warning>

    **Rust crate (planned):** `sudont-cage`
    **Dependency (planned):** `revm = "14.0"`

    The EVM Cage will use [`revm`](https://github.com/bluealloy/revm) — a pure-Rust, production-grade
    Ethereum Virtual Machine implementation.

    <CardGroup cols={2}>
      <Card title="Exact Semantics" icon="check">
        Byte-for-byte compatible with geth/reth execution
      </Card>

      <Card title="Full State Access" icon="database">
        Storage slots, emitted logs, and state diffs
      </Card>

      <Card title="Gas Accounting" icon="gauge-high">
        Precise gas computation and revert reason extraction
      </Card>

      <Card title="EIP Support" icon="file-code">
        EIP-3607 and active EIPs via feature flags
      </Card>
    </CardGroup>

    **State source (planned):** Local Base reth node with Flashblocks support. The simulation will
    reflect the pending world, not a stale cache.

    **Planned protocol adapters:** Uniswap V3 (planned) (`exactInputSingle`, `exactInput`), Aerodrome (planned) router swap flows.

    ```rust title="SimOutcome" theme={null}
    pub struct SimOutcome {
        pub success: bool,
        pub exit_reason: String,       // e.g. "Revert(0x...)" or "Stop"
        pub logs: Vec<SimLog>,         // Transfer events, Swap events
        pub asset_changes: Vec<AssetChange>, // token_in/token_out amounts
        pub state_diff: Vec<StateDiff>,      // storage slot changes
    }
    ```

    <Tip>
      The Judge uses `asset_changes` to compute effective slippage and price impact against the
      `CanonicalIntent`'s `amount_out_min` and `slippage_bps` fields.
    </Tip>
  </Tab>

  <Tab title="SVM — LiteSVM">
    **Rust crate:** `sudont-cage-svm`
    **Dependency:** `litesvm`

    The SVM Cage implements the same `SimulationEngine` trait for Solana transactions:

    ```rust title="SVM SimulationEngine" theme={null}
    pub struct SvmSimulator;

    impl SimulationEngine for SvmSimulator {
        fn simulate(&self, intent: &CanonicalIntent) -> Result<SimOutcome, String> {
            // intent.data holds the serialized Solana transaction bytes
            // The simulator deserializes into VersionedTransaction,
            // executes inside LiteSVM, and returns native logs + state diffs.
        }
    }
    ```

    **`LiteSVM`** is a fast in-process Solana runtime that executes transactions without a validator:

    <CardGroup cols={2}>
      <Card title="State Hydration" icon="download">
        Account state from RPC snapshots
      </Card>

      <Card title="Full Execution" icon="play">
        Instruction-level Solana program execution
      </Card>

      <Card title="Log Capture" icon="file-lines">
        Compute unit accounting and log output
      </Card>

      <Card title="Mainnet Compatible" icon="globe">
        Supports loading real SBF binaries when needed
      </Card>
    </CardGroup>

    <Tip>
      Standard Web3 clients submit native `Transaction` / `VersionedTransaction` payloads through the
      Sudont RPC proxy; the proxy routes the decoded bytes into `sudont-cage-svm` with `vm_type: Svm` —
      no client-side wrapping required.
    </Tip>
  </Tab>
</Tabs>

***

## RPC Routing by VM Type

The Sudont RPC proxy reads the VM discriminant directly from the incoming request and dispatches
to the correct engine:

| Endpoint family              | Engine    | Crate             |
| ---------------------------- | --------- | ----------------- |
| `eth_*`, `sudont_*` (EVM)    | `revm`    | `sudont-cage`     |
| `solana_*`, `sudont_*` (SVM) | `LiteSVM` | `sudont-cage-svm` |

The Judge, Constitution, and diagnostic machinery are shared — only the simulation backend
differs. Point a standard Ethers or Solana Web3 client at the proxy and the correct engine is
selected automatically.

***

## Extending to New VMs

<Steps>
  <Step title="Define VmType Variant" icon="plus">
    Add a new variant to the `VmType` enum in `sudont-types`.
  </Step>

  <Step title="Implement SimulationEngine" icon="code">
    Create a new Cage crate implementing the `SimulationEngine` trait for your VM.
  </Step>

  <Step title="Register in RPC Dispatch" icon="plug">
    Register the implementation in the `sudont-rpc` dispatch table.
  </Step>

  <Step title="Done — No Other Changes" icon="check">
    No changes needed to `sudont-judge`, `sudont-constitution`, or `sudont-cortex`.
    The firewall logic stays stable as new chains are added.
  </Step>
</Steps>