On this page
- §0 The area in one paragraph
- 1. The app row, seats, the pool and the shared settlement
- 2. CreateApp (24)
- 3. JoinApp (25)
- 3a. An unstarted multiplayer app closes itself
- 4. AppMove (26)
- 5. ResignApp (27) and ClaimAppTimeout (28)
- 6. Solo apps: the draw, the payout tables and the resolver
- 7. The rules engine
- 8. SettleApp (39) and the channel settlement
- 9. Views, ledger rows and the consensus/local split
16 — On-chain apps: CreateApp, JoinApp, AppMove, ResignApp, ClaimAppTimeout, SettleApp
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).playersis 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. Readingplayers: 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;turnindexes 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_BPS100; move windowAPP_MOVE_WINDOW240 blocks; settlement windowSETTLE_CHALLENGE_WINDOW240; bet capAPP_MAX_PAYOUT_FRAC_BPS500; 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_addressset 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 account04000000 ‖ 0102030405060708090A0B0C0D0E0F1011121314(24 bytes). - Expected output:
players=2400000000B6675786BEDF28B3E7DCD8BAC9BF99758B3A64604570BFFD12FD10CBF20B39EA18040000000102030405060708090A0B0C0D0E0F1011121314(62 bytes); player count 2; player 1 is the Ethereum account. Theplayersbytes24 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/poolbefore any bet answers"zbc":1000000000000000(theapps_treasuryof 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 field
Loading the test widget…
A length of 36 with two bytes after it reads as no player at all
Loading the test widget…
The apps pool before any bet: the apps treasury of both genesis files
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 share
Loading the test widget…
Player 0 resigns a 3-player app of pot 3 ZBC
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
00000000B6675786BEDF28B3E7DCD8BAC9BF99758B3A64604570BFFD12FD10CBF20B39EAat 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, params010001(colour, red, one play),rem1: 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 beginningE2400E49C2A0FE49gives 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,state010001,resolve_height11,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. computedInput: a tic-tac-toe app (type 1) for two, stake 100,000,000 ZBC, inviting the 36-byte account00000000120EE4CA…E807: body01000000000000000000E1F505000000000200002400000000000000120EE4CA9D258D75656901EC4837373E07763369AD75ED8D63FA31C7E0B7E807(60 bytes; the same followed by01= a channel app, 61 bytes). Expected: the row Open,pot100,000,000,state_blob9 zero bytes,opponent_address= those 36 bytes.- Invalid input: the 20-byte head followed directly by the 36-byte account (56 bytes:
rem36, n reads 0) →"CreateApp body too short"(admission),"Invalid CreateApp body"(block invalid). Params0300for 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 opponent0A000000‖ 32 bytes (aZBS_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 account00000000B6675786…39EA, inviting the ZooBC account00000000120EE4CA…E807. Expected: accepted; the row Open withchannel1. - 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 account04000000 ‖ 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 (body01 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 final01(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 is04000000 ‖ 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 E2400E49C2A0FE49
Loading the test widget…
A tic-tac-toe app for two at 1 ZBC, inviting one account
Loading the test widget…
The same as a channel app, between two ZooBC accounts
Loading the test widget…
Inviting a ZBS_ address: nobody could join
Loading the test widget…
A channel app created by an Ethereum account
Loading the test widget…
A channel app inviting an Ethereum account (49-byte body)
Loading the test widget…
The same invitation as an on-chain app (48 bytes) is accepted
Loading the test widget…
An invited opponent in its full-key form (92-byte body)
Loading the test widget…
The opponent appended without its length
Loading the test widget…
A dice bet on an exact total of 0
Loading the test widget…
A ZBS_ account cannot create an app
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;pot200,000,000; status Active,deadline_heighth + 240,turn−1,resolve_heighth + 2; at h + 2 the resolver setsturn=R(seed of h + 2, G, 0) mod 2andresolve_height0. - 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 body01 0000000000000000 00E1F50500000000 02 0000 01(tic-tac-toe, stake 100,000,000 ZBC, two players, no invited opponent,channel1) by the Ethereum account04000000 ‖ 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 starts
Loading the test widget…
Another account cannot join in the invited opponent's place
Loading the test widget…
Mined, that join makes the block invalid
Loading the test widget…
A join after the app is full
Loading the test widget…
An Ethereum account joins a channel app
Loading the test widget…
Mined, that join makes the block invalid
Loading the test widget…
The same join of an on-chain app is accepted
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_height162,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,280
Loading the test widget…
A 4-player app with three players closes
Loading the test widget…
A join judged for block 162,280
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_blobcell 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 centre
Loading the test widget…
The same move by the other player
Loading the test widget…
Cell 9 is off the board
Loading the test widget…
A 9-byte AppMove body
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 ZBC
Loading the test widget…
A timeout claimed at the deadline
Loading the test widget…
An account that is not a player resigns
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 withmoveRand=R(this block's seed, app id, the stored tx id), the roll the including blocksmith never saw;pending_moveis 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.
- 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); elsepay= min(owed_payout, cap left, the pool's balance of the token); whenpay> 0 the pool pays it,owed_payout−pay,paid_payout+pay, the row's version at this height. - Then each fresh win:
pay= min(total, the pool's balance of the asset); whenpayexceeds the cap left,owed_payout= total − max(cap left, 0) andpay= max(cap left, 0); the cap left −pay; whenpay> 0 the pool pays it andpaid_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 is5d12257f7b18f8159573c73dc4c0eb3a40c6f805cd8900833d2faf3c3dc5387c842ce45d30128ac7dba7b357636963c28f165cb8ca3fbf1c6e31327fa75cbffc. - 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 onZBCAPPSat 11,873),owed_payout1,000,000,000,paid_payout1,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_id5578600537796526643); 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/movementsthen 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,winnerempty, nothing moves. computed(seed = 32 zero bytes): a coin-flip app 7,220,290,349,025,501,074 with params0001: 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 cap
Loading the test widget…
When the next bet is staked at 11,877, block 11,878 pays the owed win
Loading the test widget…
The bet G resolved at 11,879: black, lost
Loading the test widget…
A coin-flip on heads with a zero seed loses
Loading the test widget…
A crash app's first play with a zero seed
Loading the test widget…
The crash multiplier at u = 0
Loading the test widget…
The crash multiplier at u = 500000
Loading the test widget…
The crash multiplier at u = 900000
Loading the test widget…
The crash multiplier at u = 999000
Loading the test widget…
The crash multiplier at u = 491834
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: threemin 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 ifmhas 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 markedm. All 24 edges set → the end: more boxes → 1 withwinner= 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 atfrommust be the mover's andtonot 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,frommust equal it;toempty; 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 totoand 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
paramsfill its commitment; on jointurn= 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 withwinner= the firer; then, if the firer has fired 100 shots and the revealer's revealed ships are fewer than 17 → 1 withwinner= 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 withwinner= 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: state020001000100010002, 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 4
Loading the test widget…
Tic-tac-toe move 2: player 1 takes cell 0
Loading the test widget…
Tic-tac-toe move 3: player 0 takes cell 2
Loading the test widget…
Tic-tac-toe move 4: player 1 takes cell 8
Loading the test widget…
Move 5: player 0 takes cell 6 and completes the diagonal
Loading the test widget…
Player 1 plays the centre after player 0 took it
Loading the test widget…
Connect-4: player 0's fourth piece in column 3 wins
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,
channel1, Active,turn0), 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_settlementrow:final_seq3, outcome 0,winner_seat−1,turn1, 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
seat2 →"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 app
Loading the test widget…
A voucher whose seat field is 2
Loading the test widget…
A voucher signed by the other player's key settles nothing
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.