A permissionless AI agent marketplace where autonomous agents compete to control AMM parameters, dynamically reshaping bonding curves, fees, and liquidity — outperforming static AMMs in capital efficiency and volatility control.

graph LR
    Users["👤 Users<br/>(Traders · LPs)"]
    Frontend["🖥 Frontend<br/>Next.js 14"]
    Contracts["⛓ Smart Contracts<br/>BSC Testnet"]
    Agent["🤖 AI Agent<br/>Node.js"]
    Greenfield["📦 BNB Greenfield<br/>Audit Storage"]

    Users -->|swap · add liquidity| Frontend
    Frontend -->|ethers.js v6| Contracts
    Agent -->|poll state & submit updates| Contracts
    Agent -.->|upload decision logs| Greenfield
    Frontend -.->|read audit logs| Greenfield

graph TD
    Trader["👤 Trader"] -->|"swap()"| Pool
    LP["💧 LP"] -->|"addLiquidity() · removeLiquidity()"| Pool
    AgentWallet["🤖 Agent"] -->|"registerAgent() + bond tBNB"| Controller
    AgentWallet -->|"submitParameterUpdate(fee, beta, mode)"| Controller

    Controller -->|"validate bounds · cooldown · bond"| Controller
    Controller -->|"updateParameters()"| Pool

    Epoch -->|"score agents · distribute rewards"| Controller
    TimeLock -.->|"governance (24h delay)"| Controller

    Pool["EvoPool.sol<br/>AMM · LP Tokens · TWAP · Fees"]
    Controller["AgentController.sol<br/>Registry · Bonds · Slashing"]
    Epoch["EpochManager.sol<br/>Competition · Rewards"]
    TimeLock["TimeLock.sol<br/>Governance"]

    style Pool fill:#1a1a2e,stroke:#F5A623,color:#F5A623
    style Controller fill:#1a1a2e,stroke:#4A90D9,color:#4A90D9
    style Epoch fill:#1a1a2e,stroke:#7ED321,color:#7ED321
    style TimeLock fill:#1a1a2e,stroke:#888,color:#888

graph LR
    A["📡 Poll Pool<br/>reserves · fee · events"] --> B["📊 Compute Features<br/>volatility · velocity · whale %"]
    B --> C{"🧠 Strategy Engine"}
    C -->|rule-based| D["Rule Engine<br/>3 curve modes"]
    C -->|ML mode| E["Linear Regression<br/>confidence-weighted"]
    D --> F["🛡 Circuit Breaker<br/>anomaly check"]
    E --> F
    F -->|safe| G["✅ Submit Update TX<br/>→ AgentController"]
    F -->|blocked| H["⛔ Skip & Alert"]
    G --> I["📈 Compute APS Score"]
    I --> J["📦 Upload Log<br/>→ BNB Greenfield"]

    style F fill:#1a1a2e,stroke:#D0021B,color:#D0021B
    style G fill:#1a1a2e,stroke:#7ED321,color:#7ED321
    style H fill:#1a1a2e,stroke:#D0021B,color:#D0021B

contracts/                Solidity smart contracts (Hardhat)
  EvoPool.sol             Adaptive AMM with ERC-20 LP, TWAP, protocol fees, EIP-2612 Permit
  AgentController.sol     Agent registry, bounds, cooldown, slashing, ERC-20 token bonding
  EpochManager.sol        On-chain epoch-based multi-agent competition
  TimeLock.sol            Governance timelock (queue/execute/cancel)
  EvoToken.sol            Minimal ERC-20 for protocol coordination
  interfaces/             Contract interfaces (IEvoPool, IAgentController, IEpochManager)

test/                     Contract tests (Mocha + Chai, 152 passing)
  AgentController.test.ts 45 tests — registration, updates, slashing, bonding
  EvoPool.test.ts         38 tests — liquidity, swaps, TWAP, protocol fees, pause
  EpochManager.test.ts    23 tests — epochs, proposals, finalization, rewards
  TimeLock.test.ts        9 tests — queue, execute, cancel, access control
  E2E.test.ts             13 tests — full lifecycle integration test
  Invariant.test.ts       24 tests — K invariant, reserve positivity, TWAP monotonicity, LP proportionality, stress

