On this page
  1. §0 The area in one paragraph
  2. 1. The four ways in and the pre-checks
  3. 2. The validator's ordered checks
  4. 3. The timestamp window and the blocksmith's right
  5. 4. Application: what can still refuse a valid block
  6. 5. The candidate pool
  7. 6. Fork resolution
  8. 7. Outcomes and the consensus/local split
  9. 8. The serialized block size
  10. 9. A receipt counts in one block
  11. 10. Survival mode

19 — Block validation: what a node does with a block it receives

Edition 0.6.1 · verified against the reference implementation, version 0.6.1

Out of scope the header bytes, the hash, the signature preimage, the payload hash, the Merkle root and the difficulty arithmetic (05); the selection generator, the priority order and the selectable set (20); the end-of-block steps a valid block triggers (22); receipts and their own validity (23); the transaction envelope, the admission checks a block's transactions pass and the foreign carrier's own form (03, 04); the fork procedure in full (24); snapshots (26); the P2P messages, the signed-call envelope and peer charging (27, 28); the readiness gate (29); the full schema of every table (07)

§0 The area in one paragraph

A block reaches a node by gossip, by sync from a peer, through the candidate pool of the slot it is competing in, or as part of a fork. Whatever the path, an implementation runs the same ordered checks against the block's previous block: the transaction ceiling, the payload length and the block's serialized size, the payload hash, the header's link, timestamp window and version, the blocksmith's right to produce at that timestamp, the block id, the signature, the seed, that no foreign carrier's native transaction id was used before or appears twice, that no two transactions come from one account, every transaction's validity at the block's height (a governance or bridge transaction in a block judged in survival mode is invalid there), the Merkle root, the fee total, the receipts (each counted in one block only, each referring to a held block of the last 720), and the cumulative difficulty string. Only then is the block applied: its transactions are normalised and executed in order, and an execution error, a duplicate, a receipt that fails re-validation, a block step that cannot read what it decides on, or a storage fault refuses the block as a whole. A block that cannot be linked to the tip is not an error in itself: one behind or at the tip with a different hash is a fork signal resolved by cumulative difficulty (24), one ahead is left for sync to fetch, one already held is a duplicate. Every check that decides validity is deterministic from chain state; the few that read the wall clock are bounded so an honest node never disagrees with the chain.

1. The four ways in and the pre-checks

Purpose. An implementation must route every arriving block through the same validation and decide, before validating, whether it is a duplicate, a fork signal or a block to fetch later.

Inputs. A block object (05 §11), the local tip, the local block store, the clock, the parameter max_block_size_bytes.

Output and effect.

  • Gossip (P2P SendBlock, a call signed by the caller's node key, 27): first the transport caps (27 §2: more transactions or transaction ids than max(500, max_transactions_per_block), or a payload_length above max_block_size_bytes, are refused INVALID_ARGUMENT), then the invalid-block throttle of an unbound sender (28). A full copy (one carrying its transactions) whose serialized size (§8) exceeds max_block_size_bytes, or whose size cannot be computed, is refused before anything else (gRPC status INVALID_ARGUMENT, message "relay: block over the serialized limit") and the sender is charged an invalid block (28); an ids-only copy is sized by §2 once its transactions are fetched. A copy of a block already applied (by its signed hash), or a copy identical to one already received (by the hash of its wire bytes), is dropped; one copy of a block is processed at a time (a second copy from an unbound sender is dropped, a bound sender's waits at most 10 s for the verdict). An ids-only copy whose parent is held must pass the header checks of §2 step 5, the signature check and the difficulty recomputation before it takes a slot in the incomplete-block queue (24 §9), else it is dropped (an unbound sender charged); one whose parent is not held is dropped unless the sender is bound to a registered key and the queue has room. Then, in order: a block already stored at that height with the same hash → duplicate, answered with a receipt (23) when the sender is a registered node, nothing else; a different hash at a stored height → fork signal, ignored (the sync loop resolves, 24); height > tip + 1 → ignored (sync fetches); height = tip + 1 with a previous hash ≠ the tip's → fork signal, ignored; previous block not held → ignored. A block whose round (§3) opens later than the local clock is held only when its blocksmith is a registered node, it passes the full §2 now, and its round opens within 900 s (at most 64 held blocks); otherwise it is dropped; one whose acceptance window closed is dropped (28). Otherwise §2, then §4. A failed §2 charges the sending peer (28).
  • Sync: blocks fetched from the sync source after the common block are validated (§2) and applied (§4) one by one; a source that does not recognise our tip's id, or whose block at our height has another hash, triggers §6.
  • Candidate pool (own production and received candidates): a candidate is admitted only if §5 passes; at selection time the best candidate must pass the full §2 against the tip; one that fails is dropped and the next best is tried; then §4.
  • Fork: §6 validates and applies each block of the other branch.

How to compute it. As stated, in that order.

Rule activation. The relay's size refusal belongs to rule block_size_serialized (§8), active from height 0 on every chain.

Rejections and errors. "relay: block over the serialized limit" (gRPC INVALID_ARGUMENT). None of the other outcomes is an error a peer sees; the duplicate is idempotent and the link mismatches are the same for every node.

Vector. computed. INPUT: tip = block 9 (hash 1446492f4cf3718857d8f0e5ea60fc81f01d6f1fdda862d7a73cafcd3215aeb6); a gossiped block of height 11. EXPECTED: ignored (height > tip + 1), stored later by sync after block 10. INPUT: tip = block 10 (hash c535a2ea1d122c30feefab263bc8a144fe332caff1f82eacb20e8fc742adc7c6), the same block 10 gossiped again. EXPECTED: duplicate, nothing changes. INPUT: a full copy of a block whose serialized size is 524,289 with max_block_size_bytes 524,288. EXPECTED: refused "relay: block over the serialized limit" before any other check. INPUT: an ids-only copy of a block at tip + 1 whose carried cumulative difficulty is one more than the recomputed one. EXPECTED: dropped before it takes a queue slot; the honest copy arriving later is queued.

Test cases · §1

7 cases · 5 valid · 2 invalid · 2 reference

Tip 9, a gossiped block of height 1119-1-aheadvalid

Loading the test widget…

Tip 10, block 10 gossiped again19-1-duplicatevalid

Loading the test widget…

Tip 10, a block of height 11 whose previous hash is not the tip19-1-fork-at-tipvalid

Loading the test widget…

Tip 10, the block of height 11 linked to it19-1-nextvalid

Loading the test widget…

A full copy of 524,289 serialized bytes19-1-over-limitinvalid

Loading the test widget…

Block 11 ignored by gossip is stored later by sync after block 1019-1-later-by-syncvalidreference

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

value
stored by sync once block 10 is held
An ids-only copy at tip + 1 whose carried difficulty is one more than the recomputed one19-1-ids-only-difficultyinvalidreference

The header, signature and difficulty checks run before the incomplete-block queue; this needs the chain to run.

A stated value: there is nothing to compute. The statement is a refusal: what a compatible node does with this input.

outcome
dropped before it takes a queue slot
honest copy arriving later
queued

Defects to match. A block at height 1 arriving while our tip is also 1 with another hash is refused by the store like any tip conflict; the fork procedure uses the genesis block as the common block for it (24).

2. The validator's ordered checks

Purpose. An implementation must run these checks in this order and refuse a block with the text of the first that fails.

Inputs. The block; its previous block; the draw set and the active registry as of the previous block (20 §1); the clock. Parameters (genesis, 06): max_transactions_per_block (2,000 in both genesis files; 500 when absent), max_block_size_bytes (524,288 in both; 88,000 when absent), min_block_interval 15, blocksmith_time_gap 15, blocksmith_block_creation_time 15, blocksmith_network_tolerance 5, max_priority_blocksmiths 10, max_recovery_interval_seconds (absent in both → 3,600), cumulative_difficulty_divisor 1,000,000, is_test_chain, max_assigned_peers = P, the priority peers per node (testnet 12, devnet 8; 5 when absent; never below 2, 23 §7). Constants: TRANSACTION_EXPIRATION_OFFSET 3,600 s, TRANSACTION_FUTURE_TOLERANCE 3,600 s, TRANSACTION_EXPIRY_CAP 86,400 s, the future bound 7,200 s, the receipt lookback 40 blocks, the receipt lookback range 20 blocks, the receipt hard cap 200, the receipt expiry grace 2 blocks, the receipt reference reach 720 blocks. The active bundle id at the block's height (29). The spent set of foreign carriers (spent_foreign_message: one row per native transaction id already carried by a main-chain block, with the height of that block; the SHA3-256 of the carrier's raw message is a second key of the same row set; a pop-off deletes the rows above its target, 24 §6).

