Architecture Overview¶

WasiAI is built as a modern Web3 application with a clear separation between frontend, backend, blockchain, and storage layers. This page provides a high-level view of how the system components interact.

System Architecture¶

┌─────────────────────────────────────────────────────────────────────────────┐
│                              WasiAI Platform                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                     FRONTEND (Next.js 14)                            │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐               │   │
│  │  │ Model Catalog │  │ Publish      │  │ User         │               │   │
│  │  │ (Browse/Search)│  │ Wizard       │  │ Dashboard    │               │   │
│  │  └──────────────┘  └──────────────┘  └──────────────┘               │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐               │   │
│  │  │ Model Detail │  │ x402 Inference│  │ License      │               │   │
│  │  │ Page         │  │ Panel        │  │ Manager      │               │   │
│  │  └──────────────┘  └──────────────┘  └──────────────┘               │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    ▼                                        │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                     BACKEND (Next.js API Routes)                     │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐               │   │
│  │  │ /api/inference│  │ /api/models  │  │ /api/ipfs    │               │   │
│  │  │ x402 Gateway │  │ CRUD + Publish│  │ Upload/Proxy │               │   │
│  │  └──────────────┘  └──────────────┘  └──────────────┘               │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐               │   │
│  │  │ /api/indexed │  │ /api/agents  │  │ /api/keys    │               │   │
│  │  │ Cached Data  │  │ ERC-8004     │  │ Protected    │               │   │
│  │  └──────────────┘  └──────────────┘  └──────────────┘               │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                          │                    │                             │
│              ┌───────────┴────────────────────┴───────────┐                │
│              ▼                                            ▼                │
│  ┌─────────────────────────┐              ┌─────────────────────────┐      │
│  │    BLOCKCHAIN           │              │    STORAGE              │      │
│  │    (Avalanche C-Chain)  │              │                         │      │
│  │  ┌─────────────────┐    │              │  ┌─────────────────┐    │      │
│  │  │ MarketplaceV3   │    │              │  │ IPFS (Pinata)   │    │      │
│  │  │ LicenseNFTV2    │    │              │  │ - Metadata      │    │      │
│  │  │ AgentRegistryV2 │    │              │  │ - Artifacts     │    │      │
│  │  │ SplitterFactory │    │              │  │ - Cover Images  │    │      │
│  │  │ ModelSplitter   │    │              │  └─────────────────┘    │      │
│  │  │ Circle USDC     │    │              │  ┌─────────────────┐    │      │
│  │  └─────────────────┘    │              │  │ Neon Postgres   │    │      │
│  │                         │              │  │ - Indexed Cache │    │      │
│  │  ┌─────────────────┐    │              │  │ - Inference Logs│    │      │
│  │  │ x402 Facilitator│    │              │  │ - User Data     │    │      │
│  │  │ (Ultravioleta/  │    │              │  └─────────────────┘    │      │
│  │  │  Thirdweb)      │    │              │                         │      │
│  │  └─────────────────┘    │              │                         │      │
│  └─────────────────────────┘              └─────────────────────────┘      │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Layer Breakdown¶

Frontend Layer¶

The frontend is built with Next.js 14 using the App Router, React 18, and Material UI. Key features:

Component	Purpose
Model Catalog	Browse and search models with filters, infinite scroll
Model Detail Page	View model info, run inference, buy licenses
Publish Wizard	5-step guided flow to publish models
x402 Inference Panel	Pay-per-use interface with wallet signing
License Manager	View and manage owned license NFTs
User Dashboard	Analytics, earnings, and settings

Wallet Integration: RainbowKit + wagmi for traditional wallets, Thirdweb for social login (Google, Apple, Email).

Backend Layer¶

Next.js API routes handle server-side logic:

Endpoint	Purpose
`/api/inference/[modelId]`	x402 payment gateway for AI inference
`/api/models/*`	Model CRUD, drafts, publishing
`/api/ipfs/*`	IPFS upload and proxy
`/api/indexed/*`	Fast queries from cached database
`/api/agents/*`	ERC-8004 agent registration
`/api/keys/*`	Protected content key management

Blockchain Layer¶

Smart contracts on Avalanche C-Chain (Fuji testnet):

