On this page
  1. §0 The area in one paragraph
  2. 1. When a snapshot is taken
  3. 2. The snapshot document
  4. 3. Chunks, names and the directory
  5. 4. Serving chunks
  6. 5. When a node fast-syncs, and the manifest walk
  7. 6. Download and verification
  8. 7. Attesting and applying the snapshot
  9. 8. Catch-up
  10. 9. Retention and the prune horizon
  11. 10a. The snapshot attestation
  12. 10b. The archive
  13. 10c. Data model
  14. 11. Consensus and local

26 — Snapshots and fast sync

Edition 0.6.1 · verified against the reference implementation, version 0.6.1

Out of scope the spine block that carries a manifest and the manifest's own fields (25 §1–§4); the main-chain pruning that the manifests drive (13 §8, 22 §14); the fork resolver that can trigger a snapshot recovery (24); the gRPC transport (27)

§0 The area in one paragraph

Every main_snapshot_interval blocks (TestNet 172,800, DevNet 240) a node writes a snapshot: a single CBOR document holding, as of the snapshot height S = h − main_snapshot_min_height (TestNet 760, DevNet 80 below the tip h that triggered it), the newest version of every row of the 65 state tables (columns in name order; a table the writer never created is carried empty; every table has an owning rule, active from height 0 on every chain, so all 65 travel), the block headers of the 1,440 blocks below S and S itself (min(S − 60, S − main_snapshot_min_height, S − 1,440) to S: the blocks every node holds, which the readiness gate counts, 29 §4b), the recent transactions, the funded and escrowed transactions with the headers of their blocks, and the published receipts from S − main_snapshot_min_height to S, encoded with every map's keys in byte order and every blob as a CBOR byte string. Every node writes the same bytes however it reached S: the document is read from a view of the database pinned when block S committed and leaves out every row the prune at S deletes. The document is cut into 102,400-byte chunks, each named by the base64url form of its SHA3-256 hash and stored under a directory named by the base64url form of the whole document's SHA3-256; the hashes, the snapshot height, an expiry and the chain identity form the manifest the node's next spine block publishes (25). A node more than 100 blocks behind that holds a usable manifest above its own height fast-syncs: it walks the newest manifests, newest first, fetches the chunks of the first snapshot someone serves (registered peers' snapshot directories, else the decentralised storage's holders), verifies every chunk against its name and the whole against the manifest, refuses any document whose SnapshotFormat is not 3, attests a seed-chosen sample of the state the snapshot would leave to registered peers on a dry run, and only then applies it: every non-genesis row of the trimmed tables and every row of the carried state tables is replaced, every transaction and ledger row the node held deleted, the newest row of every key re-marked as current, the readiness gate rebuilt from the carried decision rows and headers; then it pulls the remaining blocks through the ordinary validation and application path. Nothing in a snapshot is signed: its authority is the manifest in a spine block signed by the spine signers. The archive: the decentralised storage, not every node, keeps every snapshot from block 0, each snapshot's chunks held by five registered nodes chosen by lot; a snapshot joins it once two thirds of the registry have attested it on the main chain, and every node keeps only its last three snapshots locally.

Test cases · §0

1 case · 1 valid · 1 reference

The snapshot interval and depth on each chain26-0-intervalsvalidreference

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

testnet_interval
172800
testnet_depth
760
devnet_interval
240
devnet_depth
80
depth_when_zero
1440
chunk_size
102400
state_tables
65
block_reach
1440
locally_kept
3
archive_holders
5

1. When a snapshot is taken

Purpose. The schedule and the height a snapshot describes.

Inputs. main_snapshot_interval (TestNet 172,800 / DevNet 240), main_snapshot_min_height (TestNet 760 / DevNet 80; 1,440 when 0); every applied block (21 §1, post-commit); the node's key.

