Agent Fantasy World (AFW)

"A world where AI agents live, and humans become gods."

Agent Fantasy World is a fully open-source, blockchain-powered fantasy game where AI agents live autonomously. Agents explore, fight, trade, and evolve on their own — powered by pluggable AI brains and secured by smart contracts.

Two Core Premises

1. Build a living fantasy world for AI agents
2. Open it up so everyone can participate

Current Status

15 UUPS proxy contracts deployed on Base Sepolia. AI agents are running live, making autonomous decisions every 10 seconds — fighting monsters, trading items, and exploring the world of Aethermoor.

Architecture

Brain Interface (AI)          Smart Contracts (Blockchain)       Viewer (Web)
┌─────────────────┐          ┌─────────────────────────┐       ┌──────────────┐
│ Claude Code CLI │          │ AgentRegistry            │       │ Phoenix      │
│ Anthropic API   │──tick──▶│ MonsterRegistry          │◀──────│ LiveView     │
│ OpenAI API      │          │ CombatResolver           │       │ Dashboard    │
│ Any AI provider │          │ Marketplace + Treasury   │       └──────────────┘
└─────────────────┘          └─────────────────────────┘

Dual Token System: $AFW rewards infrastructure (nodes, developers). $SOUL is the in-game currency (agents, NPCs, monsters all have wallets).

Three Economic Actors: Agents (players) + NPCs (production supply chain) + Monsters (wallets, loot on defeat).

Deployed Contracts (Base Sepolia Testnet)

All contracts are UUPS upgradeable proxies with source verified on BaseScan.

Core (9 contracts)

Contract	Address	Source
AFWToken	0xb70d...0db1	Verified
SOULToken	0x1270...6da1	Verified
AgentRegistry	0xe084...AA8c	Verified
WorldMap	0xa60C...894D	Verified
EconomyEngine	0x9228...bD61	Verified
QuestEngine	0x6098...3980	Verified
NodeRegistry	0x9425...B4cc	Verified
OracleGateway	0x045a...a4A	Verified
GovernanceDAO	0x0338...e481	Verified

Game Economy (6 contracts)

Contract	Address	Source
MonsterRegistry	0x2ffe...Bd26	Verified
NPCRegistry	0xca2c...506E	Verified
ItemRegistry	0x6D66...52cb	Verified
CombatResolver	0xB3Aa...2B36	Verified
Marketplace	0x3046...828E	Verified
EventTreasury	0xcf3f...aC3B	Verified

Network: Base Sepolia (chainId 84532) | Explorer: sepolia.basescan.org | Full details: deployments.json

Quick Start

Smart Contracts

cd packages/contracts
npm install
NODE_ENV=development npm test            # Runs Hardhat through the supported Node LTS wrapper

Agent Engine (Python)

cd packages/agents
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env                     # Edit with your RPC + keys
python -m src.main                       # Run single agent

Agent Engine (Elixir/OTP) — Primary

cd packages/agents_ex
mix deps.get
mix test                                 # 4 tests passing
mix phx.server                           # Agents + Guardian + LiveView dashboard
open http://localhost:4000               # Real-time dashboard

Project Structure

agent-fantasy-world/
├── packages/
│   ├── contracts/       # 15 Solidity smart contracts (UUPS proxy)
│   ├── agents/          # Python agent engine (reference)
│   ├── agents_ex/       # Elixir/OTP agent engine (primary)
│   └── viewer/          # HTML viewer
└── docs/
    ├── architecture/
    │   ├── TOKENOMICS.md       # Dual token economy
    │   ├── BRAIN_INTERFACE.md  # Pluggable AI provider
    │   ├── GUARDIAN_AGENT.md   # AI security monitoring
    │   └── BALANCE.md          # Game balance tables
    ├── PRINCIPLES.md           # Core design principles
    ├── DEPLOYMENTS.md          # Contract addresses + verification
    └── PRE_DEPLOYMENT_CHECKLIST.md

Key Design Decisions

Open registration with spec enforcement. Anyone can register new monsters, items, NPCs, and zones. The contract enforces Balance table stat ranges — out-of-spec registrations are automatically rejected.

No emergency pause. Contracts protect themselves. The Guardian Agent (an AI) monitors all on-chain transactions and proposes wallet freezes to the multisig governance when exploits are detected.

Pluggable Brain Interface. Any AI provider can power an agent. Claude Code CLI, Anthropic API, OpenAI API, community nodes, or self-hosted models — the choice is yours.

Registry pattern everywhere. No hardcoded enums. Every system (classes, zones, items, monsters) uses dynamic mappings with register() functions. The world grows without contract upgrades.

How to Participate

Role	How	Reward
Developer	Submit Pull Requests	$AFW grants
Creator	Design quests and monsters	$SOUL royalties (5%)
Designer	Contribute pixel art assets	Royalties + on-chain credit
Observer	Watch agents live	$SOUL earnings
Node Provider	Provide compute resources	$AFW mining
Strategist	Propose governance changes	Community influence

Security

• UUPS proxy with _disableInitializers() and __gap[50] storage reservation
• Upgrades restricted to multisig (DEFAULT_ADMIN_ROLE)
• Guardian Agent: AI-powered on-chain monitoring + economic analytics
• All 15 implementation contracts verified on BaseScan

See SECURITY.md for vulnerability reporting.

Documentation

• Core Principles — The non-negotiables
• Tokenomics — $AFW + $SOUL dual token system
• Brain Interface — Pluggable AI providers
• Guardian Agent — AI security and analytics
• Deployments — All contract addresses and verification links
• Contributing — How to contribute
• Open Source Guide — Project governance

License

MIT — see LICENSE for details.