the docs

A blind-vote Bull vs Bear elimination tournament played over escrowed Noper bear NFTs, with an escalating ETH entry fee that accumulates into a single pot. This document is the authoritative rule set. It is written so you can paste it into a frontier model and ask it to simulate optimal strategy for a given field size, your bear count, and your risk appetite.

Everything below is enforced on-chain by the NoperTournament contract. Numeric defaults are the launch values; the owner can tune some of them (noted), but cannot influence which side wins a round, who becomes champion, or read votes before reveal.

Timeline — what happens, and when

Your part is small: mint, then pick a side and pay for each round you want in. The keeper reveals your votes for you and settles every round; at the end, payouts are pushed to the winners (or you collect yourself, whenever you like).

1. The loop (one round = one "week")

Each round has three phases, back to back:

1. Commit (vote) window — you pick a side secretly and pay the entry fee.
2. Reveal window — you (or anyone with your salt) reveal your committed side.
3. Settle — anyone calls settle(); the majority of revealed sides wins the round.

Then the game either ends (see §6) or advances to the next round at a higher fee.

Default cadence: 6d commit + 1d reveal = 1-week rounds (owner-tunable per round, but never in a way that reopens a closed vote).

2. Entering a round

To put a bear in a round you call enter with, per bear:

• The entry fee (ETH). fee(round) = baseFee + feeStep × (round − 1). Launch: baseFee = 0.005, feeStep = 0.005 → round 1 = 0.005, round 2 = 0.010, round 3 = 0.015 … (one round = one week)
• A blind commitment: keccak256(abi.encode(side, salt, tokenId, round, staker)), where side ∈ {1 = Bull, 2 = Bear} and salt is 32 random bytes kept off-chain. Only this hash is stored on-chain during the commit window — there is no per-side counter, so the live tally literally does not exist until reveals begin. (A weak/low-entropy salt is brute-forceable; the frontend uses 32 secure random bytes.)

On first entry the bear is pulled into escrow (transferred to the contract). It stays escrowed until the game ends or you exit it (see §7).

Eligibility: - A bear branded loser can never enter again. - A bear can enter a given round once. - First-ever entry is round 1 only, unless openJoin is on (see §5). - Optional whale cap: maxPerWalletPerRound (launch: 0 = unlimited).

You may recommit (change your sealed side) any time before the commit window locks. It reveals nothing.

3. Revealing

During the reveal window, submit (tokenId, side, salt). The contract recomputes the hash and checks it matches your commitment.

• Revealing is permissionless to submit (the salt is the secret) and revealing your true side only ever helps your own bear — a keeper can reveal on your behalf.
• Failing to reveal = forfeit = treated as a loss. An unrevealed bear cannot win the round.
• You cannot change your side at reveal — the commitment binds it. Reveal only discloses what you already, blindly, chose.

4. Settlement — who advances

settle() (callable by anyone after the reveal window) tallies revealed sides for the round:

• bull = count of revealed Bull, bear = count of revealed Bear.
• Winner = the bigger side. bull > bear → Bull wins; bear > bull → Bear wins.
• Tie → draw: everyone who revealed advances (both sides survive).
• Survivors = the winning side's count (or all revealers, on a draw).
• The losing side (and all forfeiters) are eliminated and become permanent loser bears when their bear leaves escrow. The loser brand is forever and on-chain.

No owner declares a winner — it is pure on-chain arithmetic over the reveals.

Strategic core: because the majority advances, this is a Keynesian beauty contest. You are not trying to be "right" about bull vs bear — you are trying to be on whichever side the crowd picks, blindly, before anyone can see the crowd. With no information, each round is ≈ a coin flip.

5. Continuing, sitting out, and openJoin

After winning a round you choose, each subsequent round, to: - Re-enter (pay the new, higher fee, commit again — you may switch sides freely), or - Sit it out (pay nothing; your bear is a "Survivor" and is not eliminated), or - Retire (stop for good and reclaim a slice of your fees — see §8).

openJoin (launch: ON, owner can switch off): - ON — bears that sat out earlier rounds (and even fresh bears) may join later rounds. The field is open. This is the anti-stall valve for early low-traction rounds. - OFF — strict bracket: only the previous round's winners may continue; no late entries.

Branded losers are always blocked regardless.

6. How the game ends (3 ways)

