QanVaultDocs
Launch App
Technical Whitepaper & Smart Contracts

System Architecture & Specs

This technical specification details the smart contract topology, state machine invariants, and off-chain keeper architecture governing the QanVault protocol.

High-Level Contract Topology#

Client Layer

Player / Frontend UI

Supports BNB, ETH, USDT, USDC, or Any Token on BSC and Ethereum

Ethereum Mainnet (Chain 1)
Uniswap v3 Swap Router & Symbiosis Bridge

Exact-output swap for ANY ERC-20 token + subsidized 1.0% bridge fee to BSC

BNB Smart Chain (Chain 56)
PancakeSwap v3 Swap Router

Native BSC QANX (0% fee) or exact-output swap for ANY BEP-20 token with dust refund

Canonical Settlement Engine

EverpotCore.sol (BNB Smart Chain)

Contiguous Range Indexing
Draw State Transitions
Commit-Reveal Verifier
Non-Custodial Treasury
PrizeEscrowVault.sol

Segregated 5-bucket ledger with 100% mathematical solvency invariant

Provably Fair Entropy
IRandomnessProvider.sol

Quantum-resistant commit-reveal & VRF randomness generation

Core Smart Contracts#

1. EverpotCore.sol

The central coordinator managing ticket registration, range assignments, and draw lifecycle transitions:

  • Maintains the global ticket counter: totalTicketsMinted.
  • Maps ranges to owners using the compact TicketBatch struct.
  • Exposes purchaseTickets(address recipient, uint256 count) and claimPrize(uint256 drawId).
  • Verifies winner selection using binarySearchBatch(uint256 winningTicketId).

2. PrizeEscrowVault.sol

A non-custodial treasury contract holding all escrowed tokens:

  • Maintains segregated balances for Daily D, Daily D+1, Weekly W, and Monthly M prize pots.
  • Enforces the 10,000 bps invariant on all fund transfers.
  • Only permits payouts when authorized by EverpotCore during valid claim execution.

3. MultiChainRouter.sol

Handles DEX routing and multi-asset execution:

  • Quotes input amounts using Uniswap v3 and PancakeSwap v3 SDKs.
  • Pulls player tokens, executes exact-output swaps, and forwards precisely 100 QANX per ticket to EverpotCore.
  • Returns unspent token dust to the sender atomically in the same transaction block.

4. IRandomnessProvider.sol

An abstracted interface decoupling the prize engine from specific oracle providers:

  • Supports commit-reveal hash commitments.
  • Compatible with Chainlink VRF v2.5.
  • Future-proofed for native QAN Platform post-quantum lattice consensus.

Draw State Machine#

Each draw transitions through four deterministic lifecycle phases:

Phase 1OPEN

Tickets can be purchased; range records increment sequentially until 23:59:59 UTC cutoff.

Phase 2COMMITTED

Keeper submits secret seed hash commitment H. Ticket sales lock for this draw period.

Phase 3REVEALED / FINALIZED

Keeper submits secret seed S. Contract verifies H == keccak256(S) and derives winning ticket ID with O(log B) search.

Phase 4CLAIMED or ROLLED OVER

Winners have 72 hours to claim. If unclaimed, 100% of funds automatically roll over to seed future jackpots.

Autonomous Keeper Infrastructure#

To ensure that draws occur precisely at 00:00:00 UTC without requiring manual human intervention, decentralized keeper bots run on automated schedules:

  • Daily Draw Keeper (00:00:00 UTC):
  1. Calls commitDraw(dailyDrawId, hashCommitment).
  2. Waits for block confirmation.
  3. Calls revealDraw(dailyDrawId, secretSeed).
  • Rollover Keeper (Hourly):

Scans all finalized draws where block.timestamp > finalizedAt + 72 hours and claimed == false, invoking triggerRollover(drawId) to redistribute unclaimed balances.

Next Steps#

PreviousUSDT Payments & DEX SwapsNextSolvency & Escrow Proofs