How ivelinweb/unitedstatesofagents works
Project type & purpose
• Full-stack decentralized metaverse dApp (“Network State of AI Agents”)
• On-chain smart contracts for token & network state (Hardhat + Ignition)
• Next.js frontend with Phaser game engine, AI agent orchestration via serverless API
Main components
A. Frontend (Next.js + React + Tailwind + Shadcn)
• UI pages: frontend/src/pages/*
• UI components: frontend/src/components/*
• Game engine: frontend/src/game/* (Phaser scenes + EventBus)
• Web3 provider: frontend/src/components/connection/WagmiProvider.tsx, ConnectWallet.tsx
• Utilities: frontend/src/lib/firebase.ts, wagmiConfig.ts, wagmiContractConfig.ts, formatData.ts
• Static resources: frontend/public/assets, resources/*.tmx
B. API layer (Next.js serverless functions)
• Agent orchestration: frontend/src/pages/api/coinbase-agents/* (roles, actions, agent wrappers, contract bridges)
• Specialized routes: travelling-salesman.ts
• Integrations: OpenAI via LangChain modules embedded in API routes
C. Blockchain network
• Target: Sei EVM Testnet (chainID 1328, plus chains 1114 & 84532 in Ignition)
• JSON-RPC endpoint (https://evm-rpc-testnet.sei-apis.com)
• Explorer (seitrace.com)
D. Smart contracts (Solidity)
• Modules: NetworkStateModule, USATokenModule
• Config & scripts: contract/hardhat.config.js, contract/scripts/*.js
• Artifacts & builds: contract/artifacts/*, contract/ignition/deployments/*
• Tests: contract/test/*.js
E. External services
• OpenAI API (via LangChain) for agent intelligence
• Firebase (user data / session)
• Coinbase-agents off-chain SDK for tokenSwap & sentiment analysis
Relationships & data flows
• User interacts with Next.js UI → requests wallet connection → WagmiProvider injects Web3 → user signs transactions
• Frontend dispatches contract calls via Wagmi/Viem → JSON-RPC → Smart Contracts on chain → events & state updates
• Phaser Game scenes emit/consume events via EventBus → route through UI/Web3 for on-chain interactions
• UI/API functions call Next.js serverless endpoints → orchestrate agent logic (LangChain/OpenAI + contract read/writes) → return results to UI
• Deployment pipeline (Hardhat + Ignition) → generates artifacts & deployed_addresses → consumed by frontend’s contract.ts adapters
Architectural patterns & design principles
• Layered architecture:
• Presentation (Next.js UI & Phaser)
• Application (API routes & agent services)
• Blockchain (Smart Contracts)
• Data/External (Firebase, OpenAI, RPC Node)
• Modular smart contracts for composability
• Serverless functions as micro-services for agent orchestration
• Event-driven game loop (Phaser EventBus)