1. Cull reached — after a settle, if survivors ≤ cullThreshold (launch: 100), those survivors are the champions. The decisive round is this round.
2. Stall / priced-out — if a round's commit window closes with entrants < minFighters (launch: 2), anyone calls endIfStalled(); the previous round's winners are the champions. (This is how the escalating fee eventually ends the game when it gets too steep to fill.)
3. Total wipeout — if a round settles with zero revealers, the previous round's winners are the champions.

When the game ends, the pot splits into a champion jackpot and a participation pool (§7), both frozen.

7. The pot and the payouts — a three-layer reward

Every fee is split across three layers, so rewards reach all players, not just the final winners:

1. Champion jackpot (the big prize). The pot minus the participation pool is split equally among the decisive-round champions (prizePerChampion = championPot ÷ championCount). Lose before the decisive round and you get none of this — it's the harsh, winner-take-most core. More co-champions = smaller slice each.
2. Participation pool — participationBps of the pot (launch: 25%), split by rounds won across the whole field: champions, retired survivors, and eliminated players for the rounds they won before being knocked out. reward = (rounds you won ÷ all rounds won) × pool. A loss does not erase the rounds you already won — you still collect for them. (First-round losers won nothing, so they get nothing here; you must win at least one round.)
3. Honors rebate (§8) — a fenced skim that refunds a slice of your own fees, scaled by wins, capped at what you paid. Cost-side, loss-mitigation only.

Who gets what (all in one call): - Champions: jackpot share + participation (most wins → most participation) + honors rebate, bear back un-branded. - Retired survivors: participation + honors rebate, bear un-branded. - Eliminated players: participation for the rounds they won + bear back (permanently branded). They forfeit their honors skim, but a knockout no longer means zero. - Immune bears (the 1/1s): never eliminated/branded, but only win the jackpot if they actually win the decisive round.

Two ways to get paid, and prizes NEVER expire. Either you call collect(yourBearIds) — one call hands back every one of your bears with whatever it's owed, whatever its state (won, lost, or retired) — or the team calls distribute and pushes each winner's prize straight to them. There is no claim deadline and no sweep: your prize sits fenced in the contract, claimable forever. Pulling a bear out mid-game (before the end) forfeits only its unfinalised participation share (it stays in the pool for those who play on — see §5); once the game ends, waiting forfeits nothing.

8. "Retired with Honor" — the self-funded fee rebate

A fixed fraction of every entry fee is fenced per bear into a separate honors pool, which is never part of the grand pot.

• honorsBps (launch: 2000 = 20%) of each fee → that bear's own honors balance (honorsContribBy).
• A bear can reclaim ownSkim × min(wins × winRebateStepBps, maxRebateBps), capped at its own total contribution:
• winRebateStepBps (launch: 2500 = 25% unlocked per round won)
• maxRebateBps (launch: 10000 = up to 100% of your own skim after 4 wins)
• minWinsForHonors (launch: 1 — need ≥1 win to qualify)
• You can never reclaim more than you put in. Retiring is therefore always a partial refund of your own fees, never a profit — which is what makes it Sybil/fee-farm proof and keeps the grand pot whole. A branded loser forfeits its skim (it becomes protocol revenue).

wins = rounds actually won (not the calendar round), so a late joiner is rewarded for genuine wins. (Honors is the cost-refund layer; the participation pool in §7 is the separate, real reward for wins — the two are independent.)

9. Money math (for simulation)

Let F₀ = starting field, e = fraction eliminated per round (≈ 0.5 with blind 50/50 voting, more if the majority is lopsided), b = number of bears YOU run, h = honorsBps, q = participationBps, c = cullThreshold.

