On this page
  1. §0 The area in one paragraph
  2. §1 Transport, framing and limits
  3. §1a The signed call
  4. §2 Messages
  5. §2.1 The services
  6. §2.2 Records shared by several RPCs
  7. §2.3 Request and response messages
  8. §3 Handshake
  9. §4 Heartbeat
  10. §5 Peer discovery
  11. §6 Node address announcements
  12. §7 Proof of origin
  13. §8 Receipt requests
  14. §9 Block delivery
  15. §10 Transaction delivery
  16. §11 Chain sync queries and the block-read budget
  17. §12 Spine signature and non-signing statement RPCs
  18. §13 Snapshot chunk download
  19. §14 Block candidates and storage pieces
  20. §15 GetStateSample
  21. §16 Load levels
  22. §17 Data kept, consensus and local

27 — P2P wire protocol

Edition 0.6.1 · verified against the reference implementation, version 0.6.1

Out of scope the peer table, scoring, blacklists, connection limits, priority peers and rate limiters (28); the sync algorithm that drives the sync RPCs (24); spine block validation and the rules for giving spine signatures (25); snapshot content (26); block validation (19) and application (21); receipt construction (23); transaction byte layout (03)

§0 The area in one paragraph

Nodes talk to each other over plain gRPC (HTTP/2, no TLS) on one TCP port, 8001 by default, where a node serves two services of package service: P2PCommunication (seventeen RPCs: peer lists, node addresses, proof of origin, block and transaction delivery, the chain-sync queries, spine signatures and non-signing statements, snapshot chunk download) and P2PServiceExtended (seven RPCs: the signed handshake, the signed heartbeat, block candidates, block-hash ranges, the state sample of the snapshot attestation and the two storage-piece transports). Every call is signed by the calling node's key (§1a): six metadata entries carry the caller's key, a timestamp, the SHA3-256 of the request body, an 8-byte nonce, the receiver's node key and an Ed25519 signature under the domain ZBC-P2P-RPC-V3; a call without them, with a signature that does not verify, made to another node, or replayed is refused UNAUTHENTICATED, and every call but the handshake must come from a key that completed a handshake with this node. Every byte that matters for compatibility is a protobuf (proto3) message defined in §2, a preimage signed with the node's Ed25519 key (the call itself, handshake, heartbeat, address announcement, proof of origin, receipt request, piece request, spine non-signing statement), or the canonical transaction bytes of 03 carried opaquely in TransactionBytes. A block travels as the Block message with its transactions usually replaced by their ids; the receiver fills them from its pool or asks for the missing ones, and the answer comes back on a separate call to the asker. A node that pushes a block or transaction to a peer signs a receipt request for that peer (§8); the peer pays a receipt (23) only for a request that verifies. Every per-host cap, budget, cool-down and strike is keyed on the caller's host: an IPv4 address as it is, an IPv6 address by its /64. Nothing in this chapter is hashed into the chain; it fixes who a node talks to (the handshake proves a key, a genesis hash and a fresh clock; an address is trusted only once this node's own dial reaches the key there), what it accepts (size caps, budgets, registered-sender privileges, load gates) and what it answers. An implementation that deviates in a signed preimage, a field number or a size rule is dropped, banned for 15 minutes or starved of blocks.

§1 Transport, framing and limits

Purpose. What an implementation must do to carry every message of this chapter.

Inputs. A peer address host:port; the method name; the serialised request.

Output and effect. A serialised response and a gRPC status code, or a transport failure.

How to compute it.

  1. gRPC over HTTP/2, plaintext. Each message is one 5-byte prefix (compressed flag 0, big-endian u32 length) followed by the protobuf bytes; the path is /service.<Service>/<Method>, content-type application/grpc; the status travels in the trailers grpc-status and grpc-message. No compression.

  2. One listening socket (listen_address, default 0.0.0.0:8001) serves both services; advertise_address (30) is what the node announces.

  3. Server limits: maximum received message 2,097,152 bytes; a larger request fails with RESOURCE_EXHAUSTED before any handler runs. Server keepalive: ping every 60 s, 20 s timeout, pings allowed without calls, minimum accepted ping interval 20 s, no ping strikes. The server runs at most 128 handler threads.

  4. Client channels: keepalive 30 s / 10 s timeout, allowed without calls; reconnect backoff 1,000–5,000 ms; maximum send and receive message 8,388,608 bytes. The channels used for the reply to RequestBlockTransactions use the gRPC defaults (4 MiB receive).

  5. Client deadlines: 8,000 ms for GetMorePeers, SendPeers, SendNodeAddressInfo, GetPeerInfo, Handshake, Heartbeat, GetNextBlockIDs, RequestSpineBlockSignature, RequestSpineRefusal, GetBlockHashes, GetStoragePiece, PutStoragePiece; 12,000 ms for GetCommonMilestoneBlockIDs; 16,000 ms for SendTransaction and GetNextBlocks; 10,000 ms for GetCumulativeDifficulty, a direct SendBlock and BroadcastBlockCandidate; 5,000 ms for the blocksmith's block broadcast, the relays and the discovery GetMorePeers; 15,000 ms for RequestBlockTransactions and the SendBlockTransactions that answers it.

  6. Protobuf rules relied on (proto3): a field holding its default (0, false, empty) is omitted and reads back as the default; repeated int64 fields are emitted packed and accepted packed or unpacked; a negative int64 is a ten-byte varint; unknown field numbers are skipped; binary data always travels in bytes fields (a string field must be valid UTF-8).

  7. Every call carries the signed metadata of §1a; a handshake is the only call that may name no receiver.

Rule activation. None: the wire protocol has no activation heights.

Rejections and errors. Status codes: UNAUTHENTICATED (a call that is not signed, does not verify, is made to another node, carries a timestamp outside the window or was seen before, §1a; a bad heartbeat signature), FAILED_PRECONDITION (a caller with no handshake on this chain, §1a; a heartbeat timestamp outside the window; spine or registry not configured), INVALID_ARGUMENT (malformed or over-sized requests), RESOURCE_EXHAUSTED (load shedding, budgets, rate limits), NOT_FOUND, INTERNAL, PERMISSION_DENIED (archive-only storage piece; a block-transactions request from a caller this node never dialled). Application refusals are status OK with accepted = false / found = false / given = false / available = false and a message or error text.

Vector. computed: a GetBlockHashesRequest{start_height 12000, end_height 12002} is the 6 protobuf bytes 08E05D10E25D, framed as 00 00000006 08E05D10E25D on /service.P2PServiceExtended/GetBlockHashes, with the six metadata entries of §1a in the call's headers.

Test cases · §1

3 cases · 3 valid · 2 reference

A GetBlockHashes request, its bytes and its gRPC frame27-1-framevalid

Loading the test widget…

The transport limits27-1-limitsvalidreference

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

server_max_receive_bytes
2097152
client_max_message_bytes
8388608
server_keepalive_s
60/20
client_keepalive_s
30/10
server_handler_threads
128
reconnect_backoff_ms
1000-5000
The client deadlines27-1-deadlinesvalidreference

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

8000_ms
GetMorePeers, SendPeers, SendNodeAddressInfo, GetPeerInfo, Handshake, Heartbeat, GetNextBlockIDs, RequestSpineBlockSignature, RequestSpineRefusal, GetBlockHashes, GetStoragePiece, PutStoragePiece
12000_ms
GetCommonMilestoneBlockIDs
16000_ms
SendTransaction, GetNextBlocks
10000_ms
GetCumulativeDifficulty, direct SendBlock, BroadcastBlockCandidate
5000_ms
the producer's block broadcast, the relays, the discovery GetMorePeers
15000_ms
RequestBlockTransactions and the SendBlockTransactions that answers it

Defects to match. None at the transport level.

§1a The signed call

Purpose. What an implementation must attach to every call it makes, and check on every call it serves, so that only a node holding a key can speak to it and a captured call is good nowhere else.

Inputs. The method name (the RPC name as in §2.1, e.g. GetNextBlocks); the serialised request body; the caller's node key pair; the receiver's node key (the key of the peer-table entry the call is made to; empty only for a Handshake made to an address whose key is not yet known); the caller's clock; 8 random bytes.

Output and effect. Six gRPC metadata entries on the call (binary entries carry raw bytes):

Metadata key Value
zbc-sender-key-bin the caller's node key (32 bytes)
zbc-request-timestamp the caller's clock in seconds, decimal ASCII
zbc-request-digest-bin SHA3-256 of the serialised request body (32 bytes)
zbc-request-nonce-bin 8 random bytes, fresh per call
zbc-receiver-key-bin the receiver's node key (32 bytes); absent on a handshake by address
zbc-request-signature-bin Ed25519 (64 bytes) by the caller's key over the signing message

The signing message:

Offset Length Field
0 14 "ZBC-P2P-RPC-V3" (ASCII, no terminator)
14 1 0x00
15 m the method name (ASCII)
15+m 1 0x00
16+m 1 the receiver key's length (32, or 0 when absent)
17+m 0 or 32 the receiver's node key
17+m+r 8 timestamp i64 LE
25+m+r 32 the request digest
57+m+r 8 the nonce

