🏛️ RACE Protocol

RWA-Powered Autonomous Commerce Engine

A fully autonomous AI agent network that transforms Real World Assets (RWA) into on-chain productive capital, driving automated DeFi commerce activities.

Features • Architecture • Quick Start • Documentation

🎯 Overview

RACE Protocol is a cutting-edge decentralized platform that bridges traditional finance with DeFi through intelligent automation. By tokenizing Real World Assets and deploying AI-powered autonomous agents, RACE enables:

Automated Asset Management: AI agents manage RWA-backed portfolios 24/7
Risk-Optimized Trading: Machine learning models assess market conditions and execute strategies
Multi-Chain Operations: Seamless deployment across Ethereum, Arc, and Monad networks
Transparent Governance: On-chain decision tracking and revenue distribution

✨ Key Features

🤖 Autonomous AI Agents

ERC-6551 Token-Bound Accounts: Each agent is a smart contract wallet with independent decision-making
Multi-Model Intelligence: Powered by GPT-4o and Claude 3.5 Sonnet for diverse strategy execution
LangChain Integration: Advanced reasoning chains for complex DeFi operations
Real-time Market Analysis: Continuous monitoring and adaptive strategy adjustment

🏦 RWA Tokenization

Vault System: Secure collateralization of real-world assets
Oracle Integration: Multi-source price feeds for accurate asset valuation
Liquidation Protection: Automated risk management and position monitoring
Revenue Distribution: Fair profit sharing among stakeholders

🔗 Multi-Chain Support

Ethereum Mainnet: Production-ready deployment
Arc Testnet: High-performance testing environment
Monad Testnet: Next-gen blockchain compatibility

📊 Professional Dashboard

Newsprint Design System: Clean, newspaper-inspired UI with Playfair Display typography
Real-time Monitoring: Live agent performance metrics and portfolio tracking
Multi-User Management: Configure and monitor multiple AI agents simultaneously
Automation Controls: Fine-tune agent behavior and risk parameters

🏗️ Architecture

race-protocol/
├── packages/
│   ├── contracts/          # Smart Contracts (Solidity)
│   │   ├── AIAgent.sol            # ERC-6551 autonomous agent
│   │   ├── RWAVault.sol           # Asset tokenization vault
│   │   ├── RiskManager.sol        # Liquidation protection
│   │   ├── OracleAggregator.sol   # Multi-oracle price feeds
│   │   ├── RevenueManager.sol     # Profit distribution
│   │   ├── LendingPool.sol        # DeFi lending integration
│   │   └── SimpleDEX.sol          # Decentralized exchange
│   │
│   ├── frontend/           # Next.js 14 Web Application
│   │   ├── App Router              # Modern Next.js routing
│   │   ├── Wagmi v2 + Viem         # Multi-chain wallet connection
│   │   ├── RainbowKit v2           # Beautiful wallet UI
│   │   ├── Tailwind CSS 3          # Utility-first styling
│   │   ├── Recharts                # Data visualization
│   │   └── Jotai + TanStack Query  # State management
│   │
│   ├── backend/            # NestJS API Server
│   │   ├── REST API                # Agent orchestration endpoints
│   │   ├── Swagger Docs            # Auto-generated API documentation
│   │   ├── Ethers.js v6            # Blockchain interaction
│   │   └── Class Validator         # Request validation
│   │
│   └── ai-agents/          # Python AI Decision Engine
│       ├── LangChain               # AI reasoning framework
│       ├── OpenAI GPT-4o           # Primary decision model
│       ├── Anthropic Claude 3.5    # Secondary analysis model
│       └── Market Analyzers        # Trading strategy modules

🚀 Quick Start

Prerequisites

Installation

# Clone the repository
git clone https://github.com/yourusername/race-protocol.git
cd race-protocol

# Install all dependencies
npm install

# Setup Python environment for AI agents
cd packages/ai-agents
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
cd ../..

Environment Configuration

Create .env files in each package:

packages/contracts/.env

PRIVATE_KEY=your_wallet_private_key
ETHERSCAN_API_KEY=your_etherscan_key
ARC_RPC_URL=https://arc-testnet-rpc.example.com
MONAD_RPC_URL=https://monad-testnet-rpc.example.com

packages/frontend/.env.local

NEXT_PUBLIC_RWA_VAULT_ADDRESS=0x...
NEXT_PUBLIC_AI_AGENT_ADDRESS=0x...
NEXT_PUBLIC_RISK_MANAGER_ADDRESS=0x...
NEXT_PUBLIC_USDC_ADDRESS=0x...
NEXT_PUBLIC_API_URL=http://localhost:5000

packages/backend/.env

PORT=5000
RPC_URL=https://eth-mainnet.g.alchemy.com/v2/your-key
CONTRACT_ADDRESS=0x...

packages/ai-agents/.env

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
RPC_URL=https://eth-mainnet.g.alchemy.com/v2/your-key

Development

# Run all services concurrently (requires Turbo)
npm run dev

# Or run services individually:

# Terminal 1: Frontend (http://localhost:3000)
npm run frontend:dev

# Terminal 2: Backend API (http://localhost:5000)
npm run backend:dev

# Terminal 3: AI Agents
npm run ai:dev

# Terminal 4: Compile & deploy contracts
npm run contracts:compile
npm run contracts:deploy

📦 Packages

🔐 Smart Contracts (`packages/contracts`)

Core Contracts:

AIAgent.sol (22KB): ERC-6551 token-bound account with autonomous trading capabilities
RWAVault.sol (7KB): Collateral management and asset tokenization
RiskManager.sol (6.6KB): Liquidation protection and health factor monitoring
OracleAggregator.sol (4.7KB): Multi-source price feed aggregation
RevenueManager.sol (4.5KB): Automated profit distribution
LendingPool.sol (7.7KB): DeFi lending protocol integration
SimpleDEX.sol (9.6KB): Decentralized exchange for asset swaps

