SOVR Protocol Specification

Stage 0 — Protocol Specification Status: Draft for review · Date: 2026-10-05 · Domain: sovr.pro

Every token is its own bank.

SOVR provides autonomous monetary systems for onchain assets. A SOVR-enabled token is given its own reserve, a transparent balance sheet, an economic constitution, a monetary mandate, an AI policy governor, policy regimes, a policy history, a constrained set of actions, and a public ledger of everything the system has done.

The governing design rule of the protocol is:

The AI does not control the money. The constitution controls the AI.

0. Document conventions

0.1 Normative language

The words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are used as in RFC 2119.

0.2 Source of truth

This specification is written against the reference implementation in this repository. Where the specification and the code disagree, the disagreement is a defect and MUST be resolved explicitly; neither silently wins.

Items marked [Specified, not implemented] describe interfaces or components that are normative for later stages but do not yet exist in code.

0.3 Units

1. What SOVR is, and what it is not

1.1 The metaphor

"Bank" is a product metaphor. A SOVR instance is closer to a central bank, treasury, reserve manager and monetary-policy engine for assets owned by a token project than to a commercial bank.

A SOVR instance:

• holds a reserve of project-owned assets;
• allocates incoming project revenue across a fixed set of uses;
• executes a small set of bounded monetary operations (scheduled buybacks, protocol-owned liquidity, reserve rebalancing);
• publishes a balance sheet, its policy decisions, and the reasoning record behind them.

1.2 What SOVR V1 is not

SOVR V1 is not a deposit-taking bank and MUST NOT be described as one. In V1 there are:

All public copy MUST follow this rule: SOVR manages project-owned assets under a published constitution. It does not take custody of user funds, does not promise any price, and does not insure anything.

2. The six primitives

The relationship is strictly one-directional: the Governor proposes, the Constitution judges (through the Executor), the Executor acts on the Reserve, and the Ledger records. Nothing flows from the Governor to the Reserve except through the Executor.

 market / chain / oracle state (structured only)
                 │
                 ▼
          ┌─────────────┐   PolicyIntent (untrusted JSON)   ┌───────────────────────┐
          │  GOVERNOR   │ ────────────────────────────────▶ │ EXECUTOR              │
          │ (AI layers) │                                   │  parseIntent (schema) │
          └─────────────┘                                   │  validateIntent       │
                 ▲                                          │  timelock             │
                 │ measured outcomes                        │  verifyExecution      │
                 │                                          └──────────┬────────────┘
          ┌─────────────┐                                              │ only allowlisted
          │   LEDGER    │ ◀──────── receipts, verdicts ────────────────┤ action types
          │ append-only │                                              ▼
          └─────────────┘                                   ┌───────────────────────┐
                                                            │ RESERVE (PDA vault)   │
          CONSTITUTION ── bounds every check ─────────────▶ │ USDC · SOL · governed │
                                                            └───────────────────────┘

3. The SovrInstance object

A SOVR instance is the unit of deployment: one governed token, one constitution, one reserve, one governor, one ledger. [Specified, not implemented] — the interface below is normative for Stage 3; the constituent types (Constitution, Mandate, Regime, Allocation) already exist in types.ts.

interface SovrInstance {
  id: string;                         // e.g. "sovr:sol:xyz" — equals constitution.instanceId
  chain: "solana" | "evm";            // V1: "solana" only
  governedToken: { symbol: string; name: string; address: string; decimals: number };
  constitution: { id: string; version: number; hash: Hex };   // hash = constitutionHash(c)
  reserveVault: string;               // address of the PDA-owned vault
  policyGovernor: {
    proposerAddress: string;          // key that may ONLY submit intents (see §13.3)
    modelVersion: string;             // e.g. "sovr-governor/0.4.2"
    status: "ONLINE" | "DEGRADED" | "OFFLINE";
  };
  policyExecutor: string;             // program / account that validates and executes
  oracleConfiguration: { sources: string[]; maxAgeSeconds: number; maxDeviationBps: Bps };
  mandate: Mandate;                   // weights sum to 10_000; priceTargeting: false
  currentRegime: Regime;
  currentParameters: {
    allocation: Allocation;           // current revenue split, sums to 10_000
    lastExecutedAt: UnixSeconds | null;
    policyWindow: number;             // current window index
  };
  policyHistory: string;              // address of the append-only PolicyLedger
  emergencyControls: {
    paused: boolean;
    pauseAuthority: string;
    resumeRequestedAt: UnixSeconds | null;
    resumeDelaySeconds: number;
  };
  metadata: { createdAt: UnixSeconds; template: ConstitutionTemplate; uri?: string };
}

id MUST equal constitution.instanceId. Every intent carries an instance field; an intent whose instance differs from the constitution's instanceId is rejected with INSTANCE_MISMATCH (check INSTANCE).