Output and effect. The first failing check names the refusal; a block that passes all is valid for application (§4). In order:

  1. Transaction ceiling. The counted actions = Σ over the transactions of: the number of payments of a SendZBCBatch or of transfers of a TransferTokenBatch (1 when its body does not parse), 1 for every other transaction (a storage-proof batch included). Counted > max_transactions_per_block → "Too many transactions in block (N > M)".
  2. Payload length. payload_length > max_block_size_bytes → "Block payload_length exceeds maximum (N > M)".
  3. Serialized size and the unhashed fields (§8, rule block_size_serialized): no size (a transaction cannot be serialized) → "BlockTooLarge: the block cannot be sized: <reason>"; size > max_block_size_bytes → "BlockTooLarge: serialized N bytes over the limit M"; a non-empty merkle_tree → "BlockTooLarge: a main block carries no merkle_tree (N bytes attached)" ("main block" = main chain block); a published receipt with intermediate_hashes longer than 1,024 bytes or rmr_linked longer than 32 bytes → "BlockTooLarge: a receipt's proof fields are over their bound (A + B bytes)" (A, B the two lengths).
  4. Payload (05 §6): recomputed length ≠ payload_length → "InvalidBlockPayload: length mismatch (calculated=X, block=Y)"; recomputed hash ≠ payload_hash → "InvalidBlockPayload: hash mismatch".
  5. Header: height ≠ previous.height + 1 → "Non-sequential block height"; previous_block_hash ≠ previous.block_hash → "Invalid previous block hash"; timestamp ≤ previous.timestamp → "Block timestamp (T) must be after previous block (P)"; timestamp > now + 7,200 → "Block timestamp too far in future"; timestamp − previous.timestamp < min_block_interval − 2 → "Block produced too fast (Gs < min 15s)" (not applied to height 1 on a chain with is_test_chain = 1); the timestamp outside the persist window of its round (§3) widened by 2 s at both ends → "Block timestamp not in valid priority window (round R)"; a gap above max_recovery_interval_seconds is accepted (rule halt_recovery_param; the smith check of step 6 decides); version 0 → "Invalid block version"; version below the newest bundle id active at this height (29 §4b; 601 on every chain, every rule being at height 0) → "Block version N is below the active bundle M (activation_readiness_gate)"; blocksmith key not 32 bytes → "Invalid blocksmith public key size".
  6. Blocksmith (§3): height 0 passes. Otherwise the draw set as of the previous block is the only set the blocksmith is checked against (rule validator_no_fallback: no other registry is consulted when that set is small or cannot be read): it cannot be read → "Cannot load the draw set at height H: <reason>" (H = the previous height); the blocksmith is not in it → "Blocksmith is not in the draw set at height H"; height 1 is judged like every other height; the blocksmith check of §3 fails → "Blocksmith not valid for block timestamp (Go-compatible validation failed)"; no round is open at the timestamp → "No active turns at block timestamp"; a blocksmith at position ≥ max_priority_blocksmiths (20 §3: the first draw naming it among the first 2n draws over the draw set of n nodes, else the hash order) whose block carries transactions → "Blocksmith at position P is beyond max_priority_blocksmiths (M) and must produce empty blocks, but block contains N transactions". (A node re-applying its own popped blocks after a failed fork skips this step and step 13, 24.)
  7. Block id (05 §4): hash shorter than 8 bytes → "InvalidID: block hash too short"; the little-endian signed 64-bit integer of hash bytes 0–7 is 0 → "InvalidID: block ID is zero"; a carried id that differs → "InvalidID: block ID mismatch".
  8. Signature: not 64 bytes → "Invalid signature size"; key not 32 bytes → "Invalid public key size"; Ed25519 verification of the signature over the unsigned header (05 §3) by the blocksmith key fails → "Invalid block signature".
  9. Hash: SHA3-256(unsigned header ‖ signature) ≠ block_hash → "Invalid block hash".
  10. Seed: height 0 passes; otherwise the 80-byte seed proof must be the blocksmith key's ECVRF proof over SHA3-256(previous seed) and the 64-byte seed its output (01 §8, 05 §5, rule seed_vrf) → else "Invalid block seed".
  11. Transactions: first the foreign carriers (rule foreign_carrier_bound): for every transaction that is a foreign carrier (04: an Ethereum-typed sender whose message parses as a signed Ethereum transaction, a Solana-typed sender whose message is a Solana transfer, a Bitcoin-typed sender whose message is a Bitcoin transaction), its carrier id = Keccak-256 of the canonical signed Ethereum transaction, the 64-byte first signature of the Solana transaction, or the Bitcoin txid; when that id, or the SHA3-256 of the raw message, is in the spent set → "ForeignCarrierReplayed"; the same id twice in the block → "ForeignCarrierReplayed". Then, for height > 0, one transaction per account: the account slot of every transaction's sender (the signing address; each member of an account group its own slot, 18) must be unique in the block, else "Block carries two transactions from one account (<hex>, transactions I and J): one transaction per account per block" (I < J the positions after sorting the (slot, position) pairs). Then every transaction's signature and stateless validity at the block's height (03, 04 §6) → the transaction's own text, or "Invalid signature at TX[i]" (the lowest failing index). This validity includes the survival refusal (§10): a transaction of the frozen set in a block whose survival flag is true → "SurvivalMode: transaction type T is not accepted while fewer than survival_min_producers distinct producers made the last 120 blocks (survival mode: governance and bridge are frozen until N produce again)" (the admission text of 04; the block is invalid). For a carrier it includes the binding checks of 04, so an unbound or expired carrier makes the block invalid: a Solana carrier's signed recent block hash must be the hash of a main-chain block at a height in [h − 720, h] ("Solana carrier recent_blockhash is not a main chain ancestor within 720 blocks"), a Bitcoin carrier must have exactly one input with a 36-byte outpoint ("Bitcoin carrier needs exactly one genesis outpoint") that spends this chain's genesis block hash at index 0xFFFFFFFF ("Bitcoin carrier input must spend the ZooBC genesis hash at index 0xFFFFFFFF"), an Ethereum carrier must be canonical, on this chain's id and pay exactly its signed gas fields; the validator's own spent-id text "Foreign carrier transaction already used" is never reached in a block (the carrier pre-check above refuses first). An Ethereum carrier's nonce is not judged here: it is judged when the block is applied (§4 step 4), where a nonce other than the sender's account nonce makes the block invalid. The same stateless validity holds two account-form rules and the bridge rule. (a) Rule canonical_account_forms: the full-key form of an Ethereum or Tron account (type 4 or 15 followed by a 64-byte key) or of a Bitcoin legacy, P2PKH or P2WPKH account (type 1, 5 or 7 followed by a 33- or 65-byte key) is no account, wherever the transaction names one: the envelope's sender, recipient or escrow approver → "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)", and every account a body names (batch recipients, split entries, an offer's counterparty, an app's invited opponent, a group member, controller or consent participant, a dataset's new owner, a release address or authority, a storage allow-list entry, an escrow request's parties) → the same text after the site's own prefix (03, 08, 10–18); a state-channel app whose creator or invited opponent cannot sign a 64-byte move voucher is refused (16). (b) Rule eth_signature_canonical_v: every signature by an Ethereum- or Tron-typed key that the transaction carries ends in the recovery byte 27 or 28: the envelope's ("Ethereum signature recovery id must be 27 or 28"), a MultiSignature body's participant signatures, an escrow co-signature, an account-group consent and a fee-vote reveal's voter signature (the same text after the site's prefix, 02, 12, 17, 18); a foreign carrier keeps its own chain's form. (c) Rule bridge_withdrawal_credit: a TransferToken whose message begins ZBW1| must be a well-formed withdrawal of an open bridge coin to its custody account (34 §5, e.g. "TransferToken: the withdrawal destination cannot be paid on ethereum: the Ethereum destination is in mixed case, so it carries an EIP-55 checksum, and the checksum does not match: a character is wrong"), and no transaction names a custody account otherwise (34 §5a). For height > 0: block.timestamp > tx.timestamp + window → "Block contains an expired transaction" (window = the transaction's version-3 expiry capped at 86,400 s, or 3,600 s when 0 or absent; rule tx_expiry_field); tx.timestamp > block.timestamp + 3,600 → "Block contains a transaction dated more than 3600 s after the block" (rule tx_timestamp_bound); with transactions, a non-empty merkle_root ≠ the recomputed root (05 §7) → "Invalid merkle root" (an empty carried root is not checked); total_fee ≠ Σ fee → "Block total fee mismatch".
  12. Receipts (23 §5), with |R| = the size of the active registry as of the previous block (rule receipt_count_active; unreadable → "Failed to read the registry for the receipt cap: <reason>"): for height h ≥ 40, the lookback height is derived from the first unlinked receipt's datum hash (the height of the main-chain block, or of the block holding the transaction, of that hash; when none is found, h − 40). Then the same recipient signature twice in the block → "DuplicateReceiptInBlock" (rule receipt_once, §9); then a derived lookback outside [h − 60, h − 20] → "ReceiptLookbackOutOfRange:<lookback>"; then, receipt by receipt in block order: sender key ≠ the block's blocksmith key → "InvalidReceiptSender"; carried by a main-chain block in [max(0, h − 40), h) → "ReceiptAlreadyPublished" (§9); recipient signature invalid → "Invalid receipt signature"; (rule receipt_reference_in_window) reference_block_height ≥ h or h − reference_block_height > 720 → "ReceiptReferenceOutOfWindow:<reference height>"; the main-chain block at the reference height not held → "InvalidReceiptBlockHash:<reference height>"; reference hash ≠ that block's hash → "InvalidReceiptBlockHash:<reference height>"; reference_height + expiration + 2 < h → "Receipt has expired" (expiration from 23); an unlinked receipt at h ≥ 40 whose recipient is not a priority peer of the blocksmith at the lookback → the texts of 23 §5. After the loop: count > 2 × min(|R| − 1, P) → "MaxAllowedReceiptsPerBlockExceeded"; count > 200 → "Too many receipts in block".
  13. Cumulative difficulty (05 §9), height > 0: recomputed ≠ carried → "Cumulative difficulty mismatch: expected X, got 'Y'".
  14. Coinbase, checked when the block is stored (§4): total_coinbase must equal the block's coinbase schedule (21; block 1 exactly 0; an empty block carries the schedule like any other) → "Negative total_coinbase", "total_coinbase exceeds emission schedule: got X, max Y", "total_coinbase below emission schedule: got X, schedule Y".

