On-Chain Prediction
Markets on BNB Chain
predictwin.fun is a fully non-custodial prediction market protocol where users buy YES or NO positions directly from their wallet using native BNB. Winnings are calculated on-chain and claimable directly to any wallet no intermediary, no wrap, no withdrawal delay.
Abstract
predictwin.fun is a permission-minimized, on-chain prediction market operating on BNB Smart Chain. The protocol allows any user holding BNB in a compatible wallet to take a directional position YES or NO on real-world binary events. When an event concludes and is resolved, winners receive a proportional share of the entire market pool, minus a fixed 3% platform fee, directly transferred to their wallet address. No accounts, no KYC, no custodial intermediary.
This document is the authoritative technical description of the deployed smart contract logic, the share model, the fee structure, the claim mechanics, and the trust model. It separates unambiguously between what is live in production today and what is planned for future protocol versions.
Every BNB deposited by every participant is held exclusively by the smart contract. No team wallet ever touches user funds. Winnings flow directly from the contract to the winner's wallet at the moment of claim trustlessly and verifiably.
Problem Statement
Traditional prediction markets suffer from a set of deep structural problems that make them inaccessible, opaque, or extractive for ordinary participants. These problems fall into three categories:
Custodial Risk
Most centralized prediction platforms require users to deposit funds into a platform-controlled wallet before trading. This introduces counterparty risk: the platform can freeze withdrawals, become insolvent, or misallocate funds. History is littered with examples of custody failures causing total loss of user capital. predictwin.fun eliminates custody entirely the contract holds funds, not a company.
Opacity and Trust Collapse
Off-chain platforms operate as black boxes. Users cannot independently verify the pool size, the number of participants, the resolution logic, or the fee extraction. This opacity allows platforms to manipulate outcomes, skim undisclosed fees, or simply lie about market states. Every critical data point in predictwin.fun pool sizes, share balances, resolution status, claimed amounts is publicly readable on-chain by anyone.
Access Barriers
Centralized prediction platforms often require account registration, identity verification, geographic restrictions, and fiat on-ramps. This excludes billions of people with smartphones and internet access but without traditional financial infrastructure. predictwin.fun requires only a BNB-compatible wallet and a small amount of BNB the same as any DeFi interaction.
No other platform in this space allows a user to: (a) connect a wallet, (b) buy a YES/NO position with native BNB in a single transaction, (c) have that position and all pool math verifiable on-chain, and (d) claim winnings directly to wallet with zero intermediary steps. This is the specific gap predictwin.fun fills.
Solution Overview
predictwin.fun solves the above problems by placing every meaningful operation on-chain in a single auditable smart contract called PredictionMarket. The design philosophy is:
- Wallet-native interaction. Users send BNB directly from their wallet to the contract. No deposit, no wrapping, no approval step for native BNB.
- Share-based position accounting. Rather than ticket lots, positions are represented as shares in a pool mathematically fair regardless of entry timing.
- Atomic claim transfers. When a winner calls
claimWinnings, the net payout transfers in the same transaction no queuing, no batching delay. - Fully on-chain pool math. All implied odds, pool sizes, and share calculations are computed directly from contract storage no oracle needed for market mechanics.
- Transparent fee extraction. The 3% fee is subtracted at claim time in public code. The accumulated fee balance is publicly readable and withdrawable only through a specific, restricted function.
Live Contract Scope
The following capabilities are confirmed live in the deployed PredictionMarket contract. This section makes no claims beyond what the deployed bytecode and public ABI verify.
| Function | Caller | Status | Description |
|---|---|---|---|
createMarket | Owner | Live | Instantiates a market with events, question string, and duration |
predict | Any user | Live | Buys YES or NO shares; payable BNB routed to side pool |
resolveEvent | Owner | Live | Finalizes a single event outcome (YES or NO) |
claimWinnings | Winners | Live | Transfers net payout from pool to winner wallet |
getYesPriceBps | Read-only | Live | Returns implied YES probability as basis points (0–10000) |
withdrawFees | Owner | Live | Transfers only accumulated collectedFees to owner |
This whitepaper does not describe or imply any functionality not present in the live contract. Features described in Section 16 (Roadmap) are explicitly marked as not yet deployed and are subject to change without obligation.
Market Lifecycle
Every market moves through a strict sequential state machine. No step can be skipped or reversed. The five states are:
Create Phase
The owner calls createMarket(question, eventNames[], durationInMinutes). This stores the question string, initialises each named event with empty YES/NO pools and share counters, and sets endTime = block.timestamp + durationInMinutes * 60. Multiple events can exist within a single market (e.g., a market for a match could have events like "Team A Wins", "Draw", "Over 2.5 Goals"), each independently resolvable.
Open / Trading Phase
Any externally-owned address can call predict(marketId, eventId, choice) and attach BNB as msg.value. The contract validates that the market exists, is not expired, and that the event is not already resolved. The sent BNB is routed to the appropriate side pool (YES or NO) and shares are minted per the formula in Section 5.
There is no minimum buy amount enforced in the current contract beyond the native gas minimum. However, very small positions (under ~0.001 BNB) should be considered inefficient due to transaction gas costs on BNB Chain.
Close Phase
Market closure is automatic and time-based. Once block.timestamp ≥ endTime, the contract rejects any further predict calls for that market. No action by the owner is required to close trading. This prevents manipulation via selective closure timing the on-chain clock is the sole arbiter of trade cutoff.
The constant RESOLVE_BUFFER is currently set to 0. This means resolution can begin immediately after market close, without any enforced waiting window. This is a known trust consideration see Section 12.
Resolve Phase
The owner calls resolveEvent(marketId, eventId, outcome) once per event after the market closes. The outcome is a boolean (YES = true, NO = false). Resolution is permanent and irreversible the contract does not allow re-resolution. Multiple events within one market are resolved independently; resolving one event does not affect others.
Claim Phase
After an event is resolved, any address holding winning-side shares for that event can call claimWinnings(marketId, eventId). The contract computes the gross payout, deducts the 3% fee, zeroes the caller's share balance for that event, adds the fee to collectedFees, and immediately transfers net BNB to msg.sender via a native call. The entire claim operation is wrapped in a nonReentrant guard.
Buy Mechanics (YES / NO Shares)
predictwin.fun uses a proportional share model, not a ticket or fixed-price lot model. This is a critical design choice that ensures every participant regardless of when they buy receives a mathematically consistent representation of their pool ownership.
Share Minting Formula
Where:
- amount the BNB value of msg.value in the current transaction
- sidePool the total BNB accumulated on that side (YES or NO) before this buy
- totalSideShares the total shares already minted for that side before this buy
Why This Model Is Fair
Because the share price (BNB per share) is always equal to sidePool / totalSideShares, the formula simply calculates how many shares the new buyer's BNB amount can purchase at the current pool price. This means:
- Early buyers get the same per-share value as later buyers no first-mover share price advantage.
- Large buyers receive proportionally more shares than small buyers, as expected.
- No per-entry price tracking is needed positions are represented entirely by share count and the pool ratio at claim time.
Importantly, YES and NO sides have completely separate share pools. A user's YES shares represent their fraction of the YES pool, and their payout is computed against the total pool (YES + NO), giving the winning side access to losing side capital.
No Buy Fee
In the current contract, there is no fee charged at buy time. The full BNB amount sent by the user is credited to the side pool. The 3% platform fee is only extracted when a winning position is claimed. This means:
- If you buy and lose, you incur no fee (you've already lost your position BNB).
- If you buy and win, a 3% fee is taken from your gross payout at claim.
- The platform only earns when winners claim an alignment of incentives.
Example Buy Scenario
Implied Odds and Price View
The contract exposes a single read function, getYesPriceBps(marketId, eventId), which returns the implied YES probability expressed in basis points (1 bp = 0.01%). This is a pure pool-ratio calculation and should be interpreted as market sentiment, not a guaranteed payout ratio.
noPriceBps = 10000 − yesPriceBps
Default State
When a market event has zero liquidity on both sides (totalPool = 0), the contract defaults to yesPriceBps = 5000, i.e., 50% implied probability. This prevents division by zero and initializes the market at neutral.
Interpreting the Price
The implied price reflects the current capital-weighted market view on the outcome. If 70% of total capital is on YES, the YES price shows ~7000 bps (70%). This is a live snapshot of pool state, not a locked entry price.
The displayed percentage is the current pool ratio, not your personal payout multiplier. Your actual payout depends on the pool state at resolution time, after all trading has ended. Prices shown during the live window are informational only.
Price Impact of Large Buys
Because price is derived directly from pool ratio, large buys will shift the implied price of both sides. A large YES buy increases the YES pool, reducing the implied payout-per-share for existing YES holders but also shifting the implied probability upward. This is equivalent to slippage in AMM models and is a known property of pool-based markets.
Resolve and Claim Flow
The resolve-to-claim path is the most critical user-facing flow in the protocol. It involves two transactions from two separate actor types: the owner resolving, and the winner claiming. Both operations are on-chain and verifiable.
Resolution
The owner resolves an event by calling resolveEvent(marketId, eventId, outcome). The outcome parameter is a binary boolean. The contract validates:
- Market exists and is past its end time.
- Event is not already resolved.
- Outcome is a valid boolean (not a null or default state).
Once resolved, the event's outcome is locked in contract storage. The specific field becomes readable on-chain, allowing anyone to verify the resolved state before attempting a claim.
Claim Calculation
fee = grossPayout × platformFeeBps / 10000
fee = grossPayout × 300 / 10000 = grossPayout × 0.03
netPayout = grossPayout − fee
netPayout = grossPayout × 0.97
Where totalPool is the sum of the YES pool and NO pool at the time of resolution. Critically, the losing side's capital flows to the winning side this is the incentive structure that makes prediction markets function as a proper information aggregation mechanism.
Post-Claim State
After a successful claim, the contract zeroes the caller's winning-side share balance for that event. This prevents double-claiming. The fee amount is added to collectedFees. The net BNB is transferred to msg.sender via a direct native call. The transfer result is checked if it fails, the transaction reverts, protecting both user and contract state.
Claim Example
Fee Model
predictwin.fun operates a single, transparent, claim-time fee. The design is intentionally simple to prevent hidden or compounding fee layers.
| Fee Type | Rate | Trigger | Notes |
|---|---|---|---|
| Buy Fee | 0% | N/A | Not charged in current contract |
| Platform Fee | 3% (300 bps) | claimWinnings | Deducted from gross payout |
| Resolve Fee | 0% | N/A | Resolution is a free owner action |
| Gas Fees | Variable | Any tx | BNB Chain native gas; not platform-controlled |
Fee Accumulation and Withdrawal
Fees accumulate in a dedicated collectedFees state variable within the contract. This variable is publicly readable. The withdrawFees function transfers only the balance of collectedFees to the owner it does not give the owner access to any other contract balance. This is a critical isolation: protocol fee accounting cannot be exploited as an unrestricted balance sweep.
The withdrawFees function is scoped strictly to collectedFees. Market pool balances the BNB deposited by users are never accessible through this function. The contract enforces this separation in code, not just policy.
Losers and Fees
Users who hold positions on the losing side do not pay any platform fee. Their position BNB is simply forfeited to the winning pool. The platform's 3% is extracted only from winners' gross payouts. This means the protocol generates revenue only when there are winning claimants aligning platform incentives with user success.
Payout Mathematics
Understanding payout mathematics is essential for rational position sizing. The following worked examples illustrate how different pool compositions affect winner returns.
Case 1: Balanced Market
Case 2: Skewed Market (Bet Against Consensus)
Case 3: One-Sided Market
Because winners claim from the entire pool (both sides), a position in a minority pool earns proportionally more per unit of capital but with correspondingly lower implied probability of being correct. This creates a natural market where consensus beliefs become lower-return positions and contrarian positions offer higher potential but lower likelihood returns.
Liquidity Dynamics
Unlike order-book models, pool-based prediction markets have unique liquidity characteristics. Understanding these is important for estimating position impact and return predictability.
Pool Depth and Price Sensitivity
In shallow pools (low total BNB), a moderate buy significantly shifts the implied probability. In deep pools, the same buy has minimal price impact. There is no liquidity provider in the current model liquidity grows organically as participants enter positions. Markets with high participation have more stable pricing and more predictable returns.
Late Entry Dynamics
The share formula ensures late entrants receive proportionally appropriate shares. If you enter a YES pool that is already 2 BNB deep with 0.1 BNB, you receive 0.1 × 2.0 / 2.0 = 0.1 shares, which represents exactly 4.76% of the updated YES pool (0.1 / 2.1). This is the same fractional ownership your BNB entitles you to regardless of when you entered.
No Withdrawal Before Close
The current contract does not support position withdrawal or early exit before market close. Once BNB is committed to a side pool, it is locked until claim (for winners) or forfeited (for losers). This is a design choice to prevent last-minute pool manipulation and ensure stable pool math at resolution time.
Security Model
The contract implements several standard security patterns. Users should understand both what protections exist and what risks remain.
Reentrancy Protection
Both predict and claimWinnings are protected by a nonReentrant modifier from OpenZeppelin's ReentrancyGuard. This prevents an attacker from re-entering the claim function mid-execution to drain the pool through recursive calls. The contract follows a checks-effects-interactions pattern: state is zeroed (shares set to 0) before the native BNB transfer is executed.
Input Validation
The contract validates all critical inputs:
- Market ID existence before any market operation.
- Event ID validity within the given market.
- Market open status before accepting predictions.
- Event resolution status before accepting claims.
- Non-zero share balance before processing claims.
- Correct binary outcome value before resolution.
Transfer Safety
Native BNB transfers in claimWinnings use a low-level .call{value: netPayout}("") pattern with a success check. If the transfer fails (e.g., receiving contract rejects it), the transaction reverts, protecting the contract state. This is preferred over the deprecated .transfer() which has a 2300 gas limit that can cause failures with smart contract wallets.
Fee Isolation
The withdrawFees function is strictly bounded to the collectedFees counter. No code path allows the owner to access user pool funds. This is verifiable in the contract source code and prevents rug-pull via the fee withdrawal vector.
Trust Assumptions
Honest disclosure of trust assumptions is a requirement of responsible protocol documentation. The current design involves the following trust assumptions users must accept:
In the current deployed contract, only the owner address can call resolveEvent. This means outcome finalization is centralized. A malicious or negligent owner could theoretically resolve events incorrectly. This is the most significant trust assumption in the current design and is explicitly acknowledged as a limitation to be addressed in the roadmap.
Trust That Is NOT Required
- Custody trust. The owner cannot access user pool funds. Code-enforced.
- Fee correctness. The fee rate (300 bps) is immutable in the contract and publicly readable. The owner cannot dynamically change fees on live markets.
- Pool accounting. Pool balances and share counts are on-chain and independently verifiable by anyone with a BNB Chain RPC endpoint.
- Claim accuracy. The claim formula is hardcoded in the contract. The owner cannot modify per-user payouts.
Resolution Risk Mitigation (Current)
While the current design is owner-resolved, several factors partially mitigate this risk in practice: resolution transactions are public on-chain and observable, the protocol's reputation depends on honest resolution, and market questions are designed to have clear, verifiable real-world outcomes. Users should size positions accordingly given the current trust model.
Wallet-Native Design
The most fundamental design principle of predictwin.fun is that the entire user flow entry, position holding, and payout is conducted through a standard BNB wallet. This section explains what that means in practice.
Direct BNB Transfer Model
When a user buys a position, they send native BNB as msg.value in the predict call. There is no ERC-20 approval step, no token wrapping, no intermediate custody wallet. The BNB goes directly from the user's wallet to the contract's pool in a single transaction.
This is structurally simpler than most DeFi protocols, which require token approval transactions before any interaction. The UX is: connect wallet → choose YES/NO → enter BNB amount → confirm transaction. Done.
Claim Directly to Wallet
When a winner calls claimWinnings, the net BNB payout transfers atomically to msg.sender the same wallet address that made the winning prediction. There is no pending withdrawal queue, no multi-step withdrawal process, no "available balance" buffer system. The BNB appears in the winner's wallet in the same block as the claim transaction.
At no point in the predictwin.fun flow does any entity other than the smart contract hold user funds. The protocol team cannot initiate transfers of user capital. Only the user's own wallet signature can trigger a claim. The contract is the sole custodian and its logic is public, immutable, and auditable.
Compatible Wallets
Any wallet that supports BNB Smart Chain (BSC, chainId 56) and can interact with smart contracts is compatible. This includes MetaMask, Trust Wallet, Binance Web3 Wallet, OKX Wallet, Rabby, and all WalletConnect-compatible wallets. No proprietary wallet, browser extension, or custodial account is required.
App and Data Layer
The predictwin.fun web application provides a user interface over the on-chain protocol. Understanding the distinction between what the app displays and what the contract holds is important for users who value on-chain finality over UI convenience.
Authoritative vs. Convenience Data
The authoritative source of truth for all balances, shares, pool sizes, resolution status, and payouts is the on-chain contract state. The app also maintains an off-chain activity layer for fast display of transaction history, portfolio views, and market timelines this is a UX convenience layer, not a financial record.
On-Chain Fallback
When off-chain indexed data is delayed, stale, or missing (due to indexer lag, RPC downtime, or cache misses), the app is designed to fall back to direct on-chain event reads for correctness. A user's share balance readable from the contract is always the authoritative balance, regardless of what the UI portfolio view shows.
Emitted Events
The contract emits standard Solidity events for all state changes: market creation, prediction placements, resolutions, and claims. These events are indexed by the off-chain layer and are independently verifiable via any BNB Chain block explorer (e.g., BscScan) without using the predictwin.fun app at all.
Why BNB Chain
The choice of BNB Smart Chain as the deployment network was deliberate and optimized for the protocol's primary use case: frequent, low-value, rapid-settlement predictions.
| Property | BNB Chain | Relevance |
|---|---|---|
| Block Time | ~3 seconds | Near-instant position confirmation |
| Avg Gas Cost | ~$0.05–$0.30/tx | Small positions remain economically viable |
| EVM Compatibility | Full | Works with all EVM wallets and tools |
| Native Token | BNB | High liquidity, wide wallet support |
| Ecosystem | Large DeFi/consumer base | Accessible to a large existing user base |
| Stability | Mature, since 2020 | Well-tested infrastructure for financial apps |
Lower gas costs are particularly important for prediction markets because users often take positions as small as 0.01–0.1 BNB. On high-fee networks, gas costs would represent an outsized fraction of position size, making small-stake predictions economically unviable. BNB Chain makes the protocol accessible to a far broader range of participants.
Future Roadmap Not Yet Live
Every item in this section is a planned future direction only. None of the features below are live in the current deployed contract or application. They are subject to change, re-prioritization, or cancellation without notice. This section is included for informational purposes about development intent only.
Decentralized Oracle / Resolver
The highest priority roadmap item is replacing the centralized owner resolution model with a decentralized oracle or multi-sig resolver. Candidate approaches include integration with Chainlink Functions for sport result feeds, a dispute-challenge resolution model similar to UMA or Kleros, and a quorum-based multi-sig resolution with time-delayed finalization windows. Eliminating the single point of trust in resolution is the key step toward full permissionlessness.
Dispute Windows and Delayed Finalization
Future contracts will include a configurable RESOLVE_BUFFER a mandatory waiting period after market close before resolution is accepted. Additionally, a dispute window will allow token-weighted challenges to a proposed resolution before it becomes final. This adds a layer of decentralized oversight to outcome finalization.
Position Cash-Out / Early Exit
A potential future feature is the ability for users to exit positions before market close, receiving a value based on current pool ratio minus a liquidity fee. This requires significant additional contract complexity and careful economic modeling to prevent manipulation, but would meaningfully improve capital efficiency for users.
Limit-Style Entries
Rather than immediate pool entry at current ratio, limit orders would allow users to specify a maximum entry price (implied probability). If the pool ratio exceeds their limit at execution time, the transaction would revert or queue. This protects users from high-slippage entry on shallow pools.
PWIN Token (Governance and Utility)
A native protocol token is in long-term planning for governance participation (fee rate votes, resolver election), fee rebates for high-volume participants, and staking rewards funded from protocol fee revenue. Token design and distribution mechanics have not been finalized and no token has been deployed as of this whitepaper version.
Analytics and Market Reporting
Future versions of the app layer will expose transparent market-level reporting: total volume per market, resolution accuracy history, pool depth over time, and historical implied probability charts. All data will be independently verifiable against on-chain events.
Summary
predictwin.fun is a live, operational, non-custodial prediction market on BNB Smart Chain. Its design is grounded in a single core promise: every user interacts directly from their own wallet, every position is on-chain, and every winning payout transfers directly back to the winner's wallet no intermediary, no account, no custody.
The current protocol is deliberately scoped and honest about its limitations. Owner-driven resolution is the primary trust assumption users must accept today. It is the primary item on the decentralization roadmap. In the meantime, fee isolation, reentrancy protection, transparent pool math, and direct-to-wallet payouts give users a reliable and verifiable foundation.
This document reflects the current on-chain implementation faithfully and separates roadmap items from live functionality. Readers should treat it as a technical specification, not as financial advice or a promise of future features. The authoritative source of truth for protocol behavior is always the deployed smart contract code.