On this page
  1. §0 The area in one paragraph
  2. 1. The app row, seats, the pool and the shared settlement
  3. 2. CreateApp (24)
  4. 3. JoinApp (25)
  5. 3a. An unstarted multiplayer app closes itself
  6. 4. AppMove (26)
  7. 5. ResignApp (27) and ClaimAppTimeout (28)
  8. 6. Solo apps: the draw, the payout tables and the resolver
  9. 7. The rules engine
  10. 8. SettleApp (39) and the channel settlement
  11. 9. Views, ledger rows and the consensus/local split

16 — On-chain apps: CreateApp, JoinApp, AppMove, ResignApp, ClaimAppTimeout, SettleApp

Edition 0.6.1 · verified against the reference implementation, version 0.6.1

Out of scope the fee floor and refund (04); the same-account test, groups as players (18); the block seed's own derivation (05); the exchange whose hold helpers these executors reuse (15); the genesis apps_treasury credit (06); signature verification by address type (02)

§0 The area in one paragraph

An app is a row keyed by its CreateApp's id that holds a stake per player, a state blob, whose player is on the clock, and a deadline. Solo apps (types 16–21) are bets against the apps pool, the protocol account ZBCAPPS: the stake goes into the pool at creation and the outcome is drawn two blocks later from that block's seed with a fixed payout table per type (each table carries the house edge), paid from the pool and capped per bet at 5 % of the pool. The draw is tagged, a block whose blocksmith is the bettor does not resolve the bet, and the solo wins paid in any window of one day never exceed the solo stakes bet in it: a win beyond that is owed and paid by later blocks. Every player is a typed account, of any kind that can sign (a channel app: of a kind that signs a 64-byte move voucher, ZooBC, Solana, Polkadot or Taproot). Multiplayer apps (types 1–8 with 2–4 seats, 32–35 with 2–4) wait Open until every player has paid the same stake, then run turn by turn: every move is an AppMove judged by a native rules engine, one engine per type, specified below move by move; a dice game's move waits one block and is applied by the next block's resolver, and a multiplayer app's opening player is drawn two blocks after the join, both so the including blocksmith never sees the roll. A decisive end pays the winner the pot minus a 1 % rake to the pool, a draw refunds every player, and a resignation or a missed 240-block deadline hands the pot minus the rake to the other seats. A multiplayer app nobody starts within app_open_timeout_blocks (161,280 blocks, four weeks; DevNet 200) closes itself: every seated player gets its stake back less 10 % (app_unused_share_bps), which goes to the longevity pool (ZBC is never burned). A channel app (2 seats, channel 1) is played off-chain with signed vouchers and settled by a SettleApp that replays them, with a 240-block challenge window in which a longer valid chain overrides. Every number here is integer arithmetic on the block seed; nothing in this area is reserved at admission except a ZBC stake.

1. The app row, seats, the pool and the shared settlement

Purpose. The state and arithmetic every mechanism below shares.

Inputs. The transactions below and the per-block resolvers.

