Stellar Agent Guard — Dashboard

Client-side operator console for Stellar Agent Guard: deploy smart accounts, configure spending guardrails, monitor live telemetry, and trigger emergency freezes.

An autonomous agent holding a wallet has a single point of failure: one prompt-injection or one buggy loop can drain it. Stellar Agent Guard makes that impossible on-chain — the agent's funds stay in its own smart account, and every transaction the account must authorize is intercepted by the contract's __check_auth and rejected pre-broadcast unless it satisfies the operator's installed policy: per-transaction spend caps, a rolling-window spend limit, recipient/asset allowlists, protocol allowlists, a pause switch, and a dead-man switch. This dashboard provides the operator's command console: a pure client-side Next.js interface for Freighter wallets to inspect guard status, deploy and configure account-level spending policies via a no-code form, view live event telemetry, and execute immediate panic-button freezes confirmed directly from the contract.

Status: Phase 3 built, with Phase 2 publish status honestly disclosed. Pure consumer of stellar-agent-guard-sdk and Soroban RPC. Holds no secrets and has no server component: every write is signed by the operator's Freighter wallet and broadcast directly to Soroban RPC. Consumes the SDK as a vendored package tarball matching merged Phase 2 main pending registry publish authorization.

Phase 2 Exit Status & Dependency Disclosure

Phase 2 exit criterion	State
SDK published to npm	met — npm view stellar-agent-guard-sdk returns version 0.1.0
CI green on main	met — merged and CI green on main (GitHub Actions run 35063436332 passed)
Real integration tests against testnet	met — tests/fixtures/integration-evidence.md in SDK repo, 5/5 live
Phase 2 merged	met — PR #2 merged into main (commit 897708a)

What this means in practice: The SDK publish criterion is satisfied. Everything claimed about Phase 1 and Phase 3 — the artifact deployed, the policy installed, the freeze confirmed — is proven against real public testnet deployments.

$ npm view stellar-agent-guard-sdk

stellar-agent-guard-sdk@0.1.0 | MIT | deps: 1 | versions: 1
Integration bridge between AI agent frameworks and stellar-agent-guard smart accounts: pre-flight policy interception, agent-auth transaction signing, cost pre-checks, and on-chain event telemetry. Full recipient/amount enforcement — spend caps, allowlist

🎯 What makes this different

Enforcement happens inside the account itself, via Soroban's native Custom Account Abstraction — not in a wrapper contract in front of funds, and not in an off-chain service.

• Zero-backend client security: The dashboard contains no backend server, no database, and no API routes handling private keys. Every transaction is constructed in the operator's browser, signed via their own Freighter wallet, and broadcast directly to Soroban RPC.
• On-chain bytecode verification: When deploying a new guard account, the dashboard fetches the contract bytecode directly off the testnet ledger, verifies its SHA-256 hash against the pinned Phase 1 artifact (f47919...), predicts the contract address pre-signing, and re-reads the deployed contract to confirm execution integrity.
• Explicit dual-freeze semantics: The console clearly distinguishes between an admin freeze (operator panic button, admin_frozen = true) and a dead-man-switch freeze (agent missed heartbeat grace window, derived from last_heartbeat), avoiding operator confusion during emergency triage.
• No mock state: Every policy field, balance, and status indicator is read live from Soroban RPC with discrete per-read error reporting. A failed RPC call renders an explicit error — never a silent zero that looks like an empty policy.

⚠️ Disclaimer: This is unaudited security tooling that gates real fund access. Do not deploy to mainnet without an independent audit. See the contracts repo's SECURITY.md.

What it does

• No-code guardrail configurator (/configure): Interactive form for defining spending policies without writing code: per-transaction cap, rolling-window cap and length, asset allowlists, recipient allowlists, protocol allowlists, active execution windows, pause state, and dead-man switch grace periods. Validates inputs locally before prompting Freighter, encodes via SDK policyToScVal, and executes set_policy.
• Artifact-verified guard deployment: Deploys fresh guard accounts from verified on-chain WASM bytecode with cryptographic address prediction.
• Emergency panic button (PanicPanel): Two-step confirmation modal with wallet-signed freeze() execution, followed by a mandatory on-chain re-read of status() confirming admin_frozen = true before updating UI state. Provides matching wallet-signed unfreeze() reversal.
• Live event telemetry feed (TelemetryFeed): Cursor-based polling of event_auth_checked topics from Soroban RPC, decoding contract outcomes and reason codes using the SDK's verified vocabulary.

Quick Start

Installation

git clone https://github.com/aigbagbobila/stellar-agent-guard-dashboard.git
cd stellar-agent-guard-dashboard
npm ci
npm run dev

Open http://localhost:3000 in a browser with the Freighter wallet extension installed and switched to Testnet.

Verification and Development

npm run typecheck    # tsc --noEmit
npm run lint         # eslint
npm test             # unit tests (31/31 passing)
npm run build        # Next.js production build
npm run inspect      # read-only dump of an instance's state

Screens & Actions Reference

Screens

• / (Console Overview): Displays connected wallet, active guard address, current balance, policy parameters summary, dead-man switch countdown, live telemetry event stream, and the emergency panic button.
• /configure (Policy Configurator & Deployment):
  • Deploy fresh guard accounts from verified on-chain WASM bytecode.
  • Configure spending policy parameters with real-time validation.
  • Sign and submit set_policy transactions.

Key Components & Actions