• Rounds to end R: smallest R with F₀ · (1−e)^R ≤ c.
• Fee of round r: fee_r = baseFee + feeStep·(r−1).
• Pot: Σ_{r=1..R} field_r · fee_r · (1−h) where field_r = F₀·(1−e)^{r−1} (the 80% after the honors skim).
• Participation pool: participationPool = q · pot. Champion jackpot: championPot = (1−q) · pot.
• Total rounds won (all players): W = Σ_{r=1..R} survivors_r ≈ Σ_{r=2..R+1} field_r (each round's winners).
• Participation per win: pool ÷ W. A bear that won k rounds earns k · pool ÷ W — even if it was later eliminated (a loss doesn't erase earlier wins; first-round losers won 0, so they get 0).
• Each champion's jackpot share: championPot ÷ survivors (survivors ≈ c).
• Your max spend (all your bears, every round to the end): Σ_{r=1..R} b · fee_r. A hard ceiling — you're only charged when you choose to vote; max loss = the fees you opt into.
• Your honors skim: h · (your fees); reclaimable up to 100% after 4 wins.
• Champion net (all b survive to the end, won R rounds each): share·b + (R·b)·pool/W + reclaimedSkim − yourFees.
• Knocked-out net (your b bears each won k rounds, then eliminated): (k·b)·pool/W − yourFees (no jackpot, but participation softens the loss — this is the "reward all players" term).
• Probability you reach round k (blind, win-rate w per round, default 0.5): w^{k}. Going all the way ≈ w^R — small. (E.g. 9 rounds at 50% ≈ 1 in 512.)

10. Strategy levers to simulate

Ask your model to optimize over these, for a given (F₀, your bears b, opponent bull-bias p, e):

1. Side each round — with no info it's a coin flip; the edge comes from predicting the crowd's majority (memes, momentum, what the bigger wallets signal).
2. Splitting your bears across both sides — e.g. run b = 50 as 25 Bull / 25 Bear. Whichever side wins, that half of your bears survives; the other half is eliminated. This buys survival certainty at the cost of guaranteed attrition + double fees. With enough of your own bears you can even force ties/draws (everyone advances) — model when yourBull + othersBull == yourBear + othersBear is reachable and whether forcing a draw is +EV.
3. Sitting out specific rounds — pay nothing, keep all your bears (openJoin lets you rejoin). Useful to skip an expensive round or wait for the field to thin. But the participation pool changes this: rounds you sit out are rounds you don't win, so you earn no participation for them. The pure "sit out early, flood the final round" free-ride now leaves the early-win participation on the table for the players who actually fought — model the trade-off, it's no longer free.
4. When to retire vs play on — a branded loss forfeits your honors skim, but it does not forfeit the participation you already earned for rounds you won (collect it via withdrawLoser after the game ends). So a deep run that ends in a loss still pays the participation for those wins — playing on is less punishing than it looks. (Exit your bear mid-game and you DO forfeit the unfinalised pool share.)
5. Concentration vs spread — many bears = more jackpot shares if you win the decisive round AND more participation (more total wins across your bears), but b × the fees and b × the elimination exposure.
6. Win depth — because participation pays per round won, grinding wins across many rounds compounds: you collect participation for each, on top of (or even without) the jackpot. Reward now tracks how much you won, not just whether you won the last round.

Objective function: maximize E[payout] − E[fees], where payout = jackpot share (if a decisive-round champion) + participation reward (rounds you won ÷ all wins × pool) + reclaimed honors skim, minus fees, subject to your max-spend budget. Report the full outcome distribution (champion / retired / knocked-out), not just the mean — and note the knocked-out case now has a positive participation term for its wins.

11. Trust model (what the admin can and cannot do)

• Cannot influence which side wins a round, who is champion, or the split among them. Settlement is permissionless and reads only on-chain reveals.
• Cannot read your committed side before reveal (only a hash is stored).
• Can tune economic params (fees before a round starts, cull, honors and participation %, round length, openJoin, pause new entries), recover genuinely stuck bears to their original staker, and distribute payouts — push each winner's prize + bear, but only ever to the rightful staker, for the exact amount the contract itself computed. It cannot redirect a prize, skip a winner, short a payout, edit a live vote tally, or reopen a closed vote.
• Cannot sweep or expire your prize. There is no claim deadline — owed prizes stay fenced in the contract forever, retrievable by you (collect/claimPrize/withdraw) or pushable by the team (distribute) at any time, years later if you like.
• Cannot renounce ownership while bears/pot are held; there is no arbitrary-call backdoor.
• NUCLEAR OPTION (read this): the owner — a Safe multisig — holds a deliberate emergency escape, withdrawAll, that can drain all ETH in the contract. It is two-step + timelocked: arming emits a public NukeArmed event and execution is blocked for 3 days (NUKE_DELAY), so you get a public warning to claim/exit first. It takes ETH only — escrowed bears are never touched and stay recoverable to their stakers. This means the pot is ultimately backstopped by trust in the multisig, not by math alone. Watch for NukeArmed.

Parameters in this doc are launch defaults. Read them live from the contract before simulating a real game: feeForRound, cullThreshold, minFighters, honorsBps, participationBps, winRebateStepBps, maxRebateBps, openJoin, and nukeArmedAt (0 = no pending nuke).

12. FAQ — escrow, recovery, and the practical edge cases

Everything below is enforced on-chain and every action is a public contract function — playable and recoverable directly via Etherscan / a script, the website is only a convenience.

How does my bear get escrowed, and how do I get it back? The only way in is enter(...), which pulls your bear into the contract and attaches your vote. (A raw transfer to the contract is rejected — "use enter()".) Getting it back is always possible. The simplest is collect(yourBearIds) — one call returns every one of your bears with whatever each is owed, whatever its state (won, lost, or retired). The per-state functions still work too (claimPrize, withdraw, withdrawLoser). The team can also distribute your prize straight to you, or emergencyReturn any stuck bear to its original staker, and after a nuke anyone can reclaimBear their own. No state can permanently trap a bear — and no prize ever expires.

Can I pull my bear out in the middle of voting? No. Once you've committed in the current round your bear is locked in for that round — withdraw and withdrawLoser both revert. The most you can do is recommit (change your sealed side) before the window locks. (Even the owner's emergencyReturn can't pull a revealed bear from a live, unsettled round — nobody can yank a live vote.) You become free to exit only after the round settles.

Sit out vs. exit — and can I come back? Two different things, and only one lets you return: - Sit out = just don't enter a round. Your bear stays escrowed as a Survivor. With openJoin on (default) you can re-enter any later round — no penalty. - Exit = withdraw your bear out mid-game. This is a one-way forfeit: you give up the jackpot and your participation share, and the bear can never re-enter this tournament (it's marked exited). You keep the bear (un-branded) + your honors rebate.

I bought a noper bear on a marketplace and it won't let me play / says "loser." A bear that lost a round is branded loser forever and cannot enter — that permanence is the game (elimination has to stick). A bear that was pulled out mid-game (exited / "Retired") also can't re-enter. Both states travel with the token, so a bear sold on secondary keeps them. Marketplaces cache metadata and can show a stale status for a long time, so the only reliable place to check a bear's status is on-chain / on the site — the battle page reads it live and warns you, and a bear's Status trait (Loser / Champion / Survivor / Retired) is read straight from the contract. Check live status before buying a bear to play with. (A new season is a fresh contract, so brands don't carry across seasons.)

What if I lose my salt / my vote never gets revealed? Your vote is a blind hash; revealing needs the exact salt. The keeper auto-reveals from an encrypted server-side store, and the site offers a downloadable backup — but if a salt is truly lost, the vote simply forfeits (counts as a loss). You still get your bear back (branded) via withdrawLoser; no funds are ever at risk from a lost salt, you just lose that round. Keep a backup.

Can the game, the UI, or the math be cheated or broken? Not for funds. The contract is independently audited (0 critical/high/medium), 122 automated tests, a 3,000-game solvency fuzz. Every payout is hard-capped (prizePaid ≤ pot, participationPaid ≤ pool, honors ≤ your own skim) and every input is validated — a wrong fee, bad salt, ineligible or double claim all revert. The website is never the source of truth for money; the contract is, and it re-checks everything. The on-page calculator is a clearly-labeled model, not a transaction.

Can the team take the pot? The team cannot influence votes, champions, or the split — that's audited. There is one deliberate emergency escape: the owner (a Safe multisig) can withdrawAll the ETH, but it is two-step and timelocked — arming emits a public NukeArmed event and execution is blocked for 3 days, and it takes ETH only (your bear stays self-recoverable). So the pot is ultimately backstopped by trust in the multisig, which we state plainly. Watch for NukeArmed.

13. Disclaimer — please read

We're a small team, and this is an experiment built in good faith because we wanted it to exist — not a polished product, and not a way for us to make money. We take no cut of the pot; the pot is the players'. A few things we'd rather say plainly than bury:

• It's a game, and you pay to play. Every entry fee is a real, non-refundable wager. Only stake what you can afford to lose. Treat it as a gamble — because it is one.
• We can be hacked. The code is open and on-chain: anyone can read it, poke at it, and try to crack it open. We've audited and tested it hard, but no contract is unbreakable. There is also a deliberate emergency escape (the timelocked nuclear withdrawal, §11) — the pot is ultimately backstopped by trust in our multisig, not by math alone.
• The game can be gamed. It's permissionless and adversarial by design — whales can flood late rounds, players can coordinate, strategies will emerge. That isn't a bug; outsmarting the field is the game.
• Nothing here is financial advice, a promise, or a guaranteed return. Most bears lose. The numbers in these docs are models, not predictions.

Play for the fun of it, with money you're happy to lose. That's the whole spirit. 🐻