4. Constitution

4.1 Structure

The constitution is the full Constitution type in types.ts. Its fields fall into three classes.

Every amended constitution MUST itself pass validateConstitution. Amendment cannot be used to escape protocol limits.

4.2 Hard prohibitions

HardProhibitions fields are typed as literal false. A constitution in which any is not false does not type-check and is rejected at runtime.

Additionally: emergency.pauseCanMoveFunds: false and mandate.priceTargeting: false are enforced.

4.3 Protocol limits

PROTOCOL_LIMITS in engine.ts are ceilings and floors that apply to every constitution. They protect against a creator constructing a malicious or reckless constitution. validateConstitution enforces them; a constitution that fails cannot be deployed.

4.4 validateConstitution — full rule set

A constitution is valid iff it produces no issues under all of the following:

1. Every prohibitions.* is false.
2. emergency.pauseCanMoveFunds === false.
3. mandate.priceTargeting === false.
4. Mandate weights over the five objectives sum to exactly 10_000.
5. Every permittedActions entry is in ACTION_TYPES.
6. Each allocationBounds[bucket] exists with 0 ≤ min ≤ max ≤ 10_000.
7. Allocation feasibility: Σ min ≤ 10_000 ≤ Σ max.
8. 0 < maxStepBps ≤ 2_500.
9. policyWindowSeconds ≥ 21_600.
10. minExecutionDelaySeconds ≥ 3_600.
11. perPolicyMaxOutflowBps ≤ 500.
12. rollingOutflow.maxBpsOfReserve ≤ 1_500.
13. rollingOutflow.windowSeconds ≥ 604_800.
14. perPolicyMaxOutflowBps ≤ rollingOutflow.maxBpsOfReserve.
15. maxSlippageBps ≤ 300.
16. oracle.maxAgeSeconds ≤ 600.
17. oracle.sources.length ≥ 2 (at least two independent sources).
18. buyback.maxParticipationBps ≤ 1_500.
19. No asset is listed twice in reserveAssets.
20. The governed asset's target.max ≤ 5_000.
21. Reserve feasibility: Σ target.min ≤ 10_000 ≤ Σ target.max.
22. At least one reserve asset (the governed token) is declared with governed: true; it may have a 0% maximum, but it must be declared.
23. Every venues[].maxExposureBps ≤ 5_000.
24. amendment.timelockSeconds ≥ 604_800.
25. amendment.authority does not name the governor (reference check: /governor/i).
26. No amendment.amendableFields entry equals, or is a sub-path of, an unamendable entry.
27. emergency.resumeDelaySeconds ≥ 3_600.

4.5 Policy versus constitutional amendment

These are two different processes with different actors, and the protocol MUST keep them distinct in data model, UI and copy.

Amendment flow:

PROPOSAL ─▶ PUBLIC NOTICE ─▶ TIMELOCK ─▶ GOVERNANCE APPROVAL ─▶ EXECUTION
 (authority)  (noticeSeconds)  (timelockSeconds)  (authority vote)   (new version,
                                                                      validateConstitution
                                                                      must pass)

Because the policy hash commits to the constitution hash (§11.3), any policy approved under constitution version n fails verifyExecution once version n+1 is active. Amendments therefore implicitly cancel in-flight policies; the governor must re-propose under the new law.

4.6 Reference constitution XYZ-001

XYZ-001 (template BALANCED, instance sovr:sol:xyz, governed token XYZ, 6 decimals) is the conformance fixture. Its values are reproduced in the BALANCED column of §17.

5. Reserve and balance sheet

5.1 Reserve assets (V1)

V1 reserves hold exactly three asset classes: SOL, USDC, and the governed token. Each is declared in reserveAssets with a target range (share of total reserve value). The governed token MUST be declared with governed: true; its maximum share MUST NOT exceed 50%.

XYZ-001 targets: USDC 40–70%, SOL 15–45%, XYZ 0–25%.

5.2 Balance sheet

The balance sheet is published for every instance and recomputed every policy window.

Assets

Liabilities

Liabilities MUST include only real, contractual, enforceable obligations of the instance: for example, a committed and unpaid operations disbursement already approved by policy, or a contractual vendor obligation registered by the project's governance. The protocol MUST NOT manufacture liabilities.

In particular:

• Market capitalisation is not a liability. Token holders have no claim on the reserve.
• Circulating supply is not a liability.
• Future buyback budgets are not liabilities; they are allocations that can be changed by policy.

In V1, with no deposits and no borrowing, liabilities are expected to be zero or small. The balance sheet MUST show the line even when zero.

Net reserve

The term used is net reserve, never "equity", "capital" or "backing".

5.3 Ratios — explicit definitions

Every ratio is published with its numerator, denominator and observation window. No ratio may be displayed without those three disclosures one click away.

