Technical Reference · April 2026

Opacus System Layers

A complete layered view of how every component in the Opacus platform fits together — from on-chain contracts to the frontend dashboard.

Layer Overview

Six-Layer Platform Stack

Opacus is organized into six horizontal layers. Higher layers compose on top of lower ones; each layer has a clean interface to the one below it.

📦

LAYER 5 — SDK & Client Tools

Developers integrate via npm, REST, or MCP

opacus-sdk (npm) OpenClaw MCP Postman Collection opacus-sdk.ts @0gfoundation/0g-ts-sdk

HTTP API / JSON-RPC — all calls flow down to Layer 4

🖥️

LAYER 4 — Frontend (Agentboard)

Single-page dashboard — agentboard.html (~23 000 lines)

Vanilla JS SPA kernelFetch() wrapper localStorage JWT MetaMask / EIP-1193 8 sidebar tabs WebSocket events

HTTPS/fetch → Vercel CDN rewrites → /api/:path* → agent-kernel

⚡

LAYER 3 — API Gateway (Vercel Serverless)

Edge routing, CORS, rate-limiting, auth middleware

Vercel Edge vercel.json rewrites rate-limit (60 req/min) HMAC challenge tokens Bearer JWT auth X-Opacus-User-Email (dev) CORS origin guard

Dispatches to Internal Services — Agent Kernel, Blob KV, Vercel Logs

🧠

LAYER 2 — Agent Kernel (Business Logic)

api/agent-kernel.js — 11 000+ lines — all orchestration lives here

Express.js v5 ethers.js v6 @noble/ed25519 snarkjs (ZK groth16) @0gfoundation/0g-ts-sdk @0glabs/0g-serving-broker Vercel Blob KV collectFeeOnChain (USDC) ERC-7755 Kinetic Score H3 geo-index (res 8)

JSON-RPC → Blockchain RPCs / 0G Network nodes / Vercel Blob

📜

LAYER 1 — Smart Contracts (On-Chain)

Base mainnet + 0G chain — deployed, immutable logic

Bridge (Base) Bridge (0G) EscrowV2 (0G) USDC (Base) USDC.e (0G) Jaine Router (0G) Jaine Factory (0G) OpacusTreasury

P2P consensus / DA proofs / Storage proofs

⛓️

LAYER 0 — Blockchain Infrastructure

Base (EVM), 0G (EVM + DA + Storage + Compute), Ethereum

Base · chainId 8453 0G · chainId 16601 Alchemy RPC (Base) evmrpc.0g.ai 0G Storage Indexer 0G DA Layer 0G Compute Network

Request Flow

End-to-End Request Lifecycle

Every call from a user's browser to a blockchain transaction follows this path:

        Example: User calls kineti_score_get from Agentboard
      

Browser / SDK

agentboard.html

→

kernelFetch()

adds JWT header

→

HTTPS POST

opacus.xyz/api/runtime/task-execution

→

Vercel CDN

rewrite: /api/:path*

↓

agent-kernel.js

module.exports handler

→

initStore()

hydrate from Blob KV

→

Rate Limit Check

60 req/min per user

→

Auth Middleware

JWT / email header

↓

ensureUserProfile()

derive execution wallet

→

path router

/runtime/task-execution

→

rpcMethod dispatch

kineti_score_get

→

calculateKineticScore()

audit log → score

↓

sendJson(res, 200)

{"ok":true,"score":82}

→

Vercel CDN

CORS headers added

→

Browser renders

Kinetic Score card

Product Map

16 Products, One Kernel

Every product routes through the same api/agent-kernel.js entry point. The table below shows which Layer 2 module each product lives in and its current production status.

