On this page
  1. §0 The area in one paragraph
  2. §1 The peer record and the peer table
  3. §2 Bootstrap: the advertised address, seeds and the start-up gate
  4. §3 Outbound connection and the pending list
  5. §4 Heartbeat loop and stale cleanup
  6. §5 Failure accounting, backoff, disconnection and recovery
  7. §6 Charging, rate limits and the blacklist
  8. §7 Known-data tracking
  9. §8 Propagation: what goes to whom, and when
  10. §9 Sync drivers and the health check
  11. §9a Block-production gate
  12. §9b Clock-skew production veto
  13. §10 Address announcement loop
  14. §11 Peer discovery loop
  15. §12 Node health monitor
  16. §13 Storage transport
  17. §14 Configuration keys of this area
  18. §15 Data kept

28 — P2P behaviour: peer table, failure accounting, charging, blacklists, propagation, sync drivers, health

Edition 0.6.1 · verified against the reference implementation, version 0.6.1

Out of scope the wire messages and the server-side handlers (27); the sync algorithm's block-level decisions and the fork resolver (24); the scramble and priority-peer computation (23); snapshot fast sync (26); the HTTP API (31); configuration keys outside [advanced] and [network] (30)

§0 The area in one paragraph

Everything in this chapter is local behaviour: none of it is hashed, signed into the chain or checked by other nodes, so an implementation may choose other numbers — but one that is stingier than the fleet finds itself alone and one that is laxer only exposes itself. A node keeps an in-memory table of peers keyed by their 32-byte node key, learned from the seed addresses, from GetMorePeers gossip and from inbound handshakes. Every call a peer makes is signed by its key (27 §1a) and, but for the handshake, allowed only once that key completed a handshake with this node ("handshake-verified"); an address is trusted — dialled on its own, passed on to others ("chain-verified") — only once this node's own dial reached the key there, because a signed handshake can be forwarded by whoever received it. A node that advertises no routable address (a home node behind NAT) holds an inbound-only entry with no address: it may call this node and sync from it, and is never dialled, gossiped or pushed to. A host (an IPv4 address, or an IPv6 /64) holds at most eight unregistered entries. The registered flag follows the node registry. Five background loops run: heartbeat (30 s), sync (10 ± 2 s, spine first), discovery (60 s), recovery (30 s, 10 s when isolated, and at once when a handshake asks for a dial) and address announcement (30 s, which also re-dials the seeds when fewer than 3 peers are connected). Consecutive RPC failures put a peer into a growing backoff and disconnect it at 10. Invalid data is charged to an identity the connection proves — the claimed node key only when it is registered and bound (it signed the call, or its receipt-request signature verified), otherwise the caller's host — and repeated bad blocks or invalid transactions blacklist a key on a 5/15/35/60-minute ladder; a registered peer is blacklisted only for a reason naming a security violation, and never while that would leave 3 or fewer active peers. Transactions are rate-limited per source host by the sender's tier. Propagation follows 23's topology. Guards keep the node producing: a production gate that stops a bare height claim from holding production for long, a clock-skew veto, a registry quorum that picks whom a stalled node syncs from, and a cool-down for peers whose branch was rejected. A health monitor moves the node through Normal / Warning / Critical / Emergency and caps what it accepts and produces.

§1 The peer record and the peer table

Purpose. What an implementation must keep about every peer, and which peers count as usable.

Inputs. Handshakes (27 §3), gossip (27 §5), seeds, RPC outcomes, the node registry.

Output and effect. The in-memory table behind every "connected peers" choice, /api/v1/node/peers and peer_count in /api/v1/node/info (31); not persisted across restarts.