30D inflows = revenue received by the instance in the trailing 30 days (fees and other project revenue routed to the instance), before allocation.

30D outflows = buyback spend + POL additions + operations disbursements, all in the trailing 30 days.

Rebalances are internal. A REBALANCE_RESERVE moves value between reserve assets and is not an outflow; only its execution cost (realised slippage + fees) is recorded, as a separate "execution cost" line.

Two notions of outflow. Accounting outflows (above) differ from the engine's cap-relevant outflow:

5.4 Governed-token holdings

Governed-token holdings in the reserve are reflexive: their value falls exactly when the reserve is most needed, and buybacks convert stable assets into governed tokens. The protocol therefore:

1. Reports governed-token holdings on a separate line, never merged into a headline "reserve" number without disclosure.
2. Publishes a haircut value. Default haircut: 50%, adjustable by the creator at genesis, never below 25%. [Specified, not implemented]
3. Excludes governed tokens from runway and liquid reserve coverage numerators.

See §26 for the open question of whether caps should use haircut values.

5.5 Worked example (fixture state)

From baseContext() in fixtures.ts:

Derived engine limits at this state:

6. Mandate

The mandate is a set of weighted, measurable objectives. Weights are in bps and MUST sum to 10_000.

XYZ-001 weights: liquidity 30%, reserve 30%, revenue 20%, market stability 10%, capital efficiency 10%.

Price targeting is excluded. priceTargeting is typed literal false and is enforced by validateConstitution. No objective may be expressed as a price level or price floor. The governor MUST NOT state or imply that any action supports, defends or targets a price.

7. Governor

7.1 Principle

The governor is an advisory, proposal-generating pipeline. Its output is a PolicyIntent, which is untrusted input. The governor:

• holds no signing key with authority over funds;
• cannot call any program other than submitting an intent (§13.3);
• cannot express an action outside the five-action vocabulary;
• cannot amend the constitution, its own authority, or the pause.

7.2 Layers

Rules:

1. No model is both proposer and judge. The Planner and Critic MUST be separate invocations with separate prompts; SHOULD be separate model families or versions. Neither can override layer 6.
2. Layers 6 and 7 contain no natural-language interpretation. engine.ts is pure, total, fail-closed, and performs no I/O.
3. The Critic can only withdraw or ask for revision; it cannot approve. Only layer 6 approves.

7.3 Structured rationale (no chain-of-thought)

The governor MUST NOT publish raw chain-of-thought. It publishes a structured rationale attached to (but not part of) the executable intent:

Language MUST be institutional: "the governor proposes", "the policy allocates", "the constitution rejected". The governor MUST NOT be anthropomorphised ("the AI feels", "the AI wants", "the AI is confident the price will…"). confidence in the intent is informational only and is never an authorisation input.

The rationale is not part of the executable schema. The schema has no free-text field; natural language cannot reach the executor.

8. Policy windows

A policy window is the cadence at which the governor may propose and at most one mutating policy may execute. The minimum spacing between executions is policyWindowSeconds (≥ 6 h; XYZ-001: 72 h).

Steps 3 and 4 iterate: the Planner may revise after simulation and critique. Step 5 is the only gate.

A rejected policy is still published (step 6) with its rejection codes. Rejections are part of the public record.

9. Policy vocabulary

9.1 Permitted actions (complete V1 set)

A constitution may permit a subset via permittedActions.

9.2 Prohibited actions

The engine recognises these names only in order to reject them with PROHIBITED_ACTION. They have no executor implementation anywhere.

AMEND_CONSTITUTION, TRANSFER, WITHDRAW_RESERVE, MINT, BURN_FROM, BORROW, LEVERAGE, SET_AUTHORITY, UPGRADE_PROGRAM, ARBITRARY_CALL, DISABLE_PAUSE, DEPOSIT_YIELD.

Any other unrecognised type is rejected with UNKNOWN_ACTION.

9.3 Buybacks

Buybacks are bounded, scheduled operations. They are not price support.

Disclosure rule: buyback receipts and UI MUST NOT say or imply that a buyback "supports", "defends", "floors" or "stabilises" the price. Accepted wording: "the instance purchased N tokens for $X across T tranches".

Bought tokens are retained in the reserve in V1 (no burn: BURN_FROM is prohibited; a self-burn of reserve-held tokens is a possible future amendment-gated feature, see §26).

9.4 Protocol-owned liquidity

V1 POL is deliberately simple:

• add liquidity on an allowlisted venue, in an allowlisted pair, bounded by slippage, venue exposure (VENUE_EXPOSURE), and outflow caps;
• the engine projects POL as taking amount_usd / 2 from each pair asset in the reserve; a shortfall in either is INSUFFICIENT_RESERVE;
• pair assets must differ.

