On this page
  1. §0 The area in one paragraph
  2. 1. The receipt and its bytes
  3. 2. Receipt requests, issuing and keeping receipts
  4. 3. Batches and the receipt Merkle root
  5. 4. Published receipts in a block
  6. 5. Validation of published receipts
  7. 6. Receipt selection by the blocksmith (reproduced behaviour)
  8. 7. The scramble and the priority peers
  9. 8. Linked receipts and their proof
  10. 9. The random picks (reproduced exactly)
  11. 10. Receipts and the participation score
  12. 11. State and the consensus/local split

23 — Receipts

Edition 0.6.1 · verified against the reference implementation, version 0.6.1

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.

  1. Concatenate the eight fields of the table up to offset 168 (rmr as carried: an empty rmr makes the unsigned bytes 136 long).
  2. Sign those bytes with Ed25519 under the recipient's node key; append the 64-byte signature.
  3. Hash: SHA3-256 of the 232 bytes, an empty rmr written as 32 zero bytes.
  4. To verify: check the sizes (keys 32, hashes 32, rmr 0 or 32, signature 64), then the Ed25519 signature over the unsigned bytes under recipient_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 receipt23-1-receiptvalid

Loading the test widget…

The same receipt with an empty rmr23-1-empty-rmrvalid

Loading the test widget…

A 31-byte rmr is refused23-1-short-rmrinvalid

Loading the test widget…

A changed signature byte does not verify23-1-tamperedinvalid

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 carried block_hash equals SHA3-256(header ‖ signature) → one receipt, type 1, over the block hash, in SendBlockResponse.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.

  1. Sender: for each recipient, digest as above; sign with Ed25519; put the 64 bytes in the request's SenderSignature.
  2. Recipient: if the claimed key is empty → no receipt. If SenderSignature is non-empty: recompute the digest with its own key as the recipient; verify → step 3, else no receipt. If empty: require_signed_receipt_requests true → no receipt; false → step 3.
  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 block23-2-block-requestvalid

Loading the test widget…

The datum of a pushed transaction23-2-tx-datumvalid

Loading the test widget…

A receipt request for a transaction23-2-tx-requestvalid

Loading the test widget…

The datum of a batch23-2-batch-datumvalid

Loading the test widget…

A receipt request for a batch23-2-batch-requestvalid

Loading the test widget…

The block request's signature checked by another recipient23-2-wrong-recipientinvalid

Loading the test widget…

The request digest naming the other recipient23-2-wrong-recipient-digestvalid

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.

  1. Collect the receipts (new + existing of h); drop those failing §1.
  2. Sort by the 64 signature bytes (byte order).
  3. Leaves = receipt hashes in that order; fold as above.
  4. 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 root23-3-batchvalid

Loading the test widget…

The batch's level-1 nodes, read from the proofs of leaves 0 and 223-3-levelsvalid

Loading the test widget…

The proof of leaf 2: itself, then level 1's first node23-3-levels-2valid

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 2023-4-bound-11valid

Loading the test widget…

The same registry with 21 receipts23-4-bound-21invalid

Loading the test widget…

A registry of 3 registered nodes23-4-bound-3valid

Loading the test widget…

Eleven active registered nodes with P = 8 (the devnet): the bound is 1623-4-bound-devnetvalid

Loading the test widget…

A block carrying 10 unlinked receipts of type 123-4-storedvalidreference

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 senders23-5-acceptedvalid

Loading the test widget…

Receipt 0's sender replaced23-5-senderinvalid

Loading the test widget…

A block at 12,441 whose first unlinked receipt names block 12,36423-5-lookbackinvalid

Loading the test widget…

A receipt with reference height 11,679 in a block at 12,400 (721 below)23-5-reference-721invalid

Loading the test widget…

A receipt with reference height 11,680 whose hash matches (720 below)23-5-reference-720valid

Loading the test widget…

A receipt whose reference height is the block's own height23-5-reference-selfinvalid

Loading the test widget…

A receipt whose reference block (inside the reach) this node does not hold23-5-reference-unheldinvalid

Loading the test widget…

A receipt whose reference hash is not the held block's hash23-5-reference-hashinvalid

Loading the test widget…

On a chain with receipt_lifecycle 0 (expiry 101), a receipt 105 blocks old23-5-expiredinvalid

Loading the test widget…

The blocksmith of the block at 12,400 sits at scramble index 0: its priority peers are the other ten23-5-scramblevalid

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 nodes23-6-maxvalid

Loading the test widget…

The block at 12,390 already carried one of the ten receipts23-6-exclusionvalid

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 023-7-testnet-12360valid

Loading the test widget…

Twelve nodes and P = 8 share windows: the start is mixed with the seed23-7-gcdvalid

Loading the test widget…

A receipt addressed outside the blocksmith's list23-7-receiverinvalidreference

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 323-8-proofvalid

Loading the test widget…

Folding leaf 3 with its proof returns the root23-8-foldvalid

Loading the test widget…

The same proof with index 2 folds elsewhere (InvalidLinkedRMR)23-8-fold-wrong-indexvalid

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 draw23-9-enginevalid

Loading the test widget…

One draw over a list of 223-9-engine-twovalid

Loading the test widget…

The datum pick over a list of 3 with engine seed 0xC8D428C040FB8C5023-9-datum-3valid

Loading the test widget…

The datum pick over a list of 2 with the same engine seed23-9-datum-2valid

Loading the test widget…

The datum pick over a list of 3, drawn from the seed S23-9-datum-pickvalid

Loading the test widget…

The datum pick over a list of 2, drawn from the seed S23-9-datum-pick-2valid

Loading the test widget…

The peer pick among three priority peers, drawn from the seed S23-9-peer-pickvalid

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 = 1223-10-climbvalid

Loading the test widget…

Twelve receipts climb no further than ten23-10-twelvevalid

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-apply23-11-rowsvalidreference

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.