System Architecture

Agent Guardrails is a three-tier system: an on-chain Solana program enforces policies at the instruction level, an off-chain server runs a monitoring pipeline with AI-powered anomaly detection, and a Next.js dashboard provides real-time visibility into agent activity. Every agent transaction flows through all three tiers before it is considered settled.

System Topology

The following diagram shows the full path of an agent transaction from initiation to dashboard display.

Agent (session key)
  -> guarded_execute (on-chain validation)
  -> CPI to target program (Jupiter, Marinade, etc.)
  -> emit event
  -> Helius webhook
  -> Server ingestion pipeline
  -> Prefilter (cheap statistical checks)
  -> Guardian Agent judge (LLM analysis)
  -> Verdict (allow / flag / pause)
  -> Executor (pause_agent on-chain if needed)
  -> SSE push to dashboard
  -> Live incident timeline

On-Chain Components

The Anchor program defines two primary PDAs that govern agent behavior:

• PermissionPolicy PDA — seeds: ["policy", owner, agent]. Stores the program allow-list, per-transaction cap, daily budget, session expiry, and pause state. Funds deposited by the owner live in this PDA — the agent keypair never holds SOL directly.
• SpendTracker PDA — seeds: ["tracker", policy]. Tracks rolling spend totals, transaction counts, and the last-reset timestamp. The guarded_execute instruction checks both PDAs before forwarding the CPI to the target program.

This design means the agent keypair is only an authorized signer, not a fund holder. Even if the agent's private key is fully compromised, the attacker cannot transfer funds without going through guarded_execute, which enforces all policy constraints.

Off-Chain Components

The server is an Express application that runs the monitoring pipeline and exposes a REST API for the dashboard.

• Express Server— handles API routes for authentication (SIWS), agent CRUD, activity queries, and incident management. Also serves the SSE endpoint at GET /api/events for real-time dashboard updates.
• Worker Pipeline— a 5-stage pipeline (Ingest, Prefilter, Judge, Executor, Reporter) processes every webhook event. Stages run in sequence per transaction but the pipeline handles concurrent transactions.
• Neon Postgres (via Prisma)— stores transaction history, verdicts, incidents, and full postmortem reports. The dashboard queries this data through the server's REST API.
• Guardian Agent— the AI judge in the pipeline. It evaluates flagged transactions on the hot path (verdict in milliseconds) and generates async postmortem reports for incidents. Uses structured JSON output for deterministic verdict parsing.

Frontend

The dashboard is a Next.js 14 application using the App Router. It is frontend-only — no API routes, no direct database access.

• TanStack Query v5— manages all server state with 30-second stale times. SSE events update the cache directly via setQueryData to avoid unnecessary refetches.
• Zustand— handles client-side UI state such as sidebar open/close, filter selections, and active tabs.
• SSE (Server-Sent Events) — the useSSE hook opens an EventSourceconnection to the server's GET /api/events endpoint. Events carry full payloads and are inserted directly into the TanStack cache.
• Wallet Adapter— supports Phantom, Solflare, and Backpack via @solana/wallet-adapter-react.

Transaction Lifecycle

Every agent transaction follows this 8-step lifecycle from request to dashboard display:

1. The agent submits a transaction calling guarded_execute with the target program, instruction data, and transfer amount.
2. The on-chain program validates the agent's session key, checks the policy is active (not paused), verifies the target program is in the allow-list, and confirms the amount is within per-transaction and daily budget limits.
3. If all checks pass, the program performs a CPI to the target program and emits a GuardedExecute event with transaction details.
4. Helius detects the event via its webhook configuration and POSTs the parsed transaction data to the server's /webhook endpoint.
5. The server's Ingest stage parses the webhook payload, creates a GuardedTxn database row, and emits a new_transaction SSE event.
6. The Prefilter stage runs 13 statistical checks. If no signals fire, the transaction is auto-allowed. Otherwise, it is forwarded to the Guardian Agent judge.
7. The Guardian Agent evaluates the transaction context and returns a structured verdict (ALLOW, FLAG, or PAUSE) with confidence and reasoning. If PAUSE, the Executor stage signs and submits a pause_agent instruction on-chain.
8. The dashboard receives SSE events (verdict, agent_paused, report_ready) and updates the UI in real time — activity feeds, spend gauges, and incident timelines all reflect the latest state.

Sponsor Integrations

SDK Sync

The sdk/ directory at the repository root is the sole source of truth for the TypeScript client and Anchor IDL. Two consumers maintain local copies:

• server/src/sdk/— used by the Express server for on-chain interactions
• dashboard/lib/sdk/— used by the Next.js dashboard for wallet transactions

Running bash scripts/sync-sdk.sh copies the latest SDK to both consumers. A pre-commit hook automatically runs the sync whenever files in sdk/ or program/ are staged, and CI fails if the copies are out of sync.