On this page
  1. §0 The area in one paragraph
  2. 1. Cumulative difficulty and its comparison
  3. 2. The sync loop, the sync source and the fork triggers
  4. 3. Fork resolution
  5. 4. Finding the common block (milestones) and the split point
  6. 5. The peer polls
  7. 6. Rollback: popping blocks and restoring state
  8. 7. The candidate pool and the selection loop
  9. 8. Health check, investigation and deeper rollback
  10. 9. The incomplete-block queue
  11. 10. The wedge: declaration, in-place rebuild, resync marker
  12. 11. Consensus and local

24 — Fork choice and sync

Edition 0.6.1 · verified against the reference implementation, version 0.6.1

Out of scope the validity checks a fork block passes (19 §2) and its application (19 §4, 21); the difficulty increment of one block (05 §9, 20 §6); the wire format of the sync messages (27, chain sync queries) and the peer charging policy (28); the spine's own fork choice (25); fast sync, snapshots and their application (26); the full schema of every table (07)

§0 The area in one paragraph

ZooBC's fork choice is heaviest cumulative difficulty: every block carries a decimal integer string, the sum of the per-block increments since genesis, and the heavier of two tips wins, an equal weight being broken by the lower tip hash. An implementation enforces it locally when it notices a peer on a heavier branch: it asks the peer for milestone block ids until it finds a block both hold, walks forward to the real split point, and judges whether the split is within reach (no deeper than max_rollback_height, not below the finality floor the spine sets). Within reach it fetches the peer's branch page by page and weighs it on the branch's own state, refuses a branch that does not out-weigh its own before touching anything, otherwise pops off its own blocks to the common block (deleting them and cutting every state table back to that height), applies the peer's blocks one by one through the ordinary validation and application, and keeps the result when the new tip weighs at least as much as the old one and the registered peers confirm it; a branch that fails part-way is kept as far as it applied. Out of reach, no vote of peers decides anything: only signed evidence — the spine block above the split naming a block this node holds differently, or the other branch's own blocks recomputed heavier — declares the node wedged, and a wedged node rebuilds itself in place from a spine-attested snapshot, the restart-and-resync marker being the fallback. Around that core sit the pieces that keep an honest node on the main chain without a fork: the sync loop and its choice of sync source, the candidate pool, the incomplete-block queue and the health check. Only the comparison, the reach limits and the state a rollback restores are consensus; every poll, threshold and timer is local and is stated so that an implementation behaves the same in the same situations.

1. Cumulative difficulty and its comparison

Purpose. The scalar every fork decision uses, and the tie-break an implementation must apply.

Inputs. Two difficulty strings (decimal digits, no sign, 05 §9); for the tie-break the two tip hashes (32 bytes each) and the rule fork_tie_by_hash.