scripts/                  Deploy, verify & demo scripts
  deploy.ts               Full deployment with TimeLock governance transfer
  demo-local.ts           One-command live simulation (11 scenarios)

agent/                    Off-chain Node.js agent
  src/
    index.ts              Main loop — multi-pool, ML integration, circuit breaker
    executor.ts           On-chain execution with multicall batching
    strategyEngine.ts     Rule-based strategy engine (3 curve modes)
    mlStrategy.ts         Online linear regression ML model
    backtester.ts         Historical backtesting framework
    circuitBreaker.ts     Anomaly detection & auto-halt
    volatility.ts         EMA-based volatility calculator
    apsCalculator.ts      Agent Performance Score computation
    config.ts             Environment configuration
  state/                  APS snapshots & update logs

frontend/                 Next.js 14 dashboard (App Router + Tailwind)
  src/app/
    page.tsx              Pool overview with live charts
    agents/page.tsx       Agent leaderboard
    swap/page.tsx         Token swap UI
    liquidity/page.tsx    Add/remove liquidity UI
    history/page.tsx      Transaction history (Swaps, Liquidity, Parameters)
    settings/page.tsx     Agent strategy configuration UI
    demo/page.tsx         Interactive demo
    api/agent-stats/      REST API for agent stats
    api/aps/              APS scoring endpoint
  src/hooks/
    useEvoPool.ts         Pool state hook
    useWallet.tsx         Multi-wallet context (MetaMask + WalletConnect)
    usePolling.ts         Generic real-time polling hook
  src/lib/
    contracts.ts          ABIs, addresses, constants
    wallet.ts             Multi-wallet connection (MetaMask, WalletConnect, injected)
  src/components/
    Charts.tsx            Recharts visualizations
    WalletButton.tsx      Connect wallet button

subgraph/                 The Graph subgraph scaffold
  subgraph.yaml           Data source configuration (EvoPool, Controller, EpochManager)
  schema.graphql          Entity schema (Swap, Agent, Epoch, Proposal, etc.)
  src/mapping.ts          Event handlers

docs/                     Documentation
  architecture.md         System architecture + Mermaid diagrams
  user-journey.md         User flow diagrams (Trader, LP, Agent journeys)
  demo-walkthrough.md     Step-by-step demo verification
  demo.md                 Demo script for judges
  gas-report.md           Gas usage report

docker/                   Docker configuration
  Dockerfile.chain        Hardhat node + deployer image
  Dockerfile.frontend     Next.js production image
  Dockerfile.agent        Off-chain agent image
docker-compose.yml        One-command full-stack launch

.github/workflows/ci.yml  3-job CI pipeline (test+coverage+lint, agent, frontend)

• EvoPool: Adaptive AMM with 3 curve modes (Normal, Defensive, VolatilityAdaptive)
• ERC-20 LP Tokens: Full ERC-20 composability with EIP-2612 Permit support
• TWAP Oracle: Uniswap-V2-style time-weighted average price accumulators
• Protocol Fee Switch: Configurable protocol fee (up to 20% of swap fee)
• Balance-Diff Accounting: Safe token accounting via balance snapshots
• EpochManager: On-chain multi-agent competition with scoring and rewards
• TimeLock: Governance timelock for admin operations (24h–7d delay)
• ERC-20 Token Bonding: Agents can stake ERC-20 tokens in addition to native bonds
• Emergency Pause: Owner can halt swaps/deposits while allowing LP emergency exits
• Formal Slashing Criteria: 3 enumerated conditions for agent slashing
• Rate Limiting: parameterUpdateBlock tracking prevents flash-loan attacks

• ML Strategy Engine: Online linear regression with confidence-weighted predictions
• Historical Backtesting: Replay-based backtesting framework with strategy comparison
• Circuit Breaker: Anomaly detection (reserve drain, price crash, rapid updates)
• Multi-Pool Support: Single agent instance manages multiple pools
• Gas Optimization: Multicall batching for on-chain execution

• 7 Pages: Pool, Agents, Swap, Liquidity, History, Settings, Demo
• Multi-Wallet: MetaMask + WalletConnect support
• Real-Time Polling: Auto-refresh pool and agent data
• Agent Settings UI: Submit parameter updates directly from the browser
• Transaction History: Browse swaps, liquidity events, and parameter updates
• Mobile-Responsive: Hamburger navigation for mobile devices
• Agent Stats API: REST endpoint at /api/agent-stats?address=0x...