The receiver, before any handler runs (a call with no transport, made in-process, is exempt):

  1. The caller's host = the host of the connection's peer string (ipv4:host:port, ipv6:[host]:port, also the percent-encoded ipv6:%5Bhost%5D:port), grouped (an IPv4 literal as it is, an IPv4 address mapped into IPv6 as the IPv4 literal, an IPv6 literal by its /64 written a:b:c:d::/64); its strike key is addr: + the host.
  2. None of the six entries present → "P2P calls must be signed by a node key". One of the five mandatory entries missing or repeated, a key not 32 bytes, a digest not 32, a signature not 64, a nonce not 8, a present receiver not 32 bytes → "signed request metadata malformed".
  3. Every method but Handshake requires a receiver; a receiver present must equal this node's key → else "signed request was made to another node".
  4. The timestamp must be a plain decimal integer (else "signed request metadata malformed") and lie within ±600 s of the receiver's clock → else "signed request timestamp outside the 600 s window; check NTP".
  5. The signature must verify over the signing message built from the claimed digest (one fixed-cost verify before any body hash) → else "signed request signature does not verify".
  6. SHA3-256 of the received body must equal the claimed digest → else "signed request digest is not this request's".
  7. Replay: the 64 signature bytes (unique per call, the nonce being signed) are looked up in a ring of the signatures served inside the last 600 s, capped at 120,000 entries (200 calls per second for the whole window); an entry already present → "signed request seen before". When the ring is full the oldest entry is forgotten, never the whole ring.
  8. A refusal of steps 2, 3, 5, 6 or 7 (a timestamp that does not parse included) is answered UNAUTHENTICATED "<Method>: <why>" and records one invalid block against the host's strike key (28 §6; five in 60 s throttle the host's blocks); a timestamp outside the window (a wrong clock, not an attack) is answered the same way without a strike.
  9. The caller identity for every budget and cool-down: a registered key is charged under its key (lower-case hex); any other verified key under <key hex>@<host>, so two nodes behind one address have separate budgets while the per-host ceilings (eight callers' worth) bound what one host can mint.
  10. The handshake requirement: every method but Handshake then requires the signing key to hold a peer-table entry marked handshake-verified (a same-chain handshake with this node, in either direction, §3) → else FAILED_PRECONDITION "no handshake for this chain".

How to compute it. As stated; the caller builds the message with the method name of the call site, so two methods sharing a request type never share a signature.

Rule activation. None (a P2P policy; both chains relaunch on 0.6.1 and nothing but a node speaks this protocol, so there is no unsigned path).

Rejections and errors. As listed; a node that cannot sign (no private key) logs once and sends the call unsigned, which every peer refuses.

Vector. computed. INPUT: method GetNextBlockIDs; receiver B = F5692B269E6323FF07078505671DCAA4CF40A0753423D02C54EC9B110977CDD3; request bytes 10F6E5B1A6AAFBC4C3E8011832 (§2's GetNextBlockIdsRequest); timestamp 1,794,211,200; nonce 0102030405060708. EXPECTED OUTPUT: digest 7879EE9C76FC9FC11AB2312AFA46A497776A531DC7C8D2B254C81A4AF8BC0D11; signing message (112 bytes) 5A42432D5032502D5250432D5633 00 4765744E657874426C6F636B494473 00 20 <B> 807DF16A00000000 <digest> 0102030405060708, i.e. 5A42432D5032502D5250432D5633004765744E657874426C6F636B4944730020F5692B269E6323FF07078505671DCAA4CF40A0753423D02C54EC9B110977CDD3807DF16A000000007879EE9C76FC9FC11AB2312AFA46A497776A531DC7C8D2B254C81A4AF8BC0D110102030405060708. A Handshake by address with the same digest, timestamp and nonce signs the 74-byte message 5A42432D5032502D5250432D5633 00 48616E647368616B65 00 00 807DF16A00000000 <digest> <nonce>. INVALID: the same call served again inside 600 s → UNAUTHENTICATED "GetNextBlockIDs: signed request seen before"; made with receiver A to node B → "GetNextBlockIDs: signed request was made to another node"; stamped 1,794,211,900 at a receiver whose clock reads 1,794,211,200 → "… timestamp outside the 600 s window; check NTP", no strike.

Test cases · §1a

19 cases · 7 valid · 12 invalid

The signing message of a GetNextBlockIDs call to node B27-1a-messagevalid

Loading the test widget…

A Handshake by address names no receiver: the 74-byte signing message27-1a-handshake-messagevalid

Loading the test widget…

Node B serves the call: signed for it, fresh, from a key with a handshake27-1a-verifiedvalid

Loading the test widget…

The same call served again inside 600 s27-1a-replayinvalid

Loading the test widget…

A call made with receiver A, received by node B27-1a-other-nodeinvalid

Loading the test widget…

A call stamped 1,794,211,900 at a receiver whose clock reads 1,794,211,200: refused, no strike27-1a-clockinvalid

Loading the test widget…

A call with none of the six entries27-1a-unsignedinvalid

Loading the test widget…

A call whose signature entry is missing27-1a-no-signatureinvalid

Loading the test widget…

A call carrying the nonce entry twice27-1a-repeated-nonceinvalid

Loading the test widget…

A call with a 7-byte nonce27-1a-short-nonceinvalid

Loading the test widget…

A GetNextBlockIDs call that names no receiver27-1a-no-receiverinvalid

Loading the test widget…

A timestamp entry that is not a plain decimal integer27-1a-timestamp-textinvalid

Loading the test widget…

A call whose signature does not verify27-1a-bad-signatureinvalid

Loading the test widget…

A signed header delivered with another body27-1a-other-bodyinvalid

Loading the test widget…

A verified call from a key with no handshake with this node27-1a-no-handshakeinvalid

Loading the test widget…

A Handshake that names no receiver passes the signed-call checks27-1a-handshake-by-addressvalid

Loading the test widget…

Five refused calls from one host within 60 s throttle its unbound blocks27-1a-strikesvalid

Loading the test widget…

Five calls with a wrong clock strike nothing27-1a-skew-no-strikevalid

Loading the test widget…

Four refused calls do not throttle27-1a-four-strikesvalid

Loading the test widget…

Defects to match. None.

§2 Messages

Purpose. The exact field numbers, types and meanings of every message; an implementation must reproduce them or no node parses its traffic.

Inputs / Output. Package service, syntax proto3. Types are protobuf scalar types; "bytes(32)" means a bytes field that must hold exactly 32 bytes to be meaningful.

How to compute it.

§2.1 The services

service.P2PCommunication Request → Response §
GetNodeAddressesInfo GetNodeAddressesInfoRequest → GetNodeAddressesInfoResponse §6
SendNodeAddressInfo SendNodeAddressInfoRequest → Empty §6
GetNodeProofOfOrigin GetNodeProofOfOriginRequest → ProofOfOrigin §7
GetPeerInfo GetPeerInfoRequest → GetPeerInfoResponse §5
GetMorePeers Empty → GetMorePeersResponse §5
SendPeers SendPeersRequest → Empty §5
SendBlock SendBlockRequest → SendBlockResponse §9
SendTransaction SendTransactionRequest → SendTransactionResponse §10
SendBlockTransactions SendBlockTransactionsRequest → SendBlockTransactionsResponse §10
RequestBlockTransactions RequestBlockTransactionsRequest → Empty §10
RequestSpineBlockSignature SpineBlockSignatureRequest → SpineBlockSignatureResponse §12
RequestSpineRefusal SpineRefusalRequest → SpineRefusalResponse §12
GetCumulativeDifficulty GetCumulativeDifficultyRequest → GetCumulativeDifficultyResponse §11
GetCommonMilestoneBlockIDs GetCommonMilestoneBlockIdsRequest → GetCommonMilestoneBlockIdsResponse §11
GetNextBlockIDs GetNextBlockIdsRequest → BlockIdsResponse §11
GetNextBlocks GetNextBlocksRequest → BlocksData §11
RequestFileDownload FileDownloadRequest → FileDownloadResponse §13
service.P2PServiceExtended Request → Response §
Handshake HandshakeRequest → HandshakeResponse §3
Heartbeat HeartbeatRequest → HeartbeatResponse §4
BroadcastBlockCandidate BroadcastBlockCandidateRequest → BroadcastBlockCandidateResponse §14
GetBlockHashes GetBlockHashesRequest → GetBlockHashesResponse §11
GetStateSample GetStateSampleRequest → GetStateSampleResponse §15
GetStoragePiece GetStoragePieceRequest → GetStoragePieceResponse §14
PutStoragePiece PutStoragePieceRequest → PutStoragePieceResponse §14

§2.2 Records shared by several RPCs

Empty and GetPeerInfoRequest have no fields.

Block (the block record of 05; a spine block of 25 uses the same message):

# Field Type Meaning
1 ID int64 block id (05 §4); 0 on receipt with a non-empty BlockHash → recomputed from the hash
2 BlockHash bytes(32) block hash (05 §4)
3 PreviousBlockHash bytes(32) parent hash
4 Height uint32 height
5 Timestamp int64 seconds
6 BlockSeed bytes(64) the block seed
7 BlockSignature bytes blocksmith signature (64); for a spine block the aggregate of 25 §6
8 CumulativeDifficulty string decimal (24); for a spine block its weight
9 BlocksmithPublicKey bytes(32) blocksmith's node key
10 TotalAmount int64
11 TotalFee int64
12 TotalCoinBase int64
13 Version uint32 the bundle id (05; 601 for a 0.6.1 blocksmith)
14 PayloadLength uint32
15 PayloadHash bytes(32)
16 MerkleRoot bytes receipt Merkle root (23); a spine block's informative copy
17 MerkleTree bytes serialised receipt tree (23); empty on a main-chain block under block_size_serialized (19)
18 ReferenceBlockHeight uint32 spine blocks: the referenced main height
19 Transactions repeated Transaction full transactions (empty when ids are sent)
20 PublishedReceipts repeated PublishedReceipt
21 SpinePublicKeys repeated SpinePublicKey spine blocks only
22 SpineBlockManifests repeated SpineBlockManifest spine blocks only
23 TransactionIDs repeated int64 transaction ids when the transactions are not carried
24 BlockSeedProof bytes(80) the VRF proof of the seed (20); empty below rule seed_vrf
25 ReferenceCommitment bytes spine blocks: the reference commitment (25 §2); empty on main chain blocks and spine block 0
26 SpineRefusals repeated SpineRefusal non-signing statements; a spine block carrying any is invalid (25 §7), so always empty

Decoding caps (the transport caps, 32 §16): a Block with more than max(500, max_transactions_per_block) = 2,000 on both chains Transactions or TransactionIDs, or more than 65,536 PublishedReceipts, SpinePublicKeys, SpineBlockManifests or SpineRefusals, is refused: where a node serves (every request it receives) it decodes to an empty block (height 0, no hash), which every consumer then refuses; where a node reads an answer (sync replies, a spine signer's promised_block) the block is refused outright ("GoProtoToBlock: oversized repeated field (anti-amplification)"). The cap equals max_transactions_per_block, so every valid block decodes. When both Transactions and TransactionIDs are present the block is processed from Transactions.

Transaction (output: every field filled; input: TransactionBytes decides):

# Field Type Meaning
1 Version uint32
2 ID int64
3 BlockID int64
4 Height uint32
5 SenderAccountAddress bytes typed account (01)
6 RecipientAccountAddress bytes typed account
7 TransactionType uint32
8 Fee int64
9 Timestamp int64
10 TransactionHash bytes(32)
11 TransactionBodyLength uint32
12 TransactionBodyBytes bytes
13 TransactionIndex uint32
14 MultisigChild bool
31 Signature bytes
32 TransactionBytes bytes the canonical signed bytes of 03
33 Message bytes
34 Survival int64 only when Version ≥ 2
35 Expiry uint32 only when Version ≥ 3

On input, a non-empty TransactionBytes is parsed (03, with signature) and every other field is ignored except a non-empty TransactionHash, which replaces the parsed hash (block application recomputes the hash and refuses a mismatch, "Transaction hash mismatch"); with TransactionBytes empty the fields are copied one by one, TransactionBodyLength defaulting to the body's size and ID to the hash-derived id.

Receipt (23 §1): SenderPublicKey #1 bytes(32), RecipientPublicKey #2 bytes(32), DatumType #3 uint32 (1 block, 2 transaction), DatumHash #4 bytes(32), ReferenceBlockHeight #5 uint32, ReferenceBlockHash #6 bytes(32), RMR #7 bytes(32), RecipientSignature #8 bytes(64).

PublishedReceipt (23): Receipt #1 Receipt, IntermediateHashes #2 bytes (32 × k), BlockHeight #3 uint32, PublishedIndex #4 uint32, RMRLinked #5 bytes, RMRLinkedIndex #6 uint32.

SpinePublicKey (25 §3): NodePublicKey #1 bytes(32), NodeID #2 int64, PublicKeyAction #3 uint32 (0 add, 1 remove), MainBlockHeight #4 uint32, Height #5 uint32.

SpineBlockManifest (25 §4): ID #1 int64, FullFileHash #2 bytes(32), FileChunkHashes #3 bytes (32 × k), ManifestReferenceHeight #4 uint32, ManifestSpineBlockHeight #5 uint32, ChainType #6 uint32, ExpirationTimestamp #7 int64, ChainGenesisHash #8 bytes(32). The manifest type is not carried (a received manifest is type 0).

Node: ID #1 int64, PublicKey #2 bytes(32), RegistrationHeight #3 int64, Address #4 string, Port #5 uint32, SharedAddress #6 uint32, RegistrationStatus #7 int64, Height #8 int64, Version #9 string, CodeName #10 string, ArchivalApiUrl #11 string. Senders fill only the fields named in §5.

Peer (defined, never sent): Info #1 Node, LastInboundRequest #2 int64, BlacklistingCause #3 int64, BlacklistingTime #4 int64, ConnectionState #5 string.

§2.3 Request and response messages

Message # Field Type Meaning, bounds
SendBlockRequest 1 Block Block the block
2 ChainType int32 1 spine, any other value main
3 SenderPublicKey bytes(32) the sender's node key (claimed)
4 SenderChainHeight uint32 never read
5 SenderCumulativeDifficulty string never read
6 SenderSignature bytes(64) receipt request, datum type 1 (§8); empty = unsigned
SendBlockResponse 1 Receipt Receipt a receipt, or absent
SendTransactionRequest 1 TransactionBytes bytes canonical signed transaction (03), ≤ max block size
2 ChainType int32 0
3 SenderPublicKey bytes(32) claimed sender key
4 SenderSignature bytes(64) receipt request, datum type 2 (§8)
SendTransactionResponse 1 Receipt Receipt a receipt, or absent
SendBlockTransactionsRequest 1 ChainType int32
2 TransactionsBytes repeated bytes ≤ 500 entries, ≤ 2,097,152 bytes together
3 SenderPublicKey bytes(32)
4 SenderSignature bytes(64) receipt request, datum type 3 over the whole list (§8)
SendBlockTransactionsResponse 1 Receipts repeated Receipt one per accepted entry, in order
RequestBlockTransactionsRequest 1 TransactionIDs repeated int64 ≤ 500
2 ChainType int32
3 BlockID int64 the block the ids belong to (informative)
4 RequesterPublicKey bytes(32) the asker's node key: the reply's receipt request is signed for it (§10); empty = the key that signed the call
GetCumulativeDifficultyRequest 1 ChainType int32 0 main, 1 spine
GetCumulativeDifficultyResponse 1 CumulativeDifficulty string the tip's, decimal
2 Height uint32 the tip height
GetCommonMilestoneBlockIdsRequest 1 ChainType int32
2 LastBlockID int64
3 LastMilestoneBlockID int64
GetCommonMilestoneBlockIdsResponse 1 BlockIds repeated int64 ≤ 10
2 Last bool
GetNextBlockIdsRequest 1 ChainType int32
2 BlockId int64 start after this block
3 Limit uint32 clamped to 100
BlockIdsResponse 1 BlockIds repeated int64
GetNextBlocksRequest 1 ChainType int32
2 BlockId int64 never read
3 BlockIds repeated int64 ≤ 50
BlocksData 1 NextBlocks repeated Block full blocks, transactions included
SpineBlockSignature 1 node_public_key bytes(32) the spine signer
2 signature bytes(64) Ed25519 over the 204 header bytes
3 node_id int64 the spine signer's registry id, 0 when unknown
4 timestamp int64 the spine signer's clock
SpineRefusal 1 spine_height uint32 a non-signing statement (25 §6b): its spine height
2 refused_block_hash bytes(32) the identity of the spine block candidate it does not sign (25 §1)
3 node_public_key bytes(32) the registered node making the statement
4 signature bytes(64) over the digest of the non-signing statement (25 §6b)
SpineBlockSignatureRequest 1 block Block the spine block candidate with the spine blocksmith's 64-byte signature
2 refusals repeated SpineRefusal non-signing statements on the candidate the spine signer committed to
SpineBlockSignatureResponse 1 accepted bool
2 error string "abstain: …", "refused: …" or a form error
3 signature SpineBlockSignature present when accepted
4 promised_block_hash bytes(32) set when refused because of a signing commitment: the identity of the candidate it committed to
5 promised_bar uint32 the required spine signatures stored with the commitment (informative)
6 promised_block Block the candidate it committed to, stripped (25 §6a)
SpineRefusalRequest 1 spine_height uint32 informative
2 refused_block_hash bytes informative
3 proposal Block the spine block candidate the statement is asked for, with its spine blocksmith's signature
SpineRefusalResponse 1 given bool
2 error string reason when not given
3 refusal SpineRefusal present when given
GetPeerInfoResponse 1 HostInfo Node PublicKey, Height, ArchivalApiUrl
GetMorePeersResponse 1 Peers repeated Node PublicKey, Address = "host:port", Height
SendPeersRequest 1 Peers repeated Node ≤ 100 read; Address = bare host, Port
NodeAddressInfo 1 NodeID int64
2 Address string "host:port"
3 Port uint32
4 BlockHash bytes(32)
5 BlockHeight uint32
6 Signature bytes(64) §6
7 Status uint32 1 pending, 2 confirmed
GetNodeAddressesInfoRequest 1 NodeIDs repeated int64 ≤ 1,000; empty = all
GetNodeAddressesInfoResponse 1 NodeAddressesInfo repeated NodeAddressInfo
SendNodeAddressInfoRequest 1 NodeAddressInfoMessage repeated NodeAddressInfo ≤ 1,000
GetNodeProofOfOriginRequest 1 ChallengeMessage bytes
2 Timestamp int64
ProofOfOrigin 1 MessageBytes bytes §7
2 Timestamp int64 echoed
3 Signature bytes(64)
FileDownloadRequest 1 SnapshotHash bytes(32)
2 FileChunkNames repeated string 1…32, each ≤ 128 characters
FileDownloadResponse 1 FileChunks repeated bytes in the order of the names served
2 Failed repeated string names not served
HandshakeRequest 1 node_public_key bytes(32)
2 version string the node version (signed, not compared)
3 chain_height uint32
4 genesis_hash bytes(32)
5 listen_address string "host:port" the caller accepts connections on
6 timestamp int64 caller's clock, within ±600 s of the receiver's
7 signature bytes(64) §3
8 archival_api_url string not signed
HandshakeResponse 1 accepted bool
2 node_public_key bytes(32)
3 chain_height uint32
4 message string
5 genesis_hash bytes(32)
6 timestamp int64 within ±600 s of the dialler's clock
7 signature bytes(64) §3
8 archival_api_url string never filled
HeartbeatRequest 1 node_public_key bytes(32)
2 chain_height uint32
3 timestamp int64 within ±600 s of the receiver's clock (§4)
4 signature bytes(64) §4
HeartbeatResponse 1 alive bool
2 node_public_key bytes(32)
3 chain_height uint32
BlockCandidateMessage 1 block Block
2 creator_public_key bytes(32)
3 priority_position int32
4 received_at int64 ignored by the receiver
BroadcastBlockCandidateRequest 1 candidate BlockCandidateMessage
BroadcastBlockCandidateResponse 1 accepted bool
2 message string
GetBlockHashesRequest 1 start_height uint32
2 end_height uint32
3 chain_type int32 ignored (main chain)
BlockHashInfo 1 height uint32
2 block_hash bytes(32)
3 block_id int64
GetBlockHashesResponse 1 block_hashes repeated BlockHashInfo
2 complete bool
GetStateSampleRequest 1 height uint32 as-of height
2 account_addresses repeated bytes ≤ 32 typed accounts
3 node_ids repeated int64 ≤ 32
AccountSample 1 account_address bytes
2 balance int64
3 found bool
NodeSample 1 node_id int64
2 node_public_key bytes(32)
3 registration_status uint32
4 found bool
GetStateSampleResponse 1 available bool
2 error string
3 accounts repeated AccountSample in request order
4 nodes repeated NodeSample in request order
GetStoragePieceRequest 1 piece_id bytes(32)
2 requester_public_key bytes(32) empty = anonymous
3 timestamp int64 requester's clock
4 signature bytes(64) §14
GetStoragePieceResponse 1 found bool
2 data bytes the piece
PutStoragePieceRequest 1 piece_id bytes(32) SHA3-256 of data
2 data bytes 1 … 1,048,576 bytes
PutStoragePieceResponse 1 accepted bool

Rule activation. None.

Rejections and errors. A message that fails protobuf parsing is refused by the transport (INTERNAL) before any handler.

Vector. computed: SendTransactionRequest{TransactionBytes = 010203, ChainType 0, SenderPublicKey = EB89F581920CAC9343663A33911D76CEF5C89390F25865651D902792B881AD65, SenderSignature = AA×64} → 105 bytes 0A03010203 1A20EB89F581…AD65 2240AA…AA (ChainType 0 is omitted). GetNextBlockIdsRequest{ChainType 0, BlockId −1,691,361,305,265,671,434, Limit 50} → 13 bytes 10F6E5B1A6AAFBC4C3E8011832 (the negative id is a ten-byte varint).

Test cases · §2

68 cases · 64 valid · 4 invalid

A SendTransaction request (ChainType 0 is left out)27-2-send-transactionvalid

Loading the test widget…

A negative block id is a ten-byte varint27-2-negative-idvalid

Loading the test widget…

A served Block with 2,000 transaction ids decodes27-2-decode-2000valid

Loading the test widget…

A served Block with 2,001 transaction ids decodes to an empty block27-2-decode-2001-servedinvalid

Loading the test widget…

An answer carrying a Block with 2,001 transactions is refused27-2-decode-2001-answerinvalid

Loading the test widget…

An answer carrying a Block with 65,537 non-signing statements is refused27-2-decode-refusalsinvalid

Loading the test widget…

A served Block with 65,537 published receipts decodes to an empty block27-2-decode-receiptsinvalid

Loading the test widget…

An answer carrying a Block with 2,000 transaction ids decodes27-2-decode-answer-2000valid

Loading the test widget…

The fields of Empty27-2-schema-Emptyvalid

Loading the test widget…

The fields of GetPeerInfoRequest27-2-schema-GetPeerInfoRequestvalid

Loading the test widget…

The fields of Block27-2-schema-Blockvalid

Loading the test widget…

The fields of Transaction27-2-schema-Transactionvalid

Loading the test widget…

The fields of Receipt27-2-schema-Receiptvalid

Loading the test widget…

The fields of PublishedReceipt27-2-schema-PublishedReceiptvalid

Loading the test widget…

The fields of SpinePublicKey27-2-schema-SpinePublicKeyvalid

Loading the test widget…

The fields of SpineBlockManifest27-2-schema-SpineBlockManifestvalid

Loading the test widget…

The fields of Node27-2-schema-Nodevalid

Loading the test widget…

The fields of Peer27-2-schema-Peervalid

Loading the test widget…

The fields of SendBlockRequest27-2-schema-SendBlockRequestvalid

Loading the test widget…

The fields of SendBlockResponse27-2-schema-SendBlockResponsevalid

Loading the test widget…

The fields of SendTransactionRequest27-2-schema-SendTransactionRequestvalid

Loading the test widget…

The fields of SendTransactionResponse27-2-schema-SendTransactionResponsevalid

Loading the test widget…

The fields of SendBlockTransactionsRequest27-2-schema-SendBlockTransactionsRequestvalid

Loading the test widget…

The fields of SendBlockTransactionsResponse27-2-schema-SendBlockTransactionsResponsevalid

Loading the test widget…

The fields of RequestBlockTransactionsRequest27-2-schema-RequestBlockTransactionsRequestvalid

Loading the test widget…

The fields of GetCumulativeDifficultyRequest27-2-schema-GetCumulativeDifficultyRequestvalid

Loading the test widget…

The fields of GetCumulativeDifficultyResponse27-2-schema-GetCumulativeDifficultyResponsevalid

Loading the test widget…

The fields of GetCommonMilestoneBlockIdsRequest27-2-schema-GetCommonMilestoneBlockIdsRequestvalid

Loading the test widget…

The fields of GetCommonMilestoneBlockIdsResponse27-2-schema-GetCommonMilestoneBlockIdsResponsevalid

Loading the test widget…

The fields of GetNextBlockIdsRequest27-2-schema-GetNextBlockIdsRequestvalid

Loading the test widget…

The fields of BlockIdsResponse27-2-schema-BlockIdsResponsevalid

Loading the test widget…

The fields of GetNextBlocksRequest27-2-schema-GetNextBlocksRequestvalid

Loading the test widget…

The fields of BlocksData27-2-schema-BlocksDatavalid

Loading the test widget…

The fields of SpineBlockSignature27-2-schema-SpineBlockSignaturevalid

Loading the test widget…

The fields of SpineRefusal27-2-schema-SpineRefusalvalid

Loading the test widget…

The fields of SpineBlockSignatureRequest27-2-schema-SpineBlockSignatureRequestvalid

Loading the test widget…

The fields of SpineBlockSignatureResponse27-2-schema-SpineBlockSignatureResponsevalid

Loading the test widget…

The fields of SpineRefusalRequest27-2-schema-SpineRefusalRequestvalid

Loading the test widget…

The fields of SpineRefusalResponse27-2-schema-SpineRefusalResponsevalid

Loading the test widget…

The fields of GetPeerInfoResponse27-2-schema-GetPeerInfoResponsevalid

Loading the test widget…

The fields of GetMorePeersResponse27-2-schema-GetMorePeersResponsevalid

Loading the test widget…

The fields of SendPeersRequest27-2-schema-SendPeersRequestvalid

Loading the test widget…

The fields of NodeAddressInfo27-2-schema-NodeAddressInfovalid

Loading the test widget…

The fields of GetNodeAddressesInfoRequest27-2-schema-GetNodeAddressesInfoRequestvalid

Loading the test widget…

The fields of GetNodeAddressesInfoResponse27-2-schema-GetNodeAddressesInfoResponsevalid

Loading the test widget…

The fields of SendNodeAddressInfoRequest27-2-schema-SendNodeAddressInfoRequestvalid

Loading the test widget…

The fields of GetNodeProofOfOriginRequest27-2-schema-GetNodeProofOfOriginRequestvalid

Loading the test widget…

The fields of ProofOfOrigin27-2-schema-ProofOfOriginvalid

Loading the test widget…

The fields of FileDownloadRequest27-2-schema-FileDownloadRequestvalid

Loading the test widget…

The fields of FileDownloadResponse27-2-schema-FileDownloadResponsevalid

Loading the test widget…

The fields of HandshakeRequest27-2-schema-HandshakeRequestvalid

Loading the test widget…

The fields of HandshakeResponse27-2-schema-HandshakeResponsevalid

Loading the test widget…

The fields of HeartbeatRequest27-2-schema-HeartbeatRequestvalid

Loading the test widget…

The fields of HeartbeatResponse27-2-schema-HeartbeatResponsevalid

Loading the test widget…

The fields of BlockCandidateMessage27-2-schema-BlockCandidateMessagevalid

Loading the test widget…

The fields of BroadcastBlockCandidateRequest27-2-schema-BroadcastBlockCandidateRequestvalid

Loading the test widget…

The fields of BroadcastBlockCandidateResponse27-2-schema-BroadcastBlockCandidateResponsevalid

Loading the test widget…

The fields of GetBlockHashesRequest27-2-schema-GetBlockHashesRequestvalid

Loading the test widget…

The fields of BlockHashInfo27-2-schema-BlockHashInfovalid

Loading the test widget…

The fields of GetBlockHashesResponse27-2-schema-GetBlockHashesResponsevalid

Loading the test widget…

The fields of GetStateSampleRequest27-2-schema-GetStateSampleRequestvalid

Loading the test widget…

The fields of AccountSample27-2-schema-AccountSamplevalid

Loading the test widget…

The fields of NodeSample27-2-schema-NodeSamplevalid

Loading the test widget…

The fields of GetStateSampleResponse27-2-schema-GetStateSampleResponsevalid

Loading the test widget…

The fields of GetStoragePieceRequest27-2-schema-GetStoragePieceRequestvalid

Loading the test widget…

The fields of GetStoragePieceResponse27-2-schema-GetStoragePieceResponsevalid

Loading the test widget…

The fields of PutStoragePieceRequest27-2-schema-PutStoragePieceRequestvalid

Loading the test widget…

The fields of PutStoragePieceResponse27-2-schema-PutStoragePieceResponsevalid

Loading the test widget…

Defects to match. None.

§3 Handshake

Purpose. What an implementation must do to prove its key, its chain and a fresh clock to a peer, and to judge a peer's handshake.

Inputs. HandshakeRequest, carried by a signed call (§1a) that may name no receiver; the caller's observed host (from the gRPC peer string, §1a step 1); the receiver's clock and genesis hash; the peer table (28).

Output and effect. HandshakeResponse; a peer entry added or refreshed (28), the key marked handshake-verified (it may call this node from now on); a strike or ban for the caller's host (and, once its signature verified, for its host and key).

How to compute it.

Request signature = Ed25519 (02, no prefix, no hashing) over:

Offset Length Field
0 32 node_public_key
32 v version (UTF-8, no length prefix)
32+v 4 chain_height u32 LE
36+v 32 genesis_hash
68+v l listen_address (UTF-8, no length prefix)
68+v+l 8 timestamp i64 LE

The dialler fills: its key, its version, its tip height, its block-0 hash, its advertise address, its clock in seconds, its archival URL if configured.

The receiver, in order (after the signed-call checks of §1a, where a handshake alone may name no receiver):

  1. The caller's host is banned → accepted = false, "Too many failed introductions".
  2. Key 32 bytes, signature 64 bytes and valid over the preimage → else strike against the host, "Invalid signature - authentication failed". version is covered by the signature but not compared with anything. From here on a strike is recorded against the pair (host, key), so one key cannot lock out other nodes behind the same address; a banned pair → "Too many failed introductions".
  3. |timestamp − now| ≤ 600 → else strike, accepted = false, "handshake timestamp out of window: your clock is ±N s from ours (limit 600 s); check NTP" (N = theirs − ours, with its sign, clamped to ±10¹²).
  4. genesis_hash empty → strike, "Genesis hash required"; own genesis unavailable → "Local genesis unavailable" (no strike); different → strike, "Genesis hash mismatch - different chain configuration".
  5. Success clears the host's and the pair's strike records. A blacklisted key (28) → "Peer is blacklisted".
  6. Peer address = observed host + ":" + port (an IPv6 host in brackets), the port parsed from listen_address (digits after the last :, 1–65,535) or 8001; the host of listen_address is never used.
    • An inbound-only node: when listen_address is empty, starts with 0.0.0.0, ::, 127.0.0.1 or localhost, has no usable port, or no host was observed, the caller claims no address. A key not yet known gets an entry with no address, handshake-verified by this handshake and never chain-verified (no dial reached an address), counted against the observed host's cap of eight unregistered entries (28 §1; a cap or a full table refuses the handshake with the table's message, nothing stored). A key the table already holds from gossip (SendPeers, a GetMorePeers answer; never handshake-verified) is admitted the same way: it becomes handshake-verified, keeps its gossiped address unverified, and counts against the observed host as well; when that host already holds eight other unregistered entries (and neither the key nor its entry is registered) the handshake is refused "Too many unregistered peers from host H" and nothing changes. A key already handshake-verified only has its row refreshed. In every accepted case: last seen, height, failures reset, the registered flag set from the registry. An entry with no address is never dialled, never gossiped and never pushed to; the key may call this node (sync, pull blocks whole, send transactions).
    • A routable address: a key not yet known is added at the observed address and marked handshake-verified (a cap or a full table refuses the handshake with "Too many unregistered peers from host H" / "Peer table full", nothing stored). When an entry already exists for the key it is moved and admitted in one step: an entry whose address this node never reached (gossiped, or inbound-only) takes the observed address, unless an unregistered entry would move to another host that already holds eight unregistered entries; an entry this node did dial keeps its address, and when the handshake arrived from another host that address is queued for a dial (the key answering this node's own dial there moves the entry), or moves at once when the stored address has failed 3 or more consecutive dials, and is then no longer chain-verified until the dial requested below reaches the key at the new address (28 §1 rule 2). A key that never completed a handshake here whose move the cap refuses is refused "Too many unregistered peers from host H": nothing is stored or marked, and the key cannot call this node. Otherwise the key is (or stays) handshake-verified (it may call this node), a dial is requested of the recovery loop at once, the registered flag is set from the registry, failures are reset only when the handshake came from the stored host, and a channel to the stored address is opened. Nothing a handshake says about an address is trusted: the entry becomes chain-verified (dialled on its own, passed on in GetMorePeers, pushed to) only when this node's own dial reaches that address and the key answers there.
  7. Reply accepted = true, own key, cached tip height, "Handshake accepted", own genesis, own clock, signature = Ed25519 over node_public_key (32) ‖ chain_height u32 LE ‖ genesis_hash (32) ‖ timestamp i64 LE (76 bytes). archival_api_url is never filled.

Strikes (the introduction limiter): 5 failures within 300 s ban the host (or the pair) for 900 s; at most 4,096 records are tracked; a new record when the table is full first drops the records that are neither banned nor inside their window, then evicts the unbanned record with the oldest window start, or, when all are banned, the ban that expires soonest; the new strike is always recorded.

The dialler: the call is signed for the expected key when the dial is of a known key, and names no receiver when it dials an address (a seed, a pending address). On the response: transport failure → the address stays pending, or the known key's entry takes a failure; accepted = false → dropped from pending when the message contains "Genesis hash mismatch", else kept; key must be 32 bytes; the response signature must verify over the 76-byte preimage with the response's key; a dial of a known key answered by another key fails ("dial answered by another key"; the entry keeps its failures, nothing is verified); the response timestamp must be within ±600 s of its clock (else refused, "handshake timestamp out of window: the peer's clock is ±N s from ours (limit 600 s); check NTP on both"); a non-empty response genesis must equal its own; a response key equal to its own means it dialled itself; otherwise the address leaves the pending list, a new key is added at the dialled address (a cap or a full table fails the dial), and the entry takes the dialled address whatever it held (a gossiped address, no address, a moved host). The entry is marked chain-verified and handshake-verified only when it then holds exactly the dialled address: when the per-host cap refuses the move (an unregistered entry, the dialled host already holding eight unregistered entries) the dial fails as a table refusal, "Not moved to A: already 8 unregistered peers from host H; the entry keeps S and this dial verified nothing" (S = its stored address, or no address), the entry keeps its address and both flags as they were, nothing is connected, and neither the stored address nor the pending list takes a failure. On success the peer's clock offset is recorded, its archival URL stored if present, and a channel opened. A node whose own height cannot be read does not handshake.

Rule activation. None.

Rejections and errors. As listed, all status OK with accepted = false.

Vector. computed. INPUT: key A = EB89F581920CAC9343663A33911D76CEF5C89390F25865651D902792B881AD65, version "0.6.1", height 12,465, genesis hash G = E003E4E3…2871 (a stand-in 32-byte value), listen "203.0.113.7:8001", timestamp 1,794,211,200. EXPECTED OUTPUT: preimage (97 B) EB89F581…AD65 302E362E31 B1300000 <G> 3230332E302E3131332E373A38303031 807DF16A00000000; with a stand-in signature AA×64 the request is 168 bytes 0A20<A>1205302E362E3118B1612220<G>2A103230332E302E3131332E373A383030313080FBC5D7063A40<AA×64>, carried with the metadata of §1a (receiver absent on a dial by address). Response preimage for key B = F5692B269E6323FF07078505671DCAA4CF40A0753423D02C54EC9B110977CDD3, height 12,466, timestamp 1,794,211,201: (76 B) <B> B2300000 <G> 817DF16A00000000. A request with listen_address "0.0.0.0:8001" from 203.0.113.7 → accepted, an inbound-only entry for A (handshake-verified, not chain-verified) counted against host 203.0.113.7. The same request when the table already holds A from gossip at 198.51.100.9:8001 → accepted; the entry keeps 198.51.100.9:8001 (unverified), A may call, and the entry counts against both 198.51.100.9 and 203.0.113.7. INVALID: the same request received at 1,794,211,900 (+700 s) → accepted = false, "handshake timestamp out of window: your clock is -700 s from ours (limit 600 s); check NTP" and a strike; with the genesis's first byte changed → "Genesis hash mismatch - different chain configuration"; a ninth unregistered key from one host → "Too many unregistered peers from host 203.0.113.7", nothing stored. The gossiped A above handshaking from 203.0.113.7 (with listen_address "0.0.0.0:8001", or with "203.0.113.7:8001") when that host already holds eight other unregistered entries → accepted = false, "Too many unregistered peers from host 203.0.113.7", the entry unchanged and A's calls still refused "no handshake for this chain". This node's dial of 203.0.113.7:8001 answered by a known unregistered key K stored at 198.51.100.9:8001, with eight unregistered entries at 203.0.113.7 → the dial fails "Not moved to 203.0.113.7:8001: already 8 unregistered peers from host 203.0.113.7; the entry keeps 198.51.100.9:8001 and this dial verified nothing"; K's entry keeps its address and is not chain-verified.

Test cases · §3

18 cases · 8 valid · 10 invalid

The handshake request: its signed bytes and the message27-3-requestvalid

Loading the test widget…

The handshake response's signed bytes27-3-responsevalid

Loading the test widget…

A signed, fresh handshake on the same chain is accepted27-3-acceptedvalid

Loading the test widget…

A handshake received 700 s after it was stamped27-3-clockinvalid

Loading the test widget…

A handshake stamped 601 s ahead of the receiver27-3-clock-aheadinvalid

Loading the test widget…

A handshake 600 s old is still inside the window27-3-edgevalid

Loading the test widget…

A handshake from another chain (first genesis byte changed)27-3-genesisinvalid

Loading the test widget…

A handshake without a genesis hash27-3-no-genesisinvalid

Loading the test widget…

A handshake whose signature does not verify27-3-bad-signatureinvalid

Loading the test widget…

A handshake advertising 0.0.0.0:8001 from 203.0.113.7: an inbound-only entry27-3-inbound-onlyvalid

Loading the test widget…

The same handshake for A held from gossip at 198.51.100.9:800127-3-gossiped-natvalid

Loading the test widget…

A ninth unregistered key from one host27-3-ninth-keyinvalid

Loading the test widget…

The gossiped A from behind NAT when 203.0.113.7 holds eight others27-3-gossiped-cappedinvalid

Loading the test widget…

The gossiped A advertising 203.0.113.7:8001 when that host holds eight others27-3-gossiped-capped-routableinvalid

Loading the test widget…

A dial of 203.0.113.7:8001 answered by K stored at 198.51.100.9:8001, the host holding eight27-3-dial-cappedinvalid

Loading the test widget…

A dial of a known key answered by another key27-3-dial-other-keyinvalid

Loading the test widget…

Five failed introductions within 300 s ban the address for 900 s27-3-strikesvalid

Loading the test widget…

Failures more than 300 s apart start a new window27-3-strikes-windowvalid

Loading the test widget…

Defects to match. None.

§4 Heartbeat

Purpose. What an implementation must do to keep a peer's last-seen time and height fresh.

Inputs. HeartbeatRequest.

Output and effect. HeartbeatResponse; last seen and height refreshed for a known peer.

How to compute it. Sender: key, tip height, clock, signature = Ed25519 over node_public_key (32) ‖ chain_height u32 LE ‖ timestamp i64 LE (44 bytes); sent in cycles of 30 s to the priority peers (23), every third cycle to the other registered connected peers, never to unregistered peers. Receiver (after §1a, handshake required): key 32 bytes, signature 64 bytes and valid, else UNAUTHENTICATED "Invalid signature"; for a key that is not a Registered node, one answer per caller host per 60 s does any work (within the cooldown the reply is sent and nothing is touched); the request timestamp must be within ±600 s of the receiver's clock, else FAILED_PRECONDITION "heartbeat timestamp out of window"; a heartbeat for a key whose entry is stored at another host than the caller's is answered and updates nothing (the signed heartbeat names no receiver, so a forwarded copy must not keep a dead entry alive); otherwise last seen (a key already in the peer table), height and failures are refreshed; reply alive = true, own key, cached tip height. Cooldown entries older than 3,600 s are purged hourly.

Rule activation. None.

Rejections and errors. The signature failure and the timestamp window; an unknown or unregistered key still gets alive = true.

Vector. computed. INPUT: key A (§3), height 12,465, timestamp 1,794,211,200. EXPECTED OUTPUT: preimage (44 B) EB89F581920CAC9343663A33911D76CEF5C89390F25865651D902792B881AD65B1300000807DF16A00000000. INVALID: a request with 64 zero bytes as signature → UNAUTHENTICATED, "Invalid signature"; the same request received at 1,794,211,900 → FAILED_PRECONDITION "heartbeat timestamp out of window".

Test cases · §4

4 cases · 2 valid · 2 invalid

The heartbeat's signed bytes27-4-preimagevalid

Loading the test widget…

A heartbeat with 64 zero bytes as signature27-4-zero-signatureinvalid

Loading the test widget…

A signed heartbeat received in its window27-4-in-windowvalid

Loading the test widget…

A signed heartbeat received at 1,794,211,90027-4-out-of-windowinvalid

Loading the test widget…

Defects to match. None.

§5 Peer discovery

Purpose. What an implementation must do to learn and share peer addresses.

Inputs. GetPeerInfo, GetMorePeers, SendPeers; the seed list.

Output and effect. Peer lists; new entries in the peer table (28).

How to compute it.

  1. Seeds: the chain's seed file, one host:port per line, shipped with the release (30). A seed is dialled with the handshake of §3; its key is learned from the response.
  2. GetPeerInfo (a signed caller with a handshake, §1a): HostInfo.PublicKey = own key, Height = cached tip, ArchivalApiUrl if configured.
  3. GetMorePeers (a signed caller with a handshake): one answer per caller identity (§1a step 9) per 1,800 s, and at most eight distinct callers per host per 1,800 s; within the cooldown, or past the host's eight, an empty list (status OK). The list = every non-blacklisted, chain-verified peer (one this node's own dial reached) whose address is a public IP literal (step 5), each as Node{PublicKey, Address = "host:port", Height}; an inbound-only entry has no address and is never served. Cooldown entries older than 86,400 s are purged hourly.
  4. Discovery (client): every 60 s one random connected peer not asked in the last 1,800 s is asked (5 s deadline); for each returned node: skip its own key and keys already known, stop at 100 peers in the table, skip non-literal addresses, then add the address (dial and handshake follow, 28).
  5. Public-literal rule: strip the port ([v6]:port → inside the brackets; a single-colon host:port → before the colon); an IPv4 dotted quad, each octet ≤ 255, not in 0/8, 127/8, 10/8, 172.16/12, 192.168/16, 169.254/16, 100.64/10, 224/4 and above → public; a string with : made only of hex digits and colons, not ::1, not ::, not starting with fe80 → public IPv6; anything else (hostnames included) → not literal.
  6. SendPeers: the caller is the key that signed the call and must hold a handshake-verified entry (§1a; a call with no key is dropped silently); a global budget of 16 entries per 60 s for all callers; at most 100 entries read; each entry's address = Address + ":" + Port; port 0 or a non-literal → skipped; else the entry is added (unverified; the per-host cap of 28 §1 applies). No node sends SendPeers; a GetMorePeers list forwarded as is (its Address already holds host:port) composes to a non-literal and is skipped.

Rule activation. None.

Rejections and errors. FAILED_PRECONDITION "no handshake for this chain" (§1a); otherwise refusals are empty lists or silent drops.

Vector. computed (the public-literal rule of step 5): "203.0.113.7:8001" → public; "10.0.0.5:8001" → not; "[fe80::1]:8001" → not; "node.example:8001" → not literal. computed (the host of §1a): "2001:db8:1:2:3:4:5:6" → 2001:db8:1:2::/64; "::ffff:203.0.113.7" → 203.0.113.7.

Test cases · §5

3 cases · 3 valid

The public-literal rule27-5-public-literalvalid

Loading the test widget…

Private and reserved ranges are not public27-5-public-literal-rangesvalid

Loading the test widget…

The host a caller is keyed on27-5-host-groupvalid

Loading the test widget…

Defects to match. Where a caller is matched to a peer-table entry by its host (the receipt request's address binding of §8), the first chain-verified entry at that host wins, else the first entry; a caller matching no entry is assumed to listen on 8001.

§6 Node address announcements

Purpose. What an implementation must do with the signed (node id, address, port) bindings registered nodes announce.

Inputs. SendNodeAddressInfoRequest; GetNodeAddressesInfoRequest; the registry; the local blocks.

Output and effect. Rows of the local table node_address_info (node id, address, port, block height, block hash, signature, status 1 pending / 2 confirmed); a list in reply.

How to compute it.

  1. Sender (every 30 s, to every connected peer, only with a registry id): preimage = node_id u64 LE (8) ‖ len(address) u32 LE (4) ‖ address (UTF-8) ‖ port u32 LE (4) ‖ block_height u32 LE (4) ‖ block_hash (32) with the advertise address, its port (8001 if unparsable) and the tip; Signature = Ed25519 over it; Status 2.
  2. Receiver (after §1a, handshake required): under load (thread or CPU level High, §16) → RESOURCE_EXHAUSTED "Node under load"; more than 1,000 entries → INVALID_ARGUMENT. Per entry (silent skips): own id; empty address or port 0; id not a Registered node; an existing row (status 1 or 2) with the same address and port; an existing pending row with block_height ≥ the entry's; the block at BlockHeight not held or with another hash; the signature not valid under the registry key of NodeID. Then the row is inserted with status 1 whatever Status says. The duplicate test runs before the outdated test, so an unchanged address is never refreshed.
  3. GetNodeAddressesInfo: ≤ 1,000 ids (else INVALID_ARGUMENT); one row per node id among statuses 1 and 2, a confirmed row preferred; FAILED_PRECONDITION without a registry, INTERNAL on a read failure. No node moves a row to status 2, and no node sends GetNodeAddressesInfo.

Rule activation. None.

Rejections and errors. As listed.

Vector. computed. INPUT: node id 1,417,521,806,099,974,635 (key A's first 8 bytes LE, top bit cleared), address "203.0.113.7:8001", port 8001, height 12,000, hash 22×32. EXPECTED OUTPUT: preimage (68 B) EB89F581920CAC13 10000000 3230332E302E3131332E373A38303031 411F0000 E02E0000 22×32.

Test cases · §6

1 case · 1 valid

The signed bytes of a node address announcement27-6-preimagevalid

Loading the test widget…

Defects to match. None.

§7 Proof of origin

Purpose. What an implementation must answer when asked to sign a challenge with its node key.

Inputs. ChallengeMessage (bytes), Timestamp (int64).

Output and effect. ProofOfOrigin{MessageBytes, Timestamp, Signature}; no state.

How to compute it. After §1a (handshake required): MessageBytes = "ZBC-POO1" (8 ASCII bytes) ‖ ChallengeMessage ‖ Timestamp i64 LE; Signature = Ed25519 over MessageBytes; Timestamp echoed. INTERNAL if signing fails. The challenge has no length cap beyond the transport's. No node calls it.

Rule activation. None. Rejections and errors. INTERNAL only.

Vector. computed. INPUT: challenge "zoobc-spec-27", timestamp 1,794,211,200. EXPECTED OUTPUT: MessageBytes (29 B) = 5A42432D504F4F317A6F6F62632D737065632D3237807DF16A00000000.

Test cases · §7

1 case · 1 valid

The proof-of-origin message bytes27-7-messagevalid

Loading the test widget…

Defects to match. None.

§8 Receipt requests

Purpose. What an implementation must sign when it pushes a block or transactions to a peer, and check before it pays a receipt.

Inputs. The datum pushed; the recipient's node key; the chain's genesis hash; the sender's node key; the receiver's switch require_signed_receipt_requests (30).

Output and effect. The SenderSignature field of SendBlockRequest, SendTransactionRequest and SendBlockTransactionsRequest; on the receiver, whether a receipt may be paid and whether the sender's identity is bound to the connection (28).

How to compute it.

  1. digest = SHA3-256("ZBC-RCPT" (8 ASCII bytes) ‖ genesis_hash (32) ‖ datum_type (1 byte) ‖ datum_hash (32) ‖ recipient_node_public_key (32)) — a 105-byte preimage.
  2. Datum type 1 (block): datum_hash = the block hash the request carries (Block.BlockHash). Type 2 (transaction): SHA3-256 of TransactionBytes. Type 3 (batch): SHA3-256 of every TransactionsBytes entry concatenated in order.
  3. SenderSignature = the sender's node-key Ed25519 signature over digest, made per recipient (each peer gets its own). A sender that does not know the recipient's key sends no signature.
  4. The receiver: no claimed SenderPublicKey → no receipt. A non-empty signature that verifies for the claimed key, this recipient's key and this chain → receipt allowed and the sender bound. A non-empty signature that does not verify → no receipt (nothing charged: the claimed key may be a victim's). An empty signature → no receipt when require_signed_receipt_requests is on; a receipt allowed when it is off. The claimed key is also bound (for charging, 28 §6) when it is the key that signed the call (§1a).
  5. A receipt is then paid only when both the sender and this node are registered (23). The signature proves that the key asked for the credit, not that its own machine served the datum.

Rule activation. None (a node switch, 30 §2). require_signed_receipt_requests is false when the configuration has no such line; the installer writes true on every chain (a preserved configuration without the line gains it, one that sets it keeps the operator's value) and the relaunch sets it to true on every node (30 §9a), so both chains refuse unsigned receipt requests from block 0. Every node of 0.6.1 sends the signature; an implementation must always send it.

Rejections and errors. None visible to the sender: a refused request simply returns no receipt.

Vector. computed, genesis = the vectors' identity G (02 §1), recipient B (§3). INPUT block hash F672CCA4DA1387E8C3416BE94009B4CDEB1E03872EB930F9AB81DBFC669C538A → preimage 5A42432D52435054 E003E4E3…2871 01 F672CCA4…538A F5692B26…CDD3; digest 32292419342661667964E21D80FA61711C6FEB6331BF5708D58DC3032C551E84. INPUT transaction bytes 010203 → datum FD1780A6FC9EE0DAB26CEB4B3941AB03E66CCD970D1DB91612C66DF4515B0A0A, digest 1171BC4AA8A3617076C4C489E366A7BBA922217EE7658258C9A08ACB4ACFB83F. INPUT batch [010203, 0405] → datum B8AB469AEEAE0CC5A78AECAB95FE9A4A3020DAD8CD968D916E2E0F231F1C3FEB, digest 95ECA129180816C882AD3D88D81474C4E477152AC73934608FA2D26702D722DA. INVALID: the block signature of the first example shown to a node whose key is not B does not verify → no receipt.

Test cases · §8

7 cases · 7 valid

The receipt request for a pushed block27-8-blockvalid

Loading the test widget…

The datum of a pushed transaction27-8-tx-datumvalid

Loading the test widget…

The receipt request for a pushed transaction27-8-txvalid

Loading the test widget…

The datum of a pushed batch27-8-batch-datumvalid

Loading the test widget…

The receipt request for a pushed batch27-8-batchvalid

Loading the test widget…

A request signed for B does not verify at another node27-8-other-recipientvalid

Loading the test widget…

The same request verifies at B27-8-own-recipientvalid

Loading the test widget…

Defects to match. None.

§9 Block delivery

Purpose. What an implementation must do to push a new block and to accept, complete, validate, apply, relay and receipt a pushed block.

Inputs. SendBlockRequest; the caller's observed host; the registry; the pool.

Output and effect. SendBlockResponse (a receipt or nothing); the block applied (21) or dropped; relays; the invalid-block record (28).

How to compute it.

Senders (every request carries ChainType, SenderPublicKey and a per-recipient SenderSignature, §8):

  • The blocksmith: the header fields (ID, Height, Timestamp, BlockHash, PreviousBlockHash, BlocksmithPublicKey, BlockSignature, MerkleRoot, TotalFee, TotalCoinBase, TotalAmount, BlockSeed, Version, CumulativeDifficulty, PayloadHash, PayloadLength, BlockSeedProof; for a spine block also ReferenceBlockHeight, MerkleTree, SpinePublicKeys, SpineBlockManifests, ReferenceCommitment), the TransactionIDs (never the transactions) and the PublishedReceipts; to the connected priority peers first, then other connected peers up to 20 in total, skipping peers known to hold the hash; in parallel, 5 s deadline.
  • The relay: the full record with Transactions replaced by TransactionIDs, to the priority peers of that height (fallbacks: connected peers active in the registry, then connected registered peers; for a spine block all connected peers), skipping the origin and peers that know the hash; only from a registered node (main chain).

Receiver, in order (after the signed-call checks of §1a, handshake required):

  1. More Transactions or TransactionIDs than the chain's maximum per block (max(500, max_transactions_per_block), 2,000 on both chains) → INVALID_ARGUMENT "Too many transactions in block" / "Too many transaction IDs in block"; PayloadLength above the maximum block size (max_block_size_bytes, 524,288 on both chains) → INVALID_ARGUMENT "Block payload exceeds max size". Each of these records an invalid block against a sender that is not bound and registered.
  2. The receipt request is judged (§8); the sender's charge identity is fixed (28 §6: the claimed key when it is registered and bound — bound by the receipt signature or by being the key that signed the call — else addr: + the caller's host).
  3. An unbound or unregistered sender whose charge identity recorded 5 invalid blocks in the last 60 s → RESOURCE_EXHAUSTED "Invalid block rate limit exceeded for unbound sender".
  4. Decode (§2 caps). Main chain, a copy that carries its transactions, rule block_size_serialized active at the block's height: a block whose serialised size (19) exceeds the maximum, or cannot be sized, → INVALID_ARGUMENT "relay: block over the serialized limit", an invalid block recorded against an unbound sender.
  5. A bound sender is marked as knowing the hash (an unbound claim marks nothing). A block hash this node has applied or held → OK, nothing more. A copy whose wire bytes (SHA3-256 of the serialised Block) were already received → OK, nothing more. (The two marks share one bounded cache of 4,096 entries; the signed hash is marked only after the block was applied or found held.)
  6. One copy per claimed block hash is processed at a time. While a copy is in flight: a second copy from a sender that is not bound and registered is dropped (OK); a copy from a bound, registered sender waits as the one waiter for that hash (a third such copy is dropped), at most 10 s, then is processed anyway; a block applied meanwhile → OK.
  7. ChainType == 1 (spine; any other value counts as the main chain, so a block sent with ChainType 7 skips the size check of step 4, is applied as main and is not relayed): no spine → OK; a block held at that height → OK (same hash: marked applied); else stored (25 §7); stored → relayed to all connected peers unless the sender is the blocksmith; any store error → OK (logged, nothing charged).
  8. Main chain, Transactions empty and TransactionIDs present. With the parent held, the header, the signature and the recomputed cumulative difficulty must hold (else dropped, an invalid block recorded against an unbound sender); with the parent not held, a sender that is not bound and registered is dropped before any lookup, and so is any copy while the incomplete-block queue is full. Then each id is resolved from the pool; a missing id found among applied transactions below this height → the block is dropped (double spend); found at or above this height → reused. All resolved → step 9. Otherwise the block is queued (at most 100 blocks, each for 120 s; a full queue drops it) and the missing ids are requested (RequestBlockTransactions with RequesterPublicKey = own key, §10) from up to 3 targets: the blocksmith's known address, then connected registered peers, else the sender when registered. While queued, a registered sender whose receipt request was accepted and whose block passes the header check, the signature check and the hash check (the claimed block hash recomputes from the header, 19) is paid a receipt (datum type 1, the claimed block hash) at once.
  9. Processing (also run when a queued block completes, then with no reply): the equivocation note (below); a block held at this height with the same hash → marked applied, receipt to a registered, accepted sender; another hash → dropped (sync resolves); height above tip + 1, a wrong parent hash or a missing parent → dropped; a block whose round has not opened (20): kept for later only when its blocksmith is registered, it validates in full and its round opens within 900 s, at most 64 such blocks, one per (height, hash); else dropped; validation (19) failure → dropped, an invalid block and a validation failure recorded against the charge identity (28); the cumulative difficulty is recomputed (24); the block is applied (21); success → marked applied, receipt (datum 1) to a registered, accepted sender when this node is registered, relay (main chain, this node registered), pool update.

The equivocation note. A header is noted in an in-memory ledger keyed by (previous_block_hash, blocksmith_public_key) only when its height lies in [tip − 720, tip + 2], its signature verifies (05) and its blocksmith is a Registered node; at most 256 (parent, blocksmith) pairs per height are kept. The same pair seen with a different block hash is an equivocation: the blocksmith's key is recorded as a proven liar (blacklisted and disconnected, 28) and, once per pair from this node (a set of at most 4,096 pairs, cleared when full), a fee-free EquivocationReport carrying both signed headers is added to the pool (35); the block itself is not dropped (fork choice, 24, decides). When the two headers straddle the recovery limit from their shared parent (rule equivocation_resume_exempt) there is no ban and no report.

Rule activation. block_size_serialized (step 4), equivocation_miss, equivocation_resume_exempt; active from height 0 on every chain.

Rejections and errors. The status codes of steps 1, 3 and 4 and those of §1a; everything else is OK with or without a receipt.

Vector. computed. INPUT: a SendBlockRequest with 2,001 TransactionIDs → INVALID_ARGUMENT "Too many transaction IDs in block". INPUT: the same block received twice with byte-identical Block messages → the second is answered OK with nothing done. INPUT: a sender with 5 invalid blocks charged to addr:203.0.113.7 in the last 60 s sends again from 203.0.113.7 → RESOURCE_EXHAUSTED "Invalid block rate limit exceeded for unbound sender". INPUT: an ids-only block whose parent this node does not hold, from a sender that is not bound and registered → dropped (OK) before any pool lookup.

Test cases · §9

5 cases · 3 valid · 2 invalid · 2 reference

A SendBlock carrying 2,001 transaction ids27-9-too-many-idsinvalid

Loading the test widget…

A SendBlock carrying 2,001 transactions27-9-too-many-transactionsinvalid

Loading the test widget…

Five invalid blocks charged to the sender's host in the last 60 s: its next unbound block is throttled27-9-throttlevalid

Loading the test widget…

A block received twice in byte-identical messages27-9-duplicatevalidreference

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

second_copy
answered OK with nothing done
An ids-only block whose parent this node does not hold, from a sender that is not bound and registered27-9-no-parentvalidreference

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

result
dropped (OK) before any pool lookup

Defects to match. None.

§10 Transaction delivery

Purpose. What an implementation must do to push transactions, accept them, receipt them, relay them and serve the transactions a block needs.

Inputs. SendTransactionRequest, SendBlockTransactionsRequest, RequestBlockTransactionsRequest; the caller's observed host.

Output and effect. Receipts; staged or pooled transactions (04); relays; a SendBlockTransactions call back to an asker.

How to compute it.

SendTransaction — receiver, in order (after §1a, handshake required):

  1. The node's emergency mode → RESOURCE_EXHAUSTED "Node in emergency mode"; then the load gates (§16), all RESOURCE_EXHAUSTED: thread level ≥ High → "Thread limit reached"; file descriptors ≥ Medium → "File descriptor limit reached"; CPU ≥ High → "CPU limit reached"; P2P requests ≥ High → "P2P request limit reached"; TransactionBytes longer than the maximum block size → INVALID_ARGUMENT "Transaction larger than the maximum block size".
  2. The receipt request is judged (§8); the sender's charge identity is fixed (28 §6). The claimed key's tier (registered, queued) counts only when the key is bound (the receipt signature verified, or the key signed the call); otherwise the sender is a stray.
  3. Per-source rate (28): the caller's host (the claimed key in hex when no host is readable) is charged one transaction under the tier (registered 2,000 / min, queued 20 / min, other 10 / min) → over it RESOURCE_EXHAUSTED "Per-source transaction rate limit". A sender neither registered nor queued with CPU, P2P or threads ≥ Medium → "Resource limit reached for unregistered sender"; the staging pool holding 500,000 → "Staging pool full".
  4. A bound sender is marked as knowing the bytes; unparsable bytes → INVALID_ARGUMENT "Failed to deserialize transaction: …". Staging (04) applies the pool's cheap checks before the signature check. Two refusals are backpressure — "A duty transaction for this window is already pending from this node" and "Too many pending transactions from this sender (max 50)" — and are answered RESOURCE_EXHAUSTED with that text, nothing recorded (an honest relay forwards them). Any other validation error is answered INVALID_ARGUMENT with its text, not relayed, no receipt, and an invalid transaction is recorded against the charge identity (28 §6: the key when bound and registered, else addr: + the host). A refusal of this node's capacity (memory pressure, "System memory pressure - try again later") is answered RESOURCE_EXHAUSTED with its text. A copy already staged is a duplicate and accepted.
  5. Accepted: receipt (datum type 2, the transaction hash) to a registered, accepted sender; if the hash is new to the relay cache (4,096), the received bytes are queued for relay (queue 2,048) to every connected peer except the origin and peers that know the bytes, each with its own SenderSignature.

A node's own duties (snapshot attestations, storage-proof batches, queue attendance, liveness attestations, roll-call answers) are relayed as soon as its pool takes them, and the newest 64 are sent again every 120 s while still pending.

SendBlockTransactions (after §1a, handshake required) — the receipt request covers the whole batch (datum type 3); more than 500 entries → INVALID_ARGUMENT "Too many transactions in request"; bytes together above 2,097,152 → RESOURCE_EXHAUSTED "Transaction batch too large"; the per-source rate (by host) is charged once per entry carried (at least 1); a sender neither registered nor queued with P2P level ≥ Medium → RESOURCE_EXHAUSTED "P2P request limit reached for unregistered sender"; each entry staged as above (unparsable entries skipped); one receipt per accepted entry for a registered, accepted sender, in order; completed queued blocks are processed afterwards.

RequestBlockTransactions (after §1a, handshake required) — the reply goes to the peer-table entry of the key that signed the call; a caller with no entry, or whose key is not handshake-verified (it never completed a same-chain handshake with this node) → PERMISSION_DENIED "block transactions require a handshake-verified peer"; the block-read budget (§11) is charged (RESOURCE_EXHAUSTED "block read budget: 200 calls per 10 s per caller"); more than 500 ids → INVALID_ARGUMENT "Too many transaction IDs requested"; a caller whose key is not registered → OK, nothing; each id is looked up in the pool, then among applied transactions; the found ones are serialised (03, with signature) until the next would pass 2,097,152 bytes together; the reply's bytes are charged to the byte budget (8 MiB per 10 s per caller identity, 64 MiB per host; over it RESOURCE_EXHAUSTED "block transaction byte budget: 8 MiB per 10 s per caller"); the reply is Empty and the transactions travel in a separate signed SendBlockTransactions to the caller's stored address (its known connection, else a new plaintext channel to that address), 15 s deadline, its receipt request signed (§8, datum type 3) for RequesterPublicKey when it is 32 bytes, else for the caller's key. Nothing is pushed to an address this node's own dial has not reached: an inbound-only caller (an entry with no address, §3) and a caller whose stored address is not chain-verified (a gossiped or forwarded one) are sent nothing (logged), and a node behind NAT completes pushed blocks by pulling them whole through sync (GetNextBlocks).

Rule activation. None.

Rejections and errors. As listed.

Vector. computed. INPUT: SendBlockTransactions with 501 entries → INVALID_ARGUMENT "Too many transactions in request". INPUT: an 11th transaction within one minute from a host whose claimed key is neither registered nor queued (10 / min) → RESOURCE_EXHAUSTED "Per-source transaction rate limit"; for a bound queued key (20 / min) the 21st is refused the same way. INPUT: RequestBlockTransactions with RequesterPublicKey = B and ids of two pooled transactions whose bytes are 010203 and 0405 → the reply's SenderSignature is over the batch digest 95ECA129…22DA of §8. INPUT: a SendTransaction whose sender already has 50 pooled transactions → RESOURCE_EXHAUSTED "Too many pending transactions from this sender (max 50)", nothing recorded.

Test cases · §10

8 cases · 4 valid · 4 invalid

A SendBlockTransactions with 501 entries27-10-batch-501invalid

Loading the test widget…

A RequestBlockTransactions naming 501 ids27-10-request-501invalid

Loading the test widget…

A sender neither registered nor queued: the 11th transaction in a minute is refused27-10-stray-ratevalid

Loading the test widget…

A queued sender: the 21st transaction in a minute is refused27-10-queued-ratevalid

Loading the test widget…

A SendTransaction whose sender already has 50 pending transactions27-10-pending-50invalid

Loading the test widget…

A sender with 49 pending transactions is staged27-10-pending-49valid

Loading the test widget…

A duty of this node for this window already pending27-10-duty-pendinginvalid

Loading the test widget…

The reply to RequestBlockTransactions is signed over the batch digest27-10-reply-signaturevalid

Loading the test widget…

Defects to match. None.

§11 Chain sync queries and the block-read budget

Purpose. What an implementation must answer to the read-only RPCs of 24's sync and fork resolution.

Inputs. As in §2.

Output and effect. The answers below; the block-read budget.

How to compute it. ChainType 0 = main, 1 = spine (FAILED_PRECONDITION "Spine blockchain not configured" without a spine), any other value → INVALID_ARGUMENT "Invalid chain type" (the first four RPCs below).

Block-read budget: RequestBlockTransactions, GetNextBlockIDs and GetNextBlocks share one budget of 200 calls per 10 s per caller identity (§1a step 9: a registered key, or key@host) and a ceiling of 8 × 200 calls per 10 s per host (sliding windows; at most 4,096 identities and 4,096 hosts tracked, a new one evicting the one with the oldest last call; a caller with no readable host is not limited by the host ceiling); over either → RESOURCE_EXHAUSTED "block read budget: 200 calls per 10 s per caller", before any work. Every RPC of this section requires a signed call from a key with a handshake (§1a).

  1. GetCumulativeDifficulty{ChainType} → the tip's CumulativeDifficulty and Height; INTERNAL "Failed to get latest block" without a tip.
  2. GetCommonMilestoneBlockIDs{ChainType, LastBlockID, LastMilestoneBlockID}: both 0 → INVALID_ARGUMENT "either LastBlockID or LastMilestoneBlockID has to be supplied"; LastBlockID ≠ 0 and held → BlockIds = [LastBlockID], Last = it is the tip; else LastMilestoneBlockID ≠ 0 → it must be held (INTERNAL "failedGetLastMilestoneBlock"), start = its height, jump = min(720, max(tip height, 1)); else start = tip height, jump = 10; then up to 10 ids walking down by jump (clamped at 0, stopping after height 0); a missing block on the walk → INTERNAL "failedGetBlocks"; Last false on this path.
  3. GetNextBlockIDs{ChainType, BlockId, Limit} (budgeted): Limit clamped to 100; BlockId must be held (NOT_FOUND "Block not found"); the ids of heights start+1 … tip in order, at most Limit, missing heights skipped.
  4. GetNextBlocks{ChainType, BlockId, BlockIds} (budgeted; BlockId is not read): more than 50 ids → INVALID_ARGUMENT "Too many block IDs requested"; each held id returned as a full Block (transactions included), missing ids omitted, in request order.
  5. GetBlockHashes{start_height, end_height} (main chain; chain_type is not read): end < start or start > tip → empty, complete = false; end clamped to the tip and to start + 999; one BlockHashInfo per held height; complete = no height of the clamped range was missing.

Rule activation. None.

Rejections and errors. As listed.

Vector. computed. INPUT: GetCumulativeDifficulty{ChainType 7} → INVALID_ARGUMENT "Invalid chain type". INPUT: GetBlockHashes{start 10, end 5} → no rows, complete = false. INPUT: GetBlockHashes{start 12000, end 4000000000} on a node whose tip is 12,465 → 466 rows 12,000…12,465, complete = true. INPUT: the 201st GetNextBlockIDs from one registered key within 10 s → RESOURCE_EXHAUSTED "block read budget: 200 calls per 10 s per caller"; the 1,601st call from one host, spread over nine keys → the same refusal.

Test cases · §11

11 cases · 5 valid · 6 invalid

GetCumulativeDifficulty with ChainType 727-11-chain-typeinvalid

Loading the test widget…

GetCumulativeDifficulty for the spine on a node without one27-11-no-spineinvalid

Loading the test widget…

GetCommonMilestoneBlockIDs with neither id27-11-milestone-emptyinvalid

Loading the test widget…

GetNextBlocks naming 51 ids27-11-next-blocks-51invalid

Loading the test widget…

GetBlockHashes with end below start27-11-hashes-reversedvalid

Loading the test widget…

GetBlockHashes clamped to the tip27-11-hashes-clampedvalid

Loading the test widget…

GetBlockHashes clamped to 1,000 rows27-11-hashes-capvalid

Loading the test widget…

200 GetNextBlockIDs calls from one registered key within 10 s are answered27-11-budget-200valid

Loading the test widget…

The 201st call from one registered key within 10 s27-11-budget-201invalid

Loading the test widget…

1,600 calls from one host spread over eight keys are answered27-11-budget-host-1600valid

Loading the test widget…

The 1,601st call from one host, spread over nine keys27-11-budget-host-1601invalid

Loading the test widget…

Defects to match. None.

§12 Spine signature and non-signing statement RPCs

Purpose. What an implementation must answer when a spine blocksmith asks it for its spine signature on a spine block candidate, or for a non-signing statement on one.

Inputs. SpineBlockSignatureRequest{block, refusals} (the candidate and the non-signing statements that free the asked node from an earlier signing commitment); SpineRefusalRequest{proposal} (a request for a non-signing statement, SpineRefusal, on the candidate in proposal).

Output and effect. SpineBlockSignatureResponse; SpineRefusalResponse; the spine signer's signing-commitment state (25 §6a).

How to compute it. Both RPCs always answer status OK. RequestSpineBlockSignature: the judgement of 25 §6a, in its order; accepted = true with signature = {own key, Ed25519 over the 204 header bytes, own registry id or 0, own clock}; otherwise accepted = false with error, and, when refused because of a signing commitment under cosign_promise_binds, promised_block_hash (the candidate it committed to), promised_bar (that candidate's required spine signatures) and promised_block. RequestSpineRefusal: the checks of 25 §6b; given = true with refusal = {height, identity, own key, Ed25519 over the digest of the non-signing statement}; otherwise given = false with error. The asker verifies a returned non-signing statement before counting it ("the refusal does not verify").

Rule activation. cosign_promise_binds, spine_late_vote, spine_bar_follows_registry (25; active from height 0 on every chain). Both RPCs require a signed call from a key with a handshake (§1a).

Rejections and errors. In error, as listed in 25 §6a and §6b.

Vector. computed: the non-signing statement on 25 §6b's worked spine block candidate by key A encodes as the SpineRefusal message (136 B) 0803 1220DE9130054E031E11DF492BDD5A9BE36A87720B8414A5E3E69EA9EE394A8D9EB6 1A20<A> 2240<signature>. INVALID: a SpineRefusalRequest without proposal → given = false, "no proposal to refuse (the request must carry it)".

Test cases · §12

2 cases · 1 valid · 1 invalid

The SpineRefusal message (a non-signing statement) on the worked candidate by key A27-12-refusal-messagevalid

Loading the test widget…

A SpineRefusalRequest without a spine block candidate27-12-no-candidateinvalid

Loading the test widget…

Defects to match. Those of 25 §6a–§6b.

§13 Snapshot chunk download

Purpose. What an implementation must answer to a chunk request (26 §4).

Inputs. FileDownloadRequest{SnapshotHash, FileChunkNames}.

Output and effect. FileDownloadResponse{FileChunks, Failed}.

How to compute it. After §1a (handshake required): no names → INVALID_ARGUMENT "request does not contain any file name"; more than 32 → INVALID_ARGUMENT "Too many file chunks requested"; empty hash → INVALID_ARGUMENT "empty snapshot hash". Directory = the snapshot directory + base64url(SnapshotHash) with = padding. Per name: empty, longer than 128 characters, containing .., / or \, unreadable, or larger than 102,400 bytes → Failed; else its bytes to FileChunks.

Rule activation. None. Rejections and errors. As listed.

Vector. computed: hash B295B329…DC30 (26 §3) and names [FPYeC1Mq…MeY=, nope] on a node holding that snapshot → FileChunks = [the 102,400 bytes of chunk 0], Failed = ["nope"]; empty hash → INVALID_ARGUMENT "empty snapshot hash".

Test cases · §13

4 cases · 1 valid · 3 invalid · 1 reference

A chunk request with an empty snapshot hash27-13-empty-hashinvalid

Loading the test widget…

A chunk request naming no file27-13-no-namesinvalid

Loading the test widget…

A chunk request naming 33 files27-13-33-namesinvalid

Loading the test widget…

Chunks served and failed27-13-servedvalidreference

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

request
hash B295B329...DC30, names [FPYeC1Mq...MeY=, nope]
FileChunks
[the 102,400 bytes of chunk 0]
Failed
["nope"]

Defects to match. None.

§14 Block candidates and storage pieces

Purpose. What an implementation must answer to the remaining extended-service RPCs.

Inputs. As in §2; every call signed and from a key with a handshake (§1a).

Output and effect. As below.

How to compute it.

  1. BroadcastBlockCandidate: the block is decoded (§2), creator key and position copied, received_at set to the receiver's own clock, and offered to the candidate pool (24); the block is first noted by the equivocation ledger (§9); reply accepted = the pool's decision, "Candidate added to pool" / "Candidate rejected"; no pool → accepted = false, "Block candidate pool not initialized".
  2. GetStoragePiece{piece_id, requester_public_key, timestamp, signature}: piece_id must be 32 bytes and storage on, else found = false. A chunk only the archive keeps (26 §10b) requires a registered requester: requester_public_key 32 bytes, signature 64 bytes = Ed25519 over "ZBC-PIECE-REQ" (13 ASCII bytes) ‖ genesis hash (32) ‖ piece_id (32) ‖ timestamp i64 LE ‖ requester_public_key (32), |now − timestamp| ≤ 300, the key registered; else PERMISSION_DENIED "old snapshot chunks of the archive are served to registered nodes only (<reason>)". Every other piece is served to anyone. Then found = true, data.
  3. PutStoragePiece{piece_id, data}: accepted = false unless storage is on, piece_id is 32 bytes, 0 < len(data) ≤ 1,048,576, the tip exists, this node is an assigned holder of the piece in the current or previous storage epoch (11), and SHA3-256(data) = piece_id; then stored, accepted = true.

Rule activation. None.

Rejections and errors. As flags, except PERMISSION_DENIED and those of §1a.

Vector. computed. INPUT: piece id = SHA3-256("piece") = 88C2C5C10BB1B738D33C84800F03628AAF99E8A6CEFDB13BA4863753D3AE845D, timestamp 1,794,211,200, requester A, genesis = the vectors' identity G (02 §1). EXPECTED OUTPUT: the piece-request preimage (117 B) 5A42432D50494543452D524551 E003E4E3…2871 88C2C5C1…845D 807DF16A00000000 EB89F581…AD65. INVALID: the same request at a holder whose clock reads 1,794,211,501 → PERMISSION_DENIED.

Test cases · §14

5 cases · 3 valid · 2 invalid

The piece id of the example27-14-piece-idvalid

Loading the test widget…

The signed bytes of a piece request27-14-piece-requestvalid

Loading the test widget…

A piece request checked 301 s after it was signed27-14-piece-lateinvalid

Loading the test widget…

A piece request signed by its requester, checked in time27-14-piece-provenvalid

Loading the test widget…

A piece request naming a key that did not sign it27-14-piece-wrong-keyinvalid

Loading the test widget…

Defects to match. None.

§15 GetStateSample

Purpose. What an implementation must answer to a joiner's as-of state query (26 §10a).

Inputs. GetStateSampleRequest{height, account_addresses, node_ids}; the caller's identity and host (§1a).

Output and effect. GetStateSampleResponse; no state change. The answer is unsigned; a joiner relies on the cross-peer majority of 26 §10a.

How to compute it. All answers are status OK (after §1a, handshake required). In order: one call per caller identity per 10 s and at most eight callers per host per 10 s (available = false, "rate limited"; the identity table is cleared past 4,096 entries); no main chain → "no main chain"; height above the cached tip → "height above my tip"; more than 32 addresses or 32 ids → "sample too large"; no database → "no database". Otherwise, per address the balance of the newest account_balance row with block_height ≤ height (found = false when none), per id the node_public_key and registration_status of the newest node_registry row with height ≤ height (found = false when none); available = true.

Rule activation. None.

Rejections and errors. All as available = false with error.

Vector. computed. INPUT: {height 12466} at a node whose tip is 12,465 → available = false, "height above my tip". INPUT: 33 addresses → "sample too large". INPUT: a second call from the same key 3 s after the first → "rate limited"; a ninth key from one host within 10 s → "rate limited".

Test cases · §15

5 cases · 1 valid · 4 invalid

A state sample above the tip27-15-above-tipinvalid

Loading the test widget…

A state sample of 33 addresses27-15-too-largeinvalid

Loading the test widget…

A second call from the same key 3 s after the first27-15-rateinvalid

Loading the test widget…

A ninth key from one host within 10 s27-15-ninth-keyinvalid

Loading the test widget…

An eighth key from one host within 10 s is answered27-15-eighth-keyvalid

Loading the test widget…

Defects to match. None.

§16 Load levels

Purpose. What the "levels" of §6, §9 and §10 are.

Inputs. Samples of the node's own resources.

Output and effect. A level per resource: None, Low, Medium, High, Critical.

How to compute it. Every 4 s the node samples CPU %, thread count, open file descriptors (against the OS limit), its own memory (the process's resident set against its limit: the smallest of the machine's total memory and every memory limit of the control groups the process belongs to, read up the hierarchy; no limit = no memory level) and the number of P2P requests in flight (handlers of Handshake, Heartbeat, SendBlock, SendTransaction, SendBlockTransactions, GetCumulativeDifficulty, GetPeerInfo, GetStateSample count while they run); it keeps the last 50 samples. A level averages the last 4 samples against the hard limit (1,000 in-flight P2P requests, 700 threads, 98 % CPU, 95 % of the memory limit, the descriptor limit): below 30 % None, from 30 % Low, from 60 % Medium, from 80 % High, from 100 % Critical. The memory level ≥ High (76 % of the limit) makes the staging pool refuse every transaction ("System memory pressure - try again later", §10). "Emergency mode" is the node's own health monitor refusing work (local).

Rule activation. None. Rejections and errors. None.

Vector. computed: samples of 850, 900, 700, 800 in-flight requests average 812 (a count average is a whole number, rounded down) → 81 % → High → SendTransaction answers RESOURCE_EXHAUSTED "P2P request limit reached". A node limited to 4 GiB by its control group whose resident set averages 3.2 GiB → 80 % of 4 GiB = 84 % of the 95 % limit → High → SendTransaction answers RESOURCE_EXHAUSTED "System memory pressure - try again later".

Test cases · §16

5 cases · 3 valid · 2 invalid

The P2P level of four samples27-16-p2p-levelvalid

Loading the test widget…

SendTransaction at the High P2P level27-16-p2p-gateinvalid

Loading the test widget…

A resident set averaging 3.2 GiB under a 4 GiB limit is High27-16-memoryvalid

Loading the test widget…

SendTransaction at the High memory level27-16-memory-gateinvalid

Loading the test widget…

A Medium level does not refuse a transaction27-16-mediumvalid

Loading the test widget…

Defects to match. None.

§17 Data kept, consensus and local

Data kept by the P2P layer (all local, none consensus): the peer table (28); node_address_info (§6: node id, address, port, block height, block hash, signature, status; one or two rows per node id); in memory: the replay ring of served call signatures (§1a, 120,000 entries, 600 s), the introduction strikes (§3, 4,096 hosts and host-key pairs), the heartbeat cooldown (by host), the GetMorePeers and GetStateSample cooldowns (by caller identity, with a per-host window of eight), the block-read and byte budgets (§11, §10: 4,096 identities and 4,096 hosts each), the seen-block cache (4,096 keys: block hashes applied or held, and wire-byte hashes received), the transaction relay cache (4,096), the incomplete-block queue (100 blocks, 120 s), the held early blocks (64, 900 s), the equivocation ledger (§9), the invalid-block and validation-failure records (28), the spine signing-commitment state (25 §10).

Consensus: nothing here is hashed into a block. What an implementation must match exactly to interoperate: the messages (§2), the signed preimages (§1a the call, §3 request and response, §4, §6, §7, §8, §14 piece request, 25 §6b non-signing statement), the canonical transaction bytes inside TransactionBytes (03), the block record inside Block (05), the receipt record (23), the sync replies (§11), the chunk rules (§13), the spine-signature and non-signing-statement answers (§12, 25). Every timeout, cooldown, budget, cache size and load level is local, but an implementation stricter than the fleet sees more failures, and one looser only exposes itself.

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