On this page
- §0 The area in one paragraph
- §1 The peer record and the peer table
- §2 Bootstrap: the advertised address, seeds and the start-up gate
- §3 Outbound connection and the pending list
- §4 Heartbeat loop and stale cleanup
- §5 Failure accounting, backoff, disconnection and recovery
- §6 Charging, rate limits and the blacklist
- §7 Known-data tracking
- §8 Propagation: what goes to whom, and when
- §9 Sync drivers and the health check
- §9a Block-production gate
- §9b Clock-skew production veto
- §10 Address announcement loop
- §11 Peer discovery loop
- §12 Node health monitor
- §13 Storage transport
- §14 Configuration keys of this area
- §15 Data kept
28 — P2P behaviour: peer table, failure accounting, charging, blacklists, propagation, sync drivers, health
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.
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:
- 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 oldestlast_seen— and when none qualifies the add fails ("Peer table full"). A new record starts withlast_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. - 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, clearschain_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). connectedis 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 whenconnectedis true and it is not inside a retry backoff (next_retry_at = 0or≤ now). An inbound-only entry is therefore never a target of anything this node sends.chain_verifiedis 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 setshandshake_verifiedand clearsobserved_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_verifiedis set by that and by an accepted inbound handshake (with or without a routable address). Each reader takes the flag it means:handshake_verifiedfor the caller check (27§1a,FAILED_PRECONDITION "no handshake for this chain"), theRequestBlockTransactionsgate (27§10), the eviction tier (rule 1) and the start-up prune below;chain_verifiedfor the recovery loop's budget of never-dialled entries (§5), theGetMorePeersanswer (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 theRequestBlockTransactionspush (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.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.last_seenis 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).- 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 ago
Loading the test widget…
A full table of connected peers refuses a new key
Loading the test widget…
A ninth unregistered key from one host
Loading the test widget…
A chain-verified entry whose handshake arrives from another host stays; that address is dialled
Loading the test widget…
The key answering this node's dial at the new address moves the entry
Loading the test widget…
After three failed dials of its address the handshake moves the entry at once
Loading the test widget…
The moved entry is chain-verified again once this node's dial reaches the key there
Loading the test widget…
Between an inbound-only key seen 2 h ago and a gossiped one seen now, the gossiped one goes
Loading the test widget…
Within one tier and one count per host the entry seen longest ago goes; a registered one never
Loading the test widget…
A table below 1,024 entries takes the key without eviction
Loading the test widget…
A gossiped key handshaking from behind NAT at a host holding eight others
Loading the test widget…
This node's dial of 203.0.113.7:8001 answered by that key
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.
- The public IP:
public_ipset (an IPv4 address, no port) → used as stated, nothing looked up;discover_public_ip = falseand nopublic_ip→ nothing looked up,advertise_addressused as written; otherwise looked up: external IP-echo services over HTTPS first (3 s timeouts), then the seed nodes' HTTP APIGET /api/v1/node/public-ipon each public seed host atseed_api_port, with headersX-Node-Public-Key(hex),X-Timestamp(unix s) andX-Signature= hex Ed25519 over the ASCII string"GET:/api/v1/node/public-ip:<timestamp>:"; the reply's JSONipis used. - The advertised address is filled from the public IP when
advertise_addressis empty, starts withauto(any case), equalslisten_address, or has a private / loopback host. Withrequire_bidirectionalthe 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. - 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. - 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 up
Loading the test widget…
A public_ip with a port is a configuration error
Loading the test widget…
The start-up sync gate
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 TCP
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 L
Loading the test widget…
Nothing is stored for the key that answered
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:
- For every connected peer set
registeredfrom the registry. - Priority set = this node's priority peers of
23at scramble height tip − 1 (max_assigned_peers: DevNet 8, TestNet and the mainnet template 12). - Targets: every connected priority peer; every other connected registered peer on cycles where
cycle mod 3 = 0; never an unregistered non-priority peer. - 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). - Stale cleanup: every peer with
last_seen > 0older 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 cycle
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 others
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.
- 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. - What counts: heartbeats (§4);
GetCumulativeDifficultyin sync (timeouts forgiven when seen ≤ 90 s ago); block broadcast and candidate broadcast (non-deadline errors); API transaction broadcast (errors other thanDEADLINE_EXCEEDEDandRESOURCE_EXHAUSTED); a failed dial of a known key (§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_failureis 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 heartbeat
Loading the test widget…
An unregistered peer's backoff stops at 120 s
Loading the test widget…
Re-dial of a disconnected peer
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):
- 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 whilerequire_signed_receipt_requestsis off — when the peer table holds a chain-verified entry for that key whose host is the caller's host. - 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). - 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 againstaddr:+ 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.
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 key
Loading the test widget…
The same block in a call signed by K itself
Loading the test widget…
The same sender bound by a chain-verified peer entry while the switch is off
Loading the test widget…
A registered sender whose receipt-request signature verifies
Loading the test widget…
A bound but unregistered sender is charged by address
Loading the test widget…
An unregistered peer banned four times within 24 h
Loading the test widget…
Nine bad blocks do not ban
Loading the test widget…
A registered peer sending 50 blocks refused as "InvalidSignature"
Loading the test widget…
A registered peer sending 50 blocks refused as "Invalid block signature"
Loading the test widget…
A registered peer's bad block reported from sync is never recorded
Loading the test widget…
No ban while it would leave 3 or fewer active peers
Loading the test widget…
Fork-related refusals count every second one
Loading the test widget…
A timing refusal is not recorded
Loading the test widget…
Five unsigned calls from one host within 60 s throttle the host's blocks
Loading the test widget…
A registered relay may send 2,000 transactions a minute
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 skipped
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.
- 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 of27§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. - 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. - 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). - 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. - 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. - 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-out
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.
- 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).
- 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). - 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 leastceil(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 recordedchain_heightis 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 of27§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. - 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. - 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 them
Loading the test widget…
Two against two: no quorum
Loading the test widget…
Two answers are too few
Loading the test widget…
A sync block whose round opens 1,000 s ahead
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 minutes
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 production
Loading the test widget…
The same at our height 5: no hold in the first blocks either
Loading the test widget…
A registered, unconfirmed claim holds for 60 s
Loading the test widget…
A confirmed heavier target holds up to 3,600 s
Loading the test widget…
A running sync holds production for at most 45 s
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: skewed
Loading the test widget…
Offsets +1000, 0, 0: not skewed
Loading the test widget…
Two peers: the clock is not known
Loading the test widget…
An even count takes the lower-mid average
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 s
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 s
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 samples
Loading the test widget…
Twenty calmer samples inside 180 s only reach Critical
Loading the test widget…
Twenty calmer samples after 180 s drop to Warning
Loading the test widget…
Nineteen calmer samples are not enough
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 s
Loading the test widget…
The wait stays within 15 s and 2 minutes
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] defaults
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.