# IBVM Lottery Play the on-chain lottery using tIBVM tokens — with smart contract prize distribution, referral rewards, and verifiable draws on the IBVM Network. IBVM Lottery is a provably fair, non-custodial lottery protocol built natively on the IBVM. Players purchase numbered tickets using IBVM — the native token of the IBVM Network — and compete for a three-tier prize pool drawn and settled entirely on-chain. No server, no trust, no hidden draws. Every ticket, every number, and every reward distribution is verifiable on-chain via the IBVM block explorer. Whether you are a casual player buying a single ticket or a frequent participant running a referral network — IBVM Lottery handles it all from a single unified interface. *** ### Key Features #### Verifiable On-Chain Draws Every lottery round is governed by a deployed smart contract on the IBVM. Ticket purchases, prize pool accumulation, winning number draws, and reward distributions all happen on-chain and are fully auditable. The platform holds no funds and has no ability to override contract rules or alter drawn numbers. #### Three-Tier Prize Structure Prizes are distributed across three match brackets based on how many leading digits of a player's ticket number match the drawn winning number. Matching more digits wins a proportionally larger share of the prize pool. All bracket percentages are set on-chain when the round starts and cannot be changed mid-round. #### Bulk Purchase Discounts Players buying multiple tickets in a single transaction receive an automatic discount calculated by the contract's discount divisor parameter. The more tickets purchased at once, the larger the percentage saved. The exact discount is displayed in the interface before any wallet interaction. #### Referral Reward System A first-class on-chain referral system lets participants earn from every ticket purchase made by their referral tree. Referrers are registered and rewarded at the contract level — not tracked off-chain — so referral rewards are always calculated accurately and distributed automatically from the round's referral fee pool. #### Real-Time Prize Pool Visibility The current prize pot, ticket price, countdown to draw, and the full fee breakdown are all fetched live from the contract and displayed before any wallet interaction. Players always see exactly what they are entering and what they stand to win. #### Non-Custodial by Design Private keys never leave the player's wallet. All transactions are signed and broadcast directly through the connected wallet. The platform never stores keys, seeds, or custody over any assets. #### Admin-Controlled Round Lifecycle Each lottery round is explicitly started and closed by the protocol administrator via separate on-chain transactions. Admins configure all round parameters — pricing, fees, reward brackets, end time — at the moment of start. After the round closes, the admin draws the final number on-chain to make prizes claimable. #### Multi-Wallet Support Connect any major EVM wallet through the Reown AppKit integration. MetaMask, Coinbase Wallet, WalletConnect-compatible wallets, and hardware wallets through AppKit are all fully supported. *** ### How It Works #### 1. Connect Your Wallet Click **Connect Wallet** and select your preferred wallet. IBVM Lottery uses Reown AppKit, so any WalletConnect-compatible wallet works in addition to injected providers like MetaMask and Coinbase Wallet. Once connected, your tIBVM balance is displayed in the header. If the connected network is not IBVM, the app will prompt you to switch. You can add the IBVM to your wallet automatically from within the app. #### 2. Review the Active Round The main screen displays all live round information pulled directly from the contract: * Current prize pot (total IBVM locked so far) * Ticket price for the active round * Time remaining until the draw * Reward breakdown by match tier #### 3. Buy Tickets Click **Buy Tickets** and enter the number of tickets you want to purchase. The interface will: * Generate random 3-digit ticket numbers (100–999) for each ticket * Let you manually edit any number before confirming * Show the full cost breakdown including bulk discount and final price in IBVM * Allow you to input a referrer address if you arrived via a referral link Once you confirm, a single wallet transaction purchases all tickets and locks your IBVM into the prize pool. #### 4. Wait for the Draw After the round's end time passes, the administrator closes the round and draws the final winning number on-chain. This is a two-step admin process: 1. **Close Lottery** — Transitions the round from Running to Closed 2. **Draw Final Number** — Draws the winning number and transitions to Claimable Both steps emit on-chain events visible on the IBVM block explorer. You do not need to take any action during this phase. #### 5. Check If You Won Click **Are you a winner? Check Now**. The app queries your full ticket history against all completed rounds and identifies any winning tickets, grouped by match bracket. Results are displayed with the prize amount claimable for each ticket set. #### 6. Claim Your Reward For each lottery round where you hold winning tickets, click **Claim**. The contract verifies your ticket numbers against the drawn number, confirms your match bracket, and releases your share of the prize pool directly to your wallet. *** ### Winning Criteria Ticket numbers are 3-digit values ranging from 100 to 999. The drawn winning number is also a 3-digit value. Prizes are awarded based on how many digits match from the **first (leftmost) digit** in sequence: | Match | Bracket | Prize Share | | --------------------- | --------- | --------------------------------------- | | First 1 digit matches | Bracket 1 | rewardsBreakdown\[0]% of net prize pool | | First 2 digits match | Bracket 2 | rewardsBreakdown\[1]% of net prize pool | | All 3 digits match | Bracket 3 | rewardsBreakdown\[2]% of net prize pool | | No match | — | No prize | **Example**: If the winning number is **4 7 3** and your ticket is **4 7 8**, you match the first 2 digits and win a Bracket 2 prize. If your ticket is **4 0 1**, you match only the first digit and win a Bracket 1 prize. Bracket percentages are set by the admin at round start and are readable directly from the contract. *** ### Fee Structure Every lottery round has three fee components, all configured on-chain at round start and publicly readable from the contract: | Fee Component | Description | Mechanism | | ------------- | ----------------------------------------------- | ---------------------------------------------------------- | | Treasury Fee | Protocol fee deducted from the gross prize pool | On-chain, basis points (e.g., 500 = 5%) | | Referral Fee | Distributed to the referral reward pool | On-chain, basis points (e.g., 1000 = 10%) | | Bulk Discount | Reduces the cost for multi-ticket purchases | Applied automatically by contract based on discountDivisor | **Net prize pool = Total prize pot − Treasury fee − Referral fee** The net prize pool is then split across the three match brackets according to the rewards breakdown percentages. All calculations are displayed in full before any wallet transaction. *** ### Referral System IBVM Lottery includes an on-chain referral registry. Any player can participate as a referrer and earn from their referred players' activity. #### How Referral Works 1. A player with an existing account shares their wallet address as a referral link parameter (`?Referrer=
`) 2. A new player who arrives via that link and has no existing referrer on-chain will have the referrer registered on their first ticket purchase 3. The referrer relationship is stored permanently on-chain 4. A portion of each referred player's ticket purchase contributes to the referral fee pool, which is distributed to referrers *** ### User Roles | Role | Capabilities | | ------ | --------------------------------------------------------------------------------------------------------------------------- | | Player | Connect wallet, buy tickets, view history, check winners, claim rewards, participate in referral program | | Admin | Start new lottery rounds with full parameter configuration, close active rounds, draw final numbers, manage round lifecycle | *** ### Lottery Round Lifecycle ``` RUNNING (Status 1) │ Players buy tickets, prize pool accumulates ▼ CLOSED (Status 2) │ Admin calls closeLottery() after end time ▼ CLAIMABLE (Status 3) Admin calls drawFinalNumberAndMakeLotteryClaimable() Players can now claim rewards ``` *** ### Smart Contract #### Lottery Contract The primary contract deployed on IBVM. Handles all round logic: ticket purchases, prize pool management, winning number draws, and reward distribution. | Function | Description | | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | `startLottery(endTime, ticketPrice, discountDivisor, rewardsBreakdown[], treasuryFee, referralFee)` | Admin — start a new lottery round | | `buyMultiCoinTickets(lotteryId, ticketIds[], tokens[], details[], parent)` | Player — purchase one or more tickets | | `closeLottery(lotteryId)` | Admin — close a running round | | `drawFinalNumberAndMakeLotteryClaimable(lotteryId, autoInjection)` | Admin — draw winning number and open claims | | `claimTickets(lotteryId, ticketIds[], brackets[])` | Player — claim prizes for winning tickets | | `calculateTotalPriceForBulkTickets(discountDivisor, ticketPrice, numberOfTickets)` | Read — calculate total cost with bulk discount | | `viewCurrentLotteryId()` | Read — get the ID of the active round | | `viewLottery(lotteryId)` | Read — fetch full details of a specific round | | `viewUserInfoForLotteryId(address, lotteryId, cursor, size)` | Read — fetch a player's tickets for a specific round | *** ### Supported Network | Network | Chain ID | RPC Endpoint | Explorer | | ------------ | -------- | ----------------------------------------------------------- | ----------------------------------------------------------- | | IBVM Testnet | 2107 | [https://rpc-testnet.ibvm.io](https://rpc-testnet.ibvm.io/) | [https://testnet.ibvmscan.io](https://testnet.ibvmscan.io/) | *** ### Supported Wallets | Wallet | Connection Method | | ---------------- | ------------------------------- | | MetaMask | Injected provider | | Coinbase Wallet | Injected provider | | Any EVM wallet | Reown AppKit / WalletConnect v2 | | Hardware wallets | Reown AppKit | *** ### Token **IBVM** is the native currency of the IBVM Network, used for all ticket purchases and prize distributions within IBVM Lottery. * **Decimals**: 18 * **Network**: IBVM Testnet (Chain ID: 2107) * **Use**: Ticket payment, prize receipt, referral reward distribution Testnet tIBVM carries no real-world monetary value and is used exclusively for testnet participation. *** ### Get Started Access IBVM Lottery and connect your EVM wallet to view the active round and purchase tickets. Testnet users can acquire tIBVM from the IBVM faucet and participate in the full lottery flow — including buying tickets, waiting for the draw, and claiming rewards — at zero real cost. Referrers can begin sharing their wallet address immediately after connecting. No registration required. **Launch IBVM Lottery →** --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://ibvm.gitbook.io/ibvm-doc/ibvm-lottery.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.