Architecture Overview

System Architecture

Agentic Wallet is built as a gateway + multi-service execution system where AI agents express intents, and the platform handles validation, policy enforcement, transaction construction, signing, and confirmation.

Core Principle

Agents do not directly hold private keys and do not submit raw RPC transactions by themselves. All execution flows through controlled boundaries with policy gates and signing isolation.

High-Level Flow

Agent / CLI / SDK / MCP
          |
          v
   API Gateway (auth/scope/rate-limit, stable error envelope)
          |
          v
Transaction Engine
  -> build/simulate
  -> policy_eval / approval_gate
  -> sign boundary (wallet-engine)
  -> submit / confirm
  -> proof + audit + metrics
          |
          v
Solana RPC / Protocol Programs

System Diagram

Entry Layer

API Gateway (Port 3000)
Authentication & Rate Limiting
Route-based scoping
Response normalization

Execution Layer

Transaction Engine (Port 3006)
Wallet Engine (Port 3002)
Policy Engine (Port 3003)
Agent Runtime (Port 3004)

Protocol Layer

Protocol Adapters (Port 3005)
7 protocol integrations
Adapter registry pattern
Real Anchor escrow program

Observability Layer

Audit & Observability (Port 3007)
MCP Server (Port 3008)
Execution proofs
Metrics aggregation

Key Architectural Decisions

1. Intent-Based Execution Model

Agents express high-level intents rather than constructing raw transactions:

Agent sends: { type: "swap", protocol: "jupiter", intent: { inputMint, outputMint, amount } }
Platform handles: Quote fetching, transaction building, simulation, policy checks, signing, submission

This creates a security boundary where agents cannot bypass safety controls.

2. Multi-Service Separation of Concerns

Each service has a single responsibility:

Service	Responsibility	Trust Level
`api-gateway`	Auth, routing, rate limiting	Entry point
`wallet-engine`	Key custody, signing	Highest trust
`policy-engine`	Policy evaluation	Safety critical
`transaction-engine`	Orchestration, simulation	Execution coordinator
`agent-runtime`	Agent lifecycle, capabilities	Agent governance
`protocol-adapters`	Protocol-specific logic	Protocol boundary
`audit-observability`	Audit stream, metrics	Forensics
`mcp-server`	MCP tools, agent integration	Agent interface

3. Fail-Secure Policy Gates

Build Transaction

Construct unsigned transaction using protocol adapters

Simulate

Run simulation against Solana RPC to validate execution

Policy Evaluation

Evaluate against wallet policies and risk controls

Approval Gate (if needed)

Pause execution for manual approval when policy requires it

Sign

Only after all checks pass, wallet-engine signs the transaction

Submit & Confirm

Submit to RPC and wait for confirmation

Generate Proof

Create deterministic execution proof with hashes

If any step fails, execution stops and no transaction is signed or submitted.

4. Pluggable Signer Backends

The wallet-engine supports multiple key custody strategies:

encrypted-file: AES-256-GCM encrypted keys on disk (development)
memory: Ephemeral in-memory keys (testing)
kms: Centralized key management service integration
hsm: Hardware security module integration
mpc: Multi-party computation with threshold signatures

All backends implement the same KeyProvider interface, allowing custody strategy to be swapped via environment configuration.

5. Durable Outbox Pattern

The transaction-engine uses a durable outbox queue with:

SQLite-backed persistence
Lease/retry semantics with configurable max attempts
Restart recovery drain to handle process crashes
Idempotency keys to prevent duplicate execution

This ensures transactions survive service restarts and transient failures.

6. RPC Failover Pool

Solana RPC operations use a health-scored pool with:

Multiple endpoint URLs (configurable via SOLANA_RPC_POOL_URLS)
Health probing with score decay on failures
Automatic failover to healthy endpoints
Adaptive priority fee and compute budget tuning

This provides resilience against single RPC endpoint failures.

Technology Stack

Runtime & Framework

Node.js >= 20
TypeScript for type safety
Hono for HTTP services
Zod for schema validation