There is no autonomous range management, rebalancing of LP ranges, or inventory-skewing. Autonomous market making is a separate future product with its own constitution class and is out of scope for V1.

V1 has no "remove liquidity" action. Removing POL is a constitutional-amendment-gated operation in V1 (see §26).

9.5 Reserve rebalances

• Only between allowlisted reserve assets; from_asset ≠ to_asset.
• Post-execution composition MUST be inside each asset's target range, or, if an asset is already outside its range, the action MUST move it strictly toward the range (RESERVE_COMPOSITION).
• The engine projects the received amount at worst-case slippage: amount_usd × (1 − max_slippage_bps / 10_000).
• No discovery of yield protocols, lending markets, or new assets. Adding an asset is a constitutional amendment.

10. Policy simulator

The simulator produces ranges under stated assumptions, not predictions. Every mutating policy MUST carry a simulationHash; a mutating intent with simulationHash: null, or submitted while the simulator is not ONLINE, results in NO_ACTION / SIMULATOR_UNAVAILABLE. NO_CHANGE does not require simulation.

10.1 Scenarios

Each candidate policy is simulated against the current state under all of:

10.2 Outputs

Per scenario, the simulator reports P10 / P50 / P90 for: net reserve, net reserve (ex-governed), runway, stable share, POL depth ratio, realised execution cost, and remaining rolling-outflow headroom. It also reports whether any constitutional bound would be breached on the following window under that scenario.

10.3 Hash

simulationHash = sha256(canonicalJson({ inputs, assumptions, seed, simulatorVersion, outputs })). The full simulation artefact is published alongside the receipt so the hash is independently verifiable.

10.4 Language

Simulation results MUST be described as "under scenario X, the range is …". They MUST NOT be described as forecasts, expectations or targets.

11. Intent format, schema and hashing

11.1 Envelope (strict)

All objects are strict: unknown keys are rejected (MALFORMED_INTENT). All numbers are bounded. bps fields are integers 0–10_000; amount_usd is finite, 0 – 1e12. Strings where numbers are expected, fractional bps, and non-JSON text are all MALFORMED_INTENT.

11.2 Example intent (JSON)

The following is the fixture baseIntent(). Against XYZ-001 and baseContext() it returns PASS with next allocation 35 / 30 / 20 / 15. (Hash values in this example are fixture placeholders: evidenceHash is "a"×64, simulationHash is "b"×64.)

{
  "instance": "sovr:sol:xyz",
  "window": 21,
  "regime": "ACCUMULATION",
  "proposedAt": 1791208800,
  "effectiveTime": 1791216000,
  "actions": [
    {
      "type": "SET_REVENUE_ALLOCATION",
      "parameters": {
        "reserve_bps": 3500,
        "liquidity_bps": 3000,
        "buyback_bps": 2000,
        "operations_bps": 1500
      }
    }
  ],
  "confidence": 0.78,
  "modelVersion": "sovr-governor/0.4.2",
  "evidenceHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "simulationHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
}

A scheduled buyback intent (passes in the conformance suite, regime BUYBACK):

{
  "instance": "sovr:sol:xyz",
  "window": 21,
  "regime": "BUYBACK",
  "proposedAt": 1791208800,
  "effectiveTime": 1791216000,
  "actions": [
    {
      "type": "EXECUTE_SCHEDULED_BUYBACK",
      "parameters": {
        "amount_usd": 60000,
        "pay_asset": "USDC",
        "venue": "orca-whirlpool",
        "max_slippage_bps": 75,
        "tranches": 24,
        "duration_seconds": 86400
      }
    }
  ],
  "confidence": 0.78,
  "modelVersion": "sovr-governor/0.4.2",
  "evidenceHash": "ee8250fb76e094b34b471f13a73dbbe51d1ae142e9df59d7c0d31ec20f0a0a8e",
  "simulationHash": "32e4bc02a7ccf34d72692db7f08aa945102e290beb4832d5673b987015d8cb4f"
}

$60,000 is below the per-policy cap ($120,532), the participation cap ($124,000) and the rolling cap ($289,277); 24 tranches over 24 h meets the 12-tranche / 24 h minimum; 0.75% slippage is within the 1% bound.

11.3 Hashing

The policy hash binds an intent to the exact constitution version it was validated against. Hashes are independent of key order and identical across services and languages that implement the same canonicalisation.

12. Constitution engine — normative behaviour

12.1 Properties

The engine (engine.ts) MUST be:

• Pure — no I/O, clock reads, or randomness; ctx.now is the only clock.
• Total — never throws on any input; malformed input is a REJECT.
• AI-free — interprets no natural language.
• Fail-closed — missing data is REJECT or NO_ACTION, never PASS.
• Exhaustive — once past schema and dependency gates, every check runs and every failing invariant is reported, not only the first.

