Skip to main content

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.

Screenshot pending — see make demo-tui for the live experience.

​
Overview

The TUI demo is the canonical way to see Sudont judge real signed transactions against live mainnet state, in-process, with deterministic latency. It runs as two terminals: one hosts the sidecar plus the dashboard, the other drives the agent harness against it. Every verdict in this walkthrough is produced by the same hot path documented in The Diamond Architecture.

​
One-Command Setup

The demo is two make targets, run in two panes: 
# Pane 1 — in-process sidecar with the three-pane TUI dashboard
make demo-tui

# Pane 2 — deterministic agent harness; pick one
make agent-five           # the five-scenario walk-through
make agent-monte-carlo    # the headline route-optimizer scenario
make demo-tui boots a single binary that hosts the sidecar and renders the dashboard. The agent harness in pane 2 issues real signed transactions against 127.0.0.1:8080. Nothing about the layout depends on a network sidecar process — the in-process Cage is what makes the I/O overhead measurable as zero.

​
The Three Panes

The dashboard shows three live regions side-by-side. Together they prove the sidecar is judging real transactions against live state in an environment with no observable I/O hop.

​
[ SOLANA MAINNET · slotSubscribe ] — slot stream

A real slotSubscribe subscription over wss://api.mainnet-beta.solana.com. Each slot tick renders as a jitter sparkline so the room can confirm the sidecar is wired to mainnet, not a fixture file. The pane is read-only telemetry; nothing here gates the verdict.

​
[ PROCESS TELEMETRY ] — host metrics

RSS, mean / p50 / p99 hot-path latency, a rolling latency sparkline, and the I/O overhead 0.00 ms line that proves the in-process Cage adds no socket hop between the agent’s request and the simulator. Hydration surface — protocol allowlists, route venues, working-set size, state freshness, refresh model — is also logged here so the Constitution’s context is visible alongside the latency it operates inside.

​
[ LITESVM HOT-PATH CAGE ] — per-request narration

Per-request narration of the simulate → evaluate → verdict path with µs-resolution phase timing and a pinned banner for the most recent decision. Every [CORTEX], [CAGE], [CONSTITUTION], [JUDGE], and [EGRESS] line emitted by the RPC server lands here in the same order the agent saw them. The phase breakdown sums to the wall-clock total within ±1 µs of clock resolution.

​
The Five-Scenario Run

make agent-five walks the agent through five canonical cases. The expected verdict sequence is ALLOW, INTERROGATE → ALLOW, BLOCK, BLOCK, BLOCK. Scenario 1 — Allow: clean transfer. A small SOL rebalance to an approved vault. The Cortex labels the intent (SOL TRANSFER), the Cage simulates, the Constitution accepts, and Sudont emits an approval attestation. The agent observes Allow and continues. Egress is a noop in terminal-demo mode and a real broadcast when devnet is configured. Scenario 2 — Interrogate then Allow: self-correction. The agent attempts to move slightly more than its delegated authority. Sudont holds the request and returns an actionable challenge; the agent reads the actionable_feedback field, narrows the amount, and resubmits. The corrected request clears the same Constitution and lands as Allow. This is the canonical ReAct loop: the agent is probabilistic, the sidecar is deterministic, and capital only moves after the second pass. Scenario 3 — Block: forbidden program. A signed bundle calls a program outside the Constitution’s allowlist. The Cortex labels it CUSTOM SVM PROGRAM CALL and the Judge denies with SUDONT_UNSUPPORTED_TARGET. The block lands before egress; nothing reaches the network. This is the simple policy-control case. Scenario 4 — Block: Mythos trojan swap. The transaction looks like an ordinary SPL swap. The block does not come from a signature match or a pre-labeled attack heuristic — it comes from the simulated state diff. The Cage runs the transaction against live state and observes value flowing into an attacker PDA that is not in the recipient allowlist. The Judge denies with SUDONT_UNAUTHORIZED_RECIPIENT. This is the technical claim that distinguishes Sudont from a calldata scanner: execution is the only ground truth. The sidecar judges the actual balance movement, not the agent’s stated intent or the bytes of the call. Scenario 5 — Block: shallow-AMM MEV swap. The transaction is syntactically valid and the calldata is unremarkable. The problem is economic physics: the chosen route runs a shallow AMM pool, and the simulated execution price diverges from spot by more than the policy ceiling. The Judge denies with SUDONT_POLICY_DENY. This is the realized-vs-spot check: Sudont is not counting nominal slippage tolerance, it is comparing the actual fill the Cage produced against the public reference price the Constitution declares safe. MEV-style sandwiching, frontrunning, and toxic routing all collapse into the same physical signal — the realized price is wrong — and they are all blocked the same way. For the full reason-code vocabulary and what each one means for the agent’s next action, see the Verdicts & Reason Codes reference.

​
The Headline Scenario: Monte Carlo Route Optimizer

make agent-monte-carlo runs against the same make demo-tui sidecar, but exercises a separate RPC method (sudont_optimizeSwap) on a planning plane that lives off the hot path. The sidecar hydrates the approved AMM venues, walks a candidate trade-size and route-split grid, and returns the largest candidate with positive expected edge, positive downside edge, and policy-safe tail impact. The Cage pane logs the planning header, the hydrated route count and reserve-vault count, the per-route Monte Carlo sample count, and the candidate table — QUALIFY, REJECT:TAIL, REJECT:DOWNSIDE — the planner walked through. The agent then signs only the recommended split and submits it through ordinary sendTransaction. The hot-path Judge re-runs the full simulate → evaluate → verdict pipeline on the signed result, independently of the planner, and the final verdict is Allow. The architectural point: planning runs asynchronously, off the hot path, so its compute budget is unconstrained — but every signed result still passes the same Constitution the five-scenario run used. The planner can be wrong; the Judge cannot be bypassed. For the JSON-RPC surface the harness drives, see the RPC method reference. For the verdict variants every scenario above terminates in, see Verdicts & Reason Codes.