Commands:

cd packages/contracts
npm run compile          # Compile contracts
npm run test            # Run test suite
npm run deploy          # Deploy to local network
npm run deploy:arc      # Deploy to Arc Testnet
npm run deploy:monad    # Deploy to Monad Testnet

🎨 Frontend (`packages/frontend`)

Tech Stack:

Framework: Next.js 14 with App Router
Blockchain: Wagmi v2 + Viem v2 + RainbowKit v2
Styling: Tailwind CSS 3 with custom Newsprint design system
State: Jotai (atomic state) + TanStack Query v5 (server state)
Charts: Recharts with custom styling
Icons: Lucide React
Animations: Framer Motion

Design System:

Typography: Playfair Display (headlines), Lora (body), Inter (UI), JetBrains Mono (code)
Colors: Newsprint palette (#F9F9F7 bg, #111111 ink, #CC0000 accent)
Layout: Zero border-radius, dot-grid backgrounds, hard shadows

Commands:

cd packages/frontend
npm run dev      # Start dev server (localhost:3000)
npm run build    # Production build
npm run start    # Start production server
npm run lint     # ESLint check

⚙️ Backend (`packages/backend`)

Features:

RESTful API for agent orchestration
Swagger/OpenAPI documentation
Ethers.js v6 for blockchain interaction
Class-validator for request validation
Modular architecture with dependency injection

API Endpoints:

GET /api/agents - List all AI agents
POST /api/agents - Create new agent
GET /api/agents/:id - Get agent details
POST /api/agents/:id/execute - Execute trading strategy
GET /api/market/prices - Fetch current market prices
GET /api/portfolio/:address - Get portfolio stats

Commands:

cd packages/backend
npm run start:dev    # Development mode with hot reload
npm run start:prod   # Production mode
npm run build        # Build for production
npm run test         # Run tests

🧠 AI Agents (`packages/ai-agents`)

AI Models:

GPT-4o: Primary decision-making and strategy generation
Claude 3.5 Sonnet: Risk analysis and market sentiment
LangChain: Reasoning chains and tool orchestration

Capabilities:

Market trend analysis and prediction
Risk assessment and portfolio optimization
Automated trading strategy execution
Multi-agent coordination
Real-time decision logging

Commands:

cd packages/ai-agents
source venv/bin/activate
python -m src.main              # Start AI agent service
python -m src.backtest          # Run strategy backtesting
python -m pytest tests/         # Run test suite

🌐 Supported Networks

Network	Chain ID	Status	RPC URL
Ethereum Mainnet	1	✅ Production	`https://eth-mainnet.g.alchemy.com`
Arc Testnet	1234	🧪 Testing	`https://arc-testnet-rpc.example.com`
Monad Testnet	5678	🧪 Testing	`https://monad-testnet-rpc.example.com`

🛠️ Technology Stack

Frontend

Backend

Smart Contracts

AI/ML

📚 Documentation

Smart Contracts: See packages/contracts/README.md for contract documentation
API Reference: Visit http://localhost:5000/api/docs when backend is running
Frontend Components: Check packages/frontend/src/components/ for UI documentation
AI Agents: Read packages/ai-agents/docs/ for strategy documentation

🧪 Testing

# Run all tests
npm run test

# Test specific packages
npm run contracts:test    # Smart contract tests
cd packages/frontend && npm run test    # Frontend tests
cd packages/backend && npm run test     # Backend tests
cd packages/ai-agents && pytest         # AI agent tests

🚢 Deployment

Smart Contracts

# Deploy to Arc Testnet
npm run contracts:deploy:arc

# Deploy to Monad Testnet
npm run contracts:deploy:monad

# Verify contracts
cd packages/contracts
npx hardhat verify --network arc <CONTRACT_ADDRESS>

Frontend

cd packages/frontend
npm run build
# Deploy to Vercel, Netlify, or your preferred hosting

Backend

cd packages/backend
npm run build
npm run start:prod
# Deploy to AWS, GCP, or your preferred cloud provider

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

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

📄 License

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

🔗 Links

Website: https://race-frontend.vercel.app/
Twitter: @DawneraGames

Built with ❤️ by the RACE Protocol Team

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
packages		packages
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
demo_user_controls.sh		demo_user_controls.sh
package-lock.json		package-lock.json
package.json		package.json
turbo.json		turbo.json
vercel.json		vercel.json

Folders and files

Latest commit

History

Repository files navigation

🏛️ RACE Protocol

RWA-Powered Autonomous Commerce Engine

🎯 Overview

✨ Key Features

🤖 Autonomous AI Agents

🏦 RWA Tokenization

🔗 Multi-Chain Support

📊 Professional Dashboard

🏗️ Architecture

🚀 Quick Start

Prerequisites

Installation

Environment Configuration

Development

📦 Packages

🔐 Smart Contracts (packages/contracts)

🎨 Frontend (packages/frontend)

⚙️ Backend (packages/backend)

🧠 AI Agents (packages/ai-agents)

🌐 Supported Networks

🛠️ Technology Stack

Frontend

Backend

Smart Contracts

AI/ML

📚 Documentation

🧪 Testing

🚢 Deployment

Smart Contracts

Frontend

Backend

🤝 Contributing

📄 License

🔗 Links

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

🔐 Smart Contracts (`packages/contracts`)

🎨 Frontend (`packages/frontend`)

⚙️ Backend (`packages/backend`)

🧠 AI Agents (`packages/ai-agents`)

Packages