On this page
- §0 The area in one paragraph
- §1 Transport, framing and limits
- §1a The signed call
- §2 Messages
- §2.1 The services
- §2.2 Records shared by several RPCs
- §2.3 Request and response messages
- §3 Handshake
- §4 Heartbeat
- §5 Peer discovery
- §6 Node address announcements
- §7 Proof of origin
- §8 Receipt requests
- §9 Block delivery
- §10 Transaction delivery
- §11 Chain sync queries and the block-read budget
- §12 Spine signature and non-signing statement RPCs
- §13 Snapshot chunk download
- §14 Block candidates and storage pieces
- §15 GetStateSample
- §16 Load levels
- §17 Data kept, consensus and local
27 — P2P wire protocol
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.
-
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-typeapplication/grpc; the status travels in the trailersgrpc-statusandgrpc-message. No compression. -
One listening socket (
listen_address, default0.0.0.0:8001) serves both services;advertise_address(30) is what the node announces. -
Server limits: maximum received message 2,097,152 bytes; a larger request fails with
RESOURCE_EXHAUSTEDbefore 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. -
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
RequestBlockTransactionsuse the gRPC defaults (4 MiB receive). -
Client deadlines: 8,000 ms for
GetMorePeers,SendPeers,SendNodeAddressInfo,GetPeerInfo,Handshake,Heartbeat,GetNextBlockIDs,RequestSpineBlockSignature,RequestSpineRefusal,GetBlockHashes,GetStoragePiece,PutStoragePiece; 12,000 ms forGetCommonMilestoneBlockIDs; 16,000 ms forSendTransactionandGetNextBlocks; 10,000 ms forGetCumulativeDifficulty, a directSendBlockandBroadcastBlockCandidate; 5,000 ms for the blocksmith's block broadcast, the relays and the discoveryGetMorePeers; 15,000 ms forRequestBlockTransactionsand theSendBlockTransactionsthat answers it. -
Protobuf rules relied on (proto3): a field holding its default (0, false, empty) is omitted and reads back as the default;
repeated int64fields are emitted packed and accepted packed or unpacked; a negativeint64is a ten-byte varint; unknown field numbers are skipped; binary data always travels inbytesfields (astringfield must be valid UTF-8). -
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 frame
Loading the test widget…
The transport limits
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 deadlines
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):
- The caller's host = the host of the connection's peer string (
ipv4:host:port,ipv6:[host]:port, also the percent-encodedipv6:%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 writtena:b:c:d::/64); its strike key isaddr:+ the host. - 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". - Every method but
Handshakerequires a receiver; a receiver present must equal this node's key → else"signed request was made to another node". - 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". - 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". - SHA3-256 of the received body must equal the claimed digest → else
"signed request digest is not this request's". - 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. - 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. - 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. - The handshake requirement: every method but
Handshakethen requires the signing key to hold a peer-table entry marked handshake-verified (a same-chain handshake with this node, in either direction, §3) → elseFAILED_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 B
Loading the test widget…
A Handshake by address names no receiver: the 74-byte signing message
Loading the test widget…
Node B serves the call: signed for it, fresh, from a key with a handshake
Loading the test widget…
The same call served again inside 600 s
Loading the test widget…
A call made with receiver A, received by node B
Loading the test widget…
A call stamped 1,794,211,900 at a receiver whose clock reads 1,794,211,200: refused, no strike
Loading the test widget…
A call with none of the six entries
Loading the test widget…
A call whose signature entry is missing
Loading the test widget…
A call carrying the nonce entry twice
Loading the test widget…
A call with a 7-byte nonce
Loading the test widget…
A GetNextBlockIDs call that names no receiver
Loading the test widget…
A timestamp entry that is not a plain decimal integer
Loading the test widget…
A call whose signature does not verify
Loading the test widget…
A signed header delivered with another body
Loading the test widget…
A verified call from a key with no handshake with this node
Loading the test widget…
A Handshake that names no receiver passes the signed-call checks
Loading the test widget…
Five refused calls from one host within 60 s throttle its unbound blocks
Loading the test widget…
Five calls with a wrong clock strike nothing
Loading the test widget…
Four refused calls do not throttle
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)
Loading the test widget…
A negative block id is a ten-byte varint
Loading the test widget…
A served Block with 2,000 transaction ids decodes
Loading the test widget…
A served Block with 2,001 transaction ids decodes to an empty block
Loading the test widget…
An answer carrying a Block with 2,001 transactions is refused
Loading the test widget…
An answer carrying a Block with 65,537 non-signing statements is refused
Loading the test widget…
A served Block with 65,537 published receipts decodes to an empty block
Loading the test widget…
An answer carrying a Block with 2,000 transaction ids decodes
Loading the test widget…
The fields of Empty
Loading the test widget…
The fields of GetPeerInfoRequest
Loading the test widget…
The fields of Block
Loading the test widget…
The fields of Transaction
Loading the test widget…
The fields of Receipt
Loading the test widget…
The fields of PublishedReceipt
Loading the test widget…
The fields of SpinePublicKey
Loading the test widget…
The fields of SpineBlockManifest
Loading the test widget…
The fields of Node
Loading the test widget…
The fields of Peer
Loading the test widget…
The fields of SendBlockRequest
Loading the test widget…
The fields of SendBlockResponse
Loading the test widget…
The fields of SendTransactionRequest
Loading the test widget…
The fields of SendTransactionResponse
Loading the test widget…
The fields of SendBlockTransactionsRequest
Loading the test widget…
The fields of SendBlockTransactionsResponse
Loading the test widget…
The fields of RequestBlockTransactionsRequest
Loading the test widget…
The fields of GetCumulativeDifficultyRequest
Loading the test widget…
The fields of GetCumulativeDifficultyResponse
Loading the test widget…
The fields of GetCommonMilestoneBlockIdsRequest
Loading the test widget…
The fields of GetCommonMilestoneBlockIdsResponse
Loading the test widget…
The fields of GetNextBlockIdsRequest
Loading the test widget…
The fields of BlockIdsResponse
Loading the test widget…
The fields of GetNextBlocksRequest
Loading the test widget…
The fields of BlocksData
Loading the test widget…
The fields of SpineBlockSignature
Loading the test widget…
The fields of SpineRefusal
Loading the test widget…
The fields of SpineBlockSignatureRequest
Loading the test widget…
The fields of SpineBlockSignatureResponse
Loading the test widget…
The fields of SpineRefusalRequest
Loading the test widget…
The fields of SpineRefusalResponse
Loading the test widget…
The fields of GetPeerInfoResponse
Loading the test widget…
The fields of GetMorePeersResponse
Loading the test widget…
The fields of SendPeersRequest
Loading the test widget…
The fields of NodeAddressInfo
Loading the test widget…
The fields of GetNodeAddressesInfoRequest
Loading the test widget…
The fields of GetNodeAddressesInfoResponse
Loading the test widget…
The fields of SendNodeAddressInfoRequest
Loading the test widget…
The fields of GetNodeProofOfOriginRequest
Loading the test widget…
The fields of ProofOfOrigin
Loading the test widget…
The fields of FileDownloadRequest
Loading the test widget…
The fields of FileDownloadResponse
Loading the test widget…
The fields of HandshakeRequest
Loading the test widget…
The fields of HandshakeResponse
Loading the test widget…
The fields of HeartbeatRequest
Loading the test widget…
The fields of HeartbeatResponse
Loading the test widget…
The fields of BlockCandidateMessage
Loading the test widget…
The fields of BroadcastBlockCandidateRequest
Loading the test widget…
The fields of BroadcastBlockCandidateResponse
Loading the test widget…
The fields of GetBlockHashesRequest
Loading the test widget…
The fields of BlockHashInfo
Loading the test widget…
The fields of GetBlockHashesResponse
Loading the test widget…
The fields of GetStateSampleRequest
Loading the test widget…
The fields of AccountSample
Loading the test widget…
The fields of NodeSample
Loading the test widget…
The fields of GetStateSampleResponse
Loading the test widget…
The fields of GetStoragePieceRequest
Loading the test widget…
The fields of GetStoragePieceResponse
Loading the test widget…
The fields of PutStoragePieceRequest
Loading the test widget…
The fields of PutStoragePieceResponse
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):
- The caller's host is banned →
accepted = false,"Too many failed introductions". - Key 32 bytes, signature 64 bytes and valid over the preimage → else strike against the host,
"Invalid signature - authentication failed".versionis 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". |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¹²).genesis_hashempty → strike,"Genesis hash required"; own genesis unavailable →"Local genesis unavailable"(no strike); different → strike,"Genesis hash mismatch - different chain configuration".- Success clears the host's and the pair's strike records. A blacklisted key (
28) →"Peer is blacklisted". - 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 oflisten_addressis never used.- An inbound-only node: when
listen_addressis empty, starts with0.0.0.0,::,127.0.0.1orlocalhost, 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, aGetMorePeersanswer; 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 inGetMorePeers, pushed to) only when this node's own dial reaches that address and the key answers there.
- An inbound-only node: when
- Reply
accepted = true, own key, cached tip height,"Handshake accepted", own genesis, own clock,signature= Ed25519 overnode_public_key (32) ‖ chain_height u32 LE ‖ genesis_hash (32) ‖ timestamp i64 LE(76 bytes).archival_api_urlis 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 message
Loading the test widget…
The handshake response's signed bytes
Loading the test widget…
A signed, fresh handshake on the same chain is accepted
Loading the test widget…
A handshake received 700 s after it was stamped
Loading the test widget…
A handshake stamped 601 s ahead of the receiver
Loading the test widget…
A handshake 600 s old is still inside the window
Loading the test widget…
A handshake from another chain (first genesis byte changed)
Loading the test widget…
A handshake without a genesis hash
Loading the test widget…
A handshake whose signature does not verify
Loading the test widget…
A handshake advertising 0.0.0.0:8001 from 203.0.113.7: an inbound-only entry
Loading the test widget…
The same handshake for A held from gossip at 198.51.100.9:8001
Loading the test widget…
A ninth unregistered key from one host
Loading the test widget…
The gossiped A from behind NAT when 203.0.113.7 holds eight others
Loading the test widget…
The gossiped A advertising 203.0.113.7:8001 when that host holds eight others
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 eight
Loading the test widget…
A dial of a known key answered by another key
Loading the test widget…
Five failed introductions within 300 s ban the address for 900 s
Loading the test widget…
Failures more than 300 s apart start a new window
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 bytes
Loading the test widget…
A heartbeat with 64 zero bytes as signature
Loading the test widget…
A signed heartbeat received in its window
Loading the test widget…
A signed heartbeat received at 1,794,211,900
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.
- Seeds: the chain's seed file, one
host:portper line, shipped with the release (30). A seed is dialled with the handshake of §3; its key is learned from the response. GetPeerInfo(a signed caller with a handshake, §1a):HostInfo.PublicKey= own key,Height= cached tip,ArchivalApiUrlif configured.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 asNode{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.- 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). - Public-literal rule: strip the port (
[v6]:port→ inside the brackets; a single-colonhost: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 withfe80→ public IPv6; anything else (hostnames included) → not literal. 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 of28§1 applies). No node sendsSendPeers; aGetMorePeerslist forwarded as is (itsAddressalready holdshost: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 rule
Loading the test widget…
Private and reserved ranges are not public
Loading the test widget…
The host a caller is keyed on
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.
- 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;Status2. - 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 withblock_height ≥the entry's; the block atBlockHeightnot held or with another hash; the signature not valid under the registry key ofNodeID. Then the row is inserted with status 1 whateverStatussays. The duplicate test runs before the outdated test, so an unchanged address is never refreshed. GetNodeAddressesInfo: ≤ 1,000 ids (elseINVALID_ARGUMENT); one row per node id among statuses 1 and 2, a confirmed row preferred;FAILED_PRECONDITIONwithout a registry,INTERNALon a read failure. No node moves a row to status 2, and no node sendsGetNodeAddressesInfo.
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 announcement
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 bytes
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.
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.- Datum type 1 (block):
datum_hash= the block hash the request carries (Block.BlockHash). Type 2 (transaction): SHA3-256 ofTransactionBytes. Type 3 (batch): SHA3-256 of everyTransactionsBytesentry concatenated in order. SenderSignature= the sender's node-key Ed25519 signature overdigest, made per recipient (each peer gets its own). A sender that does not know the recipient's key sends no signature.- 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 whenrequire_signed_receipt_requestsis 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). - 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 block
Loading the test widget…
The datum of a pushed transaction
Loading the test widget…
The receipt request for a pushed transaction
Loading the test widget…
The datum of a pushed batch
Loading the test widget…
The receipt request for a pushed batch
Loading the test widget…
A request signed for B does not verify at another node
Loading the test widget…
The same request verifies at B
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 thePublishedReceipts; 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
Transactionsreplaced byTransactionIDs, 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):
- More
TransactionsorTransactionIDsthan 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";PayloadLengthabove 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. - 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 — elseaddr:+ the caller's host). - 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". - Decode (§2 caps). Main chain, a copy that carries its transactions, rule
block_size_serializedactive 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. - 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.) - 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.
ChainType == 1(spine; any other value counts as the main chain, so a block sent withChainType7 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).- Main chain,
Transactionsempty andTransactionIDspresent. 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 (RequestBlockTransactionswithRequesterPublicKey= 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. - 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 ids
Loading the test widget…
A SendBlock carrying 2,001 transactions
Loading the test widget…
Five invalid blocks charged to the sender's host in the last 60 s: its next unbound block is throttled
Loading the test widget…
A block received twice in byte-identical messages
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 registered
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):
- The node's emergency mode →
RESOURCE_EXHAUSTED "Node in emergency mode"; then the load gates (§16), allRESOURCE_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";TransactionByteslonger than the maximum block size →INVALID_ARGUMENT "Transaction larger than the maximum block size". - 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. - 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 itRESOURCE_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". - 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 answeredRESOURCE_EXHAUSTEDwith that text, nothing recorded (an honest relay forwards them). Any other validation error is answeredINVALID_ARGUMENTwith its text, not relayed, no receipt, and an invalid transaction is recorded against the charge identity (28§6: the key when bound and registered, elseaddr:+ the host). A refusal of this node's capacity (memory pressure,"System memory pressure - try again later") is answeredRESOURCE_EXHAUSTEDwith its text. A copy already staged is a duplicate and accepted. - 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 entries
Loading the test widget…
A RequestBlockTransactions naming 501 ids
Loading the test widget…
A sender neither registered nor queued: the 11th transaction in a minute is refused
Loading the test widget…
A queued sender: the 21st transaction in a minute is refused
Loading the test widget…
A SendTransaction whose sender already has 50 pending transactions
Loading the test widget…
A sender with 49 pending transactions is staged
Loading the test widget…
A duty of this node for this window already pending
Loading the test widget…
The reply to RequestBlockTransactions is signed over the batch digest
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).
GetCumulativeDifficulty{ChainType}→ the tip'sCumulativeDifficultyandHeight;INTERNAL "Failed to get latest block"without a tip.GetCommonMilestoneBlockIDs{ChainType, LastBlockID, LastMilestoneBlockID}: both 0 →INVALID_ARGUMENT "either LastBlockID or LastMilestoneBlockID has to be supplied";LastBlockID ≠ 0and held →BlockIds = [LastBlockID],Last= it is the tip; elseLastMilestoneBlockID ≠ 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 byjump(clamped at 0, stopping after height 0); a missing block on the walk →INTERNAL "failedGetBlocks";Lastfalse on this path.GetNextBlockIDs{ChainType, BlockId, Limit}(budgeted):Limitclamped to 100;BlockIdmust be held (NOT_FOUND "Block not found"); the ids of heights start+1 … tip in order, at mostLimit, missing heights skipped.GetNextBlocks{ChainType, BlockId, BlockIds}(budgeted;BlockIdis not read): more than 50 ids →INVALID_ARGUMENT "Too many block IDs requested"; each held id returned as a fullBlock(transactions included), missing ids omitted, in request order.GetBlockHashes{start_height, end_height}(main chain;chain_typeis not read):end < startorstart > tip→ empty,complete = false;endclamped to the tip and tostart + 999; oneBlockHashInfoper 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 7
Loading the test widget…
GetCumulativeDifficulty for the spine on a node without one
Loading the test widget…
GetCommonMilestoneBlockIDs with neither id
Loading the test widget…
GetNextBlocks naming 51 ids
Loading the test widget…
GetBlockHashes with end below start
Loading the test widget…
GetBlockHashes clamped to the tip
Loading the test widget…
GetBlockHashes clamped to 1,000 rows
Loading the test widget…
200 GetNextBlockIDs calls from one registered key within 10 s are answered
Loading the test widget…
The 201st call from one registered key within 10 s
Loading the test widget…
1,600 calls from one host spread over eight keys are answered
Loading the test widget…
The 1,601st call from one host, spread over nine keys
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).
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 A
Loading the test widget…
A SpineRefusalRequest without a spine block candidate
Loading the test widget…
§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 hash
Loading the test widget…
A chunk request naming no file
Loading the test widget…
A chunk request naming 33 files
Loading the test widget…
Chunks served and failed
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.
Output and effect. As below.
How to compute it.
BroadcastBlockCandidate: the block is decoded (§2), creator key and position copied,received_atset to the receiver's own clock, and offered to the candidate pool (24); the block is first noted by the equivocation ledger (§9); replyaccepted= the pool's decision,"Candidate added to pool"/"Candidate rejected"; no pool →accepted = false,"Block candidate pool not initialized".GetStoragePiece{piece_id, requester_public_key, timestamp, signature}:piece_idmust be 32 bytes and storage on, elsefound = false. A chunk only the archive keeps (26§10b) requires a registered requester:requester_public_key32 bytes,signature64 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; elsePERMISSION_DENIED "old snapshot chunks of the archive are served to registered nodes only (<reason>)". Every other piece is served to anyone. Thenfound = true, data.PutStoragePiece{piece_id, data}:accepted = falseunless storage is on,piece_idis 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), andSHA3-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 example
Loading the test widget…
The signed bytes of a piece request
Loading the test widget…
A piece request checked 301 s after it was signed
Loading the test widget…
A piece request signed by its requester, checked in time
Loading the test widget…
A piece request naming a key that did not sign it
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 tip
Loading the test widget…
A state sample of 33 addresses
Loading the test widget…
A second call from the same key 3 s after the first
Loading the test widget…
A ninth key from one host within 10 s
Loading the test widget…
An eighth key from one host within 10 s is answered
Loading the test widget…
Defects to match. None.
§16 Load levels
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 samples
Loading the test widget…
SendTransaction at the High P2P level
Loading the test widget…
A resident set averaging 3.2 GiB under a 4 GiB limit is High
Loading the test widget…
SendTransaction at the High memory level
Loading the test widget…
A Medium level does not refuse a transaction
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.