Ritual Agent Arena

Ritual Agent Arena is a Ritual testnet dApp where users summon AI-themed onchain agents and interact with them through real arena transactions (Support / Train / Invoke / Challenge). This is not a DeFi app and does not claim fake AI execution.

Stack

• Frontend: Next.js 16 (App Router), TypeScript, Tailwind CSS v4, wagmi + viem, RainbowKit, TanStack Query, SWR
• Contracts: Solidity 0.8.24, Hardhat, OpenZeppelin 5.x
• Network: Ritual Testnet (Chain ID 1979)

Monorepo structure

• frontend/ — Next.js app
• contracts/ — Hardhat project (contracts + tests + deploy)

Features (current)

• Wallet connect (MetaMask/injected) + wrong-network switch
• Summon Agent (onchain) + explorer links
• Arena actions (onchain): Support (+1), Train (+3), Invoke (+5), Challenge (+8) with cooldowns
• Gas estimate shown via real contract simulation (eth_estimateGas)
• Confetti on confirmed success + clear message on wallet cancellation
• Arena feed reads recent onchain logs with “Load older / Load more”
• Ranks: top agents + active handlers (recent activity window)

Prerequisites

• Node.js 18+ (recommended)
• MetaMask (or another injected wallet)

Setup

1) Install deps

cd frontend
npm install

cd ../contracts
npm install

2) Environment variables

Frontend (frontend/.env.local)

Copy from frontend/.env.example and fill:

• NEXT_PUBLIC_AGENT_REGISTRY_ADDRESS
• NEXT_PUBLIC_AGENT_ARENA_ADDRESS
• Optional: NEXT_PUBLIC_RITUAL_RPC_URL (defaults to Ritual RPC)

Contracts (contracts/.env)

Copy from contracts/.env.example and fill:

• PRIVATE_KEY (deployer)
• Optional: RITUAL_RPC_URL

3) Compile + test contracts

cd contracts
npm test

4) Deploy to Ritual testnet

cd contracts
npm run deploy:ritual

The deploy script prints NEXT_PUBLIC_* env values you should paste into frontend/.env.local.

5) Run the app

cd frontend
npm run dev

Open http://localhost:3000.

Security notes (prod)

The app includes an RPC proxy at frontend/src/app/api/rpc/route.ts.

• Allowlist: only permits required JSON-RPC methods (including eth_estimateGas)
• Payload limit: rejects oversized bodies

When deploying, keep RITUAL_RPC_URL set to a trusted endpoint.

Troubleshooting

• UI doesn’t reflect changes: restart dev server (Ctrl+C then npm run dev) and hard refresh (Ctrl+Shift+R).
• Gas estimate shows error: ensure /api/rpc is reachable and the proxy allowlist includes eth_estimateGas.