YumeBet Whitepaper

Abstract

YumeBet is a permissionless prediction market protocol built on the Sui blockchain. It allows any wallet to stake YES or NO on objective, time-bounded outcomes and earn pro-rata payouts from the losing pool. Markets are created and resolved by an on-chain bot operator using multi-source oracle validation, with an admin-gated dispute path and a seven-day auto-cancel safety net for stale cases.

The protocol charges a 7% settlement fee, split between liquidity stakers (3%), treasury (2.5–4%), and the market creator (0–1.5%) depending on creation path. NFT holders of the Yume Spirits collection stake for a share of both market fees and secondary market royalties.

This document describes the protocol architecture, market mechanics, fee model, NFT system, oracle design, community structure, and governance model for V1 Mainnet.

---

1. Introduction

Prediction markets have consistently produced more accurate probability estimates than expert polls, media consensus, or quantitative models. Despite this track record, crypto-native prediction markets have struggled to achieve sustained traction — burdened by complexity, poor UX, opaque settlement, or fragile oracle designs.

YumeBet is built to be the prediction market that a crypto-native user actually wants to use. It starts from three first principles:

1. Transparency over trust. Every fee split, every resolution, every oracle reading is on-chain and auditable. Settlement math is visible in the contract code.

1. Speed over deliberation. Markets resolve automatically using cross-validated oracles. Most markets complete without any human involvement.

1. Ownership over access. Positions are wallet-native. Staking rewards accrue on-chain. The Yume Spirits NFT collection gives holders a structural stake in the protocol's revenue.

YumeBet launches on Sui for its object-centric model, low gas costs, and high throughput — qualities that make short-duration markets (5 and 15 minutes) economically viable at the base layer.

---

2. Protocol Architecture

YumeBet is a 14-module Sui Move package. The modules separate concerns cleanly so each piece can be upgraded independently.

2.1 Core Modules

2.2 Shared Object Graph

YumeBetAdmin (shared)
├── pause flag
├── approved template list
├── market count
└── capability epoch (for revocation)

RewardVault (shared)
├── winner_escrow_balance
├── staker_fee_balance
├── treasury_fee_balance
├── quarantined_no_staker_rewards
└── royalty staker index

StakingRegistry (shared)
└── staked NFT positions (NFT ID → owner, rarity)

Market (shared, per market)
├── YES pool, NO pool, bond balance
├── position count, pool totals
├── status, winning outcome
└── fee accounting

MintRegistry (shared)
├── rarity map (2,222 bytes)
├── mint phase, allowlist
└── per-wallet count map

---

3. Prediction Market Mechanics

3.1 Market Structure

Each market asks a binary question with an objective, measurable outcome. Examples:

• "Will BTC close above $100,000 on June 1, 2026?"
• "Will the SUI/USD price be ≥ $3.00 at close?"
• "Will the floor price of [Collection] exceed 5 SUI within 24 hours?"

Every market has:

• A close time — when new deposits stop
• A resolution time — when the oracle reads final price
• A template ID — links to an approved market category
• A comparison operator — ≥ (GTE) or < (LT)
• A target value — the threshold being compared

3.2 Participation

Any wallet deposits at least 0.1 SUI on YES or NO while the market is OPEN. Each deposit creates a Position — a soulbound receipt object held in the depositor's wallet. Positions cannot be transferred, listed for sale, or burned. Only the original depositor can claim or refund.

Payout formula (parimutuel):

payout = deposited_amount × (total_winner_pool / total_winning_side_deposits)

Example: Market resolves YES. Total YES deposits = 100 SUI, Total NO deposits = 200 SUI, total pool = 300 SUI. After 7% fee: winner pool = 279 SUI. A user who deposited 10 SUI on YES receives 10 × (279 / 100) = 27.9 SUI.

3.3 The Zero-Winners Edge Case

If the winning side has zero deposits at resolution (nobody bet on the correct outcome), the winner pool is redirected to the treasury. No funds are stranded. Depositors on the losing side cannot claim — their funds formed the pool.

3.4 Market Duration

Bot-created markets can run as short as 5 minutes (e.g., the next 15-minute price candle). User-created markets enforce a 1-hour minimum to ensure adequate participation time.

3.5 Market Templates

V1 allows market creation only from admin-approved template IDs. Templates define the category and resolution method. Approved templates at launch:

Custom templates are planned for V2.

---

4. Market Creation Paths

4.1 Bot Path (Automated)

The protocol operator runs a Cloudflare Worker with a MarketCreatorCap capability. The bot:

