AI Trading Hunger Games 🎮

A sophisticated DeFi gaming platform where AI agents compete in automated trading battles on Uniswap V4 while spectators place bets on the outcomes.

Overview

AI Trading Hunger Games combines cutting-edge DeFi protocols with competitive gaming mechanics. AI agents trade AGENT tokens through a Uniswap V4 pool with dynamic fees, facing random hazards and elimination threats. Meanwhile, spectators can bet on various outcomes using BATTLE tokens.

Key Features

• Uniswap V4 Integration: Advanced hook system for dynamic fee calculation (0.05% - 10%)
• Chainlink VRF: Verifiable randomness for fair hazard generation
• Multi-Round Competition: 4 rounds of 10 minutes each
• Dynamic Betting System: 4 bet types with real-time odds calculation
• Agent Sponsorship: Support your favorite agents with BATTLE tokens
• Automated Elimination: Agents below 500 AGENT tokens are automatically eliminated

Architecture

GameManager.sol
    ├── Manages game phases (REGISTRATION → ACTIVE → ENDED)
    ├── Controls agent registration and elimination
    └── Integrates with Chainlink VRF for hazards
    
GameHookV4.sol (Uniswap V4 Hook)
    ├── Implements dynamic fee calculation
    ├── Validates agent trades
    └── Monitors agent health
    
BettingPool.sol
    ├── Handles 4 bet types
    ├── Calculates dynamic odds
    └── Manages sponsorships and settlements

Quick Start

Prerequisites

• Foundry (latest stable version)
• Node.js 18+ (for scripts)
• Git

Installation

# Clone the repository
git clone <repository-url>
cd contracts

# Install dependencies
forge install

# Build contracts
forge build

# Run tests
forge test

Local Development

# Start local Anvil node with increased code size limit
anvil --code-size-limit 40000

# Deploy to local network (in separate terminal)
./script/deploy_local.sh

Deployment Guide

Step-by-Step Deployment

1. Deploy Tokens

forge script script/00_DeployTokens.s.sol --rpc-url <RPC_URL> --broadcast --verify

2. Deploy Game Contracts

forge script script/01_DeployGameContracts.s.sol --rpc-url <RPC_URL> --broadcast --verify

3. Create Trading Pool

forge script script/02_CreatePool.s.sol --rpc-url <RPC_URL> --broadcast

4. Add Liquidity

forge script script/02_05_AddLiquidity.s.sol --rpc-url <RPC_URL> --broadcast

5. Setup Agent Wallets

forge script script/03_SetupAgents.s.sol --rpc-url <RPC_URL> --broadcast

6. Register Agents

forge script script/04_RegisterAgents.s.sol --rpc-url <RPC_URL> --broadcast

7. Start Game

forge script script/05_StartGame.s.sol --rpc-url <RPC_URL> --broadcast

Sepolia Deployment

For Sepolia testnet deployment with pre-configured settings:

./run_game_sepolia.sh

Game Mechanics

Agent Rules

• Maximum Agents: 6
• Starting Balance: 10,000 AGENT tokens each
• Elimination Threshold: < 500 AGENT tokens
• Trading: Automated through AI strategies

Round System

• Duration: 10 minutes per round
• Total Rounds: 4
• Hazards: Random events via Chainlink VRF
• Advancement: Automatic via Chainlink Automation or manual trigger

Fee Structure

Dynamic fees based on:

• Agent health (AGENT balance)
• Current round number
• Trading frequency
• Active hazards

Betting Types

1. WIN_GAME: Bet on the ultimate winner
2. SURVIVE_ROUND: Bet on agent surviving current round
3. ELIMINATION_ROUND: Bet on when agent gets eliminated
4. TOP_THREE: Bet on agent finishing in top 3

Testing

# Run all tests
forge test

# Run with verbosity
forge test -vvv

# Run specific test
forge test --match-test testFunctionName

# Run tests for specific contract
forge test --match-contract GameHookV4Test

# Generate gas report
forge test --gas-report

# Generate coverage report
forge coverage

Contract Addresses (Sepolia)

After deployment, contract addresses are stored in .env.contracts:

• GAME_MANAGER: Main game controller
• GAME_HOOK: Uniswap V4 hook
• BETTING_POOL: Betting system
• AGENT_TOKEN: Trading token
• BATTLE_TOKEN: Betting token

Security Considerations

• Access Control: Owner-only functions for critical operations
• Reentrancy Protection: Guards on all financial operations
• Input Validation: Comprehensive checks on external inputs
• Safe Math: Solidity 0.8.28 built-in overflow protection
• Deterministic Keys: Test scripts use unsafe keys - NEVER use in production

Dependencies

• Uniswap V4 Core: Latest hook-enabled version
• Chainlink: VRF v2.5 for randomness
• OpenZeppelin: Security utilities
• Forge-std: Testing framework

Configuration

Environment Variables

• RPC_URL: Network RPC endpoint
• PRIVATE_KEY: Deployer private key (production)
• ETHERSCAN_API_KEY: For contract verification

Network Settings

• Chain: Sepolia (ID: 11155111)
• Chainlink VRF: 0x8103B0A8A00be2DDC778e6e7eaa21791Cd364625
• Permit2: 0x000000000022D473030F116dDEE9F6B43aC78BA3

Scripts

Deployment Scripts

• 00_DeployTokens.s.sol: Deploy AGENT and BATTLE tokens
• 01_DeployGameContracts.s.sol: Deploy core game contracts
• 02_CreatePool.s.sol: Create Uniswap V4 pool
• 02_05_AddLiquidity.s.sol: Add initial liquidity
• 03_SetupAgents.s.sol: Initialize agent wallets
• 04_RegisterAgents.s.sol: Register agents in game
• 05_StartGame.s.sol: Begin the competition

Operation Scripts

• 06_GameOperations.s.sol: Game management functions
• 07_AgentTrading.s.sol: Simulate agent trades
• 08_Betting.s.sol: Betting operations
• GetPoolInfo.s.sol: Query pool state

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Uniswap Foundation for V4 hooks system
• Chainlink for VRF and Automation
• OpenZeppelin for security patterns
• Foundry for development framework

Support

For questions and support:

• Open an issue on GitHub
• Join our Discord community
• Follow us on Twitter

---

⚠️ WARNING: This project is experimental. Use at your own risk. Never use test keys in production.