> ## 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. # The Diamond Architecture > How Constitution, Cortex, Cage, and Judge form a bare-metal execution firewall for autonomous agents — organised around three pillars. ## Overview Sudont enforces a four-node decision architecture called **The Diamond**. Every transaction an AI swarm wants to execute must pass through all four nodes before any value moves on-chain. ``` "Intent + Physics + Policy = Verdict" ┌───────────────────────┐ │ THE CONSTITUTION │ ← Layer 1: THE LAW │ user-defined policy │ └───────────┬───────────┘ │ ┌──────────────┴──────────────┐ │ │ ┌──────▼──────┐ ┌──────▼──────┐ │ THE CORTEX │ │ THE CAGE │ ← Layer 2: THE BODY │ intent │ │ physics │ │ extraction │ │ simulation │ └──────┬──────┘ └──────┬──────┘ │ │ └──────────────┬──────────────┘ │ ┌───────────▼───────────┐ │ THE JUDGE │ ← Layer 3: THE VERDICT │ ALLOW · DENY │ │ DIAGNOSE_ONLY │ └───────────────────────┘ ``` The Diamond is a **fan-out / fan-in** shape: it fans out from a single policy source (Constitution) into two parallel verification paths (Cortex and Cage), then converges at a single verdict (Judge). No single node can approve or reject alone. The Judge requires both the Cortex's canonical intent *and* the Cage's bare-metal simulation results to produce any verdict. When a transaction is fatal, the Judge emits a deterministic JSON ReAct error that the swarm consumes directly. See [Agentic ReAct Loop](/architecture/interrogation). *** ## Three Pillars The Diamond is organised around three architectural pillars that together define Sudont's execution physics. No custom SDKs. We are a drop-in RPC proxy. Point your standard Web3 libraries at us, and we handle the rest. We drop every transaction into a local LiteSVM or revm memory sandbox. We simulate the exact mathematical State-Diff of the market before it hits the chain. When a fatal trade is blocked, we don't output human prose. We fire deterministic JSON ReAct errors back to your AI, allowing it to instantly recalculate its route. *** ## The Four Layers > *"The law that governs what is acceptable before a transaction leaves the system."* **Rust crate:** `sudont-constitution` The Constitution is the top of the Diamond. It defines rules that every transaction is evaluated against. Operators author policy in JSON or YAML; the Constitution compiles this into an immutable policy object used throughout the hot path. | Field | Purpose | | ------------------------------------ | --------------------------------------------------------------- | | `chain_allowlist` | Permitted chain IDs | | `protocol_allowlist` | Permitted protocol identifiers (e.g. `uniswap_v3`, `aerodrome`) | | `target_allowlist` | Permitted router/contract addresses | | `token_allowlist` / `token_denylist` | Per-token permissions | | `max_trade_size` | Absolute size cap in base units | | `max_slippage_bps` | Slippage tolerance in basis points | | `max_price_impact_bps` | Price impact cap | | `min_liquidity` | Minimum pool liquidity threshold | | `private_route_required` | Force private mempool egress | | `fail_closed` | Reject any transaction with uncertain state | The `PolicySnapshot` struct in `sudont-types` captures the compiled policy at a point in time. All policy decisions are deterministic and auditable. #### The Constitution Compiler The compiler (`rust/constitution/src/compiler.rs`) transforms operator-facing JSON into an optimised `CompiledPolicy`: * Address lists (`target_allowlist`, `token_allowlist`, etc.) → `HashSet<[u8; 20]>` for O(1) membership checks * Program hashes → `HashSet<[u8; 32]>` for Solana program verification * Numeric thresholds (`max_slippage_bps`, `max_trade_size`, etc.) → direct `U256` comparisons The compiled policy is wrapped in `Arc` for zero-copy sharing across threads. It is loaded once at startup and shared across every Judge evaluation — no runtime modification, no admin override. If `fail_closed` is set, any unknown state or missing data results in a `DENY` verdict. > *"Canonical intent — what transaction did the swarm actually emit?"* **Rust crate:** `sudont-cortex` The Cortex parses raw signed transactions, unsigned tx requests, and typed trade requests, then normalises them into a `CanonicalIntent`. ```rust title="CanonicalIntent" theme={null} pub struct CanonicalIntent { pub vm_type: VmType, // Evm or Svm — routes to the correct Cage pub from: Address, pub to: Option
, pub value: U256, pub data: Bytes, pub nonce: u64, pub gas_limit: u64, // Swap-specific (optional) pub token_in: Option
, pub token_out: Option
, pub amount: Option, pub slippage_bps: Option, } ``` The Cortex is deterministic — no LLM in the hot path. Unknown fields are preserved as explicit nulls; the Cortex never fabricates intent it cannot infer. > *"Bare-metal physics — drop the transaction into a local sandbox and compute the exact State-Diff."* **Rust crates:** `sudont-cage` (revm), `sudont-cage-svm` (LiteSVM) The Cage drops the transaction into a local `revm` or `LiteSVM` memory sandbox and computes the exact mathematical State-Diff of the market against current chain state. Both cages implement the `SimulationEngine` trait: ```rust title="SimulationEngine Trait" theme={null} pub trait SimulationEngine: Send + Sync { fn simulate(&self, intent: &CanonicalIntent) -> Result; } ``` ```rust title="SimOutcome" theme={null} pub struct SimOutcome { pub success: bool, pub exit_reason: String, pub logs: Vec, pub asset_changes: Vec, pub state_diff: Vec, } ``` `UniversalStateDiff` normalises both engines' output into a single type — `BalanceChange` entries, `simulated_price_impact_bps`, `programs_touched`, and `reverted_on_chain` — so the Judge works identically for EVM and SVM. What the Cage produces is **fact, not opinion**: an auditor can verify the Cage's output by replaying the same simulation locally. Execution is deterministic. The Cage cannot make allow/veto decisions and cannot see the agent's intent; it only reports what the physics of the transaction would produce. > *"The verdict engine — does canonical intent match the simulated State-Diff, and does the State-Diff satisfy mathematical bounds?"* **Rust crate:** `sudont-judge` The Judge receives the `CanonicalIntent` from Cortex, the `SimOutcome` from Cage, and the compiled `PolicySnapshot` from Constitution, then produces one of four verdicts: | Verdict | When | Output | | --------------- | --------------------------------------------------------------- | --------------------------------------------------- | | **ALLOW** | Canonical intent matches State-Diff, within Constitution bounds | EIP-191 signed approval artifact | | **DENY** | State-Diff violates bounds, or Constitution hard-violated | Deterministic JSON ReAct error payload | | **INTERROGATE** | Medium-risk signal detected | Deterministic JSON ReAct error — swarm recalculates | | **DIAGNOSE** | Diagnosis-only request (no forwarding) | Full diagnosis envelope; never broadcasts | ```rust title="VerdictDecision Enum" theme={null} pub enum VerdictDecision { Allow, Deny, Interrogate, Diagnose, } ``` **Reason codes** are stable and machine-readable: `SUDONT_SLIPPAGE_EXCEEDED`, `SUDONT_PRICE_IMPACT_EXCEEDED`, `SUDONT_POLICY_DENY`, `SUDONT_UNSUPPORTED_TARGET`, `SUDONT_UNKNOWN_STATE`, `SUDONT_INTENT_OUTCOME_MISMATCH`, `SUDONT_UNAUTHORIZED_RECIPIENT`. #### Decision criteria — Trade pipeline ``` ALLOW if: ├── destination is on allowlist (Constitution) ├── amount ≤ constitutional limit ├── reality.amount_out ≥ intent.min_out ← intent matches physics └── reality.slippage_bps ≤ intent.max_slippage ← physics within tolerance DENY if any of: ├── destination not recognized ├── amount exceeds constitutional limit ├── slippage exceeds intent constraint ← physics diverges from intent └── output below minimum ← agent would receive less than claimed ``` #### Decision criteria — Raw TX pipeline ``` ALLOW if: ├── destination is valid and allowlisted └── amount within constitutional limits INTERROGATE if: └── destination is a contract AND not allowlisted → Cortex interrogation protocol activates DENY if: ├── agent fails interrogation (cannot provide allowlisted destination) ├── invalid destination └── invalid amount ``` #### The signed approval artifact When the Judge issues `ALLOW`, the approval binds the verdict to the exact parameters evaluated: ```json theme={null} { "kind": "sudont_approval_v1", "issued_at": 1739289600, "destination": "0x7a250d...", "amount_eth": 0.25, "intent_min_out": 500.0, "intent_max_slippage_bps": 100, "reality_amount_out": 510.5, "reality_slippage_bps": 42, "pool_id": "0xB4e16d...", "execution_engine": "revm-proxy", "simulation_time": "sub-millisecond local hot path", "gas_used": 152847 } ``` Signed with EIP-191 (`eth_account.sign_message`) using a dedicated policy key. The signature is **non-repudiable** — you cannot fabricate an approval after the fact. *** ## The ReAct Loop When the Judge blocks a fatal trade, the Diamond fires a deterministic JSON error straight back into the swarm's ReAct loop: ``` Judge → JSON ReAct error → Swarm (recalculate_route) → Diamond (re-enter) → Judge ``` Sudont never emits human prose to an agent. Every block ships with a stable `rule_id`, a machine-readable `simulated_reality`, and an `actionable_feedback` token the swarm consumes directly. The agent recalculates; the firewall stays out of its loop. See [Agentic ReAct Loop](/architecture/interrogation) for payload structure, trigger conditions, and integration patterns. *** ## The Event Stream — Observable Diamond Every node in the Diamond emits structured events as it operates. These events form the audit trail. | Event | Emitter | Content | | -------------- | -------------------- | ------------------------------------------------------------------- | | `system_event` | Any Diamond node | Component-level actions (CORTEX, CAGE, JUDGE, CONSTITUTION, SIGNER) | | `log_event` | Cortex pipeline | Structured trace lines for the operator console | | `status_event` | Cortex orchestration | Pipeline state transitions (idle → analyzing → vetoed) | Every event carries: * **`run_id`** — correlates all events for a single request * **`agent`** — which AI agent made the request * **`module`** — which Diamond node acted * **`kind`** — classification (request, interrogation, verdict, approval, headline, blast\_radius) The HUD (`hud/src/App.jsx`) consumes this event stream and renders it in real time. The HUD is **read-only and passive** — it cannot influence the Diamond's decisions. An operator observes but cannot override. *** ## Why This Holds Up Under Audit ### 1. The Diamond is deterministic Every transaction follows the same path through the same four nodes. There are no skip paths, no admin overrides, no manual approvals. The Constitution defines the rules; the Diamond enforces them. ### 2. No single node can decide alone | Diamond node | Can do | Cannot do | | ------------ | --------------------------- | ----------------------------------- | | Constitution | Define rules | Execute transactions | | Cortex | Analyse intent, interrogate | Approve, sign, modify policy | | Cage | Simulate physics | Make judgements, see intent | | Judge | Cross-validate, sign, deny | Modify simulations, override policy | The intent path (Cortex) and the physics path (Cage) are independent. Neither can influence the other. The Judge needs both to converge before it can act. ### 3. Adversarial interrogation record MEDIUM-risk transactions don't get a silent pass/fail. The Cortex interrogates the agent, logging its exact responses. Auditors can independently review what the agent claimed versus what the firewall verified — evidence of agent behaviour under scrutiny, not just outcomes. ### 4. Cryptographic non-repudiation Every `ALLOW` verdict produces an EIP-191 signature binding the policy signer to the exact parameters (amount, destination, slippage, simulation results). An auditor can independently verify any approval artifact against the signer's public address. You cannot forge a historical approval. ### 5. Fail-secure at every node | Failure | Diamond behaviour | | ----------------------------- | -------------------------------------------------------------------------------------------- | | `revm` cache miss | Cage state hydrator fetches missing slots from the configured RPC backend | | Local node out-of-sync | Cage degrades to remote RPC fallback and escalates unknown contracts to Cortex interrogation | | `CompiledPolicy` load failure | Startup fails — never runs without a valid policy (fail-closed) | | Simulation error | Judge returns `DENY` with `SUDONT_INTERNAL_SIMULATION_ERROR` reason code | Every failure mode defaults to the more restrictive path. The Diamond never silently degrades security. ### 6. Policy is versioned and declarative The Constitution is tracked in Git: * **`constitution.json`** — operator-facing policy (readable, diffable) * **`CompiledPolicy`** — in-memory compiled representation (O(1) lookups, `HashSet`-backed) An auditor can diff the JSON to see what the operator changed, verify that the Rust compiler produces the correct `CompiledPolicy` from any given JSON, and read the JSON without understanding the Rust enforcement code. ### 7. Risk classification is deterministic The rules that determine when to interrogate (MEDIUM risk) are compiled math checks in the `CompiledPolicy` — not external rule engines. Adding a new risk heuristic is a policy JSON change compiled at startup. ### 8. Complete event lineage Every step through the Diamond emits a timestamped event with `run_id` correlation. An auditor can reconstruct the full decision path — from intercept through simulation and interrogation to verdict — using the event stream alone, without access to the code. *** ## Project Structure ``` rust/ ├── types/ ← Shared types (CanonicalIntent, SimOutcome, UniversalStateDiff, Verdict, CompiledPolicy) ├── constitution/ ← Policy compiler (RawConstitution JSON → CompiledPolicy with O(1) HashSet lookups) ├── cortex/ ← Deterministic intent parser (raw tx → CanonicalIntent) ├── cage/ ← EVM simulation engine (revm-backed, implements SimulationEngine trait) ├── cage-svm/ ← SVM simulation engine (LiteSVM-backed, implements SimulationEngine trait) ├── judge/ ← Verdict engine (CanonicalIntent × SimOutcome × PolicySnapshot → Verdict) ├── rpc/ ← JSON-RPC reverse proxy (routes by VmType, catch-all passthrough) ├── cli/ ← CLI tooling ├── bench/ ← Benchmarks └── tests/ ← Golden tests and integration tests ``` **Dependency direction:** all crates depend on `sudont-types`. The Judge depends on types only — it is completely VM-agnostic. The RPC layer orchestrates the pipeline.