# AgenticPlace Architecture System architecture for AgenticPlace — the ERC-8004 Agent Registry browser with Algorand on-chain verification. ## Overview ``` ┌─────────────────────────────────────────────────────────────────┐ │ agenticplace.pythai.net │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ index │ │ register │ │ minter │ │ agents │ │ │ │ Agent │ │ Agent │ │ aORC NFT │ │ Explorer │ │ │ │ Browser │ │ Registry │ │ Minter │ │ │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ │ │ │ │ ┌────┴──────────────┴──────────────┴──────────────┴─────┐ │ │ │ Wallet Abstraction Layer │ │ │ │ ┌─────────────┐ ┌──────────────┐ │ │ │ │ │ Pera Wallet │ │ Parsec Wallet│ │ │ │ │ │ (mobile/web)│ │ (desktop WS) │ │ │ │ │ └─────────────┘ └──────────────┘ │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ │ ┌───────────────────────────┐ │ │ │ PHP API (Apache) │ │ │ │ stats · agents · scan │ │ │ │ download · allchainft │ │ │ └────────────┬──────────────┘ │ │ │ │ │ ┌────────────┴──────────────┐ │ │ │ MariaDB Database │ │ │ │ 126k agents · 2.5k chains│ │ │ └───────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌───────────┴──────────┐ ┌─────────────┴──────────┐ │ 8004scan.io API │ │ Algorand Mainnet │ │ (ERC-8004 agents) │ │ ┌──────────────────┐ │ │ │ │ │ aORC Minter │ │ └──────────────────────┘ │ │ (ASA creation) │ │ │ ├──────────────────┤ │ │ │ aORC Registry │ │ │ │ (verification) │ │ │ └──────────────────┘ │ └─────────────────────────┘ ``` ## Smart Contracts Two separate contracts with clear separation of concerns: ### aORC Minter (`contracts/aORC-minter.algo.ts`) **Purpose:** Record NFT mints. The user creates their own ASA. **Pattern:** Sender-mints. The user creates the ASA in an atomic group alongside a payment + app call. The contract validates payment and emits an attestation log. | Method | Cost | What it does | |--------|------|-------------| | `mintChainNFT(payment, chainId, chainName)` | 0.001 ALGO | Log chain NFT mint | | `mintAgentNFT(payment, agentId, agentData)` | 0.001 ALGO | Log agent NFT mint | | `mintCustomNFT(payment, data)` | 0.001 ALGO | Log custom NFT mint | | `withdraw(amount, to)` | — | Treasury withdrawal (admin) | | `transferTreasury(newTreasury)` | — | Transfer admin | **State:** `totalMinted` (uint64), `treasury` (Account) **Atomic group (frontend builds):** 1. ASA Create (user is creator → auto-holds, ARC-69 note) 2. Payment to contract (0.001 ALGO) 3. App call to minter contract (logs the event) ### aORC Registry (`contracts/aORC-registry.algo.ts`) **Purpose:** On-chain registry of verified blockchains. Platform reads box state to display the verified chain list. | Method | Cost | What it does | |--------|------|-------------| | `listChain(payment, chainId, connectionData)` | 1 ALGO | Register a chain with connection data | | `verifyChain(payment, chainId)` | 1 ALGO | Verify chain active, increment consensus count | | `batchList(payment, id1, data1, id2, data2)` | 2 ALGO | List two chains at once | | `readChain(chainId)` | free | Read chain box data | | `isListed(chainId)` | free | Check if chain exists | | `getVerifyCount(chainId)` | free | Get verification count | | `getLastVerifiedRound(chainId)` | free | Get last verified round | **State:** `totalChains`, `totalVerifications`, `treasury`, `chains` BoxMap **Box layout** (104-byte header + variable JSON): ``` Offset Size Field 0 8 chainId (uint64) 8 32 lister (address) 40 8 listedRound (uint64) 48 8 verifyCount (uint64) 56 8 lastVerifiedRound (uint64) 64 32 lastVerifier (address) 96 8 lastVerifiedTs (uint64) 104 var connectionData (JSON) ``` **Consensus model:** Each `verifyChain` call increments `verifyCount`. The platform displays chains sorted by verification count — more verifiers = higher confidence. ## Wallet Integration ### Abstraction Layer Both `minter.html` and `register.html` use a common pattern: ```javascript // Detection const parsecStatus = await parsecWallet.isAvailable(); // Connection await connectPera(); // or connectParsec() // Unified signing (works with both) const signed = await signWithWallet([[{ txn, signers: [algoAddr] }]]); ``` ### Pera Wallet (mobile/web) - SDK: `@perawallet/connect@1.5.1` (UMD from unpkg) - Connection: QR code / deep link to Pera mobile app - Signing: `peraWallet.signTransaction(txnGroups)` ### Parsec Wallet (desktop) - SDK: `modules/parsec-connect.js` - Connection: WebSocket to `localhost:9876` - Signing: `parsecWallet.signTransaction(txnGroups, message)` - User approval: Desktop dialog in Parsec Wallet UI - See [PARSEC-CONNECT.md](./PARSEC-CONNECT.md) for full reference ## ARC-69 Data Flow ``` User fills form → buildMetadata() → JSON.stringify → noteBytes │ ASA Create Transaction ←─────────── note: noteBytes ─┘ │ Sign (Pera or Parsec) │ Submit to Algorand │ Indexer picks up → ARC-69 note readable by any explorer ``` ARC-69 metadata structure: ```json { "standard": "arc69", "description": "agenticORacle chain 8453 (Base) verified active", "external_url": "https://agenticplace.pythai.net", "properties": { "type": "chain-verification", "chainId": 8453, "name": "Base", "timestamp": "2026-03-26T...", "connectionData": { "name": "Base", "sym": "BASE", "rpc": [...] } } } ``` ## Database Schema ### agents (115k+ records) | Column | Type | Description | |--------|------|-------------| | agent_id | TEXT PK | e.g. "ethereum_12345" | | token_id | INTEGER | NFT token ID on chain | | chain_id | INTEGER | EVM chain ID | | name | TEXT | Agent name | | description | TEXT | Agent description | | is_verified | BOOLEAN | Verification status | | total_score | INTEGER | Community score | | supported_protocols | TEXT[] | e.g. {Web, MCP} | ### allchains (2,510 records) | Column | Type | Description | |--------|------|-------------| | chain_id | BIGINT PK | EVM chain ID | | name | TEXT | Chain name | | native_currency | JSONB | {name, symbol, decimals} | | rpc_urls | TEXT[] | RPC endpoints | | explorers | JSONB | Block explorer URLs | | native_price | NUMERIC | USD price | | market_cap | NUMERIC | Market cap USD | ## API Endpoints | Endpoint | Method | Description | |----------|--------|-------------| | `/api/stats` | GET | Agent count, chain stats, scan status | | `/api/agents` | GET | Paginated agents (search, filter, sort) | | `/api/scan` | POST | Fetch batch from 8004scan.io | | `/api/download` | GET | Stream full agent list as JSON | | `/api/allchainft` | GET | Blockchain connection registry metadata | | `/api/register-local` | POST | Instant local DB insert after mint | | `/api/confirm` | GET | Poll 8004scan for agent confirmation | | `/api/export` | GET | Export agents/chains as CSV/JSON/MD | | `/api/setup` | GET | Create database schema (once) | | `/api/import` | GET | Bulk import from CSV (once) | Query parameters for `/api/agents`: - `page` — page number (default 1) - `limit` — results per page (default 200) - `q` — search name/description/owner - `chain` — filter by chain_id - `sort` — column to sort (name, token_id, total_score, created_at) - `dir` — sort direction (asc, desc) ## File Structure ``` live/ ├── index.html # Landing page (WebGL, live stats, portals) ├── browse.html # Agent browser (virtual scroll, 126k+) ├── register.html # Agent registration + NFT minting ├── minter.html # aORC NFT minter (chain/agent/custom) ├── agents.html # Agent explorer (alternate view) ├── app.js # Virtual scroll, pagination, scan engine ├── style.css # Glass-morphism design system ├── .htaccess # Apache routing, HTTPS, security headers ├── contracts/ │ ├── aORC-minter.algo.ts # Minting contract (PuyaTS) │ └── aORC-registry.algo.ts # Verification registry (PuyaTS) ├── modules/ │ ├── parsec-connect.js # Parsec Wallet browser SDK │ └── allchainft.ts # Chain connection NFT module ├── api/ │ ├── config.php # DB connection + CORS │ ├── setup.php # Schema creation │ ├── import.php # CSV bulk import │ ├── agents.php # Paginated agent queries │ ├── stats.php # Stats + 8004scan cache │ ├── scan.php # Adaptive auto-scan from 8004scan │ ├── register-local.php # Instant local DB insert after mint │ ├── confirm.php # 8004scan confirmation polling │ ├── download.php # JSON streaming │ ├── export.php # CSV/JSON/MD export │ └── allchainft.php # Chain connection metadata └── data/ ├── agents-export.csv # 115,498 pre-loaded agents └── allchains-export.csv # 2,510 chains with market data ``` ## Deployment See [deployment guide](./docs/deployment.md) for step-by-step hosting setup. **Requirements:** Apache + PHP 7.4+ + MariaDB 10.3+ (or MySQL 5.7+) **Quick deploy:** 1. Upload files to document root 2. Edit `api/config.php` with DB credentials 3. Visit `/api/setup?key=setup-agenticplace-2026` 4. Visit `/api/import?key=setup-agenticplace-2026` 5. Verify at `/api/stats` ## External Dependencies | Service | Purpose | Rate limit | |---------|---------|-----------| | 8004scan.io | ERC-8004 agent data | 10 req/min | | Nodely (mainnet-api.4160.nodely.dev) | Algorand algod | Public tier | | unpkg.com | Pera SDK + algosdk CDN | Public CDN | | localhost:9876 | Parsec Wallet connect | Local only |