Canonical game rules v0.1
1. Race Entry
One Race Entry contains exactly:
- one supported prediction market;
- one outcome;
- one separate native fill-or-kill order of at least $5, executed completely or cancelled completely;
- one specific NFT horse;
- zero to three boost cards;
- an immutable gameplay snapshot captured at activation.
Different horses owned by one player may enter the same market and may select the same or opposite outcomes. The same horse token may enter a given market only once. Each horse requires its own separate order.
2. Horses
| Horse class | Base speed | Capacity | Daily races |
|---|---|---|---|
| Common Runner | ×2.0 | 4 | 3 |
| Epic Contender | ×4.0 | 5 | 5 |
| Pure Legend | ×6.0 | 6 | 10 |
The first race of each horse each game day is free of hay. A game day is the UTC interval `[00:00, 24:00)`. UTC is authoritative for daily races, hay pricing, check-ins, qualified-volume rewards, tickets, and draws. The UI may display local time and a countdown, but local timezone changes never alter a game bucket.
3. Evolution
Horse Evolution is a future feature. It changes an existing NFT horse rather than minting another horse, and will use Hay and Boost Cards. Exact requirements, recipes, stat changes, and launch timing are not announced. The existing local-only prototype contains historical test values; they are not a public product promise and must not be exposed in player-facing UI.
4. Boost cards
There are 18 Boost Card definitions: Speed, Shield, and Luck, six levels each. They are consumable NFTs. A Race Entry may contain at most three cards. Duplicate categories and duplicate levels are allowed when the player owns separate available NFT copies. Effects of every selected card add within its category. Shield is the only category with a post-sum cap: 80%. Cards do not combine or upgrade into higher-level Boost Cards.
| Level | Capacity cost | Speed | Shield | Luck minimum delta | Luck maximum delta |
|---|---|---|---|---|---|
| I | 1 | +10% | 20% | +0.02 | +0.20 |
| II | 1 | +20% | 30% | +0.04 | +0.40 |
| III | 2 | +30% | 40% | +0.06 | +0.60 |
| IV | 2 | +40% | 50% | +0.08 | +0.80 |
| V | 3 | +50% | 65% | +0.10 | +1.00 |
| VI | 3 | +60% | 80% | +0.12 | +1.20 |
Total Shield is capped at 80%. Base Shield without cards is 0%.
Final stacking and card-label rule
This rule is authoritative for calculation, UI previews, card artwork, and future balance simulations:
- **Speed:** add all selected Speed percentages. There is no separate Speed cap; the three-card and Capacity limits are the constraint. Apply the total once to the horse's current Speed: `finalSpeed = horseSpeed × (1 + sumSpeed)`.
- **Luck:** start from the base range `×1.10–×1.50`, then add every selected Luck card's lower delta to the lower boundary and every upper delta to the upper boundary. There is no separate Luck cap; the three-card and Capacity limits are the constraint.
- **Shield:** add all selected Shield percentages, then cap the effective result at 80%: `effectiveShield = min(sumShield, 80%)`. Shield applies only to the lost half of the neutral game result after an incorrect prediction and has no effect on a win.
- **Mixed loadouts:** calculate each category independently. Speed does not increase Shield or Luck values; Luck does not amplify the printed Speed percentage; Shield changes only the losing bet result before the common race multiplier is applied.
Examples:
Speed I + Speed II + Speed III = +10% + 20% + 30% = +60% Speed
Luck I + Luck II + Luck III = ×(1.10 + .02 + .04 + .06)–×(1.50 + .20 + .40 + .60)
= ×1.22–×2.70 Luck
Shield I + Shield II = 20% + 30% = 50% Loss Shield
Shield II + Shield III + Shield IV = 30% + 40% + 50% = 120%, capped to 80% Loss Shield
Shield VI + any Shield = 80% effective, because the cap has already been reached
Compact artwork labels:
- Speed: `+10% Speed` through `+60% Speed`;
- Luck: `+0.02–0.20 Luck` through `+0.12–1.20 Luck`;
- Shield: `+20% Loss Shield` through `+80% Loss Shield`.
The plus sign on Shield is intentional: several Shield cards add together before the 80% cap. The help screen must state that the printed percentage protects that share of the 50% loss penalty—it does not return that percentage of the wager and does not add the printed percentage directly to points.
Base Luck range is ×1.10–×1.50. Luck cards add their minimum deltas to the lower boundary and maximum deltas to the upper boundary. After official market resolution, every eligible Race Entry independently receives one uniformly distributed Luck value inside its own final range. There is no market-wide Luck, user roll, animation requirement, or reroll.
The cards have different balance roles. Speed gives the strongest predictable average among cards of the same level. Luck has a slightly lower average but a higher possible maximum. Shield does nothing on a win, but on a loss it protects more than same-level Speed. The current approved card-level values are listed above; future Evolution values are not yet a public promise.
For MVP, an internal server-only Luck service derives the value from a protected server secret plus immutable Race Entry and provider-resolution identifiers. The value is generated once, stored permanently, and returned unchanged on every retry. Cashed-out and disqualified entries receive no Luck. Calculations retain four decimal places; the UI displays two. Public verification is deferred beyond MVP.
Card lifecycle:
- before confirmation: `AVAILABLE`;
- during reservation and active entry: `FROZEN`;
- valid market resolution: `BURNED`;
- Cash Out or disqualification: `BURNED`;
- market cancellation: returned to `AVAILABLE`;
- order failure before activation: returned to `AVAILABLE`.
5. Point calculation
For an active position held in full until official resolution:
raceMultiplier = baseSpeed × (1 + sumSpeed) × luck points = betResultUsd × raceMultiplier
Win:
betResultUsd = grossSettlementPayoutUsd grossSettlementPayoutUsd = winningShares × providerPayoutPerShare
The game uses the provider's actual gross settlement payout, including returned principal. It does not apply another ×2. A fully matched $5 order bought at $0.50 normally acquires ten winning shares and therefore produces a $10 gross payout; this special case is numerically equal to the previous ×2 example.
Loss:
effectiveShield = min(sumShield, 0.80) baseLossMultiplier = 0.5 baseLossPenalty = 1.0 - baseLossMultiplier = 0.5 shieldRefund = baseLossPenalty × effectiveShield outcomeMultiplier = baseLossMultiplier + shieldRefund betResultUsd = matchedUsd × outcomeMultiplier
In plain language, an incorrect prediction keeps 50% of the neutral game result and loses the other 50%. Shield returns its stated percentage of that lost half. The two `0.5` values in the compact formula represent different things: the first is the result already retained after a loss; the second is the size of the penalty that Shield can partially restore.
Examples:
Loss without Shield: 0.5 Loss with 40% Shield: 0.5 + 0.5 × 0.40 = 0.70 Loss at the 80% cap: 0.5 + 0.5 × 0.80 = 0.90
Shield never increases a winning result. A cashed-out or disqualified entry receives zero points rather than a settlement result.
Money and shares are computed in fixed-point units. Display rounding must not affect stored values or leaderboard ordering.
Personal Race Entries and Championships
The main competition leaderboard is period-based. For each wallet, it sums the
points from every eligible `SETTLED_WIN` and `SETTLED_LOSS` Race Entry whose
settlement timestamp falls inside the selected UTC week or month. A wallet has one
row in this table regardless of how many horses it owns or markets it entered.
Each Race Entry is an independent personal run. Competition occurs through the weekly and monthly Championship Leaderboards. Prediction markets do not produce separate multiplayer standings.
One filled FOK order, one horse, and its selected cards create one personal Race Entry. Different horses may select opposite outcomes in the same provider market through separate orders. There are no market places, placement bonuses, market prize pools, or redistribution between entries. Cancelled, failed, cashed-out, and disqualified entries contribute zero Championship Points. Won/Lost refers only to the financial prediction outcome.
6. Final coverage requirement and early sale
Activation records the exact provider account, market, outcome, matched USD, and shares acquired.
The MVP does not monitor continuous ownership or reconstruct which particular shares were sold. Immediately before settlement, it compares the player's actual shares for the provider account, market, and outcome with the aggregate shares required by active Race Entries. Selling and rebuying before that check is allowed. A deficit at the final check disqualifies affected entries.
Full or partial Cash Out causes the whole selected Race Entry to earn zero game result. The MVP UI supports full Cash Out only.
On Cash Out or disqualification:
- points: 0;
- cards: burned;
- hay spent for entry: not returned;
- daily race: not returned;
- Evolution volume/races: not counted;
- hay from qualified volume: not awarded;
- lottery tickets: not awarded.
Because shares of the same account/market/outcome may be fungible, all active entries form a required coverage pool:
requiredShares = sum(registered shares of all eligible active entries) final coverage is valid when accountShares >= requiredShares
External buys never increase any Race Entry's registered gross payout, which remains capped by the shares acquired through its original game order. At the final check, if account shares fall below the aggregate requirement, the newest Race Entries are disqualified whole until the remaining requirement is covered. Cash Out through the game targets the selected entry directly and immediately makes it ineligible.
7. Cancellation and technical failure
Market cancellation:
- financial refund follows partner rules;
- cards return;
- entry hay returns;
- daily race remains spent;
- no points or result-based Evolution progress;
- qualified volume, hay, and tickets already credited from the original full FOK fill remain credited.
Failure before `ACTIVE`:
- cards and hay reservations release;
- daily race is not spent;
- horse/market uniqueness reservation releases;
- no game rewards.
8. Hay
- Minimum qualified order and race: a native fill-or-kill order of at least $5, executed completely.
- Every $5 of qualified fully filled FOK volume awards 1 hay immediately, without progressive pricing.
- Hay is non-transferable.
- Purchase rate: $2 for 10 hay.
- Check-in sequence: 1 / 1 / 1 / 2 / 2 / 3 / 5, totaling 15 hay per seven consecutive UTC days. One claim is allowed per UTC day. After day seven, the next consecutive claim starts a new cycle at day one; missing a UTC day resets the next claim to day one.
- Hay cost is determined by the ordinal number of that horse's activated race inside the daily reset bucket:
| Race number | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
|---|---|---|---|---|---|---|---|---|---|---|
| Hay cost | 0 | 1 | 2 | 2 | 3 | 3 | 3 | 4 | 4 | 5 |
This produces full-day totals of Common Runner 3, Epic Contender 8, and Pure Legend 27 hay. A race consumes its listed cost only when the Race Entry becomes `ACTIVE`.
9. Lottery tickets
Qualified daily volume thresholds are cumulative:
$5 / $15 / $35 / $75 / $155 / $315 / …
The first ticket requires $5 of qualified fully filled FOK volume. Every next incremental requirement doubles: another $10, then $20, $40, $80, $160, and so on. Therefore $100 of qualified volume earns four tickets by crossing the cumulative thresholds at $5, $15, $35, and $75.
Qualified volume, hay, and tickets are committed immediately when the native provider FOK order fills completely and the Race Entry becomes `ACTIVE`. They belong to the UTC day of the provider fill and enter that day's next 00:00 UTC draw. A later win, loss, Cash Out, disqualification, or market cancellation does not add, duplicate, or claw back these fill rewards. A failed order that never becomes `ACTIVE` earns nothing. A Cash Out sale, rebuy, or unrelated direct provider trade does not create additional qualified game volume. Each provider order ID can be credited once. Tickets never carry over and burn after their draw.
The daily prize pool is server-configurable and must be published before the corresponding UTC ticket day begins; it cannot be changed retroactively. The current balance-test configuration is 1 Elite pack, 5 Rare packs, and 20 Basic packs, not a permanent production promise. Each ticket is one separate chance. The draw selects winning ticket records without replacement, so one ticket can win at most one pack while a player holding several tickets may win several packs. If there are fewer valid tickets than configured prizes, every ticket can win at most once and undistributed packs do not roll over.
Points, Luck, leaderboard results, and result-based Evolution progress remain deferred until valid settlement. They are separate from fill-time volume rewards.
10. Card packs
The canonical Boost Pack names are **Basic Boost Pack**, **Rare Boost Pack**, and **Elite Boost Pack**. They return as separate limited editions each season. Pack contents, prices, and card strength do not automatically change between seasons; cards from earlier seasons remain owned and fully playable. A season adds provenance, not a new rarity or stronger card level. The canonical machine-readable catalog is `packages/game-engine/src/catalog.ts`.
| Season 1 pack | Price | Supply | Contents |
|---|---|---|---|
| Basic Boost Pack | $1 | 600 | 2 cards from levels I–II |
| Rare Boost Pack | $3 | 300 | 2 cards I–II + 1 card III–IV |
| Elite Boost Pack | $5 | 100 | 1 card I–II + 1 card III–IV + 1 card V–VI |
Each later season receives its own predeclared limited supply of these same packs. No more packs may be issued from a season after it ends. The next supply is decided using activity, remaining cards, and actual consumption. Store `seasonId` and mint source as provenance metadata. The supply limits pack issuance, not the number of horses or cards a wallet may hold; there is no general asset ownership cap. The allocation of a season's packs among sale, leaderboard, lottery, and other rewards remains an open product decision.
Starting three cards are non-transferable. Purchased, weekly, and lottery cards are transferable and may be sold. Selected cards are committed only after a successful complete FOK fill activates the Race Entry. Cancelled, rejected, or incomplete orders do not consume them. Cards used by a valid entry are consumable; future horse Evolution may also use cards as materials.
11. Genesis horses
The **Genesis Horse Pack** contains one unrevealed NFT horse. Both Epic Contender and Pure Legend come from this same pack; Common Runner is the free starter horse and is never a Genesis reveal.
- Maximum 300 public closed packs at $10 each.
- Limit: 5 packs per game account during the primary mint only; no general horse ownership cap.
- Full-series composition: 270 Epic Contender (90%), 30 Pure Legend (10%).
- Mint remains open for seven days; reveal occurs after the close. The mint date has not been announced, so minting is not active.
- Unsold packs burn.
- Treasury receives no reserved Genesis NFTs.
- Genesis is never reissued.
This one-time Genesis edition is never reissued. One free Common Runner is granted to each new player profile and is not inside the Genesis pack. Evolution changes an existing horse NFT and cannot increase the horse count.