Arcana

FHE-Powered Prediction Arcade - Provably Fair Gaming

Overview

Arcana is a fully onchain prediction game built on FHERand, demonstrating the power of Fully Homomorphic Encryption (FHE) for provably fair, private gaming. Players make encrypted predictions, and results are generated using cryptographically secure randomness that remains encrypted until reveal.

Features

• Encrypted Predictions - Your predictions stay private until reveal
• Provably Fair - Cryptographically verifiable randomness using FHERand
• USDC Staking - Stake 1-10 USDC per game
• Proximity Rewards - Win based on how close your prediction is:
• Exact match → 2.5× multiplier
• ±1 match → 2× multiplier
• ±2 match → 1.5× multiplier
• Leaderboard - Compete with other players
• Cryptographic Proofs - All results are verifiable on-chain
• Instant Results - No oracle delays, fully onchain

How It Works

Game Flow

1. Predict - Choose a number (0-9) and stake 1-10 USDC
2. Encrypt - Your prediction is encrypted using FHE before submission
3. Generate - Arcana uses FHERand to generate an encrypted random number
4. Reveal - Decrypt your result off-chain to see if you won
5. Claim - Submit proof to claim your rewards on-chain
6. Verify - Contract cryptographically verifies your proof matches the encrypted result

Technical Architecture

• Smart Contracts: Solidity contracts using FHEVM for encrypted operations
• Frontend: React + Vite + Wagmi + Tailwind CSS
• Randomness: FHERand protocol for provably fair random number generation
• Encryption: Fully Homomorphic Encryption (FHE) via FHEVM

Quick Start

Prerequisites

• Node.js >= 20.0.0
• pnpm >= 8.0.0
• A Web3 wallet (MetaMask, WalletConnect, etc.)
• USDC on Sepolia testnet (for testing)

Installation

# Clone the repository
git clone git@github.com:0xNana/arcana.git
cd arcana

# Install dependencies
pnpm install

Frontend Setup

cd packages/frontend

# Copy environment variables
cp .env.local.example .env.local

# Edit .env.local with your configuration:
# - NEXT_PUBLIC_ARCANA_ADDRESS - Arcana contract address
# - NEXT_PUBLIC_USDC_ADDRESS - USDC token address
# - NEXT_PUBLIC_FHERAND_ADDRESS - FHERand contract address
# - NEXT_PUBLIC_SEPOLIA_RPC_URL - Sepolia RPC endpoint

# Run development server
pnpm dev

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

Contract Setup

cd packages/contracts

# Compile contracts
pnpm compile

# Run tests
pnpm test

# Run Arcana-specific tests
pnpm test:arcana

# Deploy to Sepolia (requires .env configuration)
pnpm deploy:sepolia

Project Structure

arcana/
├── packages/
│   ├── contracts/          # Smart contracts
│   │   ├── contracts/
│   │   │   ├── Arcana.sol              # Main game contract
│   │   │   ├── ArcanaTestHelper.sol    # Test helper contract
│   │   │   └── MockUSDC.sol            # Mock USDC for testing
│   │   ├── deploy/          # Deployment scripts
│   │   └── test/            # Contract tests
│   └── frontend/            # React frontend
│       ├── src/
│       │   ├── app/         # App pages
│       │   ├── hooks/       # React hooks
│       │   └── lib/         # Utilities and configs
│       └── public/          # Static assets
├── package.json
└── README.md

Usage

Making a Prediction

import { useArcana } from "@/hooks/useArcana";
import { parseUnits } from "ethers";

const { makePrediction, isPredicting } = useArcana();

// Predict number 5, stake 1 USDC
await makePrediction(5, parseUnits("1", 6));

Viewing Game History

const { getPlayerGames, getGame } = useArcana();

// Get all games for a player
const gameIds = await getPlayerGames(playerAddress);

// Get specific game details
const game = await getGame(gameId);

Viewing Leaderboard

const { getLeaderboard } = useArcana();

// Get top 10 players
const [players, scores, accuracies] = await getLeaderboard(10);

Smart Contracts

Arcana.sol

Main game contract that handles:

• Encrypted prediction submission
• FHERand integration for random number generation
• Cryptographic proof verification
• Reward calculation and distribution
• Player statistics and leaderboard

Key Functions

• predict(externalEuint8 encryptedPrediction, bytes calldata inputProof, uint256 stakeAmount) - Submit an encrypted prediction
• claimRewards(uint256 gameId, uint8 decryptedResult, bytes calldata proof) - Claim rewards with proof
• getGame(uint256 gameId) - Get game details
• getLeaderboard(uint256 count) - Get top players

Development

Running Tests

# Test all contracts
cd packages/contracts
pnpm test

# Test Arcana contract only
pnpm test:arcana

Building

# Build frontend
cd packages/frontend
pnpm build

# Build contracts
cd packages/contracts
pnpm compile

Scripts

# From root directory
pnpm contracts:compile    # Compile contracts
pnpm contracts:test        # Test contracts
pnpm contracts:test:arcana # Test Arcana contract
pnpm frontend:dev         # Run frontend dev server
pnpm frontend:build       # Build frontend

Network Information

Sepolia Testnet

• Chain ID: 11155111
• Gateway Chain ID: 55815 (FHEVM)
• RPC: Use your preferred Sepolia RPC endpoint
• FHEVM Relayer: Configure in .env.local

Security

• All predictions and results are encrypted using FHE
• Cryptographic proofs ensure results cannot be manipulated
• Reentrancy protection via OpenZeppelin's ReentrancyGuard
• Pausable contract for emergency stops
• Ownable for administrative functions

License

BSD-3-Clause-Clear - See LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Learn More

• FHERand Documentation
• FHEVM Documentation

Acknowledgments

Built on:

• FHERand - Provably fair randomness service
• FHEVM - Fully Homomorphic Encryption Virtual Machine

---

Note: This is a demonstration project showcasing FHE-powered gaming.