1. Reads the approved template schedule
2. Constructs market parameters (close time, resolution time, target value, oracle sources)
3. Calls market_factory::create_market on-chain

Bot markets carry no bond (the operator is trusted by the protocol) and pay no creator fee at resolution. All excess beyond the staker 3% goes to treasury (4%).

Scheduled drops:

• 5-minute price markets — perpetual BTC, ETH, SUI price markets running around the clock
• 15-minute price markets — mid-range duration with higher target values
• Thursday weekly markets — 6 markets per Thursday with 7-day durations on SUI ecosystem narratives
• SUI ecosystem markets — governance votes, TVL milestones, project launches (created when events warrant)

4.2 User Path (Permissioned by Bond)

Any wallet can create a market by posting a 5 SUI bond. Bond mechanics:

• Bond is held in the market's bond_balance field until settlement
• Market resolved cleanly → bond returned to creator
• Market cancelled or auto-cancelled → bond slashed to treasury

User-created markets earn the creator a 1.5% fee at resolution, paid directly to the creator address.

4.3 Tradeport Integration (BETA)

Bot markets can also source resolution data from Tradeport's GraphQL API (https://api.tradeport.xyz/graphql) for Sui NFT collection floor prices and 24-hour volumes. These markets carry a BETA label in the UI.

Failure handling: if Tradeport returns no data at resolution time, the market is automatically marked NeedsReview. If admin does not resolve within 7 days, the watchdog auto-cancels it.

Reliability threshold: if the Tradeport failure rate over any rolling 30-day window exceeds 10%, the template is suspended pending investigation.

---

5. Oracle System

YumeBet uses a two-source cross-validation model. Every auto-resolution requires agreement between a primary and fallback oracle.

5.1 Oracle Sources

5.2 Auto-Resolution Criteria

The resolver bot executes resolve_market only if both conditions hold:

1. Confidence ≥ 90 — the resolver's internal confidence score (0–100) based on data freshness, source availability, and price stability
2. Source agreement within 1% — primary and fallback readings must be within 1% of each other (|p1 - p2| / p1 ≤ 0.01)

If either condition fails, the bot calls mark_needs_review and logs the reason.

5.3 Resolution Snapshots

Before calling resolve_market, the bot publishes a ResolutionSnapshot object on-chain. The snapshot contains:

