02 — Architecture overview

1. The five layers

OAW is a stack of five layers. Each is independently testable, and each maps to a concrete reference module in the Betvax tree.

┌───────────────────────────────────────────────────────────────────────────┐
│ L5  INTENT SAFETY                                                           │
│     Reasoning classifier → deterministic, policy-gated execution.          │
│     ref: chat_capability_intent_service.py                                  │
├───────────────────────────────────────────────────────────────────────────┤
│ L4  EXECUTION + POLICY                                                       │
│     agent_authority block, spend-intents, reservations, receipts, policy.  │
│     ref: agent_policy_engine, venue_execution_receipts, EconomicActionReceipt│
├───────────────────────────────────────────────────────────────────────────┤
│ L3  FUNDING                                                                 │
│     CAIP-2 chain map; deposit-address + bridge + swap routing; gated execute│
│     ref: venue_funding_router.py, stablecoin_route_service,                 │
│          polymarket_bridge_service                                          │
├───────────────────────────────────────────────────────────────────────────┤
│ L2  VENUE BINDING                                                           │
│     Venue capability contract registry + universal pre-bind gate +         │
│     per-venue adapters.                                                     │
│     ref: venue_capability_contract.py, venue_prebind_gate.py,              │
│          venue_binding_service.py, *_venue_service.py                       │
├───────────────────────────────────────────────────────────────────────────┤
│ L1  AGENT AUTHORITY                                                         │
│     AgentAuthority (EconomyOSAgentProfile) + provider adapters.            │
│     ref: economyos_agent_wallet_service.py, virtuals_os_acp_v3_client.py    │
└───────────────────────────────────────────────────────────────────────────┘
        ▲
        │  provider adapters plug in here
   ┌────┴─────────────────┬───────────────────────┬─────────────────────┐
   │  Privy adapter       │  Virtuals adapter      │  External adapter   │
   │  embedded / server / │  EconomyOS / ACP /     │  user key /         │
   │  server-v2 (agent) / │  DegenClaw /           │  capped signer      │
   │  deposit-address     │  tokenization          │                     │
   └──────────────────────┴────────────────────────┴─────────────────────┘

The agent brain (Hermes or any LLM runtime) sits above L5 on the chat/mobile surface. It is a client of this stack, not a layer in it. It never holds keys.

2. The object model

Five durable objects, provider- and venue-agnostic. Names in parentheses are the Betvax reference names.

AgentAuthority (EconomyOSAgentProfile)

The single parent authority for one agent. Holds:

• authority_source: provider_managed | virtuals_linked | external_imported
• wallet_provider: privy | virtuals | external
• wallet_address, provider_wallet_id (e.g. privy_agent_wallet_id)
• virtuals_agent_id, proof_state (verified | pending | unverified | n/a)
• signer_status, supported_chains
• policy reference (caps, autonomy mode, blocked categories)
• never holds raw key material; references it by opaque provider id only.

VenueBinding

A child of AgentAuthority, one per venue. Holds binding payload (JSONB), lifecycle state, venue-local signer/credential references (not secrets), and the audit trail. Many bindings per authority is a hard requirement.

VenueCapabilityContract

Declarative, not per-user. The registry entry for a venue: its auth model, signing model, lifecycle modes, funding/readiness/approval requirements, whether it needs per-user authority, whether it's ACP-native, etc. Adding a venue is mostly a contract entry + one adapter.

FundingPlan / FundingReceipt

The resolved route from agent balance → venue's native chain, plus the durable record of any executed transfer.

SpendIntent / ExecutionReceipt

The durable economic-action records. A live venue action must have a spend-intent (reservation + policy decision) before execution, and a receipt + audit event after.

Relationship

User
 └─ Agent (brain)
     └─ AgentAuthority         (1 active authority; provider adapter resolves it)
         ├─ VenueBinding[polymarket]   ─ FundingPlan ─ SpendIntent ─ ExecutionReceipt
         ├─ VenueBinding[hyperliquid]  ─ FundingPlan ─ SpendIntent ─ ExecutionReceipt
         ├─ VenueBinding[virtuals]     ─ (ACP jobs) ─ EconomicActionReceipt
         └─ VenueBinding[…]

3. The brain/executor split (the security spine)

This is the single most important architectural decision and the reason OAW is safe to drive from chat.

   ┌──────────────┐   intent (text)    ┌────────────────────────────┐
   │  Agent brain │ ─────────────────▶ │  L5 intent classifier      │
   │  (LLM/Hermes)│                    │  reasoning, not keywords   │
   │              │ ◀───────────────── │  → capability + is_action  │
   └──────────────┘   plan / question  └────────────┬───────────────┘
        decides WHAT                                 │ only on confident action
        holds NO keys                                ▼
                                    ┌────────────────────────────────┐
                                    │ L1–L4 backend executor          │
                                    │ resolves authority, checks      │
                                    │ policy + funding + live flags,  │
                                    │ signs via provider adapter,     │
                                    │ writes receipt. Holds the keys. │
                                    └────────────────────────────────┘
                                       decides WHETHER + actually DOES

Properties this buys you:

• Prompt injection cannot move money. A poisoned input can at most make the brain propose an action; the backend still independently checks policy, limits, funding, live flags, and ownership before it signs.
• The LLM is replaceable. Hermes, GPT, Claude, a local model — all are clients of the same executor. The executor's guarantees don't depend on the model.
• Determinism where it matters. Recognition is fuzzy (a model); execution is deterministic and gated. The fuzzy part can never directly cause an irreversible effect.

Anti-pattern explicitly rejected: letting the LLM call a "sign and submit" tool directly. The model may request execution; the backend is the gate.

4. Capability flags & fail-closed defaults

Every money-moving capability is off by default behind an explicit config flag and only acts when all of: live flag on, policy passes, funding present, approval present (where required), authority verified. Reference flags: VENUE_FUNDING_EXECUTE_ENABLED, per-venue live-execution flags. When a flag is off, the system returns a precise ready_but_live_locked with execution_performed: false — it does not degrade to a fake prepare-only product, and it does not silently skip the action.

5. What "plug and play" means concretely for a dev

A developer integrating OAW does four things:

1. Pick a provider adapter (Privy by default) and configure it. They get ensure_agent_wallet() and link_existing_virtuals_agent() for free.
2. Enable the venues they want by including their VenueCapabilityContract entries. They get binding, pre-bind gating, readiness, and funding-target resolution for free.
3. Wire the funding router with their supported source chains. They get "deposit anywhere → fund the venue" for free.
4. Attach their chat brain to the L5 classifier. They get reasoning-based intent → deterministic gated execution for free.

What they write themselves: the venue adapter's execute() for any venue OAW doesn't ship, and their agent's strategy/prompts. Everything else is the kit.

6. Reference module map (Betvax → OAW)

OAW concept	Betvax reference file
AgentAuthority + provider ops	economyos_agent_wallet_service.py
Virtuals/ACP adapter	virtuals_os_acp_v3_client.py
Venue capability contract	venue_capability_contract.py
Universal pre-bind gate	venue_prebind_gate.py
Generic venue binding	venue_binding_service.py
Hyperliquid venue adapter	hyperliquid_venue_service.py
Polymarket binding orchestrator	polymarket_binding_orchestrator.py
Funding router	venue_funding_router.py
Intent classifier	chat_capability_intent_service.py

The next docs specify each layer in turn, starting with the heart — L1 authority.