Blockchain

Solana Web3.js for RPC interactions
SPL Token for token operations
Anchor for on-chain program development (escrow)

Storage

SQLite for durable state (wallets, policies, transactions, agents, outbox)
JSON file fallback for simple stores

Cryptography

crypto (Node.js) for AES-256-GCM encryption
scrypt for key derivation
Ed25519 signatures (Solana keypairs)

Data Flow Example: Simple Transfer

Scalability & Deployment

Current State (Prototype)

Single-node deployment: All services run on one machine
SQLite persistence: Suitable for prototype and small-scale deployments
In-process communication: Services communicate via HTTP on localhost

Production Path

Horizontal Scaling

Replace SQLite with PostgreSQL
Introduce distributed queue (Redis, RabbitMQ)
Load balance API Gateway instances
Scale execution services independently

High Availability

Multi-region RPC pool
Replicated database with failover
Circuit breakers for external APIs
Health checks and auto-recovery

Security Posture

Agent intent is untrusted until it survives validation, risk evaluation, policy checks, and signing-boundary controls.

Defense in Depth

API Gateway: Authentication, authorization, rate limiting
Schema Validation: Zod schemas reject malformed inputs at service edges
Protocol Risk: Protocol-specific risk controls (slippage, pool concentration, oracle checks)
Policy Engine: User-defined rules (spending limits, allowlists, rate limits)
Simulation: Pre-execution validation against Solana RPC
Signing Boundary: Only wallet-engine can sign, agents never see keys
Delta Guard: Post-execution balance verification
Audit Stream: Immutable audit log with execution proofs

See Trust Boundaries for detailed security architecture.

Next Steps

Services Deep Dive

Detailed breakdown of each service’s responsibilities and APIs

Execution Flow

Transaction and escrow lifecycle with state machines

Trust Boundaries

Security model and control boundaries

API Reference

Complete API documentation for all services

Getting Started

Architecture

Core Concepts

Operations

Security

Integration

System Architecture

Core Principle

High-Level Flow

System Diagram

Entry Layer

Execution Layer

Protocol Layer

Observability Layer

Key Architectural Decisions

1. Intent-Based Execution Model

2. Multi-Service Separation of Concerns

3. Fail-Secure Policy Gates

4. Pluggable Signer Backends

5. Durable Outbox Pattern

6. RPC Failover Pool

Technology Stack

Data Flow Example: Simple Transfer

Scalability & Deployment

Current State (Prototype)

Production Path

Horizontal Scaling

High Availability

Security Posture

Defense in Depth

Next Steps

Services Deep Dive

Execution Flow

Trust Boundaries

API Reference

Build docs developers (and LLMs) love

Getting Started

Architecture

Core Concepts

Operations

Security

Integration

​System Architecture

​Core Principle

​High-Level Flow

​System Diagram

Entry Layer

Execution Layer

Protocol Layer

Observability Layer

​Key Architectural Decisions

​1. Intent-Based Execution Model

​2. Multi-Service Separation of Concerns

​3. Fail-Secure Policy Gates

​4. Pluggable Signer Backends

​5. Durable Outbox Pattern

​6. RPC Failover Pool

​Technology Stack

​Data Flow Example: Simple Transfer

​Scalability & Deployment

​Current State (Prototype)

​Production Path

Horizontal Scaling

High Availability

​Security Posture

​Defense in Depth

​Next Steps

Services Deep Dive

Execution Flow

Trust Boundaries

API Reference

Build docs developers (and LLMs) love

System Architecture

Core Principle

High-Level Flow

System Diagram

Key Architectural Decisions

1. Intent-Based Execution Model

2. Multi-Service Separation of Concerns

3. Fail-Secure Policy Gates

4. Pluggable Signer Backends

5. Durable Outbox Pattern

6. RPC Failover Pool

Technology Stack

Data Flow Example: Simple Transfer

Scalability & Deployment

Current State (Prototype)

Production Path

Security Posture

Defense in Depth

Next Steps