On this page
  1. §0 The area in one paragraph
  2. 1. The spine block
  3. 2. The payload hash
  4. 3. Public-key changes and the spine signers
  5. 4. Manifests
  6. 5. Production: timing, the spine blocksmith selection and the weight
  7. 6. The required spine signatures and the aggregate signature
  8. 6a. How a registered node decides to give its spine signature, and the signing commitment
  9. 6b. Non-signing statements and the non-signing round
  10. 6c. A late spine block
  11. 7. Validation and application of a received spine block
  12. 8. Sync and fork choice on the spine
  13. 9. Chain identity, the finalized height, the pin and the hierarchy
  14. 10. Data model, and the consensus/local split

25 — The spine chain

Edition 0.6.1 · verified against the reference implementation, version 0.6.1

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 id25-1-candidatevalid

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 commitment25-2-payloadvalid

Loading the test widget…

The worked spine block candidate's payload passes its check25-2-payload-validvalid

Loading the test widget…

A claimed payload length of 45 is refused25-2-payload-lengthinvalid

Loading the test widget…

A commitment naming main height 12,001 for a reference of 12,000 is refused25-2-commitment-heightinvalid

Loading the test widget…

A commitment of 36 bytes is refused25-2-commitment-shortinvalid

Loading the test widget…

A commitment whose difficulty is not decimal is refused25-2-commitment-decimalinvalid

Loading the test widget…

A payload hash that does not match is refused25-2-payload-hashinvalid

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:

  1. 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].
  2. Additions come from the rows in (A, R], where A = 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).
  3. 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 id25-3-genesis-signersvalid

Loading the test widget…

Late spine block 4 carries the removal of K_2 and leaves the addition of K_9 pending25-3-late-removalsvalid

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]25-3-after-latevalid

Loading the test widget…

A spine block that is not late carries the additions and the removals of its range25-3-not-latevalid

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 minimum25-4-expiryvalid

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 nodes25-5-drawvalid

Loading the test widget…

The round of a 86,600-second gap25-5-roundvalid

Loading the test widget…

A gap of exactly one period is round 125-5-round-1valid

Loading the test widget…

K_5 at a gap of 86,600 s (round 3) is drawn in round 225-5-drawn-round-2valid

Loading the test widget…

K_8 at a gap of 86,400 s is drawn in round 125-5-drawn-round-1valid

Loading the test widget…

K_1 at a gap of 86,600 s is not drawn25-5-not-drawninvalid

Loading the test widget…

A gap of 86,249 s is too early25-5-too-earlyinvalid

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:

  1. share = ceil(n × 67 / 100) computed as (n × 67 + 99) div 100 in 64-bit (rule quorum_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.
  2. req = max(share, spine_min_signatures); for a late block the floor is skipped: req = share.
  3. 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.
  4. A req of 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, late25-6-required-signaturesvalid

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 counted25-6-removed-not-countedvalid

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):

  1. 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".
  2. 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.
  3. 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), n their number; the request's refusals that verify (§6b), are by distinct keys among the counting spine signers, and name H and the identity it is committed to.
  4. Storage-time checks: the blocksmith is the one the reference seed draws for a round 1…r (§5; refuse SpineBlocksmithNotDrawn/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; refuse SpineBlockTooEarly). A candidate that storage would refuse is never committed to.
  5. A block held at H binds for good: another identity → refuse; the same identity → sign again.
  6. Refused before: an identity in its refused list at H (it gave a non-signing statement on it) → refuse ("… never signing it").
  7. The committed candidate itself: a candidate whose identity equals the commitment it holds at H is signed again, whatever its age (a lost collection can complete).
  8. 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 when candidate.timestamp > now + 150 (stamped ahead beyond the tolerance; lateness is read from the stamp, so a future stamp could claim it early).
  9. Commitment: when it holds a signing commitment at H for 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 than n − req + 1, req being the committed candidate's required spine signatures (1 when n < 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.
  10. Reference: refuse when reference < previous reference, or (spine height > 0) when reference = previous reference (an empty block); abstain when the spine signer's main tip is below the safety gap or reference > its tip − gap.
  11. 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.
  12. 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 H changed 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 commitment25-6a-commitment-bindsinvalid

Loading the test widget…

Four verified non-signing statements on P release the signing commitment and Q is signed25-6a-releasedvalid

Loading the test widget…

A request for height 5 while the tip is 3 is not judged25-6a-wrong-heightinvalid

Loading the test widget…

A spine block candidate stamped 61 s before the registered node's clock is not signed25-6a-staleinvalid

Loading the test widget…

A spine block candidate stamped 151 s ahead of the registered node's clock is not signed25-6a-aheadinvalid