Output and effect. A snapshot is requested for a block of height H when interval ≠ 0, H > min_height, H mod interval = 0 and no snapshot at or above H was taken yet; it is built for the snapshot height S = H − min_height ("Invalid snapshot height" when H ≤ min_height). The manifest's reference height is S; its expiry is timestamp(H) + max(snapshot_manifest_expiration_seconds, 3 × interval × block_time_interval, 2,592,000) (25 §4). After each snapshot the node prunes its local copies to the three newest generations (§9). A node builds its snapshot not at the exact trigger height but offset blocks later, offset = FNV-1a(node_public_key) mod (window + 1) with window = min(interval / 10, 60) (0…60 on TestNet, 0…24 on DevNet), so the fleet does not all encode at once; the content is read as of S, so every node's bytes and full_file_hash are identical. The content is read from a view of the database pinned when block S commits (a read transaction on a read-only connection, opened under the chain lock before any later block can commit); the document is built from that view once the stagger offset has passed and the view released; at the trigger H it is published (manifest, §3) only if the main chain still holds, at S, the block hash the view was pinned at. A node that did not apply block S while running (it started later, or rebuilt) does not build the snapshot of S. A build whose consensus-parameter reads (the prune horizons of §2) failed is not built ("the snapshot of height N is not built: <fault>"), so no node publishes bytes computed from a default. The snapshot depth must exceed max_rollback_height by at least 20 (the genesis builder's check), so S is final when it is published. Node-local: the trigger is the tip height, so a node that was offline at the multiple of the interval takes no snapshot for that period (the next node to produce one feeds the spine).

How to compute it. As stated.

Rule activation. None.

Rejections and errors. None at the chain level; a failed build is logged and the next interval retried.

Vector. computed (TestNet): the first snapshot is taken at tip 172,800 for height 172,040 (depth 760); its expiry is timestamp(172,800) + max(0, 3 × 172,800 × 15 = 7,776,000, 2,592,000) = 90 days later (the newest manifest never expires anyway, §5); before it no fast sync is possible on the TestNet. computed (DevNet): tip 480 → S = 400; expiry = timestamp(480) + max(0, 3 × 240 × 15 = 10,800, 2,592,000) = 30 days later.

Test cases · §1

6 cases · 5 valid · 1 invalid · 1 reference

The first TestNet snapshot: tip 172,800, height 172,040, a 90-day manifest26-1-testnet-firstvalid

Loading the test widget…

DevNet: tip 480 gives S = 400 and a 30-day manifest26-1-devnet-480valid

Loading the test widget…

A tip that is not a multiple of the interval takes no snapshot26-1-no-triggervalid

Loading the test widget…

A node's stagger offset is FNV-1a of its key modulo the window plus one26-1-staggervalid

Loading the test widget…

A height at or below the depth has no snapshot26-1-too-lowinvalid

Loading the test widget…

Before TestNet block 172,800 there is no manifest, so no fast sync26-1-no-fast-sync-beforevalidreference

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

value
every TestNet node syncs from genesis until the first snapshot is published at tip 172,800

Defects to match. None.

2. The snapshot document

Purpose. The bytes a manifest names.

Inputs. The state at S on the view pinned at block S (the newest row per key with height ≤ S), safe = S − min_height, batch_receipt_lookback_height 40, the receipt LOOKBACK_RANGE 20, SNAPSHOT_BLOCK_REFERENCE_REACH 720, SIGNAL_WINDOW_MAX_BLOCKS 1,440 (= MIN_ROLLBACK_BLOCKS, the blocks every node keeps below its tip), TRANSACTION_REPLAY_WINDOW_SECONDS 90,000 (the one-day expiry cap 86,400 + the 3,600-s future tolerance), min_block_interval 15, the interval, max_rollback_height, receipt_lifecycle and the registry (for the prune horizons of 13 §8 / 22).

Output and effect. A CBOR (RFC 8949) map with eight keys, serialised with definite lengths, integers in their minimal width (major type 0 for ≥ 0, type 1 for negatives), blobs as byte strings (type 2), strings as text (type 3), SQL NULL as null, and every map's keys in ascending byte order (the encoder sorts them). Blocks, RecentTransactions and PublishedReceipts are omitted when empty; the other five are always written. Top level, in that order:

Key Value
Blocks array of block maps for heights min(S − 60, safe, S − reach) … S with reach = max(SNAPSHOT_BLOCK_REFERENCE_REACH, SIGNAL_WINDOW_MAX_BLOCKS) = 1,440 under rule readiness_registry_schedule (60 = 40 + 20; 720 = the oldest block a later transaction may cite — a ProofOfOwnership's block, an equivocation report's parent, a queue attendance's block; 1,440 = the readiness gate's widest signal window, 29 §4b, so a joiner's tallies count the same headers as every other node; from 0 when below 0), height 0 excluded, ascending. Both chains: S − 1,440 … S (1,441 headers once S ≥ 1,441)
EscrowedTransactions transaction maps (RecentTransactions' shape) for every transaction below the RecentTransactions window whose id is an escrow_transaction whose newest row as of S has status 0 (pending), by height then index; written even when empty
FundedBlocks block maps (the Blocks shape) for every height below the Blocks window that holds a FundedTransactions row, ascending; always written
FundedTransactions transaction maps for every transaction below the RecentTransactions window whose newest longevity record as of S still holds a deposit (13); always written, even when empty
PublishedReceipts array of receipt maps for block_height in [safe, S], height 0 excluded, by height
RecentTransactions array of transaction maps for block_height in [S − max(replay, interval + min_height), S] (from 1 when below 1), by height then index; replay = ceil(90,000 / max(min_block_interval − 2, 1)) = 6,924 blocks at 15-s blocks (25 h at the fastest legal pace); TestNet takes interval + depth = 173,560, DevNet 6,924. The local prune keeps exactly this window (13 §8)
SnapshotFormat 3
StateTables map table name → {"Columns": [names…], "Rows": [[values…]…]}, one entry for each of the 65 tables below

A block map carries BlockHash, BlockSeed, BlockSignature, BlocksmithPublicKey, CumulativeDifficulty (text), Height, ID, MerkleRoot, MerkleTree, PayloadHash, PayloadLength, PreviousBlockHash, ReferenceBlockHeight, Timestamp, TotalAmount, TotalCoinBase, TotalFee, Version — a key whose value is 0 or empty is omitted. A transaction map carries BlockHeight, BlockID, Fee, ID, Message, MultisigChild, RecipientAccountAddress, SenderAccountAddress, Signature, Timestamp, TransactionBodyBytes, TransactionBodyLength, TransactionHash, TransactionIndex, TransactionType, Version, plus Survival only when Version ≥ 2, Expiry only when Version ≥ 3 and EscrowBytes only when present, with the same omission rule. A receipt map carries BlockHeight, IntermediateHashes, PublishedIndex, RMRLinked, RMRLinkedIndex and Receipt → the eight receipt fields of 23 §1 by name, same omission rule.

State tables. For each table of the list, in that order (the CBOR map then sorts the names):

  1. Columns = the table's column names sorted by name in byte order, latest removed; the bytes follow the state, never a node's schema history (a column added later sits where the sort puts it). Every table has one owning rule (its gate, listed below); a table travels only while its gate is active at S, and the dataset_object column last_billing_height travels only under dataset_rent_object_clock. Every gate is active from height 0 on every chain, so all 65 tables and every column travel.
  2. A table the writer never created is written as {"Columns": [], "Rows": []}, so every snapshot names all 65 tables.
  3. Rows = the selected rows as arrays in that column order; for account_balance and account_token_balance the spendable_balance value is replaced by balance (a spendable balance below the balance is a node's own pool reservation, not chain state); a value is written by its stored type: integer, text, blob or null; a real value is written as its text.
  4. Row selection: a versioned table with a key → the row with the greatest height ≤ S per key (node_registry additionally every row with height in [safe, S]); an unversioned table with a height column → every row with height ≤ S; a table without a height column → every row; ordered by the key then the height (by the height when the key is empty).
  5. The prune filter: before selection every table is filtered to the rows the prune at height S keeps, so a node whose own prune lags and a node restored from an earlier snapshot write the same rows. With lifecycle = max(max(100, 2 × registered nodes) + 1, receipt_lifecycle), receipt = S − lifecycle (nothing is filtered while S ≤ lifecycle), floor = min(receipt, S − max_rollback_height), cycle = the snapshot cycle (22): superseded versions (latest = 0) of node_registry (by id), participation_score, node_liveness, queue_state (by node_id) and account_balance (by address) are left out when their height is below floor and a newer version of the same key sits at or below floor; score_unit_clock rows below receipt; queue_attendance rows below receipt whose window + 2 ≤ the newest evaluated window; skipped_blocksmith below floor; fee-vote commitments and reveals below min(receipt, S − (cycle + rollback)); oracle_attestation rows of resolved events below receipt (other than parameter ZBCGOV1: and release ZBCREL1: votes), parameter votes below the vote window start for cycle + rollback, release votes below S − (release window + rollback); pending_transaction executed envelopes and superseded versions below floor, and their pending_signature rows once no pending version at or below floor remains. The prune deletes the same rows (13 §8, 22).

The 65 tables (key; height column; v versioned, u unversioned with a height column, n no height column; the gate when a table has one of its own — every other table's gate is the relaunch set, active from 0), in the writer's order:

# Table Key Height Kind Gate
1 account_balance account_address block_height v
2 account_token_balance account_address, token_id block_height v
3 account_split_policy account_address block_height v
4 account_group group_address block_height v
5 account_group_member member_address block_height v
6 spent_foreign_message msg_hash block_height u
7 token token_id block_height v
8 account_dataset setter_account_address, recipient_account_address, property height v
9 dataset_object object_id height v (column last_billing_height: dataset_rent_object_clock)
10 dataset_delete_vote object_id, voter_address height v
11 stored_file file_root block_height v
12 storage_proof piece_id, epoch, prover_address block_height u
13 longevity target_tx_id block_height v
14 longevity_funder target_tx_id, funder_address block_height v
15 longevity_deposit target_tx_id, seq block_height v
16 longevity_vote target_tx_id, voter_address block_height v
17 file_deposit object_id, seq block_height v
18 escrow_transaction id block_height v
19 escrow_request id block_height v
20 liquid_payment_transaction id block_height v
21 trigger_schedule trigger_id block_height v
22 pending_transaction transaction_hash block_height v
23 pending_signature account_address, transaction_hash block_height v
24 multisignature_info multisig_address block_height v
25 multisignature_participant multisig_address, account_address block_height v
26 swap_offer id block_height v
27 market id block_height v
28 order_book id block_height v
29 trade taker_order_id, maker_order_id block_height u
30 app id block_height v
31 app_settlement app_id block_height v
32 node_registry id height v (+ recent history)
33 participation_score node_id height v
34 node_admission_timestamp (none) block_height v
35 skipped_blocksmith blocksmith_public_key, blocksmith_index block_height u
36 node_liveness node_id height v
37 queue_attendance node_id, window height u
38 queue_state node_id height v
39 liveness_expulsion node_public_key, height height u
40 score_unit_clock height height u
41 survival_state height height u survival_mode
42 readiness_bundle_decision bundle_id height v readiness_decision_state
43 lock_release node_public_key, height height u
44 node_claim node_id, height height u
45 node_exit node_id, height height u
46 seat_change node_id, height height u
47 roll_call node_id height u
48 equivocation_charge node_id, equivocated_height height u
49 spine_equivocation_charge node_id, spine_height height u spine_equivocation_report
50 archival_registry node_public_key block_height v
51 gateway_registry gateway_key block_height v
52 relay_registry relay_key block_height v
53 release_authority id block_height v
54 release_registry version block_height v
55 consensus_parameters parameter_name — n
56 consensus_parameter_change id block_height u
57 fee_scale (none) block_height v
58 fee_vote_commitment_vote voter_address block_height u
59 fee_vote_reveal_vote voter_address block_height u
60 oracle_attestation event_id, attester block_height u
61 oracle_result event_id resolved_height u
62 bridge_withdrawal_request trigger_hash block_height v bridge_withdrawal_credit
63 network_topology period_height period_height u
64 bridge_coin token_id — n
65 chain_metadata key — n escrow_commission_nonnegative

survival_state (columns active, height) holds the survival-mode flag per height (19); both chains set survival_min_producers 5, so a row is written for every block applied above 0 (a chain with 0 writes none). readiness_bundle_decision (bundle_id, effective_height, height, latest) is the readiness gate's decision row (29 §4b): the newest row per bundle travels, so a joiner never recomputes an activation height from headers it does not hold. chain_metadata travels whole: every row is a genesis-builder constant with no runtime writer (the supply bound of SendZBC and the emission ceiling among them, 06). Two tables carry texts the genesis builder writes of its own: the description beside every row of consensus_parameters and the nine values of chain_metadata. They are in no hash but this document's, so they are listed byte for byte in 06 §13: an implementation whose genesis wrote other texts shares the chain's genesis hash and still writes documents that hash differently from every other node's. A governance change of a parameter and its rollback change the row's value only (07 §8), so the text stays the genesis text on every node. spine_equivocation_charge is the charge record of SpineEquivocationReport (35); bridge_withdrawal_request the bridge's withdrawal request row (34). The storage audit ledger (storage_missing, storage_unconfirmed) is node-local and not a snapshot table; so are spine_promise, spine_refused and the rule-activation record. The archive's membership travels in oracle_result (§10b).

How to compute it. As stated; the SHA3-256 of the document is the manifest's full_file_hash.

Rule activation. snapshot_funded_transactions (the FundedTransactions and FundedBlocks sections), readiness_registry_schedule (the 1,440-block reach of Blocks), and the table gates survival_mode, readiness_decision_state, spine_equivocation_report, bridge_withdrawal_credit, escrow_commission_nonnegative and dataset_rent_object_clock; all active from height 0 on every chain.

Rejections and errors. A reader refuses SnapshotFormat ≠ 3 ("Snapshot format N is not accepted…"), a missing StateTables ("Snapshot has no StateTables section"), a missing FundedTransactions ("snapshot has no FundedTransactions section (rule snapshot_funded_transactions): built before the rule; this node would hold nothing of what the deposits keep alive"), a missing FundedBlocks ("snapshot has no FundedBlocks section: this node would hold funded transactions without the headers of their blocks"), a missing EscrowedTransactions ("snapshot has no EscrowedTransactions section: this node would lack the transactions of pending escrows"), and the table errors of §7.

Vector. computed: a minimal document, the encoding rules only (a real document names all 65 tables). INPUT: EscrowedTransactions [], FundedBlocks [], FundedTransactions [], SnapshotFormat 3, StateTables = { survival_state: Columns ["active", "height"], Rows [[0, 1], [1, 2]]; bridge_coin: Columns [], Rows [] } (Blocks, RecentTransactions, PublishedReceipts empty, so absent). EXPECTED OUTPUT (165 bytes): A5 74 "EscrowedTransactions" 80 6C "FundedBlocks" 80 72 "FundedTransactions" 80 6E "SnapshotFormat" 03 6B "StateTables" A2 6B "bridge_coin" A2 67 "Columns" 80 64 "Rows" 80 6E "survival_state" A2 67 "Columns" 82 66 "active" 66 "height" 64 "Rows" 82 82 00 01 82 01 02, i.e. A574457363726F7765645472616E73616374696F6E73806C46756E646564426C6F636B73807246756E6465645472616E73616374696F6E73806E536E617073686F74466F726D6174036B53746174655461626C6573A26B6272696467655F636F696EA267436F6C756D6E738064526F7773806E737572766976616C5F7374617465A267436F6C756D6E7382666163746976656668656967687464526F777382820001820102; full_file_hash = 169263781B6EF81747432AA279B3D23508508E046D77728BC524B78C8CD1683B (one chunk, whose hash is the same), directory FpJjeBtu-BdHQyqiebPSNQhQjgRtd3KLxSS3jIzRaDs=. INVALID: the same document with SnapshotFormat 2 → "Snapshot format 2 is not accepted…"; without EscrowedTransactions → "snapshot has no EscrowedTransactions section: this node would lack the transactions of pending escrows". computed: TestNet replay = ceil(90,000 / 13) = 6,924 < 172,800 + 760, so the RecentTransactions window is [S − 173,560, S]. computed (the Blocks window): TestNet S = 172,040 → min(171,980, 171,280, 170,600) = 170,600, so blocks 170,600 … 172,040 (1,441 headers); DevNet S = 400 → the bound is below 0, so blocks 1 … 400.

Test cases · §2

13 cases · 7 valid · 6 invalid

A minimal document: sorted keys, minimal integers, 165 bytes26-2-minimalvalid

Loading the test widget…

The minimal document is one chunk whose hash is the document's26-2-minimal-one-chunkvalid

Loading the test widget…

Blobs are byte strings, text is text, negatives use major type 126-2-bytes-negativevalid

Loading the test widget…

A document of format 2 is refused26-2-format-2invalid

Loading the test widget…

A document without SnapshotFormat reads as format 1 and is refused26-2-no-formatinvalid

Loading the test widget…

A document without EscrowedTransactions is refused26-2-no-escrowedinvalid

Loading the test widget…

A document without FundedBlocks is refused26-2-no-funded-blocksinvalid

Loading the test widget…

A document without FundedTransactions is refused26-2-no-funded-transactionsinvalid

Loading the test widget…

A document without StateTables is refused26-2-no-state-tablesinvalid

Loading the test widget…

TestNet S = 172,040: the RecentTransactions window is interval + depth, the Blocks from 170,600 (1,441 headers)26-2-testnet-windowsvalid

Loading the test widget…

DevNet: 6,924 blocks of transactions and the headers from S - 1,44026-2-devnet-windowsvalid

Loading the test widget…

DevNet S = 400: the bound is below 0, so blocks 1 to 40026-2-devnet-earlyvalid

Loading the test widget…

The 65 state tables in the writer's order, and the five with a gate of their own26-2-table-listvalid

Loading the test widget…

Defects to match. (1) The writer's insertion order is not the wire order: the encoder sorts keys, so an implementation must sort. (2) Zero and empty block, transaction and receipt fields are absent, so a reader must default them. (3) Every version of node_admission_timestamp travels because the spec gives it no key. (4) A FundedTransactions row whose header the writer lacks, or a funded target with no transaction row, is only logged, never refused (every honest node lacks it alike). (5) EscrowedTransactions takes the escrows whose newest row as of S is pending. (6) An escrow's original transaction inside the RecentTransactions window travels there, not in EscrowedTransactions. (7) The PublishedReceipts window is main_snapshot_min_height deep, not the 40-block receipt lookback of 23; with the live depths (760 / 80) it covers the lookback, but a chain whose genesis set the depth below 40 would let a fast-synced node accept a receipt a full node refuses as already published.

3. Chunks, names and the directory

Purpose. How the document is cut and addressed.

Inputs. The document bytes; SNAPSHOT_CHUNK_SIZE_BYTES 102,400; the snapshot directory $HOME/.zoobc/snapshots.

Output and effect. Chunk i = bytes [102,400 i, 102,400 (i+1)) (the last one shorter); chunk_hash_i = SHA3-256(chunk_i); the manifest's file_chunk_hashes = the concatenation in order; full_file_hash = SHA3-256(document). Names: base64url with = padding (alphabet A–Z a–z 0–9 - _), 44 characters for 32 bytes. The chunks are written to <snapshot dir>/<base64url(full_file_hash)>/<base64url(chunk_hash_i)>.

How to compute it. As stated.

Rule activation. None.

Rejections and errors. None.

Vector. computed: a 250,000-byte document whose byte i is i mod 251 → three chunks of 102,400, 102,400 and 45,200 bytes; full_file_hash B295B329983547C2ADD8C42F779B9987C2B52839B73D7957DAC5798A1678DC30, directory spWzKZg1R8Kt2MQvd5uZh8K1KDm3PXlX2sV5ihZ43DA=; chunk names FPYeC1MqlWaAE1nDI4zPwltmssZIFTk0mP_B9g_HMeY=, 07SBXgM30orafWCfJQNlXLVHXZFcPEqaldmRvno0MNs=, I90pRVbfeGcHD-sHhBD8KklO6Iq2YxVYpnEI0bznCHg=.

Test cases · §3

2 cases · 2 valid

A 250,000-byte document cut into three chunks26-3-three-chunksvalid

Loading the test widget…

A document of exactly two chunk sizes makes two full chunks26-3-exact-multiplevalid

Loading the test widget…

Defects to match. None.

4. Serving chunks

Purpose. What a peer answers to a chunk request.

Inputs. FileDownloadRequest { SnapshotHash: bytes, FileChunkNames: [string] }; at most 32 names per request, at most 128 characters per name.

Output and effect. FileDownloadResponse { FileChunks: [bytes], Failed: [string] }: for each name in order, the file <dir>/<base64url(SnapshotHash)>/<name> is appended to FileChunks when it exists and is ≤ 102,400 bytes; otherwise the name goes to Failed (also when empty, longer than 128 characters, or containing .., / or \). No names → INVALID_ARGUMENT "request does not contain any file name"; more than 32 → "Too many file chunks requested"; an empty hash → "empty snapshot hash".

How to compute it. As stated.

Rule activation. None.

Rejections and errors. As listed.

Vector. computed: a request for the three names of §3's vector returns three FileChunks in request order and an empty Failed; a request naming ../x returns it in Failed.

Node-local: a served chunk is not re-hashed by the server; the client verifies (§6).

Test cases · §4

8 cases · 5 valid · 3 invalid

A request for the three names returns three chunks in request order26-4-serve-threevalid

Loading the test widget…

Chunks come back in the order they were asked for26-4-serve-reorderedvalid

Loading the test widget…

A name with '..' goes to Failed26-4-traversalvalid

Loading the test widget…

An unknown name goes to Failed26-4-unknown-namevalid

Loading the test widget…

A name over 128 characters goes to Failed26-4-long-namevalid

Loading the test widget…

An empty snapshot hash is refused26-4-empty-hashinvalid

Loading the test widget…

A request without names is refused26-4-no-namesinvalid

Loading the test widget…

More than 32 names are refused26-4-too-manyinvalid

Loading the test widget…

Defects to match. None.

5. When a node fast-syncs, and the manifest walk

Purpose. The decision and the sync points, newest to oldest.

Inputs. The best peer's height (24 §2) and ours; MIN_BLOCKS_FOR_FAST_SYNC 100; the local manifests of this chain's identity (received through spine blocks, 25 §4, including spine blocks stored ahead of the main chain); the local spine blocks; the walk limit 8 manifests, the unavailable-snapshot pause 600 s, the refused-manifest pause 1,800 s.

Output and effect. Fast sync is attempted, before block-by-block sync, when the node is at least 100 blocks behind, the newest manifest of its chain has a reference height above the local height, and the walk below finds at least one sync point. The newest manifest of a chain is usable even past its wall-clock expiry (a stalled chain or a long-offline node keeps a fast-sync target; the decision only logs it). Node-local: the decision keeps the walk's result for 60 s per (network height, local height, newest manifest hash), so repeated sync passes do not re-verify the same sync points; the memory is cleared when a fast sync starts.

The walk (with a target height and a floor height): take the newest 8 manifests of this chain (one row per manifest id, at its newest spine height; ordered by reference height descending, then spine height descending, then id descending) and keep, in that order, each manifest that passes:

  1. refused: a manifest whose state registered peers contradicted within the last 1,800 s (§10a) ends the walk — an error when it is the first, otherwise the points found so far are the list (an older snapshot is no way around a contradicted state);
  2. unavailable: a manifest that nobody served within the last 600 s is skipped;
  3. a reference height above the target is skipped;
  4. a reference height at or below floor is skipped (the normal sync passes the node's own height, so a node is never cut back to an older state; the fork resolver's snapshot recovery passes 0);
  5. its spine block (at manifest_spine_block_height) must be held locally and be a valid sync point: its previous spine block held; the spine signers as of that previous block read (a failed read is an error: "Signer list of the sync point's previous spine block could not be read: …", "signer list" meaning the spine signers); no spine signers means it is not a sync point; and its signatures by keys of its counting spine signers (those spine signers minus the keys the block itself removes, 25 §6), each verifying over the 204 header bytes, reach the block's own required spine signatures (25 §6: fallback, late and cap included, computed over the counting spine signers).

No manifest left → "No valid sync point among n manifest(s): <why the last was left out>". The fast sync then tries the points in order (§6): bytes that do not match the manifest end the attempt (never a step down to an older state); a snapshot that nobody serves is marked unavailable for 600 s and the next point is tried; with none left, linear sync runs ("No snapshot could be fetched: n manifest(s) tried, the last said: … (linear sync is next)"). The fork resolver may also start a fast sync when no common block is found or the node is wedged (24), with floor 0. Node-local: the reference keeps the walk's memory of unavailable and refused manifests in memory only (§10c).

How to compute it. As stated.

Rule activation. None.

Rejections and errors. "No manifest for this chain", "No valid sync point among …", "Manifest refused m min ago: its state disagreed with registered peers", "Previous spine block of the sync point not found", "Sync already in progress".

Vector. computed: a node at height 1,000 with manifests at references 1,840 (purged everywhere), 1,600 and 1,360 (DevNet, interval 240): the walk lists 1,840, 1,600, 1,360; 1,840 fails to download and is marked unavailable; 1,600 is fetched and applied. With the node at 1,700 the floor leaves only 1,840, and when it cannot be fetched the node syncs block by block. computed (TestNet): no manifest exists before block 172,800, so until then every node syncs from genesis.

Test cases · §5

10 cases · 7 valid · 3 invalid · 1 reference

A node at 1,000: the walk lists 1,840, 1,600 and 1,36026-5-walkvalid

Loading the test widget…

After 1,840 failed to download it is skipped and 1,600 is the first point26-5-walk-unavailablevalid

Loading the test widget…

At height 1,700 the floor leaves only 1,84026-5-walk-floorvalid

Loading the test widget…

At 1,700 with 1,840 unavailable no sync point is left (block-by-block sync)26-5-walk-noneinvalid

Loading the test widget…

A refused newest manifest ends the walk with an error26-5-walk-refusedinvalid

Loading the test widget…

A refused manifest after a usable one ends the walk there26-5-walk-refused-latervalid

Loading the test widget…

A manifest above the target is skipped26-5-walk-aheadvalid

Loading the test widget…

No manifest at all26-5-walk-emptyinvalid

Loading the test widget…

Only the newest 8 manifests are walked26-5-walk-limitvalid

Loading the test widget…

TestNet: no manifest before block 172,80026-5-testnet-genesis-syncvalidreference

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

value
until the first manifest every node syncs from genesis
min_blocks_behind
100

Defects to match. (1) The sync point's spine block is re-counted against its required spine signatures but its other checks are those of 25 §7 run when it was stored; a block stored ahead of the main chain is used before its deferred checks have run (they run once the node's main chain reaches the reference; a mismatch stops the node, 25 §7).

6. Download and verification

Purpose. Getting the bytes and proving they are the manifest's.

Inputs. The manifest; the connected registered peers (all connected peers while the node's height is at most 10); the decentralised storage (§10b): this node's piece store and snapshot directory, then the chunk's holders, then every other registered node (GetStoragePiece, 27).

Output and effect. The chunks are fetched one by one in manifest order. Chunk i is first requested from the peers' snapshot directories (§4, one name per request, 30-second deadline, peers in order until one answers); its bytes are accepted only when their SHA3-256 equals the manifest's i-th chunk hash. When no peer serves it, it is taken from the decentralised storage: this node's own copy (piece store or snapshot directory), else the chunk's holders in their rendezvous order (§10b), else every other registered node, by its chunk hash as the piece id, the first verified copy winning. A holder serves the chunks of an archive-only snapshot (older than the three newest archived snapshots) only on a request signed by a registered node (§10b); an unregistered joiner therefore fast-syncs only from the newest snapshots, which every holder serves to anyone. Bytes that do not hash to the chunk's hash fail the attempt as invalid ("Chunk i verification failed"); a chunk nobody serves makes the snapshot unavailable (§5) with the storage's reason. Then the chunks are concatenated in manifest order and SHA3-256(all) = full_file_hash is required ("Full file hash mismatch"). A node whose own height cannot be read skips the request (a fault is never taken for the bootstrap case). Node-local: a failed download is retried on a later sync pass; the reference holds the chunks in memory and keeps none between attempts.

How to compute it. As stated.

Rule activation. None.

Rejections and errors. "Chunk i verification failed", "Chunk i of the snapshot of height r: no peer still has its directory, and the decentralised storage did not serve it: …" (with "the holders serve this old snapshot's chunks to registered nodes only, and this node is not one" for a refused archive-only chunk), "No peers available for snapshot download", "Snapshot verification failed".

Vector. computed: for §3's document the three chunks are requested in index order, FPYeC1Mq… first; a copy of chunk 1 with one byte changed hashes to another value and ends the attempt.

Test cases · §6

3 cases · 1 valid · 2 invalid

The three chunks are requested in index order and the whole verifies26-6-in-ordervalid

Loading the test widget…

A copy of chunk 1 with one byte changed ends the attempt26-6-tamperedinvalid

Loading the test widget…

Chunks that match but a different full_file_hash fail the whole26-6-full-mismatchinvalid

Loading the test widget…

Defects to match. None.

7. Attesting and applying the snapshot

Purpose. The state a node holds after loading a snapshot of height S.

Inputs. The verified document; S; the manifest's full_file_hash (the sample seed).

Output and effect. The apply runs twice. First a dry run: the whole apply below inside one database transaction; the attestation sample (§10a) is read from the state it leaves; the transaction is rolled back. The attestation then asks peers with no database lock held. Only when it accepts is the apply run again and committed; a refused snapshot is never committed ("Snapshot refused (nothing applied): …").

The apply, in one database transaction:

  1. The format and sections are checked (§2).
  2. Trim: every row whose height is not 0 is deleted from main_block (height) and from account_balance, node_registry, archival_registry, gateway_registry, relay_registry, account_dataset, participation_score, published_receipt, escrow_transaction, pending_transaction, pending_signature, multisignature_info, multisignature_participant, skipped_blocksmith, fee_scale, fee_vote_commitment_vote, fee_vote_reveal_vote, liquid_payment_transaction, node_admission_timestamp, account_token_balance, token, swap_offer, market, order_book, app (their height columns): rows above S go as well as rows at or below it, so a node recovering from a fork by snapshot loses its fork's rows; genesis rows (height 0) survive this step. Then every row whose height field is not 0 is deleted from the transaction and ledger tables zbc_transaction, account_ledger, account_transaction_index, eth_tx_hash, merkle_tree (by block_height) and node_receipt (by reference_block_height, or by block_height when the table has no such column): a joiner holds no confirmed transaction or side index before the document's are restored, and a node recovering in place keeps nothing of its abandoned branch (a table this node does not have is skipped; a table without the height column fails the apply, "Snapshot purge: <t> has no <column> column").
  3. The Blocks are inserted as main-chain rows; the RecentTransactions inserted (ignoring duplicates); the FundedTransactions the same way, then the FundedBlocks as main-chain rows (ignoring duplicates), then the EscrowedTransactions like the recent ones.
  4. State tables, for each of the 65 tables in the list order that the document carries:
    • a table this node does not have is accepted only when it carries no rows ("Snapshot carries table <t> which this node does not have" otherwise);
    • every column named must exist on this node ("Snapshot column <t>.<c> does not exist on this node: the snapshot is from a different release");
    • every row of the table is deleted (whatever its height, genesis rows included);
    • a table with no columns must carry no rows ("Snapshot table <t> has rows but no columns");
    • the document's rows are inserted, a row with the same primary key replacing the earlier one; a value may be null, bytes, text or an integer that fits in i64;
    • for a versioned table, every row loses latest and the newest row per key regains it (a table without a key: the single newest row).
  5. The PublishedReceipts are inserted; commit.

After the commit the node's cached tip is dropped and every connected peer is marked registered or not from the snapshot's registry, so the catch-up asks the right peers at once. Then, before any block above S is applied, the readiness gate is rebuilt (29 §4b) from the carried readiness_bundle_decision rows and the carried headers, so a bundle the chain decided is in force on the joiner at once: a failed rebuild fails the sync ("Readiness gate rebuild failed: …"; among its reasons "Invalid stored readiness decision for bundle B" for a row whose effective height is not its height + 1 or lies above S + 1). The node now holds block 0, the funded blocks and min(S − 60, S − min_height, S − 1,440) … S (§2), the transactions of the recent window plus the funded and escrowed ones, the full state at S with spendable_balance = balance, and continues from S. A table the document does not carry (an older writer) is left as it is.

How to compute it. As stated. An implementation with other storage must reach the same observable state: the state of S (21 §1) with no unconfirmed reservation, blocks min(S − 60, S − min_height, S − 1,440) … S servable. The blocks back to S − 720 let a restored node validate a later ProofOfOwnership (720 blocks), equivocation report or queue attendance (120 blocks) that cites one; the blocks back to S − 1,440 let it tally the readiness gate's signal window as every other node does (29 §4b); the escrowed transactions let a later approval or decline of an escrow older than the window pay out as it does elsewhere; and a bridge withdrawal is carried out only while its trigger lies inside the window every node holds (34).

Rule activation. readiness_decision_state (the decision rows the rebuild reads) and readiness_registry_schedule (the window the carried headers cover), active from height 0 on every chain.

Rejections and errors. "Snapshot data is empty", "Failed to decode snapshot CBOR: …", "Snapshot payload is not an object", the format and section errors of §2, "Malformed snapshot table <t>" (not an object), "Snapshot table <t> has no Columns or Rows list", "Malformed snapshot column name in <t>", "Snapshot carries table <t> which this node does not have", "Snapshot column <t>.<c> does not exist on this node: …", "Snapshot table <t> has rows but no columns", "Malformed snapshot row in <t>" (not an array, or the wrong width), "Malformed snapshot value in <t>.<column>". Any failure rolls the transaction back and the node keeps its previous state.

Vector. computed. INPUT: a node holding survival_state rows for heights 1…900 applies §2's document at S = 400. EXPECTED OUTPUT: survival_state holds exactly (active 0, height 1) and (active 1, height 2); bridge_coin is empty; every main-chain block above height 0 not in the document is gone. INVALID: a document whose survival_state row is [0] (one value for two columns) → "Malformed snapshot row in survival_state", nothing applied; a document carrying "bridge_coin": {"Columns": [], "Rows": [[1]]} → "Snapshot table bridge_coin has rows but no columns"; a document naming the column survival_state.flag → "Snapshot column survival_state.flag does not exist on this node: the snapshot is from a different release".

Test cases · §7

8 cases · 2 valid · 6 invalid · 1 reference

Applying the minimal document replaces survival_state and empties bridge_coin26-7-applyvalid

Loading the test widget…

A row with one value for two columns is refused26-7-short-rowinvalid

Loading the test widget…

Rows without columns are refused26-7-rows-no-columnsinvalid

Loading the test widget…

A column this node does not have is refused26-7-unknown-columninvalid

Loading the test widget…

A table without a Rows list is refused26-7-no-listsinvalid

Loading the test widget…

A fractional value is refused26-7-fractioninvalid

Loading the test widget…

A document that is not a map is refused26-7-not-objectinvalid

Loading the test widget…

Every main-chain block above height 0 not in the document is gone after the apply26-7-blocks-gonevalidreference

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

value
the node holds block 0, the document's Blocks and FundedBlocks, and nothing else of the main chain

Defects to match. (1) The account_ledger, node_receipt, merkle_tree, participation_score_ledger and node_registry_ledger tables are not carried: a fast-synced node has no history before S and no receipt batches, and a node recovering in place loses its own ledger rows of every height (step 2).

8. Catch-up

Purpose. Reaching the tip after the snapshot.

Inputs. S; the target height; the connected registered peers (all connected peers while the node's height is at most 10).

Output and effect. A peer whose block at S has our hash (GetBlockHashes from S to S) and the greatest difficulty is chosen; with none, the heaviest peer above S is followed block by block. Blocks are pulled with GetNextBlockIDs(our tip id, 50) and GetNextBlocks, each re-fetched from another peer when its payload is missing, validated (19 §2), given its difficulty and applied (21); a different block at a held height hands over to the fork resolver (24); the loop ends at min(target, peer height). A node whose own height cannot be read stops ("local fault: the chain height could not be read; sync skipped: …"). Node-local: the reference runs the catch-up inside the sync pass, so a slow peer stalls other sync work.

How to compute it. As stated.

Rule activation. None.

Rejections and errors. "No connected peers", "No peers with matching snapshot base", "Missing block payload during catch-up", "Fork detected during catch-up".

Vector. computed: a DevNet node fast-synced to 1,600 pulls 1,601 onward in batches of 50 until the peer's tip.

Test cases · §8

1 case · 1 valid · 1 reference

A node fast-synced to 1,600 pulls 1,601 onward in batches of 5026-8-catch-upvalidreference

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

first_block
1601
batch
50
until
the peer's tip

Defects to match. None.

9. Retention and the prune horizon

Purpose. What a node keeps, and how snapshots bound pruning.

Inputs. SNAPSHOTS_TO_KEEP 2 (keep count SNAPSHOTS_TO_KEEP + 1 = 3); the manifest rows of this chain's identity.

Output and effect. The rows of manifest_type 0 for this chain are grouped by distinct reference height; the three newest distinct heights are kept with their directories, and every row whose reference height is not among those three has its directory removed. The manifest rows stay: they are the archive's record of every snapshot (25 §4); only the local directories go. Keeping generations, not a count of rows, means the spine-block copies of one manifest never evict the previous snapshot. The pruning horizon of the main chain is the manifests' second-newest distinct reference height, the prune horizon (13 §8, 22 §14). Every node keeps only its last three snapshots; the decentralised storage keeps every snapshot from block 0 (§10b).

How to compute it. As stated.

Rule activation. None.

Rejections and errors. None.

Vector. computed: manifests at references 400, 640, 880 and 1,120 (DevNet; 880 carried by three spine blocks, so three rows) → the directories of 640, 880 and 1,120 stay, 400's goes; all rows stay; the prune horizon is 880.

Test cases · §9

3 cases · 3 valid · 1 reference

Four generations, 880 in three rows: 400's directory goes, every row stays26-9-generationsvalid

Loading the test widget…

With one generation the horizon is one interval below it26-9-one-generationvalid

Loading the test widget…

Manifest rows are never deleted26-9-rows-stayvalidreference

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

value
only the directories of older generations are removed

Defects to match. One spine block carries one manifest per generation; nothing else.

10a. The snapshot attestation

Purpose. To prove the snapshot is real state and not a plausible fabrication that merely hashes to its manifest.

Inputs. The state the snapshot would leave (the dry run of §7), as of the manifest's reference height R; the manifest's full_file_hash (the 32-byte sample seed); the registered node keys of that state; the connected peers; the RPC GetStateSample (27 §… : request height = R, account_addresses, node_ids; answer available, accounts[{account_address, balance, found}], nodes[{node_id, node_public_key, registration_status, found}]).

Output and effect. From the dry-run state the node reads every account_balance row with latest = 1 ordered by address and every node_registry row with latest = 1 ordered by id, and keeps the ones at the indices Sample(full_file_hash, count, 8) (below) (up to 8 accounts and 8 nodes), with each account's balance and each node's (public_key, status). An empty sample (empty snapshot) skips attestation. The peers asked are connected peers whose key is registered in the snapshot's own registry (the node's own marks when the snapshot names none). It asks a narrow round of 3 such peers for the same rows at R (by the explicit address and id lists) and judges the answers in the narrow round. A peer contradicts when any sampled balance or (public_key, status) it returns differs from ours, and agrees when at least one row matches and none contradict; found = false rows neither agree nor contradict. The verdict:

Verdict When (narrow) Effect
Agree no contradiction and ≥ 2 agree; or contradictions present but ≥ 2 agree and agreeing > contradicting proceed; the contradicting peers are recorded as liars
Escalate contradictions are present and not outnumbered widen to 7 peers and judge again in the wide round
Insufficient no contradiction and < 2 agreed (too few peers answered) proceed on the hashes alone, logged

In the wide round Agree needs ≥ 2 agreeing and ≥ ceil(2 × answering / 3); otherwise the verdict is Disagree: the manifest is refused for 1,800 s (§5), nothing is applied and the fast sync fails. Node-local: the reference's GetStateSample server is unauthenticated; it answers one call per caller host per 10 s ("rate limited" otherwise), refuses a height above its tip ("height above my tip") and more than 32 addresses or 32 node ids ("sample too large"), and reads at most 64 rows. Because Insufficient proceeds on the hashes alone, a joiner with fewer than two honest registered peers is protected by the hashes and the manifest the spine signers signed only.

How to compute it. The sample function Sample(seed, population, k): x = 0x9E3779B97F4A7C15; for each seed byte b, x = (x XOR b) × 0x100000001B3 mod 2^64; then repeat x = (x × 6364136223846793005 + 1442695040888963407) mod 2^64, idx = (x >> 17) mod population, appending idx when not already chosen, until min(k, population) distinct indices are held — deterministic per (seed, population, k), so every joiner samples the same rows and a fabricator cannot know in advance which to make consistent.

Rule activation. None: a joiner-side acceptance check, not consensus. Two nodes that never fast-sync never run it.

Rejections and errors. "Snapshot refused (nothing applied): <reason>" on Disagree (the node falls back to block-by-block sync). Insufficient and a skipped attestation (no peers wired) are logged, not errors.

Vector. computed, seed = the vectors' identity G of 02 §1 (E003E4E3…2871, an example 32-byte value): Sample(seed, 44, 8) = [43, 11, 8, 18, 23, 30, 10, 1], Sample(seed, 13, 8) = [2, 8, 11, 10, 5, 7, 6, 3], Sample(seed, 5, 8) = [0, 3, 1, 2, 4] (population below k: all).

Test cases · §10a

10 cases · 10 valid

Sample(G, 44, 8): the seed is the vectors' identity G26-10a-sample-44valid

Loading the test widget…

Sample(G, 13, 8): the seed is the vectors' identity G26-10a-sample-13valid

Loading the test widget…

Sample(G, 5, 8): the seed is the vectors' identity G26-10a-sample-5valid

Loading the test widget…

An empty population gives no sample26-10a-sample-emptyvalid

Loading the test widget…

Attestation: 2 agree, 0 contradict, narrow round gives Agree26-10a-attest-agreevalid

Loading the test widget…

Attestation: 1 agree, 0 contradict, narrow round gives Insufficient26-10a-attest-insufficientvalid

Loading the test widget…

Attestation: 2 agree, 1 contradict, narrow round gives Agree26-10a-attest-majorityvalid

Loading the test widget…

Attestation: 1 agree, 1 contradict, narrow round gives Escalate26-10a-attest-escalatevalid

Loading the test widget…

Attestation: 5 agree, 2 contradict, wide round gives Agree26-10a-attest-wide-agreevalid

Loading the test widget…

Attestation: 4 agree, 3 contradict, wide round gives Disagree26-10a-attest-wide-disagreevalid

Loading the test widget…

Defects to match. None.

10b. The archive

Purpose. The decentralised storage, not every node, keeps every snapshot from block 0: each snapshot's chunks are held by five registered nodes chosen by lot, every node keeps only its last three snapshots locally, and anyone can travel the spine to any past snapshot and rebuild state from its holders.

Inputs. The snapshot a node built (§1–§3); the fee-free AttestEvent duty and the oracle step (17); oracle_result (consensus state, carried in snapshots, rolled back by height, never pruned); the registry; storage_replication 5, storage_proof_epoch_blocks (TestNet 240, DevNet 10), oracle_quorum 3, snapshot_reward_share_ppm 100,000 (bounded 0…500,000; both genesis files), SNAPSHOTS_TO_KEEP + 1 = 3; the longevity pool.

Output and effect.

  1. Attestation and membership (consensus). After a node publishes the snapshot of S it sends an AttestEvent duty (fee 0, relayed to peers) with event id "ZBCSNAP1:" ‖ decimal(S) and value hex64(full_file_hash) ‖ ":" ‖ decimal(chunk count). The oracle step resolves it like any event fact (17); the resolved oracle_result rows are the archive, each admitted at its resolved_height. Membership is decided on the main chain only: no balance may depend on the spine's manifest table, which lags or leads a node's main chain.
  2. The archive as of height h: every oracle_result row whose event id starts with ZBCSNAP1: and resolved_height ≤ h, parsed strictly (reference height a decimal without sign or leading zero ≤ 2³²−1; value exactly 64 lower-case hex digits, :, a decimal 1 … 2²² without leading zero; anything else is not a snapshot), sorted by reference height, then admitted height, then file hash, keeping the first per reference height. A read of the table that fails is an error that fails the block step on this node, never an empty archive. Its size is the sum of the chunk counts; position p is chunk p of that concatenation.
  3. Chunk name (by place, not content): SHA3-256("ZBC-ARCHIVE-CHUNK" ‖ full_file_hash(32) ‖ index u32 LE). Holders of a chunk: the rendezvous selection of 11 over the registered node keys with the chunk's name, seed = full_file_hash and K = storage_replication; the seed is fixed per snapshot, so a chunk moves only when one of its holders leaves the registry.
  4. Holding (node-local): a node keeps in its piece store, under the chunk's hash (from the manifest), every chunk it is a holder of, copied from its own snapshot directory when it built the snapshot, else fetched from the other holders, then any registered node, each copy checked against its hash; a chunk it no longer holds is deleted after 3,600 s. Storage is on by default ([storage] enabled=false switches it off, 30).
  5. Sample, proofs and reward (consensus; the storage side is 11 §12, the block step 22). For storage epoch e (blocks e·E … (e+1)·E − 1), the archive as of block e·E and the seed = the hash of block e·E: the sample is Sample(seed, size, 64) positions (§10a's function). Each holder of a sampled chunk proves it with SHA3-256(chunk bytes ‖ nonce), the challenge nonce of 11 §12 for (seed, name, e), answered under the chunk's name, in its one storage-proof batch of the epoch (11 §6). At block h with h mod E = 0 and h ≥ 2E the epoch h / E − 1 is tallied over the registry as of its first block: a sampled chunk is confirmed when at least oracle_quorum holders agree on one proof; each holder that gave it is one honest answer (a silent or wrong holder only loses its part; no score moves). budget = floor(pool balance × ppm / 1,000,000), part = budget div honest answers; each owner of an earning holder (36: not missing, suspended or immature) is credited its parts (ledger event 77, ARCHIVE_REWARD), the pool debited the sum in one row; withheld parts stay in the pool.
  6. Access (node-local). A holder serves the chunks of the archive's older snapshots (all but the newest three archived ones, less any chunk whose bytes a newer one shares) only to a GetStoragePiece request signed by a registered node key: Ed25519 over "ZBC-PIECE-REQ" ‖ genesis hash(32) ‖ piece id(32) ‖ timestamp i64 LE ‖ requester key(32), the timestamp within 300 s of the holder's clock (fields requester_public_key, timestamp, signature, 27); otherwise PERMISSION_DENIED "old snapshot chunks of the archive are served to registered nodes only (<reason>)". Every other piece stays open. The HTTP read path that rebuilds an old block or transaction from the archive answers only the node's operator (31).

How to compute it. As stated.

Rule activation. None.

Rejections and errors. As in item 6; an attestation is an oracle event (17).

Vector. computed: for §3's document at S = 172,040 the event id is ZBCSNAP1:172040, the value b295b329983547c2add8c42f779b9987c2b52839b73d7957dac5798a1678dc30:3, and the name of chunk 0 is 737132CC56BF0AC8E6ABE1FB73A451A1D1DE681EC120B00704CA918775F61B3A.

See also 11 §12 (the snapshot archive from the storage side).

Test cases · §10b

12 cases · 12 valid · 1 reference

The archive attestation of the 250,000-byte document at S = 172,04026-10b-eventvalid

Loading the test widget…

The attestation reads back as a snapshot26-10b-parsevalid

Loading the test widget…

Not a snapshot: upper hex26-10b-parse-upper-hexvalid

Loading the test widget…

Not a snapshot: leading zero26-10b-parse-leading-zerovalid

Loading the test widget…

Not a snapshot: zero chunks26-10b-parse-zero-chunksvalid

Loading the test widget…

Not a snapshot: too many chunks26-10b-parse-too-many-chunksvalid

Loading the test widget…

Not a snapshot: signed26-10b-parse-signedvalid

Loading the test widget…

Not a snapshot: short hash26-10b-parse-short-hashvalid

Loading the test widget…

2^22 chunks is the largest count26-10b-max-chunksvalid

Loading the test widget…

The epoch budget: 10 % of the pool, rounded down26-10b-budgetvalid

Loading the test widget…

The share is capped at 500,000 ppm26-10b-budget-capvalid

Loading the test widget…

The signed piece-request preimage and the 300-second window26-10b-piece-requestvalidreference

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

preimage
"ZBC-PIECE-REQ" || genesis hash (32) || piece id (32) || timestamp i64 LE || requester key (32)
window_seconds
300

Defects to match. (1) The archive keeps snapshots (state as of S, and the block window of §2), not every block: blocks between two snapshots' windows are in no snapshot and are gone once every node has pruned them. (2) A node joining at height 0 long after launch computes the holders over the genesis registry and may find none. (3) A chain of fewer than oracle_quorum holders per chunk never confirms a sampled chunk and pays nothing.

10c. Data model

Purpose. What an implementation stores for snapshots and the fast sync.

  • The state tables of §2: their full schema (columns, types, keys, the latest marker) is 07. The snapshot reads, per table, "the newest row per key with height at or below S" (versioned), "every row with height at or below S" (unversioned) or "every row" (no height column), after the prune filter of §2 step 5, ordered by the key then the height. The apply (§7) deletes and re-inserts as stated there and recomputes latest as "the row with the greatest height per key".
  • Main-chain blocks and transactions (05, 07): the apply deletes every block above height 0 and every transaction and ledger row of every height (§7 step 2), then inserts the document's blocks and transactions.
  • readiness_bundle_decision (29 §4b): carried in the document; the readiness gate is rebuilt from it right after the apply.
  • spine_block_manifest (25 §10): the walk of §5 reads the newest 8 manifests of this chain.
  • Local files: the snapshot directory $HOME/.zoobc/snapshots/<base64url(full_file_hash)>/ with one file per chunk named base64url(chunk hash) (§3); the archive's piece store (11), keyed by the chunk hash.
  • In memory only: the manifests refused by the attestation (1,800 s) and the snapshots found unavailable (600 s), keyed by full_file_hash; the walk's result (60 s, §5).

11. Consensus and local

Nothing here is consensus except the archive's membership, sample and tally (§10b): a snapshot is a transport of state whose authority is the spine block naming it, signed by the spine signers (25), and two honest nodes that never fast-sync agree without any of it — but every node must write the same bytes (§1, §2: the pinned view, the prune filter, the column order, the empty tables, the 1,440-block window), because the archive admits a snapshot only when two thirds of the registry attest one full_file_hash. What an implementation must match to interoperate: §2's bytes exactly (to publish manifests other nodes can use, and to accept theirs), the genesis texts of 06 §13 included, §3's names, §4's answers, §6's checks, and §7's resulting state (the readiness decision rows included: a joiner that ignored them would judge a decided bundle's rules off). The schedule (§1), the walk (§5), the attestation (§10a), the retention (§9) and the catch-up policy (§8) are local.

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