> ## 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.

# Constitution Compiler

> Sudont's Constitution is an AOT-compiled policy object — memory-aligned Rust HashSets that evaluate line-rate with the RPC.

## Overview

The Sudont Constitution is an **AOT-compiled policy object**. Operators author their rules in
JSON or YAML; the compiler lowers every allowlist, denylist, and mathematical bound into
memory-aligned Rust `HashSet` and `BTreeMap` structures. At evaluation time, the Judge dereferences
pre-hashed keys against pre-aligned buckets so policy evaluation stays **line-rate with the RPC**
— indistinguishable from zero alongside the Cage's bare-metal simulation run.

<Note>
  The Constitution is compiled once at policy load, not interpreted per-transaction. Hot-path
  decisions never parse strings, walk trees, or allocate. This is how Sudont meets sub-millisecond
  latency targets while enforcing thousands of rules.
</Note>

***

## Why AOT Compilation

A policy-as-code system that evaluates JSON at runtime loses to garbage collection, cache misses,
and branch mispredictions. Sudont's compiler flattens the entire ruleset into a single contiguous
memory layout:

<CardGroup cols={2}>
  <Card title="Memory-Aligned HashSets" icon="memory">
    Every allowlist entry is pre-hashed into a fixed-capacity Rust `HashSet` with a cache-line
    aligned backing allocation. Lookups hit L1 on the first probe.
  </Card>

  <Card title="Zero Allocation" icon="bolt">
    Evaluation never calls `malloc`. The compiler reserves every buffer during policy load; the
    hot path is pure arithmetic and pointer comparison.
  </Card>

  <Card title="Deterministic Dispatch" icon="scale-balanced">
    Rule lookup is `O(1)` by construction. No tree walks, no regex, no string comparison in the
    Judge.
  </Card>

  <Card title="Line-Rate Evaluation" icon="gauge-high">
    Hash-set membership and integer comparison against pre-aligned buckets. A full Constitution
    evaluation fits well inside the RPC path alongside the Cage's bare-metal simulation run.
  </Card>
</CardGroup>

***

## Policy Fields

Every Constitution exposes the same compiled schema. The `PolicySnapshot` struct in
`sudont-types` captures the compiled form used by the Judge.

| Field                    | Type (compiled)       | Purpose                                     |
| ------------------------ | --------------------- | ------------------------------------------- |
| `chain_allowlist`        | `HashSet<ChainId>`    | Permitted chain IDs                         |
| `protocol_allowlist`     | `HashSet<ProtocolId>` | Permitted protocol identifiers              |
| `target_allowlist`       | `HashSet<Address>`    | Permitted router / contract addresses       |
| `token_allowlist`        | `HashSet<Address>`    | Permitted tokens                            |
| `token_denylist`         | `HashSet<Address>`    | Blocked tokens                              |
| `max_trade_size`         | `U256`                | Absolute size cap in base units             |
| `max_slippage_bps`       | `u32`                 | Slippage tolerance in basis points          |
| `max_price_impact_bps`   | `u32`                 | Price impact cap                            |
| `min_liquidity`          | `U256`                | Minimum pool liquidity threshold            |
| `private_route_required` | `bool`                | Force private mempool egress                |
| `fail_closed`            | `bool`                | Reject any transaction with uncertain state |

***

## Compilation Pipeline

<Steps>
  <Step title="Author Policy" icon="pen">
    Operators write JSON or YAML against the Constitution schema. Source-of-truth is versioned in
    source control, not stored in a database.
  </Step>

  <Step title="Validate and Canonicalise" icon="check">
    The compiler validates every field, resolves aliases, and canonicalises addresses to their
    checksummed form.
  </Step>

  <Step title="Lower to HashSets" icon="cog">
    Allowlists and denylists are lowered into fixed-capacity, memory-aligned `HashSet` structures.
    Numerical bounds are unpacked into native `U256` / `u32` fields.
  </Step>

  <Step title="Freeze Snapshot" icon="snowflake">
    The compiled `PolicySnapshot` is made immutable. A content hash is computed and embedded in
    every `ExecutionAttestation` so downstream systems can verify which policy approved a trade.
  </Step>
</Steps>

***

## Hot-Path Evaluation

At evaluation time the Judge holds a shared reference to the compiled `PolicySnapshot` and
performs only the following operations per transaction:

* Hash-set membership checks against allowlists and denylists — pre-hashed keys landing in
  cache-line-aligned buckets that hit L1 on the first probe.
* Integer comparisons of simulated State-Diff against `max_slippage_bps`, `max_price_impact_bps`,
  and `max_trade_size` — single-cycle each.
* Boolean gates for `private_route_required` and `fail_closed`.

No string parsing, no allocation, no I/O. A full Constitution evaluation fits comfortably
alongside the Cage's bare-metal simulation run — both stay line-rate with the RPC.

<Tip>
  Because the compiled snapshot is content-hashed, the Constitution version that approved any given
  trade is cryptographically anchored in the `ExecutionAttestation`. Auditors can reconstruct the
  exact rule set active at any point in time.
</Tip>

***

<Card title="ReAct Error Payload" icon="code" href="/react-loop">
  See how Constitution violations are serialised into deterministic JSON errors consumed by
  agentic ReAct loops.
</Card>