The onchain PolicyExecutor MUST implement the same checks with the same semantics. The TypeScript engine is the reference used for governor pre-flight, simulation, the UI, and conformance testing.

12.2 Verdicts

12.3 Evaluation order (validateIntent)

Then policyHash is computed. Any rejection → REJECT; otherwise PASS.

Report order. Checks are reported in CHECK_IDS order (SCHEMA, INSTANCE, DEPENDENCIES, PAUSE, ACTION_PERMITTED, ALLOCATION_BOUNDS, ALLOCATION_VELOCITY, POLICY_FREQUENCY, ASSET_ALLOWLIST, VENUE_ALLOWLIST, VENUE_EXPOSURE, SLIPPAGE, BUYBACK_LIMITS, PER_POLICY_OUTFLOW, ROLLING_OUTFLOW, RESERVE_COMPOSITION, ORACLE_FRESHNESS, TIMELOCK), which differs from evaluation order only in that DEPENDENCIES is evaluated first. A FAIL on a check is sticky and is never overwritten by PASS or SKIP. A check with nothing to evaluate is SKIP.

"Mutating" means the intent contains any action other than NO_CHANGE. "Value-moving" means EXECUTE_SCHEDULED_BUYBACK, ADD_PROTOCOL_OWNED_LIQUIDITY, or REBALANCE_RESERVE; asset, venue, slippage, composition and oracle checks apply only to value-moving actions.

12.4 Rejection codes (complete)

12.5 verifyExecution

At execution time the executor MUST, in order:

1. Parse the execution payload with the strict schema (schema rejections returned as-is).
2. Recompute policyHash(c, payload) against the currently active constitution; if it differs from the approved hash → EXECUTION_HASH_MISMATCH.
3. Require ctx.now ≥ effectiveTime → otherwise EXECUTION_TOO_EARLY.
4. Re-run validateIntent against current state. Cooldown is still measured from the previous execution. If the state has changed such that the policy is no longer valid (pause, oracle staleness, exhausted rolling cap, composition), execution is refused with the resulting codes. A NO_ACTION at this stage is surfaced as MALFORMED_INTENT with the NO_ACTION detail.

Only on ok: true is a transaction built.

13. Executor and authority model

13.1 Who holds what

13.2 Execution scope

The executor composes only: SPL token transfers between the reserve vault and allowlisted venue programs, swap instructions on allowlisted venues with a minimum-out derived from max_slippage_bps and the oracle price, and liquidity-add instructions on allowlisted pools. The venue program IDs are fixed per VenueRule. There is no generic CPI.

13.3 Proposer key

The proposer key can call exactly one instruction: submit_policy(intent). Compromise of this key yields the ability to submit intents — which remain subject to every check, the timelock, and public visibility. It is equivalent to a compromised governor, which the protocol already treats as adversarial.

14. Regimes

The governor classifies the economy into one of seven regimes each window. The regime is a label on the intent; it confers no additional authority. All regimes are bounded by the same constitution.

14.1 Regime definitions

14.2 Typical parameter behaviour

Arrows indicate typical direction of the revenue allocation relative to the current allocation; every move remains within allocationBounds and maxStepBps.

Regime transitions SHOULD be rate-limited by the governor (hysteresis), and frequent regime flips are reported as a performance metric (§19).

15. Policy receipt

Every policy, passed or rejected, produces a receipt in the PolicyLedger.

Example receipt (rendered):

POLICY #0021 · XYZ · ACCUMULATION
Proposed        2026-10-05 14:00 UTC
Effective       2026-10-05 16:00 UTC
Model           sovr-governor/0.4.2
Input state     4ba69735…0e4e
Constitution    XYZ-001 v1
Policy hash     823412d1…a812
Simulation      32e4bc02…cb4f
Action          SET_REVENUE_ALLOCATION 30/35/20/15 → 35/30/20/15
Constitution    PASS (9 PASS · 9 SKIP · 0 FAIL)
Execution tx    (pending timelock)

16. Security invariants

These are the protocol's non-negotiable properties. Each is enforced in at least one deterministic place and covered by at least one test or a named Stage 3+ test.

17. Constitutional templates

Templates are starting points. Every template below satisfies PROTOCOL_LIMITS and every rule in §4.4. BALANCED is identical to XYZ-001. CUSTOM permits any values that pass validateConstitution.

17.1 Parameters

17.2 Limit conformance

17.3 Template character

• HARD_MONEY — slow, stable-heavy, small buybacks only from the buyback allocation, no POL additions. For mature tokens prioritising reserve credibility.
• BALANCED — the reference. All five actions, moderate caps.
• GROWTH — faster windows, larger liquidity allocation, higher (still protocol-capped) outflows. Higher governed-token exposure is permitted and is the template's main risk; it must be disclosed at genesis.
• RESERVE_MAXIMALIST — accumulation only. No outflow-generating action is permitted; outflow caps are set but cannot be reached. Rebalances keep the reserve stable-heavy.
• CUSTOM — any combination passing validateConstitution. The genesis UI MUST show the diff against the nearest template.