How to compute it. A peer record: node_public_key (32 bytes, the identity; the table key is its lower-case hex), address ("host:port", [host]:port for IPv6; empty for an inbound-only entry), observed_host (the host group a handshake with no routable address came from: an inbound-only entry's, or a gossiped entry's whose key then handshook from behind NAT; empty otherwise), chain_height, last_seen (unix seconds), connected, consecutive_failures, last_failure, next_retry_at, registered, archival_api_url, chain_verified (the ADDRESS: this node's own dial reached exactly the stored address and the key answered there; never true for an entry with no address), handshake_verified (the KEY: it completed a same-chain handshake with this node in either direction, so it may call this node; chain_verified implies it), clock_known, clock_offset (§9b). The host of an entry is its address's host group (an IPv4 address as it is, an IPv6 address by its /64), or, with no address, its observed_host. The per-host count at host H counts every unregistered entry whose address's host is H or whose observed_host is H (each entry once at each host; a gossiped entry admitted from behind NAT counts at both of its hosts). Rules:

  1. Add (address, key): the key must be 32 bytes; never the node itself; a key under ban is refused ("Peer is currently blacklisted"; an expired ban is cleared on the way); a key already present is refused ("Peer already exists"); an unregistered key whose host already holds eight unregistered entries is refused ("Too many unregistered peers from host H", logged once per host); at 1,024 entries one unconnected, unregistered entry is evicted — an entry whose key never completed a handshake here (not handshake-verified: gossip) before a handshake-verified one, within a tier the entry whose host holds the most unconnected unregistered entries, then the oldest last_seen — and when none qualifies the add fails ("Peer table full"). A new record starts with last_seen = now, everything else zero / false (a new entry is never chain-verified). An inbound-only add (observed host, key; 27 §3) stores an entry with no address, handshake-verified and not chain-verified, under the same cap and eviction; for a key already in the table it changes nothing when the key is handshake-verified, and otherwise (a gossiped entry) marks the key handshake-verified and records the observed host beside the unverified address, refused "Too many unregistered peers from host H" with nothing changed when H already holds eight other unregistered entries and neither the key nor the entry is registered.
  2. Address of a known key: an entry whose address this node never reached (gossiped, or inbound-only) takes the address a signed handshake observed (inbound) or this node's own dial reached (outbound); a chain-verified entry moves only when this node's own dial reached the key at the new address, or when its stored address has failed 3 or more consecutive dials; an unregistered entry never moves to another host already holding eight unregistered entries. A changed address drops the open connection, resets the failure counters, clears observed_host (the entry counts against its new address's host alone from then on) and, for a move that is not this node's own dial reaching the key there, clears chain_verified: an entry an inbound handshake moves after 3 failed dials is handshake-verified only until the dial the handshake requests reaches the key at the new address (rule 4). A move the cap refuses: an inbound handshake of a key that is not yet handshake-verified is refused (27 §3); a dial verifies nothing (rule 4).
  3. connected is set when a channel to the stored address opens (refused while banned, for an unknown key, for an entry with no address, or when a channel exists) and cleared by a disconnect, a ban or the failure threshold (§5). A peer counts as connected for every choice in this chapter only when connected is true and it is not inside a retry backoff (next_retry_at = 0 or ≤ now). An inbound-only entry is therefore never a target of anything this node sends.
  4. chain_verified is set only when this node's own dial is answered by the entry's key and the entry then holds exactly the dialled address (27 §3; it also sets handshake_verified and clears observed_host); a dial whose move the cap refuses sets nothing; it is cleared by every move that is not such a dial (rule 2). handshake_verified is set by that and by an accepted inbound handshake (with or without a routable address). Each reader takes the flag it means: handshake_verified for the caller check (27 §1a, FAILED_PRECONDITION "no handshake for this chain"), the RequestBlockTransactions gate (27 §10), the eviction tier (rule 1) and the start-up prune below; chain_verified for the recovery loop's budget of never-dialled entries (§5), the GetMorePeers answer (27 §5), the no-move rule (rule 2), the address binding of a claimed key (§6), the choice of an entry at a caller's host (27 §5) and the RequestBlockTransactions push (27 §10). At start every peer that is neither handshake-verified nor registered and whose address is not a public IP literal (27 §5) is deleted.
  5. registered = the registry's status for the key is Registered (09); looked up when the peer's connection opens, refreshed for every connected peer at the top of each heartbeat cycle and right after a fast-sync apply (from the snapshot's registry), and set on inbound block and transaction traffic.
  6. last_seen is refreshed by a successful outbound heartbeat, difficulty query, block / candidate / transaction push or handshake, and by an inbound handshake or heartbeat of a known key (a heartbeat only from the host the entry is stored at).
  7. Removal: stale cleanup (§4), a ban (§6), eviction (rule 1). Removal also drops the known-data record (§7) and the per-key query stamps.

Rule activation. None.

Rejections and errors. As listed; all local.

Vector. computed: a table of 1,024 entries, two of them unconnected and unregistered — one gossiped (its key never handshook here) at a host holding three such entries, one chain-verified last seen 2 h ago — the rest connected; adding a new key evicts the gossiped one and succeeds. The same table with every entry connected → "Peer table full". A ninth unregistered key from host 203.0.113.7 → "Too many unregistered peers from host 203.0.113.7". A chain-verified entry at 203.0.113.7:8001 whose handshake now arrives from 198.51.100.9: the entry stays, 198.51.100.9:8001 is dialled; the key answering there moves the entry. The same after three failed dials of 203.0.113.7:8001: the handshake moves it at once to 198.51.100.9:8001, handshake-verified and not chain-verified (not gossiped, not pushed to); this node's dial of 198.51.100.9:8001 answered by the key makes it chain-verified again. A table of 1,024 whose only two unconnected unregistered entries are an inbound-only key (handshake-verified, last seen 2 h ago) and a gossiped one (seen now) → the gossiped one is evicted. INVALID: a gossiped unregistered key at 198.51.100.9:8001 handshaking from 203.0.113.7 with no routable address while 203.0.113.7 already holds eight other unregistered entries → "Too many unregistered peers from host 203.0.113.7", the entry unchanged and the key still not handshake-verified; this node's dial of 203.0.113.7:8001 answered by that key → the dial fails (27 §3), the entry stays at 198.51.100.9:8001, not chain-verified.

Test cases · §1

12 cases · 8 valid · 4 invalid

A full table evicts its gossiped entry before a chain-verified one seen 2 h ago28-1-evictvalid

Loading the test widget…

A full table of connected peers refuses a new key28-1-fullinvalid

Loading the test widget…

A ninth unregistered key from one host28-1-ninthinvalid

Loading the test widget…

A chain-verified entry whose handshake arrives from another host stays; that address is dialled28-1-verified-moved-hostvalid

Loading the test widget…

The key answering this node's dial at the new address moves the entry28-1-verified-dialledvalid

Loading the test widget…

After three failed dials of its address the handshake moves the entry at once28-1-verified-failingvalid

Loading the test widget…

The moved entry is chain-verified again once this node's dial reaches the key there28-1-verified-failing-dialledvalid

Loading the test widget…

Between an inbound-only key seen 2 h ago and a gossiped one seen now, the gossiped one goes28-1-evict-gossip-firstvalid

Loading the test widget…

Within one tier and one count per host the entry seen longest ago goes; a registered one never28-1-evict-oldestvalid

Loading the test widget…

A table below 1,024 entries takes the key without eviction28-1-roomvalid

Loading the test widget…

A gossiped key handshaking from behind NAT at a host holding eight others28-1-gossiped-nat-cappedinvalid

Loading the test widget…

This node's dial of 203.0.113.7:8001 answered by that key28-1-dial-cappedinvalid

Loading the test widget…

Defects to match. (1) An entry with no address, or one whose key handshook from behind NAT while it holds a gossiped address at another host, has its last_seen refreshed only by its handshakes, not by its heartbeats (the heartbeat's host check compares the caller's host with the stored address's host), so such an entry goes stale after stale_peer_timeout (600 s; 3,600 s when registered) and the node behind NAT must handshake again, which its own recovery loop does once its calls are refused "no handshake for this chain".

§2 Bootstrap: the advertised address, seeds and the start-up gate

Purpose. How an implementation enters the network.

Inputs. node.conf [network]: listen_address (default 0.0.0.0:8001), advertise_address, public_ip, discover_public_ip (default true), seed_peers, seed_api_port (8080), p2p_enabled (true), require_bidirectional (false) (30).

Output and effect. A listening server (27 §1), the advertised address in every handshake and announcement, the first peers.

How to compute it.

  1. The public IP: public_ip set (an IPv4 address, no port) → used as stated, nothing looked up; discover_public_ip = false and no public_ip → nothing looked up, advertise_address used as written; otherwise looked up: external IP-echo services over HTTPS first (3 s timeouts), then the seed nodes' HTTP API GET /api/v1/node/public-ip on each public seed host at seed_api_port, with headers X-Node-Public-Key (hex), X-Timestamp (unix s) and X-Signature = hex Ed25519 over the ASCII string "GET:/api/v1/node/public-ip:<timestamp>:"; the reply's JSON ip is used.
  2. The advertised address is filled from the public IP when advertise_address is empty, starts with auto (any case), equals listen_address, or has a private / loopback host. With require_bidirectional the advertised host must be public and its port equal the listen port, or the node refuses to start. A peer records a node at its observed IP with the advertised port (27 §3): a wrong host costs nothing, a wrong port does.
  3. Start order: the server; 500 ms; unservable peers pruned (§1 rule 4); the loops (heartbeat at once, sync after 5 s, discovery after 10 s, recovery after 15 s or at once when an inbound handshake asks for a dial, announcement after 10 s); every seed dialled once through the handshake; then the start-up sync gate: up to 30 one-second attempts, each taking the connected peers seen within 120 s and passing when our height ≥ their highest height (or after 5 attempts when both are 0), otherwise running a sync (24). Block production begins after the gate.
  4. Later, the announcement loop re-dials every seed that is not our own address, not connected and not already known whenever fewer than 3 peers are connected, once per 30 s cycle.

Rule activation. None.

Rejections and errors. "Invalid public_ip '<x>' (an IPv4 address without a port, e.g. 203.0.113.7)" at configuration load; a require_bidirectional failure stops the node.

Vector. computed. INPUT: public_ip = 203.0.113.7, listen_address = 0.0.0.0:8001, advertise_address empty. EXPECTED OUTPUT: advertised 203.0.113.7:8001, no lookup made. INPUT: public_ip = 203.0.113.7:8001 → the configuration error above. INPUT: the seed request signed at 1,794,211,200 → the signed string is GET:/api/v1/node/public-ip:1794211200:.

Test cases · §2

3 cases · 2 valid · 1 invalid · 1 reference

A stated public_ip fills the advertised address; nothing is looked up28-2-public-ipvalid

Loading the test widget…

A public_ip with a port is a configuration error28-2-public-ip-portinvalid

Loading the test widget…

The start-up sync gate28-2-start-gatevalidreference

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

attempts
30 of one second
peers_considered
connected, seen within 120 s
passes
our height >= their highest (or after 5 attempts when both are 0)
loop_starts_s
heartbeat 0, sync 5, discovery 10, recovery 15, announcement 10

Defects to match. None.

§3 Outbound connection and the pending list

Purpose. How an implementation turns an address into a verified, connected peer and keeps trying addresses that did not answer.

Inputs. An address, optionally a known key.

Output and effect. A peer record with a channel, or a pending-address entry.

How to compute it. Every dial is the outbound handshake of 27 §3 (10 s deadline), signed for the expected key when one is known. Outcomes for a dial by address (a seed, a pending address, a discovered address): transport failure or a refusal → the address joins the pending list (or its attempt count grows), a "Genesis hash mismatch" refusal → dropped for good; success → the address leaves the pending list, the peer is added (an existing entry tolerated; the entry takes the dialled address), marked chain-verified and handshake-verified, its archival URL stored, connected, height set, failures reset. Outcomes for a dial of a known key: a transport failure, a refusal, a response from another key ("dial answered by another key") or a clock outside the window → one failure on the entry (§5); success → as above, the entry taking the dialled address whatever it held. Either way, when the per-host cap refuses the entry's move to the dialled address (§1 rule 2) the dial fails as a table refusal (27 §3): nothing is verified or connected, the entry keeps its address and flags, and no failure is counted anywhere. Pending list: an address enters with attempt count 1 unless a connected peer has it; the recovery loop retries it when its last attempt is ≥ 30 s old; after 10 attempts it is forgotten. A node whose own height cannot be read does not handshake.

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

Vector. computed: an address that refuses TCP is dialled at t = 0 and then every 30–60 s by the recovery loop until its 10th attempt (roughly 5–10 minutes), then forgotten until something re-adds it. A gossiped entry for key K at 203.0.113.7:8001 whose dial is answered by key L → the dial fails, K's entry takes a failure and stays unverified; nothing is stored for L.

Test cases · §3

3 cases · 1 valid · 2 invalid · 1 reference

An address that refuses TCP28-3-pendingvalidreference

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

retries
every 30-60 s by the recovery loop
forgotten_after_attempt
10
duration
roughly 5-10 minutes
A gossiped K at 203.0.113.7:8001 whose dial is answered by L28-3-other-keyinvalid

Loading the test widget…

Nothing is stored for the key that answered28-3-other-key-not-storedinvalid

Loading the test widget…

Defects to match. None.

§4 Heartbeat loop and stale cleanup

Purpose. How an implementation keeps liveness, heights and registration flags fresh and drops silent peers.

Inputs. The connected peers, the registry, the topology (23).

Output and effect. Height and last-seen updates; failure counts; removals.

How to compute it. Every 30 s:

  1. For every connected peer set registered from the registry.
  2. Priority set = this node's priority peers of 23 at scramble height tip − 1 (max_assigned_peers: DevNet 8, TestNet and the mainnet template 12).
  3. Targets: every connected priority peer; every other connected registered peer on cycles where cycle mod 3 = 0; never an unregistered non-priority peer.
  4. Heartbeats in parallel (27 §4, 8 s). Success → height, last seen, failures reset. A connection error ("Connection refused", "failed to connect", "UNAVAILABLE") drops the cached channels for that address; a timeout is forgiven when the node's own health level is ≥ Critical or the peer was seen ≤ 90 s ago; otherwise a failure (§5).
  5. Stale cleanup: every peer with last_seen > 0 older than 600 s (3,600 s when registered) is removed with its channel; expired bans are cleared; channels to addresses no longer connected are dropped.

Rule activation. None. Rejections and errors. None.

Vector. computed: 10 connected registered peers, 8 of them priority → a cycle sends 8 heartbeats, every third cycle 10. A registered peer last seen 3,601 s ago is removed; an unregistered one at 601 s.

Test cases · §4

2 cases · 2 valid · 1 reference

Heartbeat targets per cycle28-4-targetsvalidreference

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

connected_registered
10
priority
8
per_cycle
8
every_third_cycle
10
Stale cleanup: 3,600 s for registered peers, 600 s for the others28-4-stalevalid

Loading the test widget…

Defects to match. §1 defect (1): the stale cleanup removes an inbound-only entry whose heartbeats never refreshed it.

§5 Failure accounting, backoff, disconnection and recovery

Purpose. When an implementation leaves a failing peer alone and when it retries it.

Inputs. RPC failures from the heartbeat, sync, broadcast and candidate paths.

Output and effect. consecutive_failures, next_retry_at, connected; re-dials.

How to compute it.

  1. A failure on a connected peer: consecutive_failures += 1, last_failure = now, next_retry_at = now + backoff, backoff = 15 s doubled per earlier failure, capped at 120 s (600 s when registered): 15, 30, 60, 120, 120… / 15, 30, 60, 120, 240, 480, 600…; at 10 failures the peer is disconnected and its channel dropped. On a disconnected peer: last_failure = now, next_retry_at = now + 15, nothing counted. Any success zeroes the three fields.
  2. What counts: heartbeats (§4); GetCumulativeDifficulty in sync (timeouts forgiven when seen ≤ 90 s ago); block broadcast and candidate broadcast (non-deadline errors); API transaction broadcast (errors other than DEADLINE_EXCEEDED and RESOURCE_EXHAUSTED); a failed dial of a known key (§3).
  3. Recovery loop (first after 15 s or when an inbound handshake asks for a dial, then every 30 s, every 10 s while fewer than 3 peers are connected, and at once on a dial request): the candidates are every peer that is not connected, has an address, is not banned, and whose last_failure is 0 or ≥ 60 s old (30 s when registered), taking at most eight unregistered entries per host and at most eight never-dialled (not chain-verified) entries per pass; each has its counters reset and is re-dialled with the handshake of §3, 500 ms apart, a failed dial counting against it; then the pending addresses (§3). While isolated with nothing to re-dial and a non-empty blacklist, the whole blacklist is cleared. Before the chain's genesis time only genesis-mismatch failures are reported, at most hourly per address.

Rule activation. None. Rejections and errors. None.

Vector. computed: a registered peer failing every heartbeat it is sent: backoffs 15, 30, 60, 120, 240, 480, 600, 600, 600 s, disconnected at the 10th failure; re-dialled by the recovery loop 30 s later.

Test cases · §5

3 cases · 3 valid · 1 reference

A registered peer failing every heartbeat28-5-registeredvalid

Loading the test widget…

An unregistered peer's backoff stops at 120 s28-5-unregisteredvalid

Loading the test widget…

Re-dial of a disconnected peer28-5-recoveryvalidreference

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

registered_redial_after_s
30
unregistered_redial_after_s
60
loop_period_s
30 (10 while fewer than 3 peers are connected)

Defects to match. None.

§6 Charging, rate limits and the blacklist

Purpose. How an implementation decides whom invalid data is charged to, limits transaction floods, and shuts out peers that keep sending invalid data, without ever isolating itself or cutting off registered nodes for timing noise.

Inputs. The signed call (27 §1a) and the receipt-request verdict of 27 §8; the caller's host; the claimed SenderPublicKey; block and transaction outcomes; require_signed_receipt_requests.

Output and effect. Charge records, throttles, ban entries; the banned peer and its channel removed.

How to compute it.

The charge identity of a block's or transaction's sender (used by the invalid-block throttle of 27 §9 step 3, the invalid-block record, the invalid-transaction record and the validation-failure record of §9):

  1. The claimed key is bound to the connection when it is the key that signed the call (27 §1a), when the request's receipt-request signature verifies (27 §8), or — only while require_signed_receipt_requests is off — when the peer table holds a chain-verified entry for that key whose host is the caller's host.
  2. Bound and registered → charged as the key (its lower-case hex); otherwise charged as addr: + the caller's host (as the claimed key's hex when no host is readable).
  3. The invalid-block record: per charge identity, the timestamps of invalid blocks in the last 60 s; 5 or more → the throttle of 27 §9 step 3 for an identity that is not bound-and-registered. At most 4,096 identities: a new one when full evicts the identity whose newest stamp is oldest; every 300 s identities whose newest stamp left the window are dropped. A call refused by the signed-call checks (unsigned, malformed, wrong receiver, bad signature or digest, replayed; not a clock outside the window) is recorded here against addr: + the host.

Transaction rate (27 §10): per source host (the claimed key's hex when no host is readable), a sliding 60-s window; the tier follows the claimed key only when it is bound: registered 2,000, queued (an admission-queue node) 20, other 10 transactions per minute ([advanced] registry_tx_rate_limit, queued_tx_rate_limit, stray_tx_rate_limit); a request counts once per transaction it carries; over the limit → RESOURCE_EXHAUSTED "Per-source transaction rate limit". At most 4,096 sources: a new one when full first sweeps sources with nothing in their window, then evicts the source touched longest ago.

Bad blocks (from sync, 24: a block that fails validation or application): reasons containing "previous block not found", "not assigned to any valid turn", "timestamp", "Blocksmith not found", "already have block", "missing previous", "block height mismatch" or "cannot validate" are not recorded; for a registered peer, reasons containing "applied transaction", "double-spend", "emergency", "timeout", "deadline", "resource exhausted" or "sync" are ignored too. A reason containing "fork", "Fork", "at current height" or "duplicate" is fork-related. Per key: the first record sets bad_block_count = 1, the window start, and fork_failure_count 1 or 0; a record whose window started ≥ 600 s ago restarts the same way; otherwise a fork-related reason increments fork_failure_count and adds a bad block only when that count is even; another reason adds one. At 10 (50 for a registered peer) the record is erased and the key is banned with "Sent <n> bad blocks…: <reason>". A sync block whose round opens more than 900 s ahead is recorded as a bad block ("Block at height h during sync is dated s s ahead of its round").

Invalid transactions (staging validation errors on SendTransaction, 27 §10, excluding the backpressure refusals — the duty-already-pending and the 50-per-sender cap — which record nothing): per charge identity (the key when bound and registered, else addr: + the host), a 300 s window from the first; 5 (10 for a registered peer) → banned with "Sent <n> invalid transactions: <reason>" (an addr: identity is not a key and cannot be banned; its record only grows).

Proven lies (an equivocating blocksmith, 27 §9; a difficulty claim its own blocks contradict, 24): the key's lie count grows and it is banned with "proven lie: <reason>"; with 2 or more lies the key is also left out of peer choices for the rest of the session.

The ban: a registered peer is banned only when the reason contains "signature", "malformed", "invalid hash", "injection", "overflow" or "proven lie", matched case-sensitively ("InvalidSignature" does not contain "signature"); otherwise its bad-block record is cleared and nothing happens. Nothing is banned while the connected, unbanned peers number ≤ 3. Ban length by offence count 1 / 2 / 3 / 4+: 300 / 900 / 2,100 / 3,600 s; the count continues from an existing entry unless its first offence is ≥ 86,400 s old. The entry keeps banned_until, first_offense_time, offense_count, reason; the peer record and channel are deleted. While banned: adding, connecting and re-dialling the key are refused, its inbound handshake is answered "Peer is blacklisted", discovery and recovery skip it. Expiry is checked lazily and every heartbeat cycle; an expired entry is erased with its offence count, so a peer that serves its ban and offends again is banned 300 s again: the count climbs only when a key is banned again while its entry still stands. All bans are cleared when the sync loop finds no connected peer at all, or the recovery loop is isolated with nothing to retry.

Rule activation. None.

Rejections and errors. Local, plus the replies of 27 §9–§10.

Vector. computed. INPUT: a block sender claiming registered key K with no SenderSignature, from 203.0.113.7, whose call was signed by another key L, while require_signed_receipt_requests is on → charged as addr:203.0.113.7. The same block in a call signed by K itself → charged as K's hex (bound). The same with the switch off and a chain-verified peer entry for K at 203.0.113.7 → charged as K's hex (bound). INPUT: an unregistered peer sends 10 blocks refused as "InvalidSignature" within 600 s → banned 300 s; the same again within 24 h, each time after the ban has expired → 300 s each time (the expired entry and its count are gone). A registered peer sending 50 such blocks is not banned (the reason "Sent 50 bad blocks (registered node, elevated threshold): InvalidSignature" does not contain "signature"); its bad-block record is cleared. The same 50 blocks refused as "Invalid block signature" → banned 300 s. INPUT: five unsigned calls from one host within 60 s → the host's blocks are throttled (27 §9 step 3).

Test cases · §6

15 cases · 15 valid

A block claiming registered K, with no receipt signature, in a call signed by another key28-6-unsignedvalid

Loading the test widget…

The same block in a call signed by K itself28-6-bound-by-callvalid

Loading the test widget…

The same sender bound by a chain-verified peer entry while the switch is off28-6-bound-by-entryvalid

Loading the test widget…

A registered sender whose receipt-request signature verifies28-6-bound-by-signaturevalid

Loading the test widget…

A bound but unregistered sender is charged by address28-6-unregistered-boundvalid

Loading the test widget…

An unregistered peer banned four times within 24 h28-6-laddervalid

Loading the test widget…

Nine bad blocks do not ban28-6-ninevalid

Loading the test widget…

A registered peer sending 50 blocks refused as "InvalidSignature"28-6-registered-50valid

Loading the test widget…

A registered peer sending 50 blocks refused as "Invalid block signature"28-6-registered-50-lowervalid

Loading the test widget…

A registered peer's bad block reported from sync is never recorded28-6-registered-syncvalid

Loading the test widget…

No ban while it would leave 3 or fewer active peers28-6-floorvalid

Loading the test widget…

Fork-related refusals count every second one28-6-fork-weightvalid

Loading the test widget…

A timing refusal is not recorded28-6-non-faultvalid

Loading the test widget…

Five unsigned calls from one host within 60 s throttle the host's blocks28-6-unsigned-callsvalid

Loading the test widget…

A registered relay may send 2,000 transactions a minute28-6-rate-registeredvalid

Loading the test widget…

Defects to match. None.

§7 Known-data tracking

Purpose. How an implementation avoids pushing a block or transaction to a peer that already has it.

Inputs. Pushes and arrivals.

Output and effect. Peers skipped.

How to compute it. Per peer key: up to 256 block hashes and up to 256 hashes of received transaction bytes, least recently used evicted; at most 1,024 peers tracked, the least recently active evicted. Marked when a block or transaction arrives from a bound sender (§6; an unbound claim marks nothing, so a stranger claiming a key cannot stop the relay to it) and before every push to it; checked before every push; cleared when the peer is removed.

Rule activation. None. Rejections and errors. None.

Vector. computed: a blocksmith whose 10 peers all relayed its block back first skips all 10.

Test cases · §7

1 case · 1 valid · 1 reference

Peers that relayed a block back are skipped28-7-knownvalidreference

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

peers
10
all_relayed_it_back_first
true
pushes
0

Defects to match. None.

§8 Propagation: what goes to whom, and when

Purpose. The fan-out an implementation uses for produced blocks, candidates, its own duties and user transactions (relays of received data are 27 §9–§10).

Inputs. The topology of 23; the connected peers; the known-data sets.

Output and effect. SendBlock, BroadcastBlockCandidate, SendTransaction calls; receipts stored (23).

How to compute it.

  1. Produced main chain block: the connected peers among the blocksmith's priority peers at scramble height height − 1, then other connected peers up to 20 in total; with no priority peer connected, all connected peers. Peers that know the hash are skipped; each remaining peer is marked, then sent the request of 27 §9 with its own receipt-request signature, in parallel, 5 s deadline. The blocksmith waits at most 3,000 ms or until min(3, ⌈n/2⌉) successes; a reply's receipt is kept when its sender is the blocksmith and both parties are in the registry; late replies are stored for 3 s more (they may join a later block's receipts, 23). A spine block uses the same path with chain type 1.
  2. Block candidate (24): priority peers among the connected registered peers, then other connected registered peers up to 20 (all connected registered peers without a priority match); 10 s deadline; the same 3 s / min(3, ⌈n/2⌉) wait.
  3. Own duties (snapshot attestation, storage-proof batch, queue attendance, liveness attestation): to every connected peer as soon as the pool takes them; the newest 64 are sent again every 120 s while still pending. The roll-call answer has its own 120 s re-send (36).
  4. Transaction submitted through the HTTP API: skipped at health level ≥ Critical; else the canonical bytes go to every connected peer, each request signed for that peer (27 §8), 5 s deadline, all awaited; receipts stored when both parties are in the registry.
  5. Spine signatures and non-signing statements (25 §6a–§6b): sequentially over the connected peers whose key is among the counting spine signers of the candidate (25 §6; all connected peers when the spine signers cannot be read), de-duplicated by signer key, stopping when the required spine signatures are gathered; then the non-signing round and, when a bound group cannot be released, the re-collection of its candidate.
  6. Scramble maintenance: after every applied block the scrambled list is rebuilt when height mod topology_period = 0 (40 on both chains) from the active registry and the block seed (23).

Every push is a signed call for the peer it is made to (27 §1a). An inbound-only entry (no address, §1) is never connected from this side and so receives none of the above; a node behind NAT learns blocks and transactions by pulling (27 §11).

Rule activation. None. Rejections and errors. None at this layer.

Vector. computed: 10 connected peers, 8 of them priority → the blocksmith sends to all 10 and returns after 3 receipts or 3 s.

Test cases · §8

1 case · 1 valid · 1 reference

A produced block's fan-out28-8-fan-outvalidreference

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

connected
10
priority
8
sent_to
10
returns_after
min(3, ceil(10/2)) = 3 receipts or 3,000 ms

Defects to match. None.

§9 Sync drivers and the health check

Purpose. When an implementation asks peers for blocks and when it suspects it is on the wrong branch (the algorithms are 24's; this section fixes the schedule and the peer bookkeeping).

Inputs. Random samples of connected peers; difficulty replies (27 §11).

Output and effect. Blocks applied; peers failed, forgiven, deferred or set aside; fork investigations.

How to compute it.

  1. Sync loop: first after 5 s, then every 10 s ± 2 s (a uniform whole-second jitter in −2…+2). A circuit breaker opens for 60 s after 5 consecutive errors and closes on a success. A node whose own height cannot be read skips the pass (a fault is never taken for the bootstrap case).
  2. Spine first (25 §8): 3 random connected registered peers (any connected peers while the main height is ≤ 10), the best spine weight followed, blocks stored (ahead of the main chain too); a mismatch at a held height triggers the spine fork path. A fetched spine block refused as naming another main chain block than this node's, carrying at least its required spine signatures, is checkpoint evidence for the fork resolver (24) and a fork outcome against that peer, never a bad block; any other invalid spine block is a bad block for the peer (§6) unless this node's clock is skewed (§9b).
  3. Main (24): the same 3-peer sample; a peer in the divergent cool-down (below) is not "best"; a peer whose branch was applied only in part on the last pass is skipped once, so the rest of that branch is fetched from another peer. Registry quorum for a stalled node (tip older than twice the recovery limit): a tip reported with the same height and cumulative difficulty by at least ceil(2 × answers / 3) of a sample of at least 3 distinct registered peers picks whom to sync from; the branch is then weighed like any other and a lighter one refused after comparison; without a quorum the heavier branch is kept. When no sampled peer answers the difficulty query, the node syncs from the sampled peer whose recorded chain_height is highest above its own (a height that may be stale). Fast sync (26) is tried before block paging. The paging cursor moves only to the newest block the node now holds; a batch that fails part-way ends the pass. Every fetched block is decoded under the transport caps of 27 §2 (2,000 transactions or transaction ids; 65,536 receipts, spine keys, manifests or statements), an oversized one refused. A block whose round opens more than 900 s ahead is a bad block from that peer (§6) and ends the pass; a block whose round opens sooner pauses the sync until it does. Validation failures → a validation-failure record (per height, under the charge identity; one record per identity per height, at most 64 per height, the oldest dropped first; records older than 120 s dropped; above 200 heights, the lowest heights are erased down to 100); 3 distinct identities failing at one height within 60 s → a pending fork investigation; "Invalid previous block hash" → the fork resolver at once; other failures → a bad block (§6) and the pass ends.
  4. Divergent cool-down: a fork resolution whose branch is rejected after comparison sets the peer (by key) aside for 10, 20, 40, 80, then 120 minutes as the streak grows; a resolution that stopped on this node's own read fault is not an outcome. A wedge (24: the signed-evidence verdict that this node sits beyond its rollback bound on a branch the spine left) is rebuilt in place from a spine-attested snapshot first (26); when that fails the wedge reason is declared and the resync marker is the fallback (30 §5). The streak detector (10 consecutive failed resolutions against at least 2 distinct peers over at least 1,800 s with the height frozen) declares a wedge only when the last resolution carried that signed beyond-bound evidence; a streak without it is logged and orders nothing.
  5. Health check after each pass (24): skipped within 120 s of a fork resolution and, unless an investigation is pending, within 30 s of the last check, and at height ≤ 10; samples 5 random connected registered peers, each asked at most once per 30 s (10 s while investigating); needs ≥ 2 answers; triggers when ≥ 60 % report a higher difficulty and ≥ 60 % are ≥ 10 blocks ahead (≥ 50 % higher difficulty while an investigation is pending); on trigger, resolves against the highest-difficulty responder, with one deeper retry when asked.

Rule activation. None. Rejections and errors. None.

Vector. computed: answers {(12,465, "D1"), (12,465, "D1"), (12,465, "D1"), (12,470, "D2")} from 4 registered peers to a stalled node: ceil(2 × 4 / 3) = 3 agree on (12,465, D1) → it syncs from one of them. A block during sync whose round opens 1,000 s ahead → a bad block, "sync block dated far ahead of its round".

Test cases · §9

5 cases · 4 valid · 1 invalid · 1 reference

Three of four registered peers agree: the stalled node syncs from one of them28-9-quorumvalid

Loading the test widget…

Two against two: no quorum28-9-no-quorumvalid

Loading the test widget…

Two answers are too few28-9-too-fewvalid

Loading the test widget…

A sync block whose round opens 1,000 s ahead28-9-far-aheadinvalidreference

A stated value: there is nothing to compute. The statement is a refusal: the exact text a compatible node answers.

result
a bad block from that peer, the pass ends
refusal
sync block dated far ahead of its round
limit_s
900
The divergent cool-down: 10, 20, 40, 80, then 120 minutes28-9-cooldownvalid

Loading the test widget…

Defects to match. None.

§9a Block-production gate

Purpose. What keeps an implementation producing when a peer claims a height it does not reach.

Inputs. The connected peers (chain_height, last_seen, registered, key); our height; now; whether the peer is in the divergent cool-down; whether the sync confirmed within the last 60 s that the peer's chain is heavier ("confirmed target").

Output and effect. hold (do not produce now), with the claimed height, the peer and a reason. Both production paths ask after the clock-skew check (§9b) and skip producing while hold is true.

How to compute it. Per peer: silent longer than 120 s, or not ahead of us → skipped; set aside by the fork resolver → ignored; an unregistered peer → ignored, at every height, the first ten blocks included (the genesis registry exists from height 0, so a peer outside it is never a sync target and never holds production). Otherwise, keyed by the peer's key (its address when none), track the first hold and the last time it was ahead (a window older than 600 s restarts). Held ≥ 3,600 s without a sync completing → produce anyway. Not a confirmed target and held ≥ 60 s → ignored (once ≥ 600 s its window resets for one more short hold). A confirmed target holds up to the 3,600 s ceiling. The verdict is the highest claim still counting; with none, production continues. Separately, a sync in progress holds production for at most 45 s.

Rule activation. None.

Rejections and errors. None.

Vector. computed: an unregistered peer at our height + 1,000 → no hold, at our height 5 as at our height 500; a registered peer at + 1,000 not confirmed → hold for 60 s, then production resumes; a confirmed heavier target → hold up to 3,600 s; a sync running → hold ≤ 45 s.

Test cases · §9a

5 cases · 5 valid

An unregistered peer 1,000 blocks ahead of height 500 does not hold production28-9a-unregisteredvalid

Loading the test widget…

The same at our height 5: no hold in the first blocks either28-9a-unregistered-earlyvalid

Loading the test widget…

A registered, unconfirmed claim holds for 60 s28-9a-unconfirmedvalid

Loading the test widget…

A confirmed heavier target holds up to 3,600 s28-9a-confirmedvalid

Loading the test widget…

A running sync holds production for at most 45 s28-9a-syncvalid

Loading the test widget…

Defects to match. None.

§9b Clock-skew production veto

Purpose. What stops an implementation whose clock is far from the fleet's from producing.

Inputs. For each peer, clock_offset = the peer's signed handshake-response timestamp minus our clock at receipt (outbound handshakes only); now; the block gap 15 s; past_bootstrap = the chain has started (now is at or after the genesis timestamp; a genesis timestamp that cannot be read counts as started).

Output and effect. skewed (do not produce), known, the median offset. While skewed the node does not produce, and a spine store refusal does not charge the feeder (25 §7).

How to compute it. Take the offsets of peers seen within 120 s with a known clock (past bootstrap: registered peers only). Fewer than 3 → known = false, production proceeds. Tolerance = 15 div 2 = 7 s. behind = offsets > +7, ahead = offsets < −7. skewed when behind × 2 > n or ahead × 2 > n. Median = the middle offset (the lower-mid average for an even count).

Rule activation. None.

Rejections and errors. None.

Vector. computed: offsets {+10, +12, +9} → behind 3, 6 > 3 → skewed, median +10; {+1000, 0, 0} → behind 1, 2 > 3 false → not skewed; {+8, 0} → 2 peers → known = false.

Test cases · §9b

4 cases · 4 valid

Offsets +10, +12, +9: skewed28-9b-skewedvalid

Loading the test widget…

Offsets +1000, 0, 0: not skewed28-9b-one-offvalid

Loading the test widget…

Two peers: the clock is not known28-9b-twovalid

Loading the test widget…

An even count takes the lower-mid average28-9b-evenvalid

Loading the test widget…

Defects to match. None.

§10 Address announcement loop

Purpose. The sender side of 27 §6 and the seed watchdog.

Inputs. The node's registry id, tip, advertised address; the seed list.

Output and effect. SendNodeAddressInfo calls; seed re-dials.

How to compute it. First after 10 s, then every 30 s: build and sign the announcement (27 §6) and send it to every connected peer (8 s each, one after another) — skipped when the node has no registry id; then the seed re-dial of §2 when fewer than 3 peers are connected.

Rule activation. None. Rejections and errors. None.

Vector. computed: over 15,360 s a registered node sends 512 announcement rounds.

Test cases · §10

1 case · 1 valid · 1 reference

Announcement rounds over 15,360 s28-10-announcementsvalidreference

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

rounds
512
period_s
30

Defects to match. None.

§11 Peer discovery loop

Purpose. The client side of 27 §5.

Inputs. The connected peers.

Output and effect. New dials.

How to compute it. First after 10 s, then every 60 s: pick uniformly at random one connected peer not asked in the last 1,800 s (per address), ask GetMorePeers (5 s); for each node returned skip our own key and known keys, stop at 100 peers in the table, skip non-public-literal addresses, else dial it (§3). Ask stamps older than 86,400 s are purged hourly.

Rule activation. None. Rejections and errors. None.

Vector. computed: a node with 10 connected peers asks each at most once per 30 minutes, so at most 10 asks per 1,800 s.

Test cases · §11

1 case · 1 valid · 1 reference

Discovery asks per 1,800 s28-11-discoveryvalidreference

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

connected
10
max_asks_per_1800_s
10

Defects to match. None beyond 27 §5.

§12 Node health monitor

Purpose. Local overload protection that changes what an implementation accepts and produces.

Inputs. Pool size, block-processing times, received transactions, the thread level (27 §16).

Output and effect. Level Normal / Warning / Critical / Emergency; the blocksmith's cap of transactions per block 500 / 300 / 200 / 100; transactions refused in Emergency ("Node in emergency mode", 27 §10); empty blocks produced in Emergency; API transaction broadcasts suspended at ≥ Critical; heartbeat timeouts forgiven at ≥ Critical (§4); exposed by /api/v1/node/health (31).

How to compute it. Every 500 ms a sample (the last 20 kept); the suggested level is the highest of: pool size ≥ 5,000 / 10,000 / 20,000 → Warning / Critical / Emergency; the average of the last 20 block-processing times ≥ 3,000 / 5,000 / 8,000 ms; received TPS (transactions since the previous sample ÷ elapsed seconds) ≥ 200 / 500 / 1,000; thread level High → Critical, Critical → Emergency. Hysteresis: a higher level needs 3 consecutive samples suggesting it, a lower one 20; after Emergency the level stays at least Critical for 180 s. The [advanced] keys do not reach this monitor.

Rule activation. None. Rejections and errors. None.

Vector. computed: 1,200 transactions received within one 500 ms sample → TPS 2,400 → Emergency suggested; after 3 such samples (1.5 s) the node stops accepting transactions and produces empty blocks; it needs 20 calmer samples and 180 s since entering Emergency to drop to Warning.

Test cases · §12

4 cases · 4 valid

A flood of 2,400 TPS: Emergency after three samples28-12-floodvalid

Loading the test widget…

Twenty calmer samples inside 180 s only reach Critical28-12-cooldownvalid

Loading the test widget…

Twenty calmer samples after 180 s drop to Warning28-12-recoveredvalid

Loading the test widget…

Nineteen calmer samples are not enough28-12-nineteenvalid

Loading the test widget…

Defects to match. None.

§13 Storage transport

Purpose. How the decentralised storage (11) reaches peers.

Inputs. The registry's active node keys; the peer table.

Output and effect. GetStoragePiece / PutStoragePiece calls (27 §14).

How to compute it. A piece is fetched from replica key K only when K is in the peer table (connected or not), through GetStoragePiece signed with this node's key; an unknown key → "replica not a connected peer"; a holder's refusal of an archive-only chunk → permission denied. Storage is on by default ([storage] enabled=false switches it off, 30). Each storage epoch's pass (holding this node's share of the archive, 26 §10b, and proving the sampled chunks) runs as soon as a peer is connected, or after a quarter of the epoch (clamped to 15 s … 2 min) when none is; archive chunks it could not fetch are retried every minute within the epoch.

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

Vector. computed: DevNet epochs are 10 blocks (150 s): a node with no peer runs its pass after min(max(150 / 4, 15), 120) = 37 s.

Test cases · §13

2 cases · 2 valid

A DevNet node without peers runs its storage pass after 37 s28-13-gracevalid

Loading the test widget…

The wait stays within 15 s and 2 minutes28-13-grace-clampedvalid

Loading the test widget…

Defects to match. None.

§14 Configuration keys of this area

node.conf [advanced], each optional, integers:

Key Default Effect
min_active_peers 3 §5 isolation, §6 ban floor
stale_peer_timeout 600 §4
stale_registered_peer_timeout 3600 §4
max_consecutive_failures 10 §5
ban_level_1 … ban_level_4 300 / 900 / 2100 / 3600 §6
offense_reset_period 86400 §6
bad_blocks_threshold 10 §6
bad_block_window 600 §6
invalid_tx_threshold 5 §6
invalid_tx_window 300 §6
validation_failure_threshold 3 §9
stray_tx_rate_limit / queued_tx_rate_limit / registry_tx_rate_limit 10 / 20 / 2000 §6 transaction rate per source per minute
stray_block_rate_limit 1 parsed; no caller
max_peer_count — parsed; no caller

Test cases · §14

1 case · 1 valid · 1 reference

The [advanced] defaults28-14-defaultsvalidreference

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

min_active_peers
3
stale_peer_timeout
600
stale_registered_peer_timeout
3600
max_consecutive_failures
10
ban_levels
300/900/2100/3600
offense_reset_period
86400
bad_blocks_threshold
10
bad_block_window
600
invalid_tx_threshold
5
invalid_tx_window
300
validation_failure_threshold
3
tx_rate_limits
stray 10 / queued 20 / registry 2000 per minute

§15 Data kept

All in memory unless said: the peer table (§1, ≤ 1,024, inbound-only entries included, at most eight unregistered entries per host); the dial request flag (§5); the pending addresses (§3); the ban entries (§6: key → banned_until, first_offense_time, offense_count, reason); the bad-block records (per key: count, window start, fork-failure count); the invalid-transaction records (per key, 300 s window); the proven-lie counts (per key, for the session); the invalid-block records (per charge identity, ≤ 4,096); the transaction rate windows (per source, ≤ 4,096); the validation-failure records (per height and identity, §9); the known-data sets (§7); the divergent cool-downs (per key); the production-gate claims (§9a); the health samples (§12). Nothing of this is consensus.

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