• Docker Compose: One-command full-stack launch (chain + deployer + agent + frontend)
• 3-Job CI Pipeline: test+coverage+lint, agent build, frontend build
• Gas Snapshot: Automated gas reporting as CI artifact
• BSC Testnet + Mainnet: Dual-network Hardhat configuration
• Subgraph Scaffold: Ready for The Graph deployment

Launch the entire stack in one command — Hardhat node, contract deployment, AI agent, and frontend:

docker-compose up --build

To stop: docker-compose down · To reset: docker-compose down -v

• Node.js ≥ 18
• npm or yarn
• BSC Testnet (Chapel) RPC + funded wallet

npm install

cp .env.example .env
# Fill in PRIVATE_KEY, BSC_TESTNET_RPC, BSCSCAN_API_KEY

npx hardhat compile

npx hardhat test          # 152 tests
npx hardhat coverage      # Coverage report
npm run test:gas          # Gas usage report

npx hardhat run scripts/deploy.ts --network bscTestnet

cd agent && npm install
npm run once              # Single epoch
npm start                 # Continuous loop
npm run backtest          # Historical backtesting

cd frontend && npm install && npm run dev

./demo.sh          # Quick: live simulation only (~5s)
./demo.sh full     # Full: compile + 152 tests + simulation + gas report

152 tests passing across 6 test files.

Each epoch the agent computes:

APS = 0.4·LPΔ + 0.3·SlippageReduction + 0.2·VolatilityCompression + 0.1·FeeRevenue

1. Excessive Deviation: Parameters deviate >200bps from optimal in a single update
2. Rapid Oscillation: >5 updates within 10 minutes suggesting manipulation
3. Manipulation Detected: Evidence of coordinated front-running or sandwich attacks

All contracts are verified on BscScan. Click to inspect source code and transactions.

Deployer: 0x3E7716BeE2D7E923CB9b572EB169EdFB6cdbDAB6

EvoArena integrates BNB Greenfield decentralized storage to create an immutable, tamper-proof audit trail of all AI agent decisions.

1. Agent submits parameter update on-chain via AgentController.sol
2. After TX confirmation, a structured JSON log is uploaded to Greenfield bucket evoarena-audit-logs
3. Logs are publicly readable — anyone can verify agent decisions
4. The /audit page in the frontend browses and displays all stored logs

• Transparency: All AI agent decisions are publicly auditable
• Immutability: Stored on decentralized storage, not a centralized database
• BNB Ecosystem: Bridges BSC smart contracts with Greenfield storage
• Cross-Chain: Same wallet works on both BSC and Greenfield

• Optimal Dynamic Fees for AMMs
• Uniswap v3 Concentrated Liquidity
• Bancor IL Protection
• Autonomous AI Agents in DeFi

Token Utility (EvoToken):

• Used as pool pair tokens for demonstration
• Agent bonding collateral (ERC-20 token bonding supported)
• Epoch reward distribution medium
• Governance participation (via TimeLock proposals)

• Adaptive AMM with 3 curve modes (Normal, Defensive, VolatilityAdaptive)
• Agent registry with bonding, cooldown, slashing
• Epoch-based multi-agent competition
• Governance timelock
• Off-chain ML + rule-based agent
• Circuit breaker & anomaly detection
• Next.js frontend with 7 pages
• BNB Greenfield audit trail
• 152 tests, 95%+ coverage
• BSC Testnet deployment (6 verified contracts)

• Professional audit (CertiK / PeckShield)
• BSC Mainnet deployment
• Multi-pool support (any ERC-20 pair)
• The Graph subgraph deployment for indexed queries
• Agent SDK — npm package for building custom agents
• Advanced ML models (LSTM, transformer-based volatility prediction)

• Agent marketplace — discover and delegate to top agents
• LP vault aggregator — auto-route liquidity to best-performing pools
• opBNB L2 integration for gas-efficient agent updates
• Cross-chain expansion (Ethereum, Arbitrum, Base)
• Mobile app for LP monitoring

• EVO governance token launch
• DAO-controlled protocol parameters
• Community agent bounties
• Insurance fund for LP protection
• Partnership integrations (PancakeSwap, Venus, Alpaca Finance)

MIT — see LICENSE.