Output and effect. app(id, app_type, status, seats, creator_address, players, opponent_address, stake_token_id, stake_amount, pot, state_blob, turn, created_height, last_move_height, deadline_height, resolve_height, winner_address, persist_height, channel, block_height, latest, pending_move, owed_payout, paid_payout), key (id, block_height), versioned (07 §2); status 0 Open / 1 Active / 2 Finished / 3 Cancelled (written when an unstarted app closes itself, §3a); persist_height is never written (0); pending_move = a dice game's move awaiting the next block's seed, [tx id 8 LE][move bytes], empty when none (§4); owed_payout = what the pool still owes a won solo bet, paid from later blocks' caps in id order (§6); paid_payout = what the pool has paid that bet so far, every tranche included (§6). Types: id, stake_token_id, stake_amount, pot, owed_payout, paid_payout signed 64-bit; app_type, seats, status, channel small integers; turn signed 32-bit (−1 = pending); heights unsigned 32-bit; creator_address, opponent_address, winner_address typed account bytes (empty when none); players, state_blob, pending_move byte strings. app_settlement(app_id, claimant_address, final_seq, outcome, winner_seat, turn, state_blob, challenge_deadline_height, resolved, block_height, latest), key (app_id, block_height). Reads the logic depends on (each on the latest rows): an app by id; the apps to resolve (Active with 0 < resolve_height ≤ height, or with a non-empty pending_move) in ascending id; the apps with owed_payout > 0 in ascending id; the Open multiplayer apps with created_height ≤ height − T in ascending id; the sum of stake_amount of solo rows (types 16–31) of one stake token with created_height in (since, height]; the sum of paid_payout of solo rows of one stake token with block_height in (since, height]; the unresolved settlements with challenge_deadline_height < height in ascending app id. A rollback to H deletes the rows above H.

  • A player is a typed account (01: its 4-byte LE type first) of 4 to 255 bytes whose type can sign (types 0, 1, 4, 5, 6, 7, 9, 11, 12, 13, 14, 15, 16; not 2, 3, 8, 10 or an unknown type). players is the seats in joining order, the creator first, each written as one byte n (its length) then the n bytes of the account; a solo app has its one player the same way. Reading players: from offset 0, take n = the byte at the offset; n = 0, or fewer than n bytes left, ends the list (a malformed tail seats nobody); else the next n bytes are a player and reading goes on after them. The player count is the number of seats read; turn indexes them. A sender is matched to a player by byte equality with the player, or else by the same-account test (18 §1, a member of a seated group acting as the group).
  • The pool is the account 00000000 ‖ "ZBCAPPS" ‖ 25 × 0x00 (36 bytes). Every chain funds it in genesis (apps_treasury, 06; TestNet: 10,000,000 ZBC and genesis-coin balances). Its ZBC balance is read as the confirmed balance (not the spendable one, which a node's own pending reservations would move). It is rent-exempt (13 §9).
  • Constants: rake APP_RAKE_BPS 100; move window APP_MOVE_WINDOW 240 blocks; settlement window SETTLE_CHALLENGE_WINDOW 240; bet cap APP_MAX_PAYOUT_FRAC_BPS 500; at most 100 plays per bet; solo resolution at creation + 2.
  • Settling a win: rake = floor(pot × 100 / 10,000); winner +(pot − rake) (asset 0: row event 100, app payout), pool +rake (event 67); winner_address = the player. A draw: every player +stake_amount (event 100), no rake, no winner. A split (resign, timeout, channel forfeit): net = pot − rake, shared equally among the winning seats in player order with the remainder to the first of them (event 100 each), pool +rake (event 67); winner_address set only when one player wins. Token stakes move with no ledger row.

How to compute it. As stated; every division floors.

Rule activation. None in this area; state_answer_noop (height 0) where noted.

Rejections and errors. None.

Vector. computed.

  • Input: a 2-player app whose seats are the ZooBC account 00000000B6675786BEDF28B3E7DCD8BAC9BF99758B3A64604570BFFD12FD10CBF20B39EA (36 bytes) and an Ethereum account 04000000 ‖ 0102030405060708090A0B0C0D0E0F1011121314 (24 bytes).
  • Expected output: players = 2400000000B6675786BEDF28B3E7DCD8BAC9BF99758B3A64604570BFFD12FD10CBF20B39EA18040000000102030405060708090A0B0C0D0E0F1011121314 (62 bytes); player count 2; player 1 is the Ethereum account. The players bytes 24 00 00 (a length 36 with 2 bytes after it) read as no player at all.
  • Input: a win of pot 200,000,000. Expected: rake 2,000,000 (event 67 on the pool), the winner +198,000,000 (event 100). A 3-player resignation of pot 300,000,000: net 297,000,000, each of the two other seats +148,500,000, remainder 0, rake 3,000,000.
  • computed (from the genesis files): GET /api/v1/apps/pool before any bet answers "zbc":1000000000000000 (the apps_treasury of both the TestNet and the DevNet genesis file: 10,000,000 ZBC) and the pool's genesis-coin balances (06).

Test cases · §1

5 cases · 5 valid · 1 reference

A ZooBC player and an Ethereum player in the players field16-1-seatsvalid

Loading the test widget…

A length of 36 with two bytes after it reads as no player at all16-1-malformedvalid

Loading the test widget…

The apps pool before any bet: the apps treasury of both genesis files16-1-poolvalidreference

A stated value: there is nothing to compute. A compatible node shows the same value.

zbc
1000000000000000
A win of a pot of 2 ZBC: the rake and the winner's share16-1-winvalid

Loading the test widget…

Player 0 resigns a 3-player app of pot 3 ZBC16-1-resign-threevalid

Loading the test widget…

Defects to match. (1) persist_height exists in the row and is never used. (2) A Finished or Cancelled app's row is never pruned by this area.

2. CreateApp (24)

Purpose. Place a solo bet, or open a multiplayer app with the creator's stake.

Inputs. Body:

Offset Length Field Encoding
0 1 app_type u8 (§6, §7)
1 8 stake_token_id i64 LE (0 = ZBC)
9 8 stake_amount i64 LE ≥ 0
17 1 seats u8: 1 = solo; 2…4 multiplayer
18 2 plen u16 LE
20 plen params the bet (§6) or the type's setup (battleship: 3,200 bytes)

After params, with rem = the number of bytes left:

rem What follows params
0 nothing: no opponent, channel 0
1 channel (1 byte; 1 = state channel, seats must be 2)
4 + n or 5 + n n (u32 LE, 4 ≤ n ≤ 255), the invited opponent's typed account (n bytes), then, when rem = 5 + n, the channel byte
anything else (2, 3, or a length that does not match) not a body

Output and effect. The stateless rules (below) at every height. The creator must be of a kind that can sign (§1), else block invalid ("apps take a player of a kind that can sign", checked before any debit). Solo (seats 1): the largest payout of the bet (§6) must be ≤ floor(pool balance of the stake asset × 500 / 10,000) (the pool's confirmed ZBC balance or its token balance), else a paid no-op; the fee; the stake leaves the sender into the pool (ZBC: rows event 66 −stake on the sender and +stake on the pool; a refusal → nothing more, fee kept, no row); the row: id = tx.id, seats 1, players = the creator alone (the form of §1), state_blob = params verbatim, status Active, resolve_height = height + 2. Multiplayer: the fee; the stake leaves the sender (event 66; a refusal → nothing more, fee kept, no row); the row: status Open, pot = stake, players = the creator alone, state_blob = the type's initial state (§7), turn 0, opponent_address = the opponent bytes as given (empty when none). creator_address = the sender as the dispatcher presents it (08). Then 04 §5.

How to compute it. Stateless (admission mirror and execution alike, every height): not a body by the layout above ("CreateApp body too short" at admission / "Invalid CreateApp body" at execution, block invalid); "Unknown app type" (types 1–8, 16–21, 32–35 only); "negative stake"; "not a single-player app" (seats 1 with a type outside 16–21); "seats must be 1 (solo) or 2..4 (multiplayer)"; "state-channel apps must have seats == 2"; "battleship needs seats=2 + a 3200-byte board commitment"; dice: "dice: need [type, total]", "dice: bet type must be 0..3 (under/lucky7/over/exact)", "dice: exact total must be 2..12"; crash: "crash: missing target multiplier", "crash: target must be 1.01x..10x"; "app: repeat count N exceeds 100", "app: stake too small to split across N plays" (N > 1 and floor(stake / N) = 0). Stateless as well (rule admission_checks_in_block, admission and block validation): "CreateApp: apps take a player of a kind that can sign" (the creator's kind) and "CreateApp: the invited opponent's kind cannot sign, so nobody could join" (an opponent whose kind cannot sign), so a block carrying either is invalid. Then (rule canonical_account_forms, stateless too, admission and block validation, in this order): an opponent in a full-key form (01: an Ethereum or Tron type followed by a 64-byte key, a Bitcoin legacy, P2PKH or P2WPKH type followed by a 33- or 65-byte key) → "CreateApp: the invited opponent: a full-key account form (an Ethereum or Tron key, a Bitcoin key) is not an account: no transaction can be sent from it; name the 20-byte address (rule canonical_account_forms)"; for a channel app (channel 1), a creator, or an invited opponent, whose kind does not sign a 64-byte move voucher (§8: only types 0 ZooBC, 9 Taproot, 11 Solana and 12 Polkadot do; Ethereum and Tron sign 65 bytes, the Bitcoin kinds and Ripple 99 or 131, Cardano and Tezos 98) → "CreateApp: a state-channel app's seats sign 64-byte move vouchers, and the creator's kind cannot (create it as an on-chain app; rule canonical_account_forms)", or the same with "the invited opponent's kind" in place of "the creator's kind". A channel app ends only by SettleApp (AppMove, ResignApp and ClaimAppTimeout change nothing for it), so any other kind could never settle and could only lose by forfeit; every other app ends by moves, ResignApp, ClaimAppTimeout or the close of §3a, which every kind that signs can send, and takes every such kind. Admission (state): "CreateApp: insufficient balance for the stake" (spendable ZBC or token balance ≥ stake), "CreateApp: bet too large for the apps pool (largest payout P exceeds the pool's cap for one bet, C)". A ZBC stake is reserved at admission (04 §7). Execution (block invalid): "negative fee", "apps take a player of a kind that can sign", for a multiplayer app "CreateApp: the invited opponent's kind cannot sign, so nobody could join", then the canonical_account_forms texts above (unreachable in a valid block: block validation refuses them first).

Rule activation. state_answer_noop, admission_checks_in_block, canonical_account_forms (active from height 0 on every chain).

Rejections and errors. As listed.

Vector. computed.

  • Input: CreateApp (type 24) by 00000000B6675786BEDF28B3E7DCD8BAC9BF99758B3A64604570BFFD12FD10CBF20B39EA at height 11,877, fee 5,000,000, body (24 bytes) 12 0000000000000000 00CA9A3B00000000 01 0300 010001 00 = type 18 roulette, ZBC, stake 1,000,000,000, seats 1, params 010001 (colour, red, one play), rem 1: channel 0; the pool holds 1,000,000,000,000,000 ZBC; call the app's id G (the LE i64 of the first 8 bytes of the transaction's hash; a hash beginning E2400E49C2A0FE49 gives G = 5,331,875,765,163,016,418).
  • Expected output: the sender −1,000,000,000 and the pool +1,000,000,000 (rows event 66); the row (G) Active, players = 24 ‖ the sender, state 010001, resolve_height 11,879. Largest payout (per type, §6: roulette stake × 36) 36,000,000,000 ≤ the cap floor(1,000,000,000,000,000 × 500 / 10,000) = 50,000,000,000,000.
  • computed Input: a tic-tac-toe app (type 1) for two, stake 100,000,000 ZBC, inviting the 36-byte account 00000000120EE4CA…E807: body 01000000000000000000E1F505000000000200002400000000000000120EE4CA9D258D75656901EC4837373E07763369AD75ED8D63FA31C7E0B7E807 (60 bytes; the same followed by 01 = a channel app, 61 bytes). Expected: the row Open, pot 100,000,000, state_blob 9 zero bytes, opponent_address = those 36 bytes.
  • Invalid input: the 20-byte head followed directly by the 36-byte account (56 bytes: rem 36, n reads 0) → "CreateApp body too short" (admission), "Invalid CreateApp body" (block invalid). Params 0300 for type 16 with seats 1 (dice: exact total must be 2..12). A creator whose account is type 10 → "CreateApp: apps take a player of a kind that can sign". The tic-tac-toe body above with the opponent 0A000000 ‖ 32 bytes (a ZBS_ address, type 10) → "CreateApp: the invited opponent's kind cannot sign, so nobody could join": refused at admission, and a block carrying it is invalid.
  • Input (a channel app): the 61-byte channel body above (the same 60 bytes followed by 01), sent by the ZooBC account 00000000B6675786…39EA, inviting the ZooBC account 00000000120EE4CA…E807. Expected: accepted; the row Open with channel 1.
  • Invalid input (rule canonical_account_forms, stateless: refused at admission, and a block carrying it is invalid): that 61-byte channel body sent by an Ethereum account 04000000 ‖ 0102030405060708090A0B0C0D0E0F1011121314 → "CreateApp: a state-channel app's seats sign 64-byte move vouchers, and the creator's kind cannot (create it as an on-chain app; rule canonical_account_forms)"; sent by the ZooBC account and inviting that Ethereum account (body 01 0000000000000000 00E1F50500000000 02 0000 18000000 04000000 0102030405060708090A0B0C0D0E0F1011121314 01, 49 bytes) → "CreateApp: a state-channel app's seats sign 64-byte move vouchers, and the invited opponent's kind cannot (create it as an on-chain app; rule canonical_account_forms)"; the same 49 bytes without the final 01 (an on-chain app, 48 bytes) are accepted. An invited opponent in its full-key form, 44000000 ‖ 04000000 ‖ 79BE667EF9DCBBAC55A06295CE870B07029BFCDB2DCE28D959F2815B16F81798483ADA7726A3C4655DA4FBFC0E1108A8FD17B448A68554199C47D08FFB10D4B8 (the 64-byte key of the secp256k1 private key 1; its 20-byte form is 04000000 ‖ 7E5F4552091A69125D5DFCB7B8C2659029395BDF), in place of the 36-byte opponent of the 60-byte body (92 bytes) → "CreateApp: the invited opponent: a full-key account form (an Ethereum or Tron key, a Bitcoin key) is not an account: no transaction can be sent from it; name the 20-byte address (rule canonical_account_forms)".

Test cases · §2

11 cases · 4 valid · 7 invalid

A roulette bet of 10 ZBC on red at height 11,877, its id G from a hash beginning E2400E49C2A0FE4916-2-roulettevalid

Loading the test widget…

A tic-tac-toe app for two at 1 ZBC, inviting one account16-2-ttt-invitevalid

Loading the test widget…

The same as a channel app, between two ZooBC accounts16-2-ttt-channelvalid

Loading the test widget…

Inviting a ZBS_ address: nobody could join16-2-zbs-opponentinvalid

Loading the test widget…

A channel app created by an Ethereum account16-2-channel-eth-creatorinvalid

Loading the test widget…

A channel app inviting an Ethereum account (49-byte body)16-2-channel-eth-opponentinvalid

Loading the test widget…

The same invitation as an on-chain app (48 bytes) is accepted16-2-onchain-eth-opponentvalid

Loading the test widget…

An invited opponent in its full-key form (92-byte body)16-2-full-key-opponentinvalid

Loading the test widget…

The opponent appended without its length16-2-bare-opponentinvalid

Loading the test widget…

A dice bet on an exact total of 016-2-dice-exact-3invalid

Loading the test widget…

A ZBS_ account cannot create an app16-2-zbs-creatorinvalid

Loading the test widget…

Defects to match. (1) A stake of 0 is accepted (it closes with nothing to return). (2) A token stake is not reserved at admission.

3. JoinApp (25)

Purpose. Join an Open app with an equal stake; the last player to join starts the app.

Inputs. Body: app_id (8, i64 LE); bytes beyond ignored.

Output and effect. Unknown app → block invalid; status ≠ Open → paid no-op; full → paid no-op; an opponent_address that is set and is neither byte-equal to the sender nor the same account (18 §1) → block invalid ("Not the invited opponent"); the sender already seated → paid no-op; a sender of a kind that cannot sign → block invalid ("apps take a player of a kind that can sign", before the stake debit); for a channel app (channel 1), a sender of a kind that does not sign a 64-byte move voucher (§2: not type 0, 9, 11 or 12) → block invalid ("JoinApp: a state-channel app's seats sign 64-byte move vouchers, and this kind cannot", before the stake debit); the fee; the stake leaves the sender (event 66; a refusal → nothing more, fee kept); the player (the sender as presented, 08) is appended to players (§1), pot += stake; when the seats are full: status Active, deadline_height = height + 240, turn pending (−1, nobody on the clock, every move a no-op) and resolve_height = height + 2; the resolver of §6 draws the opening player from the seed of the block at resolve_height (one the join block's blocksmith never saw) as R(that seed, id, 0) mod seats (§6). Battleship (type 7) is exempt: turn 1 at once (the joiner commits first). Then 04 §5.

How to compute it. Admission, in this order: "JoinApp: apps take a player of a kind that can sign", "JoinApp body too short", "JoinApp: unknown app", "… app is not open", for a channel app a sender whose kind does not sign a 64-byte voucher "JoinApp: a state-channel app's seats sign 64-byte move vouchers, and this kind cannot (rule canonical_account_forms)", the close of §3a (below), "… app is full", "… not the invited opponent", "… already joined", "… insufficient balance for the stake"; when judged for a block, at or after the close height of §3a, "JoinApp: nobody started the app in T blocks; it closes itself at height H" (H = created_height + T); block assembly leaves such a join out, and a mined one finds the app Cancelled (a paid no-op). Execution (block invalid): "Invalid JoinApp body", "Unknown app", "Not the invited opponent", "apps take a player of a kind that can sign", "JoinApp: a state-channel app's seats sign 64-byte move vouchers, and this kind cannot", "Fee cannot be negative". The app's channel flag and the sender's kind never change, so admission's answer is the block's.

Rule activation. apps_seed_after_bet, apps_turn_plus_two (the pending opening turn) and canonical_account_forms (the channel-app kinds), active from height 0 on every chain.

Rejections and errors. As listed. The stake is not reserved at admission.

Vector. computed (the tic-tac-toe app of §2 with id G, invited opponent O = 00000000120EE4CA…E807).

  • Input: JoinApp (type 25) by O at height h, body = LE64(G), O holding ≥ 100,000,000 + fee.
  • Expected output: O −100,000,000 (event 66); players = 24 ‖ creator ‖ 24 ‖ O; pot 200,000,000; status Active, deadline_height h + 240, turn −1, resolve_height h + 2; at h + 2 the resolver sets turn = R(seed of h + 2, G, 0) mod 2 and resolve_height 0.
  • Invalid input: the same join by any other account → refused at admission "JoinApp: not the invited opponent"; mined, the block is invalid ("Not the invited opponent"). A second join after the app is full → "JoinApp: app is full". A join of a channel app created with the 21-byte body 01 0000000000000000 00E1F50500000000 02 0000 01 (tic-tac-toe, stake 100,000,000 ZBC, two players, no invited opponent, channel 1) by the Ethereum account 04000000 ‖ 0102030405060708090A0B0C0D0E0F1011121314 → refused at admission "JoinApp: a state-channel app's seats sign 64-byte move vouchers, and this kind cannot (rule canonical_account_forms)"; mined, the block is invalid ("JoinApp: a state-channel app's seats sign 64-byte move vouchers, and this kind cannot"); the same join of an on-chain app is accepted.

Test cases · §3

7 cases · 2 valid · 5 invalid

The invited opponent joins and the app starts16-3-joinvalid

Loading the test widget…

Another account cannot join in the invited opponent's place16-3-not-invitedinvalid

Loading the test widget…

Mined, that join makes the block invalid16-3-not-invited-minedinvalid

Loading the test widget…

A join after the app is full16-3-fullinvalid

Loading the test widget…

An Ethereum account joins a channel app16-3-channel-ethinvalid

Loading the test widget…

Mined, that join makes the block invalid16-3-channel-eth-minedinvalid

Loading the test widget…

The same join of an on-chain app is accepted16-3-onchain-ethvalid

Loading the test widget…

Defects to match. None.

3a. An unstarted multiplayer app closes itself

Purpose. A multiplayer app nobody starts does not lock its stakes for ever.

Inputs. The Open apps with seats > 1; app_open_timeout_blocks T (genesis parameter: 161,280 = 28 days of 15-s blocks on mainnet and testnet, 200 on DevNet; the builder requires 1 … 2³²−1); app_unused_share_bps b (genesis parameter: 1,000 = 10 % on TestNet and DevNet; the builder requires 0 … 10,000; read clamped to that range); the block height and timestamp.

Output and effect. At the start of every block above 0, after the solo resolver (§6) and the settlement resolver (§8) and before the block's transactions: every app with latest, status Open, seats > 1 and created_height ≤ height − T (nothing when height < T), in ascending id. For each: share = floor(max(0, stake_amount) × b / 10,000), back = stake − share; every seated player (in player order, the creator first) gets back in the stake asset (ZBC: a plain credit with a row event 100, app payout, transaction_id = the app id, the block's timestamp; a token: no row); the shares, seated × share, go for ZBC to the longevity pool (one row event 84 on the pool, transaction_id = the app id) and for a token to the apps pool (the longevity pool pays only ZBC); the row becomes status Cancelled (3) with last_move_height = height (new version). A failed credit or write fails the block. A JoinApp in that block or later finds the app Cancelled.

How to compute it. As stated; the close height of an app is created_height + T.

Rule activation. None.

Rejections and errors. None.

Vector. computed (TestNet, T = 161,280, b = 1,000).

  • Input: a type-1 app created at 1,000 with stake 100,000,000 ZBC and only its creator seated.
  • Expected output: at the start of block 162,280: the creator +90,000,000 (event 100, transaction_id = the app id), ZBCLONGV +10,000,000 (event 84), status Cancelled, last_move_height 162,280.
  • Input: a 4-player app with three seated players and stake 1,000,000,000. Expected: 900,000,000 back to each of the three, 300,000,000 to ZBCLONGV.
  • Invalid input: a JoinApp for the first app judged for block 162,280 → "JoinApp: nobody started the app in 161280 blocks; it closes itself at height 162280".

Test cases · §3a

3 cases · 2 valid · 1 invalid

A 2-player app with only its creator closes at 162,28016-3a-closevalid

Loading the test widget…

A 4-player app with three players closes16-3a-close-threevalid

Loading the test widget…

A join judged for block 162,28016-3a-late-joininvalid

Loading the test widget…

Defects to match. None known.

4. AppMove (26)

Purpose. A move by the player on the clock, or a paid keep-alive.

Inputs. Body: app_id (8, i64 LE) ‖ mlen (u16 LE) ‖ move[mlen] (§7); bytes beyond ignored.

Output and effect. Unknown app → block invalid; status ≠ Active, channel 1, or turn outside the seated range → paid no-op. Keep-alive (mlen 0): the sender must be on the clock (else a paid no-op); the fee; deadline_height = height + 240, last_move_height = height; new version. A move: the sender not on the clock → a free no-op (no fee). For a dice game (types 32, 33, 34, 35; rule apps_seed_after_bet) the move is not applied here: the fee is charged and the move is stored on the row as pending_move = [tx id 8 LE][move bytes] (one at a time; a second move while one waits is a paid no-op), and the next block's resolver (§6) applies it with that block's seed, keyed by the move's tx id, so the including blocksmith never saw the roll. For any other game: moveRand = R(block seed, app_id, tx.id) (§6); the engine (§7) judges the move; illegal → a free no-op; the fee; state_blob = the new state, last_move_height = height; outcome 1 → the winner (the engine's player, else the mover) is paid (§1 win), status Finished; outcome 2 → the draw refund, Finished; else turn = the engine's next player and deadline_height = height + 240. Then 04 §5.

How to compute it. Admission: "AppMove body too short", "AppMove: unknown app", "… app not active", "… not your turn", "AppMove: a move is already waiting for the next block's dice" (a dice game with a pending_move), "… illegal move for the current board (square occupied or out of range)" (the engine with moveRand 0, non-channel apps only). Execution (block invalid): "Invalid AppMove body", "Unknown app", "Fee cannot be negative".

Rule activation. apps_seed_after_bet, apps_seed_prefix (height 0).

Rejections and errors. As listed.

Vector. computed: the moves of §7's vector, each as an AppMove body app_id (8 LE) ‖ 0100 ‖ cell; e.g. tic-tac-toe app id 1 (0100000000000000), cell 4 → body 0100000000000000 0100 04.

  • Input: that move by the player on the clock. Expected: the fee; state_blob cell 4 = the mover's mark; turn = the other player; deadline_height = height + 240.
  • Invalid input: the same move by the other player → refused at admission "AppMove: not your turn"; mined, a free no-op. Cell 9 (… 0100 09) → "AppMove: illegal move for the current board (square occupied or out of range)". Body of 9 bytes → "AppMove body too short".

Test cases · §4

4 cases · 1 valid · 3 invalid

Player 0 takes the centre16-4-movevalid

Loading the test widget…

The same move by the other player16-4-not-your-turninvalid

Loading the test widget…

Cell 9 is off the board16-4-cell-9invalid

Loading the test widget…

A 9-byte AppMove body16-4-shortinvalid

Loading the test widget…

Defects to match. (1) An out-of-turn or illegal move that reaches a block pays nothing and writes rows 22 / 47 (04 §5 step 3); a stale-status move pays its fee. (2) Admission judges dice moves with a zero die, execution with the block's: legality never depends on the die.

5. ResignApp (27) and ClaimAppTimeout (28)

Purpose. Ending an app by forfeit.

Inputs. Body: app_id (8, i64 LE).

Output and effect. Both: unknown app → block invalid; status ≠ Active or channel 1 → paid no-op. Resign: the sender not seated → block invalid ("Not a player in this app"); the fee; the split (§1) among every player but the sender's; Finished. Timeout: height ≤ deadline_height → paid no-op; the sender not seated, or on the clock → paid no-op; the fee; the split among every player but the one on the clock; Finished. Then 04 §5.

How to compute it. Admission: "ResignApp body too short", "ResignApp: unknown app", "… app not active", "… not a player in this app"; "ClaimAppTimeout body too short", "ClaimAppTimeout: unknown app", "… app not active", "… per-move deadline not yet passed" (judged at the next height), "… only a waiting player can claim a timeout". Execution (block invalid): "Invalid ResignApp body" / "Invalid ClaimAppTimeout body", "Unknown app", "Not a player in this app", "Fee cannot be negative".

Rule activation. None.

Rejections and errors. As listed.

Vector. computed.

  • Input: ResignApp (type 27) by player 0 of an Active 2-player ZBC app of pot 200,000,000, body = LE64(id).
  • Expected output: the fee; the other player +198,000,000 (event 100), the pool +2,000,000 (event 67), winner_address = that player, status Finished.
  • Invalid input: ClaimAppTimeout at a height ≤ deadline_height → "ClaimAppTimeout: per-move deadline not yet passed" (admission); mined, a paid no-op. ResignApp by an account not seated → "ResignApp: not a player in this app"; mined, the block is invalid ("Not a player in this app").

Test cases · §5

3 cases · 1 valid · 2 invalid

Player 0 resigns a 2-player app of pot 2 ZBC16-5-resignvalid

Loading the test widget…

A timeout claimed at the deadline16-5-early-timeoutinvalid

Loading the test widget…

An account that is not a player resigns16-5-stranger-resignsinvalid

Loading the test widget…

Defects to match. A timeout may be claimed at deadline_height + 1 even if the on-clock player's move is in the same block after the claim; the move is then a paid no-op.

6. Solo apps: the draw, the payout tables and the resolver

Purpose. How a bet against the pool is decided.

Inputs. The bet's params, stake_amount, the seed of the block at resolve_height.

Output and effect. The random number R(seed, app id, x) = the unsigned 64-bit little-endian value of the first 8 bytes of SHA3-256("zbc-apps" (8 ASCII bytes, no terminator) ‖ the block seed (all its bytes, as the block carries it, 05) ‖ LE64(app id) ‖ LE64(x)); x = 0 for a game-level draw, the move's transaction id for a move's dice (rule apps_seed_prefix).

At the start of every block (22), the resolver takes every Active app with 0 < resolve_height ≤ height and every app with a pending_move, in ascending id:

  • a pending dice move (rule apps_seed_after_bet, §4): the move is applied now with moveRand = R(this block's seed, app id, the stored tx id), the roll the including blocksmith never saw; pending_move is cleared; an illegal move (the board moved meanwhile) is dropped and the player stays on the clock;
  • a pending opening turn (a multiplayer app with resolve_height ≤ height, §3): turn = R(seed, id, 0) mod seats, resolve_height = 0;
  • a solo bet whose resolving block's blocksmith is the bettor (rule apps_seed_after_bet: the blocksmith's registered owner account is byte-equal to the bet's player): skipped this block, resolved by a later block another account's node produces;
  • the draw of a solo bet: r = R(seed, app id, 0).

N = params[base] when present (1 when absent or 0, capped at 100), per = floor(stake / N) (stake itself with N 1 when that is 0); play 0 uses r, play s > 0 uses the s-th output of splitmix64 seeded with r (state += 0x9E3779B97F4A7C15; z = state; z = (z ⊕ z≫30) × 0xBF58476D1CE4E5B9; z = (z ⊕ z≫27) × 0x94D049BB133111EB; output z ⊕ z≫31; all mod 2⁶⁴); the payout is the sum over the plays of:

Type params Play with random rr Payout on a win
16 dice [dtype, dtotal, N?] d1 = rr mod 6 + 1, d2 = floor(rr/6) mod 6 + 1, s = d1 + d2; dtype 0 wins when s < 7, 1 when s = 7, 2 when s > 7, 3 when s = dtotal (2…12) floor(per × m / 100), m = 228 (0, 2), 570 (1), 3420 / (6 − |7 − dtotal|) (3)
17 coin-flip [choice, N?] wins when (rr mod 2) = (choice mod 2) floor(per × 198 / 100)
18 roulette [type, value, N?] roll = rr mod 37; type 0: roll = value (0…36); type 1: value 0 = red, 1 = black; red = {1,3,5,7,9,12,14,16,18,19,21,23,25,27,30,32,34,36}, black = the rest except 0 per × 36 (type 0), per × 2 (type 1)
19 slots [N?] a = rr mod 8, b = floor(rr/8) mod 8, c = floor(rr/64) mod 8 a = b = c: per × 50 when a = 7 else per × 15; any two equal: floor(per × 18 / 10)
20 lottery [pick, N?] wins when rr mod 100 = pick per × 90
21 crash [T lo, T hi, N?] (T = 101…1000) u = rr mod 1,000,000; C = floor(99,000,000 / (1,000,000 − u)) clamped to 100…1000; wins when C ≥ T floor(per × T / 100)

A total > 0 is a win. The per-block cap (rules apps_payout_cap, apps_payout_cap_net): a block pays solo wins in a stake token only up to cap, read once per token before the block's first payment in that token: with since = height − APPS_PAYOUT_INFLOW_WINDOW_BLOCKS (4 × 60 × 24 = 5,760; 0 when height ≤ 5,760), cap = max(0, Σ stake_amount of the solo rows (types 16–31) of that token with created_height in (since, height] − Σ paid_payout of the solo rows of that token with block_height in (since, height]) (a bet counts its whole paid_payout while the block of its last payment is inside the window). Every payment lowers the cap left for the rest of the block.

  1. Owed wins first, the rows with owed_payout > 0 in ascending id: when the token's cap left is ≤ 0, skip to the next row (the other tokens' owed wins still pay); else pay = min(owed_payout, cap left, the pool's balance of the token); when pay > 0 the pool pays it, owed_payout −pay, paid_payout +pay, the row's version at this height.
  2. Then each fresh win: pay = min(total, the pool's balance of the asset); when pay exceeds the cap left, owed_payout = total − max(cap left, 0) and pay = max(cap left, 0); the cap left −pay; when pay > 0 the pool pays it and paid_payout +pay; winner_address = the player. Nothing is re-drawn and nothing is forfeited to the cap.

A payment: the pool −pay, then the player +pay (ZBC: rows event 100 on both, transaction_id = the app id, the block's timestamp; a token: no rows); a pool debit that fails pays nobody. A loss moves nothing (the stake is already the pool's). The bet's row becomes Finished with last_move_height = height (a new version). The largest payout used by the cap of §2 is: dice floor(stake × m / 100) for the bet's own m, coin-flip floor(stake × 198 / 100), roulette stake × 36, slots stake × 50, lottery stake × 90, crash floor(stake × T / 100); all saturating.

How to compute it. As stated; every product in 128-bit, every division floors.

Rule activation. apps_seed_prefix, apps_seed_after_bet, apps_turn_plus_two, apps_payout_cap, apps_payout_cap_net (height 0).

Rejections and errors. None.

Vector. computed (the seeds below are inputs: 64-byte block seeds as a block carries them).

  • Input: a roulette bet, app 5,578,600,537,796,526,643 (type 18, params 010001: colour red, one play, stake 1,000,000,000 ZBC), created at 11,871 (the first solo bet of the chain), resolved at 11,873, whose block seed is 5d12257f7b18f8159573c73dc4c0eb3a40c6f805cd8900833d2faf3c3dc5387c842ce45d30128ac7dba7b357636963c28f165cb8ca3fbf1c6e31327fa75cbffc.
  • Expected output: r = R(seed, 5578600537796526643, 0) = 0x3DA4D35B441EB593; roll = r mod 37 = 3 (red) → a win of 1,000,000,000 × 2 = 2,000,000,000. The cap at 11,873: inflow (5,873, 11,873] = 1,000,000,000 (this bet), payouts 0 → cap 1,000,000,000; so the pool pays 1,000,000,000 (event 100, −1,000,000,000 on ZBCAPPS at 11,873), owed_payout 1,000,000,000, paid_payout 1,000,000,000. When at 11,877 a second bet of 1,000,000,000 is staked (event 66 +1,000,000,000 on the pool), at 11,878 the owed pass reads cap = 2,000,000,000 − 1,000,000,000 = 1,000,000,000 and pays the owed 1,000,000,000 (event 100 −1,000,000,000 at 11,878, reference_id 5578600537796526643); owed 0. (The owed pass of block 11,877 runs before that block's transactions, so the new stake counts from 11,878.) GET /api/v1/accounts/000000005A42434150505300000000000000000000000000000000000000000000000000/movements then lists exactly these four rows.
  • Input: the bet G of §2's vector (the same bet, created 11,877, resolved at 11,879, seed 4bcf38e602ccbade2ff12edd238e95271baa0aaaa618db1fba321bf15aa5f1fdb82ce33481b50e8509ec5856304b1f3ea0d0cff02206446e8bb1d5d461939306). Expected: r = R(seed, 5331875765163016418, 0) = 0xF0100D1F43848946, roll 29 (black) → lost, winner empty, nothing moves.
  • computed (seed = 32 zero bytes): a coin-flip app 7,220,290,349,025,501,074 with params 0001: r = 0x52C103F98C753FAD, r mod 2 = 1 ≠ choice 0 → loses; a crash app −7,674,452,679,971,341,885, play 0: r = 0x280D97A5A37ADBBA, u = 491,834 → C = 194. The crash curve: u 0 → C 100, u 500,000 → 198, u 900,000 → 990, u 999,000 → 1000.

Test cases · §6

10 cases · 10 valid

The roulette bet resolved at 11,873: red, a win held back by the cap16-6-roulette-winvalid

Loading the test widget…

When the next bet is staked at 11,877, block 11,878 pays the owed win16-6-owed-passvalid

Loading the test widget…

The bet G resolved at 11,879: black, lost16-6-roulette-lossvalid

Loading the test widget…

A coin-flip on heads with a zero seed loses16-6-coin-flipvalid

Loading the test widget…

A crash app's first play with a zero seed16-6-crashvalid

Loading the test widget…

The crash multiplier at u = 016-6-crash-0valid

Loading the test widget…

The crash multiplier at u = 50000016-6-crash-500000valid

Loading the test widget…

The crash multiplier at u = 90000016-6-crash-900000valid

Loading the test widget…

The crash multiplier at u = 99900016-6-crash-999000valid

Loading the test widget…

The crash multiplier at u = 49183416-6-crash-491834valid

Loading the test widget…

Defects to match. (1) The N-way split loses the remainder stake − N × per to the pool. (2) A payout above the pool's balance is cut to the balance and the rest forfeited when the cut payment fits the cap left; when it does not, owed_payout is total − cap left, the pool-cut part included. (3) A bet placed when the pool holds exactly the 5 %-of-pool cap of §2 can still be cut at resolution if other bets drained the pool between. (4) A bet's whole paid_payout counts in the window while its last payment's block is inside it, so the cap errs toward holding a win back.

7. The rules engine

Purpose. For each multiplayer type: the initial state, the move bytes, legality, the state after the move, the outcome (0 ongoing, 1 win, 2 draw) and the next player. Marks are m = turn + 1 unless stated. S = seats. "Next" = (turn + 1) mod S.

Inputs. state_blob, turn, seats, the move bytes, moveRand (§4).

Output and effect.

  • 1 tic-tac-toe. State 9 bytes (cells 0–8, row-major, 0 empty). Move [cell], cell ≤ 8 and empty. Win: three m in a row (rows, columns, diagonals) → 1 (mover); board full → 2; else next.
  • 3 connect-4. State 42 bytes (7 × 6, index y × 7 + x). Move [column] ≤ 6; the piece lands at the highest y (5 → 0) with an empty cell; full column illegal. Win: 4 in a line through the cell (horizontal, vertical, both diagonals) → 1; full → 2; else next.
  • 6 gomoku. State 225 bytes (15 × 15, index y × 15 + x). Move [x, y], both ≤ 14, cell empty. Win: 5 in a line → 1; full → 2; else next.
  • 5 reversi. State 64 bytes; initial cells 27 = 2, 28 = 1, 35 = 1, 36 = 2. Move [cell], empty, and it must sandwich ≥ 1 opponent line in some of the 8 directions; those lines flip. Then: if the other mark has a legal move → next; else if m has one → the same player again (the opponent passes); else the end: more pieces wins (winner = player 0 for mark 1, player 1 for mark 2) → 1, equal → 2.
  • 8 dots-and-boxes 3 × 3. State 33 bytes: edges 0–23 (horizontal edge of box row br, column bc: top = 3br + bc, bottom = 3(br + 1) + bc; vertical: left = 12 + 4br + bc, right = 12 + 4br + bc + 1), boxes 24–32 (index 24 + 3br + bc). Move [edge] ≤ 23 and unset; the edge is set to 1; every box whose four edges are now set and which is unowned is marked m. All 24 edges set → the end: more boxes → 1 with winner = that player (0 for mark 1), equal → 2. Else: a box was completed → the same player moves again, otherwise next.
  • 2 chess. State 64 bytes, index row × 8 + col; white (player 0) 1 P 2 N 3 B 4 R 5 Q 6 K, black 7–12; initial row 0 = 4 2 3 5 6 3 2 4, row 1 pawns 1, row 6 pawns 7, row 7 = the same back rank + 6. Move [from, to], both ≤ 63, different; the piece at from must be the mover's and to not the mover's; pseudo-legal: pawn one step forward (white +1 row, black −1) to an empty cell, two from its start row (1 / 6) over an empty cell, or one diagonal onto an enemy; knight (1, 2); bishop clear diagonal; rook clear line; queen either; king one step; no castling, no en passant; then the mover's king must not be attacked after the move. A pawn reaching row 7 / 0 becomes a queen (5 / 11). After the move: if the opponent has no legal move → 1 when its king is attacked (checkmate, mover wins) else 2 (stalemate); else next.
  • 4 checkers. State 65 bytes: cells 0–63 (0 empty, 1/3 player-0 man/king, 2/4 player-1 man/king; initial men on dark cells (row + col odd), rows 0–2 player 0, rows 5–7 player 1) and byte 64 = the multi-jump lock (0xFF none). Move [from, to]: the piece must be the mover's; with a lock set, from must equal it; to empty; a diagonal step of 1 is legal only when the mover has no capture anywhere and (for a man) it goes forward (player 0 +row, player 1 −row); a diagonal jump of 2 must cross an enemy piece (removed) and (for a man) go forward; anything else illegal. A man reaching row 7 / 0 becomes a king (3 / 4). After a jump, if the moved piece can capture again, the lock is set to to and the same player continues; else the lock is cleared and the opponent with no pieces left loses (→ 1), else next.
  • 7 battleship. State 6,606 bytes: commitments of player 0 and player 1 (3,200 each: 100 cells × SHA3-256(is_ship(1) ‖ salt(32))), reveal boards of player 0 and 1 (100 each: 0 unknown, 1 miss, 2 hit), phase (6600), pending cell (6601), hits suffered by player 0 / 1 (6602 / 6603), shots fired by player 0 / 1 (6604 / 6605). The creator's 3,200-byte params fill its commitment; on join turn = 1. Phase 0 SETUP: player 1 moves [2 ‖ 3,200 bytes] → its commitment, phase 1, player 0 on the clock. Phase 1 FIRE: [0, cell], cell ≤ 99, the opponent's reveal cell still 0 → pending = cell, the mover's shots + 1, phase 2, opponent on the clock. Phase 2 REVEAL: [1, is_ship, salt(32)] (34 bytes): SHA3-256(is_ship ‖ salt) must equal the revealer's commitment for the pending cell → the revealer's board cell = 2 when is_ship else 1; a ship → its hits + 1, and 17 hits → 1 with winner = the firer; then, if the firer has fired 100 shots and the revealer's revealed ships are fewer than 17 → 1 with winner = the firer; else phase 1 with the revealer on the clock (it fires next).
  • 33 pig. State S + 1 bytes: a score per player, then the turn total. [0] roll: die = moveRand mod 6 + 1; 1 → turn total 0, next; else turn total + die (capped at 250), same player. [1] hold: score + turn total (capped at 250), turn total 0; score ≥ 100 → 1; else next.
  • 34 race. State S bytes (positions). [0]: die as above; p = position + die; ladders 3 → 22, 8 → 26, 20 → 38, 28 → 44; snakes 17 → 4, 31 → 14, 40 → 19, 47 → 26; p capped at 49; every other player standing on p (p > 0) goes back to 0; p ≥ 49 → 1; a 6 → the same player, else next.
  • 32 ludo. State 4S + 1 bytes: 4 token progresses per player (0 yard, 1–51 track, 52–57 home stretch, 57 home) and the pending die. Pending 0: [0] → die; a token can move when (progress 0 and die 6) or (progress < 57 and progress + die ≤ 57); none → next (pass); else pending = die, same player. Pending set: [1, k], k ≤ 3 and movable: progress 0 → 1, else + die; on the track (1…51) with absolute cell a = (13 × turn + progress − 1) mod 52 not a multiple of 13, every other player's token q on the track with (13 × that player's index + q − 1) mod 52 = a goes to the yard; pending 0; all four at 57 → 1; die 6 → the same player, else next.
  • 35 monopoly-lite. State 4S + 42 bytes: money u16 LE per player (start 1,500), position per player, owner of cells 0–39 (0 none, else the owner's player index + 1), bankrupt flag per player, phase, pending buy (0xFF none). Prices: 0 60 0 60 0 200 100 0 100 120 0 140 150 140 160 200 180 0 180 200 0 220 0 220 240 200 260 260 150 280 0 300 300 0 320 200 0 350 0 400. Phase 0: [0]: d1 = moveRand mod 6 + 1, d2 = floor(moveRand/6) mod 6 + 1; p = position + d1 + d2; p ≥ 40 → money + 200 and p mod 40; p = 30 → 10; cell 4 → pay 200, cell 38 → pay 100 (to nobody); a priced cell unowned → phase 1 with the pending buy, same player; owned by another → rent floor(price / 6) to the owner. Paying more than one holds sets money 0 and the bankrupt flag (the owner receives what was paid). Then: one or no player left solvent → 1 with winner = the last solvent player (none left → the mover, by the −1 rule of §4); else the next solvent player. Phase 1: [1] buys when money ≥ price (money −price, owner = the mover's player index + 1), [2] passes; phase 0; then as above. Money is clamped to 0…65,535.

Any other type, state size, move size or value is illegal.

How to compute it. As stated.

Rule activation. None.

Rejections and errors. An illegal move is the free no-op of §4 (refused at admission).

Vector. computed (tic-tac-toe, seats 2, initial state 000000000000000000).

  • Input: [4] by player 0, [0] by player 1, [2] by player 0, [8] by player 1, [6] by player 0.
  • Expected output: after the fourth move the state is 020001000100000002 (cells 0…8 = 2, 0, 1, 0, 1, 0, 0, 0, 2); the fifth completes the diagonal 2-4-6: state 020001000100010002, outcome 1, winner the mover (player 0), status Finished, the win of §1 paid.
  • Invalid input: [4] by player 1 after the first move → illegal (cell taken): refused at admission, a free no-op if mined.
  • Connect-4: column 3 four times by player 0 with player 1 playing column 0 in between → outcome 1 at player 0's fourth piece (cells 38, 31, 24, 17 = y 5, 4, 3, 2 of x 3).

Test cases · §7

7 cases · 6 valid · 1 invalid

Tic-tac-toe move 1: player 0 takes cell 416-7-ttt-1valid

Loading the test widget…

Tic-tac-toe move 2: player 1 takes cell 016-7-ttt-2valid

Loading the test widget…

Tic-tac-toe move 3: player 0 takes cell 216-7-ttt-3valid

Loading the test widget…

Tic-tac-toe move 4: player 1 takes cell 816-7-ttt-4valid

Loading the test widget…

Move 5: player 0 takes cell 6 and completes the diagonal16-7-ttt-5valid

Loading the test widget…

Player 1 plays the centre after player 0 took it16-7-takeninvalid

Loading the test widget…

Connect-4: player 0's fourth piece in column 3 wins16-7-connect4valid

Loading the test widget…

Defects to match. (1) Reversi and dots-and-boxes can end with the non-mover winning. (2) Checkers has no loss by immobility. (3) Battleship never verifies 17 ships unless all 100 shots are fired. (4) Monopoly tax money vanishes; GO pays only on passing by roll.

8. SettleApp (39) and the channel settlement

Purpose. A 2-player channel app is played off-chain; a replayed voucher chain settles it.

Inputs. Body: app_id (8, i64 LE) ‖ final_seq (u32 LE) ‖ count (u32 LE) ‖ count × (seat (1) ‖ mlen (u16 LE) ‖ move[mlen] ‖ signature (64)); final_seq = count; count ≤ 1,024 and ≤ floor(remaining bytes / 67).

Output and effect. Every failure below is a free no-op (nothing charged, rows 22 / 47): unparseable; unknown app; channel ≠ 1; seats ≠ 2; status ≠ Active; the sender not seated. Replay from the row's state_blob and turn: for voucher i (seq i, from 1), seat must equal the current turn; digest = SHA3-256(app id LE8 ‖ seq LE4 ‖ SHA3-256(state before the move) ‖ move); the signature (always 64 bytes) must verify for the player's typed account by that account type's scheme (02) with the 32 digest bytes as the signed message (for a type-0 player: Ed25519 over the 32 bytes; Taproot: BIP-340; Solana: Ed25519; Polkadot: sr25519; no other kind can play a channel app, §2, §3); the move must be legal by §7 with moveRand 0; the state, outcome, winning player and turn advance; a terminal outcome stops the replay. With an existing settlement: resolved → no-op; final_seq ≤ its final_seq → no-op. The fee; the settlement row (new version): claimant = the sender as given, final_seq, outcome, winner player (−1 unless outcome 1), the turn after the last voucher, the replayed state, challenge_deadline_height = height + 240, resolved 0. At the start of every block (after the solo resolver): each unresolved settlement with challenge_deadline_height < height, by app id: when the app is still Active with channel 1, its state_blob = the claim's; outcome 1 → the win of §1 to the winning player (player 0 when −1); 2 → the draw refund; 0 → the split to every player but the claim's turn; Finished; the settlement marked resolved whatever the app's state.

How to compute it. Stateless: "SettleApp body malformed", "SettleApp: seat out of range (2-player only)" (seat > 1). No admission state check. Node-local: the settlement's ledger rows carry the executor's current block timestamp, which at that point in the block is still the previous block's.

Rule activation. None.

Rejections and errors. As listed.

Vector. computed.

  • Input: a tic-tac-toe channel app (seats 2, channel 1, Active, turn 0), SettleApp (type 39) body = LE64(id) ‖ 03000000 ‖ 03000000 ‖ three vouchers (seat ‖ 0100 ‖ cell ‖ 64-byte signature): player 0 cell 4, player 1 cell 0, player 0 cell 2, each signed over SHA3-256(LE64(id) ‖ LE32(seq) ‖ SHA3-256(state before) ‖ move) by that player's key.
  • Expected output: the fee; app_settlement row: final_seq 3, outcome 0, winner_seat −1, turn 1, the replayed state, challenge_deadline_height = height + 240, resolved 0. At the first block above the deadline with no longer chain filed: the app's state = the claim's; outcome 0 → the split to every player but player 1: player 0 +(pot − rake); status Finished; the settlement resolved.
  • Invalid input: a voucher with seat 2 → "SettleApp: seat out of range (2-player only)" (stateless); a voucher signed by the wrong key → a free no-op.

Test cases · §8

3 cases · 2 valid · 1 invalid

Three vouchers settle an unfinished tic-tac-toe channel app16-8-settlevalid

Loading the test widget…

A voucher whose seat field is 216-8-seat-2invalid

Loading the test widget…

A voucher signed by the other player's key settles nothing16-8-wrong-keyvalid

Loading the test widget…

Defects to match. (1) A claim with outcome 1 and winner_seat −1 pays player 0.

9. Views, ledger rows and the consensus/local split

Event Row (ZBC stakes only) Written by
66 player −stake; pool +stake (solo) CreateApp, JoinApp
100 winner / player +payout; pool −payout (solo) the settlements of §1, the resolver of §6 and its owed payments, an unstarted app's refund (§3a)
84 longevity pool +shares an unstarted app closing itself (§3a)
67 pool +rake win, split
1, 22, 47 per 04 §5 every type here (SettleApp and the free no-ops of §4 collect nothing)

Views (local): /apps?category=&limit= (apps[]: id (string), app_type, status, seats, creator, players[] (each player's typed account as stored, lower-case hex, variable length), opponent (the stored bytes in hex, "" when none), stake_token_id, stake_amount, pot, state (hex), turn, created_height, last_move_height, deadline_height, resolve_height, winner ("" when none), channel, owed_payout; paid_payout is not shown), /apps/open (Open 2-player apps: id, app_type, maker, seats, stake_token, stake_amount), /apps/pool (zbc, tokens[] {token_id, balance, decimals, symbol}, channels), /apps/stats (apps_total, apps_open, apps_active, apps_finished, players_active, pot_at_stake), /accounts/<a>/apps (the apps one of whose seats is byte-equal to the account); the per-block /blocks/height/<h>/touched-accounts view gives each app transaction an app_id and lists the app's creator, every player and the invited opponent (31).

Consensus: both tables, the player rules, the close of an unstarted app, every draw, table and engine above, the pool's balances, the cap, the windows and the accept/no-op/invalid outcome of each type. Local: the ledger rows except event 22 (04), the views.

A question about this chapter, or a statement that does not match the network? Discuss on zoobc.pro.