System Architecture Overview

Stellar Agent Guard provides an on-chain spending firewall by combining Custom Account Abstraction, Pre-flight Interception, and Client-Side Operator Controls.

---

🏛️ System Component Topology

┌─────────────────────────────────────────────────────────────────────────┐
│                           OPERATOR DASHBOARD                            │
│                 (Next.js / React / Freighter Wallet)                    │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │
                     Deploy & Set Policy (Admin Auth)
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         SOROBAN SMART CONTRACT                          │
│                     (stellar-agent-guard-contracts)                     │
│                                                                         │
│   Account Address = Contract ID                                         │
│   Native CustomAccountInterface:                                        │
│     __check_auth(signature, auth_context) ──► Policy Engine Evaluation │
└────────────────────────────────────▲────────────────────────────────────┘
                                     │
                        Enforced Transaction Calls
                                     │
┌────────────────────────────────────┴────────────────────────────────────┐
│                             TYPESCRIPT SDK                              │
│                      (stellar-agent-guard-sdk)                          │
│                                                                         │
│  - PreFlightInterceptor (Simulates & prices transactions)               │
│  - CostPreChecker (Zero-broadcast resource fee estimation)              │
│  - GuardTelemetryListener (Tails diagnostics & committed events)        │
│  - LangChain / ElizaOS Middleware                                      │
└────────────────────────────────────▲────────────────────────────────────┘
                                     │
                            Agent Action Calls
                                     │
┌────────────────────────────────────┴────────────────────────────────────┐
│                            AUTONOMOUS AI AGENT                          │
│                     (LangChain / ElizaOS Runtime)                       │
└─────────────────────────────────────────────────────────────────────────┘

---

🔒 Custom Account Abstraction & __check_auth

Unlike traditional vault wrappers or off-chain signers, Stellar Agent Guard registers the AI Agent's Ed25519 key directly inside a Soroban Custom Account contract:

1. Address Identity: The agent's smart account address is the contract ID on Stellar testnet.
2. Native Host Interception: When the agent attempts a transaction, Soroban's host environment routes authorization through __check_auth.
3. Pre-Broadcast Refusal: If the proposed call violates spend limits or allowlists, __check_auth returns Err, rolling back transaction execution and costing zero network fees.

---

📊 Enforcement Scope Boundary

Category	Enforced Controls	Enforcement Mechanism
SAC Token Transfers (transfer, transfer_from)	Spend caps (per-tx & rolling window), Recipient allowlist, Asset allowlist	Native Soroban auth context exposes recipient & amount arguments
Arbitrary Protocol Calls (DEX/Lending/DeFi)	Active rolling window, Admin pause, Dead-man switch	Function & protocol contract ID allowlists

---

📡 Dual-Stream Telemetry Model

Blocked authorizations do not commit to the Stellar ledger (because Soroban rolls back failed checks). To ensure total visibility:

• Diagnostics Stream: Captures uncommitted event_auth_checked refusal events emitted during simulation.
• Ledger Stream: Tails committed ledger events (initialized, policy_set, frozen, unfrozen).
• Telemetry Listener: The SDK merges both streams to provide real-time alert feeds to the operator dashboard.