On this page
- §0 The area in one paragraph
- 1. When a snapshot is taken
- 2. The snapshot document
- 3. Chunks, names and the directory
- 4. Serving chunks
- 5. When a node fast-syncs, and the manifest walk
- 6. Download and verification
- 7. Attesting and applying the snapshot
- 8. Catch-up
- 9. Retention and the prune horizon
- 10a. The snapshot attestation
- 10b. The archive
- 10c. Data model
- 11. Consensus and local
26 — Snapshots and fast sync
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 chain
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 manifest
Loading the test widget…
DevNet: tip 480 gives S = 400 and a 30-day manifest
Loading the test widget…
A tip that is not a multiple of the interval takes no snapshot
Loading the test widget…
A node's stagger offset is FNV-1a of its key modulo the window plus one
Loading the test widget…
A height at or below the depth has no snapshot
Loading the test widget…
Before TestNet block 172,800 there is no manifest, so no fast sync
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):
Columns= the table's column names sorted by name in byte order,latestremoved; 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 atS, and thedataset_objectcolumnlast_billing_heighttravels only underdataset_rent_object_clock. Every gate is active from height 0 on every chain, so all 65 tables and every column travel.- A table the writer never created is written as
{"Columns": [], "Rows": []}, so every snapshot names all 65 tables. Rows= the selected rows as arrays in that column order; foraccount_balanceandaccount_token_balancethespendable_balancevalue is replaced bybalance(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; arealvalue is written as its text.- Row selection: a versioned table with a key → the row with the greatest height ≤
Sper key (node_registryadditionally 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). - The prune filter: before selection every table is filtered to the rows the prune at height
Skeeps, so a node whose own prune lags and a node restored from an earlier snapshot write the same rows. Withlifecycle = max(max(100, 2 × registered nodes) + 1, receipt_lifecycle),receipt = S − lifecycle(nothing is filtered whileS ≤ lifecycle),floor = min(receipt, S − max_rollback_height),cycle= the snapshot cycle (22): superseded versions (latest = 0) ofnode_registry(by id),participation_score,node_liveness,queue_state(by node_id) andaccount_balance(by address) are left out when their height is belowfloorand a newer version of the same key sits at or belowfloor;score_unit_clockrows belowreceipt;queue_attendancerows belowreceiptwhose window + 2 ≤ the newest evaluated window;skipped_blocksmithbelowfloor; fee-vote commitments and reveals belowmin(receipt, S − (cycle + rollback));oracle_attestationrows of resolved events belowreceipt(other than parameterZBCGOV1:and releaseZBCREL1:votes), parameter votes below the vote window start forcycle + rollback, release votes belowS − (release window + rollback);pending_transactionexecuted envelopes and superseded versions belowfloor, and theirpending_signaturerows once no pending version at or belowfloorremains. 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 bytes
Loading the test widget…
The minimal document is one chunk whose hash is the document's
Loading the test widget…
Blobs are byte strings, text is text, negatives use major type 1
Loading the test widget…
A document of format 2 is refused
Loading the test widget…
A document without SnapshotFormat reads as format 1 and is refused
Loading the test widget…
A document without EscrowedTransactions is refused
Loading the test widget…
A document without FundedBlocks is refused
Loading the test widget…
A document without FundedTransactions is refused
Loading the test widget…
A document without StateTables is refused
Loading the test widget…
TestNet S = 172,040: the RecentTransactions window is interval + depth, the Blocks from 170,600 (1,441 headers)
Loading the test widget…
DevNet: 6,924 blocks of transactions and the headers from S - 1,440
Loading the test widget…
DevNet S = 400: the bound is below 0, so blocks 1 to 400
Loading the test widget…
The 65 state tables in the writer's order, and the five with a gate of their own
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 chunks
Loading the test widget…
A document of exactly two chunk sizes makes two full chunks
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 order
Loading the test widget…
Chunks come back in the order they were asked for
Loading the test widget…
A name with '..' goes to Failed
Loading the test widget…
An unknown name goes to Failed
Loading the test widget…
A name over 128 characters goes to Failed
Loading the test widget…
An empty snapshot hash is refused
Loading the test widget…
A request without names is refused
Loading the test widget…
More than 32 names are refused
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:
- 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);
- unavailable: a manifest that nobody served within the last 600 s is skipped;
- a reference height above the target is skipped;
- a reference height at or below
flooris 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); - 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,360
Loading the test widget…
At height 1,700 the floor leaves only 1,840
Loading the test widget…
At 1,700 with 1,840 unavailable no sync point is left (block-by-block sync)
Loading the test widget…
A refused newest manifest ends the walk with an error
Loading the test widget…
A refused manifest after a usable one ends the walk there
Loading the test widget…
A manifest above the target is skipped
Loading the test widget…
No manifest at all
Loading the test widget…
Only the newest 8 manifests are walked
Loading the test widget…
TestNet: no manifest before block 172,800
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 verifies
Loading the test widget…
A copy of chunk 1 with one byte changed ends the attempt
Loading the test widget…
Chunks that match but a different full_file_hash fail the whole
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:
- The format and sections are checked (§2).
- Trim: every row whose height is not 0 is deleted from
main_block(height) and fromaccount_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 aboveSgo 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 tableszbc_transaction,account_ledger,account_transaction_index,eth_tx_hash,merkle_tree(byblock_height) andnode_receipt(byreference_block_height, or byblock_heightwhen 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"). - The
Blocksare inserted as main-chain rows; theRecentTransactionsinserted (ignoring duplicates); theFundedTransactionsthe same way, then theFundedBlocksas main-chain rows (ignoring duplicates), then theEscrowedTransactionslike the recent ones. - 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
latestand the newest row per key regains it (a table without a key: the single newest row).
- a table this node does not have is accepted only when it carries no rows (
- The
PublishedReceiptsare 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_coin
Loading the test widget…
A row with one value for two columns is refused
Loading the test widget…
Rows without columns are refused
Loading the test widget…
A column this node does not have is refused
Loading the test widget…
A table without a Rows list is refused
Loading the test widget…
A fractional value is refused
Loading the test widget…
A document that is not a map is refused
Loading the test widget…
Every main-chain block above height 0 not in the document is gone after the apply
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 50
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 stays
Loading the test widget…
With one generation the horizon is one interval below it
Loading the test widget…
Manifest rows are never deleted
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 G
Loading the test widget…
Sample(G, 13, 8): the seed is the vectors' identity G
Loading the test widget…
Sample(G, 5, 8): the seed is the vectors' identity G
Loading the test widget…
An empty population gives no sample
Loading the test widget…
Attestation: 2 agree, 0 contradict, narrow round gives Agree
Loading the test widget…
Attestation: 1 agree, 0 contradict, narrow round gives Insufficient
Loading the test widget…
Attestation: 2 agree, 1 contradict, narrow round gives Agree
Loading the test widget…
Attestation: 1 agree, 1 contradict, narrow round gives Escalate
Loading the test widget…
Attestation: 5 agree, 2 contradict, wide round gives Agree
Loading the test widget…
Attestation: 4 agree, 3 contradict, wide round gives Disagree
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.
- Attestation and membership (consensus). After a node publishes the snapshot of
Sit sends anAttestEventduty (fee 0, relayed to peers) with event id"ZBCSNAP1:" ‖ decimal(S)and valuehex64(full_file_hash) ‖ ":" ‖ decimal(chunk count). The oracle step resolves it like any event fact (17); the resolvedoracle_resultrows are the archive, each admitted at itsresolved_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. - The archive as of height
h: everyoracle_resultrow whose event id starts withZBCSNAP1:andresolved_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; positionpis chunkpof that concatenation. - 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 of11over the registered node keys with the chunk's name, seed =full_file_hashand K =storage_replication; the seed is fixed per snapshot, so a chunk moves only when one of its holders leaves the registry. - 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=falseswitches it off,30). - Sample, proofs and reward (consensus; the storage side is
11§12, the block step22). For storage epoche(blockse·E … (e+1)·E − 1), the archive as of blocke·Eand the seed = the hash of blocke·E: the sample isSample(seed, size, 64)positions (§10a's function). Each holder of a sampled chunk proves it withSHA3-256(chunk bytes ‖ nonce), the challenge nonce of11§12 for (seed, name,e), answered under the chunk's name, in its one storage-proof batch of the epoch (11§6). At blockhwithh mod E = 0andh ≥ 2Ethe epochh / E − 1is tallied over the registry as of its first block: a sampled chunk is confirmed when at leastoracle_quorumholders 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. - 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
GetStoragePiecerequest 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 (fieldsrequester_public_key,timestamp,signature,27); otherwisePERMISSION_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,040
Loading the test widget…
The attestation reads back as a snapshot
Loading the test widget…
Not a snapshot: upper hex
Loading the test widget…
Not a snapshot: leading zero
Loading the test widget…
Not a snapshot: zero chunks
Loading the test widget…
Not a snapshot: too many chunks
Loading the test widget…
Not a snapshot: signed
Loading the test widget…
Not a snapshot: short hash
Loading the test widget…
2^22 chunks is the largest count
Loading the test widget…
The epoch budget: 10 % of the pool, rounded down
Loading the test widget…
The share is capped at 500,000 ppm
Loading the test widget…
The signed piece-request preimage and the 300-second window
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
latestmarker) is07. The snapshot reads, per table, "the newest row per key with height at or belowS" (versioned), "every row with height at or belowS" (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 recomputeslatestas "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 namedbase64url(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.