Bitcoin Arena docs

Round

One match of a game or one market, with a start, an entry close and a stake. Every round has a 32-byte round id.

Entry

A player's place in a round, with their stake.

Node

One running arena-node server (also signer node or seat). Its operator chooses the games it hosts.

Bond

Bitcoin a node locks on chain to get a seat. Its signed advertisement travels in the same transaction. See Bond and advertisement.

Census

The set of bonds that are confirmed and old enough, read from the chain. Committees are drawn from it.

Committee

The 7 nodes drawn for one round. They run it and sign its results and payouts; 5 of 7 must agree.

Federation, guardians

The Fedimint federation that holds the stakes; its guardians are nodes that each hold one of its keys.

E-cash

The federation's notes, held in your browser's wallet under your 24 words or your Nostr key.

Stake lock

A contract inside the federation that holds a paid entry's stake until the round's result opens it, or its expiry hands it back. See Stake locks and settlement.

Settlement

The one transaction in which a round's committee claims the losing locks and pays the winners, the node fee and the donations.

Manifest

The developer's signed record of a game or market: its rules, its client files, how it pays out. Its hash is the game id.

Replayed game

The result is a run the nodes replay from the player's inputs (Tick Tock, Next Block).

Attested game, attestors

A prediction market: the result is an outcome signed by the people or services the developer named, its attestors (Bitcoin Up or Down).

Head-to-head game

Each player hides a move, all moves are revealed after the entry close, and the game's rule decides between them (Rock Paper Scissors). A round is played only when all its players entered.

Template

A market manifest whose rounds each ask their own question with their own outcome labels. See Event-market templates.

Leaderboard

One game's board across its finished rounds over a window of days. See Leaderboard.

Donation

The player's optional 0 to 5 % of a paid stake, split between the game's developer and the protocol developers. Collected with a dev client.

Protocol reserves

The network's own fund: 2% of every paid round and 20% of every item on protocol 11, held in the federations under each one's 5-of-7 reserve key. Paid out only to proposals the bonded nodes vote for. See Protocol reserves.

Objection window

The 10 minutes after a result is signed in which anyone can prove it wrong. See When a node cheats.

Bitcoin Arena runs in your browser. There is nothing to install and no account to make.

1. Open the testnet page

   Go to testnet.bitcoinarena.io. Each game also has its own link: ?game=nextblock, ?game=rock-paper-scissors and ?game=btc-updown-15m. The page finds the nodes, reads their rounds and shows them in the lobby.

2. Make your wallet

   On your first visit the page asks how you want your wallet:

   • Create a new wallet. It is ready at once. Back up its 24 words later in Settings.
   • Restore a wallet from its 24 words (or a 64-hex seed).
   • Login with Nostr: a browser extension (NIP-07, for example Alby or nos2x), a phone signer (NIP-46, for example Amber, by QR code), a bunker:// link, or an nsec. You can also create a new Nostr account there. See Nostr.
   Keep your 24 words or your Nostr key safe. They are the only way back into your wallet. Nobody, not even the nodes, can recover it for you.
3. Deposit test sats

   Open Deposit, pick an amount and pay the Lightning invoice from any Lightning wallet: scan the QR code, copy it, or pay it from a wallet you connected with Nostr Wallet Connect. On testnet the page links to a test Lightning wallet with a small faucet, run by the project.

4. Join a round

   The lobby lists the open rounds with their stake, their federation and its load. It also shows how many nodes agree on each round. Joining a paid round locks your stake in the federation. Play starts only when the nodes have verified the lock.

5. Get paid

   When the round is settled, winnings and refunds go back into your wallet on their own; they show as pending until they are redeemed. Withdraw any time: paste an invoice from your own Lightning wallet, or let a connected NWC wallet make one.

Settings

