Contracts — Architecture

🏛️ Custom Account Abstraction Topology

Host Invocation (e.g. transfer call)
            │
            ▼
Soroban Host Auth Interception
            │
            ▼
┌────────────────────────────────────────────────────────┐
│                   __check_auth()                       │
│  1. Verify Agent Ed25519 Signature                     │
│  2. Evaluate Account State (Admin Frozen / Dead-Man)   │
│  3. Evaluate Policy Decision Matrix over Context       │
└───────────────────────────┬────────────────────────────┘
                            │
              ┌─────────────┴─────────────┐
              ▼                           ▼
        Policy Pass                 Policy Refused
      (Transaction Runs)          (Err #code, Rollback)
                                  Zero network fee spent

---

🔒 Policy Engine Evaluation Order

__check_auth evaluates checks in strict priority order:

1. Host Crypto: Verifies the agent's Ed25519 signature against signature_payload.
2. Account State:
   • admin_frozen == true ──► Blocks with AdminFrozen.
   • dead_man_switch expired (now - last_heartbeat > grace_secs) ──► Blocks with HeartbeatExpired.
   • paused == true ──► Blocks with Paused.
   • Active window inactive (now < start or now > end) ──► Blocks with OutsideActiveWindow.
3. Context Classification:
   • AssetTransfer (transfer/transfer_from on SAC tokens): Enforces per_tx_cap, recipient_allowlist, and window_cap.
   • Protocol (Calls to non-token contracts): Enforces protocol_allowlist and function_allowlist.
   • Unknown: Default-deny refusal with UnknownContract.

---

⏳ Rolling Window Algorithm

The rolling window spend cap uses a bounded circular log in contract storage:

• Stores (timestamp, amount) entries within the duration window (e.g. 60s).
• Prunes expired entries dynamically during pre-flight checks.
• Guarantees exact rolling volume accumulation across transactions without storage underflow or un-pruned state explosion.