Stellar Agent Guard

Appearance

Contracts — Overview ​

The stellar-agent-guard-contracts repository implements a non-custodial, account-level spending firewall for autonomous AI agents on the Stellar network.

🎯 What it Does ​

An autonomous AI agent holding a private key has a single point of failure: one prompt injection attack or one buggy loop can drain its wallet.

Stellar Agent Guard fixes this 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 entrypoint. The transaction is rejected pre-broadcast unless it satisfies the operator's installed policy:

  • Per-transaction spend caps: Maximum amount allowed in a single transfer call.
  • Rolling window spend caps: Time-windowed cap tracking accumulated volume across past calls.
  • Recipient allowlists: Allowed addresses for SAC token transfers (transfer/transfer_from).
  • Protocol allowlists: Contract ID and function-level access control for arbitrary Soroban calls.
  • Pause switch: Operator-triggered administrative freeze (admin_frozen).
  • Dead-man switch: Automated freeze when the agent fails to send a heartbeat() liveness signal before the grace period lapses.

🛡️ Custom Account Abstraction vs Custodial Vaults ​

Enforcement happens inside the account itself, via Soroban's native Custom Account Abstraction (CustomAccountInterface):

  • No Deposit Step: Funds never leave the agent's smart account — there is no deposit vault or top_up function.
  • Zero Admin Fund Authority: The policy admin holds no fund-moving authority. Admin functions update policy and freeze states only.
  • Native Host Interception: The agent's Ed25519 public key is registered at initialize(). Any transaction requiring the agent's authorization is routed by the Soroban host through __check_auth().

📂 Repository Layout ​

  • src/lib.rs — Custom account implementation: __check_auth, policy engine, rolling window, dead-man switch, admin controls.
  • src/integration_tests.rs — 30 unit & integration tests exercising __check_auth Ed25519 signature verification and the complete policy scenario matrix.
  • tools/agent-tx/ — Rust CLI submission helper that signs Soroban auth entries and submits transactions.
  • tests/fixtures/README.md — Live testnet evidence for all 5 enforcement scenarios.
  • SPEC.md — Full architectural specification.