On this page
- §0 The area in one paragraph
- 1. The receipt and its bytes
- 2. Receipt requests, issuing and keeping receipts
- 3. Batches and the receipt Merkle root
- 4. Published receipts in a block
- 5. Validation of published receipts
- 6. Receipt selection by the blocksmith (reproduced behaviour)
- 7. The scramble and the priority peers
- 8. Linked receipts and their proof
- 9. The random picks (reproduced exactly)
- 10. Receipts and the participation score
- 11. State and the consensus/local split
23 — Receipts
Out of scope the block bytes a receipt is hashed into (05 §6); the validator's ordered checks around the receipts and the receipt-once rule (19 §2 step 12, §9); the score formula the receipt counts feed (21 §3, 36); the peer transport, connection identity and the message envelopes that carry receipts (27, 28); the candidate pool and block production around receipt selection (19, 20); snapshots, which carry published_receipt (26)
§0 The area in one paragraph
A receipt is a 232-byte signed statement by one registered node (the recipient) that it
received a specific datum — a block or a transaction, named by its 32-byte hash — from another
registered node (the sender), at a stated reference block, and that the recipient's own receipt
batches stood at a stated Merkle root (rmr) at that moment. A node asks for a receipt when
it pushes a block, a transaction or a batch of transactions to a peer: the push carries the
sender's receipt request signature, a chain-bound Ed25519 signature by the sender's node key
naming the datum and the recipient, and the recipient answers with a receipt only when that
signature verifies. The sender keeps the receipts it earns, batches them once per block height
into a Merkle tree of their hashes sorted by signature, and publishes a few of them in the blocks
it produces: unlinked receipts, taken from a batch about forty blocks back and addressed to the
blocksmith's priority peers of that period, and linked receipts, which prove with a Merkle
path that a receipt the blocksmith earned belongs to a batch whose root it had earlier committed to.
Who may receipt whom is decided by the scramble: every 40 blocks the registered nodes are
ordered by a hash of a block seed and their id, and each node's priority peers are the nodes after
its own position in that order (max_assigned_peers of them). Validators check every published
receipt's sender, signature, reference (a held main-chain block of the 720 below the block, with
its hash), age, lookback and recipient-is-a-priority-peer rule, bound the count by the registry as
of the previous block, refuse a receipt any block of the last 40 already carried, and move the
blocksmith's participation score by the number published. A
published receipt's recipient also counts as a sign of life (36). Everything else — which
receipts a blocksmith picks, how it batches, what it keeps — is local; the reference behaviour is
specified so an implementation can produce the same blocks.
1. The receipt and its bytes
Purpose. An implementation must produce, sign, hash and verify the one datum that proves delivery between two nodes.
Inputs. The sender's and recipient's 32-byte node keys; the datum type (u32: 1 block, 2 transaction) and the 32-byte datum hash; the recipient's latest block (height and hash) and its latest batch root; the recipient's node private key.
Output and effect. The unsigned receipt (168 bytes) and the signed receipt (232 bytes):
| Offset | Size | Field | Encoding |
|---|---|---|---|
| 0 | 32 | sender_public_key |
the node key of the sender |
| 32 | 32 | recipient_public_key |
the node key of the signer |
| 64 | 4 | reference_block_height |
u32 LE |
| 68 | 32 | reference_block_hash |
the signer's latest block hash at signing |
| 100 | 4 | datum_type |
u32 LE: 1 block data, 2 transaction data |
| 104 | 32 | datum_hash |
the block hash or the transaction hash received |
| 136 | 32 | rmr |
the signer's latest batch root (§3), 32 zero bytes before its first batch |
| 168 | 64 | recipient_signature |
Ed25519 over bytes 0…167, by the recipient's node key |
The signature is a plain Ed25519 signature of the 168 bytes (no domain prefix, no chain binding).
The receipt hash = SHA3-256 of the 232 bytes, with an empty rmr replaced by 32 zero bytes;
it is the Merkle leaf of §3. On the peer wire the receipt is the message Receipt (27):
| Field | Number | Type | Content |
|---|---|---|---|
SenderPublicKey |
1 | bytes | 32 |
RecipientPublicKey |
2 | bytes | 32 |
DatumType |
3 | uint32 | 1 or 2 |
DatumHash |
4 | bytes | 32 |
ReferenceBlockHeight |
5 | uint32 | |
ReferenceBlockHash |
6 | bytes | 32 |
RMR |
7 | bytes | 0 or 32 |
RecipientSignature |
8 | bytes | 64 |
In a block it is carried inside a PublishedReceipt (§4) and hashed into the payload by its 232
bytes (05 §6).
How to compute it.
- Concatenate the eight fields of the table up to offset 168 (
rmras carried: an emptyrmrmakes the unsigned bytes 136 long). - Sign those bytes with Ed25519 under the recipient's node key; append the 64-byte signature.
- Hash: SHA3-256 of the 232 bytes, an empty
rmrwritten as 32 zero bytes. - To verify: check the sizes (keys 32, hashes 32,
rmr0 or 32, signature 64), then the Ed25519 signature over the unsigned bytes underrecipient_public_key.
Rule activation. None.
Rejections and errors. Sizes, in this order: "InvalidReceiptRecipientPublicKeySize",
"InvalidReceiptSignatureSize", "InvalidReceiptSenderPublicKeySize",
"InvalidReceiptReferenceBlockHashSize", "InvalidReceiptDatumHashSize",
"InvalidReceiptRmrSize"; signature: "InvalidReceiptSignature".
Vector. computed. INPUT: recipient key = the Ed25519 key of seed 11 × 32 (public key
d04ab232742bb4ab3a1368bd4615e4e6d0224ab71a016baf8520a332c9778737); sender key = the public key
of seed 22 × 32 (a09aa5f47a6759802ff955f8dc2d2a14a5c99d23be97f864127ff9383455a4f0); reference
height 12,364; reference hash = datum hash = the 32 bytes
23b278946de20a26eae25e393bec5bca57c0071acc31f06a15a15bab010c04ae; datum type 1; rmr =
SHA3-256("rmr-example") = fb8df4a23b3f0cc17c5bc1fa69a9c734aacc23c5599e41111b91d7507d90a328.
EXPECTED OUTPUT: unsigned bytes (168) =
a09aa5f47a6759802ff955f8dc2d2a14a5c99d23be97f864127ff9383455a4f0d04ab232742bb4ab3a1368bd4615e4e6d0224ab71a016baf8520a332c97787374c30000023b278946de20a26eae25e393bec5bca57c0071acc31f06a15a15bab010c04ae0100000023b278946de20a26eae25e393bec5bca57c0071acc31f06a15a15bab010c04aefb8df4a23b3f0cc17c5bc1fa69a9c734aacc23c5599e41111b91d7507d90a328;
signature =
57c7084dd7426ad269e6c7b53e10251b552eaa678a7078ee78ca52fb935a0f185b67f0c0d5bddcc578fe03a6befef7cad83db01665f93e3126529be707d56d0e;
receipt hash = 1a1f0973ec79be7f0111da4169eab5adf1050ba7028390bcfd29feb029a06308. The same
receipt with an empty rmr: unsigned bytes 136 long, signature
d154f62463dd4a51a4fbe2e38fe6c4ad6484b2e6d5d35bd7f1cdd2879aff13abfb27896374d3b288574380d3e1f76ea2e0a1bd6b4cb1c4aff3cfe40cae71e403,
hash (over 168 + 64 bytes, rmr as 32 zero bytes)
12b732ec05c3fb1a20c41620b40ab498b55d657994da3207de5e7caeef925a8c. INVALID: the first receipt
with its last signature byte changed from 0e to 0f → "InvalidReceiptSignature"; with a
31-byte rmr → "InvalidReceiptRmrSize".
Test cases · §1
4 cases · 2 valid · 2 invalid
Build, sign and hash a receipt
Loading the test widget…
The same receipt with an empty rmr
Loading the test widget…
A 31-byte rmr is refused
Loading the test widget…
A changed signature byte does not verify
Loading the test widget…
Defects to match. (1) A receipt deserialised with an empty rmr signs over 136 bytes but
hashes as if the field were 32 zero bytes. (2) Nothing in the receipt's own bytes names the chain:
a receipt signed on one chain verifies on another (the request signature of §2 is chain-bound;
the receipt is not).
2. Receipt requests, issuing and keeping receipts
Purpose. An implementation must sign every push it wants a receipt for, issue a receipt only for a request that proves its sender, and keep the receipts it earns.
Inputs. A pushed block (SendBlock), transaction (SendTransaction) or batch of transactions
(SendBlockTransactions) with the claimed SenderPublicKey and the SenderSignature; the chain's
genesis block hash (32 bytes); the receiving node's node key; the registry; the receiving node's
latest block and batch root; the node configuration value require_signed_receipt_requests
(section [node] of the node configuration, boolean, default false).
Output and effect.
The request signature. A node pushing a datum to a peer signs, with its node key, the digest
digest = SHA3-256( "ZBC-RCPT" (8 ASCII bytes, no terminator)
‖ genesis_block_hash (32)
‖ datum_type (1 byte)
‖ datum_hash (32)
‖ recipient_node_public_key (32) ) = 105 bytes hashed
| Push | rpc and field | datum_type byte |
datum_hash |
|---|---|---|---|
| a block | SendBlockRequest.SenderSignature (field 6, bytes) |
1 | the block hash the request claims |
| a transaction | SendTransactionRequest.SenderSignature (field 4, bytes) |
2 | SHA3-256 of the served TransactionBytes |
| a batch | SendBlockTransactionsRequest.SenderSignature (field 4, bytes) |
3 | SHA3-256 of the served TransactionsBytes concatenated in order |
The request byte numbering (1, 2, 3) is its own; the receipt's datum_type stays 1 or 2. The
signature is computed per recipient (the recipient's key is in the digest). A node with no
genesis hash yet, no private key, or no known key for the recipient sends the field empty.
There is no activation height: every node signs its pushes from block 0 on, so between nodes that
know each other's node keys no unsigned request occurs. A node that asks a peer for a block's missing transactions (RequestBlockTransactions,
a call signed by its node key like every P2P call, 27) names its own node key in
RequestBlockTransactionsRequest.RequesterPublicKey (field 4, bytes, 32). The serving node
answers only a caller whose signing key is a handshake-verified peer (PERMISSION_DENIED "block transactions require a handshake-verified peer"), silently ignores an unregistered one, applies
the read budget (24 §2) and a byte budget (8 MiB per 10 s per caller, 64 MiB per host; over it
RESOURCE_EXHAUSTED "block transaction byte budget: 8 MiB per 10 s per caller"), refuses more
than 500 ids (INVALID_ARGUMENT "Too many transaction IDs requested"), serves at most 2 MiB
of transactions in request order, and pushes them with a SendBlockTransactions signed for
the key the request names, or, when that field is empty or malformed, for the key that
signed the call. Nothing is pushed to an address this node's own dial has not reached (the
entry's address is not chain-verified, 28 §1): a caller with no routable address (an
inbound-only node) or one known only by a gossiped or forwarded address gets no push and completes
its block by pulling it whole.
Issuing. A node issues a receipt only when all hold: the claimed sender key is non-empty; the
request signature is present and verifies (64 bytes, a 32-byte key, Ed25519 over the digest with
this node's own key as the recipient and this chain's genesis hash) — or, only while
require_signed_receipt_requests is false, the signature is empty; the sender key and this node
are both registered (a current Registered registry row); and the datum was accepted:
- a transaction (new, or already in the pool) that passes staging's checks → one receipt,
type 2, over the transaction hash, in
SendTransactionResponse.Receipt(field 1); a transaction refused by staging's cheap checks (04§6) earns none; - a batch → one receipt per accepted transaction, type 2, in
SendBlockTransactionsResponse.Receipts(field 1, repeated), all under the one batch signature; - a block applied, already held with the same hash, or queued as an incomplete (ids-only)
block whose header passed the checks of
19§2 step 5 against its previous block, whose signature verifies, and whose carriedblock_hashequals SHA3-256(header ‖ signature) → one receipt, type 1, over the block hash, inSendBlockResponse.Receipt(field 1).
A signature that does not verify earns no receipt and is not charged to the claimed key (it may be
a victim's). The receipt's reference block is the signer's latest block at signing; its rmr is
the signer's latest batch root. The setting require_signed_receipt_requests decides only whether
an unsigned request still earns a receipt. A node configuration without the line reads false;
the installer writes true into every node configuration it creates on either chain (a kept
configuration that lacks the line gains it; one that sets it keeps the operator's value), and the
relaunch procedure sets it to true on every node of both chains (30 §2, §9a). So both chains
refuse unsigned receipt requests from block 0, and every node signs its requests anyway.
Keeping. The sender keeps a returned receipt in node_receipt (§11) only when the receipt names
itself as sender, both keys are registered, the sizes and the signature verify (§1), and (for a
block push) the datum is the pushed block's hash; a receipt whose reference hash disagrees with
the sender's own main-chain block at that height is refused ("Receipt reference_block_hash mismatch - receipt from forked node"). A second receipt with the same (sender, recipient, datum
type, datum hash) is ignored.
How to compute it.
- Sender: for each recipient, digest as above; sign with Ed25519; put the 64 bytes in the
request's
SenderSignature. - Recipient: if the claimed key is empty → no receipt. If
SenderSignatureis non-empty: recompute the digest with its own key as the recipient; verify → step 3, else no receipt. If empty:require_signed_receipt_requeststrue → no receipt; false → step 3. - Both registered and the datum accepted → build and sign the receipt (§1), answer it.
Rule activation. None by height: require_signed_receipt_requests is node configuration.
Node-local: while the setting is false, an unsigned request from a registered key earns a receipt,
so a peer can claim another registered key; the peer-charging side of that claim is bound by the
signed call envelope (28).
Rejections and errors. No error is returned to the pusher: a refused request simply gets no receipt (the push itself is processed as usual).
Vector. computed. INPUT: genesis hash G =
e003e4e3557ef19f0519bd345009dea7fb43b3445eaa043920c5dc23b3302871 (a 32-byte value; a node uses
its own chain's), datum type 1, datum hash = the block hash
42cfa11fce0acdbebfcb649a2934dffcaecc032789259024db35146ce1881c52, recipient
a7e89b25b24c11165c68641aefbe652987dd798c008e2ff09e298c57a048e634, sender key = seed 22 × 32.
EXPECTED OUTPUT: preimage (105 bytes)
5a42432d52435054e003e4e3557ef19f0519bd345009dea7fb43b3445eaa043920c5dc23b33028710142cfa11fce0acdbebfcb649a2934dffcaecc032789259024db35146ce1881c52a7e89b25b24c11165c68641aefbe652987dd798c008e2ff09e298c57a048e634;
digest 86a921bc4f14b5d968334bb596793312257d0c3aa211d5f6f51f243cc38d182e; SenderSignature
ee2d336f94b2de127658f9a45ac7d8416661e60ce0eaa46b045b118fd6dd83b408ff786e46dbd02e72c587cc76c55c4e161c2e8b85914f84d5c5c5f55913f40a.
A transaction push of TransactionBytes = 01020304: datum
966dbdcbd0e0348faa1ccbce5a62b8e73b0d08955d666db82243b303d9bd9502, digest (type 2, same
recipient) c92313880c019339d60cd9a92714dd20e8ed2af95d834069c7ee70638ea7a9ac, signature
953bca8281819cfc3f9ee364321906ced35d0223a8b264fcd81b60834b734802ac7417bb8910cb958d8003fafe1e75a2bc6b57ad10d1235b92388cb2ae98eb00.
A batch of aa and bbcc: datum f13aba30e421e3686bffcb8d387dc2557b3578983f92ca63fecd6d88bab96172,
digest (type 3) 554987e92928d2d0b47fa1e66e7a628b190e58c2f160c4568bb4d557fc5a5d4d, signature
f0cd70274fb4dd02e8365605843d4984eecf931eeadf4f68b14f6a0b25c23722ee31116dd8586f3b1309f4d6fe33c47499eb2d33bb23ffbcdf68134aafb41603.
INVALID: the block signature above presented to the recipient
715ea8e2f51bbcb778a26e69d73bd1044fe3a43d76cb1cf6cbc3a9a661a2fbac does not verify (the digest
names another recipient) → no receipt.
Test cases · §2
7 cases · 6 valid · 1 invalid
A receipt request for a block
Loading the test widget…
The datum of a pushed transaction
Loading the test widget…
A receipt request for a transaction
Loading the test widget…
The datum of a batch
Loading the test widget…
A receipt request for a batch
Loading the test widget…
The block request's signature checked by another recipient
Loading the test widget…
The request digest naming the other recipient
Loading the test widget…
Defects to match. The request signature proves that the key asked, not that the key's own machine served the datum.
3. Batches and the receipt Merkle root
Purpose. An implementation that wants to produce the same receipts (and linked proofs) as the reference must commit to the receipts it earned, once per height, in the same way.
Inputs. After a block of height h is committed, and after the node broadcasts a block it
produced: the block's datum hashes = [block_hash, tx_hash_0, …] in transaction order; the
node's unbatched node_receipt rows (no batch root yet) whose datum is one of them; the batch
already stored for h, if any.
Output and effect. The unbatched receipts for h's data (at most 1,000), each re-checked by §1
(invalid ones skipped), are merged with the receipts of the existing batch of h (if any), sorted
by signature bytes ascending, hashed (§1) into leaves and folded into a Merkle root: pairs
hashed as SHA3-256(left ‖ right), an odd last node hashed with itself, level by level until one
node remains; one leaf is its own root; no leaves → 32 zero bytes. The root replaces the
merkle_tree row of h; every receipt of the batch gets its batch root and its position; the
node's latest batch root becomes this root, and every receipt the node signs from now on
carries it as rmr. With no valid receipt and no batch yet at h, a root over the datum hashes
themselves is stored (no receipt is marked).
How to compute it.
- Collect the receipts (new + existing of
h); drop those failing §1. - Sort by the 64 signature bytes (byte order).
- Leaves = receipt hashes in that order; fold as above.
- Store the root for
h; mark every receipt with (root, index).
Rule activation. None.
Rejections and errors. None at the block level (all local).
Vector. computed. INPUT: three receipts, sender seed 22 × 32, reference height 12,364,
datum type 1, reference hash = datum hash 23b27894…10c04ae, rmr fb8df4a2…7d90a328 (§1),
signed by the keys of seeds 31, 32, 33 × 32 (recipients
48075a597e721a156e2e0799de5cc0c5324dc6e7eaf1cdd46250868ec53215dd,
5e212c0980e4b39fc09721134aa02109374edfd260c0d3d03cb501c8d65457a9,
17cb79fb2b4120f2b1ec65e4198d6e08b28e813feb01e4a400839b85e18080ce). EXPECTED OUTPUT: sorted by
signature: 4cf634c1322299e2…, a9444c8d66ba76f7…, b263b7b5c682aa3a… (full signatures
4cf634c1322299e24049597b2fa96c27de3f81ddd1aeadb8e01579e73c66b3674a8d03f8aa6f07b32923453c6d094def73b047f9660104ae36f28a32ff6fd106,
a9444c8d66ba76f7ec31fbfd62ffa95ff4d31152a88dfe7e5be46f815484e4482cf972a7494393a8047057646d656cf88e4516e3fb5cecd8ddd5a2e5fe31680c,
b263b7b5c682aa3a02f89817b8af01321678ffb7d952fa6f80e229ce82628752c43861e08791b7cc4f932a6595f736644e9bb437a317330e39255820e2316f0f);
leaves ae51fc37d7a0f21f6961c4f4dbf6eda82b2839da2043d4c93a996eadc7f71183,
7d4bca13824071d7ea2172f75f428a74faf185282aa1086be7290dfcafb0e411,
756c39c79433c7a60128a0e00d4a54f71501b7c06ab5fb3c9663b5c6bf771665; level 1
65cea3983225c32e02fc634c612c0e21d52b1f437f1ea25842182ca0bed8ce88 (leaves 0 ‖ 1),
e5065550823de86425f40f843e2cc41a4b842c2ea541a36baa4f437bf4252345 (leaf 2 ‖ leaf 2); root
21c6e97252abf108fe8728d0c54811da5d9acafb04329d66f1d0fec4c356b889; indices 0, 1, 2 in that order.
Test cases · §3
3 cases · 3 valid
Three receipts sorted by signature and folded into a root
Loading the test widget…
The batch's level-1 nodes, read from the proofs of leaves 0 and 2
Loading the test widget…
The proof of leaf 2: itself, then level 1's first node
Loading the test widget…
Defects to match. (1) A late receipt for an old block re-batches that height and changes its root; receipts already signed with the old root still verify (the root is only compared in §8). (2) The datum-hash root stored for a height with no receipts is never referenced by anything.
4. Published receipts in a block
Purpose. An implementation must carry, bound and store the receipts a block publishes.
Inputs. The block's published_receipts list; the active registry size n as of the previous
block (rule receipt_count_active); max_assigned_peers = P (the priority-peer count: 12 on the
testnet, 8 on the devnet; at least 2; 5 when the genesis does not name it); the hard cap 200.
Output and effect. Each published receipt is the receipt of §1 plus (wire message
PublishedReceipt, 27):
| Field | Number | Type | Meaning |
|---|---|---|---|
Receipt |
1 | Receipt | the receipt of §1 |
IntermediateHashes |
2 | bytes, k × 32, k ≤ 32 | the Merkle siblings of a linked receipt, leaf to root; empty for unlinked |
BlockHeight |
3 | uint32 | set by every node to the block's height when stored |
PublishedIndex |
4 | uint32 | set by every node to the position in the block (0…) when stored |
RMRLinked |
5 | bytes, 0 or 32 | the batch root the receipt is proven against; empty (or all zero) = unlinked |
RMRLinkedIndex |
6 | uint32 | the receipt's leaf index in that batch |
A receipt is linked iff RMRLinked contains a non-zero byte. Bounds: count ≤ 2 × min(n − 1, P) ("MaxAllowedReceiptsPerBlockExceeded", checked by the validator and again at application)
and count ≤ 200 ("Too many receipts in block"); the proof fields are bounded by 19 §8 (rule
block_size_serialized). The receipts are stored in published_receipt (§11) under the block's
height and their position, and counted into the blocksmith's score as linked / unlinked (§10).
How to compute it. As stated; the payload hash takes only the 232-byte receipt of each entry
(05 §6).
Rule activation. receipt_count_active, active from height 0 on every chain.
Rejections and errors. The two bounds; both make the block invalid.
Vector. computed (11 active registered nodes, P = 12): the bound is 2 × min(10, 12) = 20; a
block carrying 10 receipts, all of type 1, all unlinked (empty RMRLinked and
IntermediateHashes), is stored with published_index 0…9; the same registry with 21 receipts →
"MaxAllowedReceiptsPerBlockExceeded"; a registry of 3 registered nodes bounds a block to 2 ×
min(2, 12) = 4; with P = 8 (the devnet) and 11 nodes the bound is 2 × min(10, 8) = 16.
Test cases · §4
5 cases · 4 valid · 1 invalid · 1 reference
Eleven active registered nodes, P = 12: the bound is 20
Loading the test widget…
The same registry with 21 receipts
Loading the test widget…
A registry of 3 registered nodes
Loading the test widget…
Eleven active registered nodes with P = 8 (the devnet): the bound is 16
Loading the test widget…
A block carrying 10 unlinked receipts of type 1
A stated value: there is nothing to compute. A compatible node shows the same value.
- count
10- datum_type
1 (all)- linked
none- published_index
0…9
Defects to match. An all-zero RMRLinked of 32 bytes counts as unlinked but is still carried.
5. Validation of published receipts
Purpose. An implementation must accept exactly the published receipts every other node accepts.
Inputs. The block (height h, seed, blocksmith key, receipts); the local main chain (block
hashes and transactions); the scramble of §7; receipt_lifecycle (testnet 518,400 / devnet 1,440);
the active registry size n as of the previous block; the published receipts of the main chain
(§11); batch_receipt_lookback_height = 40, the lookback range 20.
Output and effect. Before application (19 §2 step 12), in this order: for h ≥ 40, the
lookback height is the height of the main-chain block holding the first unlinked receipt's
datum (a block hash, or a transaction hash of that block), else h − 40; two receipts with one
recipient signature → "DuplicateReceiptInBlock" (rule receipt_once); a lookback found from a
datum outside [h − 40 − 20, h − 40 + 20] → "ReceiptLookbackOutOfRange:<lookback>"; then each
receipt in order: its sender must be the block's blocksmith ("InvalidReceiptSender"); its
recipient signature must not be carried by a main-chain block in [max(0, h − 40), h)
("ReceiptAlreadyPublished", rule receipt_once, 19 §9); its signature must verify ("Invalid receipt signature"); its reference must be inside the reach (rule
receipt_reference_in_window): reference_block_height < h and h − reference_block_height ≤ 720, else "ReceiptReferenceOutOfWindow:<reference height>"; the main-chain block at that height
must be held, else "InvalidReceiptBlockHash:<reference height>" (a pruned or snapshot-synced
node holds the 720 blocks below its tip, 26); its reference hash must equal that block's hash
("InvalidReceiptBlockHash:<reference height>"); it must be young enough:
reference_block_height + expiry + 2 ≥ h with expiry = max(max(100, 2n) + 1, receipt_lifecycle)
("Receipt has expired"; it binds only on a chain whose expiry + 2 is below 720, which neither
shipped genesis allows: 518,400 and 1,440); if unlinked and h ≥ 40, its recipient must be among the
blocksmith's priority peers in the scramble of the lookback height ("InvalidReceiptReceiver",
"BlocksmithNotInScrambleList"; a scramble this node cannot build refuses the block on this node:
"cannot validate receipts: scramble unavailable at lookback height <H>"). After the loop the two
count bounds of §4.
During application (19 §4), for h ≥ 40: the count bound again; every receipt's sender is the
blocksmith again; when the main-chain block at the lookback range floor h − 40 − 20 is not held
(a pruned or freshly synced node) the block is refused on this node ("cannot validate receipts: lookback-range floor <F> not retained") and retried later; the unlinked receipts' lookback
(derived as above, the same range check) gives the datum list of the lookback block (its hash,
then its transaction hashes in order): each unlinked receipt's datum must be in it
("InvalidReceiptDatumHash") with the type matching its position (index 0 → 1, else 2;
"InvalidReceiptDatumType"), and the priority-peer rule holds again. From h ≥ 80 each linked
receipt's proof must verify (§8; "InvalidLinkedRMR"); below 80 linked receipts are counted without
proof.
How to compute it. As stated, in that order; the first failure refuses the block.
Rule activation. receipt_once (the two checks named above) and receipt_reference_in_window
(the reach and the held-reference refusal) are active from height 0 on every chain. The heights
40 and 80 are batch_receipt_lookback_height and twice it.
Rejections and errors. Listed above; all make the block invalid, except the two "cannot validate receipts" refusals, which refuse it on this node only.
Vector. computed (a block at 12,400 by blocksmith 6b9aa5c7… over the registry and the
period seed of §7's vector): the first receipt's datum 23b27894…10c04ae is the hash of the
main-chain block at 12,364 → lookback 12,364 ∈ [12,340, 12,380]; scramble period 12,360; the
blocksmith sits at scramble index 0 and its priority peers are the other ten registered nodes
(§7), so a receipt from any of those ten is accepted; every sender is the blocksmith; reference
height 12,364 is inside the reach (12,400 − 12,364 = 36 ≤ 720); expiry = max(max(100, 22) + 1,
518,400) = 518,400. INVALID: the same block with receipt 0's sender replaced by a09aa5f4…a4f0 →
"InvalidReceiptSender"; a block at 12,441 whose first unlinked receipt has datum 23b27894… →
lookback 12,364 ∉ [12,381, 12,421] → "ReceiptLookbackOutOfRange:12364"; a receipt with
reference_block_height 11,679 in a block at 12,400 → "ReceiptReferenceOutOfWindow:11679"
(721 > 720); one with 11,680 whose hash matches → accepted (720 ≤ 720); one with 12,400 →
"ReceiptReferenceOutOfWindow:12400".
Test cases · §5
10 cases · 3 valid · 7 invalid
A block at 12,400 by its blocksmith: lookback, reach, expiry and senders
Loading the test widget…
Receipt 0's sender replaced
Loading the test widget…
A block at 12,441 whose first unlinked receipt names block 12,364
Loading the test widget…
A receipt with reference height 11,679 in a block at 12,400 (721 below)
Loading the test widget…
A receipt with reference height 11,680 whose hash matches (720 below)
Loading the test widget…
A receipt whose reference height is the block's own height
Loading the test widget…
A receipt whose reference block (inside the reach) this node does not hold
Loading the test widget…
A receipt whose reference hash is not the held block's hash
Loading the test widget…
On a chain with receipt_lifecycle 0 (expiry 101), a receipt 105 blocks old
Loading the test widget…
The blocksmith of the block at 12,400 sits at scramble index 0: its priority peers are the other ten
Loading the test widget…
Defects to match. Every unlinked receipt in a block is judged against the lookback of the first one.
6. Receipt selection by the blocksmith (reproduced behaviour)
Purpose. Which receipts a blocksmith of the reference implementation puts in a block; an implementation that wants identical blocks follows it, one that only wants valid blocks may choose any receipts §5 accepts.
Inputs. The new block's height H, seed and blocksmith key; the blocksmith's batches and
receipts; n (the active registry as of the previous block); the cap max = min(min(n − 1, P), 200); the published_receipt rows of the main chain.
Output and effect. Unlinked: for H ≥ 40, take the blocksmith's batch root nearest to
H − 40 (exact, else the closest within ±20 by |height − target|, ties by the store's order);
build the datum list of the batch's height; pick the random datum (§9) from it; take the
batch's receipts for that datum and type (ascending signature, at most 1,000), leaving out every
receipt whose recipient signature a main-chain block at a height ≥ max(0, H − 40) carries — if
none, the first datum of the list that has some; keep those whose recipient is one of the
blocksmith's priority peers at the scramble of the batch's height (none → no receipts); drop those
whose reference hash disagrees with the local chain; cut to max; each becomes a published receipt
with published_index = its position, no proof, no link. Linked: for H ≥ 80, walk the
main-chain blocks from H − 1 down to H − 1 − 2(n + 40) (at most 200 rows, newest first) and,
for each block whose blocksmith had this node among its priority peers at the scramble of
height − 40 (consuming one of max steps per such block): take that block's first unlinked
published receipt addressed to this node (its rmr = ρ, this node's batch root at the time); pick
the random datum (§9) of that receipt's reference block; sort this node's priority peers at that
reference height by node key and pick one at random (§9, prefix zbc-receipt); find this node's
kept receipt for that datum and type addressed to that peer and not carried by a main-chain block at
a height ≥ max(0, H − 40) (else the first datum with one); require it to be batched, valid with a
reference-block check, and in the batch whose root is ρ; publish it with RMRLinked = ρ,
RMRLinkedIndex = its index in ρ's batch, IntermediateHashes = its Merkle siblings. Then:
duplicates by signature removed; linked receipts whose proof fails dropped; unlinked receipts dropped
when the scramble at the derived lookback cannot be built or the recipient is no longer a priority
peer. Last, whatever path selected them: every receipt whose recipient signature a main-chain
block in [max(0, H − 40), H) carries is removed and the rest renumbered 0…; when those rows
cannot be read the blocksmith offers no receipt for the block. This exclusion is applied whether
or not rule receipt_once is active (skipping is never invalid).
How to compute it. As stated; §9 for the random picks.
Rule activation. None (the exclusion is ungated; it matches what receipt_once refuses).
Rejections and errors. None (a failure yields fewer receipts).
Vector. computed (a block at H = 12,400, H − 40 = 12,360, the registry of §7's vector):
a blocksmith whose batch root nearest to 12,360 is the one of height 12,364 (within ±20) names
the datum of that height's block hash 23b27894…10c04ae (that block carried no transaction, so
its datum list is that one hash and a pick from it is index 0 without a draw); its receipts are
addressed to its ten priority peers, max = min(min(11 − 1, 12), 200) = 10. Had the block at
12,390 already carried the receipt with signature 57c7084d…d56d0e (23 §1), the blocksmith
would publish only the other nine, renumbered 0…8.
Test cases · §6
2 cases · 2 valid
The blocksmith's cap for a block at 12,400 over 11 registered nodes
Loading the test widget…
The block at 12,390 already carried one of the ten receipts
Loading the test widget…
Defects to match. (1) The random datum is drawn from the new block's own seed, so the pick is
known only once the seed is (05 §5). (2) published_index assigned by the blocksmith is overwritten
by every node with the block position.
7. The scramble and the priority peers
Purpose. An implementation must compute who may receipt whom in a period of 40 blocks.
Inputs. topology_period_blocks (40 in both genesis files; 40 when absent); P =
max_assigned_peers (12 testnet, 8 devnet); the 64-byte block seed of the period block
Q = h − (h mod 40); the registry as of Q: for every node id, its newest row with
height ≤ Q, kept when that row's status is Registered (0); rule topology_full_id.
Output and effect. Each node's scramble key = SHA3-256(seed (64) ‖ id as u64 LE ‖ Q as u64
LE ‖ "zbc-topology-v2" (15 ASCII bytes)), the id being the registry's signed 64-bit id
reinterpreted as unsigned. The scrambled list = the nodes sorted by key ascending (byte order),
ties by id then by node key; a node's index is its position. The priority peers of the node at
index i in a list of L nodes (rule topology_window_fix): start = (i × P) mod L; when
g = gcd(P, L) > 1, start = (start + (i div (L / g)) × k) mod L with k = 1 + seed[0] mod max(L / g − 1, 1); then visit positions (start + a + 1) mod L for a = 0, 1, …, skipping the
node itself and any repeat, until P peers are named or L positions were visited; a list of one
node has no peers. "A is a priority peer of B" means A is in B's list; the relation is not
symmetric. A published receipt's recipient must be a priority peer of the blocksmith (§5).
How to compute it. As stated.
Rule activation. topology_full_id, topology_window_fix: active from height 0 on every
chain.
Rejections and errors. "ReceiptSenderNotInScrambleList", "ReceiptRecipientNotInScrambleList",
"ReceiptRecipientNotInPriorityList" (the sender-side check on linked candidates);
"BlocksmithNotInScrambleList", "InvalidReceiptReceiver" (§5).
Vector. computed. INPUT: Q = 12,360, the seed of the block at 12,360 =
c4e0b8fda93fc1f62a7bbd349fc6bad4b0992bc47dc2538c9164659164567cc26295252cebb28ed3b0ea5082bc2e400830db3e902b0dfbfa5583cc5396e2de5a,
the eleven registered nodes of 20 §1 (ids and keys there), P = 12. EXPECTED OUTPUT (index: key
prefix, id, node key prefix): 0: 04efdaa3e8269f7d, 4,832,784,384,054,893,163, 6b9aa5c7;
1: 11222a5e7c51fbba, 3,715,018,299,146,412,646, 66a2b2c6; 2: 30ba61fce74ffa60,
3,219,899,983,035,352,172, 6cc41b8d; 3: 30e6bff3397fb1f0, 9,161,275,597,898,082,805,
f5692b26; 4: 6d9751941e74cbeb, 6,491,144,547,391,062,772, f442f504; 5: 6fe26fcd7877ed15,
1,590,136,471,457,360,039, a7e89b25; 6: 8d2140d574c43918, 88,697,328,554,714,370, 02a50719;
7: 935b6ecacaf4bec3, 1,417,521,806,099,974,635, eb89f581; 8: 9d970290140ccb06,
4,016,115,710,591,262,321, 715ea8e2; 9: d811df07b68d56fe, 5,679,266,776,148,337,025,
81e1fff8; 10: fdce5cf1cb10207a, 4,933,499,001,599,987,543, 578f1c02. The node at index 0
(6b9aa5c7…): start 0, gcd(12, 11) = 1, peers = indices 1…10 (ten, fewer than P because L − 1 =
10). INVALID: a receipt in a block by 6b9aa5c7… with lookback 12,364 addressed to a key outside
the list → "InvalidReceiptReceiver".
Test cases · §7
3 cases · 2 valid · 1 invalid · 1 reference
The scramble of period 12,360 and the priority peers of index 0
Loading the test widget…
Twelve nodes and P = 8 share windows: the start is mixed with the seed
Loading the test widget…
A receipt addressed outside the blocksmith's list
A stated value: there is nothing to compute. The statement is a refusal: the exact text a compatible node answers.
- refusal
InvalidReceiptReceiver
Defects to match. (1) With P ≥ L − 1 every node receipts every other node. (2) The registry "as of Q" counts a node admitted at Q itself.
8. Linked receipts and their proof
Purpose. An implementation must verify that a published receipt belongs to a committed batch.
Inputs. The published receipt's 232 bytes, RMRLinked, RMRLinkedIndex,
IntermediateHashes (k × 32 bytes).
Output and effect. leaf = SHA3-256(the 232 bytes) (§1); cur = leaf, i = RMRLinkedIndex;
for each 32-byte sibling in order: cur = SHA3-256(cur ‖ sibling) when i is even,
SHA3-256(sibling ‖ cur) when odd; i = i div 2; the receipt is valid iff cur = RMRLinked. No
siblings → valid iff leaf = RMRLinked. A length not a multiple of 32 is invalid. A proof is
generated level by level from the leaves (§3's tree): the sibling at index xor 1, or the node
itself when it has no sibling.
How to compute it. As stated.
Rule activation. None (validated from height 80).
Rejections and errors. "InvalidLinkedRMR", "LinkedReceiptFinalValidationError".
Vector. computed. INPUT: leaves = SHA3-256 of the single bytes 00…04:
5d53469f20fef4f8eab52b88044ede69c77a6a68a60728609fc4a65ff531e7d0,
2767f15c8af2f2c7225d5273fdd683edc714110a987d1054697c348aed4e6cc7,
0a1e2736777f80a62beb2df72b649878481c0ca10194b832b5136befbae54017,
e3ed56bd086d8958483a12734fa0ae7f5c8bb160ef9092c67e82ed9b19e4c7b2,
989216075a288af2c12f115557518d248f93c434965513f5f739df8c9d6e1932. EXPECTED OUTPUT: root
16fc6793cd693f2f8453c7e09e08efaa2277445cf6345f7b07a39d27c8abeefb; the proof of index 3 is
0a1e2736…bae54017, d9a58c55807dd1bd547132f162bb15314b2d185c828ae604c53e6eaf705a071c,
27bf3247cea980d35b3acc767543ff79caf2fe2eea2241b534b64eaf6c774868, and folding leaf 3 with index 3
returns the root. INVALID: the same leaf and siblings with RMRLinkedIndex 2 fold to
92e0dcd501a3f19c6e737bf4173e03f4b80bd2d3e412edcd625937cf87f7885c ≠ root → "InvalidLinkedRMR".
Test cases · §8
3 cases · 3 valid
Root of five leaves and the proof of leaf 3
Loading the test widget…
Folding leaf 3 with its proof returns the root
Loading the test widget…
The same proof with index 2 folds elsewhere (InvalidLinkedRMR)
Loading the test widget…
Defects to match. Nothing ties RMRLinked to a receipt the chain has seen: any root the
blocksmith holds a batch for is accepted, so the link is self-attested.
9. The random picks (reproduced exactly)
Purpose. The two pseudo-random choices the blocksmith makes, so an implementation can produce the same block.
Inputs. A 64-byte block seed; a list of m items; a prefix.
Output and effect. s = SHA3-256(prefix ‖ seed); x = the first 8 bytes of s as a
big-endian u64; a 64-bit Mersenne Twister (MT19937-64) seeded with x; one draw r uniform
over k values [0, k − 1] → the item at index r. Prefixes: "zbc-receipt-datum" (rule
receipt_datum_prefix) for the datum pick, over the whole list, k = m (index 0 = the block hash,
type 1; others = transaction hashes, type 2; m = 1 → index 0 without a draw); "zbc-receipt" for
the peer pick among the priority peers sorted by node key, over all but the last of them, k = m − 1
(the last peer by key is never picked; m = 1 → index 0 without a draw). The uniform draw over k
values: p = u × k as a 128-bit product with u the next engine output; if the low 64 bits of p
are below k, let t = (2⁶⁴ − k) mod k and redraw u (and p) while the low 64 bits of p are
below t; the result is p ≫ 64 (k = 1 → 0). The
engine is standard MT19937-64 (mt[0] = x, mt[i] = 6364136223846793005 × (mt[i−1] ⊕ (mt[i−1] ≫ 62)) + i mod 2⁶⁴; 312 words; twist with matrix B5026F5AA96619E9; tempering ≫29 & 5555555555555555,
≪17 & 71D67FFFEDA60000, ≪37 & FFF7EEE000000000, ≫43).
How to compute it. As stated.
Rule activation. receipt_datum_prefix, active from height 0 on every chain.
Rejections and errors. None.
Vector. computed. INPUT: engine seed 0x0123456789ABCDEF. EXPECTED OUTPUT: raw outputs
B6C31645639E9724, 04BC4BD824F74CA2; a draw over 3 values gives 2, over 2 values 1. INPUT: prefix
zbc-receipt-datum, the seed S of 20 §1. EXPECTED OUTPUT: s =
c8d428c040fb8c5007ee3aaf39fa212f1824a62063cb4bd482d815b0dc90895e, x = 0xC8D428C040FB8C50;
a datum list of 3 → index 2, of 2 → index 1. INPUT: prefix zbc-receipt, the same seed S, 3
priority peers. EXPECTED OUTPUT: x = 0xDF81F206A22BE201; a draw over the first 2 peers →
index 0.
Test cases · §9
7 cases · 7 valid
The 64-bit Mersenne Twister and one draw
Loading the test widget…
One draw over a list of 2
Loading the test widget…
The datum pick over a list of 3 with engine seed 0xC8D428C040FB8C50
Loading the test widget…
The datum pick over a list of 2 with the same engine seed
Loading the test widget…
The datum pick over a list of 3, drawn from the seed S
Loading the test widget…
The datum pick over a list of 2, drawn from the seed S
Loading the test widget…
The peer pick among three priority peers, drawn from the seed S
Loading the test widget…
Defects to match. A validator must not reproduce the pick — it accepts any datum of the list (§5).
10. Receipts and the participation score
Purpose. The economic effect of publishing, which every node computes alike.
Inputs. The block's published receipts (linked and unlinked counts); the draw set |S| and the
registry |R| at the previous block; the score-road parameters (21 §3).
Output and effect. In the block's liveness step (21 §3, 36): from height 40 the blocksmith's
score moves by the receipt delta: receipt_score = linked + unlinked (both weighing 1), cap = min(|S| − 1, P) (rule small_n_measurement), pivot = cap div 2, full = cap × max(1, min(linked weight, unlinked weight)) (one receipt per priority peer of either kind), span = max(1, full − pivot); at or above the pivot a climb of (min(receipt_score, full) − pivot) × ClimbPerUnit × |S| div (span × unit(|S|)) in 128-bit (ClimbPerUnit = 62,500,000,000 at
score_climb_ratio 8); below the pivot a drift down (21 §3). Each published receipt's
recipient is a sign of life: its last_seen_height becomes the receipt's reference height when
that is higher, which orders the expulsion floor (36); it resets no miss, lifts no suspension and
ends no missing stretch.
How to compute it. 21 §3.
Rule activation. small_n_measurement, receipt_count_active: active from height 0 on every
chain.
Rejections and errors. None.
Vector. computed (|S| = 11, P = 12 → cap 10, pivot 5, full 10, span 5, unit = max(11,
2,880) = 2,880): 10 receipts → (10 − 5) × 62,500,000,000 × 11 div (5 × 2,880) = 238,715,277;
12 receipts climb the same (capped at full).
Test cases · §10
2 cases · 2 valid
Ten receipts with a draw set of 11 and P = 12
Loading the test widget…
Twelve receipts climb no further than ten
Loading the test widget…
Defects to match. None.
11. State and the consensus/local split
Purpose. The records an implementation keeps for receipts and how each is read and written.
Inputs. The applied blocks, the pops, the prune horizon.
Output and effect. Three tables.
published_receipt (consensus: what the main chain carried; carried by snapshots, 26). One row
per published receipt of a stored block. Columns: sender_public_key (32 bytes),
recipient_public_key (32), datum_type (integer), datum_hash (32), reference_block_height
(integer), reference_block_hash (32), rmr (0 or 32 bytes), recipient_signature (64),
intermediate_hashes (null or k × 32), block_height (integer), rmr_linked (null or 32),
rmr_linked_index (integer), published_index (integer). Key: (block_height, published_index),
unique. Lookups the logic depends on: by block_height, by recipient_signature (the receipt-once
window), by rmr_linked, by datum_hash. Writes: applying block h first deletes every row with
block_height = h, then inserts one row per published receipt in block order with
published_index = its position and block_height = h. A pop-off to target t deletes every row with
block_height > t. The prune after each block deletes, oldest first, at most 500 rows with
block_height below min(receipt horizon, the reference height of the newest spine block), the
receipt horizon being h − max(max(100, 2 × registered nodes) + 1, receipt_lifecycle) (no prune while
that is ≤ 0). Reads: "is there a row with this recipient signature and block_height in [a, b)"
(§5, §6); "the first unlinked row of block b addressed to this node" (§6).
node_receipt (local: the receipts this node earned). Columns: the eight receipt fields of §1,
rmr_batch (null until batched, then the 32-byte batch root) and rmr_batch_index (0 until
batched, then the position in the batch). Key: (sender_public_key, recipient_public_key,
datum_type, datum_hash), unique; an insert of an existing key is ignored. Lookups by rmr,
recipient_public_key, reference_block_height. Reads: the unbatched rows whose datum is in a list
(§3); the rows of a batch root and datum, ordered by recipient_signature ascending, at most 1,000,
excluding signatures published at block_height ≥ a given height (§6); the first row for (datum,
type, recipient) (§6). A pop-off to t deletes the rows whose reference_block_height is above t.
Pruned: rows with reference_block_height below the
receipt horizon (h − expiry of §5, and in chunks of 500 below the prune horizon).
merkle_tree (local: this node's batch roots). Columns: id (the 32-byte root), block_height,
tree (the root bytes again), timestamp (wall-clock seconds at creation). Lookups by id and by
block_height. Writes: a batch of h replaces the row of h. A pop-off to t deletes rows above t.
Pruned below the receipt horizon. The node's latest batch root is the row with the highest
block_height.
Consensus: §1 bytes and signature, §4 bounds, §5 checks (with receipt_once), §7 scramble and
priority peers, §8 proof, the score effect and the sign of life (§10), published_receipt. Local:
§2 issuing and keeping (the request signature protects only who earns), §3 batching, §6 selection
and §9 picks (a blocksmith may choose otherwise and still make valid blocks), node_receipt,
merkle_tree. Node-local: a receipt earned on a popped branch whose reference height is at or
below t stays in node_receipt; what that store holds decides only which receipts this node may
select, never whether a block is valid.
How to compute it. As stated.
Rule activation. None beyond the sections above.
Rejections and errors. A failed write to published_receipt refuses the block on this node.
Vector. computed: applying block 12,400 writes ten published_receipt rows (12,400, 0…9); a
pop to 12,399 deletes them; re-applying the block writes them again; with receipt_lifecycle
518,400 nothing is pruned on the testnet before height 518,401.
Test cases · §11
1 case · 1 valid · 1 reference
Block 12,400's published_receipt rows across a pop and a re-apply
A stated value: there is nothing to compute. A compatible node shows the same value.
- apply
ten rows (12400, 0…9)- pop to 12399
deleted- re-apply
written again- first prune
after height 518,400
Defects to match. The prune of published_receipt runs in chunks of 500 rows per block, so a
backlog shrinks over several blocks.
A question about this chapter, or a statement that does not match the network? Discuss on zoobc.pro.