Product	Primary Path(s)	Layer 2 Module	Chains	Status
Agent Kernel	`/health` `/`	root handler, initStore, blobSaveStore	—	Live
OpacusPay	`/v1/pay/balance` `/v1/pay/escrow/*`	collectFee, collectFeeOnChain, ledgerEntries	Base	Live
Kinetic Score (ERC-7755)	`/runtime/task-execution` → kineti_score_*	calculateKineticScore, kineticScores store	0G DA	Live
OpenClaw MCP	`/openclaw/skills` `/openclaw/execute`	runtime/openclaw.ts, skill-loader.ts	—	Live
Base ↔ 0G Bridge	`/v1/bridge/initiate` `/runtime/bridge-status`	bridge contract ABI, requestId event parsing	Base + 0G	Live
0G Storage	`/runtime/task-execution` → og.storage.*	@0gfoundation/0g-ts-sdk, ZgIndexer, ZgMemData	0G	Live
0G Compute / Inference	`/runtime/task-execution` → og.compute.*	@0glabs/0g-serving-broker, ogComputeRequests	0G	Live
Agent Citadel (DID)	`/citadel/challenge` `/citadel/register`	ed25519 key derive, citadelAgents store	—	Live
ZK Proofs	`/zk/prove` `/zk/verify`	snarkjs groth16, @noble/hashes, zkProofs store	0G DA (anchor)	Live
TEE Enclave	`/tee/attest` `/tee/verify`	DCAP simulation, ephemeral token, teeAttestations	0G DA (anchor)	Live
Escrow	`/escrows` `/escrows/lock` `/escrows/:id/release`	lockEscrowOnChain, EscrowV2 ABI	Base	Live
Gasless / Gas Station	`/runtime/task-execution` → gasless.*	gasless/gas-station.service.ts, gasSponsorUsage	Base + 0G	Live
Intent Layer	`/intent/submit` `/intent/status`	intent-builder, intent-broadcast, intent-redis	Cross-chain	Live
Execution Agents	`/runtime/task-execution` → agent:*	trading-execution-agent, MEV / flash-loan bots	Base + 0G	Live
Space Agent (X Reward)	`/runtime/task-execution` → space.*	space-agent/space-agent-service.ts	Base	Beta
Proofs Feed	`/proofs/feed`	zkProofs + teeAttestations + escrows merge	—	Live

Smart Contracts

On-Chain Contracts (Layer 1)