The gear opens Settings: your balance and history, Deposit, Withdraw and Move, your name in the lobby (up to 32 characters), your donation (0 to 5 %, 5 % by default, for games before protocol 11; on 11 the developers' 4 % is fixed; see Where the money goes), your seed phrase (show it, check it word by word, restore), the federations you confirmed, and a link to the community on Armada.

Your sats are e-cash of a Fedimint federation, held by your browser. The wallet is the Fedimint client itself, compiled to WebAssembly, and its keys come from your 24 words (one wallet per seed and federation). No server keeps your balance.

Federations

A federation holds the stakes. It is a stock Fedimint federation (mint v2, Lightning v2) whose guardians are bonded Arena nodes. On testnet4 there are two, each with 7 guardians that need 5 of 7 to sign:

Together their 14 nodes form the testnet4 census. Every game can be paid through either federation. A deposit goes to the open federation with the lower load. A federation that is not on the page's known list is shown with its guardians, and the page asks you to confirm it before it is used.

Load

A federation's load is the bitcoin it holds divided by what its guardians' bonds cover. On mainnet the page refuses deposits into a federation at a load of 1 or more. On testnet4 it only warns (“Load N: this federation holds X sat, more than the Y sat its guardians' bonds cover”) and refuses nothing. The deposit screen shows each federation's funds and free capacity: green below 70 %, yellow from 70 %, red from 90 %. When yours is above 90 % and another is below 50 %, the page offers to move.

Federation status

The page hides what a status does not allow, and moves e-cash out of a DRAINING or CRITICAL federation on its own.

Stake locks and settlement

A paid entry does not send your sats to anyone. One federation transaction turns your e-cash into a stake lock (and a fee lock beside it). A lock is a Lightning v2 contract inside the federation with exactly three ways out:

• Claim: the round's settlement key takes it, in the round's one settlement transaction, when you lost.
• Forfeit: the committee hands it back to you (paid only to your refund key), with a payout contract for your winnings when you won.
• Refund after expiry: if nobody acts, the lock runs out and your own client takes it back with your key.

The nodes check every field of the lock with the federation before your entry counts (POST /lock, POST /fee-lock). After the round, the committee signs one settlement transaction together (FROST, 5 of 7), which each node has rebuilt itself. There is no pool wallet.

Winnings can also be sent straight to a Lightning address: a player names one with POST /payout-address, and the seats co-sign the send (GET /winnings shows its state).

Three games run on testnet4 today. All three are paid through both federations and checked by the same nodes.

Tick Tock, Next Block

Code name nextblock · a replayed skill game · play it

Drive a truck through the next Bitcoin block. Every player of a round gets the same block and the same seed; the best run of the round wins the pot.

• Play: load mempool transactions onto your truck, cross the bitcoin price war front (the closer you drive to it, the more points you score) and deliver to the miners' drop-off before time runs out.
• Checked by replay: your inputs go to every node of the round as you play. Each node replays them with the game's deterministic core and signs the score it gets. The battlefield's BTC price is a sample the committee signs every 5 seconds. Each seat reads Coinbase's exchange ticker (the last trade and its time); a reading older than 5 seconds counts as none. A seat signs a proposed price only within 0.05 % of its own reading, so no seat can pick the price. A scheme in which every seat signs its own reading and the median is taken is being built for a later protocol version.
• Payout: a rank curve. The top quarter of the players who qualified share the losers' stakes, with weights 0.75^rank−1; qualifiers below them get their stake back.
• Rounds: a new round starts every 90 seconds. The run lasts 82 seconds. You can join until 45 seconds after the start, but a late run still ends with the round. The rounds overlap, so one is always open.

Rock Paper Scissors

Code name rock-paper-scissors · head to head · play it

Rock Paper Scissors for bitcoin. Both players commit a hidden move, then reveal it; the winner takes the pot, a draw returns both stakes.

• Commit and reveal: your pick is sealed as a hash of the round, your key, your move and a secret salt. After the entry close you reveal it (POST /reveal); the nodes collect each other's reveals and sign the result.
• 8-second rounds: rounds close every 8 seconds, back to back, with several tables per slot. A third player gets a second table.
• Results: a win pays your stake plus your opponent's; a draw returns both stakes; a player who does not reveal forfeits; a round without two players is void and refunded.
• Tables on demand: when the page finds no open table it asks the nodes for one (POST /h2h-want), and the operator publishes a new grid of rounds in one Bitcoin transaction. On testnet this takes a while, so open tables are usually already there.

Bitcoin Up or Down

Code name btc-updown-15m · a prediction market · play it

Will the bitcoin price be higher at the end of the 15-minute window? Pick Up or Down; the attestors sign the price and the winning side shares the pot.

• A market every 15 minutes, 96 a day.
• The rule: the price to beat is the 60-second time-weighted average price before the window starts; the end price is the same average before it ends. Up wins if the end price is at or above the price to beat (a tie is Up).
• Who decides: three independent attestors, each reading several exchanges and taking the median. 2 of the 3 must sign the same outcome, which anyone then posts to the nodes (POST /outcome). The nodes check it; they do not set the price.
• Trading: signed limit orders in whole cents (0.01 to 0.99), at least 5 shares; a share pays 1 sat if its side wins. The nodes clear orders in batches every half second, at one price every node computes the same way.
• Fee: 1 % (0.5 % nodes, 0.5 % donation), due only on what fills. An order that has not filled can be cancelled at no cost (POST /cancel).
• Void: if the attestors contradict each other, or no outcome stands by the deadline, everything is refunded: every stake and every fee.

Leaderboard

A leaderboard is one game's board across its finished rounds: every node can add up the rounds it holds as final over the last 1 to 90 days (7 by default) and rank the players. Ask any node with GET /season?game=nextblock&days=7.

• The game page shows only the players ahead: a player whose net over the window is 0 or below is not listed, so the board is the players who won sats. A node's answer still carries every row.
• Each row is one player: rounds played, wins (the round's sole best delivered score, or a payout above the stake), net (paid out less staked, in msat), best score and when they last played.
• Rows are ordered by net, then wins, then best score, then the player's key, never by who arrived first.
• A result counts once it is final at that node, and an amount once the round's settlement is accepted. Refunds and void rounds are left out.
• A leaderboard computes no payout; it only sums what the settlements paid. Answers are kept 30 seconds.
• A round is held only by the nodes of its committee, so one node's leaderboard misses rounds. Add &scope=network for the whole network's: the node asks every node it knows for its rounds (GET /season-rounds, same game and days) and counts a round only when at least 3 different nodes hand in exactly the same account of it. A finished round is held by at least 5 nodes, so a real one always reaches 3; no single node, nor two, can put a made-up row on the board. The answer says how many nodes were asked and how many answered.

Your Nostr key can be your wallet login, your node's owner key and your name in the community, and your Lightning wallet can connect over Nostr. Everything below is built and in use.

When a node cheats

Nodes are not trusted. Anyone can check what a node signs, and a false signature is evidence against it. This section shows what happens when a node cheats.

What a node could try

Each of these cheats leaves a proof anyone can check:

Why one node alone cannot do it

Every round has a committee of 7 seats, and a result or payout counts only when 5 of them sign the same one. Up to 9 nodes are drawn per role, so spares take the seats of nodes that do not show up. The draw comes from a Bitcoin block hash, and your app computes the committee itself. A cheating node is one signature of the five needed. To change a result, five nodes would have to lie together.

How it is caught: replay and the objection window

After a result is signed, it waits 10 minutes before it is final. In that time anyone can object: the player, another player, a node that is not in the committee, a spectator or a watchtower. An objection is evidence: the player's inputs, the receipts the committee's nodes signed for them, and the result that replaying them gives. Any node checks it the same way, by running the game again with the round's own rules (POST /objection; tools/check-objection.mjs does the same check outside any node).

• A valid objection stops the result. The whole committee replays the inputs again, and the replay decides. The new result gets its own 10-minute window.
• If the committee cannot get 5 of 7 to agree, the entry is void and the stake goes back to the player.
• An objection that does not check is refused with its reason, and nothing is stored.

The player's app sends the run's inputs to all the round's nodes as it plays, and each node signs a receipt for them. So the evidence is not only on the player's phone.

What evidence is kept

Nodes keep every proof they hold and hand it to anyone who asks (/slash-proofs, /equivocation). A proof has no deadline. An objection that arrives after the 10 minutes can no longer change a final result: the payment goes ahead. It is still a proof against every node that signed the false result.

What happens to the cheater

Every node puts up a bond on Bitcoin to get a seat. The bond has a slash path that only a separate set of arbitration keys can use, and only with a proof:

• The arbitration keys sign a transaction that takes the bond. It names the proof's hash on chain, so anyone can fetch the proof later and check it again. A slash without a valid proof is itself public evidence against the arbitration set.
• Half the bond goes to the players the cheat harmed. Of the other half, 75% goes evenly to the other active nodes (not the round's own seats) and 25% to the developers. Nothing is burned.
• A spent bond is no longer a bond, so the node drops out of the census and out of every future committee. It would need a new bond to come back.

Arbitration touches bonds only. It can never move a player's stake, delay a round or change a result.

What the other nodes and your app do

• Honest nodes replay every run themselves and sign only what their own replay gives. They will not co-sign a false result. They check and store objections, and replay again when one is valid.
• Your app works out the committee and checks every signature itself, and sends your inputs to every node of the round as you play.

The limits

Bitcoin cannot replay a game, so a slash needs the arbitration set to confirm that the proof checks. So you trust the arbitration set, but only a little: it is separate from the committees, cannot touch stakes, and cannot hold a bond forever. In the design, 30 days after a bond confirms its owner can always take it back.

Your money never depends on slashing. Three things protect it even if arbitration failed completely: the 5-of-7 rule, stakes that go back to you by default if nothing is signed, and the objection window. Slashing only punishes a node that was caught.

4 % of every paid round goes to the nodes that did the work. Every node checks the others: see When a node cheats.

Liquidity providers

Seats and committees

Drawn by bond, seeded by a Bitcoin block. A node that does not show up is replaced by a reserve.

Bond and advertisement

The census

Who posts the rounds

One of the two grids is played; a stake never sits in both.

Your computer checks the games, pays out the winners and earns 4 % of every paid round. Setting it up takes about 15 minutes.

The setup, step by step

Updates are automatic. Your node fetches each new release, checks its signature, backs itself up, and goes back by itself if the new release does not start. To update right away: bitcoinarena update.

# start a node on port 31221 with its database in node.db
node packages/arena-node/src/main.js 31221 node.db

# the same, hosting Tick Tock, Next Block (sets ARENA_APPS to nextblock when it is not set)
node packages/nextblock/bin/node.mjs 31221 node.db

Everything about your node is on its owner page: whether it runs, what it earns, its roles, its bond, its uptime, its services and its updates.

Dev clients and donations

Donations are paid in the round's settlement as payout contracts to the developers' keys. A developer collects them with the dev client, packages/arena-donor:

arena-donor init       # make the developer's keys
arena-donor once       # collect once
arena-donor loop       # collect every few minutes
arena-donor status     # what is waiting
arena-donor game-key   # the Ed25519 game developer key
arena-donor sign <dir> # sign a game's manifest

It asks every seat what it verified for its key (GET /donations?key=), redeems the payout contracts in each federation with the same WebAssembly client the page uses, run in Node, and withdraws to the developer's own Lightning node. It then tells the seats what it read (POST /donations/read, signed by the key). On testnet4 the donation key set names two dev clients (dev a and dev b), split 2:1, which run as services that collect every 5 minutes.

From the owner area. A node's owner can also run dev clients on the node itself: set one up with a new key or an imported developer key (an imported key's wallets are recovered from the federation), see its donations split into the protocol developers' part and each game's part, withdraw to a Lightning invoice or Lightning address, or remove it (its directory and key are kept). The node restarts a client that stops, and refuses a second client on one key. These are owner-signed requests: GET /owner/dev, POST /owner/dev/setup, /owner/dev/withdraw and /owner/dev/remove. The public dashboard lists every dev client with the protocol/game split.

Every node answers the same HTTP requests at its own address, for example https://tn4.bitcoin-arena.io/guardian-1/games. The full reference is a page of its own: the node API reference, an OpenAPI 3 document generated from the node's source (openapi.json) and shown with Swagger UI. You can try the read-only requests live against the public testnet4 nodes there.

• Requests are open to any page (CORS is open). The few that change something need a signature (a player's, a node's, an owner's) or an operator token; the reference marks them.
• Round ids, entry ids and keys are hex strings in the query: ?round=<64 hex>.
• Answers are JSON, or binary when they are a protocol record (a round contract, a manifest, an attestation). Binary records are encoded and decoded with packages/arena-protocol.
• Ask several nodes, not one: every node of the committee answers for itself, and the page compares them.

A game played for money usually needs a company: a server, a wallet to hold players' money, a way to stop cheaters and someone to pay out. Bitcoin Arena does all of that, so a developer writes only the game.

There are two kinds: games, whose runs the nodes replay, and prediction markets, whose outcome named attestors sign. Start here:

A devnet is the whole network on your own machine: a private Bitcoin chain (regtest), a Fedimint federation of seven guardians (5 of 7), seven Arena nodes that are each one guardian, two Lightning gateways, and a free and a paid round of Tick Tock open in the lobby. One command starts it, one stops it. Nothing in it touches testnet4 or mainnet, and it needs no test coins: it mines its own.

What you need: Node.js 24 with the repository's packages installed; Bitcoin Core (bitcoind, bitcoin-cli); the Fedimint build the network runs (fedimintd, fedimint-cli, gatewayd, gateway-cli) with arena-stake-lock built beside it (packages/arena-node/tools/stake-lock); and lnd with lncli for the two gateways. Without lnd the devnet runs free rounds only and says so.

export BITCOIN_BIN=<dir with bitcoind> FEDIMINT_BIN=<dir with fedimintd and arena-stake-lock> LND_BIN=<dir with lnd>
node packages/arena-node/tools/devnet.mjs up        # start everything, print the links
node packages/arena-node/tools/devnet.mjs status    # what runs, its ports, the chain tip, the rounds
node packages/arena-node/tools/devnet.mjs play      # one player through a free round, to its signed result
node packages/arena-node/tools/devnet.mjs replay    # that run replayed here, checked against every node's result
node packages/arena-node/tools/devnet.mjs down      # stop everything it started

1. up

   Starts the chain and mines it to maturity, founds the federation (each node's guardian takes part in the key ceremony), starts the seven nodes, joins a federation client for each, starts two lnds with a gateway each and registers both at every guardian, then bonds the seven nodes on the chain and publishes a free round and a paid round. It prints the node addresses, the federation invite, both round ids and a lobby link. Measured on a macOS: 75 s from an empty directory, 32 s after a down (the federation and the bonds are kept), 6 s when everything already runs.

2. status

   Each process and whether it still runs, each node and its guardian, the chain's height, every port that answers, and the rounds node 1 lists.

3. play

   Opens a fresh free round, joins it as a new player, plays the run with the round's own core (a driver steers the truck), sends the inputs and signed marks to all seven nodes as the page does, waits for the round to close, and prints each node's signed result with its signature checked: outcome, score and transcript hash, how many of the seven agree, and whether that matches the run it played. Measured: 229 s for a Tick Tock round (an 82 s run), 157 s for the template's 10 s game, every one of the seven nodes signing the same result.

4. replay [round entry]

   The replay simulator: fetches a run's inputs and signed marks from a node, replays them here with the node's own replay code in the core's sandbox, and compares the outcome, score and transcript hash with every node's signed result. With no arguments it replays the last play.

5. down

   Stops exactly what up started, by the process ids it wrote (each in its own process group, so a node's guardian goes with it), and checks that none of its ports still answers. The directory is kept, and up starts on it again.

Your own game on the devnet

The game template is a whole replayed game called coin-count: each tick the player presses a number from 0 to 9, some ticks count three times, and the score is the sum. One command copies it into a directory of yours, makes your developer keys with the dev client and signs its manifest:

node packages/arena-node/tools/devnet.mjs new-game ./my-game my-game
# {"step":"new game","name":"my-game","gameId":"…","core":"…","hostedAs":true,…}
DEVNET_DIR=./my-devnet DEVNET_APPS=./my-game/game.js node packages/arena-node/tools/devnet.mjs up
node packages/arena-node/tools/devnet.mjs play --game my-game
node packages/arena-node/tools/devnet.mjs replay

Three files are yours to change:

• core.js, the rules: pure integer arithmetic over the seed and the inputs, run by every node in a sandbox with no network, files, clock or randomness. Its id is the SHA-256 of the file.
• body.mjs, the manifest: the core and its config by hash, the run length (runTicksMax), the payout rule, your client pages and your donation set. Sign it again after any change: node packages/arena-donor/bin/arena-donor.mjs sign ./my-game/dev ./my-game/body.mjs. The signed manifest's hash (gameIdOf) is your game id; a new version names the old id as its parent.
• game.js, what a node loads: the signed manifest, the core and its configs, and your donation set. A node checks all of it at start and refuses a game that does not match.

A game is four things: its rules (a small core every node can run and get the same result), its client (the web page the player sees), its donation key (where your share of the donations goes) and its manifest (your signed record of all of it). The example below is a whole game called coin-count: each tick the player presses a number, and the score is the sum.

1. Write the rules as pure arithmetic

   Nodes on different machines must reach the same score bit for bit. So the core may use only integers (or fixed-point), the round's seed and the player's inputs: no clock, no Math.random, no network, no files. Every core has the same small interface:

   // core.js - coin-count
   export const CORE = {
     name: 'coin-count',
     RUN_TICKS: 600,                                   // the longest run a round may ask
     runTicksFits: (t) => Number.isInteger(t) && t >= 1 && t <= 600,
     INPUT_WORDS: 5,                                   // a tick carries five input numbers
     start: (seedWord, config, { runTicks }) => ({ seed: seedWord | 0, sum: 0, ticks: 0, length: runTicks }),
     eventsOf: () => ({ count: { liquidations: 0, loads: 0, samples: 0, tapes: 0 }, before() {} }),
     step(st, words) { if (st.ticks < st.length) { st.sum += words[0] | 0; st.ticks++; } },
     stateHash: (st) => sha256(`coin-count:${st.seed}:${st.sum}:${st.ticks}:${st.length}`),
     result: (st) => ({ outcome: st.ticks < st.length ? null : 'DELIVERED', score: st.sum }),
   };

   The core's id is the SHA-256 of its file. A config (a set of rule numbers) is named by its hash too.

2. Write the client: what the player sees

   Your client is a web page at games/<game name>/index.html beside the Bitcoin Arena page. The page runs it only if its SHA-256 is in your manifest, so a client changed by one byte is refused. It gets the engine as window.parent.ARENA_GAME; stakes, locks, the wallet and the seed stay the engine's, so your client never touches a key.

   const A = window.parent.ARENA_GAME;
   A.rows();          // this game's open rounds: id, line, joinable, entry close
   A.identity();      // the player's name and key fingerprint (the same in every game)
   A.join(roundId);   // join, through the engine's own join and stake
   A.back();          // back to the list of games

3. Make your donation key: where your share is paid

   node packages/arena-donor/bin/arena-donor.mjs init ./my-game-dev --label "coin-count dev"
   # prints recipientPk: the key your game's donation set names

   The same tool later collects your donations from the federation and pays them to your own Lightning node.

4. Make your developer key

   node packages/arena-donor/bin/arena-donor.mjs game-key ./my-game-dev
   # writes ./my-game-dev/game-dev.pkcs8 (readable only by you) and prints your public key

   This Ed25519 key signs your game and every later version of it. Keep it safe; a node never sees it.

5. Write the manifest

   // body.mjs - coin-count, version 1
   import { RESULT_TYPE, PAYOUT_RULE, NO_PARENT } from './packages/arena-protocol/src/manifest.js';
   import { donationSetId } from './packages/arena-protocol/src/donation.js';
   const hex = (h) => Uint8Array.from(Buffer.from(h, 'hex'));
   export const DONATION_SET = [{ recipientPk: hex('02…your recipientPk…'), label: 'coin-count dev', shareBps: 10000 }];
   export const BODY = {
     gameName: 'coin-count', version: 1, parentManifestId: NO_PARENT,
     resultType: RESULT_TYPE.REPLAY, payoutRule: PAYOUT_RULE.RANK_CURVE, rankNumerator: 3, rankDenominator: 4,
     minScore: 1, runTicksMax: 600, roundPeriodMs: 0n,
     cores: [{ hash: hex('…sha256 of core.js…'), configs: [hex('…sha256 of your config…')] }],
     clients: [hex('…sha256 of games/coin-count/index.html…')],
     gameDonationSetId: donationSetId(DONATION_SET),
   };

6. Sign it

   node packages/arena-donor/bin/arena-donor.mjs sign ./my-game-dev body.mjs
   # {"step":"signed","game":"coin-count","version":1,"gameId":"…","file":"./my-game-dev/coin-count-manifest.hex"}

   That id is your game. Change one byte of the manifest and the id changes too.

7. Hand it to the nodes

   A node loads a game from a module that exports GAME, listed in its ARENA_APPS. It checks every piece against the manifest at start and refuses a game that does not match.

   // coin-count/game.js
   export const GAME = { name: 'coin-count', title: 'Coin Count', manifest, gameId,
     cores: new Map([[CORE_HASH, { name: 'coin-count', hash: CORE_HASH, url: CORE_URL, adapter: CORE,
       configs: new Map([[CONFIG_HASH, {}]]) }]]),
     donationSet: DONATION_SET };

   Then ask node operators to host it. Each decides alone; the game appears in the lobby of every page whose nodes host it. Check it with GET /games on their nodes.

8. Test on your own machine

   devnet.mjs new-game makes this whole game from the template, signed with your own keys, and a devnet hosts it on seven nodes and plays it end to end. packages/arena-node/tools/games-regtest.mjs serves a built page beside two nodes, so you see the game picker and your client.

9. Ship updates

   An update is a new manifest with the same key, version + 1 and the old game id as parentManifestId. Rounds already written keep the manifest they named.

Payout rules: the rank curve or a top-N split

A replayed game's manifest picks how its winners are paid:

• The rank curve (the default, Tick Tock's): the top quarter of the qualifiers share the losers' stakes with weights 0.75^rank−1, and qualifiers below them get their stake back.
• A top-N split (PAYOUT_RULE.TOP_SPLIT): fixed shares for places 1 to N, 1 to 10 shares in basis points that never increase and sum to 10,000. [10000] is winner takes all, [5000, 3000, 2000] pays three places. Places are ranked by score, then by key; each place is weighted by its share and its own net stake. With fewer qualifiers than shares, the unused shares go to the places filled in proportion (two players under 50/30/20 get 62.5 % and 37.5 %); nothing is left over for anyone else.

A manifest with a top-N split must require protocol version protocol 4, so a node that cannot pay it is never seated for its rounds. Existing manifests keep their bytes and game ids.

In a replayed game every run is checked on its own, so one player's score can never depend on what another player did. A head-to-head game is for the games where it does: each player picks a move in secret, all moves are shown together, and the game's rule decides who won. The engine hides the moves, reveals them, checks them and moves the money; your game only says which move beats which. The example is the real Rock Paper Scissors (packages/rock-paper-scissors).

A round, step by step

1. Hide. Before entry close the player enters with a commitment instead of a move: H(round id ‖ session key ‖ move ‖ salt), with a fresh 32-byte salt. Nobody can read the move from it, and nobody can copy it: it names the entry's own session key.
2. Wait for the other players. A round seats exactly the game's players. A further entry is refused ("that round already seats … 2 players").
3. Reveal. Between entry close and the round's end, each player sends its move and salt to every node (POST /reveal). A node takes it only if it hashes to that entry's commitment.
4. Decide. At the round's end every node pulls the other nodes' reveals (GET /reveals), hands all the moves to the game's rule, and signs each player's result, exactly as it signs a replayed run. Same moves, same rule, so every node signs the same result.
5. Pay. The result goes through the normal settlement, unchanged:

Build it

1. Write the rule

   One function: it gets the moves of the players who revealed and says WIN, DRAW or LOSS for each. Like a core it must be pure: same moves, same answer, on every machine.

   // plugin/decide.js - Rock Paper Scissors: 0 rock, 1 paper, 2 scissors
   export const DECIDE = {
     name: 'rock-paper-scissors decide v1',
     decide(moves) {                                   // [{ key, move }]  ->  { [key]: 'WIN' | 'DRAW' | 'LOSS' }
       const shown = [...new Set(moves.map((m) => m.move))];
       const out = {};
       if (shown.length !== 2) { for (const m of moves) out[m.key] = 'DRAW'; return out; }
       const beats = (a, b) => (a - b + 3) % 3 === 1;
       const winning = beats(shown[0], shown[1]) ? shown[0] : shown[1];
       for (const m of moves) out[m.key] = m.move === winning ? 'WIN' : 'LOSS';
       return out;
     },
   };

   Its id is the SHA-256 of its file, and the manifest names it in cores[], so a node installs and checks it just like a replay core.

2. Write the manifest

   export const BODY = {
     gameName: 'rock-paper-scissors', version: 1, parentManifestId: NO_PARENT,
     resultType: RESULT_TYPE.HEAD_TO_HEAD,
     cores: [{ hash: sha256(decide.js), configs: [sha256('rock-paper-scissors-config:v1')] }],
     runTicksMax: 0,                                   // no run
     payoutRule: PAYOUT_RULE.RANK_CURVE, rankNumerator: 3, rankDenominator: 4,
     minScore: 2,                                      // a win scores 2, a draw 1
     players: 2,                                       // 2 to 16: a round is played only with all of them
     moveCount: 3,                                     // 2 to 32 moves
     revealWindowMs: 120000n,                          // 10 s to 1 h: the longest a round may give for reveals
     roundPeriodMs: 0n, clients: [sha256(games/rock-paper-scissors/index.html)], gameDonationSetId,
   };

   Sign it and hand it to the nodes exactly as in Implement a game (arena-donor sign, a module exporting GAME, listed in ARENA_APPS).

3. Write the client

   Besides rows, identity and back, a head-to-head client gets these from window.parent.ARENA_GAME. The salt, the stake and the keys stay the engine's.

   const A = window.parent.ARENA_GAME;
   A.headToHead;          // { players, moveCount } - or null for another kind of game
   A.hide(roundId, move); // enter the round with this move hidden
   A.hidden(roundId);     // this tab's hidden move in that round (kept in the tab until revealed)
   A.hiddenAll();         // every move this tab hid in this game - a round leaves the rows at its entry close
   A.reveal(roundId);     // after entry close: send the move and salt to every node
   A.reveals(roundId);    // the moves the nodes hold: { [entryId]: move }
   A.result(roundId);     // the round as the nodes hold it: entries, each signed outcome and how many nodes signed it

   Show the players A.result, the signed result, not a verdict your page worked out itself. Rock Paper Scissors' client shows "waiting for an opponent (1 of 2)" before entry close, reveals at entry close, and then "You win - signed by 2 nodes".

4. Keep it apart from other games

   A page shows one game's rounds at a time: on nodes that host Tick Tock, Next Block and Rock Paper Scissors, the truck's lobby lists only its own rounds, and Rock Paper Scissors loads none of the truck.

5. Try it on your own machine

   ARENA_PAGE=<a page with games/rock-paper-scissors/index.html> node packages/rock-paper-scissors/tools/demo-regtest.mjs ./work
   # a private test chain, two nodes hosting both games, one free round always open; prints the lobby link

   Open the link twice in two browser profiles (two players) and add &game=rock-paper-scissors.

A market is a round where players pick one outcome and the right picks share the stakes of the wrong ones. It uses the same custody, nodes and settlement as a game, but there is no core and no run: the result is the outcome reported by the attestors you name.

1. Choose the question, the outcomes and who reports the result

   2 to 16 outcomes, for example ['up', 'down']. Then 1 to 16 attestors: Ed25519 keys of the people or services that report the outcome (for example three price-feed operators), and how many of them must sign the same outcome (for example 2 of 3). Players see who decides before they stake.

2. Write the manifest

   The same as a game's, with these differences:

   export const BODY = {
     gameName: 'btc-up-down', version: 1, parentManifestId: NO_PARENT,
     resultType: RESULT_TYPE.ATTESTED,          // the result is an outcome, not a replayed run
     payoutRule: PAYOUT_RULE.PARI_MUTUEL,       // the right picks share the wrong picks' stakes
     outcomes: ['up', 'down'],
     attestors: [KEY_A, KEY_B, KEY_C],          // 32-byte Ed25519 public keys
     attestThreshold: 2,                        // 2 of the 3 must sign the same outcome
     cores: [], runTicksMax: 0,                 // nothing to run
     clients: [hex('…sha256 of games/btc-up-down/index.html…')],
     gameDonationSetId: donationSetId(DONATION_SET),
     // … roundPeriodMs and the rest as for a game
   };

   Sign it and hand it to the nodes exactly as for a game (steps 4, 6 and 7 above). Your client shows the outcomes; the page's own pick sheet takes the stake and the pick.

3. Players pick and stake

   An entry into a market round carries a pick, the index of one outcome. Nodes refuse a pick that is out of range, and any pick once they hold a valid result for that round.

4. Report the outcome

   After the entry close, your attestors sign the round's outcome and anyone posts it to the nodes. What they sign is the id of { round id, outcome index, observed time in ms }:

   import { createPrivateKey, sign } from 'node:crypto';
   import { attestationBodyId, encodeAttestation } from './packages/arena-protocol/src/attested.js';
   
   const body = { roundId, outcome: 0, observedAtMs: BigInt(Date.now()) };   // 0 = 'up'
   const digest = Buffer.from(attestationBodyId(body));
   const signatures = [attestorA, attestorB].map((a) => ({
     key: a.publicKey,                                                     // 32 bytes
     signature: new Uint8Array(sign(null, digest, a.privateKey)),          // Ed25519, 64 bytes
   }));
   const attestation = encodeAttestation({ ...body, signatures });
   
   for (const node of committeeNodes)
     await fetch(`${node}/outcome?round=${roundIdHex}`, { method: 'POST', body: attestation });

   Each node checks that the attestation is for this round, that the outcome exists, and that enough of the named attestors signed it. It answers why when it refuses.

5. Follow it

   GET /outcome?round=… answers the round's state: OPEN (no result yet), ATTESTED (one outcome, with the payout table) or DISPUTED. The round settles once a result has stood for the objection window (600 s) with nothing contradicting it.

6. If attestors contradict themselves

   Two valid attestations of different outcomes for one round are the proof that the attestors disagreed. The round is DISPUTED and pays out on neither outcome; the stakes go back to their players by the refund path.

How a market pays out (pari-mutuel)

• A market's fees are its own, set in its manifest: 0.5% to the nodes and 0.5% donation by default, at most 5% each and 10% together. Its net stake in the pool is the stake less those fees: a 1 sat pick at 1% stakes 0.99 sat on the odds.
• The fees are due when an order fills, for winners and losers alike; a pick fills at the round's entry close. Before that, an order can be cancelled at no cost: the player signs POST /cancel, and its stake and fee locks come back at once. The fees sit in the fee lock until the market resolves; then the nodes take their part and the donation is paid to the protocol developers' and the market developer's keys.
• Every entry that picked the winning outcome gets its net stake back plus its share of the losing pool: losing pool × its net stake ÷ all winning net stakes, rounded down; the millisats left over go one each to the winners.
• If nobody picked the winning outcome, or the market is void, everything goes back: every stake and every fee. A market is void if its attestors contradict each other, or if no outcome stands by its deadline.
• There is no house and no counterparty: the wrong picks pay the right ones.

Bitcoin Up or Down, every 15 minutes

The first market follows Polymarket's BTC Up or Down 15m. There is one market per quarter hour with two outcomes, Up and Down. Up wins if the time-weighted average BTC price over the window is at or above the price at its start (the price to beat); a tie is Up. The attestors apply that rule to the prices they read (upDownOutcome in packages/arena-protocol/src/up-down.js) and sign the outcome.

Trading uses signed limit orders. Prices are in whole cents (0.01 to 0.99), an order buys at least 5 shares, and a share pays 1 sat if its side wins. An Up buyer at 0.73 and a Down buyer at 0.27 together fund a share. The nodes clear each batch of orders at one price that every node computes the same way (clearBatch in order-book.js). The fee is charged on the part of an order that filled, when it fills; what has not filled can be cancelled at no cost.

The example market btc-close (three outcomes, three attestors, 2 of 3) lives in packages/arena-node/test/plugins/market/ with its own client, and packages/arena-client/tools/market-live.sh runs it on a private test chain end to end.

Event-market templates

A market manifest can be a template: one signed set of rules (attestors, threshold, fees, deadline) whose rounds each ask their own question. The template names a category, the most outcomes a round may have (2 to 16) and how long after the entry close a round must resolve. Each round's contract then carries its event: the question (1 to 280 bytes), 2 to 16 unique outcome labels (1 to 64 bytes each) and when it resolves.

• A template must name its market terms, require protocol version protocol 3 or later, and run on no grid. Rounds are written one by one.
• Nodes refuse a template round without an event, an event on any other game's round, too many labels, or a resolution time outside the template's window.
• The attestors sign an outcome index into the round's own labels. GET /rounds rows carry the event; GET /round names it in the x-question, x-outcomes and x-resolve-at-ms headers; GET /outcome answers with the question and labels. The page shows the question and labels from the contract it checked.

Markets on games

A market can be on a game round: spectators back BULLS or BEARS of one Tick Tock round, and that round's own result, signed by 5 of its 7 nodes, decides the market. No attestor and no outside source. Built in protocol version protocol 6; it runs once nodes advertise that version.

• The manifest names the source game, the kind of result it reads (a Tick Tock round's result: BULLS, BEARS or FLAT) and which outcome each result pays, or a refund. It names no attestors, and no attestation is taken for it.
• Each round of the market names the one source round it is on. Its entries must close before that round starts, and the source round must end by the market's resolution time; otherwise the market is void and every stake goes back.
• FLAT (or any result the manifest maps to a refund) gives every stake back at once; so does no signed result by the deadline.
• The nodes of a market round fetch the source round's signed result themselves once it has ended, check it against the committee they draw for it, and keep it as the market's outcome: the market then settles like any other (pari-mutuel), after the objection window. A node that does not hold the source round fetches its contract from other nodes and checks it against the round's id. Anybody can also hand a node the result at POST /game-outcome; GET /outcome shows it with its signatures. Rock Paper Scissors is not a source yet: it signs each player's result, not a table winner.

Scalar markets

A market can ask for a number - a price, a count - and pay by where it lands between two bounds, instead of one outcome per bucket. Built in protocol version protocol 7; it runs once nodes advertise that version.

• The manifest names the bounds low < high (whole numbers, may be negative) and their unit, and its two outcomes are the sides LONG and SHORT. A player picks a side.
• The attestors (k of n, as for any market) sign the value they observed in a value attestation of its own kind - an outcome attestation is refused for a scalar market, and a value attestation for any other. Hand it in at POST /outcome, as an outcome attestation.
• The value is clamped to the bounds. LONG's share of the whole pool (the net stakes of both sides) is (value - low) ÷ (high - low), SHORT's the rest; each side's share is split over its own players by their net stakes. Every amount is whole millisats, rounded down, the leftovers to named places; nothing is kept back.
• If only one side has players there is no counterparty, and every stake goes back, its fee too. No value by the deadline, or two different values signed, makes the market void: every stake back.

Every paid entry is split by the protocol version the game requires. Versions run side by side: a round keeps the split of its own version.

On protocol 11 the whole split is fixed: the developers' 4% is no longer a donation the player lowers. Before 11 the developers' 5% is a donation, 5% by default, down to zero. A 100 sat entry on protocol 11 pays the nodes 4 sat, the developers 2 + 2 sat, the reserves 2 sat, and puts 90 sat in play. A prediction market charges its own manifest's fees instead: 1% by default (0.5% nodes, 0.5% donation), due when it resolves (see Implement a prediction market).

Items (an add-on bought in a game, such as Tick Tock's larger truck) on protocol 11: 40% of the list price to the nodes and 20% to the protocol reserves, both fixed, plus the developers' share the player chooses (40, 30, 20, 10 or 0%, half game, half protocol). The player pays 60% plus that share: a 500 sat item costs 500 sat at the 40% default and 300 sat at 0%.

Protocol reserves

The protocol reserves are the network's own fund. No company and no single key holds them, and they are spent only on what the bonded nodes vote for.

• Where they are: in the federations. Each paid entry and item locks its reserve share in its own federation to that federation's reserve key, a 5-of-7 key its seven guardian seats made together. No seat holds the key alone; 5 of the 7 must sign to move anything.
• How you see them: every node answers GET /reserves with the total, per federation, the payments in and every payment out. bitcoinarena.io shows the live total under the fees once five nodes name the same one, and the node dashboard shows what each round paid in.
• When a federation is drained (it is closing or has lost guardians), its reserves move on their own to a healthy federation: its successor, or else the open federation with the lowest id. No vote is needed for that move; every node records it.

The referral program

A website that brings players earns 10% of the nodes' fee on every stake they place. It comes out of the nodes' part: the player's stake and fee are the same with or without it. On a 10,000 sat stake the nodes' fee is 400 sat (4%), the website gets 40 sat and the nodes keep 360.

• A program is a key. Each entry can name a website's payout key (33 bytes, signed into the entry, so no node can swap it). At settlement that key is paid its share in the round's federation, beside the other payouts. From an order book: 10% of the nodes' part of each filled order's fees.
• Run one from your node. In the owner area, Referrer: name a program and your node makes its key. You can have several, each earns on its own. Its name is signed with its own key and shown on the explorer's Metrics page and on Health.
• Bring players. Link to https://testnet.bitcoinarena.io/?ref=<key> (the page keeps it 30 days), or host a game on your site in an iframe: /?game=rock-paper-scissors&ref=<key>. The demo page does exactly that.
• Withdraw over Lightning. Your node collects the program's payouts in the federation. In Referrer, Withdraw pays a Lightning invoice or a Lightning address.
• Where it is counted: every node answers GET /referral-fees with what each program earned and its name.

The 10% is a network fee like the others: a passed fee proposal can set it between 0 and 40% for rounds after it takes effect. It was 20% until 2026-10-25. Step by step: Referral Program.

Funding proposals: how the reserves pay out

Anyone can propose a payout, not only a developer: a player, a developer or a node operator, for any project and to any Lightning address. A proposal names its purpose, the amount in sat and the Lightning address (LNURL) to pay, and is signed by its author's key. Anyone can comment on it, in threads; comments carry no weight.

1. Signal (1 week, 1008 blocks)

   Nodes signal support. The proposal goes on to the vote if the nodes supporting it are at least 15% of the nodes that served a round in the 72 hours (432 blocks) before the week ends. Nothing is paid on a signal.

2. Vote (2 weeks, 2016 blocks)

   Bonded nodes vote YES, NO or ABSTAIN on Bitcoin, weighted by bond and age (rules 1 and 2 below). It passes when 60% of the votes say YES and YES is at least 20% of everyone who could vote. It is decided once its last block is 6 deep.

3. Payout

   After the 2-week window (rule 5), the federation that holds the reserves pays the proposal's Lightning address, signed by 5 of its 7 guardian seats. If the payment fails, the money returns to the reserve key. Every node records the payout with its proof (the payment's preimage and the federation transaction).

Five rules, so nobody can rent a majority. Bonding a lot of bitcoin for a few weeks to vote yourself a payout does not work:

1. Who votes: bonds at least 3 months old when the proposal is published, that stay locked at least 3 months after the vote. A bond past its lock date still serves rounds but no longer votes.
2. How much they count: bond × age: 1× under a year, 2× from one year, 3× from two. Nodes that have been in the game longer outweigh new money.
3. When it passes: 60% of the votes say YES, and the YES votes are at least 20% of everyone who could vote.
4. How much it can take: at most 10% of the reserves per proposal, and 25% in any 3 months.
5. Time to say no: nothing is paid for 2 weeks after the vote, and NO votes in that time stop it. Above 1% of the reserves, it is paid in 4 monthly parts, each one stoppable the same way.

The signal counts only nodes with a bond at least 3 months old that served rounds in 3 of the last 4 weeks. No vote can pass in a network's first 3 months.

Review and discuss: the Project proposals forum lists every proposal the nodes hold, with its stage and its replies. Reply or propose there with the same key you play with, or with your nsec.

To post a proposal, sign it and send it to any node: POST /funding with { "kind": "proposal", "hex": ... }; the nodes pass it on to each other. GET /funding lists every proposal with its comments, signals and vote. A node owner can propose, comment and signal from the owner area.

What Bitcoin Arena is built with, and what each part is for.