Architecture

LightChallenge is a full-stack Web3 protocol with smart contracts, off-chain services, a webapp, and a mobile evidence collector.

Repository Structure

lightchallenge/
├── contracts/           # Solidity smart contracts
├── deploy/              # Hardhat deploy scripts
├── offchain/            # TypeScript off-chain services
│   ├── adapters/        # Evidence source adapters (OpenDota, Riot, etc.)
│   ├── connectors/      # Data provider connectors (Apple, Strava, Garmin)
│   ├── db/              # Database access layer
│   ├── evaluators/      # Evidence evaluation logic
│   ├── identity/        # Identity binding registry
│   ├── indexers/        # On-chain event indexers
│   ├── lib/             # Shared utilities
│   └── workers/         # Polling worker processes
├── webapp/              # Next.js 14 web application
│   ├── app/             # App router pages and API routes
│   ├── lib/             # Client-side utilities
│   └── public/          # Static assets, ABIs, deployments
├── mobile/ios/          # iOS HealthKit evidence collector
├── db/                  # Database migrations and seed scripts
├── schemas/             # JSON schemas for challenge rules
├── scripts/             # Deploy, admin, and operations scripts
└── docs-site/           # Documentation portal (Nextra)

Smart Contracts

Challenge Lifecycle (ChallengePay V1)

Active → (proof submitted) → Finalized (Success/Fail)
Active → (deadline passed) → Finalized (Expired)
Active → (admin cancel)   → Canceled → Refundable

Verification Path

The active verification path uses ChallengePayAivmPoiVerifier, which:

1. Receives a proof submission containing an AIVM inference result
2. Verifies the result was finalized by the Lightchain AIVM network (PoI consensus)
3. Calls ChallengePay.finalize() with the verified outcome

Off-chain Services

Workers

Indexers

Database

PostgreSQL (Neon) with tables for challenges, participants, evidence, verdicts, AIVM jobs, identity bindings, and claims.

Lightchain AIVM Integration

LightChallenge is a client of the Lightchain AIVM network:

1. Request — Our challengeWorker submits an inference request via requestInferenceV2()
2. Process — Lightchain native workers commit, reveal, and attest results
3. Finalize — The network emits InferenceFinalized when quorum is reached
4. Bridge — Our aivmIndexer catches the event and calls submitProofFor() + finalize() on ChallengePay

We do NOT run AIVM workers or validators — the Lightchain network handles verification independently.

Webapp

Next.js 14 with App Router. Key pages:

Wallet Integration

• wagmi v2 for chain interaction
• RainbowKit for connect UI
• WalletConnect v2 for mobile wallets and Safari
• Supports: MetaMask, WalletConnect, Coinbase Wallet, Rainbow, Trust Wallet, Phantom