18. Genesis and onboarding

18.1 Genesis flow (new instance)

Mandatory disclosure (step 7). Genesis cannot complete without displaying, verbatim from the constitution being deployed:

GOVERNOR CAN
  · Propose a revenue allocation within: reserve 20–60%, liquidity 10–50%,
    buyback 0–30%, operations 10–25%; moving any bucket ≤ 10% per policy
  · Propose scheduled buybacks ≤ 2.5% of reserve per policy, ≤ 10% of 24h volume,
    ≥ 12 tranches over ≥ 24h, on Orca Whirlpools / Raydium CLMM / Meteora DLMM
  · Propose protocol-owned liquidity within venue caps (35% / 35% / 25%)
  · Propose reserve rebalances among USDC, SOL, XYZ within target ranges
  · Execute at most one policy every 72h, after ≥ 2h public notice
  · Cause total reserve outflow of at most 6% per rolling 30 days

GOVERNOR CANNOT
  · Mint, transfer to any address, withdraw, borrow, or use leverage
  · Use any asset, venue, or protocol not listed in this constitution
  · Deposit into yield protocols or call arbitrary programs
  · Amend this constitution, change its own authority, or disable the pause
  · Act while paused, while oracles are stale, or without a simulation
  · Target, support, or promise any token price

(Example shown for XYZ-001; values are rendered from the actual constitution.)

The creator MUST also acknowledge: the instance is not a bank; it takes no deposits; nothing is insured; token holders have no claim on the reserve.

18.2 Attach existing token

For a token already in circulation with an existing treasury:

1. Token — verify mint; disclose mint authority, freeze authority, and top-holder concentration. If mint authority is held by the project, disclose it prominently: SOVR cannot mint, but the project still can.
2. Treasury import — the project transfers a chosen portion of its treasury into the reserve vault. The remainder stays outside SOVR and is disclosed as "project treasury, not governed".
3. Existing liquidity — existing project-owned LP positions MAY be transferred into the instance as POL; positions on non-allowlisted venues cannot be.
4. Baseline — the indexer computes 90 days of historical revenue, operations outflow, volume and depth to seed the Observer and the static-policy baseline (§19).
5. Mandate, Constitution, Revenue, Governor, Genesis — as in §18.1, including the mandatory disclosure.
6. Observation period — the governor runs in shadow mode for at least three policy windows (proposals validated and published, none executed) before execution is enabled. [Specified, not implemented]

19. Governor performance

There is no single score. Performance is reported as a panel, each metric with its definition and window, and each compared against a static-policy baseline (the genesis allocation held constant with no discretionary actions).

A high constitutional rejection rate is a governor-quality signal, not a security failure: the constitution is working. A rising rate SHOULD trigger review of the model version.

20. Threat model

21. Solana V1 architecture

21.1 Onchain: one consolidated program

V1 uses a single Anchor program, sovr_core, rather than separate registry / vault / executor / ledger programs.

Justification for consolidation:

1. No trust boundaries inside SOVR. Separate programs communicating by CPI introduce authority hand-offs (who may call the vault?) that are themselves attack surface. In one program, the vault PDA's signer seeds are only reachable from execute_policy.
2. Atomic validation and execution. Constitution read, check evaluation, timelock check, transfer and ledger append happen in one instruction under one program's invariants.
3. One audit target, one upgrade authority. Fewer upgrade keys to secure (§26), one set of conformance vectors.
4. Compute. Checks are cheap arithmetic; the expensive parts (swaps) are venue CPIs regardless of structure.

Separation can be revisited when autonomous market making (a separate product) is introduced.

Accounts

Instructions

There is no instruction that transfers vault assets to an arbitrary address.

21.2 Offchain services

Chain state is canonical. Postgres is an index, not a source of truth. Any displayed number MUST be reproducible from chain state + oracle accounts + published artefacts. If the index and chain disagree, the chain wins and the indexer reports DEGRADED.

21.3 ChainAdapter

Chain-specific code lives behind a single interface. Core types are chain-agnostic. [Specified, not implemented]

interface ChainAdapter {
  getTokenState(instance: string): Promise<TokenState>;          // supply, circulating, mint/freeze authority
  getReserveState(instance: string): Promise<ExecutionContext["reserve"] & { venueExposureUsd: Record<VenueId, Usd> }>;
  getMarketState(instance: string): Promise<{ volume24hUsd: Usd; depth: DepthProfile }>;
  getOracleState(assets: AssetId[]): Promise<OracleReading[]>;
  buildPolicyExecution(c: Constitution, intent: PolicyIntent): Promise<UnsignedExecution>;
  submitExecution(tx: UnsignedExecution): Promise<{ signature: string }>;
  getExecutionReceipt(signature: string): Promise<ExecutionReceipt>;
}

