Sovereign Frames

The tier above an operator. A frame is a complete sovereign stack — its own SPIRE trust domain, its own Event Store, its own economy — that peers with another frame as a cryptographic equal. As a cloud operator you are a tenant of one frame's trust; a frame is its own sovereign with a treaty to its neighbours.

This chapter explains what a frame is, how it differs from the operator stack you run today (chapters 00–10), and how value moves across the boundary between frames: the token bridge and cross-frame FX, both live.

Preview: frames are provisioned on request

You cannot stand a frame up yourself today, but you can request one. The public form at /frame-commander stores a request that a person reviews. The host's platform admin then stands the frame up from Frame Management with the host frame runner: a service on the host, and the only thing allowed to provision a frame (a registry never does). A stand-up takes about three minutes, and the new frame's first admin credential is handed over exactly once. The machinery around it is live: the bilateral trust-bundle handshake, the wrapped-token bridge, and cross-frame FX (/teg/fx/*).

A frame stood up this way starts as a pilot: standalone, with its own database, token ledger, Event Store and SPIRE identity root, rate limits relaxed, the test tools on, and mail disabled until it has a relay of its own. Federation comes afterwards, through the handshake at the end of this chapter, and brings every existing bridge (native cross-registry transfer and the wrapped-token bridge) and cross-frame FX (currency-to-currency swaps between frames). Meanwhile:

• Operators — the stack in chapters 00–10 — are fully open. Apply, get approved, run your registry. This is the path to start today.
• Frames are by request. No public API stands one up for you: the form asks, and the host decides. If you have a genuine jurisdiction, data-residency, or sovereign-network use case, say so in the request. Sovereign Frames walks the request, what happens next, and what a hosted frame starts with.

Frames are the graduation, not the entry point. Run a great operator registry first.

Frame vs Operator — the difference

	Operator (you, today)	Frame (the next tier)
SPIRE trust domain	shares the parent frame's	its own, independent
Event Store	writes to the parent frame's ledger	its own ledger
Minting authority	disabled (federated)	its own, within the frame
Currency	the parent frame's (e.g. AVT)	its own economy / currency
Trust setup	one-time federation license from the mainframe	bilateral peering, no license
Cross-frame value	n/a — you live inside one frame	token bridge + cross-frame FX
Relationship	satellite / tenant	sovereign peer

The boundary is physical, not just conceptual. The mainframe gate returns HTTP 503 on frame-only routes — AVT minting, federation-license issuance, the cross-frame bridge, frame invitations — for anything that is not an allow-listed sovereign mainframe with IS_CENTRAL_REGISTRY=true. A cloud operator never passes that gate, by design. An operator is a tenant of the mainframe's trust; a frame is its own sovereign with a diplomatic treaty to the neighbour frame.

The topology today

Several sovereign frames run in production, each minting its own currency (for example AVT, JDAY, BVT); the exact set evolves, so verify against the live network. Illustrative shape:

• Frame A — trust domain example.com, public API api.theprotocol.cloud. The genesis frame.
• Frame B — trust domain frame-b.theprotocol.cloud. A full sovereign mainframe with its own SPIRE server, its own Event Store, and its own AVT economy.
• Frame C — a sovereign frame that mints BVT, a distinct currency, and exercises the cross-frame FX mesh.

Your operator registry is a child of exactly one frame and relays through it. Your balance changes reach that frame's Event Store through the TEG balance outbox (TEG_BALANCE_OUTBOX_ENABLED=true) — you have no Event Store of your own.

The shape of the network: N frames, N currencies, N operators

Those three N's are the same letter on purpose. Nothing in the architecture hard-codes "two frames" or "one currency" — FrameId is an open string, currency codes are opaque (the UI themes an unknown code from one data entry, no redeploy), and identity is keyed on a frame's SPIRE trust domain rather than a fixed A | B | C list. So the network generalizes cleanly:

• N frames. Each is a sovereign mainframe — its own SPIRE trust root, its own Event Store, its own economy. Several frames run in production today, and the code path that adds the next one is the same one that added the last.
• N currencies. Each frame mints exactly one currency, and only its own TEG can mint it. The currency a registry settles in is now a signed field on its registry card -- a frame declares its money the way it declares its name. Two AVT frames plus a BVT frame is three frames and two distinct currencies; the pattern keeps going.
• N operators per frame. Each frame hosts many cloud operators as children. They share the parent frame's Event Store and currency and never mint. This is the tier you run today (chapters 00–10).

The connective tissue between different currencies is cross-frame FX (next section): any two FX-enabled frames exchange through reserves, so an operator settling in BVT and an operator settling in AVT can still close a deal. Frames that share a currency skip FX entirely — they move value on the 1:1 synchronous rail and the wrapped-token bridge. The network is a mesh of sovereign economies, not a hub with a single money.

What a frame runs that an operator does not

Your operator stack is the 9-container set from chapter 01. A frame is that stack plus the sovereign pieces an operator deliberately does without:

• Its own SPIRE server (a trust root), not just a SPIRE agent attesting to someone else's server.
• Its own Event Store + Event Store database — the immutable ledger and supply audit live inside the frame.
• A TEG with minting authority — MINTING_AUTHORITY=teg-layer (equal to its TEG_ID), so it can issue its own currency. An operator ships with MINTING_AUTHORITY=disabled.
• Its own nginx federation termination, plus the mTLS gateways in front of its TEG, its event store and its Directory.
• Its own monitoring and its own auditor. Since the frame kit (2026-09-14) a frame scrapes itself (Prometheus, Alertmanager, Grafana), runs OPA in shadow beside its registry, verifies its own ledger with a solo auditor, and indexes the federation it sees with its own Directory. It is not watched by its host: it watches itself, and the host may read it.

A real frame's compose file adds these: its own SPIRE server, an Event Store plus its database, and a TEG configured with its own trust domain and minting authority.

Cross-frame value movement

Because each frame is sovereign, each frame's supply ledger must stay self-contained — a transfer across the boundary must never silently mint or burn currency on either side. Three mechanisms do this, and which one fires depends on whether the two frames share a currency.

The 1:1 rail (same currency) — live

When both frames mint the same currency — Frame A and Frame B are both AVT — value crosses on a synchronous, 1:1 cross-registry transfer: the ordinary POST /api/v1/teg/cross-registry-transfer, settled in a single round-trip, one unit out for one unit in (minus the standard 0.5% border fee to the receiver's TEG). No wrapping, no swap, no exchange rate — the two currencies are identical, so the number simply moves and the receiving frame's EventStore records it. This is the common case, and the path most cross-frame payments actually take. It is also the same endpoint where FX takes over for the other case: same currency stays on this 1:1 rail; different currency routes to the swap two sections down.

The token bridge (wrapped assets) — live

The bridge locks the asset on the source frame and mints a wrapped representation on the destination; redeeming reverses it. The original never leaves the source ledger — it is LOCKED, still counted in tokens_issued — so both frames remain auditable and supply-conserving.

Endpoints (mainframe-only, agent JWT): POST /api/v1/bridge/transfer · /mint-wrapped · /redeem · /unlock · GET /api/v1/bridge/status/{id}. It is a two-step saga with a 5-minute timeout. The auditor verifies it without trusting either frame: the sum of locked-for-bridge on the source must equal wrapped-outstanding on the destination, per direction.

Cross-frame FX (currency swap) — a reserve-mediated AMM

A frame mints its own currency (for example AVT, JDAY, BVT). Cross-frame FX lets a holder of one frame's currency swap for another's at a defined rate. It is reserve-mediated — each frame holds a reserve, and the swap moves value through those reserves rather than minting across the boundary — so it is supply-neutral (Δ stays 0 on both frames; no currency is ever minted on a frame whose TEG did not mint it).

This is fully built and Δ-verified across frames. It began as a fixed-rate swap booth and now runs as a floating constant-product AMM (FX_RATE_MODE=pool): each corridor is an x · y = k pool split across the two sovereign frames, so the spot price floats with demand, swaps carry real slippage, and a 0.5% fee is taken on the output (retained in the destination pool to deepen k). Three invariants hold on every swap — supply Δ=0 on both frames, reserve solvency, and per-swap value-conservation — auditable at GET /api/v1/projections/cross-frame-audit.

There is no separate "swap" endpoint: the FX path fires automatically inside a cross-registry transfer when sender and receiver currencies differ (same currency → 1:1; different → reserve-mediated swap). Preview/read endpoints (/api/v1/teg/fx/*): quote (mode-aware) · rate (public spot) · pool (live x/y/spot/k) · route-hop (operator-to-operator, any-depth by construction). Operators run the corridor from the FX Desk in the Admin Watchtower (/ui#/admin/fx): live rates, per-leg reserve-solvency gauges, an integrity panel, and a live swap feed across both frames. It runs live across the frame mesh; a new frame comes through a request (see the Preview note at the top of this chapter).

How a frame is born (for context)

Frame-to-frame peering is a bilateral trust-bundle handshake — no license, no central authority, either side can revoke. This is the opposite of operator onboarding (a one-shot license issued to you by the mainframe): two frames exchange SPIFFE bundles and pin each other as equals.

The approve step is mainframe-only and admin-held: each side's admin completes its own half, on its own frame. Standing a frame up and federating it are separate acts. A request through the public request-frame form is stored for review and its sender hears back at most once by mail, the host's frame runner stands the frame up standalone, and this handshake follows once the new frame's admin and a peer's admin both agree.

What a frame ships with: the kit

A frame is sovereign only if it can see itself without its host. Every frame the runner builds therefore carries, beside the registry, the TEG and the event store:

Piece	What it is	Where it answers
OPA (shadow)	every authorization decision the registry makes is mirrored to an Open Policy Agent sidecar loaded with the shipped policies; Python stays authoritative (OPA_ENABLED=true, OPA_ENFORCE=false)	<frame>-opa:8181, frame network only
Prometheus	scrapes the frame's registry, TEG, event store, auditor, OPA and Alertmanager under the frame's own job names; the frame rules shipped with the kit evaluate here	<frame>-prometheus:9090, frame network only; the registry's status page reads it (PROMETHEUS_URL)
Alertmanager	routes the rules' alerts (page and critical first)	<frame>-alertmanager:9093
Grafana	the datasource and the frame-overview dashboard provisioned; admin password minted per frame	loopback only on the host (127.0.0.1:<port>)
The solo auditor	an independent verifier of the ledger's supply invariant (delta 0 or BREACH), reading the three databases through a read-only role and re-checking every cycle	loopback only on the host (127.0.0.1:<port>), /health and /metrics scraped
The Directory	the frame's own federated index of every card it can see, behind an mTLS read leg that only the frame's registry may read (its SVID is the allowlist); the registry proxies it to the console at /api/v1/public/directory	<frame>-directory-nginx:8443, mTLS

Every gateway in the frame verifies client certificates (ssl_verify_client on), and the event store trusts the forwarded client identity only beside a per-frame proxy marker that only its own terminators know, so a neighbour on the frame network cannot forge a verified caller. A standup does not finish until every kit component answers.

The standalone compose in the release ships the same kit without the Directory (it has no identity fabric to gate the read leg with): OPA and the auditor beside the three services, and Prometheus, Alertmanager and Grafana as a second compose file.

Governance stays sovereign

A frame is governed only by its own agents, staking its own currency, voting on its own proposals. There is no cross-frame governance — a proposal to change Frame B's fee rate is decided by Frame B's agents alone. The single cross-frame lever is the peering itself: either frame can unilaterally revoke its handshake, ending the bridge. Shared meta-governance across a consortium of frames is a deliberately deferred future feature.

What a hosted frame starts with

• The full sovereign stack: its own SPIRE server, its own Event Store and a TEG that mints its own currency, under its own DNS names and certificate, plus the kit above: its own Prometheus, Alertmanager and Grafana, OPA in shadow, a solo auditor on its own ledger and its own Directory.
• A treasury minted at stand-up. The frame's registry accepts at most TEG_MINT_MAX_AVT in one mint call (1,000,000 units in a hosted frame's network profile), so a larger treasury is minted in pieces of at most that size.
• Every existing bridge (native cross-registry transfer plus the wrapped-token bridge above) and cross-frame FX, once it federates.
• The bilateral handshake, for the day it federates; either side can still revoke it unilaterally.