Architecture
Ohge is an AI trading application on Solana built around one rule: the AI is never the security boundary. A Solana program (Ohge Guard) holds the funds and enforces the owner's policy; an agent only proposes; a separate worker signs with a limited, expiring session key; the owner can pause, revoke and withdraw at any time.
Components
| Component | Where it runs | Responsibility |
|---|---|---|
Ohge Guard program (onchain/programs/ohge_guard) | Solana (Anchor 1.0.2) | Vault PDA as token authority; policy storage; session registration; atomic policy enforcement around one validated Orca Whirlpool swap CPI; drawdown circuit breaker; owner controls. |
Web app (src/app) | Next.js 16 (server + browser) | Landing page, dashboard, wallet sign-in, transaction building with the wallet, read-only chain views, REST API for the worker's records. |
Agent worker (scripts/worker.mts → src/server/worker) | Long-running Node process | Durable job queue (PostgreSQL), proposal generation via a configurable LLM provider, execution through the session signer, confirmation and reconciliation, heartbeat. |
Session signer (src/server/signer) | Worker host or external service | Creates session keys, signs transaction messages. Never exposes private bytes to the model or the API. |
PostgreSQL (src/server/db) | Managed PostgreSQL / embedded local server / PGlite | Users, nonces, vault labels, strategies, session key metadata (public keys and handles only), proposals, transactions, jobs, heartbeats. |
Data flow
- The owner connects a wallet and signs a nonce-bound sign-in message (domain, network, issued-at, expiry; single use).
- The owner creates a vault (
initialize_vault), sets a policy (set_policy), deposits (deposit) and registers a session public key (register_session). Every one of these is signed by the owner's wallet in the browser; the API only records signatures for reconciliation. - The worker runs the strategy on its interval: it reads the vault, balances, Pyth reference prices and the Orca pool from the chain, computes a rebalancing candidate, and asks the LLM for a structured intent (
holdorswapof at most the candidate amount). The output is validated against a strict schema and against the verified state. - In review mode the proposal waits for the owner. In autonomous session mode it is queued for execution immediately.
- Execution re-reads the chain (policy version, nonce, session validity, balances), fetches a venue quote, computes the reference floor, builds the single
execute_orca_swapinstruction, signs it with the session key through the signer, simulates it, sends it and waits for confirmation. Nothing is marked successful before the cluster confirms it; an offchain rejection is recorded as such and never as an onchain event. - The program enforces everything again atomically: control state, authority, nonce, policy version, expiry, adapter, venue, mints, per-trade and per-window amounts, reference floor, drawdown floor, then the real balance deltas after the CPI.
Why chain state is authoritative
Balances, policy, session state, nonce and spending counters are read from the vault account and the token accounts on every request. The database holds labels, strategy settings and records of what the app did; if the two disagree, the UI says so and follows the chain.
Networks
Local validator (tests clone the mainnet Orca pool and Pyth feeds), devnet (real transactions; the devnet pool uses a test token with no USD reference) and mainnet-beta (only with a configured, reviewed deployment). The build never targets mainnet by itself; see Setup and deployment.