Esport Oracle

Esport Oracle is a decentralized oracle developed by PoC Innovation that bridges Counter-Strike 2 esports data with blockchain smart contracts. It securely and verifiably transfers match results, player statistics, tournament details and other competitive data onto the blockchain, enabling new possibilities for decentralized betting and other CS2-related applications while ensuring full transparency and accessibility for all stakeholders in the esports ecosystem.

🏗️ Architecture

The project consists of two main components:

1. Smart Contract Oracle (/oracle)

• EsportOracle.sol: Main oracle contract with staking mechanism and consensus system
• EsportOracleRequester.sol: Extension contract for handling match data requests
• Built with Solidity ^0.8.20 and Foundry framework
• Implements a decentralized consensus mechanism with node validation
• Features a punishment system for malicious actors

2. Go Data Provider (/goapp)

• Go application that fetches data from PandaScore API
• Automatically submits match data to the smart contract
• Runs on a configurable cron schedule (default: every 15 minutes)
• Handles data transformation from API format to contract-compatible format

🔧 How does it work?

1. Node Registration: Data providers stake 0.001 ETH to become oracle nodes
2. Data Collection: Nodes fetch CS2 match data from PandaScore API
3. Consensus Mechanism: Multiple nodes submit the same data, requiring quorum (>50% + minimum 3 votes)
4. Data Validation: Smart contract validates and stores match results on-chain
5. Punishment System: Nodes submitting incorrect data are penalized or banned after 3 violations

🚀 Getting Started

Prerequisites

• Node.js (v16+)
• Go (v1.24+)
• Foundry (for smart contract development)
• Docker & Docker Compose (for deployment)
• PandaScore API Token (Get one here)

Installation

1. Clone the repository

git clone https://github.com/PoCInnovation/esport-oracle.git
cd esport-oracle

2. Set up the smart contract

cd oracle
forge install
forge build

3. Configure the Go application

cd ../goapp
cp .env.sample .env

Edit the .env file with your configuration:

CHAIN_ID=1337
PRIVATE_KEY=your_private_key_without_0x
CONTRACT_ADDRESS=deployed_contract_address_without_0x
CLIENT_ETH=http://localhost:8545
PANDASCORE_API_TOKEN=your_pandascore_api_token
CRON_SCHEDULE=*/15 * * * *

4. Install Go dependencies

go mod download

Quick Deployment with Docker

For a complete local deployment:

cd oracle
chmod +x deploy_oracle.sh
./deploy_oracle.sh

This will:

• Start a local Anvil blockchain node
• Deploy the EsportOracle contract
• Provide you with the contract address for configuration

Manual Deployment

1. Deploy Smart Contract

cd oracle

# Start local blockchain
anvil

# Deploy contract (in another terminal)
forge create "src/esportOracle.sol:EsportOracle" \
  --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
  --rpc-url http://localhost:8545

2. Run the Go Oracle Node

cd goapp
go run cmd/myapp/main.go

📖 Usage

For Oracle Node Operators

1. Stake ETH to become a node:

cast send --private-key <your_private_key> \
  --value 0.001ether \
  "<CONTRACT_ADDRESS>" \
  "addFundToStaking()"

2. Start the Go application:

go run cmd/myapp/main.go

The application will automatically:

• Fetch match data every 15 minutes (configurable)
• Submit data to the smart contract
• Handle consensus and validation

For Smart Contract Interactions

Get pending matches:

cast call "<CONTRACT_ADDRESS>" "getPendingMatches()(bytes32[])"

Get match by ID:

cast call "<CONTRACT_ADDRESS>" "getMatchById(uint256)(tuple)" <MATCH_ID>

Get listed nodes:

cast call "<CONTRACT_ADDRESS>" "getListedNodes()(address[])"

Withdraw stake:

cast send --private-key <your_private_key> \
  "<CONTRACT_ADDRESS>" \
  "withdrawStake()"

For DApp Developers

You can integrate the oracle data into your applications:

interface IEsportOracle {
    struct Match {
        uint256 _id;
        Opponents[] _opponents;
        Games[] _game;
        Result[] _result;
        uint256 _winnerId;
        uint256 _beginAt;
    }
    
    function getMatchById(uint256 matchId) external view returns (Match memory);
    function getPendingMatches() external view returns (bytes32[] memory);
}

🧪 Testing

Smart Contract Tests

cd oracle
forge test -vvv

Go Application Tests (need to be implemented)

cd goapp
go test ./...

📁 Project Structure

esport-oracle/
├── oracle/                    # Smart contract components
│   ├── src/
│   │   ├── esportOracle.sol          # Main oracle contract
│   │   └── esportOracleRequester.sol # Request handling extension
│   ├── test/                         # Foundry tests
│   ├── script/                       # Deployment scripts
│   └── docker-compose.yml           # Local deployment
├── goapp/                     # Go data provider
│   ├── cmd/myapp/            # Application entry point
│   ├── internal/
│   │   ├── client/           # API and blockchain clients
│   │   ├── contract/         # Generated contract bindings
│   │   ├── models/           # Data models
│   │   └── service/          # Business logic
│   └── .env.sample          # Environment configuration template
├── .github/                  # GitHub workflows and templates
└── README.md                # This file

🔐 Security Features

• Staking Mechanism: Nodes must stake ETH to participate
• Consensus System: Requires majority agreement for data validation
• Punishment System: Progressive penalties for incorrect submissions
• Node Banning: Automatic banning after 3 violations
• Owner Controls: Administrative functions for emergency situations
• Pausable Contract: Can be paused in case of emergency

🌐 API Integration

The oracle currently integrates with:

• PandaScore API: For CS2 match data, statistics, and tournament information

Data Sources

• Match results and scores
• Team information and rosters
• Tournament brackets and schedules
• Player statistics
• Live match updates

🔧 Configuration

Smart Contract Parameters

• Staking Amount: 0.001 ETH (fixed)
• Maximum Violations: 3 violations before ban
• Punishment Amount: 0.0001 ETH per violation
• Quorum Requirement: >50% of nodes + minimum 3 votes

Go Application Configuration

• Update Frequency: Configurable via CRON_SCHEDULE
• API Rate Limiting: Handled automatically
• Error Handling: Automatic retry with exponential backoff
• Data Validation: Schema validation before submission

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Code Standards

• Solidity: Follow Foundry conventions
• Go: Use gofmt and follow Go best practices
• Commits: Use conventional commit messages
• Testing: Maintain test coverage

📄 License

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

🔗 Links

• Documentation: Foundry Book
• PandaScore API: Documentation
• Support: For questions, contact our team or open an issue

Get involved

You're invited to join this project! Check out the contributing guide.

If you're interested in how the project is organized at a higher level, please contact the current project manager.

Our PoC team ❤️

Developers

[Jules Lordet]	[Gregoire Caseaux]	[Grégor Sternat]	[Aaron Aniambossou]

Manager

[Lucas Leclerc]	[Sacha Dujardin]

Organization

🚀 Don't hesitate to follow us on our different networks, and put a star 🌟 on PoC's repositories

Made with ❤️ by PoC