Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
456 lines (313 loc) · 8.08 KB

GETTING_STARTED.md

File metadata and controls

456 lines (313 loc) · 8.08 KB

Getting Started with Global Truth Protocol

Welcome to the Global Truth Protocol (GTP) - a planetary-scale probabilistic truth infrastructure.

🎯 Quick Start (5 minutes)

Prerequisites

  • Node.js >= 18.0.0
  • Python >= 3.10
  • Git
  • MetaMask (or Web3 wallet)
  • Docker (optional, for local blockchain)

1. Clone Repository

git clone https://github.com/burnzy/global-truth-protocol
cd GlobalTruthProtocol

2. Setup Environment Variables

Create a .env file in the root directory:

# Blockchain
ETHEREUM_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY
DEPLOYER_PRIVATE_KEY=your_private_key_here
ETHERSCAN_API_KEY=your_etherscan_key

# AI Core
FRED_API_KEY=your_fred_api_key
NEWS_API_KEY=your_news_api_key
SPORTS_API_KEY=your_sports_api_key

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=gtp_predictions
DB_USER=postgres
DB_PASSWORD=your_password

REDIS_HOST=localhost
REDIS_PORT=6379

# API
API_SECRET_KEY=your_secret_key_here

# Monitoring
SLACK_WEBHOOK_URL=your_slack_webhook
ALERT_EMAIL=alerts@yourcompany.com

3. Install Dependencies

AI Core (Python)

cd ai-core
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Smart Contracts

cd ../smart-contracts
npm install

Frontend

cd ../frontend
npm install

Backend API

cd ../backend
npm install

4. Deploy Smart Contracts (Local)

cd smart-contracts

# Start local Hardhat node
npx hardhat node

# In another terminal, deploy contracts
npx hardhat run scripts/deploy.js --network localhost

Copy the deployed contract addresses to your .env file.

5. Start AI Core

cd ai-core
python main.py

The AI prediction engine will start listening for events.

6. Start Backend API

cd backend
npm run dev

API will be available at http://localhost:8000

7. Start Frontend

cd frontend
npm run dev

Open http://localhost:3000 in your browser.

📚 Detailed Setup

Database Setup

PostgreSQL

# Install PostgreSQL
brew install postgresql  # macOS
sudo apt install postgresql  # Ubuntu

# Create database
createdb gtp_predictions

# Run migrations
psql gtp_predictions < database/schema.sql

Redis

# Install Redis
brew install redis  # macOS
sudo apt install redis  # Ubuntu

# Start Redis server
redis-server

AI Model Training

The AI models need historical data to train on:

cd ai-core

# Download training data
python scripts/download_data.py

# Train models
python scripts/train_models.py

# This will create trained model checkpoints in models/checkpoints/

Training takes approximately 2-4 hours on a GPU.

Smart Contract Verification

After deploying to testnet/mainnet, verify contracts:

cd smart-contracts

npx hardhat verify --network sepolia DEPLOYED_ADDRESS "CONSTRUCTOR_ARGS"

🎮 Usage Examples

Create a Prediction Event

// Using ethers.js
const eventId = ethers.utils.id("2026_US_ELECTION");
const description = "2026 US Midterm Elections - Democratic Control";
const category = 1; // Politics
const lockDate = Math.floor(Date.now() / 1000) + 30 * 24 * 60 * 60; // 30 days
const resolutionDate = lockDate + 7 * 24 * 60 * 60; // 7 days after
const criteriaHash = ethers.utils.keccak256(ethers.utils.toUtf8Bytes("Democratic majority in House"));

const tx = await eventRegistry.createEvent(
  eventId,
  description,
  category,
  lockDate,
  resolutionDate,
  criteriaHash,
  { value: ethers.utils.parseEther("0.01") }
);

await tx.wait();
console.log("Event created:", eventId);

Generate AI Prediction

# Using Python AI Core
from main import PredictiveCore
import asyncio

async def predict():
    config = load_config('config.yaml')
    core = PredictiveCore(config)
    
    prediction = await core.predict_event('EVT_2026_US_ELECTION')
    
    print(f"Truth Score: {prediction['truthScore']:.3f}")
    print(f"Volatility: {prediction['volatilityIndex']:.3f}")
    print(f"Hash: {prediction['predictionHash']}")

asyncio.run(predict())

Stake on Event

// Stake TRUTH tokens on outcome
const eventId = ethers.utils.id("2026_US_ELECTION");
const amount = ethers.utils.parseEther("100"); // 100 TRUTH
const outcome = true; // Predicting TRUE

// Approve TRUTH tokens
await truthToken.approve(stakingPool.address, amount);

// Stake
const tx = await stakingPool.stakeOnEvent(eventId, amount, outcome);
await tx.wait();

console.log("Staked successfully!");

Claim Rewards

// After event resolution
const eventId = ethers.utils.id("2026_US_ELECTION");

const tx = await stakingPool.claimRewards(eventId);
const receipt = await tx.wait();

console.log("Rewards claimed!");

🧪 Testing

Smart Contract Tests

cd smart-contracts
npx hardhat test

# With gas reporting
REPORT_GAS=true npx hardhat test

# Coverage
npx hardhat coverage

AI Core Tests

cd ai-core
pytest tests/ -v

# With coverage
pytest tests/ --cov=. --cov-report=html

Integration Tests

cd backend
npm test

# E2E tests
npm run test:e2e

📦 Deployment

Deploy to Sepolia Testnet

cd smart-contracts

# Deploy
npx hardhat run scripts/deploy.js --network sepolia

# Verify
npx hardhat verify --network sepolia DEPLOYED_ADDRESS

Deploy AI Core to Production

cd ai-core

# Build Docker image
docker build -t gtp-ai-core .

# Run container
docker run -d \
  --name gtp-ai-core \
  -p 8000:8000 \
  --env-file .env \
  gtp-ai-core

Deploy Frontend to Vercel

cd frontend

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel --prod

🔧 Configuration

AI Model Parameters

Edit ai-core/config.yaml:

monte_carlo:
  num_simulations: 100000  # Increase for more accuracy

reinforcement_learning:
  learning_rate: 0.001  # Adjust based on performance

Smart Contract Parameters

Edit deployment script or use governance:

// Adjust platform fee
await stakingPool.setPlatformFee(200); // 2%

// Adjust stake limits
await stakingPool.setStakeLimits(
  ethers.utils.parseEther("1"),
  ethers.utils.parseEther("1000000")
);

🐛 Troubleshooting

Issue: AI predictions are slow

Solution:

  • Reduce num_simulations in config
  • Use GPU acceleration
  • Enable caching in Redis

Issue: Smart contract deployment fails

Solution:

  • Check you have enough ETH for gas
  • Verify RPC URL is correct
  • Increase gas limit in hardhat.config.js

Issue: Frontend not connecting to wallet

Solution:

  • Ensure MetaMask is installed
  • Check network is correct (Sepolia testnet)
  • Clear browser cache

Issue: Database connection errors

Solution:

  • Verify PostgreSQL is running: pg_isready
  • Check credentials in .env
  • Ensure database exists: psql -l

📖 Further Reading

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md

Development Workflow

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

Code Style

  • Python: Follow PEP 8, use Black formatter
  • JavaScript: Follow Airbnb style guide, use Prettier
  • Solidity: Follow Solidity style guide

🆘 Support

📄 License

MIT License - See LICENSE for details

"Truth is not binary. It's a probability distribution backed by economic consequence."