22. Prompt-injection defence

Prompt injection is treated as a data-flow problem, not a prompting problem.

22.1 Three zones

If any text source is ever used (e.g. for sentiment), it MUST be reduced by an isolated, unprivileged model to a bounded numeric feature (e.g. an integer score in a fixed range) with no free-text passthrough, and that feature MUST NOT be able to unlock any action the numeric state would not already allow.

22.2 Rules

1. Planner inputs are structured schemas only. No URLs, no free-form strings from external sources.
2. Planner output is the strict intent schema only. No free-text field exists in the executable schema.
3. The planner's tool set is tiny and explicit: read the typed state vector, read the constitution, request a simulation. No web access, no file access, no transaction tools.
4. Token metadata (name, symbol, description) is displayed in the UI but never placed in a model prompt.
5. Even a fully compromised planner can only produce an intent that must pass every check, wait out the timelock in public, and be re-validated at execution.

23. Emergency pause and recovery

23.1 Pause

23.2 Recovery flow

1. Pause — authority pauses; ledger records reason code and timestamp.
2. Diagnose — public incident note referencing affected policies, checks, and transactions.
3. Remediate — if the cause is the constitution, run the amendment process (notice + timelock still apply; pause does not shorten them). If the cause is the program, an upgrade follows the upgrade policy (§26). If the cause is a dependency, wait for recovery.
4. Request resume — authority calls request_resume; the ledger records it.
5. Resume delay — resumeDelaySeconds (≥ 1 h; XYZ-001: 6 h) must elapse. This gives observers time to react to a resume made under a compromised key.
6. Resume — execution re-enabled. Policies approved before the pause are re-validated against current state; those invalidated by elapsed cooldown windows, oracle state or a new constitution hash are rejected. The governor MUST re-propose rather than replay.

24. Development stages

25. Conformance tests

src/core/engine.test.ts is the Stage 2 conformance suite. A conforming executor implementation (including the Stage 3 program) MUST produce the same verdicts and rejection codes for the same inputs.

25.1 Fixtures

25.2 Valid policy

25.3 Core rejection behaviour

25.4 Parameter checks

25.5 Constitution validation (malicious creators)

25.6 Hashing

25.7 Coverage gaps (to add)

The following codes and rules are implemented but not yet directly asserted by a test: DUPLICATE_ACTION; NO_CHANGE combined with another action; future-dated intent (proposedAt > now + 300); INSUFFICIENT_RESERVE; ORACLE_MISSING via oracle network OFFLINE; rebalance with identical assets; POL pair with identical assets; validateConstitution rules 4, 5, 8, 9, 11, 13, 14, 15, 16, 18, 19, 20, 21, 22, 23, 24, 27. Each SHOULD gain a test before Stage 3 so the conformance vectors fully cover the executor.

26. Open questions and challenges

This section deliberately challenges the design. Each item needs a decision before Stage 6.

26.1 Buybacks: funded from reserve or from revenue?

The engine counts a buyback's full amount_usd as a reserve outflow and debits the reserve's pay_asset. Meanwhile the revenue allocation has a buyback bucket. The two are not reconciled: a policy can spend reserve USDC on a buyback regardless of how much revenue was allocated to buybacks.

Spending reserve on buybacks during a revenue shortfall converts durable assets into the most reflexive asset at the worst time. Recommendation: buybacks SHOULD be funded only from an accrued buyback balance (the cumulative buyback allocation of revenue, less prior buyback spend), held as a sub-account of the vault. Add a check (BUYBACK_BUDGET) that amount_usd ≤ accrued buyback balance. Reserve-funded buybacks, if allowed at all, should be a separate, constitution-level opt-in with tighter caps.

26.2 Should governed-token holdings count toward reserve value?

Currently reserve.totalUsd — the denominator for per-policy and rolling outflow caps — includes the governed token at oracle price. Consequences:

• A buyback increases governed-token holdings, which increases totalUsd, which loosens future caps.
• A rally in the governed token loosens caps exactly when they matter least; a crash tightens them exactly when liquidity is needed.

Recommendation: report governed holdings separately (§5.4) and compute caps on a haircut reserve value (e.g. stable + SOL + 50% of governed), or on reserve ex-governed. This is a semantic change to PER_POLICY_OUTFLOW, ROLLING_OUTFLOW and composition math and must be versioned.

26.3 Rolling cap denominator drifts

The rolling cap is computed against current reserve.totalUsd, not the value at the start of the window. As the reserve shrinks (or a price falls), the cap shrinks too — conservative in a decline but permissive in a rally. A cap anchored to the window-start reserve or the window minimum would be more predictable. Decide and specify.