• The market ID it applies to
• The oracle-computed outcome (YES or NO)
• Signing authority (the bot's address)

The contract validates that the snapshot's computed_outcome matches the winning_outcome argument passed to resolve_market. The bot cannot pass an outcome that contradicts its own published snapshot.

After resolution, the snapshot object is deleted (consume_snapshot).

5.4 Dispute Path

A market in NeedsReview status can be:

• Resolved by the admin using resolve_market_by_admin (AdminCap required)
• Cancelled by the admin using cancel_market
• Auto-cancelled by anyone after 7 days via auto_cancel_stale

Auto-cancel is callable by any wallet with no capability — it is a permissionless safety net, not an admin operation.

---

6. Fee Model

6.1 Settlement Fee — 7% of Total Pool

All settlement fees are computed at resolution from total_pool_mist (the sum of all YES and NO deposits).

Fee constants are in basis points (out of 10,000). Winner share = 9,300 bps, staker = 300 bps, treasury bot = 400 bps, treasury user = 250 bps, creator = 150 bps.

6.2 Fee Flow at Resolution

1. Winner pool (93%) goes into RewardVault.winner_escrow_balance — claimable per position
2. Staker fee (3%) distributed across all active stakers pro-rata by staking weight
3. Treasury fee routed directly to RewardVault.treasury_fee_balance
4. Creator fee (1.5%, user markets only) transferred immediately to the creator's wallet at resolution

6.3 NFT Royalties — 10% Target

Secondary market royalties (10% of sale price) are deposited by compliant marketplaces via a RoyaltyDepositorCap:

• 50% → NFT stakers (added to the royalty reward index)
• 50% → treasury

Target marketplaces at launch: Tradeport and BlueMove. Royalty enforcement is opt-in (honor system in V1).

6.4 No-Staker Quarantine

If no NFTs are staked at the time a market resolves, the 3% staker fee is quarantined in RewardVault.quarantined_no_staker_market_rewards_mist. It is non-claimable in V1 and does not roll into treasury. This edge case is expected only in the earliest hours after deployment.

6.5 Treasury Withdrawals

The admin calls reward_vault::admin_withdraw_treasury with an AdminCap to withdraw SUI from the treasury balance. Every withdrawal emits a TreasuryWithdrawn event, which the indexer records and the admin dashboard surfaces in real time.

---

7. Yume Spirits NFT Collection

7.1 Overview

Yume Spirits are the protocol's 2,222-piece NFT collection. In the YumeBet mythology, Spirits are dream oracles — entities that perceive the arc of events before they unfold. Staking them earns a structural share of protocol revenue.

Practically: a staked Yume Spirit is a claim on 3% of every market settlement and 50% of all secondary royalties, forever, pro-rata by rarity weight.

7.2 Supply and Rarity

Rarity is pre-seeded into the MintRegistry.rarity_map before mint opens. Every token ID maps to a fixed rarity tier — no reveal randomness exploits possible.

7.3 Mint Allocation

Per-wallet cap: 20 NFTs across all phases combined.

Mint phases are set by the admin:

• Phase 0 (Closed) — default, no minting
• Phase 1 (Allowlist) — only wallets on the allowlist can mint at the allowlist price
• Phase 2 (Public) — open mint at the public price

Mint proceeds go directly to treasury.

7.4 Soulbound NFT Design

YumeSpirit objects are defined with has key only (no store). They cannot be listed on secondary markets in V1. The protocol uses Sui's display standard for metadata; rarity is an on-chain field accessible to any marketplace or aggregator.

Secondary transfers require marketplace integration via the protocol's transfer policy hooks (planned for V1 Mainnet).

7.5 Art and Metadata

Artwork is generated using the HashlLips art engine with custom trait layers. Traits are layered in order: Background → Body → Eyes → Mouth → Accessory → Aura. Rarity of the minted token is on-chain; visual trait rarity is reflected in the generative art but not separately indexed in V1.

Metadata URL pattern: https://yumebetdev.github.io/yumebet-assets/json/{N}.json Image URL pattern: https://yumebetdev.github.io/yumebet-assets/images/{N}.png

Post-reveal: URLs migrate to Arweave for permanent, decentralised hosting. GitHub Pages remains as a CDN fallback.

---

8. NFT Staking

8.1 How Staking Works

1. Wallet calls nft_staking::stake(spirit, registry, ctx) — the Spirit moves into the StakingRegistry shared object
2. The staker's address and the Spirit's rarity tier are recorded
3. Staking is immediate — no lockup, no minimum duration

To unstake: call nft_staking::unstake(spirit_id, registry, ctx). The Spirit is returned to the wallet. Any unclaimed rewards remain claimable after unstaking.

8.2 Reward Accrual

The reward index (RewardVault) tracks a global staker_reward_per_point value. Each time a market resolves, the 3% staker fee is added to the vault and the index is bumped:

staker_reward_per_point += staker_fee_mist / total_staking_points

A staker's pending reward = (current_index - entry_index) × staker_weight.

Rewards are claimed via reward_vault::claim_staker_rewards. No lockup. Claims can happen at any time.

8.3 Royalty Rewards

Royalty deposits follow the same index mechanism but in a separate royalty_staker_reward_per_point accumulator. Stakers receive both market fee rewards and royalty rewards from a single claim call.

8.4 Staking Points Reference

With 2,222 total NFTs at full stake:

Actual staking points vary based on what fraction of the collection is staked at any given time.

---

9. Discord Community & Allowlist System

9.1 Community Roles

9.2 Allowlist Qualification

WL slots are earned through Discord activity, early supporter status, and community contribution. The bot tracks activity milestones and automatically grants the WL role when conditions are met.

9.3 AI Moderation

The Discord server uses Gemini 2.0 Flash as primary moderation AI. The bot:

• Classifies messages as normal, spam, toxic, or requiring human review
• Takes graduated action: warn → 1-hour timeout → ban
• Requires ≥ 0.85 confidence before any punitive action
• Flags edge cases for moderator review
• Handles /appeal requests with AI-generated verdicts

Operating cost at community scale: approximately $0.18–0.52/month.

---

10. Infrastructure

10.1 Smart Contract Layer

• Network: Sui Mainnet (testnet for V1 Beta)
• Language: Move
• Package: 14 modules, audited May 2026
• UpgradeCap: retained by admin for bug patches
• Events: every state transition emits a typed event

10.2 Off-Chain Layer

10.3 RPC

• Primary: Shinami free tier
• Fallback: Sui public RPC
• Price oracle 1: Pyth Network
• Price oracle 2: CoinGecko

10.4 Wallet Support

Slush, Suiet, Phantom, Backpack, Nightly — all five wallets supported via @mysten/dapp-kit.

---

11. Security

11.1 Audit

The YumeBet V1 contracts were independently audited in May 2026. All Critical and High severity findings were remediated before this document was published. The audit report is available at yumebet.xyz/audit.

11.2 Key Security Properties

Capability model: Sensitive operations (market creation, resolution, treasury withdrawal) require on-chain capability objects (MarketCreatorCap, ResolverCap, AdminCap). Capabilities can be revoked by bumping the admin epoch.

Pause mechanism: YumeBetAdmin.paused halts new deposits instantly. Claims and refunds remain live during pause — the protocol never traps user funds.

Position soulbinding: Position objects are has key only with no store. Original depositors are the only addresses that can claim or refund. No position can be stolen or transferred.

Oracle manipulation resistance: Two-source cross-validation (primary + fallback within 1%) and a confidence threshold of 90/100 prevent any single compromised feed from forcing an incorrect resolution.

Bond slashing: User-created markets that fail to resolve cleanly have their 5 SUI bond slashed to treasury. This creates a financial incentive for market creators to propose resolvable markets.

Auto-cancel safety net: Any market in NeedsReview for more than 7 days can be cancelled by any wallet. Users are guaranteed a refund path regardless of admin availability.

No admin theft path: The admin cannot extract funds from winner escrow or staker balances except through the audited admin_sweep_winner_residual function, which is bounded by winner_payout_remaining_mist and emits a logged event.

11.3 Known Limitations (V1)

• No community dispute mechanism — admin is the sole final arbiter for contested markets
• No on-chain random for resolution — all resolution is deterministic (oracle-based)
• Royalty enforcement is opt-in (honor system with partner marketplaces)
• Custom market templates deferred to V2

---

12. Roadmap

V1 Testnet (Current)

Wallet integration, preview markets, mint and stake surfaces, resolver and indexer rehearsal. Core contract audit complete. Discord community in setup.

V1 Mainnet

• Yume Spirits mint (allowlist → public)
• Bot-created markets live: 5-min, 15-min, Thursday weekly, Sui ecosystem
• User-created markets with bond
• Automated resolution (Pyth + CoinGecko)
• Staking and reward claims
• NFT staker royalty distribution
• Admin dashboard
• Tax CSV export per wallet
• Full Discord community with AI moderation

V2 Features

• Permissionless custom market templates (verified users only)
• Richer dispute path (community escalation mechanism)
• Deeper analytics and market history
• Mobile-native expansion
• Additional oracle integrations
• Augur-style community resolution for disputed markets

---

13. Treasury and Governance

13.1 Revenue Model

YumeBet treasury accrues SUI from three sources:

1. Settlement fees: 2.5–4% of every market's total pool
2. Bond slashes: 5 SUI per cancelled user market
3. NFT mint proceeds: direct SUI from Allowlist and Public mint
4. Royalty split: 50% of all secondary market royalties

13.2 Treasury Use

In V1, treasury funds are used for:

• Gas top-ups for the bot operator wallet
• Infrastructure costs (paid in fiat, converted from treasury SUI)
• Development and security audit funding

There is no governance token in V1. The admin makes treasury decisions unilaterally with full on-chain transparency (every withdrawal emits a TreasuryWithdrawn event indexed to the admin dashboard).

13.3 V2 Governance

Community governance via NFT-weighted voting is planned for V2. Yume Spirits holders would vote on approved template additions, fee parameter changes, and treasury allocations.

---

14. Token Summary

YumeBet has no protocol token in V1. There is no YB token, no governance token, and no airdrop. The economic model is:

• SUI is the only settlement currency (deposits, payouts, fees, bond, mint)
• Yume Spirits NFTs are the staking instrument that earns protocol revenue
• Market positions are soulbound non-transferable receipts, not tradeable assets

This design avoids regulatory complexity, eliminates token volatility risk for users, and ensures the protocol earns only from actual market activity.

---

Appendix A — Numeric Constants Reference

---

Appendix B — Event Reference

Every on-chain state change emits a typed event indexed by the Cloudflare Worker:

---

YumeBet is in testnet beta. All figures, constants, and parameters are subject to change before V1 Mainnet launch.

Contract source: [github.com/YumeBetDev/yumebet](https://github.com/YumeBetDev/yumebet) NFT assets: [github.com/YumeBetDev/yumebet-assets](https://github.com/YumeBetDev/yumebet-assets)