Contract	Role
MarketplaceV3	Model registry, license sales, pricing
LicenseNFTV2	ERC-721 license tokens
AgentRegistryV2	ERC-8004 agent identity
SplitterFactory	Creates per-model revenue splitters
ModelSplitter	Distributes payments to seller/creator/marketplace
Circle USDC	Payment token for x402

Storage Layer¶

Storage	Purpose
IPFS (Pinata)	Decentralized storage for metadata, images, artifacts
Neon Postgres	Indexed cache for fast queries, inference history

Data Flow Examples¶

Publishing a Model¶

1. Creator fills Publish Wizard (5 steps)
       │
       ▼
2. Frontend uploads to IPFS via /api/ipfs
   - Cover image → ipfs://Qm...
   - Metadata JSON → ipfs://Qm...
   - Artifacts → ipfs://Qm...
       │
       ▼
3. Frontend calls MarketplaceV3.publishModel()
   - Stores on-chain: name, uri, pricing, royalties
   - Auto-creates ModelSplitter via SplitterFactory
   - Auto-registers Agent via AgentRegistryV2
       │
       ▼
4. Indexer syncs blockchain → Neon Postgres
   - ModelPublished event → models table
   - AgentRegistered event → agents table
       │
       ▼
5. Model appears in catalog

Running Inference (x402)¶

1. User clicks "Run Model" in X402InferencePanel
       │
       ▼
2. Frontend POST /api/inference/{modelId} (no payment)
       │
       ▼
3. Backend returns HTTP 402 + X402PaymentRequirement
   {
     scheme: "exact",
     network: "avalanche-fuji",
     maxAmountRequired: "10000",  // $0.01 USDC
     payTo: "0x...",              // Splitter address
     asset: "0x5425..."           // USDC
   }
       │
       ▼
4. Frontend builds authorization + signs with wallet (EIP-712)
       │
       ▼
5. Frontend POST /api/inference/{modelId} + X-PAYMENT header
       │
       ▼
6. Backend verifies payment via Facilitator
   - Decode base64 payload
   - Validate signature, amount, recipient, time window
   - Call facilitator.settle() → USDC transfer
       │
       ▼
7. Backend executes AI inference (model endpoint)
       │
       ▼
8. Backend returns result + X-PAYMENT-RESPONSE header
   {
     ok: true,
     result: {...},
     payment: { txHash: "0x...", verified: true }
   }

Buying a License¶

1. User clicks "Buy License" on Model Detail Page
       │
       ▼
2. Frontend calls MarketplaceV3.buyLicense()
   - User approves USDC spend
   - Marketplace transfers USDC to Splitter
   - Splitter distributes to seller/creator/marketplace
   - LicenseNFT minted to user
       │
       ▼
3. User receives License NFT (ERC-721)
   - Token ID: unique license identifier
   - Rights: API access, download access
   - Duration: perpetual or subscription period

Technology Choices¶

Why Avalanche?¶

Fast finality: ~1 second confirmation
Low fees: Fractions of a cent per transaction
EVM compatible: Standard Solidity tooling
x402 support: Native integration with Ultravioleta facilitator

Why x402?¶

HTTP native: Works with standard web infrastructure
Gasless for users: Facilitator pays gas
Micropayments: Enables $0.001 transactions
Standard protocol: Interoperable with other x402 services

Why IPFS?¶

Decentralized: No single point of failure
Content-addressed: Immutable references
Cost-effective: Pay once, store forever

Why Neon Postgres?¶

Serverless: Scales automatically
Fast queries: Sub-millisecond latency
Familiar: Standard SQL interface

Security Model¶

Smart Contract Security¶

Ownable2Step: Two-step ownership transfer
ReentrancyGuard: Protection against reentrancy attacks
Pausable: Emergency stop functionality
Timelocks: 24-hour delay for critical changes

Payment Security¶

Nonce tracking: Replay protection
Time windows: Payments expire after 60 seconds
Amount validation: Exact payment required
Recipient validation: Payment to correct address

API Security¶

Rate limiting: 10 requests per minute per IP
Input validation: Sanitized inputs
CORS: Restricted origins

Next Steps¶

x402 Payment Flow: Deep dive into payments
Smart Contracts Overview: Contract architecture
Frontend Architecture: UI components