26.4 Reflexivity of runway measured in SOL

Runway counts SOL at spot. A SOL drawdown shortens runway and can push the governor toward CONSERVATION, rebalancing SOL → USDC after the fall (selling low). Options: report runway in two forms (USDC-only and USDC + haircut SOL); use a volatility-adjusted SOL value; set mandate tolerances so a SOL drawdown alone does not trigger a regime change. The SOL_-30 scenario exists precisely to expose this.

26.5 Oracle quality for long-tail governed tokens

The engine requires readings from every configured source for the governed token whenever a buyback is proposed. Most long-tail tokens lack two independent, robust oracle feeds; available feeds are often derived from the same thin pool the buyback trades against, making "agreement" meaningless. Questions: minimum liquidity / source-independence requirements for the governed token at genesis; whether TWAP-based feeds qualify; whether buybacks should be disabled until oracle quality is attested.

26.6 Depeg is not detected

ORACLE_DEVIATION detects disagreement, not a depeg on which all sources agree. Proposed check STABLE_PEG: for assets flagged stable in reserveAssets, reject value-moving actions that sell another asset into the stable (or count it at par) when its price is outside a band (e.g. ±2%). [Specified, not implemented]

26.7 Volume-based caps are manipulable

The participation cap uses volume24hUsd, which wash trading inflates cheaply on Solana. Mitigations to evaluate: use the minimum of 24 h and 7 d average volume; use volume only from allowlisted venues; exclude self-trades detectable onchain; cap absolute buyback size additionally by depth within ±2%.

26.8 Legal and regulatory language risk

"Every token is its own bank" is a product metaphor with real regulatory risk: in many jurisdictions "bank" is a protected term, and language implying deposits, safekeeping, guaranteed reserves or backing may create obligations or be misleading. Requirements:

• the tagline is always paired with plain-language disclosure (§1.2) on the same surface;
• prohibited words in UI and receipts: "deposit" (for anything a user does), "insured", "guaranteed", "backed by", "redeemable", "price support", "peg" (for the governed token);
• legal review of the tagline and all public copy before mainnet, per launch jurisdiction.

26.9 Does the governor add value over a static rule?

A fixed allocation with periodic scheduled buybacks is cheap, predictable, and immune to model failure. The governor must earn its complexity. Recommendation: every instance publishes its performance panel (§19) against a static-policy baseline computed on the same history. If the governor does not outperform the baseline on the mandate's own weighted metrics over a defined period, the honest default is to recommend the creator reduce permittedActions or widen policyWindowSeconds. A constitutional option for "static fallback policy when governor is offline" should also be considered; today offline means no action.

26.10 Program upgrade authority

Every invariant above is only as strong as the program's upgrade authority. Options: immutable program (no fixes); upgrade gated by a multisig with a timelock ≥ the longest amendment timelock; upgrade gated by per-instance opt-in (instances pin a program version). This must be decided before Stage 3 deploys anything holding value, and disclosed at genesis.

26.11 Reserve-held governed tokens: retain or burn?

Bought-back tokens currently settle into the reserve and count toward reserve value (see 26.2). Retaining them preserves optionality; burning them removes the reflexive asset from the balance sheet but is irreversible. V1 retains. A constitution-level, amendment-gated "retire bought-back tokens" option may be specified later.

26.12 No exit path for POL

V1 has no action to remove protocol-owned liquidity. If a venue degrades, the only recourse is amendment (slow) or pause (which cannot move funds). A bounded REMOVE_PROTOCOL_OWNED_LIQUIDITY action — inflow-only to the vault, allowlisted venue, slippage-bounded — is a candidate V1.1 addition.

26.13 Amendment authority check is name-based in the reference engine

validateConstitution rejects an amendment authority whose name matches /governor/i. This is a reference heuristic. Onchain, the rule MUST be identity-based: the amendment authority key MUST NOT equal the proposer key or any key controlled by the governor service.

26.14 Engine allocation projection

SET_REVENUE_ALLOCATION changes how future revenue is split, but RESERVE_COMPOSITION and the outflow caps evaluate only the current vault. A combined policy (allocation change + buyback) is evaluated against the pre-allocation state. This is acceptable because allocation does not move existing funds, but it should be stated explicitly in receipts.

27. Non-goals for V1

SOVR V1 will not include:

28. Glossary

29. The product test

Every design decision in this document is judged by one question:

Can I trust the system even when the AI is stupid?

If the governor hallucinates, the schema and the constitution reject it. If it goes offline, nothing happens. If it is injected, it can only propose what the constitution already allows, in public, after a timelock, re-checked at execution. If it is consistently wrong, the performance panel shows it against a static baseline, and the constitution — not the model — limits the damage.

The AI does not control the money. The constitution controls the AI.