x402 LOTTERY

x402 LOTTERY Technical Documentation

1. Overview — The Payment Singularity

x402 LOTTERY is a fully autonomous, protocol-native lottery running on Solana. It embodies the HTTP 402 "Payment Required" status code—a reserved but never-implemented standard—by making every lottery entry a direct, machine-to-machine value transfer with no intermediaries.

This is not a traditional web app with a payment gateway. It's a smart contract as the payment endpoint: users send SOL, the program validates and records the entry, updates the jackpot, and schedules the draw—all on-chain, all atomic, all transparent.

"Think of it as a web client and server exchanging value automatically—except the 'server' is a Solana smart contract, and the 'payment' is your lottery entry. Welcome to the 402 web."

2. The 402 Principle

HTTP 402 was reserved in 1997 for future digital payment systems but never standardized. x402 LOTTERY brings this vision to life on Solana:

  • No middlemen: No payment processors, no escrow services—just pure protocol.
  • Atomic transactions: Entry, payment, and state update happen in one transaction.
  • Machine-native: Smart contracts handle everything from entry validation to winner selection.
  • Transparent: All logic, all funds, all draws are verifiable on-chain.

x402 LOTTERY is the realization of what HTTP 402 could have been: a world where value flows as freely as data.

3. High-Level Architecture

x402 LOTTERY runs entirely on Solana, with optional cross-chain mirroring for multi-chain entries.

┌─────────────────────────────────┐
│ USER WALLET (Phantom/etc) │
└──────────────┬──────────────────┘
│ SOL Transfer
▼
┌─────────────────────────────────┐
│ x402 LOTTERY PROGRAM (Solana) │
│ • Entry Validation │
│ • Treasury Management │
│ • Draw Execution │
│ • Winner Selection (VRF) │
└──────────────┬──────────────────┘
│
├──────────┬──────────┬──────────┤
▼ ▼ ▼ ▼
┌────────┐
│Treasury│
└────────┘
┌────────┐
│Jackpot │
└────────┘
┌────────┐
│Entries │
└────────┘
┌────────┐
│Winners │
└────────┘

Key Components:

  • Entry Program: Validates entries, records participants, updates jackpot
  • Treasury: Holds all funds, splits between jackpot and operational reserves
  • Draw Program: Executes draws using Switchboard VRF for randomness
  • NFT Multiplier: Optional boost for holders of x402 NFTs

4. The Treasury–Jackpot Circuit

Every entry payment flows through a deterministic split:

Entry Fee = 0.1 SOL
→ 70% to Jackpot (0.07 SOL)
→ 20% to Treasury Reserve (0.02 SOL)
→ 10% to Protocol Fee (0.01 SOL)

Major Jackpot: Accumulates from all entries, drawn monthly
Minor Jackpot: Smaller pool, drawn every 30 minutes

All splits are hardcoded in the program and executed atomically on every entry.

5. Entry Mechanics

How to Enter:

  1. Connect Phantom wallet to x402lottery.com
  2. Click "BUY TICKETS NOW"
  3. Select quantity (1 ticket = 0.1 SOL)
  4. Approve transaction
  5. Entry is recorded on-chain instantly

Entry Validation:

  • Minimum: 0.1 SOL (1 ticket)
  • Maximum: 10 SOL (100 tickets) per transaction
  • Each entry gets a unique ID and timestamp
  • Entries are immutable once recorded

6. Cross-Chain Payment Mirroring

Future Feature: Users on Ethereum, Base, or other chains can enter by sending ETH/USDC to a bridge contract. The bridge:

  1. Locks funds on source chain
  2. Relays entry to Solana via Wormhole/LayerZero
  3. x402 program records entry with cross-chain flag
  4. Winner payout can be claimed on original chain

This makes x402 LOTTERY the first truly multi-chain lottery where the draw happens on Solana but entries come from anywhere.

7. NFT Multipliers

Holders of x402 NFTs get bonus entries:

  • Lucky Kitsune: 1.5x entries (0.7 SOL)
  • Golden Crane: 3x entries (2.1 SOL)
  • Daruma Doll: 5x entries (3.5 SOL)
  • Oni Trickster: 10x entries (7.0 SOL)

NFTs are verified on-chain during entry. Multipliers stack with base entries.

8. Economic Model

Revenue Streams:

  • 10% protocol fee on all entries
  • NFT sales (primary + royalties)
  • Treasury yield (staking SOL reserves)

Sustainability:

  • 20% of entries go to treasury reserve
  • Reserve ensures jackpot can always be paid
  • Excess reserves fund development and marketing

9. Security Considerations

Randomness: Switchboard VRF provides verifiable randomness for draws

Audits: Program audited by [TBD] before mainnet launch

Upgradability: Program is upgradable via multisig for bug fixes

Fund Safety: Treasury uses PDA (Program Derived Address) with no private key

10. Program Interface

Core Instructions:

enter_lottery(amount: u64, nft_mint?: Pubkey)
→ Records entry, updates jackpot, emits event
execute_draw(draw_id: u64)
→ Requests VRF, selects winner, transfers jackpot
claim_prize(draw_id: u64)
→ Winner claims their jackpot

11. Client API

JavaScript SDK:

import { X402Lottery } from '@x402/sdk'

const lottery = new X402Lottery(connection, wallet)
await lottery.enterLottery(0.1) // 1 ticket
const jackpot = await lottery.getJackpot()

12. HTTP Gateway Specification

REST API Endpoints:

GET /api/jackpot → Returns current jackpot amounts
GET /api/entries → Returns recent entries
GET /api/winners → Returns past winners
POST /api/entry → Submit entry (requires signature)

13. State Machine

Draw States:

  • OPEN: Accepting entries
  • PENDING_VRF: Waiting for randomness
  • SELECTING_WINNER: Processing VRF result
  • COMPLETED: Winner selected, prize claimable
  • CLAIMED: Prize claimed by winner

14. Operational Procedures

Draw Schedule:

  • Minor Draw: Every 30 minutes (automated)
  • Major Draw: Monthly on the 3rd (manual trigger)

Monitoring:

  • Treasury balance alerts
  • VRF failure notifications
  • Entry volume tracking
  • Winner claim monitoring

15. Testing & Simulation

Test Coverage:

  • Unit tests for all instructions
  • Integration tests for full draw cycle
  • Fuzz testing for edge cases
  • Load testing for high entry volume

Devnet Deployment: Fully functional test environment at devnet.x402lottery.com