How to compute it. As stated; every recomputation is specified in 05, 20 and 23. Step 11 may verify the signatures in parallel; the verdict and the text (lowest failing index) must not depend on it.

Rule activation. Every rule named here (block_size_serialized, foreign_carrier_bound, receipt_once, receipt_reference_in_window, tx_expiry_field, tx_timestamp_bound, seed_vrf, validator_no_fallback, halt_recovery_param, receipt_count_active, activation_readiness_gate, survival_mode, canonical_account_forms, eth_signature_canonical_v, bridge_withdrawal_credit) is active from height 0 on every chain. The one-transaction-per-account check, the batch ceiling, the version-0 refusal and the exact coinbase have no rule.

Rejections and errors. As listed; each makes the block invalid.

Vector. computed (a header with these values; the chain's genesis is at 1,793,509,027). INPUT (the header fields): version 600, timestamp 1,793,509,192, total_amount 0, total_fee 0, total_coinbase 197,732,050, payload_length 0, payload_hash 32 zero bytes, blocksmith_public_key 715ea8e2f51bbcb778a26e69d73bd1044fe3a43d76cb1cf6cbc3a9a661a2fbac, block_seed 4cb46a86ec544cd107fed1d2fc2a30318a4fa54701dff7d1c02598f05b09fbda07e847ba79b0a9e57acb64db45810ebe43da8e490c8bef475a404c9519dd0af2, previous_block_hash 1446492f4cf3718857d8f0e5ea60fc81f01d6f1fdda862d7a73cafcd3215aeb6, block_seed_proof 65c4971d4cb7313c4d0c7846494f556022b1476f5de76726819b4b53feacbd0cc6752e89d0b9db1b72000808754553b2aa170f89737e22b9523ec31c3791f739e5f3345e0a9baf76ee7c7f824f74040d, block_signature 5cb62b52b24f47fc883bfeda20eec412a884713f1bca2d5d01cf882bd4f6c5941924aa51a6685a6b2c303021a4d6b3ea808ad30523d4817edfa0f4115668fa05; previous block 9: timestamp 1,793,509,177, hash as above, cumulative difficulty 8500000. EXPECTED: the 284-byte unsigned header is 5802000048c7e66a0000000000000000000000000000000000000000d226c90b0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000715ea8e2f51bbcb778a26e69d73bd1044fe3a43d76cb1cf6cbc3a9a661a2fbac4cb46a86ec544cd107fed1d2fc2a30318a4fa54701dff7d1c02598f05b09fbda07e847ba79b0a9e57acb64db45810ebe43da8e490c8bef475a404c9519dd0af21446492f4cf3718857d8f0e5ea60fc81f01d6f1fdda862d7a73cafcd3215aeb665c4971d4cb7313c4d0c7846494f556022b1476f5de76726819b4b53feacbd0cc6752e89d0b9db1b72000808754553b2aa170f89737e22b9523ec31c3791f739e5f3345e0a9baf76ee7c7f824f74040d; the signature verifies under the blocksmith key; block_hash = SHA3-256(header ‖ signature) = c535a2ea1d122c30feefab263bc8a144fe332caff1f82eacb20e8fc742adc7c6; id 3,471,169,332,495,660,485; gap 15 s → round 1, persist window [1,793,509,185, 1,793,509,199); the cumulative difficulty the block must carry is 9500000 (one node drawn first over a draw set equal to the registry, 20 §6). The seed check of step 10 needs the previous seed, which this vector does not give. On every chain built from 0.6.1 this header is nevertheless refused at step 5: "Block version 600 is below the active bundle 601 (activation_readiness_gate)" (every rule of bundle 601 is at height 0, so 601 is active at height 10); a valid block of such a chain carries version 601 and a signature over the header with that value. INVALID INPUTS (each a version-601 block of that kind with one change): total_fee 1 → "Invalid block signature" (the fee is in the signed header; the payload check passes); timestamp 1,793,509,177 → "Block timestamp (1793509177) must be after previous block (1793509177)"; previous_block_hash with its last byte changed → "Invalid previous block hash"; 2,001 SendZBC transactions → "Too many transactions in block (2001 > 2000)"; payload_length 524,289 → "Block payload_length exceeds maximum (524289 > 524288)"; a SendZBC and a TransferToken signed by one key → the one-transaction-per-account refusal; two SendZBC carriers wrapping the same signed Ethereum transaction (one carrier id) → "ForeignCarrierReplayed"; one SendZBC carrier whose Ethereum transaction a block below h already carried → "ForeignCarrierReplayed"; a receipt with reference_block_height h − 721 → "ReceiptReferenceOutOfWindow:<h − 721>"; a SendZBCBatch whose payment 0 names 04000000 followed by a 64-byte key (68 bytes) → "SendZBCBatchTransaction: payment 0: 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)"; a SendZBC (no carrier) from an Ethereum-typed sender whose 65-byte signature verifies but ends in the byte 01 → "Ethereum signature recovery id must be 27 or 28" (the same signature with last byte 1c = 28 is accepted).

Test cases · §2

32 cases · 12 valid · 20 invalid

The §2 header at height 10: bytes, signature, hash and id19-2-block-10valid

Loading the test widget…

The §2 header with total_fee 1: the signature no longer verifies19-2-fee-changedvalid

Loading the test widget…

The §2 header over block 9: refused for version 600 below bundle 60119-2-version-600invalid

Loading the test widget…

The same header with version 601, signed by its blocksmith: valid, round 119-2-validvalid

Loading the test widget…

The version-601 header: its block hash19-2-version-601-hashvalid

Loading the test widget…

The version-601 block with total_fee 119-2-fee-1invalid

Loading the test widget…

The block stamped like block 919-2-same-timestampinvalid

Loading the test widget…

The block with the last byte of its previous hash changed19-2-previous-hashinvalid

Loading the test widget…

The block presented at height 1119-2-heightinvalid

Loading the test widget…

An empty block carrying payload_length 119-2-payload-lengthinvalid

Loading the test widget…

The block with version 019-2-version-0invalid

Loading the test widget…

The block carrying another block hash19-2-block-hashinvalid

Loading the test widget…

A carried block hash whose first 8 bytes are zero19-2-id-zeroinvalid

Loading the test widget…

Previous difficulty 8500000, the blocksmith drawn first over a draw set equal to the registry19-2-difficulty-10valid

Loading the test widget…

2,001 SendZBC transactions19-2-2001-sendsinvalid

Loading the test widget…

2,000 SendZBC transactions pass the ceiling19-2-2000-sendsvalid

Loading the test widget…

1,976 SendZBC and a SendZBCBatch of 25 payments count 2,00119-2-batch-countsinvalid

Loading the test widget…

payload_length 524,28919-2-payload-524289invalid

Loading the test widget…

A SendZBC and a TransferToken signed by one key19-2-one-accountinvalid

Loading the test widget…

Two transactions from two accounts19-2-two-accountsvalid

Loading the test widget…

One Ethereum carrier and a SendZBC from another account: the carrier id, nothing spent19-2-carrier-oncevalid

Loading the test widget…

Two SendZBC carriers wrapping the same signed Ethereum transaction (one carrier id)19-2-carrier-twiceinvalid

Loading the test widget…

A carrier whose Ethereum transaction a block below already carried19-2-carrier-spentinvalid

Loading the test widget…

A carrier whose raw message's SHA3-256 is in the spent set19-2-carrier-message-hashinvalid

Loading the test widget…

The carrier of the next nonce is another carrier id19-2-carrier-other-noncevalid

Loading the test widget…

A receipt with reference_block_height h − 72119-2-reference-721invalid

Loading the test widget…

A receipt with reference_block_height h − 72019-2-reference-720valid

Loading the test widget…

A receipt whose reference height is the block's own19-2-reference-at-hinvalid

Loading the test widget…

A SendZBCBatch whose payment 0 names an Ethereum full-key form (68 bytes)19-2-batch-full-keyinvalid

Loading the test widget…

The same batch naming the 20-byte Ethereum address instead19-2-batch-addressvalid

Loading the test widget…

A SendZBC from an Ethereum-typed sender whose signature verifies but ends in 0119-2-eth-v-01invalid

Loading the test widget…

The same signature with last byte 1c (28)19-2-eth-v-28valid

Loading the test widget…

Defects to match. (1) The future bound is the only wall-clock dependency: a block dated more than two hours ahead of a node's clock is refused by that node and accepted later. (2) The "too fast" test uses min_block_interval − 2. (3) A carried merkle_root of zero length is accepted whatever the transactions, and replaced by the computed root at apply (§4). (4) The ceilings read the parameters; the values used when a parameter is absent are far smaller. (5) Step 12 tests the in-block duplicate before the lookback range: a block failing both is refused DuplicateReceiptInBlock; the verdict is the same. (6) The carrier replay check of step 11 runs before the one-transaction-per-account check: a block failing both is refused ForeignCarrierReplayed.

3. The timestamp window and the blocksmith's right

Purpose. An implementation must tie a block's timestamp to its blocksmith exactly as here (the full selection is 20).

Inputs. The previous block's timestamp P and seed; the parameters of §2; the draw set as of the previous block (20 §1).

Output and effect. With base = P (rule smith_window_anchor) and the half gap 7 (= 15 div 2): round(T) = 1 when T − base − 8 < 0, else 1 + floor((T − base − 8) / 15). For round r: target_r = base + 15 + 15 × (r − 1); the persist window [max(target_r − 7, P + 1), target_r + 7); the creation window [max(target_r − 7, P + 1), target_r + 7 + 20). The blocksmith check holds when, for some round i in {round(T) − 1, round(T)} (i ≥ 1), the i-th draw of the selection generator seeded with "zbc-blocksmith" and the previous seed (20 §1) names the blocksmith in the draw set (the demoted previous blocksmith counted as 20 §1 says) and T lies in round i's creation window. §2 step 5 additionally requires T in the persist window of round(T) widened by 2 s at both ends. The blocksmith's position (the index of the first draw naming it among the first 2n draws over the draw set of n nodes, else its place in the hash order, 20 §3) decides the empty-block rule of §2 step 6.

How to compute it. Integer arithmetic only, divisions rounding toward zero on non-negative values.

Rule activation. smith_window_anchor is active from height 0 on every chain.

Rejections and errors. §2 steps 5 and 6.

Vector. computed. INPUT: P = 1,793,509,177. EXPECTED: T = P + 15 = 1,793,509,192 → round 1, persist window [P + 8, P + 22) = [1,793,509,185, 1,793,509,199), creation window [1,793,509,185, 1,793,509,219). T = P + 30 → round 2, persist [P + 23, P + 37). T = P + 22 → round 1; outside [P + 8, P + 22) but inside the 2 s widening [P + 6, P + 24) → accepted. T = P + 25 → round 2. INVALID: T = P + 5 → "Block produced too fast (5s < min 15s)" (the gap test of §2 step 5 runs before the window test).

Test cases · §3

3 cases · 2 valid · 1 invalid

Rounds and windows after block 919-3-windowsvalid

Loading the test widget…

T = P + 22: outside round 1's persist window, inside its 2 s widening19-3-widenedvalid

Loading the test widget…

T = P + 5: the gap test runs before the window test19-3-too-fastinvalid

Loading the test widget…

Defects to match. The persist window is that of the round derived from T itself, widened by 2 s, and the gap test refuses every T below P + 13 first: the window test of §2 step 5 never refuses a block whose gap test passed. An implementation must still run it in that place.

4. Application: what can still refuse a valid block

Purpose. An implementation must apply a validated block atomically and refuse it as a whole when any of these steps fails.

Inputs. The validated block; the tip; the mempool; the state; the block's survival flag (§10).

Output and effect. Under one exclusive lock of the chain:

  1. The tip must still be the block's previous block, else "Block at current height - fork resolution needed", "Block height mismatch: expected H, got G" or "Invalid previous block hash" (a changed tip, no penalty). The one-transaction-per-account check and the transaction ceiling of §2 run again (same texts).
  2. In one database transaction, each transaction is normalised: a carried transaction_body_length of 0 is filled with the body size, any other value must equal it → "Invalid transaction body length"; the carried hash must equal the recomputed one (03 §9) → "Transaction hash mismatch"; the id derived from it must be non-zero and equal any carried id → "Invalid transaction ID (zero)", "Transaction ID mismatch"; no id twice in the block → "Duplicate transaction ID in block"; for height > 0 no transaction with this id already in the chain → "DuplicateTransaction".
  3. For height > 0 the stored merkle_root is the root recomputed from the transactions (05 §7), whatever the copy carried.
  4. The end-of-block sweeps that precede transactions (22); then every transaction is executed in block order (08 §1). Any executor error refuses the block with the executor's own text (the node logs "BLOCK REJECTED: Transaction i/n in block H failed: <code>: <reason>", i counted from 0, <code> the error's category such as ValidationError). The executor first re-runs the transaction's validation of §2 step 11 at the block's height, so a transaction of the frozen set (§10) in a block whose survival flag is true fails there with the text of §2 step 11; the executor's own survival text ("SurvivalMode: transaction type T is not accepted in block H (survival mode: governance and bridge are frozen; fewer than survival_min_producers producers)") follows that check and is never reached. Two carrier outcomes (rule foreign_carrier_bound): (a) an Ethereum carrier whose signed nonce N is not the sender's account nonce M (one transaction per account per block, so M is the nonce before the block) makes the block invalid: the executor refuses it, right after the re-run validation and the account-group gate and before anything of the transaction is written, with "ForeignCarrierNonce: carrier nonce N, account nonce M (a block carrying it is invalid)"; no fee is taken, the nonce does not move, the carrier id is not spent, and the whole block is refused like any executor error (its blocksmith loses the block; the relaying peer is not charged, as for every §4 refusal). The mempool, the staging pool and block assembly refuse a wrong nonce first (04, 20 §4), so an honest blocksmith never builds such a block. (b) A carrier whose id the committed state already holds as spent (unreachable through §2, which refuses it first) is a paid no-op: the declared fee is charged and the overpay above the fee floor (04 §5) returned (event 22), or, when the signer cannot pay, the refund and not-collected rows of 04 §5 are written; nothing moves. A successful carrier writes its id (and the SHA3-256 of its message, as a second key) to the spent set at this height.
  5. The published receipts are processed (re-validated unless the block was produced here; a failing one, or "MaxAllowedReceiptsPerBlockExceeded", refuses the block) and written as published_receipt rows of this height, one per receipt (23; §9 reads them).
  6. For height > 1 the skipped-blocksmith step runs (it writes rows from height 40, 20 §5); its failure refuses the block.
  7. The block is stored (its link checked again and the coinbase of §2 step 14), then its survival flag (§10).
  8. The registry step, the liveness step (expulsions paused while the flag is true, §10, 36), the leave step (09, 36), the fee scale (17 §3) and the remaining steps of 22; then the rule edge records and the readiness gate (29: with block h applied the gate decides h + 1 and, when a gated bundle qualifies, writes its decision row in this block's transaction, 21 §1 step 13).

The block is refused on this node (to be retried by sync) when the registry, liveness or leave step returns an error; when an end-of-block step (the archive, the fee scale, the price counts, the oracle, the bridge, the release governance, the survival flag) cannot read what it decides on; when a consensus parameter read during the apply is malformed or unreadable, or an account, token, node-owner or oracle row cannot be read; and when the storage fails any write while the block is applied (busy, locked, out of memory, read-only, interrupted, I/O error, corrupt, full, cannot open, protocol error, not a database); a constraint or schema refusal is not a storage fault. A failed read is never taken for "nothing there". Only after every step does the transaction commit, and the block is broadcast when it was produced here.

A blocksmith runs its own candidate (when it carries transactions) through this same application as a dry run before signing it: every step runs, nothing commits, no survival row is written and the readiness gate of 29 does not advance; a transaction that fails deterministically is evicted and the candidate rebuilt without it (20 §4). This is local behaviour.

How to compute it. As stated, in that order.

Rule activation. The survival refusal (step 4, through §2 step 11) and the paused expulsions (step 8) are rule survival_mode (§10); the two carrier outcomes of step 4 are rule foreign_carrier_bound; both active from height 0 on every chain. Nothing else here changes by height.

Rejections and errors. As listed. Deterministic (every node refuses alike): steps 1–5, 7 and the executor errors. Local (this node only, retried): lock timeouts, the 60 s normalisation and 90 s execution watchdogs, the fail-closed reads, storage faults ("<what>; block H not applied", "survival state unreadable: <reason>"). A storage fault or a failed read noticed after the readiness gate advanced, or a failed commit of the block's database transaction, puts the gate back (it forgets a decision made for h + 1, whose row did not commit), so the next attempt decides again. Node-local: the watchdogs are a resource limit, not a validity verdict; a slow node refuses a block a fast one accepts, and fetches it again.

Vector. INPUT: a valid block at height h carrying transaction X twice. EXPECTED: "Duplicate transaction ID in block", no state changes. INPUT: a block at h whose survival flag is true (§10 vector: h = 3 on a chain with N = 5) carrying a SetConsensusParam (type 51). EXPECTED: invalid, refused at §2 step 11 with "SurvivalMode: transaction type 51 is not accepted while fewer than survival_min_producers distinct producers made the last 120 blocks (survival mode: governance and bridge are frozen until N produce again)"; the executor, which re-runs that validation first, would give the same text (logged as "BLOCK REJECTED: Transaction 0/1 in block 3 failed: ValidationError: SurvivalMode: transaction type 51 is not accepted while fewer than survival_min_producers distinct producers made the last 120 blocks (survival mode: governance and bridge are frozen until N produce again)"). INPUT: block h at index 0 carries a SendZBC carrier whose signed Ethereum transaction carries gas limit 30,000, gas price 10^12 wei (declared fee = 30,000 × 10^12 / 10^10 = 3,000,000) and nonce 4, while the sender's account nonce is 3 and its balance 10,000,000. EXPECTED: the block is invalid, refused at apply with "ForeignCarrierNonce: carrier nonce 4, account nonce 3 (a block carrying it is invalid)" (logged as "BLOCK REJECTED: Transaction 0/1 in block h failed: ValidationError: ForeignCarrierNonce: carrier nonce 4, account nonce 3 (a block carrying it is invalid)"); nothing is written: the balance stays 10,000,000, the account nonce 3, the carrier id is not in the spent set. The same carrier with nonce 3: the block is valid, the transfer is made, the account nonce becomes 4 and the carrier id is spent at h. INPUT: a valid block with no transactions and an empty merkle_root. EXPECTED: stored with merkle_root 32 zero bytes.

Test cases · §4

6 cases · 3 valid · 3 invalid · 2 reference

A SetConsensusParam in block 3 of a chain with N = 519-4-survival-51invalid

Loading the test widget…

A SendZBC in the same block is not frozen19-4-survival-sendvalid

Loading the test widget…

A block carrying one transaction twice19-4-duplicate-txinvalidreference

The apply path's normalisation; it needs the chain to run.

A stated value: there is nothing to compute. The statement is a refusal: the exact text a compatible node answers.

refusal
Duplicate transaction ID in block
state
no state changes
An Ethereum carrier with nonce 4 while the account nonce is 3: the block is invalid19-4-carrier-nonceinvalid

Loading the test widget…

The same carrier with nonce 3: valid, the nonce becomes 4 and the id is spent19-4-carrier-nonce-3valid

Loading the test widget…

A block with no transactions and an empty merkle_root is stored with 32 zero bytes19-4-empty-merkle-rootvalidreference

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

merkle_root
0000000000000000000000000000000000000000000000000000000000000000

Defects to match. A carried transaction_body_length of 0 is accepted and filled; a wrong non-zero length makes the block invalid.

5. The candidate pool

Purpose. An implementation that produces must hold competing candidates for a height and apply the one the timing rules prefer.

Inputs. Candidates (block, creator key, claimed priority position, local or received); the previous block; the selectable set; the tip; the clock; max_priority_blocksmiths, max_block_size_bytes.

Output and effect. Bounds first: a candidate at or below the tip height, or more than 4 heights above it, is refused, and so is one that would bring the sum of the pooled candidates' serialized sizes (§8) above the byte cap = max(8,388,608, max_priority_blocksmiths × max_block_size_bytes); every candidate at or below the tip is dropped on every add and whenever the tip moves. Then a candidate is admitted when: no candidate of the same creator is held for that height; the previous block is held and the candidate's previous_block_hash and height link to it; no two of its transactions come from one account (§2 step 11); its signature verifies over the 284-byte unsigned header (05 §3); the selectable set is non-empty; the recomputed priority (count − 1 of 20 §6) equals the claimed one; the blocksmith check of §3 holds; a priority ≥ max_priority_blocksmiths carries no transactions. Selection: among the candidates whose selectable window contains the current time (the persist window of round position + 1, its start moved blocksmith_network_tolerance = 5 s later for rounds 2 and above while that leaves the window non-empty: round 2 is selectable from P + 28, not P + 23), the lowest position wins, ties by the earlier block timestamp; the winner must pass the full §2 against the tip and is applied by §4; one that fails is removed and the next best tried (at most 64 tries). A node behind its peers does not select. Node-local: selection follows the local clock, so nodes with skewed clocks apply different candidates for a moment, and §6 settles it.

How to compute it. As stated. With both shipped genesis files the cap is max(8,388,608, 10 × 524,288 = 5,242,880) = 8,388,608 bytes.

Rule activation. None.

Rejections and errors. A refused candidate is answered "Candidate rejected" (27); nothing else is observable.

Vector. INPUT: tip 100; candidates for heights 100, 104, 105. EXPECTED: 100 refused (at or below the tip), 104 admitted, 105 refused (too far ahead). INPUT: two valid candidates for height 101 at positions 0 and 1, block 100 stamped P. EXPECTED: their selectable windows are [P + 8, P + 22) and [P + 28, P + 37), so the clock is never in both: at P + 15 position 0 is applied; at P + 25 nothing is selected; position 1 is applied from P + 28 only when position 0's candidate was not applied. INPUT: a correctly signed round-1 candidate with a wrong payload hash. EXPECTED: admitted, then refused by the full validation ("InvalidBlockPayload: hash mismatch") at selection and removed.

Test cases · §5

6 cases · 6 valid · 1 reference

Tip 100: candidates for heights 100, 104 and 10519-5-boundsvalid

Loading the test widget…

A candidate that would bring the pool over its byte cap19-5-fullvalid

Loading the test widget…

Candidates at positions 0 and 1, the clock in position 0's window19-5-position-0valid

Loading the test widget…

The clock 2 s into round 2's persist window: nothing is selected yet19-5-position-1-heldvalid

Loading the test widget…

The clock in round 2's selectable window19-5-position-1valid

Loading the test widget…

A correctly signed round-1 candidate with a wrong payload hash19-5-bad-payloadvalidreference

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

admitted
yes
at selection
InvalidBlockPayload: hash mismatch
then
removed

Defects to match. None: a candidate whose size cannot be computed is refused at admission ("candidate size cannot be computed: <reason>"), before the bounds.

6. Fork resolution

Purpose. What the validation decides when a node weighs its branch against a peer's (the full procedure, the page loop, the rollback, the partial application and the wedge recovery are 24).

Inputs. A peer whose chain diverges; max_rollback_height (testnet 720, devnet 60; 720 when absent); the finalized height (the reference height of the newest spine block checked against this node's main chain, rule checkpoint_finality, 25); the newest spine block above the split; MIN_PEERS_FOR_CONFIRMATION 3; the page size 100 ids; the fetch cap 2 × max_rollback_height + 100 blocks; the attempt budget max(120, 15 × ceil((2 × max_rollback_height + 100) / 100)) s.

Output and effect. Triggered when the sync source does not recognise our tip's id, when its block at our height has another hash, or on a periodic investigation (28). The common milestone is found and walked forward to the real split point (100 ids per page, at most 10 pages); a peer with nothing past what we share → "Peer has no new blocks". Before any download: when depth = tip − common > max_rollback_height, or the common block is below the finalized height, the branch is out of reach; peers' confirmations are then a hint for the log only, and the decision rests on signed evidence: the newest spine block above the split names a block this node holds differently at that height → this node is wedged ("Fork rejected: beyond the rollback bound on the branch the spine's checkpoint names (wedge)"); it names our block, or the common block is below the finalized height → refused ("Fork rejected: common block C is below the checkpoint floor F (the last co-signed spine reference); the branch was not fetched", "Fork rejected: rollback depth exceeds max_rollback_height limit"; in these texts "checkpoint" means the newest spine block and "co-signed" means carrying the required spine signatures); no spine block above the split yet → the branch is fetched and weighed like any other, a heavier valid branch is the wedge ("Fork rejected: beyond the rollback bound on a heavier valid branch (wedge)"), a lighter one refused. A spine block carrying its required signatures whose reference names a main-chain block this node holds differently is kept as checkpoint evidence (24 §3): it answers "theirs" for every split below its reference height until a newer spine block supersedes it, and the peer that served it is not charged. Within reach, the branch is downloaded page by page and weighed on its own state (a replay from the common block: the liveness with the survival flag followed along the branch, §10, a scratch registry, the skipped blocksmiths, each block's difficulty over the branch's draw set); every branch header's signature must verify first; a branch that does not out-weigh ours is refused before any rollback. A heavier branch is applied block by block through §2 and §4; it is kept when it weighs at least ours and the registered peers confirm it; a branch that fails part-way keeps the applied prefix and the outcome is partial (24); a popped block's transactions return to the mempool. A wedge is rebuilt in place from a spine-attested snapshot, the resync marker being the fallback (24, 26).

How to compute it. As stated; difficulty strings compare as unbounded non-negative decimal integers (longer is larger, then lexical). A branch is fetched only while it is strictly heavier than ours, so a branch of exactly our weight is refused before any rollback; the lower tip hash (rule fork_tie_by_hash) decides only when an applied prefix ties our weight (24 §3). Node-local: within reach the confirmations are peer polls (with fewer than 3 other registered voters the milestone poll passes and the weight poll leaves the decision to the recomputed weight, 24 §5), and a branch whose first block fails §2 on a timestamp is attributed to the local clock without charging the peer.

Rule activation. checkpoint_finality, branch_registry_replay, difficulty_draw_set, weight_by_draw_share, fork_tie_by_hash and survival_mode (the flag in the replay, §10) are active from height 0 on every chain.

Rejections and errors. As listed (the texts are local log and peer-charging reasons, 24).

Vector. INPUT (devnet, max_rollback_height 60): tip 1,000, split at 939 (depth 61), the newest spine block above 939 names our block at its reference height. EXPECTED: "Fork rejected: rollback depth exceeds max_rollback_height limit", nothing downloaded. Same with no spine block above 939 and a branch that recomputes heavier. EXPECTED: "Fork rejected: beyond the rollback bound on a heavier valid branch (wedge)". INPUT: max_rollback_height 720. EXPECTED: attempt budget max(120, 15 × ceil(1,540 / 100)) = 15 × 16 = 240 s. INPUT: difficulties "9500000" vs "10000000". EXPECTED: the second is heavier (8 digits > 7).

Test cases · §6

4 cases · 3 valid · 1 invalid

Devnet, split 61 deep, a spine block names our block19-6-depth-61-oursinvalid

Loading the test widget…

Devnet, split 61 deep, no spine block above it, a heavier branch19-6-depth-61-heaviervalid

Loading the test widget…

The attempt budget at max_rollback_height 72019-6-budget-720valid

Loading the test widget…

9500000 against 1000000019-6-comparevalid

Loading the test widget…

Defects to match. None.

7. Outcomes and the consensus/local split

Situation Outcome
same hash already stored at that height duplicate: ignored (receipt answered)
different hash at a stored height, or previous hash ≠ tip at tip + 1 fork signal: ignored, resolved by §6
height > tip + 1 ignored, fetched by sync
a full relayed copy over the serialized limit refused before validation, sender charged
any check of §2 fails invalid: not stored, sender charged (28)
§4 fails deterministically invalid: not stored; a blocksmith evicts the transaction
§4 fails on a local fault or timeout not stored here; fetched again
all pass stored, tip advanced, survival flag written, mempool reconciled, broadcast if own

Consensus: §2 steps 1–14 (the two-hour future bound included, which every honest clock agrees on), the serialized size (§8), the receipt-once rule (§9), the carrier replay rule and the spent set, the survival flag and its frozen set (§10), §3, the normalisation and execution refusals of §4, the fork choice by the branch-replayed cumulative difficulty, the rollback depth and the finality floor. Local: the candidate pool's clock-driven selection and bounds, the blocksmith's dry run and size trim, the relay's early size refusal (it refuses only what §2 refuses), the peer polls, the wedge declaration and its recovery, watchdogs, lock timeouts, the fail-closed read refusals (a healthy node never takes them), the peer-charging policy and the log texts.

Test cases · §7

1 case · 1 valid · 1 reference

Outcomes of an arriving block19-7-tablevalidreference

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

same hash already stored at that height
duplicate: ignored (receipt answered)
different hash at a stored height, or previous hash not the tip at tip + 1
fork signal: ignored, resolved by §6
height above tip + 1
ignored, fetched by sync
a full relayed copy over the serialized limit
refused before validation, sender charged
any check of §2 fails
invalid: not stored, sender charged
§4 fails deterministically
invalid: not stored; a blocksmith evicts the transaction
§4 fails on a local fault or timeout
not stored here; fetched again
all pass
stored, tip advanced, survival flag written, mempool reconciled, broadcast if own

8. The serialized block size

Purpose. An implementation must compute one number as a block's size, the same for every copy of the block, and bound the fields a copy carries outside the block hash.

Inputs. The block: its header (with or without the 80-byte seed proof), its transactions in their signed form (03 §1), the number of its published receipts and each one's intermediate_hashes and rmr_linked lengths, its merkle_tree length; the parameter max_block_size_bytes (524,288 in both genesis files; 88,000 when absent).

Output and effect. The serialized size S(b), an unsigned 64-bit byte count:

S(b) = U + 64 + Σ over the transactions of their signed length + 1,288 × (number of published receipts)

  • U = the length of the unsigned header of 05 §2: 4 (version) + 8 × 5 (timestamp, total amount, total fee, total coinbase, payload length) + 32 (payload hash) + 32 (blocksmith key) + 64 (seed) + 32 (previous hash) = 204, plus 80 when the block carries a seed proof = 284 for every block above genesis on every chain (rule seed_vrf). The 64-byte signature is counted whether or not the block is signed yet.
  • Each transaction counts its signed length (envelope, body, escrow part, message, signature, 03 §1).
  • Each published receipt counts a fixed 1,288 bytes: its 232 signed bytes (sender 32 + recipient 32 + reference height 4 + reference hash 32 + datum type 4 + datum hash 32 + rmr 32 + signature 64, 23 §1) + a 1,056-byte proof allowance (intermediate_hashes up to 32 × 32 = 1,024, rmr_linked up to 32), whatever proof bytes the copy actually carries. The proof fields travel outside the block hash; counting the allowance instead of the actual bytes makes the size a function of the hashed content, so a relay cannot pad an honest full block's copy over the limit.

The block is invalid (§2 step 3) when a transaction cannot be serialized (no size), when S(b) > max_block_size_bytes, when its merkle_tree is non-empty (a main-chain block carries none), or when a published receipt carries intermediate_hashes longer than 1,024 bytes or rmr_linked longer than 32 bytes. The last two judge the copy as received; the bound keeps the bytes on the wire at or below the bytes counted. payload_length (§2 step 2) keeps its own meaning for the payload hash (05 §6).

The blocksmith, once its receipts are attached and its payload hash given its final 32 bytes, drops transactions from the end of its candidate until S ≤ max_block_size_bytes (receipts stay; a candidate whose header and receipts alone exceed the limit is left with no transactions). A node receiving a full copy by gossip sizes it before anything else (§1); an ids-only copy is sized by §2 once its transactions are fetched.

How to compute it.

  1. S = 204 + 64; S += 80 when the block carries a seed proof.
  2. For each transaction in block order: serialize it signed; failure → the block is invalid; S += its length.
  3. S += 1,288 × number of published receipts.
  4. Invalid when S > max_block_size_bytes, or merkle_tree is non-empty, or any receipt's intermediate_hashes > 1,024 bytes or rmr_linked > 32 bytes.

Rule activation. Rule block_size_serialized, active from height 0 on every chain.

Rejections and errors. Make the block invalid: "BlockTooLarge: the block cannot be sized: <reason>", "BlockTooLarge: serialized N bytes over the limit M", "BlockTooLarge: a main block carries no merkle_tree (N bytes attached)" ("main block" = main chain block), "BlockTooLarge: a receipt's proof fields are over their bound (A + B bytes)". The relay's early refusal: "relay: block over the serialized limit".

Vector. computed. INPUT: the header of §2 (seed proof present, no transactions, no receipts, merkle_tree empty). EXPECTED: S = 284 + 64 = 348, valid. INPUT: a block with a seed proof, no transactions, 10 published receipts each with empty intermediate_hashes and empty rmr_linked, payload_length 2,320. EXPECTED: S = 348 + 10 × 1,288 = 13,228, valid. INPUT: the same block with one receipt carrying 33 intermediate hashes (1,056 bytes) and an empty rmr_linked. EXPECTED: S unchanged (13,228), refused "BlockTooLarge: a receipt's proof fields are over their bound (1056 + 0 bytes)". INPUT: the header of §2 with a merkle_tree of 64 bytes. EXPECTED: "BlockTooLarge: a main block carries no merkle_tree (64 bytes attached)". INPUT: seed proof present, 20 receipts (the receipt bound of a registry of 11 with P = 12: 2 × min(11 − 1, 12)), and signed transactions totalling 498,181 bytes, max_block_size_bytes 524,288. EXPECTED: S = 348 + 498,181 + 25,760 = 524,289 → "BlockTooLarge: serialized 524289 bytes over the limit 524288"; with 498,180 bytes of transactions S = 524,288, valid.

Test cases · §8

6 cases · 6 valid

Size of an empty block19-8-block-10valid

Loading the test widget…

Ten receipts: each counts 1,288 bytes19-8-ten-receiptsvalid

Loading the test widget…

A receipt with 33 intermediate hashes19-8-proof-overvalid

Loading the test widget…

A main chain block with a merkle_tree attached19-8-merkle-treevalid

Loading the test widget…

One byte over the limit19-8-one-overvalid

Loading the test widget…

Exactly at the limit19-8-at-limitvalid

Loading the test widget…

Defects to match. None.

9. A receipt counts in one block

Purpose. An implementation must let a published receipt earn its blocksmith a score once: never twice in one block, never again in a later block of the lookback window.

Inputs. The block at height h and its published receipts' 64-byte recipient_signature; the published_receipt record set of the main chain; the receipt lookback 40.

Data. published_receipt holds one row per published receipt of every stored main-chain block (columns in 07 and 23 §4); this mechanism reads two of them: recipient_signature (64 bytes) and block_height (u32, the height of the block that carried it). The rows of a block are written when the block is applied (§4 step 5); a pop-off to height t deletes every row with block_height above t, so the rows always describe the main chain. The read used here: "is there a row with this recipient signature and block_height in [a, b)?" (an index on the signature serves it).

Output and effect. A published receipt is identified by its recipient_signature. The block is invalid when two of its receipts carry the same signature ("DuplicateReceiptInBlock"), or when a receipt's signature appears in a row with block_height in [max(0, h − 40), h) ("ReceiptAlreadyPublished"). An empty signature is never "published" (and fails the signature check). A blocksmith applies the same window to every receipt it offers, and offers no receipt at all when the rows cannot be read; skipping is never invalid, so a blocksmith does this whether or not the rule is active (23 §6).

How to compute it.

  1. Collect the recipient signatures of the block; any repeat → DuplicateReceiptInBlock (before the lookback-range check of §2 step 12).
  2. For each receipt, after its sender check (§2 step 12): if a row with this signature and block_height in [max(0, h − 40), h) exists → ReceiptAlreadyPublished. A failed read → "ReceiptAlreadyPublished: the published receipts could not be read (<reason>)" (refused on this node).

Rule activation. Rule receipt_once, active from height 0 on every chain.

Rejections and errors. Make the block invalid: "DuplicateReceiptInBlock", "ReceiptAlreadyPublished".

Vector. computed. A block at height 12,400 by blocksmith 6b9aa5c7ca7f11c32b3bc6e006571319a7521aaa472f3c422f52626e48c3833e carries 10 receipts with 10 distinct recipient signatures, all with that sender, all with reference height 12,364 (inside the lookback window [12,340, 12,380]); the first is the receipt of 23 §1's vector, recipient signature 57c7084dd7426ad269e6c7b53e10251b552eaa678a7078ee78ca52fb935a0f185b67f0c0d5bddcc578fe03a6befef7cad83db01665f93e3126529be707d56d0e. INPUT: the block carrying that receipt twice. EXPECTED: "DuplicateReceiptInBlock". INPUT: a block at 12,420 carrying that receipt, with the row (signature above, block_height 12,400) present. EXPECTED: "ReceiptAlreadyPublished" (12,400 ∈ [12,380, 12,420)). INPUT: the same receipt as the first unlinked receipt of a block at 12,441, no row in [12,401, 12,441). EXPECTED: "ReceiptLookbackOutOfRange:12364" (12,364 ∉ [12,381, 12,421]).

Test cases · §9

6 cases · 2 valid · 4 invalid

Block 12,400 carrying the 23 §1 receipt, lookback 12,364 inside [12,340, 12,380]19-9-in-windowvalid

Loading the test widget…

Block 12,400 carrying that receipt twice19-9-twiceinvalid

Loading the test widget…

A block failing both the in-block duplicate and the lookback range19-9-twice-out-of-rangeinvalid

Loading the test widget…

A block at 12,420 carrying the receipt block 12,400 carried19-9-publishedinvalid

Loading the test widget…

The same receipt as the first unlinked receipt of a block at 12,44119-9-out-of-rangeinvalid

Loading the test widget…

The receipt carried by a block 41 heights below19-9-outside-windowvalid

Loading the test widget…

Defects to match. None.

10. Survival mode

Purpose. When too few distinct blocksmiths keep the chain alive, an implementation must keep producing but freeze what the chain governs and pause expulsions, until enough blocksmiths return.

Inputs. The genesis parameter survival_min_producers (N, the minimum number of distinct blocksmiths; an integer; absent or ≤ 0 means 0 = off; 5 in both shipped genesis files; the mainnet template does not name it (off); part of the genesis configuration hash only when the genesis names it, 06; the genesis builder refuses a value below 0 or above 10,000, above the number of genesis registered nodes − 2, and above 1 on a one-node genesis); the blocksmith keys of the main-chain blocks; the window SURVIVAL_WINDOW_BLOCKS = 120.

Data. survival_state(height u32 primary key, active 0/1): one row per height, written when the block of that height is stored, only while N > 0; a height without a row reads false. A pop-off to height t deletes every row above t. Snapshots carry the table (26). The prune keeps the rows of the last max_rollback_height + 120 heights, and every row at or above the lowest of: the newest attestation's height of each pending oracle or bridge event (parameter and release votes excepted) whose survival-adjusted idle age is within 720 blocks, and the height of each attestation of a pending release vote whose survival-adjusted age is within the vote window plus the rollback depth (22 §14); a snapshot carries exactly the retained rows. The flag is also recomputable from the blocks (below); an implementation that recomputes must get the same value. The blocksmiths are read from the main-chain blocks: "the number of distinct blocksmith keys among the main-chain blocks at heights a … b".

Output and effect. Every height h has a flag (true = survival mode). Height 0 has no flag (false). For h ≥ 1:

  • made(h) = the number of distinct blocksmith keys of the main-chain blocks at heights max(1, h − 120) … h − 1 (0 when h = 1);
  • flag(h) = next(flag(h − 1), made(h), N) with next(was, made, N) = false when N = 0, else made < N: the previous flag does not enter the result; survival mode ends as soon as N or more distinct blocksmiths made blocks in the window (no hysteresis), and a new chain starts in it (flag(1) … flag(N) are true, since fewer than N blocksmiths have produced).

The block at h is judged by flag(h), which depends only on blocks below h; the status API shows flag(tip + 1) as survival_mode (31). While flag(h) is true:

  • a block at h carrying a transaction of the frozen set is invalid (§2 step 11): the governance category — 7 FeeVoteCommitment, 263 FeeVoteReveal, 32 RegisterRelease, 33 ReleaseAuthorityPropose, 34 ReleaseAuthorityAccept, 35 RevokeRelease, 51 SetConsensusParam — and the bridge category, 17 AttestEvent; admission refuses them for the block they would land in (tip + 1) and a blocksmith leaves admitted ones in its pool (04);
  • a cycle-end count (the parameter-vote count at a cycle's last block, the fee-vote count at its count block) at h is skipped and the cycle's votes and reveals lapse (22);
  • the liveness step at h makes no expulsion: no candidate is chosen and no row is reset; suspended nodes stay suspended and keep their misses, and are expelled at the first later height whose flag is false (36);
  • the oracle resolution, the two bridge resolution steps and the release-governance step do not run at h: attestations and votes already on chain stay pending and are tallied at the first later height whose flag is false; the bridge idle window, the release-vote window and the authority delay do not count the survival heights (22 §13, 34, 17).

Every other transaction and registry change (registrations, suspensions, exits, key changes, receipts, pings) proceeds. A fork replay follows the same flag along the other branch, seeded from the stored flag at the common block and the blocksmiths of the 120 blocks up to it, advanced with the branch's blocksmiths (§6).

How to compute it.

  1. N = survival_min_producers; N = 0 → every flag is false and nothing is stored. A present but non-integer value is an error that refuses every block that needs it.
  2. For the block at h ≥ 1: start = h − 120 when h > 120, else 1; made = the distinct blocksmith keys among the main-chain blocks at start … h − 1.
  3. flag(h) = made < N.
  4. Store (h, flag(h)) after the block is stored; on a pop to t delete every row above t.

Rule activation. Rule survival_mode, active from height 0 on every chain. A chain whose genesis does not name survival_min_producers has N = 0 and the rule changes nothing.

Rejections and errors. In a block and at admission alike (the same transaction validity, judged at the block's height or at tip + 1): "SurvivalMode: transaction type T is not accepted while fewer than survival_min_producers distinct producers made the last 120 blocks (survival mode: governance and bridge are frozen until N produce again)" makes the block invalid (§2 step 11; the executor's later text "SurvivalMode: transaction type T is not accepted in block H (…)" is never reached, §4); "SurvivalMode: the survival state could not be read: <reason>" refuses it on this node.

Vector. computed (N = 5, the value of both shipped genesis files). INPUT: blocks 1 … 8 made by keys A, B, C, D, E, A, B, C. EXPECTED: flag(0) false; flag(1) … flag(5) true (made = 0, 1, 2, 3, 4); flag(6) … flag(8) false (made = 5). INPUT: blocks 1 … 499 made by A, B, C, D in turn, block 500 by E. EXPECTED: flag(500) true (heights 380 … 499: 4 keys); flag(501) false (heights 381 … 500: 5 keys). INPUT: blocks 501 … 620 by A, B, C, D in turn. EXPECTED: flag(621) true again (heights 501 … 620: 4 keys), with no hysteresis in either direction. INPUT: a block at 500 carrying a SetConsensusParam. EXPECTED: invalid, "SurvivalMode: transaction type 51 is not accepted while fewer than survival_min_producers distinct producers made the last 120 blocks (survival mode: governance and bridge are frozen until N produce again)". INPUT: a block at 500 carrying an AttestEvent (type 17). EXPECTED: invalid, the same text with type 17. INPUT: N = 0. EXPECTED: every flag false, no survival_state row.

Test cases · §10

6 cases · 4 valid · 2 invalid

Survival flag on a fresh chain, N = 519-10-fresh-chainvalid

Loading the test widget…

The 120-block window, N = 5: no hysteresis in either direction19-10-windowvalid

Loading the test widget…

N = 0: every flag is false19-10-offvalid

Loading the test widget…

A SetConsensusParam in block 500 (flag true)19-10-frozen-500invalid

Loading the test widget…

An AttestEvent (type 17) in block 500 (flag true)19-10-attest-frozeninvalid

Loading the test widget…

A SetConsensusParam in block 501 (flag false)19-10-after-500valid

Loading the test widget…

Defects to match. None.

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