Output and effect. Compare(a, b) ∈ {−1, 0, 1}: an empty string loses to a non-empty one (both empty → 0); leading zeros are stripped, keeping at least one digit; a longer string is greater; strings of equal length compare character by character. Tie-broken comparison of a branch against ours: Compare(fork, ours) when it is not 0; when it is 0 (rule fork_tie_by_hash active at the fork tip's height) the branch wins (+1) when its tip hash is lower than ours as a byte string (unsigned, lexicographic, first byte most significant), loses (−1) when ours is lower, and 0 when the hashes are equal (one chain). Without the rule an equal weight compares 0.

How to compute it.

  1. If both strings are empty → 0; if a is empty → −1; if b is empty → 1.
  2. Strip leading 0 characters from each, leaving one character if all were zeros.
  3. A longer string → 1 for it; equal lengths → the first differing character decides.
  4. Tie (0) and the rule active → compare the tip hashes bytewise; the lower hash's branch wins.

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

Rejections and errors. None.

Vector. computed (a block carrying "11810449964" and its successor carrying "11811449964", the increment of 20 §6):

Input Expected output
Compare("11811449964", "11810449964") 1 (same length, character 5 1 > 0)
Compare("99999999999", "100000000000") −1 (shorter)
Compare("", "0") −1
Compare("007", "7") 0
tie, fork tip hash 42cfa11fce0acdbebfcb649a2934dffcaecc032789259024db35146ce1881c52, our tip hash f8bde70949a02d92d9340816449928ee99b6ea53d5729735dd3f3951e15c0086 +1: the fork's hash is lower (42 < f8), the fork wins
the same with the hashes swapped −1: ours is lower, our chain stays

Test cases · §1

6 cases · 6 valid

Compare("11811449964", "11810449964")24-1-nextvalid

Loading the test widget…

Compare("99999999999", "100000000000")24-1-shortervalid

Loading the test widget…

Compare("", "0")24-1-emptyvalid

Loading the test widget…

Compare("007", "7")24-1-leading-zerosvalid

Loading the test widget…

Equal weights: the branch's tip hash is lower24-1-tie-fork-lowervalid

Loading the test widget…

Equal weights: our tip hash is lower24-1-tie-ours-lowervalid

Loading the test widget…

Defects to match. None.

2. The sync loop, the sync source and the fork triggers

Purpose. How a node finds out it is behind or diverged, and whom it syncs from.

Inputs. Every 10 s ± 2 s of jitter: a random sample of 3 connected registered peers (when none and our height ≤ 10, 3 connected peers of any kind); our tip; max_recovery_interval_seconds (absent in both genesis files → 3,600); each sampled peer's GetCumulativeDifficulty answer (difficulty string, height; 27).

Output and effect.

  • Stale tip. Our tip is stale when now − tip.timestamp > 2 × max_recovery_interval_seconds (7,200 s). A stale node with height > 10 widens its sample to 7 registered peers and looks for a registry quorum: the answers are counted once per registered node key; with at least 3 answers, a tip (height, difficulty) reported by at least ceil(2n/3) of the n answers and higher than ours names the sync source (one of the peers that answered with it). The quorum picks whom to sync from only: the branch then reached is weighed like any other (§3), and a lighter one is refused after comparison. Without a quorum the node stays with the heaviest answer.
  • Best peer. Otherwise the sync source is the answering peer with the greatest difficulty (§1), skipping peers in divergence cool-down (after a branch refused with a verdict: 10, 20, 40, 80 then 120 minutes, doubling per refusal, capped; a success clears it; the streak is kept under the peer's node key when known, so a reconnect from another address carries it, and the address mirrors the key's entry) and, once, the peer whose branch was applied only in part on the previous pass (§3 step 9). With no answer at all, the connected peer with the greatest known height above ours is used. Nothing happens when the source's difficulty is not greater than ours (unless a quorum or the height fallback chose it).
  • Pull. The fast-sync hand-off (26 §5) is offered first. Then, from a cursor at our tip: GetNextBlockIDs(cursor id, 50) and GetNextBlocks(ids) from the source; each block is validated against our tip (19 §2) and applied (19 §4). The cursor moves only to a block this node now holds (applied, or already held with the same hash); a batch not held whole ends the pass and the next pass asks again from the tip. A fetched block whose round opens more than 900 s after our clock is a bad block ("sync block dated far ahead of its round", the source charged); one whose round opens within 900 s pauses the pass until it does. A block announced with a payload length but no transactions or receipts is fetched again from another peer before validation.
  • Fork triggers, each starting §3 with the source: (T1) the source answers NOT_FOUND for our tip id; (T2) a fetched block's height is one we hold with a different hash; (T3) a fetched block fails validation with "Invalid previous block hash"; (T4) the source is heavier but its tip is not above ours (another branch of equal or lower height, which the pull would never reach). Any other validation failure is recorded against the peer at that height; when 3 distinct peers fail at the same height within 60 s an investigation is raised (§8).
  • Messages (wire format and every error in 27, chain sync queries): GetCumulativeDifficulty (tip difficulty string and height), GetCommonMilestoneBlockIDs (§4), GetNextBlockIDs (at most 100 ids after a held block, NOT_FOUND "Block not found" for an id the server does not hold), GetNextBlocks (at most 50 ids per request, else INVALID_ARGUMENT "Too many block IDs requested"; full blocks in request order, unknown ids omitted), GetBlockHashes (§5; at most 1,000 heights, clamped to the server's tip). Every call is signed by the caller's node key (27). GetNextBlockIDs and GetNextBlocks (with RequestBlockTransactions) share one read budget per caller (its registered key, else key@host): at most 200 calls per 10 s, and a ceiling of 8 × 200 per host (an IPv4 address or an IPv6 /64), over either RESOURCE_EXHAUSTED "block read budget: 200 calls per 10 s per caller" before any work; a syncing node treats that answer as an RPC failure of that peer. A node decoding a fetched block refuses one whose repeated fields exceed the caps (more than max(500, max_transactions_per_block) transactions or transaction ids; more than 65,536 published receipts, spine public keys, spine manifests or spine refusals): "GoProtoToBlock: oversized repeated field (anti-amplification)", the batch not held.

How to compute it. As stated; ceil(2n/3) = (2n + 2) div 3. Node-local: T2 fires on any hash mismatch at a held height, including one caused by our own stale candidate (§3 settles it), and with no difficulty answer at all the source is chosen by height alone.

Rule activation. None.

Rejections and errors. Local; the loop returns and retries on the next tick.

Vector. computed:

Input Expected output
stale tip, 7 registered answers: 5 answer (12471, "11882449964"), 2 answer (12300, "11711449964"), our height 12,000 quorum: 5 ≥ ceil(14/3) = 5 → sync source = one of the 5 peers answering 12,471
stale tip, 7 answers: 4 report one tip, 3 another no quorum (4 < 5): stay with the heaviest answer
stale tip, 2 answers, both the same tip no quorum (fewer than 3 answers)
a batch of 50 ids whose 20th block fails to apply the pass ends with the cursor on the 19th; the next pass asks again from our tip

Test cases · §2

5 cases · 5 valid · 1 reference

Stale tip, 7 answers: 5 report one tip24-2-quorumvalid

Loading the test widget…

Stale tip, 7 answers split 4 and 324-2-no-quorumvalid

Loading the test widget…

Stale tip, 2 answers on the same tip24-2-too-fewvalid

Loading the test widget…

A key answering twice counts once24-2-one-vote-per-keyvalid

Loading the test widget…

A batch of 50 ids whose 20th block fails to apply24-2-cursorvalidreference

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

cursor
the 19th block
next pass
asks again from our tip

Defects to match. None.

3. Fork resolution

Purpose. Replacing our branch by a peer's when the peer's is heavier, or declaring the node wedged when the network left it beyond reach.

Inputs. The peer (the feeder) and the trigger block; max_rollback_height (testnet 720, devnet 60; compiled 720); the finalized height (rule checkpoint_finality: the reference height of the newest spine block checked against this node's main chain, 25); the newest spine block (its spine height, the main chain height and main chain block hash it names); the constants: common-block trials 10, consecutive RPC errors 145, retry back-off 500 ms doubling to 30 s, download segment 10 blocks with 3 tries, page size 100 ids, SAFE_BLOCK_GAP 720, bootstrap threshold 100, the fetch cap 2 × max_rollback_height + 100 blocks, the attempt budget max(120, 15 × ceil((2 × max_rollback_height + 100) / 100)) seconds.

Output and effect. One resolution runs at a time. Steps:

  1. Common block. Genesis when the trigger block's height is 1. Otherwise the milestone of §4 (none → the feeder is charged a bad block, "No common block found - possibly different blockchain"), then the walk to the split point (§4): the last block both chains hold. A feeder with nothing past what we share → "Peer has no new blocks".
  2. Reach, before any download. depth = our tip height − common height. The split is out of reach when depth > max_rollback_height, or when the common block is below the finalized height. Out of reach, the registered peers are asked about the branch's first block (§5, the milestone poll) for the log only; the decision is the reach judgement:
    • the spine side: the newest spine block, when its reference height is above the common height, names a main chain block; our block at that reference height has that hash → ours; our chain reaches that height with a different hash → theirs; our chain does not reach it, or no such spine block → unknown;
    • side theirs → wedge: "Fork rejected: beyond the rollback bound on the branch the spine's checkpoint names (wedge)"; nothing is downloaded; §10 follows;
    • side ours → refused, and the feeder is charged (it serves a branch the spine contradicts); below the floor the text is "Fork rejected: common block C is below the checkpoint floor F (the last co-signed spine reference); the branch was not fetched", otherwise "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);
    • below the floor with side unknown → refused with the floor text;
    • deeper than the limit with side unknown → the branch is fetched and weighed (step 3); when it out-weighs ours it is a wedge ("Fork rejected: beyond the rollback bound on a heavier valid branch (wedge)"), otherwise refused as lighter. Checkpoint evidence. A spine block received by spine sync that carries at least its required signatures (25) and whose reference names a main-chain block this node holds differently is not stored and its feeder is not charged: it is kept as evidence, and this judgement answers theirs for every split whose common block is below the evidence's reference height (the spine side is probed from the newest spine block only for a split at or above it); the evidence is dropped once a newer spine block references a height at or above it.
  3. Fetch and weigh before any rollback. The branch is fetched in pages: GetNextBlockIDs(last id, 100), then the page's blocks by GetNextBlocks in segments of 10 ids. Each page is weighed by one replay of the branch seeded once at the common block and extended page by page (19 §6: every header's signature verified and the chaining checked, the branch's own liveness with the survival flag followed along it (19 §10), its own registry, its skipped smiths, each block's difficulty over the branch's draw set). Fetching stops when the recomputed total is strictly greater than ours. Refusals before any rollback: the branch ends (a page shorter than 100 ids) without exceeding ours → "Fork rejected before rollback: the peer's branch is not heavier than ours"; the fetch cap is reached → "Fork rejected before rollback: branch too long without out-weighing ours"; a page announced and not served → "Fork rejected: the peer announced ids and returned no blocks" (charged); the attempt budget spent → "Fork rejected: attempt budget exceeded (the peer served its branch too slowly)" (charged); a header whose signature fails → "Fork rejected: …" (a proven lie, 28); a branch that does not chain → "Fork rejected: …" (charged a bad block).
  4. The claim. The whole branch is recomputed from the common block. A carried difficulty on the branch's last block that differs from the recomputation is a false claim: a proven lie when the replay could mirror every registry change of the branch, otherwise the branch is unweighable here (refused "Fork rejected: unweighable here: …", no charge; when the spine side is theirs the node is wedged, when ours the feeder is charged). A recomputed weight lighter than ours → "Fork rejected before rollback: …".
  5. Milestone poll (§5) unless the common block is below height 100: fail → "Fork rejected: common milestone not confirmed by multiple peers".
  6. The depth is checked again against max_rollback_height with the reach judgement of step 2.
  7. Pop off. The pool is backed up (every pooled transaction undone, 04), our blocks above the common block are popped (§6; a floor refusal there reads as "Fork rejected: …"), the registry and scramble caches above the common height are refreshed (local).
  8. Apply. Each fork block in order (one whose id equals the common block's is skipped) is validated against the current tip (19 §2), its difficulty recomputed, and applied (19 §4, no broadcast). The loop stops at the first block that:
    • fails validation with "InvalidReceiptBlockHash:<h>", h below the common height: our hash at h is checked with the registered peers (§5, hash verification); when they confirm ours the block's blocksmith is a proven liar, the feeder charged, and the outcome is "Fork rejected: a block carries a receipt contradicting the registered majority's history"; otherwise a deeper rollback to h − 1 is flagged (§8) when tip − (h − 1) ≤ max_rollback_height and h − 1 is not below the finalized height, else "Fork rejected: historical divergence beyond the rollback bound" (charged); a finalized height that cannot be read stops the loop as a local fault (no charge; the prefix applied so far is weighed like a partial switch);
    • fails validation otherwise: the feeder is charged a bad block, except for a text containing timestamp (attributed to the local clock) and for a block 1 refused for its blocksmith or timing;
    • claims a round that has not opened on our clock;
    • fails to apply: "DuplicateTransaction" on a block we hold with the same hash counts as applied and the loop continues; "Block at current height…" (a tip conflict) stops without a charge; any other failure charges the feeder only when every node computes it (a validation refusal, or a deterministic executor verdict); a local fault (a lock, storage) does not.
  9. Decision. d = the tie-broken comparison (§1) of the new tip against the old tip. With at least one block applied:
    • d < 0 → the applied blocks are popped again and ours restored: "Fork rejected after comparison: lower difficulty than ours" (or "… equal weight and our tip hash is lower (rule fork_tie_by_hash)");
    • d ≥ 0 → confirmation: a hash tie needs none; below height 100 (the new tip) the weight alone; otherwise the fork poll (§5). Confirmed → the branch is kept. Not confirmed → popped again, ours restored: "Fork rejected after comparison: not confirmed by the registered peers". A kept branch that applied fewer blocks than the feeder served (the common block excluded) is partial: it stays as our chain (a valid heavier prefix is a legitimate state), the resolution reports it, and the feeder is skipped once as sync source so the rest comes from another peer (§2).
  10. Restore (nothing kept): unless bootstrap, our popped blocks are checked against the registered peers' hashes (§5); a block the majority rejects is replaced by the version of the heaviest peer; each block is re-validated (the smith check skipped for our own blocks only) and re-applied; a block that no longer validates, or that fails to apply, or a tip that cannot be read, stops the restore as a local fault ("local fault: block H no longer validates: …", "local fault: …"), leaving the node at the last block restored, with the mempool backup restored at once.
  11. Mempool. Transactions of the losing blocks that the winning blocks do not carry are re-admitted when they still apply; the backup of step 7 is restored.

A pop that fails after fork blocks were applied leaves them as the chain (nothing of ours is put on top of foreign blocks) and the resolution stops as a local fault (no charge, no cool-down, not counted toward a wedge); the fault's text says where the chain stands ("… N of M fork blocks stay applied" or "… our chain is restored").

How to compute it. As stated; §1 for every comparison. Node-local: the reference node tells the step-8 cases apart by the refusal texts (InvalidReceiptBlockHash:, timestamp, Block at current height, DuplicateTransaction); an implementation may tell them apart by its own means. A branch of exactly our weight is refused at step 3 (fetching needs strictly heavier), so the lower-hash tie of §1 decides only when an applied prefix ties our weight at step 9. The deeper-rollback flag is acted on only by the health check's investigation (§8), not by the sync loop's triggers. The reach judgement:

below the floor depth > limit spine side branch recomputed heavier verdict
no no any any within reach: steps 3–11
any (out of reach) theirs any wedge
any (out of reach) ours any refused, feeder charged
yes any unknown any refused (floor text)
no yes unknown yes wedge (after fetching)
no yes unknown no refused (lighter)

Rule activation. checkpoint_finality, fork_tie_by_hash, branch_registry_replay (the replay weighs a branch over its own scratch registry, seeded at the common block and advanced with the branch's removals, key rotations and replayed expulsions; a RemoveNodeRegistration, ClaimNodeRegistration or NodeRegistrationUpdate of a node the scratch holds counts only when its envelope is signed by that node's owner account as the scratch holds it: same owner, signature verified over the chain-bound digest of 02, and, under rule eth_signature_canonical_v judged at the branch block's height, an Ethereum- or Tron-typed owner's 65-byte signature ending in 27 or 28; an unsigned or foreign removal or update is not mirrored, which makes a false claim unweighable here at step 4 rather than a proven lie, and a claim not so signed starts no exit), eth_signature_canonical_v, difficulty_draw_set, weight_by_draw_share, late_stamp_priced and survival_mode (the flag of the replay, 19 §10) are active from height 0 on every chain.

Rejections and errors. The quoted strings; "Fork resolution cancelled: shutdown requested". Every refusal whose text begins Fork rejected is a verdict: the feeder enters divergence cool-down (§2). A failure without a verdict (an RPC error before any page, a shutdown, a local fault) puts nobody in cool-down.

Vector. computed:

Input Expected output
max_rollback_height 720 attempt budget max(120, 15 × ceil(1,540 / 100)) = 240 s; fetch cap 1,540 blocks
max_rollback_height 60 attempt budget max(120, 15 × ceil(220 / 100)) = 120 s; fetch cap 220 blocks
devnet, depth 60, not below the floor within reach
devnet, depth 61, the newest spine block names a block we hold differently wedge, nothing downloaded
devnet, depth 61, the newest spine block names our block, recomputed heavier refused "Fork rejected: rollback depth exceeds max_rollback_height limit", feeder charged
devnet, depth 61, no spine block above the split, branch recomputed heavier wedge after fetching
devnet, depth 61, no spine block above the split, branch recomputed lighter "Fork rejected before rollback: the peer's branch is not heavier than ours"
depth 10, common block 900 below finalized height 1,000, side unknown "Fork rejected: common block 900 is below the checkpoint floor 1000 (the last co-signed spine reference); the branch was not fetched"
depth 10, common block 900 below finalized 1,000, side theirs wedge
a 30-block branch that applies 18 blocks, then a block fails execution deterministically; the 18-block prefix out-weighs ours and the fork poll confirms kept, partial (18 of 30), feeder charged a bad block for the failed block and skipped once as sync source
a branch block carrying a RemoveNodeRegistration of a node whose owner is Ethereum-typed, signed by that owner with a 65-byte signature ending in 01 (it verifies) not mirrored: the node stays in the scratch registry (the same signature ending in 1c is mirrored: the node begins its exit at that block)

Test cases · §3

13 cases · 8 valid · 5 invalid · 1 reference

Budget and fetch cap at max_rollback_height 72024-3-budget-720valid

Loading the test widget…

Budget and fetch cap at max_rollback_height 6024-3-budget-60valid

Loading the test widget…

Devnet, depth 60, not below the floor24-3-withinvalid

Loading the test widget…

Devnet, depth 61, the spine block names a block we hold differently24-3-wedge-theirsvalid

Loading the test widget…

Devnet, depth 61, the spine block names our block, recomputed heavier24-3-refused-oursinvalid

Loading the test widget…

Devnet, depth 61, no spine block above the split, branch heavier24-3-wedge-heaviervalid

Loading the test widget…

Devnet, depth 61, no spine block above the split, branch lighter24-3-lighterinvalid

Loading the test widget…

Depth 10, common block 900 below the finalized height 1,00024-3-floorinvalid

Loading the test widget…

The same with the spine block on the peer's side24-3-floor-theirsvalid

Loading the test widget…

A branch block's RemoveNodeRegistration signed by its Ethereum-typed owner, ending in 0124-3-removal-v01invalid

Loading the test widget…

The same removal with the signature ending in 1c (28)24-3-removal-v1cvalid

Loading the test widget…

The same removal of a node the scratch holds under another owner24-3-removal-foreigninvalid

Loading the test widget…

A 30-block branch that applies 18 blocks24-3-partialvalidreference

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

outcome
kept, partial (18 of 30)
feeder
charged a bad block, skipped once as sync source

Defects to match. The reach judgement reads only the newest spine block: an older spine block whose reference lies between the split and our tip is not consulted when the newest one's reference is beyond our tip.

4. Finding the common block (milestones) and the split point

Purpose. Locating the fork point with few round trips, then moving to the real split.

Inputs. Our tip id; the peer's answers to GetCommonMilestoneBlockIDs(last_block_id, last_milestone_id) and GetNextBlockIDs(id, 100) (27, chain sync queries); SAFE_BLOCK_GAP 720.

Output and effect. Server side (what an implementation answers): both ids 0 → INVALID_ARGUMENT "either LastBlockID or LastMilestoneBlockID has to be supplied". When last_block_id is a block it holds on its main chain → [last_block_id], Last = whether it is the tip. Otherwise a descending list of at most 10 ids: start height = the milestone's height when last_milestone_id is given (a milestone it does not hold → INTERNAL "failedGetLastMilestoneBlock"), else its own tip; step jump = min(720, max(tip, 1)) when a milestone was given, else 10; at each step the id of the block at that height is appended, then the height decreases by jump, clamped to 0; height 0 is appended and ends the list; a height it does not hold → INTERNAL "failedGetBlocks"; Last is false. Client side: up to 10 trials; each answer's ids are checked in order against our main chain, an id already seen skipped; the first id we hold is the milestone; every id we do not hold becomes last_milestone_id for the next trial; when the only id seen so far is the last milestone the search ends "not found"; up to 145 consecutive RPC errors are retried with the back-off of §3. After 10 trials → "No common block found - possibly different blockchain".

The walk to the split point. From the milestone, page through the peer's GetNextBlockIDs(id, 100), at most (720 + 100) div 100 + 2 = 10 pages: for each id in order, the block we hold with that id must sit at the next height (else the walk fails: "the peer's block ids do not follow our chain after height H", and the milestone stays the common block); the first id we do not hold is the branch's first block and its parent the common block; a page shorter than 100 ids ends the walk (the peer's chain is a prefix of ours: nothing differs → "Peer has no new blocks"); running out of pages keeps the last block reached. Node-local: the milestone can lie up to 720 blocks below the real split; the walk repairs it, within its 10 pages.

How to compute it. As stated. Block ids are the signed little-endian 64-bit value of the first 8 bytes of the block hash (05 §4).

Rule activation. None.

Rejections and errors. As listed.

Vector. computed (four block hashes and the ids derived from them):

Block Hash Id
12,399 f8bde70949a02d92d9340816449928ee99b6ea53d5729735dd3f3951e15c0086 −7,913,492,734,660,854,280
12,400 42cfa11fce0acdbebfcb649a2934dffcaecc032789259024db35146ce1881c52 −4,698,086,955,867,320,510
12,401 bef5277d8fa56e64fa435c29373f64312c3ccf2e2fab969110ba36dfd55ad4ae 7,236,903,686,929,642,942
12,402 6dfc8283998a7fe02d09bf10856f32f65feb56c8cdc05ac9858e2eccdc38549e −2,269,943,295,230,411,667
Input Expected output
GetNextBlockIDs(−7913492734660854280, 3) on a chain holding those four blocks at 12,399 … 12,402 [−4698086955867320510, 7236903686929642942, −2269943295230411667]
milestone request, server tip 12,471, our tip id unknown to it, no milestone ids of heights 12,471, 12,461, 12,451, 12,441, 12,431, 12,421, 12,411, 12,401, 12,391, 12,381
the same with last_milestone_id = id(12,381) ids of 12,381, 11,661, 10,941, 10,221, 9,501, 8,781, 8,061, 7,341, 6,621, 5,901
server tip 25, no milestone ids of 25, 15, 5, 0
both ids 0 INVALID_ARGUMENT "either LastBlockID or LastMilestoneBlockID has to be supplied"
walk: milestone 12,381, we hold the peer's ids up to 12,410, the next id unknown to us common block 12,410, first fork block = that id

Test cases · §4

8 cases · 7 valid · 1 invalid · 1 reference

Block ids of the blocks at 12,399 to 12,40224-4-idsvalid

Loading the test widget…

GetNextBlockIDs(id of 12,399, 3) on a chain holding the four blocks at 12,399 to 12,40224-4-next-idsvalid

Loading the test widget…

GetNextBlockIDs for an id the server does not hold24-4-next-ids-unknownvalid

Loading the test widget…

Server tip 12,471, our tip unknown to it, no milestone24-4-no-milestonevalid

Loading the test widget…

The same with the milestone at 12,38124-4-milestonevalid

Loading the test widget…

Server tip 25, no milestone24-4-short-chainvalid

Loading the test widget…

Both ids 024-4-both-zeroinvalid

Loading the test widget…

The walk from milestone 12,381 to the split24-4-walkvalidreference

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

common
12410
first_fork_block
the peer's next id

Defects to match. None.

5. The peer polls

Purpose. The three places other registered peers are asked before a branch is adopted or our own is restored.

Inputs. The connected registered peers; GetNextBlockIDs, GetCumulativeDifficulty, GetBlockHashes (27); MIN_PEERS_FOR_CONFIRMATION 3, MAX_PEERS_FOR_CONFIRMATION 5, CONFIRMATION_THRESHOLD 0.66.

Output and effect. Voters: the connected registered peers, one per node key, never the feeder, shuffled, at most 5. Milestone poll (§3 steps 2 and 5): fewer than 3 voters → pass. Each voter is asked for 10 ids after the common block: no answer or an empty list abstains; a first id equal to the branch's first block confirms; another first id disagrees, and is heavy when that voter's difficulty is ≥ the branch's (recomputed when known, else claimed) weight. A heavy disagreement that no second voter shares on the same competing first block is probed: its first page is fetched and weighed, and a claim its own blocks refute is a proven lie. Verdict: confirmations ≥ 3 → pass; else at least one answer and no competing first block with two or more heavy voters → pass; else ≥ 3 answers → fail; else at least one confirmation → pass; else fail. Fork poll (§3 step 9): fewer than 3 voters, or fewer than 3 answers → pass iff the new tip is strictly heavier than the old; otherwise a voter votes for when its difficulty ≥ the fork's and > ours, against when ≥ ours and < the fork's, else abstains; no for/against vote → fail; pass iff for / (for + against) ≥ 0.66. Hash verification (§3 steps 8 and 10): the first 5 connected registered peers are asked GetBlockHashes(start, end); fewer than 3 registered peers or fewer than 3 answers → not available; per height the hash most peers report is the consensus; our block is verified when it is the consensus, or when at least 2 peers report ours and they are more than half of the answers for that height. Replacement blocks come from the registered peer with the greatest difficulty above ours (GetNextBlockIDs from the block below the lowest mismatch, then GetNextBlocks). Node-local: voter sampling is random, so two nodes in the same situation may decide differently, and the milestone poll passes with a single confirmation when fewer than 3 voters answer.

How to compute it. As stated.

Rule activation. None.

Rejections and errors. As stated.

Vector. computed:

Input Expected output
fork poll: 5 answers, 3 for, 1 against, 1 abstaining 3 / 4 = 75 % ≥ 66 % → confirmed
fork poll: 2 for, 1 against 66.7 % → confirmed
fork poll: 1 for, 1 against 50 % → rejected
fork poll: 2 voters only, new tip "11811449964", old "11810449964" strictly heavier → confirmed
milestone poll: 4 answers, 1 confirms, 3 disagree on 3 different first blocks, each heavy no head with two heavy voters → pass
milestone poll: 4 answers, 0 confirm, 2 heavy on the same first block ≥ 3 answers and a heavy head → fail
hash verification at one height: peers report A, A, B; ours is B consensus A; 1 peer agrees with us → not verified

Test cases · §5

8 cases · 8 valid

Fork poll: 3 for, 1 against, 1 abstaining24-5-fork-3-1-1valid

Loading the test widget…

Fork poll: 2 for, 1 against24-5-fork-2-1valid

Loading the test widget…

Fork poll: 1 for, 1 against24-5-fork-1-1valid

Loading the test widget…

Fork poll with 2 voters only24-5-fork-two-votersvalid

Loading the test widget…

Milestone poll: 1 confirms, 3 disagree on 3 different heavy heads24-5-milestone-passvalid

Loading the test widget…

Milestone poll: none confirms, 2 heavy on one head24-5-milestone-failvalid

Loading the test widget…

Milestone poll with fewer than 3 voters24-5-milestone-fewvalid

Loading the test widget…

Hash verification: peers report A, A, B; ours is B24-5-hash-verifyvalid

Loading the test widget…

Defects to match. None.

6. Rollback: popping blocks and restoring state

Purpose. What the node's state is after popping off to a block: exactly the state after that block, as if nothing above it had been applied.

Inputs. The target block (height t, id); the state; the finalized height.

Output and effect. Refusals first: a target above the tip → "PopOffToBlock: Target block height exceeds current height"; a target at the tip's height with another id → "PopOffToBlock: Target and current at same height but different block IDs"; a target at the tip with the same id → nothing to pop; under checkpoint_finality a target below the finalized height → "PopOffToBlock: target T is below the finalized height F (rule checkpoint_finality)" (a floor that cannot be read refuses the pop as a local fault). Then, in one database transaction:

  1. For each block from the tip down to t + 1: its coinbase ledger rows (account ledger rows at that block height with event type 8 or 74) are deleted; for each of its transactions, last to first, the account ledger rows carrying that transaction's id are deleted; the block's transactions and the block row itself are deleted. Popped blocks are kept in memory, returned in ascending height.
  2. The block reached must be the target, same height and same id, else "Target block ID mismatch - different chain?".
  3. Every table that records state by height is cut back to t (below). For a versioned table (one row per change, the newest row per key marked latest = 1, 07 §2): every row whose height is above t is deleted, then latest is cleared everywhere and set again on the row with the greatest height at or below t for each key. For an append-only table: every row whose height is above t is deleted.
  4. The pop commits. Only then does the readiness gate forget any effective height above t + 1 (29): the decision for h* is made when block h* − 1 is applied, so a pop that keeps block h* − 1 keeps the decision and its row, and one that pops it deletes the row (below) and re-decides on the way up; a pop whose transaction fails leaves the gate exactly as it was (the chain still runs the bundle). Then the node's caches above t (registry, scramble, balance) are refreshed.

A failed step undoes the whole transaction and the chain is unchanged; a table this node never created is skipped (it holds nothing to roll back).

Table Height column Kind and key (the newest row per key at or below t becomes latest)
main_block, zbc_transaction — deleted per popped block (step 1)
account_ledger block_height append-only (per transaction and per coinbase in step 1, then every row above t)
account_balance block_height versioned by account_address; then every latest row's spendable_balance is set equal to its balance (unconfirmed reservations cleared; the pool's backup re-applies them, 04)
participation_score height versioned by node_id
participation_score_ledger, skipped_blocksmith block_height append-only
node_liveness height versioned by node_id
survival_state height append-only (one row per height, 19 §10)
node_registry height versioned by id
node_registry_ledger block_height append-only
queue_state height versioned by node_id
queue_attendance, liveness_expulsion, lock_release, node_claim, node_exit, seat_change, roll_call, rule_activation_record, equivocation_charge, score_unit_clock, storage_missing, storage_unconfirmed height append-only
account_dataset height versioned by (setter_account_address, recipient_account_address, property)
account_split_policy block_height versioned by account_address
account_group / account_group_member block_height versioned by group_address / member_address
dataset_object height versioned by object_id
dataset_delete_vote height versioned by (object_id, voter_address)
liquid_payment_transaction, escrow_transaction, swap_offer, market, order_book, app, escrow_request block_height versioned by id
app_settlement block_height versioned by app_id
trade block_height append-only
token block_height versioned by token_id
account_token_balance block_height versioned by (account_address, token_id)
network_topology period_height append-only (scrambles of periods above t)
trigger_schedule block_height versioned by trigger_id
oracle_attestation block_height versioned by (event_id, attester): a replaced attestation stands again
oracle_result resolved_height append-only
bridge_withdrawal_request block_height versioned by trigger_hash (34)
readiness_bundle_decision height versioned by bundle_id (29; present only once the gate wrote a row)
release_authority block_height versioned by id
release_registry block_height versioned by version
gateway_registry block_height versioned by gateway_key
archival_registry block_height versioned by node_public_key
relay_registry block_height versioned by relay_key
longevity block_height versioned by target_tx_id
longevity_funder block_height versioned by (target_tx_id, funder_address)
longevity_deposit block_height versioned by (target_tx_id, seq)
file_deposit block_height versioned by (object_id, seq)
longevity_vote block_height versioned by (target_tx_id, voter_address)
stored_file block_height versioned by file_root
storage_proof, account_transaction_index, published_receipt, merkle_tree, fee_vote_commitment_vote, fee_vote_reveal_vote, eth_tx_hash, spent_foreign_message block_height append-only
fee_scale block_height versioned singleton: the row(s) at the greatest height at or below t become latest
node_admission_timestamp block_height a single timer, one row per height (key block_height): the newest row at or below t becomes latest
node_receipt reference_block_height append-only (receipts referencing blocks above t)
pending_transaction block_height versioned by transaction_hash
pending_signature block_height versioned by (account_address, transaction_hash)
multisignature_info, multisignature_participant block_height versioned by multisig_address
consensus_parameters — restored from consensus_parameter_change: its rows above t, newest first (by row id), each put back (had_row 1 → the parameter row is set to old_value; 0 → the parameter row is removed); then those change rows are deleted

Not rolled back: the node-local producer_signed_parent table (20 §4).

How to compute it. As stated. An implementation with its own storage must end in the same observable state: the state after block t, every unconfirmed reservation cleared.

Rule activation. None.

Rejections and errors. As listed; "Derived tables rollback failed: …", "Node registry rollback failed: …", "Participation score rollback failed: …" undo the pop.

Vector. computed:

Input Expected output
account_balance rows of account A: heights 10 (balance 100), 15 (balance 80), 20 (balance 50, latest); pop to t = 17 the height-20 row is deleted; the height-15 row is latest, balance 80, spendable_balance 80
token rows of token X: only one, at height 18; pop to 17 the row is deleted; token X does not exist
published_receipt rows at heights 16, 17, 18; pop to 17 the height-18 row is deleted
survival_state rows (16, true), (17, true), (18, false); pop to 17 (18, false) is deleted; the flag of 17 stands
consensus_parameter_change rows above 17: id 7 (min_fee, had_row 1, old 2,500,000), id 9 (min_fee, had_row 1, old 3,000,000) id 9 then id 7 applied: min_fee = 2,500,000; both change rows deleted
pop to a target 5 blocks below a finalized height of 1,000 (target 995) "PopOffToBlock: target 995 is below the finalized height 1000 (rule checkpoint_finality)"; nothing changes
readiness_bundle_decision row (602, effective 5,001, height 5,000); pop to 5,000 the row stays and bundle 602 keeps effective height 5,001; pop to 4,999 → the row is deleted and the gate holds the bundle until a block re-decides it

Test cases · §6

10 cases · 7 valid · 3 invalid

account_balance rows of A at 10, 15, 20; pop to 1724-6-balancevalid

Loading the test widget…

A token whose only row is at 18; pop to 1724-6-tokenvalid

Loading the test widget…

published_receipt rows at 16, 17, 18; pop to 1724-6-receiptsvalid

Loading the test widget…

survival_state rows (16, true), (17, true), (18, false); pop to 1724-6-survivalvalid

Loading the test widget…

consensus_parameter_change rows 7 and 9 of min_fee above 1724-6-paramsvalid

Loading the test widget…

A readiness_bundle_decision row (602, effective 5,001, height 5,000); pop to 5,00024-6-decision-keptvalid

Loading the test widget…

The same row; pop to 4,99924-6-decision-poppedvalid

Loading the test widget…

A pop to 995 below the finalized height 1,00024-6-finalizedinvalid

Loading the test widget…

A target above the tip24-6-above-tipinvalid

Loading the test widget…

A target at the tip's height with another id24-6-same-heightinvalid

Loading the test widget…

Defects to match. (1) Every row created above t vanishes entirely: an account whose first row was above t is unknown after the rollback. (2) Popped blocks are deleted, never kept as a side branch.

7. The candidate pool and the selection loop

Purpose. Holding the competing blocks for the next height and applying the right one.

Inputs. Candidates from the node's own production, its pre-generated block for the next height, and peers' BroadcastBlockCandidate messages; the previous block; the selectable set (20 §1); the local clock.

Output and effect. Admission, the bounds and the choice are 19 §5. The selection loop runs about once a second: it holds while the node is syncing behind its peers, while its clock is skewed, or while it is wedged (§10); otherwise, when some candidate's selectable window (the persist window for round position + 1 of 20 §2, opened 5 s later for rounds 2 and above, 19 §5) contains the current time, the lowest-position candidate in its window (ties: the earlier block timestamp) is validated in full against the tip (19 §2; one that fails is removed and the next best tried, at most 64 tries) and applied with broadcast; on success the pool is cleared up to that height, the scramble updated, and a registered node pre-generates its candidate for the next height (20 §4). Node-local: selection is clock-driven, so two nodes with skewed clocks can apply different candidates for a moment, and §3 settles it.

How to compute it. As stated.

Rule activation. None.

Rejections and errors. The peer answer "Candidate rejected"; silent otherwise.

Vector. computed: two candidates for height H, positions 0 and 1, block H − 1 stamped P; the selectable windows are [P + 8, P + 22) and [P + 28, P + 37) and never overlap. Clock P + 15 → position 0 is applied; clock P + 25 → nothing; clock P + 30 (position 0 not applied) → position 1 is applied. A position-0 candidate that fails the full validation at P + 15 is removed and nothing else is applied in that pass (position 1 is not yet selectable); position 1 is applied once its window opens at P + 28.

Test cases · §7

5 cases · 5 valid

Two candidates, the clock in position 0's window24-7-position-0valid

Loading the test widget…

Between the two windows nothing is selected24-7-betweenvalid

Loading the test widget…

Position 0's window has closed24-7-position-1valid

Loading the test widget…

After a failing position-0 candidate is removed at P + 15, the pass selects nothing more24-7-fails-passvalid

Loading the test widget…

Position 1 is applied once its window opens24-7-fails-latervalid

Loading the test widget…

Defects to match. None.

8. Health check, investigation and deeper rollback

Purpose. Catching a divergence the sync loop missed.

Inputs. Every 30 s (or at once when an investigation is pending, §2), unless a resolution ran within 120 s and only when our height is above 10: the tip states of up to 5 peers; HEIGHT_DIFFERENCE_THRESHOLD 10; HEALTH_CHECK_AGREEMENT_THRESHOLD 0.6.

Output and effect. With at least 2 answers: ahead = answers more than 10 blocks above us, heavier = answers with a greater difficulty. Resolution (§3) against the heaviest answer starts when heavier / answers ≥ 0.6 and ahead / answers ≥ 0.6, or, with an investigation pending, when heavier / answers ≥ 0.5. When that resolution flagged a deeper rollback (§3 step 8) the node pops to the flagged height through the same guarded pop (mempool backed up and restored) and resolves again; if the second resolution fails our popped blocks are re-applied. A local fault is not recorded as a resolution outcome. Node-local: the thresholds count responders, not the registry, so three answering peers on a minority branch can drag a node into a resolution, which §3 then judges on weight.

How to compute it. As stated.

Rule activation. None.

Rejections and errors. Local.

Vector. computed:

Input Expected output
5 answers: 3 heavier, 3 ahead 60 % / 60 % → resolve
5 answers: 3 heavier, 2 ahead, nothing pending no
the same with an investigation pending 60 % ≥ 50 % → resolve
1 answer no (fewer than 2)

Test cases · §8

4 cases · 4 valid

5 answers: 3 heavier, 3 ahead24-8-resolvevalid

Loading the test widget…

5 answers: 3 heavier, 2 ahead, nothing pending24-8-novalid

Loading the test widget…

The same with an investigation pending24-8-pendingvalid

Loading the test widget…

1 answer24-8-onevalid

Loading the test widget…

Defects to match. None.

9. The incomplete-block queue

Purpose. Completing a block announced with transaction ids only.

Inputs. A block whose TransactionIDs are given but whose transactions are empty; the pool; the chain; queue size 100; TIMEOUT_BLOCK_WAITING_TRANSACTIONS 120 s (checked every 30 s).

Output and effect. Before any lookup (19 §1): with the parent held, the copy's header, signature and recomputed difficulty must hold, else it is dropped; with the parent not held it is dropped unless its sender is bound to a registered key and the queue has room. Then each id is resolved from the pool, the rest from the chain — a transaction applied below the block's height makes the block a refused double-spend (handled, not queued); one applied at or above it is taken as a possible fork and allowed. With ids still missing: a full queue drops the block; else it is queued with its missing ids and their positions, the ids are requested from the blocksmith's known address and up to the request limit of connected registered peers (RequestBlockTransactions, 27), and a receipt is answered early (23 §2) only when the header passes 19 §2 step 5, the signature verifies and the carried hash equals SHA3-256(header ‖ signature). Every transaction that later arrives fills its position in every queued block needing it; a block with nothing missing leaves the queue and is processed as if received whole, its sender charged as the original sender. Blocks older than 120 s are dropped.

How to compute it. As stated; a transaction's id is the one derived from its hash (03).

Rule activation. None.

Rejections and errors. Silent drops. Node-local: a block dropped because the queue is full is answered as handled; the sender learns nothing.

Vector. computed: a block of 3 ids, two in the pool and one unknown → queued with one missing id at position 2; the transaction arrives 40 s later → the block is complete and validated; had it not arrived within 120 s the block would have been dropped.

Test cases · §9

1 case · 1 valid · 1 reference

A block of 3 ids, one unknown24-9-queuevalidreference

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

queued
one missing id at position 2
arrives after 40 s
complete and validated
not within 120 s
dropped

Defects to match. None.

10. The wedge: declaration, in-place rebuild, resync marker

Purpose. What a node does when rolling back can no longer rejoin the network.

Inputs. The wedge verdicts of §3 (steps 2, 3 and 4: signed evidence only); every resolution outcome of the sync loop and the health check (success or failure, peer, our height, wall time); auto_resync in node.conf (default true, 30); the in-place recovery's backoff 120 s.

Output and effect.

  • A wedge verdict (§3): the node first tries to rebuild in place from a spine-attested snapshot (26 §5–§8: the newest sync point the spine attests, its snapshot downloaded, attested and applied, replacing every non-genesis row, then the catch-up to the peer's height). At most one attempt per 120 s. Before the snapshot's rows are restored the rebuild deletes every transaction row and side-index row the node holds (zbc_transaction, account_ledger, account_transaction_index, eth_tx_hash, merkle_tree, node_receipt: every row whose height, or reference height, is not 0), so the dead branch's transactions and receipts do not survive it; the snapshot's own transactions are restored after. Success: the wedge is cleared, the feeder's cool-down cleared, production continues. Failure, backoff, or no spine: the wedge is declared: the reason is reported once, the node stops producing on its branch, and with auto_resync on it writes the resync marker (RESYNC_REQUIRED beside its database, with the reason) and exits, so the next start discards the local chain and rebuilds it by spine fast-sync (26, 30); with it off an operator re-runs the installer.
  • The streak detector records every outcome that is not a local fault: a success clears the streak; a failure extends it. A streak of at least 10 failures, all at one height, spanning at least 1,800 s, against at least 2 distinct peers, is reported in the log. It never declares a wedge by itself: the node's wedge reason, and so the resync marker, come only from a wedge verdict on signed evidence (§3); a streak without such a verdict is log only.

How to compute it. As stated.

Rule activation. None.

Rejections and errors. None.

Vector. computed:

Input Expected output
10 failures at height 134,583 against two peers, the first at 03:01:00 and the last at 03:35:00 UTC (2,040 s), no wedge verdict streak reported in the log; no wedge reason, no marker
10 failures within 20 minutes nothing (window < 1,800 s)
9 failures, then a success streak cleared
a §3 wedge, recovery succeeds rebuilt in place, production continues
a §3 wedge, recovery attempted 60 s ago in backoff → declared; with auto_resync on: marker written, node exits

Test cases · §10

5 cases · 5 valid · 1 reference

10 failures at height 134,583 against two peers over 2,040 s, no wedge verdict24-10-streakvalid

Loading the test widget…

The same streak after a wedge verdict on signed evidence24-10-streak-verdictvalid

Loading the test widget…

10 failures within 20 minutes24-10-shortvalid

Loading the test widget…

9 failures, then a success24-10-clearedvalid

Loading the test widget…

A wedge: recovered in place, or declared in backoff24-10-recoveryvalidreference

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

recovery succeeds
rebuilt in place
recovery 60 s ago
declared; with auto_resync a marker is written and the node exits

Defects to match. None.

11. Consensus and local

Consensus: §1 (the comparison and the hash tie-break), the reach limits of §3 (the rollback bound and the finality floor as limits on what a node will ever adopt by rolling back), the branch-replayed weight (19 §6, 20 §6), §6 (the state after a rollback must equal the state after block t, every table included). Local: every poll, sample, threshold and timer of §2, §5, §7–§10, the choice of sync source, the mempool handling, the substring matching of §3, the milestone server's step sizes (an answer with other milestones is still a valid answer), and the wedge recovery. Two nodes that follow the same consensus rules but different local policies end on the same chain once connected to an honest majority.

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