On this page
- §0 The area in one paragraph
- 1. The spine block
- 2. The payload hash
- 3. Public-key changes and the spine signers
- 4. Manifests
- 5. Production: timing, the spine blocksmith selection and the weight
- 6. The required spine signatures and the aggregate signature
- 6a. How a registered node decides to give its spine signature, and the signing commitment
- 6b. Non-signing statements and the non-signing round
- 6c. A late spine block
- 7. Validation and application of a received spine block
- 8. Sync and fork choice on the spine
- 9. Chain identity, the finalized height, the pin and the hierarchy
- 10. Data model, and the consensus/local split
25 — The spine chain
Out of scope the snapshot file a manifest names, its chunks and the fast sync that consumes it (26); the header bytes, hash and id, which the spine reuses from the main chain (05 §2–§4); the gRPC transport and the message layouts (27); the duty transaction SpineEquivocationReport (type 62) that charges a registered node for voting both ways on one spine block candidate (35)
§0 The area in one paragraph
The spine is a second, slow chain that every node of a main chain keeps beside it: one block
per spine_smithing_period (TestNet 86,400 s, DevNet 3,600 s), built by a spine blocksmith
drawn from the spine signers with a hash of the seed of the main chain block at the previous
spine block's reference height. A spine block carries no transactions but two kinds of payload —
public-key changes (which main-chain nodes joined or left the registry since the previous spine
block) and snapshot manifests (the hash, chunk hashes, reference height, expiry and chain
identity of a state snapshot a node can download instead of replaying history) — and carries
spine signatures, at least the required spine signatures of the spine signers (two thirds,
never below spine_min_signatures, never more than the spine signers minus one registered node
when there are 3, 4 or 5 of them; more than half for a fallback block and for a late block,
the late block without the floor), each spine signer signing the same 204-byte header a main chain
block signs. A registered node the block itself removes from the spine signers counts toward
nothing. A registered node's spine signature on a spine block candidate is a signing
commitment: it signs no other candidate at that height until a spine block is stored there or
signed non-signing statements prove the candidate it committed to can no longer gather the
required spine signatures; a registered node that both signs a candidate and states it did not is
charged by the duty transaction SpineEquivocationReport (35). A spine block names the main chain
block it refers to (reference_block_height, a safety gap below the main tip, strictly above the
previous spine block's: there are no empty spine blocks) and carries a signed reference
commitment (that block's height, hash and cumulative difficulty), so any node can bind the payload
to the header without holding the main chain block. The spine blocksmith must be the one the
reference seed draws, the key changes must equal every spine signer's own registry delta, the
manifests every spine signer's own snapshots. A spine block's weight is the number of valid
signatures it carries; every node stores its own count, never the claimed one, and between competing
spines the one with more signatures above their common block wins. The spine is what a fresh node
syncs first: its manifests tell it which snapshot to fetch, and the spine signers tell it which keys
to trust. A node
that is behind stores a spine block whose reference is above its main tip on the block's own
signatures and runs the checks that need its main chain when that chain reaches the reference; a
mismatch is an alarm that stops the node (§7). The newest checked reference is the main chain's
finalized height, the floor below which no main-chain reorganisation is allowed (24 §3). The
hierarchy of spines above spines exists in code but is disabled on both chains.
1. The spine block
Purpose. The unit of the spine: header, payload, spine signatures.
Inputs. The previous spine block; the main chain's latest block, the main chain block at the reference height and the main chain block at the previous spine block's reference height; the pending key changes (§3) and active manifests (§4); the spine blocksmith's key; the spine signers.
Output and effect. A spine block is a main-chain block record (05 §1) with these values:
| Field | Value |
|---|---|
version |
1 |
height |
previous spine height + 1 |
timestamp |
the spine blocksmith's clock at creation (seconds) |
previous_block_hash |
the block hash of the previous spine block (05 §4) |
reference_block_height |
max(previous spine's reference, main tip − main_snapshot_min_height) (TestNet 760, DevNet 80); the previous reference when the tip is not above the gap. It must be greater than the previous spine block's reference: when it is not, the spine blocksmith makes no block ("no new checkpoint": no new spine block) and a validator refuses one ("SpineBlockEmpty", §7) |
merkle_root |
the main chain block at the reference height: its merkle_root, copied for information. The field is outside the signed bytes, so no node judges its value; the reference commitment binds the block to the main chain block |
blocksmith_public_key |
the spine blocksmith's node key (32 bytes) |
block_seed |
the 64-byte seed of the main chain block at the previous spine block's reference height (the draw seed of §5; §7 checks it) |
total_amount, total_fee, total_coinbase |
0 |
payload_hash, payload_length |
§2 over the key changes, the manifests and the reference commitment |
cumulative_difficulty |
the spine weight: previous block's weight + the number of signatures the block carries (§6), decimal string. Not signed and not in the block hash; every node stores its own count (§7) |
reference_commitment |
proto Block field 25 (bytes): reference_block_height u32 LE ‖ the referenced main chain block's 32-byte hash ‖ its cumulative difficulty as decimal ASCII (§2); empty on spine block 0 |
block_signature |
the aggregate of §6 (4 + 96 × n bytes), or one 64-byte signature |
spine_public_keys, spine_block_manifests |
the payload lists |
spine_refusals |
proto Block field 26: always empty in a spine block (a block carrying a non-signing statement is invalid, §7) |
transactions, receipts |
none |
Stored locally with a serialised payload (format byte 3: counts, keys with length-prefixed bytes, manifests with the chain genesis hash, then the length-prefixed reference commitment; formats 1 and 2 are still read); the HTTP API exposes height, hash, previous hash, blocksmith and timestamp.
How to compute it. As stated; the header bytes, hash and id follow 05 §2–§4 exactly with
block_signature being the aggregate blob: block_hash = SHA3-256(204 header bytes ‖ the whole signature field), id = the first 8 hash bytes as LE i64. The candidate identity used by
signing commitments and non-signing statements (§6a, §6b) is SHA3-256(204 header bytes) — the
unsigned bytes the spine signers sign — so a spine block candidate (one 64-byte signature of the
spine blocksmith) and the stored block (the aggregate) have the same identity, and a spine
blocksmith cannot make a "new" candidate by re-signing the same bytes.
Rule activation. spine_producer_by_reference (the spine blocksmith is drawn with the seed of
the previous reference), spine_reference_commit (the commitment); active from height 0 on every
chain. Nothing else changes by height.
main_snapshot_min_height, the reference gap, is 760 blocks (3 h 10 min) on TestNet and 80 blocks
(20 min) on DevNet; the genesis builder refuses a value that does not exceed max_rollback_height
(720 / 60) by at least 20 blocks (06).
Rejections and errors. §7.
Vector. computed, the worked candidate (a spine block candidate, used again in §2, §6a, §6b). INPUT: version 1;
timestamp 1,793,768,227; totals 0; one key change (main height 1,000, key 11×32, add, spine height
3); no manifests; reference 12,000, referenced hash 22×32, its cumulative difficulty "123456789";
blocksmith 33×32; seed 44×64; previous hash (a stand-in 32-byte value)
5FB8B0EE676469806C0D5682C6B8A2A62543257AF6A32076B01BC366C246F7F2. EXPECTED OUTPUT: the 204 header
bytes (05 §2 layout: version, timestamp, three totals, payload length as u64, payload hash, blocksmith
key, seed, previous hash)
01000000 23BBEA6A00000000 00×24 2C00000000000000
610200CC27549FA81B53B39B8B5186AC1443940C95E1B97D4EBA27BE9264BF7B 33×32 44×64
5FB8B0EE676469806C0D5682C6B8A2A62543257AF6A32076B01BC366C246F7F2; identity =
DE9130054E031E11DF492BDD5A9BE36A87720B8414A5E3E69EA9EE394A8D9EB6. With a 64-byte signature field of
55×64 (stand-in bytes) the block hash is
F672CCA4DA1387E8C3416BE94009B4CDEB1E03872EB930F9AB81DBFC669C538A and the id
−1,691,361,305,265,671,434 (LE i64 of F672CCA4DA1387E8); the identity does not change with the
signature field.
Test cases · §1
1 case · 1 valid
The worked spine block candidate: header, identity, hash and id
Loading the test widget…
Defects to match. (1) Because the weight is not signed, two nodes may store different
cumulative_difficulty strings for one spine block only if they counted different valid
signatures, which cannot happen for one block (the count is the aggregate's entry count once every
entry verified); the value served by GetCumulativeDifficulty is the node's own.
2. The payload hash
Purpose. The commitment of the header to the key changes, the manifests and the referenced main chain block.
Inputs. The block's key changes in order, then its manifests in order; its
reference_commitment.
Output and effect. payload_bytes = the concatenation of one key record (44 bytes) per
change and one manifest record per manifest; payload_hash = SHA3-256(payload_bytes ‖ reference_commitment) and payload_length = len(payload_bytes) without the commitment. The
commitment = reference_block_height (u32 LE, 4) ‖ the referenced main chain block's hash (32) ‖ its
cumulative difficulty (decimal ASCII), so the spine block names a specific main chain block, not
merely a height. Because the block carries the commitment, the payload hash is checked by every node
without the main chain. The commitment's shape is checked first: at least 37 bytes, its first
4 bytes equal reference_block_height, every byte from offset 36 a decimal digit. Whether it names
this node's main chain block is a separate check (§7): it runs when the
node's main chain holds the reference height; a node whose chain has no block there (not reached
yet, or below its own history after a fast sync) does not judge it; another block there is invalid
("SpineReferenceNotMyBlock", both hashes named); a read of its own block that fails (as opposed to
finding no row) refuses the block on this node ("SpineContentUnverifiable: …") until the read
works.
Key record:
| Offset | Size | Field | Encoding |
|---|---|---|---|
| 0 | 4 | main_block_height |
u32 LE |
| 4 | 32 | node_public_key |
raw |
| 36 | 4 | public_key_action |
u32 LE: 0 add, 1 remove |
| 40 | 4 | height |
u32 LE, the spine height carrying the change |
Manifest record (92 + 32 k bytes for k chunks when the identity is 32 bytes):
| Offset | Size | Field | Encoding |
|---|---|---|---|
| 0 | 8 | id |
i64 LE (§4) |
| 8 | 32 | full_file_hash |
raw (its real length) |
| 40 | k×32 | file_chunk_hashes |
raw, concatenated |
| 40+k×32 | 4 | manifest_reference_height |
u32 LE |
| 44+k×32 | 4 | manifest_spine_block_height |
u32 LE |
| 48+k×32 | 4 | chain_type |
u32 LE (0 main) |
| 52+k×32 | 8 | expiration_timestamp |
i64 LE |
| 60+k×32 | 32 | chain_genesis_hash |
raw (its real length) |
manifest_type is not hashed, and it is not on the wire either: the P2P
SpineBlockManifest message has no such field, so every received manifest decodes as type 0
(Snapshot), the only type ever produced. The node's own stored form of the payload (format byte 3)
is local.
How to compute it. As stated; the validator recomputes both values and compares.
Rule activation. spine_reference_commit, active from height 0 on every chain.
Rejections and errors. "InvalidBlockPayload: length mismatch (expected L, got M)" (L the
block's own payload_length, M the recomputed length), "InvalidBlockPayload: hash mismatch", "InvalidBlockPayload: the reference commitment is missing or short (n bytes)", "InvalidBlockPayload: the reference commitment names main height h, the block's reference is r", "InvalidBlockPayload: the reference commitment's difficulty is not decimal".
Vector. computed (the worked candidate of §1). INPUT: the key change (1,000, 11×32, add, 3), no
manifest, the commitment for (12,000, 22×32, "123456789"). EXPECTED OUTPUT: key record
E803000011111111111111111111111111111111111111111111111111111111111111110000000003000000 (44 bytes);
commitment E02E0000 ‖ 22×32 ‖ 313233343536373839 (45 bytes); payload_length = 44;
payload_hash = SHA3-256(key record ‖ commitment) =
610200CC27549FA81B53B39B8B5186AC1443940C95E1B97D4EBA27BE9264BF7B. INVALID: the same block with
payload_length 45 → "InvalidBlockPayload: length mismatch (expected 45, got 44)"; a commitment whose
first four bytes are E12E0000 (12,001) → "InvalidBlockPayload: the reference commitment names main height 12001, the block's reference is 12000".
Test cases · §2
7 cases · 2 valid · 5 invalid
The payload hash of one key change and the reference commitment
Loading the test widget…
The worked spine block candidate's payload passes its check
Loading the test widget…
A claimed payload length of 45 is refused
Loading the test widget…
A commitment naming main height 12,001 for a reference of 12,000 is refused
Loading the test widget…
A commitment of 36 bytes is refused
Loading the test widget…
A commitment whose difficulty is not decimal is refused
Loading the test widget…
A payload hash that does not match is refused
Loading the test widget…
Defects to match. A manifest with an identity or file hash of another length shifts every later field; validation refuses such manifests (§4), so only 32-byte values occur.
3. Public-key changes and the spine signers
Purpose. Which node keys may build spine blocks and give spine signatures on them (the spine signers), and how they follow the main registry.
Inputs. The main registry rows with latest = 1 and height in (previous spine's reference height, reference height]; the spine_public_key table (versioned by spine height).
Output and effect. A registry row of status Registered maps to an add change, a row of
status Deleted to a remove change; rows of any other status (queued, exited, suspended …)
give no change. main_block_height = the row's height, height = the new spine height, node_id =
the registry id. The expected key changes of a spine block (the list the spine blocksmith
builds, every spine signer compares with its own registry, §6a, and the validator compares at
storage, §7) are computed from two ranges of main chain heights, R₀ = the previous spine block's
reference height and R = the block's reference height:
- Removals come from the rows in
(R₀, R]. For a block that is not late, every Deleted row. For a late block (§6c), a Deleted row only when its key is among the spine signers as of the previous spine block or was Registered inside(R₀, R]. - Additions come from the rows in
(A, R], whereA=R₀when the previous spine block is not late, else the reference height of the newest spine block below it that is not late (the walk stops at a spine block this node does not hold, taking that block's reference). A late block carries no additions. An addition whose row height is ≤R₀and whose key also has a Deleted row at a height ≤R₀inside(A, R]is dropped (the key came and went during the late stretch). - A node that holds no main chain block at
min(R₀, A) + 1(it fast-synced past it) cannot compute the list and does not judge it; a failed read of that block refuses the spine block on this node ("SpineContentUnverifiable: …").
Applying a spine block appends each change as a new row (the key's previous rows lose latest).
The active set at spine height H = keys whose newest record at height ≤ H is an add, in record
order; the spine signers for validating block H+1 = the active set at H with the block's own
changes applied (remove deletes, add inserts or replaces by node id), sorted by node id. Genesis:
the configured initial_blocksmiths (11 keys in both spine genesis files) as add records at height
0 with main_block_height 0 and node ids derived as in 06/09 (the first 8 key bytes LE with the
top bit cleared). The registered nodes the pre-genesis roll call removes at the end of its window
(36) leave the registry as Deleted rows, so they appear as removals in the first spine block
whose range covers that height; the spine signers that count for that block (its required spine
signatures and the signatures it carries) are the spine signers as of the previous spine block
minus the keys the block itself removes (rule spine_bar_follows_registry, §6).
How to compute it. As stated. The comparison of two change lists (spine signer §6a (a), validator
§7) is a multiset comparison of (node_public_key, action, main_block_height, height): order is not
meaning.
Rule activation. spine_content_validated (the comparison with the validator's own delta),
spine_late_vote (steps 1 and 2 for a late block), spine_bar_follows_registry (the counting
spine signers); active from height 0 on every chain.
Rejections and errors. "InvalidSpinePublicKey" (empty key), "DuplicateSpinePublicKeyInBlock",
"SpineKeyChangesNotRegistryDelta: …", "SpineLateCarriesKeyChanges: a late spine block leaves signer additions pending" (§7).
Vector. computed: the spine genesis of either chain lists its 11 configured keys as add records
at spine height 0 (main_block_height 0), so the spine signers for validating spine block 1 are
those 11 keys sorted by node id. computed: spine block 4 is late, its previous (block 3, not late)
has reference 12,000, block 4 has reference 12,760; the registry holds a Deleted row for key K₂ at
12,100 (K₂ among the spine signers) and a Registered row for K₉ at 12,200. EXPECTED OUTPUT: block
4 carries exactly one change, (12,100, K₂, remove, 4); K₉'s addition waits. Block 5 (not late,
reference 13,520) then takes its additions over (12,000, 13,520], so it carries (12,200, K₉, add,
5) and the removals of (12,760, 13,520].
Test cases · §3
4 cases · 4 valid
The TestNet spine genesis: its 11 keys as add records at height 0, the spine signers sorted by node id
Loading the test widget…
Late spine block 4 carries the removal of K_2 and leaves the addition of K_9 pending
Loading the test widget…
Spine block 5, not late, takes the additions over (12,000, 13,520] and the removals over (12,760, 13,520]
Loading the test widget…
A spine block that is not late carries the additions and the removals of its range
Loading the test widget…
Defects to match. (1) A node admitted and expelled between two spine blocks appears only as a removal (its Deleted row is the newest); the removal of a key never added is applied as a no-op. (2) The spine blocksmith's own key need not be among the spine signers for it to try (the spine signers then do not sign, §6a).
4. Manifests
Purpose. The spine's pointer to a state snapshot.
Inputs. From the snapshot service (26): the snapshot's full-file hash, its chunk hashes, the
snapshot height, the chain identity; main_snapshot_interval, block_time_interval,
snapshot_manifest_expiration_seconds (0 = automatic, both chains), SNAPSHOT_MANIFEST_SAFETY_FACTOR 3,
SNAPSHOT_MANIFEST_MIN_EXPIRATION_SECONDS 2,592,000.
Output and effect. A manifest is created locally when a node takes a snapshot: expiration = snapshot block timestamp + max(override, 3 × interval × block time, 2,592,000); chain_type 0,
manifest_type 0 (Snapshot), manifest_spine_block_height 0 until published; id = the
first 8 bytes, LE i64, of SHA3-256(0 as i64 LE ‖ full_file_hash ‖ chunk hashes ‖ reference
height u32 ‖ 0 u32 ‖ chain_type u32 ‖ expiration i64 ‖ chain_genesis_hash). The next spine
block the node produces carries every active manifest (unexpired, newest spine height per id)
among the three newest generations (distinct reference heights, SNAPSHOTS_TO_KEEP + 1 = 3) of
its chain type and identity, with manifest_spine_block_height set to the new height; applying a
spine block stores each carried manifest under its height (replacing the unpublished height-0 row
of the same id). Manifest rows are kept for ever: they are the record of every snapshot the
decentralised storage keeps from block 0 (26); only a node's local snapshot directories are
pruned. The latest manifest of a chain = the row with the greatest reference height (then spine
height, then id) for that chain type and identity; the fast sync reads the newest manifests in that
order (26 §5); the pruning horizon of 13 §8 and the escrow horizon of 12 §5 read the two
newest distinct reference heights.
How to compute it. As stated.
Rule activation. None.
Rejections and errors. In a block: "InvalidSpineManifestChainIdentity" (identity not 32
bytes), "InvalidSpineManifestFileHash" (empty), "DuplicateSpineManifestInBlock" (same identity
and file hash twice), "SpineManifestForeignChain" (§7).
Vector. computed: a snapshot of a block stamped 1,793,600,000 on DevNet (interval 240 blocks,
block time 15 s): 3 × 240 × 15 = 10,800 < 2,592,000, so expiration = 1,793,600,000 + 2,592,000 = 1,796,192,000.
Test cases · §4
1 case · 1 valid
A DevNet snapshot manifest expires after the 30-day minimum
Loading the test widget…
Defects to match. (1) The pruning and escrow horizons read manifests by chain type only, not
by identity; harmless, since a foreign chain's manifest is refused at validation and never enters
the table. (2) manifest_type is stored and served over the API but not hashed and not on the
wire; a received manifest is always type 0.
5. Production: timing, the spine blocksmith selection and the weight
Purpose. When a spine block is due and who makes it.
Inputs. spine_smithing_period (TestNet 86,400 s, DevNet 3,600 s), spine_blocksmith_time_gap
100, spine_blocksmith_network_tolerance 150, spine_signature_collection_timeout 60 (both spine
files); the seed of the main chain block at the previous spine block's reference height; the spine
signers (§3) sorted by node id.
Output and effect. A block is due when now ≥ previous spine timestamp + period (with no
spine block: now ≥ main genesis time + period, the genesis time estimated as main tip timestamp − height × min_block_interval). A block whose timestamp < previous + period − spine_blocksmith_network_tolerance is refused at validation ("SpineBlockTooEarly"), so a
branch cannot be minted faster than a period and win the fork by count. Round r from the gap
g = timestamp − previous timestamp: 1 when g ≤ 0 or g < period + time_gap, else (g − period) div time_gap + 1 (integer division). Spine blocksmith for round r = the spine signer at index
LE u64 of the first 8 bytes of SHA3-256(seed(64) ‖ "spine" ‖ r as u32 LE) mod n, where seed is
the main chain block's seed at the previous spine block's reference height and the list is the
spine signers as of the previous spine block (§3). The spine blocksmith computes r from its clock;
the validator (§7) and the spine signer (§6a) accept the blocksmith when it is drawn for some
round 1…r, r computed from the block's own timestamp. A node whose key is drawn builds the block
(§1), signs it, collects spine signatures (§6–§6b) and stores and broadcasts it. When the reference
it would use is not above the previous spine block's (the main chain has not advanced a gap past the
previous spine block's reference) the spine blocksmith makes no block; a main chain stalled for a
whole spine period therefore makes no spine block, and a stall of 3 periods makes the next one a
fallback block (§6). It also makes none when the main chain block at the reference height or at the
previous reference height cannot be read.
Attempts. An attempt that collected too few signatures stays current until its 60-s collection window has closed; the spine blocksmith then builds a new attempt (a fresh timestamp, so a new identity). The spine blocksmith's own signature on an attempt is a signing commitment like a spine signer's (§6a): when it is committed to its own earlier attempt at that height, it first gathers non-signing statements on that attempt (§6b); when they do not release it, it re-collects that earlier attempt (§6b, the re-collection) and the new attempt waits; when they release it, the new attempt takes the commitment, recorded only if the commitment did not move meanwhile. A late attempt (§6c) is not held by a commitment to an earlier attempt that is not late. A spine blocksmith that is handed a candidate some spine signers committed to and that it cannot release re-collects that candidate the same way.
Weight. The spine blocksmith writes previous weight + 1 while it collects and previous weight + number of signatures collected into the finalized block; it is not signed, and every node that
stores the block replaces it with its own count (§7).
How to compute it. As stated. The validator recomputes the draw (§7); it never trusts the weight.
Rule activation. spine_producer_by_reference (the spine blocksmith drawn with the reference
seed), spine_min_spacing, cosign_promise_binds (the rule that makes a spine signature a signing
commitment, here the spine blocksmith's own), spine_late_vote; active from height 0 on every
chain.
The spine timings are the same on both chains: round 100 s, creation 300 s, tolerance 150 s,
collection 60 s (spine_blocksmith_time_gap, spine_blocksmith_block_creation_time,
spine_blocksmith_network_tolerance, spine_signature_collection_timeout); only the period
differs. The genesis builder refuses spine_signature_collection_timeout ≤ 0 (a signing commitment
is released only after a window closes).
Rejections and errors. None at production; the chain-level comparisons are §8.
Vector. computed: spine timestamps 1,793,509,027 / 1,793,595,427 / 1,793,681,827 (TestNet
period 86,400 s), gaps exactly 86,400 s, so each block is round 1 (86,400 < 86,400 + 100). computed,
the draw. INPUT: seed 44×64; spine signers, 11 keys K_1 … K_11 where K_i = 32 bytes of value i
(already in node-id order). EXPECTED OUTPUT: round 1: SHA3-256(seed ‖ 7370696E65 ‖ 01000000) =
0586A41A4332986770874F6285372832B107B9A4EACFD4853A69A6B90330B910, u64 LE of its first 8 bytes
7,464,771,646,157,784,581, mod 11 = 7 → K_8; round 2 → index 4 → K_5; round 3 → index 10 → K_11.
A block by K_5 with a gap of 86,600 s (round (86,600 − 86,400) div 100 + 1 = 3) is drawn (round 2);
a block by K_1 with the same gap → "SpineBlocksmithNotDrawn: the blocksmith is not the producer the reference seed draws for any round up to 3" (the error text's "producer" is the spine blocksmith). A gap of 86,249 s → "SpineBlockTooEarly: …" (86,249 < 86,400 − 150).
Test cases · §5
7 cases · 5 valid · 2 invalid
The spine blocksmith selection for rounds 1 to 3 over 11 registered nodes
Loading the test widget…
The round of a 86,600-second gap
Loading the test widget…
A gap of exactly one period is round 1
Loading the test widget…
K_5 at a gap of 86,600 s (round 3) is drawn in round 2
Loading the test widget…
K_8 at a gap of 86,400 s is drawn in round 1
Loading the test widget…
K_1 at a gap of 86,600 s is not drawn
Loading the test widget…
A gap of 86,249 s is too early
Loading the test widget…
Defects to match. (1) A timestamp gap of exactly period gives round 1 only because of the
+ time_gap window. (2) The spine blocksmith's draw uses the latest spine signers it can read and
falls back to the main registry when there are none; the validator uses the spine signers as of the
previous spine block. They agree whenever the spine signers are not empty.
6. The required spine signatures and the aggregate signature
Purpose. How many signatures a spine block needs, and how they are carried.
Inputs. The spine signers as of the previous spine block (§3) and the block's own removals;
spine_min_signatures (5 in both spine files), spine_signature_threshold_percent 67,
spine_fallback_periods 3 (compiled default, in no genesis file; the builder refuses 0),
spine_smithing_period, spine_late_vote_after_seconds (§6c); the block's and the previous
block's signed timestamps; the previous spine block's reference_block_height (the height at which
the rules below are read).
Output and effect. The counting spine signers of a block are the spine signers as of the
previous spine block — every registered node among them, suspended or not — minus the keys
the block's own key changes remove (rule spine_bar_follows_registry: a registered node the main
registry deleted stops counting at the first spine block that carries its removal, judged from the
block alone, so a fresh node reaches the same count). A signature by a removed key is well-formed
(the key is still on the list, §7) but counts toward nothing. With n = the number of counting
spine signers, the required spine signatures req are:
share = ceil(n × 67 / 100)computed as(n × 67 + 99) div 100in 64-bit (rulequorum_floor), or, for a fallback block (block.timestamp − previous.timestamp ≥ spine_fallback_periods × spine_smithing_period) and for a late block (§6c),share = n div 2 + 1.req = max(share, spine_min_signatures); for a late block the floor is skipped:req = share.- Rule
spine_threshold_capped(the cap on the required spine signatures): for 3, 4 or 5 counting spine signers,req = min(req, n − 1)(2 of 3, 3 of 4, 4 of 5), so a small chain makes spine blocks with one registered node down; 1, 2, or 6 and more spine signers are unchanged. - A
reqof 0 is 1.
The same function decides the spine blocksmith's target, the required spine signatures a spine
signer's commitment refers to (§6a), the validator's required spine signatures (§7) and the
fast sync's test of a sync point (26 §5).
The aggregate signature field:
| Offset | Size | Field |
|---|---|---|
| 0 | 4 | count u32 LE |
| 4 + 96 i | 32 | signer i node key |
| 36 + 96 i | 64 | signer i signature (Ed25519 over the 204 header bytes) |
The spine blocksmith's own entry comes first; order is the collection order. A 64-byte field is a single signature by the blocksmith and counts 1. With fewer than the required spine signatures collected the attempt is not stored (§5).
How to compute it. As stated; every signature is over the identical 204 bytes.
Rule activation. quorum_floor (the ceiling), spine_threshold_capped (step 3),
spine_bar_follows_registry (the counting spine signers), spine_late_vote (the late block's
share without the floor); all read at the previous spine block's reference height; active from
height 0 on every chain.
Rejections and errors. "InsufficientSpineSignatures: k of the n required" (with " (fallback block: more than half of the list)" or " (late spine block: more than half of the list)"), §7.
Vector. computed (spine_min_signatures 5, 67 %; n = the counting spine signers):
| n | required spine signatures | fallback | late | non-signing statements that release a commitment to a block that is not late (n − req + 1, §6b) |
|---|---|---|---|---|
| 1 | 5 | 5 | 1 | 1 |
| 2 | 5 | 5 | 2 | 1 |
| 3 | 2 | 2 | 2 | 2 |
| 4 | 3 | 3 | 3 | 2 |
| 5 | 4 | 4 | 3 | 2 |
| 6 | 5 | 5 | 4 | 2 |
| 7 | 5 | 5 | 4 | 3 |
| 8 | 6 | 5 | 5 | 3 |
| 11 | 8 | 6 | 6 | 4 |
| 12 | 9 | 7 | 7 | 4 |
With the 11 genesis registered nodes a block needs 8 signatures (aggregate field 4 + 96 × 8 = 772
bytes), a fallback block 6, a late block 6. One or two spine signers never reach the floor of 5
except on a late block (1 and 2). INPUT: 11 spine signers as of the previous block, the block removes
K₂ and K₇ (two Deleted rows in its range) → n = 9: it needs 7 signatures (ceil(9 × 0.67) =
(603 + 99) div 100 = 7), and a signature by K₂ in its aggregate verifies but is not counted.
Test cases · §6
2 cases · 2 valid
Required spine signatures for 1 to 12 counting spine signers: normal, fallback, late
Loading the test widget…
The block removes K_2 and K_7: 9 counting spine signers need 7, and K_2's signature is not counted
Loading the test widget…
Defects to match. (1) A suspended registered node still counts among the counting spine signers until a spine block carries its removal from the registry; a spine block that is not late therefore needs two thirds of a list that may include nodes that are down, and only the fallback (3 periods) or the late block (§6c) lowers the requirement to more than half.
6a. How a registered node decides to give its spine signature, and the signing commitment
Purpose. When a registered node gives its spine signature on a spine block candidate, and what that signature commits it to.
Inputs. The SpineBlockSignatureRequest (27, a signed P2P call from a key that handshook
with this node): the spine block candidate (a spine block whose block_signature is the spine
blocksmith's 64-byte signature) and refusals (zero or more SpineRefusal, the non-signing
statements of §6b); the spine signer's spine tip, its main chain and registry, its own manifests;
its clock; its commitment state (below); spine_signature_collection_timeout (the window, 60 s),
spine_blocksmith_network_tolerance (150 s); main_snapshot_min_height (the safety gap);
spine_late_vote_after_seconds (§6c).
Output and effect. A signature (accepted = true, signature = (node key, Ed25519 over the 204 header bytes, node id, time)) or an answer accepted = false whose error begins with "abstain: "
or "refused: " (or is one of the form errors below). The commitment state per spine height H:
the signing commitment (the identity of §1 of the candidate it is committed to, that candidate's
own timestamp, the required spine signatures that candidate needs as computed when the node
committed, and the candidate itself stripped of the fields outside its identity — transactions,
receipts, Merkle tree, transaction ids, cumulative difficulty, Merkle root, block hash), the list of
identities it has signed at H (at most 1,024; the oldest is evicted beyond that) and the list
of identities it has refused, that is given a non-signing statement on, at H (§6b; at most
1,024 per height, persisted). The spine signer judges, in this order (the first that applies
decides):
- Not the height being collected: a request whose height is not the spine signer's spine tip +
1 is not judged (
"spine height H is not the one being collected (my tip is T)"); no commitment is made. Height 0:"Cannot sign genesis spine block"; no blocksmith key:"Missing blocksmith public key"; previous block not held:"Previous spine block not found". - Form: the payload hash and length (§2); the reference commitment names its own main chain block at the reference height (no block there → abstain; another block → refuse); no heavier block held at the height, the reference does not go backwards and a Merkle root is present when the reference advanced and a Merkle tree is carried; the spine signer itself and the blocksmith among the spine signers as of the previous spine block; the spine blocksmith's 64-byte signature verifies over the 204 header bytes.
- Its own view: whether the candidate is late (§6c); when the reference is at or below its
main tip, its own expected key changes of §3 for that lateness (a failed read → abstain; the
main chain block the ranges start at not held →
"abstain: I do not hold the main blocks the proposal's key changes start at"); no main chain or registry → abstain; the counting spine signers of the candidate (§6: the spine signers as of the previous spine block minus the candidate's removals),ntheir number; the request'srefusalsthat verify (§6b), are by distinct keys among the counting spine signers, and nameHand the identity it is committed to. - Storage-time checks: the blocksmith is the one the reference seed draws for a round
1…r(§5; refuseSpineBlocksmithNotDrawn/SpineSeedNotReference); a spine signer that does not hold the main chain block at the previous reference height cannot check the draw and goes on; a read fault abstains; the timestamp respects the spacing (§5; refuseSpineBlockTooEarly). A candidate that storage would refuse is never committed to. - A block held at H binds for good: another identity → refuse; the same identity → sign again.
- Refused before: an identity in its refused list at
H(it gave a non-signing statement on it) → refuse ("… never signing it"). - The committed candidate itself: a candidate whose identity equals the commitment it holds at
His signed again, whatever its age (a lost collection can complete). - Freshness (a window of 0 skips it): a candidate that is not late is refused when
now > candidate.timestamp + 60(older than its collection window); any candidate, late or not, is refused whencandidate.timestamp > now + 150(stamped ahead beyond the tolerance; lateness is read from the stamp, so a future stamp could claim it early). - Commitment: when it holds a signing commitment at
Hfor another identity, and that commitment is not released by lateness (the candidate is late and the committed candidate's timestamp is before the late threshold of §6c): it counts the non-signing statements of step 3; fewer thann − req + 1,reqbeing the committed candidate's required spine signatures (1 whenn < req) → refuse, and the answer names the commitment:promised_block_hash= the identity it is committed to,promised_bar= that candidate's required spine signatures,promised_block= the stored stripped candidate. With enough non-signing statements the commitment is released and the new candidate is judged on its merits below. - Reference: refuse when
reference < previous reference, or (spine height > 0) whenreference = previous reference(an empty block); abstain when the spine signer's main tip is below the safety gap orreference > its tip − gap. - Content: (a) a late candidate carrying an add → refuse (
"a late spine block carries signer additions"); the key changes equal its own expected key changes of step 3 (§3, multiset) → else refuse; (b) every manifest for its own chain equals its own manifest at that reference height (same chain type and type), hash for hash and chunk for chunk; no local manifest → abstain; a manifest naming another chain identity → refuse. - Sign. Before signing: a chain with a window of 0 → refuse (a commitment could never be
released); required spine signatures that cannot be computed, or 0 → refuse. Then, atomically
against concurrent requests: if its commitment at
Hchanged since it looked and now names another identity, refuse naming it ("… (concurrent request)"); if the identity was refused meanwhile, refuse; otherwise record the commitment (identity, timestamp, required spine signatures, stripped candidate), add the identity to its signed list, persist it (a commitment that cannot be persisted is not made: the previous state is restored and the answer is"abstain: cannot record my signing commitment; not signing"), and return the signature.
A signing commitment holds until a spine block is stored at H (heights at or below the spine
tip are dropped from the commitment state) or until non-signing statements release it (step 9). The
commitment that holds is persisted: one row per pending height (height, identity, required spine
signatures, candidate timestamp, stripped candidate, the signed identities concatenated, 32 bytes
each), replaced when a release moves it; at start the node deletes the rows at or below its spine
tip and restores the others. In memory at most 64 heights of commitments are kept.
How to compute it. As stated.
Rule activation. cosign_promise_binds (the signing commitment, steps 9 and 12), read at the
previous spine block's reference_block_height; spine_late_vote (steps 3, 8, 9 and 11a),
spine_bar_follows_registry (the counting spine signers), spine_producer_by_reference (the spine
blocksmith drawn with the reference seed), spine_min_spacing, spine_reference_commit,
spine_content_validated; active from height 0 on every chain.
Rejections and errors. Form errors: "Cannot sign genesis spine block", "Missing blocksmith public key", "Previous spine block not found", the payload errors (§2), "InvalidCumulativeDifficulty",
"InvalidReferenceBlockHeight", "InvalidMerkleRootBlock", "Node not active for this spine height", "Blocksmith not active for this spine height", "Missing or malformed blocksmith signature", "Invalid blocksmith signature on spine block"; judgement answers begin "abstain: "
or "refused: ", among them "refused: promised another proposal at spine height H; it is released only by k refusal(s) of it (m shown)", "refused: promised another proposal at spine height H (concurrent request)", "refused: I refused this proposal at spine height H (concurrent request)",
"refused: this chain has no collection window, a promise could never be released", "refused: the bar for this proposal cannot be computed", "refused: a late spine block carries signer additions", "abstain: I do not hold the main blocks the proposal's key changes start at",
"abstain: no main chain or registry view to check the proposal against", "abstain: cannot read my main tip", "abstain: cannot record my signing commitment; not signing" (in these texts
"promised" is the signing commitment, "proposal" the spine block candidate, "refusal" the
non-signing statement and "bar" the required spine signatures).
Vector. computed. INPUT: 11 counting spine signers, required spine signatures 8; registered
node A holds the signing commitment at height 3 for the worked candidate P of §1 (identity
DE913005…9EB6, required spine signatures 8); a new candidate Q at height 3, not late, arrives with
no non-signing statements. EXPECTED OUTPUT: accepted = false, error = "refused: promised another proposal at spine height 3; it is released only by 4 refusal(s) of it (0 shown)",
promised_block_hash = DE9130054E031E11DF492BDD5A9BE36A87720B8414A5E3E69EA9EE394A8D9EB6,
promised_bar = 8, promised_block = P without its transactions, receipts, Merkle tree, transaction
ids, cumulative difficulty, Merkle root and block hash. The same request carrying four verified
non-signing statements on DE913005…9EB6 at height 3 by four distinct counting keys: A judges Q on
its content and, signing it, its commitment moves to Q's identity while P's stays in its signed list.
computed (lateness): P stamped T₀ + 86,400 + 100 (not late, TestNet period 86,400 s, late
threshold T₀ + 86,400 + 10,800); a candidate Q′ stamped T₀ + 97,300 is late, so A's commitment
to P does not hold it: Q′ is judged on its content with no non-signing statement shown, and its age
is not refused. INVALID: a request for height 5 while A's spine tip is 3 → "spine height 5 is not the one being collected (my tip is 3)"; Q stamped 61 s before A's clock → "refused: the proposal (stamped t) is older than my collection window of 60 s (now t+61)".
Test cases · §6a
14 cases · 3 valid · 11 invalid
A registered node committed to P does not sign Q and names its signing commitment
Loading the test widget…
Four verified non-signing statements on P release the signing commitment and Q is signed
Loading the test widget…
A request for height 5 while the tip is 3 is not judged
Loading the test widget…
A spine block candidate stamped 61 s before the registered node's clock is not signed
Loading the test widget…
A spine block candidate stamped 151 s ahead of the registered node's clock is not signed
Loading the test widget…
A spine block candidate the registered node stated it did not sign is never signed
Loading the test widget…
A block held at the height binds for good
Loading the test widget…
A reference that does not advance is refused
Loading the test widget…
A reference not yet 760 blocks below the registered node's main chain tip gets an abstention
Loading the test widget…
The committed spine block candidate itself is signed again whatever its age
Loading the test widget…
A late candidate is not held by a commitment to a candidate that is not late, and its age is not refused
Loading the test widget…
A late candidate carrying a signer addition is refused
Loading the test widget…
A late candidate stamped 151 s ahead of the registered node's clock is refused
Loading the test widget…
A commitment to a late candidate holds another late one
Loading the test widget…
Defects to match. (1) An attempt that is not late and falls short binds its signers: it is
released only when n − required spine signatures + 1 registered nodes that did not sign it give
non-signing statements on it, and a registered node that did not sign it refuses a stale candidate
for its age, so with registered nodes offline the height waits for them until the late threshold (4
registered nodes, required spine signatures 3, two signed, one offline: the height waits for the
offline registered node, or for a late candidate three hours after the block was due). (2) A key
that signs two different candidates at one height is not charged: a released commitment makes
that legitimate. A key whose spine signature and non-signing statement on one candidate both
exist is charged by SpineEquivocationReport (type 62, 35), sent by the collecting spine
blocksmith that holds both (§6b).
6b. Non-signing statements and the non-signing round
Purpose. How a signing commitment to a spine block candidate that can no longer complete is released.
Inputs. A SpineRefusalRequest (27, the request for a non-signing statement): proposal (the
spine block candidate the statement is about, with its spine blocksmith's 64-byte signature;
spine_height and refused_block_hash are informative, the candidate decides); the stating node's
spine tip, spine signers, clock, its signed list at the height; the genesis hash.
Output and effect. A non-signing statement (SpineRefusal on the wire) says "I did not sign
spine block candidate P at spine height H":
SpineRefusal { spine_height (u32), refused_block_hash (32, the identity of §1), node_public_key (32), signature (64) },
the node key's Ed25519 signature over
digest = SHA3-256("ZBC-SPINE-REFUSE" ‖ genesis_block_hash (32) ‖ H as u32 LE (4) ‖ identity (32))
("ZBC-SPINE-REFUSE" is 16 ASCII bytes, no terminator; the preimage is 84 bytes). A non-signing
statement verifies when the signature is 64 bytes, the key 32 bytes and the signature checks over
that digest. Non-signing statements count for a candidate at height H with identity I when
they name H and I, verify, and are by distinct keys among the spine signers as of the previous
spine block.
Giving a non-signing statement (RequestSpineRefusal → SpineRefusalResponse{given, error, refusal}, a signed P2P call from a key that handshook with this node): the stating node checks, in
order, that the request carries a candidate; that the candidate's height is its spine tip + 1 and
the previous block is held; that the candidate's previous_block_hash is the hash of its own
spine block at that height (a statement is given only on a real candidate for the pending height:
the signed bytes carry no height, so any header the node ever signed could otherwise be relabelled
and drawn into a report against it, 35); that the blocksmith is the one the reference seed draws
for a round that has come (§5; a draw it cannot check because it does not hold the main chain block
at the previous reference also refuses the request); that the timestamp respects the spacing (§5);
that the blocksmith is among the spine signers as of the previous spine block; that the spine
blocksmith's 64-byte signature verifies over the 204 header bytes; that rule cosign_promise_binds
is active at the previous block's reference height; that the chain has a window (> 0); that the
candidate's window has closed on its clock (now > candidate.timestamp + 60); and that the
identity is not in its signed list at that height (it gives no non-signing statement on a
candidate it signed, whether that commitment still holds or a release moved it). Then it records
the identity in its refused list (persisted; at most 1,024 per height; a statement that cannot be
recorded is not given), signs the statement and answers given = true; it never signs that
candidate afterwards (§6a step 6). Any registered node among the spine signers may give one — one
that declined the candidate, is committed to another attempt, or never saw it. The stating node need
not be among the spine signers to answer; only the counting spine signers' keys count.
The non-signing round (the spine blocksmith, after its first round of requests): for every
identity that some spine signers answered with as the one they are committed to, the spine
blocksmith checks every handed-over promised_block against the identity it names (a handover
whose identity differs is ignored, so a hostile answer never blinds a group); for a group with no
valid candidate nothing is asked. For each group it computes the committed candidate's required
spine signatures itself (§6, never taken from promised_bar), counts the non-signing statements
needed (n − required spine signatures + 1, n the counting spine signers), adds its own
statement when it did not sign that attempt and the window has closed, and asks every spine signer
not committed to that identity for a non-signing statement on it (sending the candidate) until
it has enough; with enough it asks the committed spine signers again with the statements attached in
SpineBlockSignatureRequest.refusals. A group that cannot be released is re-collected: the
spine blocksmith asks every spine signer for its signature on the committed candidate itself
(sending it with no statements), counts the candidate's own 64-byte blocksmith signature (it is that
blocksmith's spine signature, whoever re-collects), and, when the signatures reach that candidate's
required spine signatures, builds the aggregate, stores and broadcasts that block; otherwise the
new attempt waits. Before the re-collection it checks the candidate the way a validator does (the
drawn blocksmith, the spacing). The spine blocksmith's own earlier attempt is handled the same way
before it builds a new candidate (§5); non-signing statements gathered for it count again in the
group round. A late attempt that fell short is re-collected once the same way.
The double vote. Whenever the spine blocksmith re-collects a candidate it holds both the spine
signatures it gathered on it and the non-signing statements it gathered on it: a key present on
both sides voted both ways, and the spine blocksmith submits a fee-free SpineEquivocationReport
(type 62, 35; rule spine_equivocation_report judged at its main tip + 1) carrying the two
signatures to its pool, one per such key.
How to compute it. As stated.
Rule activation. cosign_promise_binds, spine_bar_follows_registry, spine_late_vote,
spine_equivocation_report; active from height 0 on every chain.
Rejections and errors. given = false with "no proposal to refuse (the request must carry it)", "spine height H is not the one being collected (my tip is T)", "Previous spine block not found", "the candidate does not build on my spine block at height h", "not a valid spine blocksmith: …", "not a valid spacing: …", "Blocksmith not active for this spine height",
"Missing or malformed blocksmith signature", "Invalid blocksmith signature on spine block",
"refusals are not part of co-signing before rule cosign_promise_binds", "no collection window on this chain: no refusals", "that proposal's collection window is still open on my clock", "I signed that proposal at spine height H: a refusal would be a lie", "cannot record the refusal at spine height H: none given", "cannot sign the refusal: …" (in these texts "proposal" is the spine
block candidate, "refusal" the non-signing statement and "co-signing" giving spine signatures).
Vector. computed (the worked candidate of §1 at spine height 3). INPUT: genesis hash G =
E003E4E3557EF19F0519BD345009DEA7FB43B3445EAA043920C5DC23B3302871 (a stand-in 32-byte value),
height 3, identity DE9130054E031E11DF492BDD5A9BE36A87720B8414A5E3E69EA9EE394A8D9EB6. EXPECTED
OUTPUT: preimage (84 bytes) 5A42432D5350494E452D524546555345 ‖ G ‖ 03000000 ‖ the identity;
digest AD753566D7D623FF65CD642D61B425737F08F15180F084D5ABE70A7E0761C390 (the non-signing
statement's Ed25519 signature is over these 32 bytes). Second example: identity
A7FFC6F8BF1ED76651C14756A061D662F580FF4DE43B49FA82D80A4B80F8434A, height 3 → digest
D22DD7A43A0AEB1D04F96E668EA08BE6829CD0D7EFA50B3BDED745E6DB72A65C. INVALID: a request for the
candidate stamped 1,793,768,227 asked at 1,793,768,280 (53 s later) → given = false, "that proposal's collection window is still open on my clock"; a non-signing statement naming height 4
for the identity above does not count toward a height-3 release; a request whose candidate's
previous_block_hash is not the stating node's spine block 2 → "the candidate does not build on my spine block at height 2".
Test cases · §6b
12 cases · 3 valid · 9 invalid
The non-signing statement digest of the worked spine block candidate
Loading the test widget…
A second non-signing statement digest
Loading the test widget…
A non-signing statement naming height 4 does not count toward a height-3 release
Loading the test widget…
A repeated refuser and a key off the list count nothing
Loading the test widget…
A non-signing statement on a candidate after its window closed
Loading the test widget…
No non-signing statement while the candidate's window is still open
Loading the test widget…
No non-signing statement on a candidate the registered node signed
Loading the test widget…
A non-signing statement request without a spine block candidate
Loading the test widget…
No non-signing statements on a chain without a collection window
Loading the test widget…
A candidate that does not build on the stating node's spine block 2 is refused
Loading the test widget…
A candidate for height 4 while the stating node's tip is 2 is refused
Loading the test widget…
A candidate by a key off the spine signers is refused
Loading the test widget…
Defects to match. A key that gives a non-signing statement on a candidate and whose signature also sits in that candidate's stored aggregate is charged only when a collecting spine blocksmith held both at once (§6b, the double vote); a node reading the stored block later does not report it.
6c. A late spine block
Purpose. A spine block arrives the same day even when some spine signers stay silent.
Inputs. The previous spine block's timestamp T₀; spine_smithing_period P; the genesis
parameter spine_late_vote_after_seconds L (bounded 0…31,536,000 by the genesis builder; the DevNet
genesis names 10,800; a chain that does not name it uses 10,800, and 0 switches lateness off); the
candidate's timestamp T; the counting spine signers of §6.
Output and effect. The spine block is late when L > 0 and T ≥ T₀ + P + L, judged by the
rule at the previous spine block's reference height. A late spine block:
- needs the spine signatures of more than half of its counting spine signers, with no
spine_min_signaturesfloor and with the cap of §6 step 3 (§6:req = n div 2 + 1, capped atn − 1for 3, 4 or 5); - carries the registry's removals of §3 (so the registered nodes it needs more than half of are the ones still registered) and no additions; the pending additions ride on the next spine block that is not late (§3 step 2);
- carries no non-signing statements (no spine block does, §7): nothing a late block carries proves how many registered nodes said no, so the block is judged on its signatures alone;
- is signed by a spine signer after its collection window has closed (§6a step 8), is not held by a signing commitment to an earlier candidate that is not late (§6a step 9), and is re-collected once by its spine blocksmith when it falls short (§6b).
A spine block that is not late follows §6 unchanged. Lateness is read from the candidate's own signed timestamp, which the spacing bound and the future bound of §7 confine.
How to compute it. As stated.
Rule activation. spine_late_vote, active from height 0 on every chain.
Rejections and errors. "SpineLateCarriesKeyChanges: a late spine block leaves signer additions pending", "InsufficientSpineSignatures: k of the n required (late spine block: more than half of the list)", "SpineBlockCarriesStatements: a spine block carries no non-signing statements" (§7).
Vector. computed (TestNet: P 86,400, L 10,800; 11 spine signers as of the previous block,
none removed): a candidate stamped T₀ + 97,200 is late and needs 6 signatures; one stamped T₀ + 97,199 is not late and needs 8 (7 signatures are refused as "InsufficientSpineSignatures: 7 of the 8 required"). A late candidate that removes two registered nodes deleted from the registry
since T₀'s reference (n = 9) needs 5. A late candidate with 6 signatures that adds a node key →
"SpineLateCarriesKeyChanges: …". computed (DevNet: P 3,600, L 10,800): a block is late from
T₀ + 14,400, four periods after the previous block.
Test cases · §6c
7 cases · 4 valid · 3 invalid
A candidate stamped T0 + 97,200 is late and passes with 6 of 11
Loading the test widget…
A candidate stamped T0 + 97,199 is not late: 7 signatures of the 8 required are refused
Loading the test widget…
A late candidate with 5 signatures of the 6 required is refused
Loading the test widget…
A late candidate removing two registered nodes (9 counting) needs 5
Loading the test widget…
A late candidate with 6 signatures that adds a node key is refused
Loading the test widget…
DevNet: a block is late from T0 + 14,400, four periods after the previous block
Loading the test widget…
DevNet: a block stamped T0 + 14,399 is a fallback block, not late
Loading the test widget…
Defects to match. None.
7. Validation and application of a received spine block
Purpose. What a node checks before storing a spine block it did not produce.
Inputs. The block; its predecessor (must be held); the spine signers as of the predecessor (§3); the local clock; the main chain; the release pin (§9).
Output and effect. On the spine alone (needs no main chain), in order: height > 0 →
timestamp > previous timestamp, timestamp ≤ now + 7,200, the spacing of §5
("SpineBlockTooEarly"), reference_block_height > the predecessor's ("SpineBlockEmpty: …"); key
changes non-empty and unique (§3); manifests well-formed (§4); payload hash and length over the
carried commitment (§2); a carried id of 0 is derived from the hash (a hash shorter than 8
bytes, or an id of 0, fails); signatures: the spine signers must not be empty — with none,
nobody counts and the block is invalid ("NoSpineSignerList: …", "signer list" in the error text
being the spine signers); a 64-byte field is a single signature by the blocksmith, who must be among
the spine signers, and counts 1; otherwise the aggregate of §6 must parse exactly (count ≥ 1), hold
no duplicate signer, every signer among the spine signers, every signature valid over the header
bytes, and the blocksmith among the signers; the counted signatures are the entries whose key is
among the counting spine signers (§6: the spine signers minus the keys the block removes), and
they must reach the block's own required spine signatures (§6, fallback and late included); the
block must carry no non-signing statement ("SpineBlockCarriesStatements: …") and, when late
(§6c), no add change ("SpineLateCarriesKeyChanges: …"); previous_block_hash = the
predecessor's hash. Weight: the block's weight on this node is predecessor's stored weight + counted signatures; a block already held at that height must not be heavier than that
("InvalidCumulativeDifficulty" when it is; equal or lighter passes and the insert then fails as a
conflict). Then the reference height ≥ the predecessor's, and when it advanced, merkle_root must be
present when a merkle_tree is (judged on every node at once).
Against this node's main chain: when reference_block_height is above this node's main
tip, only the hold bound is judged (a reference no lag explains is refused, see Rejections) and
the block is stored ahead, its remaining checks deferred. Otherwise, in order: the reference
commitment names this node's main chain block at that height (§2; no block there = not judged; a failed
read refuses as "SpineContentUnverifiable: …"); the block's merkle_root value is not judged;
the content (spine_content_validated) — the key changes equal this node's own expected key
changes of §3 for the block's lateness (not judged when the node holds no main chain block at the
start of the ranges, i.e. it fast-synced past it; a failed read refuses) and every manifest for this
chain equals its own snapshot hash-for-hash ("SpineManifestNotMySnapshot: …"), a manifest naming
another chain identity is refused ("SpineManifestForeignChain"); the spine blocksmith (spine_producer_by_reference, the spine
blocksmith drawn with the reference seed) — block_seed is the main chain block's seed at the
previous reference height ("SpineSeedNotReference") and the §5 draw over the spine signers names
the blocksmith in some round 1…r ("SpineBlocksmithNotDrawn"); not judged when that main chain
block is not held, a failed read refuses ("SpineProducerUnverifiable: …", the spine blocksmith
cannot be checked).
Storage: the row with this node's weight in cumulative_difficulty (the claimed value is
discarded; a non-decimal value is refused), then every key change (§3) and every manifest (§4), and
for a deferred block a pending row (spine height, block hash), in one transaction; the same block
again → "SpineBlockAlreadyExists", a different block at a held height →
"SpineBlockHeightConflict". A pushed spine block (27 §9, chain type 1) at a height already
held is ignored whatever its hash (node-local; a conflicting block is settled only by the fork
choice of §8); a pushed block that fails to store is logged and charges nobody; stored blocks are
relayed to all connected peers unless received from their blocksmith. A spine block fetched by the
spine sync (§8) that fails to store: a refusal "SpineReferenceNotMyBlock" on a block whose
signature field holds at least its required spine signatures (as this node computes them over the
predecessor it holds) is checkpoint evidence handed to the fork resolver (24), never a charge
against the feeder (the fork outcome is noted for that peer, 28 §9); "InvalidPreviousBlockHash"
starts the spine fork path (§8); any other invalid block charges the feeder a bad block (28 §6)
unless this node's own clock is the suspect (28 §9b); a hold (not held yet) and a soft refusal
never charge.
Deferred checks: every 10 s while running, and at every start, the node takes its pending rows
in spine-height order; a row whose block is confirmed gone (not found, or another block at that
height after a spine switch) is dropped; a read fault stops the walk and the row is retried next
time; the walk stops at the first block whose reference is still above the main tip or whose check
cannot run yet; a block whose checks pass is settled (a settle that cannot be written stops the
walk). A check that fails is the alarm: the node logs "SPINE ALARM: spine block h (hash) does not match this node's main chain at its reference height r (my block there: hash): …", the
row stays pending and the node exits (exit code 3). With auto_resync on (30) the node first writes
the resync marker naming the alarm, so the next start sets its chain aside and rebuilds it from genesis
through the spine and a spine-attested snapshot (26); with it off, every later start runs the same
check first and refuses to start until the operator rebuilds the chain or the spine is corrected.
How to compute it. As stated.
Rule activation. spine_content_validated, spine_producer_by_reference,
spine_reference_commit, spine_min_spacing (read at the block's own reference height),
quorum_floor, spine_threshold_capped, spine_bar_follows_registry and spine_late_vote (read at
the predecessor's reference height); active from height 0 on every chain.
Rejections and errors. "SpineBlockEmpty: the reference r does not advance past the previous spine block's p (no new checkpoint)", "NoSpineSignerList: the signer list as of the previous spine block is empty; no signature can count", "InsufficientSpineSignatures: k of the n required" (with
" (fallback block: more than half of the list)" or " (late spine block: more than half of the list)"), "SpineBlockCarriesStatements: a spine block carries no non-signing statements",
"SpineLateCarriesKeyChanges: a late spine block leaves signer additions pending",
"SpineReferenceNotMyBlock: …", "SpineContentUnverifiable: …", "SpineKeyChangesNotRegistryDelta: …", "SpineManifestForeignChain", "SpineManifestNotMySnapshot: …",
"SpineSeedNotReference: …", "SpineBlocksmithNotDrawn: …", "SpineProducerUnverifiable: …",
"SpineBlockNotPinned" (§9); the hold bound "SpineReferenceImplausible: …" (a margin a slow clock
could explain is refused without charging the feeder; beyond ten times the gap and slack it is
invalid); "Spine block timestamp (t) must be after previous block (p)", "Spine block timestamp too far in future", "SpineBlockTooEarly: …", "InvalidID", "InvalidSpineBlocksmith",
"InvalidSignature", "DuplicateSpineSignature", "InactiveSpineSigner",
"MissingBlocksmithSignature", "InvalidPreviousBlockHash", "InvalidCumulativeDifficulty",
"InvalidReferenceBlockHeight", "InvalidMerkleRootBlock", "Cannot validate block: previous block not found", "Invalid spine cumulative_difficulty (non-decimal)", "SpineBlockAlreadyExists",
"SpineBlockHeightConflict". In these texts "checkpoint" is a spine block and "the signer list"
the spine signers.
Vector. computed: with 11 spine signers a block with a 64-byte signature counts 1 and is
refused ("InsufficientSpineSignatures: 1 of the 8 required"); an aggregate of 8 entries (772 bytes)
all by keys of the spine signers, the blocksmith among them, passes the count. An aggregate of 8
entries one of which is by a key the block itself removes counts 7 against the 7 required of the 10
counting spine signers and passes; the same block with two entries by removed keys counts 6 of the 7
required and is refused. A block carrying one SpineRefusal in field 26 →
"SpineBlockCarriesStatements: a spine block carries no non-signing statements".
Test cases · §7
10 cases · 3 valid · 7 invalid
One 64-byte signature counts 1 of the 8 required
Loading the test widget…
An aggregate of 8 listed signers, the blocksmith first, passes the count
Loading the test widget…
An aggregate of 7 is one short
Loading the test widget…
A block three periods after its predecessor (a fallback block, late as well) passes with 6 of 11
Loading the test widget…
A signer listed twice in the aggregate
Loading the test widget…
A signer off the list
Loading the test widget…
An aggregate without the blocksmith
Loading the test widget…
8 entries, one by a key the block removes: 7 counted of the 7 required of 10 counting spine signers
Loading the test widget…
8 entries, two by keys the block removes: 6 counted of the 7 required
Loading the test widget…
A spine block carrying a non-signing statement is invalid
Loading the test widget…
Defects to match. (1) The spine blocksmith selection, the seed and the content of the key changes and
manifests are enforced; an implementation must reproduce the cases where a check is skipped rather than
failed because the node lacks the main history (a node that fast-synced: the commitment, the key
delta and the spine blocksmith selection below its snapshot window). Older spine blocks then rest on their
signatures and the pin. (2) The future bound and the hold bound use the validator's clock. (3) The
finalized height of 24 §3 is the newest reference among the spine blocks below the first one
still pending: a block stored ahead and not yet checked is no floor for this node. (4) The
checkpoint-evidence test of the sync path counts the entries of the signature field against the
required spine signatures, not the entries that verify; a feeder can therefore avoid the charge for
a contradicting block by padding its aggregate with invalid entries, at the price of the block being
refused anyway.
8. Sync and fork choice on the spine
Purpose. How a node follows the spine and settles a spine fork.
Inputs. The same sync tick as the main chain (24 §2): registered peers' spine weight and
height (GetCumulativeDifficulty with chain type 1).
Output and effect. The heaviest peer by the string comparison of 24 §1 of the weights peers
claim is followed: GetNextBlockIDs(our tip id, 50) and GetNextBlocks with chain type 1, each
block stored through §7 (blocks ahead of the main chain included). A node whose main-chain height
cannot be read skips the spine sync. A fork is looked at only when the peer claims more: the common
block is searched downwards from our tip for at most 100 heights — and, when this node holds
the release pin, never below the pinned height (nothing found there → the peer is not followed) —
asking the peer for the ids after our block at height h − 1 and accepting h when the peer's
first id equals ours (an empty answer accepts h − 1; nothing found and no pin held → genesis). The
peer's blocks above the common block, up to fork height + 100, are downloaded and weighed before
anything is rolled back: each in height order through the spine-alone checks of §7 over the spine
signers their own branch carries (starting from ours at the common block, each block's key changes
applied; a block's counted signatures are those by its counting spine signers, §6), the first
failing or height-skipping block ending their branch; theirs = the sum of the counted signatures
of their valid blocks, ours = the sum of the counted signatures of our blocks above the common
block, weighed the same way over the spine signers our branch carries (a block of ours that
cannot be read or does not count ends our weight there). Their branch is followed only
when it has at least one valid block and theirs > ours (a tie keeps ours). Then, in one database
transaction, our spine is rolled back to the common block (spine_block, key records, manifests
and pending deferred checks above it, the keys' latest re-marked) and their valid blocks are
stored with every check of §7; if one fails to store, the transaction is undone and our spine is
restored exactly. A rollback below the pinned height is refused whenever this node holds the
pinned block. Manifests arrive only inside stored spine blocks (27 has no manifest RPC).
Node-local: the sync mechanics are the reference's policy, not consensus — the peer is chosen by the
weight it claims (only a reason to look; the decision counts the signatures its blocks carry), the
common-block search probes one height per round trip, the branch weighed is only what one peer
serves up to fork height + 100, and the rollback has no depth limit other than the pin and that
100-height search.
How to compute it. As stated.
Rule activation. None.
Rejections and errors. Local; a store failure stops the walk.
Vector. computed: our branch above the common block = two blocks of 8 signatures (16); theirs
= two blocks of 8 and one of 6 (22): theirs is followed. Equal sums keep ours.
Test cases · §8
3 cases · 3 valid
Their 22 signatures beat our 16
Loading the test widget…
Equal sums keep ours
Loading the test widget…
A failing block ends their branch
Loading the test widget…
Defects to match. None.
9. Chain identity, the finalized height, the pin and the hierarchy
Purpose. How a reader tells which main chain a manifest belongs to, what the spine gives the main chain, and what the hierarchy code does.
Inputs. The main chain's genesis hash (06); spine_hierarchy_enabled (false on both
chains), spine_level 1, spine_parent_period_multiplier 10; a release's spine pin (30).
Output and effect. Every manifest carries the main chain's 32-byte genesis hash (§4), and the
latest-manifest lookups filter by it; /node/info reports spine_genesis_hash (the spine block 0
hash) and spine_height. Rule checkpoint_finality (finality from the spine blocks): the reference height of the newest stored
spine block below the first one whose deferred checks still wait (§7) is the main chain's
finalized height — the floor below which no main-chain reorganisation is allowed (24 §3); 0
when there is none; a failed read is a fault, never 0. /spine/blocks/:height serves a spine block
by height. A release may ship a spine pin (height, hash; 30): a block at the pinned height
whose hash differs is refused at storage ("SpineBlockNotPinned", whatever the validation mode,
genesis included), and at start-up the stored block at that height is compared; on a conflict, with
auto_resync on the node writes the resync marker and stops, so the next start sets the chain
aside and rebuilds (30); if a marker is already there and the conflict persists it refuses to
start and says the self-heal is cooling down or the pin is wrong; with auto_resync off it refuses
to start. A node holding the pinned block never rolls its spine below it (§8). The spine chain id
strings (zoobc-spine-dev, zoobc-spine-test) are configuration only and enter no hash. The
hierarchy (levels above the spine with periods × 10 per level, child-state aggregation as SHA3-256
of count ‖ child hashes, manifests propagated upward) and the multi-chain registration are
compiled but unreachable on both chains: nothing registers a chain or a level, so the spine blocksmith's
multi-chain manifest list is always empty.
How to compute it. As stated.
Rule activation. checkpoint_finality (finality from the spine blocks), active from height 0
on every chain.
Rejections and errors. "SpineBlockNotPinned"; otherwise none.
Vector. computed: spine block 0 of either chain carries the 11 genesis keys of its spine
genesis file, a zero seed, a zero 64-byte signature and cumulative_difficulty "0"; its hash =
SHA3-256(header ‖ 64 zero bytes), and the node's spine pin names it as 0 <that hash> (30 §4b; the
relaunch re-derives the pin for the genesis it builds, 30 §9a). On the shipped files' own timestamps
spine block 0 is 7CD929C4D52D9C9455ED179D24A65F90ECBF3D1A3E1214A19611635791B3545C (TestNet) and
5876B908090A5BCA4BD735DD96A559FD8FBBE64C1419C053DE227BE3CACCEEF3 (DevNet). Every manifest of a chain
carries that chain's main genesis hash; for the shipped DevNet genesis file it is, computed (06 §3),
A37B1692EC47C7B17A7F9CB4C13CC8A73A1D5E843565A5733B9DA2A544DF99F8. The relaunch sets the genesis
timestamp at launch, so the hash a live chain's manifests carry is the one it announces on launch day
(GET /api/v1/node/info).
Test cases · §9
3 cases · 3 valid
Spine block 0 of the shipped TestNet spine genesis file
Loading the test widget…
Spine block 0 of the shipped DevNet spine genesis file
Loading the test widget…
The chain identity a manifest of the shipped DevNet genesis file carries
Loading the test widget…
Defects to match. An implementation needs none of the hierarchy to be compatible; it must accept manifests
whose chain_type is 0 and ignore the chain-id strings.
10. Data model, and the consensus/local split
Purpose. What an implementation stores for the spine, and which parts are consensus.
Tables (an implementation may store them differently; the operations below are what it must be able to answer):
| Table | Columns (type) | Key / index | Operations |
|---|---|---|---|
spine_block |
id (i64), block_hash (32 bytes), previous_block_hash (32), height (u32), timestamp (i64), block_seed (64), block_signature (64 or 4 + 96 n), cumulative_difficulty (decimal text, this node's weight), blocksmith_public_key (32), total_amount, total_fee, total_coinbase (i64, 0), version (u32, 1), payload_length (u32), payload_hash (32), merkle_root, merkle_tree (bytes), reference_block_height (u32), payload (bytes, the local serialised payload) |
unique on height |
the block at height h; the block with the greatest height (the tip); every block with height above h is deleted on a spine rollback (§8); the greatest reference_block_height among blocks with height below the lowest pending deferred check (the finalized height, §9) |
spine_public_key |
node_public_key (32), node_id (i64), public_key_action (0 add, 1 remove), main_block_height (u32), latest (0/1), height (u32, spine height) |
primary key (node_public_key, height) |
append a change: the key's earlier rows get latest = 0, the new row latest = 1; the active set at spine height H = keys whose newest row with height ≤ H is an add (§3); a rollback deletes rows with height above the target and re-marks, per key, the newest remaining row latest = 1 |
spine_block_manifest |
id (i64), full_file_hash (32), file_chunk_hashes (32 × k), manifest_reference_height (u32), manifest_spine_block_height (u32; 0 = not yet published), chain_type (u32), manifest_type (u32, 0), expiration_timestamp (i64), chain_genesis_hash (32) |
primary key (id, manifest_spine_block_height) |
store a carried manifest under its spine height (the unpublished height-0 row of that id is replaced); the newest manifests of a chain (one row per id at its greatest spine height; ordered by reference height descending, then spine height descending, then id descending); a rollback deletes rows with spine height above the target; rows are never deleted otherwise |
spine_deferred_check |
spine_height (u32), block_hash (32) |
primary key spine_height |
written with a block stored ahead of the main chain (§7); read in spine-height order; a row is deleted only together with its block (confirmed gone) or when its checks pass; a rollback deletes rows above the target |
spine_promise (local; the signing commitments) |
height (u32), hash (32, the identity committed to), bar (u32, its required spine signatures), ts (i64, the committed candidate's timestamp), proto (bytes, the stripped spine block candidate as a Block message, 27), signed (32 × m, the identities signed at that height) |
primary key height |
written (replaced) whenever the signing commitment at a height is made or moved (§6a); rows at or below the spine tip are deleted at start and as heights settle; restored at start |
spine_refused (local; the non-signing statements given) |
height (u32), identity (32) |
primary key (height, identity) |
written before a non-signing statement is signed (§6b; at most 1,024 per height); rows at or below the spine tip are deleted at start and as heights settle; restored at start |
spine_late_refusal |
spine_height (u32), refused_block_hash (32), node_public_key (32), signature (64) |
primary key (spine_height, node_public_key) |
the non-signing statements a stored block carried; always empty, since a block carrying one is refused (§7); deleted above the target on a rollback |
Consensus for the spine: §1 fields and §2 bytes, §3 derivation of the spine signers and the
expected key changes, §6 required spine signatures (fallback, late, cap and the counting spine
signers included) and aggregate format, §6c lateness, §7 checks and the storage effects, §8's
more-signatures rule; the non-signing statement digest of §6b (a non-signing statement is shown to
other registered nodes and must verify there, and is evidence for SpineEquivocationReport, 35).
Local but binding on an honest registered node: the signing commitment of §6a (an
implementation that signs a candidate and gives a non-signing statement on it is charged, 35).
Local: the production timing and draw attempt (§5), the collection order, the non-signing
round's order and the re-collection, the sync cadence, the deferred-check cadence, the manifest
expiry arithmetic (a value another node computed differently is still accepted). Effect on the main
chain: the manifests — the pruning horizon (13 §8), the escrow horizon (12 §5) and the snapshot
a fresh node fetches (26) — and the finalized height (24 §3).
A question about this chapter, or a statement that does not match the network? Discuss on zoobc.pro.