SDK — Architecture

🚀 Key Architectural Modules

                        Agent Action Request
                                  │
                                  ▼
                    ┌───────────────────────────┐
                    │   PreFlightInterceptor    │
                    └─────────────┬─────────────┘
                                  │
                  Simulate Call via Soroban RPC
                                  │
                                  ▼
                    ┌───────────────────────────┐
                    │      CostPreChecker       │
                    └─────────────┬─────────────┘
                                  │
                 Check Fee Ceilings & Enforce Policy
                                  │
             ┌────────────────────┴────────────────────┐
             ▼                                         ▼
    Decision: Admissible                       Decision: Blocked
   (Assemble & Broadcast)                  (Emit Telemetry & Halt)

---

🔍 PreFlightInterceptor

Simulates contract invocations using server.simulateTransaction():

1. Decodes diagnostic events from simulation results.
2. If event_auth_checked contains blocked, maps the contract reason code (e.g. PerTxCapExceeded, AdminFrozen) into a human-readable GuardBlockedError.
3. If simulation succeeds, returns an AdmissibleDecision with estimated inclusion and resource fees.

---

💰 CostPreChecker

Computes transaction execution cost prior to broadcast:

• Reads minResourceFee and storage footprint size.
• Calculates footprint bump fees required for custom account __check_auth storage reads.
• Asserts resource total against optional operator fee ceilings (maxResourceFeeStroops).

---

📡 GuardTelemetryListener

Tails guard events using getEvents():

• Extracts uncommitted diagnostic events (refusals) and committed ledger events (initialized, policy_set, frozen, unfrozen).
• Normalizes topics and parses ScVal payloads into TypeScript GuardEvent pages.