Loading the test widget…

A spine block candidate the registered node stated it did not sign is never signed25-6a-refused-beforeinvalid

Loading the test widget…

A block held at the height binds for good25-6a-held-otherinvalid

Loading the test widget…

A reference that does not advance is refused25-6a-empty-blockinvalid

Loading the test widget…

A reference not yet 760 blocks below the registered node's main chain tip gets an abstention25-6a-abstain-gapinvalid

Loading the test widget…

The committed spine block candidate itself is signed again whatever its age25-6a-same-commitment-stalevalid

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 refused25-6a-late-releasedvalid

Loading the test widget…

A late candidate carrying a signer addition is refused25-6a-late-addsinvalid

Loading the test widget…

A late candidate stamped 151 s ahead of the registered node's clock is refused25-6a-late-aheadinvalid

Loading the test widget…

A commitment to a late candidate holds another late one25-6a-late-held-by-lateinvalid

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 candidate25-6b-non-signingvalid

Loading the test widget…

A second non-signing statement digest25-6b-non-signing-2valid

Loading the test widget…

A non-signing statement naming height 4 does not count toward a height-3 release25-6b-height-4-non-signinginvalid

Loading the test widget…

A repeated refuser and a key off the list count nothing25-6b-unlisted-duplicateinvalid

Loading the test widget…

A non-signing statement on a candidate after its window closed25-6b-givevalid

Loading the test widget…

No non-signing statement while the candidate's window is still open25-6b-window-openinvalid

Loading the test widget…

No non-signing statement on a candidate the registered node signed25-6b-signed-itinvalid

Loading the test widget…

A non-signing statement request without a spine block candidate25-6b-no-candidateinvalid

Loading the test widget…

No non-signing statements on a chain without a collection window25-6b-no-windowinvalid

Loading the test widget…

A candidate that does not build on the stating node's spine block 2 is refused25-6b-not-on-my-blockinvalid

Loading the test widget…

A candidate for height 4 while the stating node's tip is 2 is refused25-6b-wrong-heightinvalid

Loading the test widget…

A candidate by a key off the spine signers is refused25-6b-not-activeinvalid

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:

  1. needs the spine signatures of more than half of its counting spine signers, with no spine_min_signatures floor and with the cap of §6 step 3 (§6: req = n div 2 + 1, capped at n − 1 for 3, 4 or 5);
  2. 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);
  3. 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;
  4. 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 1125-6c-late-validvalid

Loading the test widget…

A candidate stamped T0 + 97,199 is not late: 7 signatures of the 8 required are refused25-6c-not-lateinvalid

Loading the test widget…

A late candidate with 5 signatures of the 6 required is refused25-6c-late-shortinvalid

Loading the test widget…

A late candidate removing two registered nodes (9 counting) needs 525-6c-late-removes-twovalid

Loading the test widget…

A late candidate with 6 signatures that adds a node key is refused25-6c-adds-keyinvalid

Loading the test widget…

DevNet: a block is late from T0 + 14,400, four periods after the previous block25-6c-devnet-latevalid

Loading the test widget…

DevNet: a block stamped T0 + 14,399 is a fallback block, not late25-6c-devnet-not-latevalid

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 required25-7-singleinvalid

Loading the test widget…

An aggregate of 8 listed signers, the blocksmith first, passes the count25-7-eightvalid

Loading the test widget…

An aggregate of 7 is one short25-7-seveninvalid

Loading the test widget…

A block three periods after its predecessor (a fallback block, late as well) passes with 6 of 1125-7-fallbackvalid

Loading the test widget…

A signer listed twice in the aggregate25-7-duplicateinvalid

Loading the test widget…

A signer off the list25-7-unlistedinvalid

Loading the test widget…

An aggregate without the blocksmith25-7-no-blocksmithinvalid

Loading the test widget…

8 entries, one by a key the block removes: 7 counted of the 7 required of 10 counting spine signers25-7-removed-onevalid

Loading the test widget…

8 entries, two by keys the block removes: 6 counted of the 7 required25-7-removed-twoinvalid

Loading the test widget…

A spine block carrying a non-signing statement is invalid25-7-statementsinvalid

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 1625-8-theirsvalid

Loading the test widget…

Equal sums keep ours25-8-tievalid

Loading the test widget…

A failing block ends their branch25-8-failingvalid

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 file25-9-spine-genesis-testnetvalid

Loading the test widget…

Spine block 0 of the shipped DevNet spine genesis file25-9-spine-genesis-devnetvalid

Loading the test widget…

The chain identity a manifest of the shipped DevNet genesis file carries25-9-devnet-chain-identityvalid

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.