System Architecture

Heron is a vertically-integrated stack: consumer UI → Python backend (keeper + API) → on-chain programs → DeFi venues.

Overview

┌─────────────────────────────────────────────────────────────────────┐
│  Consumer Wallet UI (Next.js)                                        │
│  ├── Onboarding: Pools → Deposit → Mandate + Sign                   │
│  ├── Dashboard: Assets | Markets | Agent | Mandate | Pay.sh          │
│  └── Pay.sh tab: create wallet, fund USDC, toggle data services      │
└──────────────────────────┬──────────────────────────────────────────┘
                           │ REST API
┌──────────────────────────▼──────────────────────────────────────────┐
│  Python Backend (FastAPI)                                            │
│  ├── Keeper scheduler: 5-min decision cycles per vault               │
│  ├── Net-Edge gate: strike only when edge > costs                    │
│  ├── pay.sh integration: x402 purchases via Vybe gateway             │
│  ├── Pay.sh wallet: keypairs in GCP Secret Manager                   │
│  └── VDL: hash-chained decision ledger                               │
└──────────────────────────┬──────────────────────────────────────────┘
                           │ RPC / JSON-RPC
┌──────────────────────────▼──────────────────────────────────────────┐
│  On-chain Programs                                                   │
│  ├── Solana: heron-vault (Anchor) → Solend CPI                      │
│  ├── Arc: HeronVault.sol → Meridian                                  │
│  └── GIWA: HeronVault.sol → GiwaLend                                 │
└──────────────────────────┬──────────────────────────────────────────┘
                           │ CPI / External call
┌──────────────────────────▼──────────────────────────────────────────┐
│  DeFi Venues                                                         │
│  ├── Solend (devnet wSOL, ~1.27% APY)                                │
│  ├── Meridian (Arc testnet USDC)                                     │
│  └── GiwaLend (GIWA Sepolia WETH)                                    │
└─────────────────────────────────────────────────────────────────────┘

Data Flow

Deposit → Allocation

User signs deposit tx (wallet UI)
  → Assets land in vault (on-chain, user-owned PDA/contract)
    → Keeper detects idle balance on next 5-min cycle
      → Agent buys market data (pay.sh x402)
        → Net-Edge gate evaluates: edge > costs?
          → If yes: execute allocation (Merkle-verified, cap-checked)
          → If no: stand still, record reason in VDL

Withdrawal

User requests withdraw (wallet UI)
  → Vault checks: enough idle balance?
    → If yes: transfer immediately
    → If no: deallocate from venue first, then transfer
  → User receives assets — NEVER blocked, even while paused

Repository Structure

packages/
  solana/              Anchor programs (heron-vault, heron-distributor)
  contracts/           Solidity (EVM, for GIWA/Arc chains)
  engine/              TypeScript intelligence layer (chain-agnostic)

app/
  web/                 Next.js consumer wallet UI
  backend/             Python FastAPI (keeper, pay.sh, API)
    heron/             Core modules (swarm, netedge, vdl, paysh_wallet, etc.)
    nitro-enclave/     TEE attestation (AWS Nitro)
    data/              Decision history, pay.sh subscriptions

docs/                  This documentation site (Nextra)

Security Boundaries

Boundary	Enforced by
Vault isolation	Each wallet = own PDA/contract, no shared pools
Allocation scope	Merkle mandate — only pre-authorized venue+instruction triples
Budget limits	Per-action cap, epoch cap, position limit (on-chain)
Executor privilege	Single revocable key — not the owner
Withdrawal	Always allowed — agent/pause cannot block
Kill switch	Owner pauses agent, sentinel lowers caps
TEE (optional)	AWS Nitro Enclave proves code integrity for high-value decisions

Overview Solana (Devnet)