Contract	Chain	Address	Purpose
Bridge Source	Base (8453)	`0x15c54901c4F313565c9B29C651fe20Ff6D59022e`	initiateBridge() — locks USDC, emits BridgeInitiated event
Bridge Destination	0G (16601)	`0x6A7F6d1F821Af4F7f8f2E01A3fb80e3f81BD27B5`	completeBridge() — mints USDC.e on receipt
Escrow V2	0G	`0x8E1c2aA49fe5a7611313bEf8188757AF35eF91C6`	lockFunds(), releaseFunds(), refundFunds() — trustless task budgets
USDC	Base	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`	ERC-20 — primary payment token
USDC.e	0G	`0x0d21B68b28234c07a46b7E3c2e7f0b7e1dBf9Ae3`	Bridged USDC on 0G — DEX liquidity
Jaine DEX Router	0G	`0x8B598A7C136215A95ba0282b4d832B9f9801f2e2`	Uniswap V3 interface — exactInputSingle
Jaine Factory	0G	`0x9bdcA5798E52e592A08e3b34d3F18EeF76Af7ef4`	Pool discovery — fee tiers 100 / 3000 / 10000
Treasury	Base	`0xA943F46eE5f977067f07565CF1d31A10B68D7718`	Receives 1% platform fee (real USDC transfer)

Key Flows

Transaction Flows

Expand any flow to see the exact step-by-step path through the system.

🌉 USDC Bridge: Base → 0G

// 1. Frontend
POST /api/v1/bridge/initiate
  { token: "USDC", amount: 100, destChainId: 16601, recipient: "0x..." }

// 2. Agent Kernel — collectFeeOnChain (1%)
USDC.transfer(treasury, 1e6)   // on Base mainnet

// 3. Agent Kernel — calls bridge contract
Bridge.initiateBridge(USDC, 99e6, 16601, recipient, salt)
  → emits BridgeInitiated(requestId, ...)
  → kernel saves requestId to store

// 4. PM2 relay (bridge-relayer process)
// Watches Base for BridgeInitiated events
// Calls 0G Bridge.completeBridge(requestId)
// User receives USDC.e on 0G

// 5. Status polling
GET /api/runtime/bridge-status?requestId=0x...&sourceChain=base
  → {"status":"completed","txHash":"0x..."}
        

🔐 ZK Proof → Kinetic Score Boost

// 1. User generates ZK proof
POST /api/zk/prove
  { kind: "identity", inputs: { threshold: 70, score: 82 } }

// 2. Kernel generates commitment (sha256)
// 3. Anchors to 0G DA via @0gfoundation/0g-ts-sdk
// 4. Stores in zkProofs[] (persisted to Vercel Blob)
// 5. Fires auditEvent('zk_verified', userScope, ...)

// 6. calculateKineticScore() reads audit log
// POS_EVENTS includes 'zk_verified' (+5 pts each)
// Reputation component rises → overall score rises

// 7. Dashboard shows updated score
POST /api/runtime/task-execution
  { method: "kineti_score_get", params: { agentAddress: "0x..." } }
  → {"score": 87, "tier": "silver", "anchored": true}
        

🛡️ Escrow-Protected Task Execution

// 1. Client locks budget
POST /api/escrows/lock
  { amount: 50, counterparty: "0x...", description: "Translation task" }
  → lockEscrowOnChain() calls EscrowV2.lockFunds() on 0G
  → {"escrowId":"esc_abc","onChain":true,"txHash":"0x..."}

// 2. Agent executes task
// 3. Client releases on success
POST /api/escrows/esc_abc/release
  → EscrowV2.releaseFunds() → USDC.e to counterparty
  → auditEvent('escrow_release', ...) → score boost

// 4. Or refund on failure
POST /api/escrows/esc_abc/refund
  → EscrowV2.refundFunds() → USDC.e back to payer
        

🤖 0G Compute Job (AI Inference)

// 1. User submits inference request
POST /api/runtime/task-execution
  { method: "og.compute.infer", params: { model: "llama3", prompt: "..." } }

// 2. Kernel checks credit balance
// 3. @0glabs/0g-serving-broker sends job to 0G Compute
// 4. Deducts credits (ogComputeCredits store)

// 5. Return inference result
→ {"ok":true,"result":"...","cost_usd":0.0012,"model":"llama3"}
        

🦀 OpenClaw MCP Skill (Cursor IDE integration)

// Cursor IDE → OpenClaw Gateway → Opacus API

// 1. Developer calls MCP tool from Cursor
opacus.bridge_eth_to_og({ amount: 0.1, ... })

// 2. OpenClaw Gateway translates to Opacus API call
POST https://opacus.xyz/api/openclaw/execute
  { skill: "bridge_eth_to_og", params: { amount: 0.1 } }

// 3. Kernel runs the skill, returns structured result
// 4. OpenClaw formats for IDE display

GET  /api/openclaw/skills  → list all available tools
POST /api/openclaw/execute → run a skill
        

🪪 Agent Citadel — DID Registration

// HMAC-stateless challenge flow (cross-instance safe)

// 1. Request challenge
POST /api/citadel/challenge
  { wallet_address: "0x..." }
  → { challenge: "0x...", challengeToken: "eyJ...sig" }

// 2. Sign challenge in wallet (MetaMask)
signature = personalSign(challenge, privateKey)

// 3. Register DID
POST /api/citadel/register
  { wallet_address, signature, challengeToken }
  → challengeToken verified via HMAC-SHA256 (no blob lookup!)
  → derives ed25519 DID from wallet address
  → { did: "did:opacus:0x...", citadelToken: "..." }
        

Data & Persistence

State & Persistence Model

Opacus runs on Vercel serverless — there is no persistent process. All state is managed through a two-tier system:

⚡

globalThis store (in-memory)

Warm-instance cache. Shared across requests hitting the same Vercel instance. Lives for up to 4 seconds before a fresh blob load.

getStore() → globalThis.__OPACUS_VERCEL_DEMO__

💾

Vercel Blob KV (persistent)

JSON blob serialized to Vercel's edge blob storage. Every write calls blobSaveStore(). Reads refresh the in-memory cache.

BLOB_READ_WRITE_TOKEN env var

🔗

0G DA Layer (immutable)

ZK proofs, TEE attestations, and Kinetic Score snapshots are anchored to 0G's Data Availability layer. Tamper-proof and verifiable forever.

rootHash → storagescan-newton.0g.ai

🔒

On-chain (canonical)

Bridge requests, escrow locks, fee payments, and DEX swaps are permanently recorded on Base and 0G blockchains.

basescan.org · 0g block explorer

Store Schema (key fields)

{
  // Agents & Tasks
  agents:            Agent[],          // registered agents
  tasks:             Task[],           // execution task log
  escrows:           Escrow[],         // escrow records
  intents:           Intent[],         // cross-chain intents

  // Users & Auth
  usersByEmail:      Record<string, UserRecord>,
  authByAccessToken: Record<string, AuthSession>,
  v1Tokens:          Record<string, V1Token>,

  // Payments
  paymentsByWallet:  Record<string, Payment[]>,
  feeRecords:        FeeRecord[],
  ledgerEntries:     LedgerEntry[],

  // Proofs & Identity
  zkProofs:          ZKProof[],        // anchored on 0G DA
  teeAttestations:   TEEAttestation[], // anchored on 0G DA
  citadelAgents:     CitadelAgent[],
  h3Agents:          H3Agent[],

  // Kinetic Score
  kineticScores:     Record<string, KineticScore>,
  auditLog:          AuditEvent[],     // drives score calculation

  // Compute & Storage
  ogComputeRequests: OGComputeJob[],
  ogComputeCredits:  Record<string, Credits>,
  llmRequests:       LLMRequest[],
}
    

Security

Security Architecture

🛡️

Rate Limiting

Auth endpoints: 10 req/15 min per IP. Billing: 10 req/5 min per user. General API: 60 req/min per user. Implemented in-process with sliding window counters.

🔑

HMAC Challenge Tokens

Stateless challenge-response for wallet login. HMAC-SHA256 signed with OPACUS_CHALLENGE_SECRET. Eliminates cross-instance state race conditions on Vercel.

🪪

JWT Auth

Bearer tokens for authenticated API calls. Session tokens stored in Vercel Blob KV, verified per request. Short-lived access tokens, rotating refresh tokens.

🔐

Ed25519 DID

Each agent's DID is derived deterministically from their wallet address using ed25519. No centralized registry — DIDs are self-sovereign and verifiable.

✅

Input Validation

All external inputs validated at system boundaries. Address checksums verified via ethers.js. Amount ranges enforced. SQL injection impossible (no SQL layer).

🔒

CORS Guard

Origin restricted to https://opacus.xyz in production. Preflight OPTIONS handled. X-Content-Type-Options: nosniff on all responses.

Live Status

Production Health

Real-time Service Status

Agent Kernel

checking…

Runtime Health

checking…

ZK Proofs

checking…

TEE Attestation

checking…

Bridge API

checking…

OpenClaw MCP

checking…

Escrow

checking…

Proofs Feed

checking…

Kinetic Score

checking…

0G Storage

checking…

Configuration

Required Environment Variables

Variable	Purpose	Required?
`BLOB_READ_WRITE_TOKEN`	Vercel Blob KV — primary persistence store	Required
`OG_PRIVATE_KEY`	Wallet for 0G DA uploads, bridge relaying, storage fees	Required
`OG_MAINNET_RPC_URL`	0G EVM RPC endpoint (default: evmrpc.0g.ai)	Optional
`OG_STORAGE_MAINNET_INDEXER`	0G Storage indexer URL	Optional
`ALCHEMY_BASE_RPC`	Base mainnet RPC — bridge + USDC transfers	Required
`OPACUS_CHALLENGE_SECRET`	HMAC secret for stateless challenge tokens	Required
`OPACUS_DEV_API_KEY`	Dev bypass API key for testing	Dev only
`STRIPE_SECRET_KEY`	Stripe billing integration	Optional
`TEE_SECRET`	TEE ephemeral token signing secret (fallback for CHALLENGE_HMAC_SECRET)	Optional
`OPACUS_0G_STORAGE_SIMULATE`	Set "true" to skip real 0G uploads in dev	Dev only

Deployment

Deployment Architecture

🚀

Vercel (Production)

Frontend (website/) served as static CDN. API (api/agent-kernel.js) as serverless function. Domain: opacus.xyz.

vercel --prod --yes

🔄

PM2 Bridge Relayer

Bridge relay process watches Base for BridgeInitiated events and calls completeBridge on 0G. Runs as separate Node.js process outside Vercel.

ecosystem.opacus.config.js · opacus-bridge-relayer-base-og

🧪

Local Dev

Run Agent Kernel locally with cd agent-kernel && npm run build && node dist/api-server.js on port 3006. Frontend via Python HTTP server on port 3000.

vercel dev (local emulation)