On this page
- §0 The area in one paragraph
- 1. Cumulative difficulty and its comparison
- 2. The sync loop, the sync source and the fork triggers
- 3. Fork resolution
- 4. Finding the common block (milestones) and the split point
- 5. The peer polls
- 6. Rollback: popping blocks and restoring state
- 7. The candidate pool and the selection loop
- 8. Health check, investigation and deeper rollback
- 9. The incomplete-block queue
- 10. The wedge: declaration, in-place rebuild, resync marker
- 11. Consensus and local
24 — Fork choice and sync
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.
- If both strings are empty → 0; if
ais empty → −1; ifbis empty → 1. - Strip leading
0characters from each, leaving one character if all were zeros. - A longer string → 1 for it; equal lengths → the first differing character decides.
- 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")
Loading the test widget…
Compare("99999999999", "100000000000")
Loading the test widget…
Compare("", "0")
Loading the test widget…
Compare("007", "7")
Loading the test widget…
Equal weights: the branch's tip hash is lower
Loading the test widget…
Equal weights: our tip hash is lower
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 leastceil(2n/3)of thenanswers 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)andGetNextBlocks(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_FOUNDfor 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, elseINVALID_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).GetNextBlockIDsandGetNextBlocks(withRequestBlockTransactions) 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 eitherRESOURCE_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 tip
Loading the test widget…
Stale tip, 7 answers split 4 and 3
Loading the test widget…
Stale tip, 2 answers on the same tip
Loading the test widget…
A key answering twice counts once
Loading the test widget…
A batch of 50 ids whose 20th block fails to apply
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:
- 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". - Reach, before any download.
depth = our tip height − common height. The split is out of reach whendepth > 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.
- Fetch and weigh before any rollback. The branch is fetched in pages:
GetNextBlockIDs(last id, 100), then the page's blocks byGetNextBlocksin 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). - 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: …". - Milestone poll (§5) unless the common block is below height 100: fail →
"Fork rejected: common milestone not confirmed by multiple peers". - The depth is checked again against
max_rollback_heightwith the reach judgement of step 2. - 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). - 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>",hbelow the common height: our hash athis 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 toh − 1is flagged (§8) whentip − (h − 1) ≤ max_rollback_heightandh − 1is 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.
- fails validation with
- 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).
- 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. - 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 720
Loading the test widget…
Budget and fetch cap at max_rollback_height 60
Loading the test widget…
Devnet, depth 60, not below the floor
Loading the test widget…
Devnet, depth 61, the spine block names a block we hold differently
Loading the test widget…
Devnet, depth 61, the spine block names our block, recomputed heavier
Loading the test widget…
Devnet, depth 61, no spine block above the split, branch heavier
Loading the test widget…
Devnet, depth 61, no spine block above the split, branch lighter
Loading the test widget…
Depth 10, common block 900 below the finalized height 1,000
Loading the test widget…
The same with the spine block on the peer's side
Loading the test widget…
A branch block's RemoveNodeRegistration signed by its Ethereum-typed owner, ending in 01
Loading the test widget…
The same removal with the signature ending in 1c (28)
Loading the test widget…
The same removal of a node the scratch holds under another owner
Loading the test widget…
A 30-block branch that applies 18 blocks
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,402
Loading the test widget…
GetNextBlockIDs(id of 12,399, 3) on a chain holding the four blocks at 12,399 to 12,402
Loading the test widget…
GetNextBlockIDs for an id the server does not hold
Loading the test widget…
Server tip 12,471, our tip unknown to it, no milestone
Loading the test widget…
The same with the milestone at 12,381
Loading the test widget…
Server tip 25, no milestone
Loading the test widget…
Both ids 0
Loading the test widget…
The walk from milestone 12,381 to the split
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 abstaining
Loading the test widget…
Fork poll: 2 for, 1 against
Loading the test widget…
Fork poll: 1 for, 1 against
Loading the test widget…
Fork poll with 2 voters only
Loading the test widget…
Milestone poll: 1 confirms, 3 disagree on 3 different heavy heads
Loading the test widget…
Milestone poll: none confirms, 2 heavy on one head
Loading the test widget…
Milestone poll with fewer than 3 voters
Loading the test widget…
Hash verification: peers report A, A, B; ours is B
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:
- 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. - The block reached must be the target, same height and same id, else
"Target block ID mismatch - different chain?". - 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 markedlatest = 1,07§2): every row whose height is abovetis deleted, thenlatestis cleared everywhere and set again on the row with the greatest height at or belowtfor each key. For an append-only table: every row whose height is abovetis deleted. - 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 abovet(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 17
Loading the test widget…
A token whose only row is at 18; pop to 17
Loading the test widget…
published_receipt rows at 16, 17, 18; pop to 17
Loading the test widget…
survival_state rows (16, true), (17, true), (18, false); pop to 17
Loading the test widget…
consensus_parameter_change rows 7 and 9 of min_fee above 17
Loading the test widget…
A readiness_bundle_decision row (602, effective 5,001, height 5,000); pop to 5,000
Loading the test widget…
The same row; pop to 4,999
Loading the test widget…
A pop to 995 below the finalized height 1,000
Loading the test widget…
A target above the tip
Loading the test widget…
A target at the tip's height with another id
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 window
Loading the test widget…
Between the two windows nothing is selected
Loading the test widget…
Position 0's window has closed
Loading the test widget…
After a failing position-0 candidate is removed at P + 15, the pass selects nothing more
Loading the test widget…
Position 1 is applied once its window opens
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 ahead
Loading the test widget…
5 answers: 3 heavier, 2 ahead, nothing pending
Loading the test widget…
The same with an investigation pending
Loading the test widget…
1 answer
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 unknown
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 withauto_resyncon it writes the resync marker (RESYNC_REQUIREDbeside 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 verdict
Loading the test widget…
The same streak after a wedge verdict on signed evidence
Loading the test widget…
10 failures within 20 minutes
Loading the test widget…
9 failures, then a success
Loading the test widget…
A wedge: recovered in place, or declared in backoff
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.