• DeployPanel: Fetches bytecode, verifies SHA-256 hash (f47919...), predicts custom account address, prompts Freighter signature, and initializes admin + agent keys.
• PolicyForm: Real-time form validation, encoding via SDK policyToScVal, Freighter signing, and transaction broadcast.
• PanicPanel: Emergency freeze workflow:
  • Prompts explicit operator confirmation modal.
  • Submits wallet-signed freeze() transaction.
  • Re-reads contract status() to verify admin_frozen = true.
  • Provides wallet-signed unfreeze() to restore normal operations.
• TelemetryFeed: Cursor-based polling of event_auth_checked topics from Soroban RPC, decoding contract outcomes and reason codes.
• WalletBar: Displays Freighter connection status, address, and network validation.

Architecture

Stellar Agent Guard operates across three dedicated repositories:

┌─────────────────────────────────────────────────────────────────────────┐
│                      Operator (Browser / Freighter)                     │
│                                     │                                   │
│                                     ▼                                   │
│              stellar-agent-guard-dashboard (Next.js / UI)               │
└─────────────────────────────────────┬───────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                   AI Agent Runtime (LangChain / ElizaOS)                │
│                                     │                                   │
│                                     ▼                                   │
│                stellar-agent-guard-sdk (TypeScript / RPC)               │
│               • Pre-flight policy check  • Cost pre-checks              │
│               • Agent-auth tx signing    • Event telemetry              │
└─────────────────────────────────────┬───────────────────────────────────┘
                                      │
                                      ▼ Soroban RPC
┌─────────────────────────────────────────────────────────────────────────┐
│               stellar-agent-guard-contracts (Soroban / Rust)             │
│            • CustomAccount interface (`__check_auth`)                   │
│            • Spend caps, rolling window, allowlists, dead-man switch    │
└─────────────────────────────────────────────────────────────────────────┘

Repository	Role	Documentation
stellar-agent-guard-contracts	Soroban smart contracts implementing Custom Account Abstraction and spending policy firewall	GitBook Docs
stellar-agent-guard-sdk	TypeScript SDK for pre-flight interception, simulation pricing, and AI agent framework integration	GitHub
stellar-agent-guard-dashboard (this repo)	Client-side operator dashboard for policy deployment, inspection, and emergency panic-button freeze	GitHub

✅ Verified against live testnet

The dashboard core logic (lib/guard/*) was proven against live Stellar testnet via scripts/prove-phase3.ts using the identical module pipeline that powers the UI:

Step	Result	Evidence
Pinned bytecode verification	Hash matches f47919... (39673 bytes)	Off-chain ledger byte check
Custom account deploy	Deployed to CC6VDBH5M473O4XUPD5GNRVIPB6CJ4U6IZCITF7XLKNLMWZPP3U5BMTK	Tx bcd8eac5…
initialize(admin, agent)	Registered keys on custom account	Tx bf597dc9…
set_policy via form path	Installed initial policy rules	Tx 8d45d22f…
Unfrozen transfer	Allowed	Tx fe1f5e48…
Panic button: freeze()	Frozen	Tx 0d57cd1c…
Status re-read	admin_frozen = true	Contract read confirmation
Frozen transfer attempt	Blocked with reason admin_frozen	Pre-broadcast refusal, 0 fees
Reversal: unfreeze()	Unfrozen	Tx 33929a97…
Status re-read	admin_frozen = false	Contract read confirmation
Retried transfer	Allowed	Tx 503f649e…

Full proof artifact recorded in tests/fixtures/phase3-proof.json and tests/fixtures/README.md.

Honest limitations

• Freighter wallet dependency: Operator write actions require an active Freighter browser extension connected to Stellar Testnet; no programmatic secret keys are held or supported.
• Client-side static deployment: Designed as a pure client-side application (compatible with Vercel or any static host); does not maintain a persistent server database.
• Enforcement boundary for arbitrary calls: Full amount/recipient limits apply natively to SAC token transfers. Arbitrary Soroban contract calls are gated by protocol/function allowlists, active execution window, pause, and dead-man switches; fine-grained amount controls for non-SAC calls are tracked as v2.

Enforcement scope — read this before relying on the caps

Full recipient/amount enforcement — spend caps, allowlists, per-transaction limits — is native and automatic for SAC token transfers (transfer/transfer_from), since these are the calls whose arguments the Soroban auth context exposes for inspection. For other Soroban contract calls made by the guarded account (arbitrary DEX/lending/protocol calls), the policy engine still enforces window and pause state, but per-call amount/recipient limits are not yet enforced — extending fine-grained enforcement to arbitrary calls is tracked as a v2 item, not implied as already covered.

This boundary is an inherent property of the platform (the auth context does not expose arbitrary call arguments generically), not a gap this project hides or overclaims. The classification that produces this boundary (AssetTransfer vs Protocol vs Unknown default-deny) is spelled out in SPEC §6.

Maintainers

Name	GitHub	Telegram
Hybrid	@aigbagbobila	@aigbagbobila

Socials

• Telegram
• Discord

Contact

• GitHub issues: https://github.com/aigbagbobila/stellar-agent-guard-dashboard/issues
• Maintainer (GitHub): @aigbagbobila
• Security disclosures: see SECURITY.md (Telegram, the Stellar ecosystem norm)

License

Licensed under MIT.

Contributing

See CONTRIBUTING.md for details on coding standards, PR process, and project structure — including the strict one-commit-per-logical-unit rule.

Looking for something to work on? The issue backlog holds scoped issues with Summary / Acceptance Criteria / Tech Stack — good first tasks for the Drips Stellar Wave contributor sprints.