Guide
How it works
01 · The game loop
From mint to prize
1. Get tokens
Horses and entries are paid in the game token. On the test network, claim free tSTRIDE from the faucet in your stable.
2. Mint a horse
Pay the mint price. Seconds later Chainlink VRF rolls its speed, stamina, acceleration and finish (19–100 each), coat and sheen. They never change.
3. Enter a race
Pick an open race (1,000–2,400 m, 2–12 gates), approve the entry fee and enter. Your horse takes the next free gate.
4. Gates close
The race starts when every gate is filled, or at its deadline with at least 2 horses: then anyone can press Start.
5. VRF seals it
The start asks Chainlink VRF for one random word. When it lands (about 6–12 s on Base), the whole result is fixed.
6. Watch & cash in
Watch the race in 3D, settle it (anyone can), and collect your prize. Your horse is free for its next race.
02 · Provable fairness
Sealed before the start
01
Chainlink VRF
One random word per race, delivered only by Chainlink's coordinator.
02
Seed on-chain
RaceManager stores it. Entries were already closed: nothing can change.
03
Race model
Same maths in Solidity and in your browser: seed + stats + distance → times.
04
Result
Finishing order and times, settled on-chain and paid 60% / 25% / 15%.
05
3D replay
Only draws the result it is given. It never decides anything.
Nobody picks the seed
Only the Chainlink VRF v2.5 coordinator can answer a request, with a cryptographic proof checked on-chain. The owner cannot choose, replace or re-roll a race's random word.
Inputs are locked first
Entries close the moment the seed is requested, and every runner's stats are snapshotted when it enters. The random word lands on a field that can no longer change.
Same model, twice
RaceModel.sol settles the race on-chain. raceSim.ts, its bit-exact TypeScript mirror (tested on 17,600 races), recomputes it in your browser for every replay.
The replay only replays
The 3D engine receives the finished result, 200 m split by 200 m split, and animates it. Camera, lights and weather are cosmetic; the order and the times are the chain's.
03 · Don't trust, verify
Verify a race yourself
- 1
Read the race
RaceManager.getRace(id) gives the seed (the VRF random word), the distance and the status.
- 2
Read the field
RaceManager.getEntrantStats(id) gives every runner's stats by gate, as snapshotted at entry.
- 3
Run the model
simulateRace(seed, stats, distance) from raceSim.ts, or call RaceManager.computeResult(id) on any node.
- 4
Compare
Same order and times as the RaceSettled event, and the payouts match the 60% / 25% / 15% split.
- The race page does all of this for you. The badge “Verified: your browser’s replay matches the on-chain result” appears only when every check passes; any difference shows a loud mismatch warning instead.
// viem + utils/hyperstride/raceSim.ts
const race = await manager.read.getRace([id]);
const stats = await manager.read.getEntrantStats([id]);
const mine = simulateRace(
race.seed,
stats.map(horseStatsFromContract),
race.distanceM,
);
// the chain's own recomputation
const [splits, times, order] =
await manager.read.computeResult([id]);
assert.deepEqual(mine.order, order.map(Number));
assert.deepEqual(mine.finishTimesMs, times.map(Number));04 · Money
Fees & payouts
Prize pool
Entry fee × horses entered. Every fee is held by the race contract until the race is settled or refunded.
Protocol fee
5% of the pool on new races, capped at 10% by the contract and fixed when each race is created. No fee on refunds.
Podium split
The rest goes 60% / 25% / 15% to 1st, 2nd and 3rd (70.6% / 29.4% with 2 runners). Rounding dust goes to the winner: fee + prizes = pool, exactly.
12 horses× 10 tokens
- Pool
- 120
- Fee (5%)
- 6
- 1st
- 68.4
- 2nd
- 28.5
- 3rd
- 17.1
6 horses× 25 tokens
- Pool
- 150
- Fee (5%)
- 7.5
- 1st
- 85.5
- 2nd
- 35.63
- 3rd
- 21.38
2 horses× 50 tokens
- Pool
- 100
- Fee (5%)
- 5
- 1st
- 67.06
- 2nd
- 27.94
Prizes are credited when the race is settled and sent to your wallet with Collect on the race page, the races page or your stable. They go to the wallet that entered the horse.
05 · Rules
Start & refunds
Gates full
The last entry requests the VRF seed: the race starts at once.
Deadline, 2+ horses
Entries close. Anyone can start the race.
Deadline, under 2 horses
Anyone can cancel it: every entry is refunded.
Not started after 24 h
A race still not started a day after its deadline can be refunded by anyone.
VRF silent for 24 h
Anyone can cancel and refund. A late answer is ignored.
Seeded
A race with its seed can only be settled, never cancelled. Anyone can settle it.
Organiser powers
Creates races, can cancel an open race before its seed request (full refund) and pause new entries.
Always available
Starting, settling, refunding and withdrawing keep working even while entries are paused.
06 · FAQ
Questions
Can the team choose who wins?
No. Only Chainlink's VRF coordinator can deliver a race's random word; the owner can neither choose nor re-roll it, and entries close before it is requested. From there the result is pure maths anyone can recompute.
What do the four stats do?
Speed sets the cruising pace. Stamina limits the fade in the second half, so it matters most in long races. Acceleration softens the standing start. Finish powers the kick over the last 400 m. Each horse also gets a race-day form and a little luck per 200 m, both drawn from the seed. A horse 20 points better everywhere wins about a quarter of its races against eleven average ones.
Do coat and sheen matter?
No, they are cosmetic: 12 coats and 4 sheens (Satin, Gloss, Metallic, Iridescent), rolled by the same VRF word as the stats.
Why two transactions to enter?
The game token is an ERC-20: you first approve exactly the entry fee for the race contract, then enter. Free races need a single transaction.
Why is my horse busy?
A horse runs one race at a time. It is free again as soon as its race is settled or refunded.
I sold my horse while it was entered. Who gets the prize?
The wallet that entered it. Prizes and refunds are credited to the entrant, whoever owns the horse later.
Where are my winnings?
Settlement credits them to your balance in the race contract. Press “Collect” on the race page, the races page or your stable to send them to your wallet, whenever you like.
Is the 3D race the real result?
It is a faithful drawing of it. The result is computed first (on-chain and in your browser) and the engine animates those exact times, gate by gate. If the two computations ever disagreed, the race page would say so loudly.