On this page
- §0 The area in one paragraph
- §1 Command line, process and signals
- §2 The configuration file
- §3 Key material and identity
- §4 Start-up sequence
- §4a The clock
- §4b The spine pin
- §4c The node's signed P2P calls, from the operator's view
- §5 The daemon loop
- §6 What persists across restarts
- §7 Timers
- §8 Roles and supervisors
- §8a The gateway identity file
- §9 Self-update and the wedge rebuild
- §9a Relaunching a chain
- §10 Consensus and local
30 — Node operation: configuration, key material, start-up, persistence, timers, roles, self-update
Out of scope the HTTP API itself (31); the peer loops the node runs (28) and the wire form of the signed P2P call (27 §1a); the consensus parameters a genesis carries (06, 32); the archival API program and the bridge keeper (separate programs; only their supervision is here); the gateway and relay roles of the installer (not the node), except the gateway identity file (§8a)
§0 The area in one paragraph
A ZooBC node is one process, started with a configuration file, that owns one SQLite database and
listens on three or four TCP ports: 8001 for peers (27), 8080 for the HTTP API (31), 8545 for the
embedded Ethereum-style RPC adapter, and a Bitcoin-style adapter only when the operator enables it.
Everything that makes it this node on this chain is in the configuration (an INI file: an Ed25519
private key, the matching public key and an owner account address are mandatory) and in the database,
which must already contain block 0: the node never builds a genesis itself, and the chain identity is
the hash of that block. Start-up is a fixed sequence of initialisers, any failure of which exits with
status 1, followed by two child-process supervisors (the archival API and the bridge keeper) and a
daemon loop that drives block production. What survives a restart is the database, the snapshot and
storage-piece directories, the logs and a handful of marker files; everything else is rebuilt. A
wedged node rebuilds itself (auto_resync, on by default): in place from a spine-attested snapshot
first, otherwise by writing a resync marker that the next start honours by setting the chain aside and
re-syncing from genesis through the spine. Every P2P call the node makes is signed with its node key for
the node it calls (§4c). A self-updater outside the node follows the on-chain release registry; a
relaunch replaces the chain itself (§9a). None of this is consensus; it is what an implementation must
do to run as a member of the fleet.
§1 Command line, process and signals
Purpose. How an implementation is invoked and stopped.
Inputs. Arguments; SIGINT / SIGTERM.
Output and effect. The daemon, or a self-test, or nothing.
How to compute it. --start [path] → the daemon with path (default ~/.zoobc/node.conf); -l /
--log [file] turns file logging on (default file zoobc.log); --log-level <level> with
error|warn|warning|info|debug|trace|none (unknown → info); --help. No argument → a self-test that
signs, hashes and builds an in-memory chain, exit 0. --peers, --status, --height print nothing and
exit 0. Before the daemon starts, [logging] is applied unless the command line set it. SIGINT /
SIGTERM end the daemon loop; shutdown then stops, in order: the storage maintenance, the snapshot
scheduler, the spine blocksmith, the staging pool, the network node, the UPnP maintenance, the API server
(10 s grace), the health monitor, the load sampler, and closes the database after a WAL checkpoint; the
supervised children get SIGTERM, then SIGKILL. Exit codes: 0 normal stop; 1 a start-up error; 3 the spine
alarm (25 §7).
Rule activation. None. Rejections and errors. An unknown argument before any command → exit 1;
--log-level without a value → exit 1.
Vector. computed: --start /etc/zoobc/node.conf --log-level debug starts the daemon with debug
logging; --log-level alone exits 1.
Test cases · §1
1 case · 1 valid · 1 reference
The command line
A stated value: there is nothing to compute. A compatible node shows the same value.
- start
--start /etc/zoobc/node.conf --log-level debug starts the daemon with debug logging- log_level_alone
exit 1- no_argument
a self-test, exit 0- exit_codes
0 normal stop, 1 start-up error, 3 spine alarm- default_config
~/.zoobc/node.conf
Defects to match. None.
§2 The configuration file
Purpose. Every key an implementation reads, with its default and effect.
Inputs. An INI file: [section] lines, key = value lines, # or ; comments, whitespace trimmed; a
key = value before any section is an error; a repeated key keeps the last value; a leading ~ in a path
expands to $HOME. Booleans accept true/1/yes/y/on (any case) in [node], [network], [storage],
[archival], [bridge], but only true/1/yes (exact case) in [api] and [rpc].
Output and effect. The node's configuration; a load error stops the node with exit 1.
How to compute it.
[node] (mandatory):
| Key | Default | Effect |
|---|---|---|
listen_address |
0.0.0.0:8001 |
P2P bind address; its port is the port of every advertised address |
advertise_address |
= listen_address |
what peers are told (§4 step 1, 28 §2) |
node_private_key (alias blocksmith_private_key) |
required | hex: a 32-byte seed or a 64-byte secret key (§3) |
node_public_key (alias blocksmith_public_key) |
required | ZNK_… address or 32-byte hex; must match the private key |
node_owner_address (aliases owner_account_address, owner_account) |
required | ZBC_… address: the account allowed owner commands and whose datasets the updater reads |
bridge_signers |
empty | comma list of chain:address:private_key triples, passed to the bridge keeper |
keep_all_history |
false | keep pruned history (22 §14) |
auto_resync |
true | a wedged node rebuilds itself (§5, §9) |
require_signed_receipt_requests |
false | true: a block or transaction push that carries no receipt-request signature earns no receipt, and a sender is bound to its key only by that signature (27 §8, 28 §6); false: such a push is still answered with a receipt and a chain-verified peer entry (this node's own dial reached the key) at the caller's host also binds the key. Without the line the node's default is false. The installer writes true into a new node.conf on every chain and adds require_signed_receipt_requests = true under [node] to a kept node.conf that does not name the key (an explicit value is the operator's and is kept); the relaunch's staging step sets it to true on every node (§9a), so both relaunched chains refuse unsigned receipt requests from block 0. Every node of 0.6.1 signs its receipt requests from block 0 whatever the setting |
[network]: seed_peers (comma list, empty), seed_api_port (8080), p2p_enabled (true; false = no
network node), upnp_enabled (true), require_bidirectional (false: demands a routable advertised address
on the listen port and a UPnP mapping or a verified public IP, else the node refuses to start),
public_ip (empty: an IPv4 address without a port, advertised as stated, nothing looked up),
discover_public_ip (true: false = never look the public IP up; advertise_address is used as written).
[api]: api_enabled (true), api_host (0.0.0.0), api_port (8080), trusted_proxies (127.0.0.0/8, ::1; none = empty), write_requests_per_minute (300), read_requests_per_minute (0 = unlimited),
auth_failure_lockout_threshold (20), auth_failure_lockout_seconds (300) — the four limits integers
0…1,000,000 — and registry_allow_private_hosts (false: admits loopback / private URLs in gateway and
archival registrations, for private chains).
[rpc]: eth_rpc_enabled (true), eth_rpc_host (127.0.0.1), eth_rpc_port (8545), eth_rpc_chain_id
(0 = derived: 0x0883 << 16 | genesis[0] << 8 | genesis[1], with one retired TestNet genesis
F2F8B91BBE3437F3… (the whole 32-byte hash) mapping to 883), btc_rpc_enabled (false), btc_rpc_host (127.0.0.1),
btc_rpc_port (8332), btc_rpc_user / btc_rpc_password (both required when enabled; the pair zoobc /
zoobc is refused).
[database]: db_path (~/.zoobc/node.db), db_backend (sqlite; anything else stops the node); the
mysql_* keys are parsed and unused.
[storage]: enabled (true: holding this node's share of the snapshot archive is a duty of the registered node,
26 §10b; false = the node holds, proves and earns nothing), replication (5), epoch_blocks (240);
the chain's storage_replication / storage_proof_epoch_blocks consensus parameters override the last two.
[archival]: archival_node (alias enabled; false), public_api_url, public_api_hostname (alias
public_hostname), archive_min_disk_gb (20), archive_binary (empty = automatic). Other keys of this
section are read by the archival program, not the node.
[bridge]: enabled (true), min_disk_gb (20), min_ram_mb (512), config_path
(~/.zoobc/bridge.json), binary (empty = automatic).
[logging]: log_path (~/.zoobc/logs/node.log), log_level (info), max_log_file_size (50 MiB; a
value ≤ 10,000 is MiB, a larger one bytes, 0 = never rotate).
[advanced]: the P2P keys of 28 §14 plus max_mempool_size (25,000), max_pending_txs_per_sender (50),
min_mempool_age_seconds (10), read by the pool (04); the rest are parsed and unused.
[update]: read by the self-updater only (§9).
[notifications] (optional, the operator's claim e-mail): notify_email (comma list of addresses;
empty = off), smtp_host, smtp_port (25; 1…65,535), smtp_tls (off, the default, starttls or
tls), smtp_user and smtp_password (a user set = SMTP AUTH PLAIN), smtp_from. With
notify_email set, smtp_host and smtp_from are required. When enabled, a ClaimNodeRegistration
(09 §6) on this node's key or on a node of its owner account queues one mail when it is announced
(subject "ZooBC node claim announced", text "Claim on your node <key hex> announced at block <h>. It executes at block <due> unless you remove the node with your owner key.") and one when it executes
("ZooBC node claim executed", "Claim on your node <key hex> executed at block <h>: <outcome>"), in
the local table node_notification_outbox (§6). A queued mail is sent once its announcing block is on
the chain (abandoned when that block never appears within 600 s, as for a block only validated; skipped
when the block's own timestamp is more than 24 h from now) and retried after 1, 2, 4 … up to 60 s for one
hour.
The secrets file guard: when node_private_key or smtp_password is set the file must not be group- or
world-accessible (mode & 0o077 = 0); a file this process owns is set to 0600 with one log line; one it
cannot change stops the node: "<path> is readable by other users (mode NNNN) and holds secret credentials, and this process cannot fix it (not the owner); refusing to start. Fix: chmod 600 <path>".
Rule activation. None.
Rejections and errors. Missing or malformed key material, a missing owner address, a non-integer port
or limit, an unsupported backend, require_bidirectional with P2P off, "Invalid public_ip '<x>' (an IPv4 address without a port, e.g. 203.0.113.7)", the mode guard, "[notifications] with notify_email requires smtp_host and smtp_from", "notifications smtp_tls must be starttls, tls or off", "notifications smtp_port must be between 1 and 65535": exit 1 with the message.
Vector. computed. INPUT: a node of a TestNet built from the shipped genesis file on its own
timestamp (genesis hash 3A2897E7…863D, 06 §3) with eth_rpc_chain_id = 0. EXPECTED OUTPUT: chain id
0x0883 << 16 | 0x3A << 8 | 0x28 = 0x08833A28 = 142,817,832; the shipped DevNet file (A37B1692…99F8)
→ 0x0883A37B = 142,844,795 (the relaunch sets the genesis timestamp at launch and so changes both: the
chain id a live chain answers follows the genesis hash it announces on launch day, §9a). INPUT: public_ip = 203.0.113.7:8001 → exit 1 with the Invalid public_ip message. INPUT: [api] api_enabled = on →
false (on is not accepted in [api]). INPUT: max_log_file_size = 10 → 10 MiB; = 20000 → 20,000 bytes.
INPUT: [notifications] with notify_email = [email protected] and no smtp_from → exit 1, "[notifications] with notify_email requires smtp_host and smtp_from". INPUT: a new node.conf written by the installer for
the release v0.6.1-testnet or v0.6.1-devnet → require_signed_receipt_requests = true; a kept node.conf
without the key → the installer adds true; a kept one with require_signed_receipt_requests = false → kept
as false by the installer, set to true by the relaunch's staging step (§9a); a node.conf without the key
read by the node → false.
Test cases · §2
25 cases · 17 valid · 8 invalid · 2 reference
The chain id of a TestNet built from the shipped genesis file
Loading the test widget…
The chain id of a DevNet built from the shipped genesis file
Loading the test widget…
The retired TestNet genesis keeps 883
Loading the test widget…
A genesis sharing only the retired genesis's first eight bytes derives its own id
Loading the test widget…
public_ip with a port stops the node
Loading the test widget…
public_ip stated as an IPv4 address
Loading the test widget…
api_enabled = on is false in [api]
Loading the test widget…
api_enabled = True is false in [api] (exact spelling only)
Loading the test widget…
auto_resync = Off and upnp_enabled = ON read in any case outside [api] and [rpc]
Loading the test widget…
max_log_file_size = 10 is 10 MiB
Loading the test widget…
max_log_file_size = 20000 is 20,000 bytes
Loading the test widget…
The defaults of the keys read here
Loading the test widget…
[notifications] with notify_email and no smtp_from stops the node
Loading the test widget…
smtp_tls must be starttls, tls or off
Loading the test widget…
smtp_port 0 stops the node
Loading the test widget…
A complete [notifications] section
Loading the test widget…
A node.conf without require_signed_receipt_requests reads false
Loading the test widget…
require_signed_receipt_requests = true under [node]
Loading the test widget…
What the installer and the relaunch write for require_signed_receipt_requests
A stated value: there is nothing to compute. A compatible node shows the same value.
- new_node_conf
true, for the release v0.6.1-testnet or v0.6.1-devnet- kept_without_the_key
the installer adds true- kept_with_false
kept false by the installer, set to true by the relaunch's staging step- read_without_the_key
false
A key = value before any section
Loading the test widget…
A configuration without an owner address
Loading the test widget…
The Bitcoin-style adapter refuses the pair zoobc / zoobc
Loading the test widget…
The Bitcoin-style adapter needs both user and password
Loading the test widget…
Operator-chosen credentials are usable
Loading the test widget…
The default ports and limits
A stated value: there is nothing to compute. A compatible node shows the same value.
- p2p
8001- api
8080- eth_rpc
8545 (127.0.0.1)- btc_rpc
8332, off- write_requests_per_minute
300- read_requests_per_minute
0 (unlimited)- auth_failure_lockout_threshold
20- auth_failure_lockout_seconds
300- max_mempool_size
25000- max_pending_txs_per_sender
50- min_mempool_age_seconds
10- storage_replication
5- storage_epoch_blocks
240- archive_min_disk_gb
20- bridge_min_disk_gb
20- bridge_min_ram_mb
512- max_log_file_size
50 MiB
Defects to match. None.
§3 Key material and identity
Purpose. What an implementation signs with and how it is named.
Inputs. node_private_key, node_public_key, node_owner_address.
Output and effect. The Ed25519 key pair for every P2P call (§4c, 27 §1a), handshakes, heartbeats,
announcements, proof of origin and receipt requests (27), receipts (23), block signatures (05, 20), spine signatures and non-signing statements
(25), attestations and storage proofs; the ZNK_ identity; the node id.
How to compute it.
- A 32-byte hex value is a seed: Ed25519 key generation from the seed gives the 64-byte secret key (seed ‖ public key) and the public key. A 64-byte value is the secret key; the public key is bytes 32–63. Any other length is refused.
node_public_key(ZNK_text,01, or 32-byte hex) must equal the derived public key.- Identity string =
ZNK_encoding of the public key. Node id = the little-endian u64 of the first 8 bytes of the public key with bit 63 cleared (the registry's derivation,09). - A registered node may move to a new key (rule
node_key_rotation,09): the registration transaction names the old and the new key and is proven by the new key; the change takes effect 120 blocks after the block that includes it; the node must then be restarted on the new key. - At start the node reads the active registry; this key's row there makes it a registered node (it may
produce); no row makes it an observer that syncs and relays until a registration admits it (
09). The node never writes itself into the registry: the genesis builds the genesis registered nodes, and an empty registry only means observer mode.
Rule activation. node_key_rotation (active from height 0 on every chain).
Rejections and errors. As in §2; a registry that cannot be read at start stops the node ("Cannot read the node registry at startup: <reason>", exit 1).
Vector. computed. INPUT: public key EB89F581920CAC9343663A33911D76CEF5C89390F25865651D902792B881AD65.
EXPECTED OUTPUT: node id = LE u64 of EB89F581920CAC93 = 0x93AC0C9281F589EB, bit 63 cleared →
0x13AC0C9281F589EB = 1,417,521,806,099,974,635. INPUT: the same key on a database whose registry has no row
for it → observer mode, nothing written to the registry. INVALID: a registry table that cannot be read →
exit 1, "Cannot read the node registry at startup: …".
Test cases · §3
10 cases · 6 valid · 4 invalid · 3 reference
The node id of a public TestNet node key
Loading the test widget…
A 32-byte private key is a seed: its public key and node id
Loading the test widget…
A 64-byte private key: the public key is its last 32 bytes
Loading the test widget…
node_public_key given as a ZNK_ address
Loading the test widget…
A ZNK_ text whose checksum is that of the ZBC_ form is refused
Loading the test widget…
A 33-byte private key is refused
Loading the test widget…
A public key that does not match the private key is refused
Loading the test widget…
A key rotation takes effect 120 blocks after its block
A stated value: there is nothing to compute. A compatible node shows the same value.
- delay_blocks
120
A key with no row in the registry
A stated value: there is nothing to compute. A compatible node shows the same value.
- value
observer mode: the node syncs and relays; nothing is written to the registry
A registry table that cannot be read stops the start
A stated value: there is nothing to compute. The statement is a refusal: the exact text a compatible node answers.
- exit
1- refusal
Cannot read the node registry at startup: <reason>
Defects to match. None.
§4 Start-up sequence
Purpose. The order in which an implementation becomes a peer, a validator and a blocksmith, and what stops it.
Inputs. The configuration, the database, the network.
Output and effect. A running node, or exit status 1 with one error line.
How to compute it.
- Configuration: load (§2), the mode guard, the load sampler (
27§16), the health monitor (28§12); the P2P port fromlisten_address(8001 when unparsable). With P2P on, the public IP (28§2):public_ipas stated; or none looked up (discover_public_ip = false); or looked up from external IP-echo services (HTTPS then HTTP, 3 s each) and, failing a public IPv4, from the seeds'GET /api/v1/node/public-ip. A configured public host different from the discovered one asks the terminal (keep / use the discovered one; a non-interactive start uses the discovered one); a private, empty,autoor listen-equal value takes the discovered one. - Database: open the SQLite file (one connection for the chain, one for the pool and staging), a WAL checkpoint.
- Chain: create the tables (
07); read block 0 — missing or with a hash not 32 bytes →"Cannot read the genesis block hash; the chain identity is unknown", exit 1; the chain identity = that hash. - Consensus: load and validate the consensus parameters (
06); load the rule heights and off-heights (29§2); rebuild the readiness gate from the stored decision rows (29§4b step 9; a refusal there stops the node); a consensus parameter that is present but not an integer stops the node; the record check (29§4c): any disagreement stops the node. - Registry and pools: the registry; the spine chain, the spine blocksmith and fast sync when
spine_enabled; the pool (caps from[advanced]), the staging pool; the registration status of this key (refreshed every 5 s; §3 step 5: a registry that cannot be read stops the node, no row means observer mode). - Receipts and topology (
23). - Block services: validator, blocksmith, the snapshot scheduler (when the spine exists and
main_snapshot_interval > 0,26), the candidate pool. - Spine guards: the finalized height wired to the spine (
25§9); the release's spine pin (§4b); the deferred spine checks run once (25§7) — a spine that names another main chain block than this node's is the alarm: withauto_resyncon the resync marker is written; the node stops. - P2P: UPnP (a 3,600 s mapping of the P2P port, renewed every 1,200 s) when enabled; the
require_bidirectionalchecks; the network node (28), which signs every call it makes (§4c), withrequire_signed_receipt_requests; the storage service and its maintenance (11,26§10b); the fast-sync hooks; the fork resolver's snapshot recovery and spine block source (24,26); the duty relay (28§8). - API (
31): five tables must exist (main_block,node_registry,participation_score,account_balance,account_ledger); the API server; a gateway-liveness pass every 60 s (entries older than 3,600 s dropped); a pool-expiry pass every 300 s (a transaction leaves at its own stated expiry,04); the Ethereum adapter (forwards to the API on loopback) and the Bitcoin adapter when enabled. - The bridge supervisor, the archival supervisor (§8), the daemon loop (§5).
Rule activation. None. Rejections and errors. Each step's error ends the process with status 1.
Vector. computed: a database without block 0 → exit 1, "Cannot read the genesis block hash; the chain identity is unknown".
Test cases · §4
2 cases · 2 valid · 2 reference
A database without block 0
A stated value: there is nothing to compute. A compatible node shows the same value.
- exit
1- message
Cannot read the genesis block hash; the chain identity is unknown
The UPnP mapping
A stated value: there is nothing to compute. A compatible node shows the same value.
- lease_seconds
3600- renew_seconds
1200
Defects to match. None.
§4a The clock
Purpose. The single "now" every time comparison reads.
Inputs. The system clock.
Output and effect. Seconds since the epoch (UTC). Every consensus comparison (the acceptance gate,
the validator's future bound, the selection windows, the turn timing, the handshake window) reads it.
The node requires NTP: a clock off by more than 7 s against most peers stops production (28 §9b), more
than 600 s fails every handshake (27 §3).
How to compute it. The system clock in whole seconds.
Rule activation. None. Rejections and errors. None.
Vector. computed: 2026-11-04 00:00:00 UTC = 1,793,750,400; 2026-11-09 08:00:00 UTC = 1,794,211,200
(the stand-in timestamp of 27).
Test cases · §4a
3 cases · 3 valid · 1 reference
2026-11-04 00:00:00 UTC
Loading the test widget…
The stand-in timestamp 1,794,211,200 is 2026-11-09 08:00:00 UTC
Loading the test widget…
The clock bounds
A stated value: there is nothing to compute. A compatible node shows the same value.
- production_stops_above_seconds
7- handshake_fails_above_seconds
600
Defects to match. None.
§4b The spine pin
Purpose. A release's pinned record of a known spine block, so a node started on a forked or tampered spine history does not build on it.
Inputs. <data dir>/spine-pin.txt: one line "<height> <64 hex characters>"; the local spine chain.
Output and effect. With a well-formed file the node pins (height, hash) (25 §9) and compares its own
stored spine block at that height. A conflict: with auto_resync on, the node writes the resync marker
naming the conflict and stops, so the next start rebuilds (§9); if a marker is already there and the
conflict persists, or with auto_resync off, it exits 1 with "spine pin: <reason> … (<path>)". A
line whose hash is 64 characters that are not all hex → a warning, no pin; any other shape (a hash of
another length, no hash, no height) → no pin, nothing logged. No file → no pin. A node holding the pinned block never rolls its
spine below it (25 §8); a spine block at the pinned height with another hash is refused at storage.
The pin guards that one height only.
How to compute it. Parse the height and 64 hex characters into 32 bytes; any other shape → no pin.
Rule activation. None.
Rejections and errors. As stated.
Vector. computed: spine-pin.txt = 0 7CD929C4D52D9C9455ED179D24A65F90ECBF3D1A3E1214A19611635791B3545C
(the spine genesis block of the shipped TestNet files, 06 §7) on a node built from those files as
shipped → pinned, no conflict. The same line on a node whose genesis was rebuilt on another timestamp
without the pin being re-derived (its spine block 0 has another hash; the relaunch and a timestamped
install re-derive it, §9a) → the conflict below. The same line with the last
character changed on a node built from the shipped files →
with auto_resync on, the marker is written and the node stops; off → exit 1 "spine pin: …". The line
12 7CD9 → no pin, nothing logged; 12 followed by 64 characters that are not hex → warning, no pin.
Test cases · §4b
7 cases · 7 valid
The TestNet spine genesis pin on a TestNet node
Loading the test widget…
The shipped pin on a node whose genesis was rebuilt on another timestamp without the pin re-derived
Loading the test widget…
The pin with its last character changed, auto_resync on: the marker is written, the node stops
Loading the test widget…
The same with auto_resync off: the node exits
Loading the test widget…
The same with a marker already there: the node exits, no new marker
Loading the test widget…
The line 12 7CD9: no pin
Loading the test widget…
64 characters that are not hex: a warning, no pin
Loading the test widget…
Defects to match. None.
§4c The node's signed P2P calls, from the operator's view
Purpose. What an operator must provide so that the node can speak to its peers at all, now that every
P2P call is signed by the caller's node key for the node it calls (27 §1a), and what the node's log
says when a peer refuses it.
Inputs. node_private_key / node_public_key (§3); the system clock (§4a); advertise_address,
public_ip and the UPnP mapping (§2, 28 §2); the host the node's connections come from;
require_signed_receipt_requests (§2).
Output and effect. Calls that every peer accepts, or refusals in this node's log and in the peer's.
How to compute it.
- The key signs every call. Each call carries the node key, a stamp, the request digest, an 8-byte
nonce, the key of the node called and the signature (
27§1a). A node that cannot sign (no private key) logs once"This node cannot sign its P2P call <Method> (no node key, or a receiver key that is not 32 bytes): every peer refuses an unsigned call"and is refused by every peer. There is no unsigned mode and no setting that turns signing off. - The clock. A stamp more than 600 s from the peer's clock is refused, without a strike:
"<Method>: signed request timestamp outside the 600 s window; check NTP"; the handshake says how far off this clock is ("handshake timestamp out of window: your clock is +N s from ours (limit 600 s); check NTP"). Production stops already at 7 s against most peers (28§9b). The node needs NTP. - The handshake first. Every call but the handshake needs a same-chain handshake with the peer in
either direction (
"no handshake for this chain"); the recovery loop handshakes again when a peer has forgotten this node (a stale entry,28§4). - Refusals a peer logs (
"<Method> from <host> refused: <why>", throttled): an unsigned or malformed call, a signature that does not verify, a call made to another node, a digest that is not the body's, a header served before. Each counts one invalid block against the caller's host; five in 60 s throttle that host's blocks (28§6). The same refusal reaches the caller asUNAUTHENTICATED "<Method>: <why>". - Hosts. A host is the IPv4 address, or for IPv6 the /64 (
2001:db8:1:2::/64), an IPv4 address mapped into IPv6 counting as the IPv4 address. A peer keeps at most eight unregistered nodes per host ("Too many unregistered peers from host <host>": the handshake is refused and nothing is stored); registered nodes are not capped. Several nodes behind one address each have their own budgets (charged as key at host), under per-host ceilings of eight callers' worth. - A node behind NAT. A node whose advertised address is empty,
0.0.0.0…,::…,127.0.0.1…,localhost…or carries no usable port claims no inbound address: each peer keeps an entry for its key with no address (handshake-verified, never chain-verified), never dials it, never passes it on and never pushes to it; a peer that already learned the key from gossip admits it the same way and keeps the gossiped address unverified. It syncs, sends transactions and completes blocks by pulling them whole. Its entry goes stale like any other and it handshakes again. - A moved address. A peer trusts the address of an entry (dials it on its own, passes it on) only once its own dial reaches this node's key there. After an operator moves a node to a new public address the peers dial the new address when its first handshake arrives from there, and the entry moves when this key answers that dial (or at once when the old address has failed three consecutive dials, trusted only once this peer's own dial then reaches the key there). A dial the peer's per-host cap cannot place (eight unregistered entries already at the new host) verifies nothing: the entry keeps its old address.
- Receipts. Every 0.6.1 node signs its receipt requests whatever
require_signed_receipt_requestssays; the setting only decides whether this node still answers an unsigned one (§2).
Rule activation. None (P2P policy; both chains relaunch on 0.6.1 and nothing but a node speaks the protocol).
Rejections and errors. As listed; none ends the process.
Vector. computed. INPUT: a node whose clock is 700 s ahead. EXPECTED OUTPUT: every call it makes is
refused UNAUTHENTICATED "<Method>: signed request timestamp outside the 600 s window; check NTP" and its
handshakes are answered "handshake timestamp out of window: your clock is +700 s from ours (limit 600 s); check NTP". INPUT: nine unregistered nodes behind 203.0.113.7 handshake with one peer → the ninth is
answered "Too many unregistered peers from host 203.0.113.7". INPUT: two unregistered nodes at
2001:db8:1:2:3:4:5:6 and 2001:db8:1:2:ffff::1 → one host, 2001:db8:1:2::/64. INPUT: a node with
advertise_address = 0.0.0.0:8001 behind NAT → an entry with no address at each peer; it syncs; no peer
dials it.
Test cases · §4c
5 cases · 4 valid · 1 invalid
A node whose clock is 700 s ahead: its calls and its handshakes are refused
Loading the test widget…
A clock 599 s behind is still inside the window
Loading the test widget…
Nine unregistered nodes behind 203.0.113.7 handshake with one peer: the ninth is refused
Loading the test widget…
Two unregistered nodes in one IPv6 /64 count against one host
Loading the test widget…
A node advertising 0.0.0.0:8001 behind NAT gets an entry with no address
Loading the test widget…
Defects to match. None beyond 28 §1 (an entry with no address goes stale between handshakes).
§5 The daemon loop
Purpose. What drives production and selection, and the wedge policy.
Inputs. The registration flag, the candidate pool, peers' heights, the rule bundles (29 §4b).
Output and effect. Blocks pushed (21), candidates broadcast (28 §8), the resync marker, the
production halt.
How to compute it.
- The start-up sync gate (
28§2) first. - Every 10 s the deferred spine checks (
25§7); the alarm: withauto_resyncon the resync marker is written; the node stops with exit code 3. - Every 5,760 blocks while a newer release is registered on chain than the one running, a warning naming
the version, the blocksmiths already running it, the blocksmiths needed (two thirds of the counted
registered nodes)
and the earliest block its rules could switch on;
/node/infonewer_releasereports the same (31). - Selection, every 1 s: with
auto_resyncon, a non-empty wedge reason (24) is written to<db dir>/RESYNC_REQUIREDand the node stops; skipped while syncing; when not registered, every 5 s ask whether this key is a resume candidate (09) and otherwise skip; take the chain lock (30 s wait); skip when a peer seen within 120 s is ahead (the production gate,28§9a) or this node's clock is skewed (28§9b); before the genesis time nothing is built; a node whose own bundle id is below a bundle decided for the next height, an observation bundle of a newer registered release included, does not produce (one fatal line per height naming the release to install;GET /api/v1/blockchain/rulesproduction_halt,29§4b step 10); when the selection window for tip + 1 has passed (20), push the best candidate (21); on success batch receipts, update the topology, clear the pool to that height and, when registered, pre-generate and broadcast the next candidate; on failure remove the candidate and, when the failure is deterministic, evict the offending transaction from the pool. - Main loop, every 1 s: skip while syncing; every 5 s refresh the registration flag; every 10 s when registered, pre-generate a candidate for tip + 1 if none exists, or sync when a peer seen within 120 s is ahead.
- The wedge: the fork resolver (
24) first rebuilds a wedged node in place from a spine-attested snapshot (26§7); the resync marker is the fallback. A wedge reason exists only with the fork resolver's beyond-bound verdict (24§3: beyond the rollback limit, the spine's newest checkpoint above the split names a block this node holds differently, or the branch, fetched and validated here, is heavier on this node's own registry). A separate streak detector (10 consecutive failed fork resolutions, against at least 2 distinct peers, over at least 1,800 s, the height frozen) never sets a wedge reason on its own: without that evidence it only logs"Wedge detector streak (log only, no signed beyond-bound evidence): <reason>"; with it the reason is set once ("CHAIN WEDGED: <reason>") and cleared by any later successful resolution. The rebuild itself runs at most once per 86,400 s (§9).
Rule activation. The readiness gate (29 §4b) for the production halt.
Rejections and errors. None at this layer.
Vector. computed: a node running 0.6.1 (bundle 601) on the chain of the 29 §4b vector, where the
gate decides bundle 602 for height 56,000, logs "FATAL: readiness for future rule bundle 602 observed from height 56000 and this binary carries bundle 601: block production stops at height 56000 (validation continues). …" once per height from 56,000 and does not produce; it keeps validating and syncing. A
streak of 12 failed fork resolutions against 3 peers over 2,000 s with the height frozen and no signed
evidence → one log line, no wedge reason, no marker.
Test cases · §5
4 cases · 4 valid · 1 reference
A 0.6.1 node on the chain where bundle 602 is decided for height 56,000 stops producing there
Loading the test widget…
12 failed fork resolutions against 3 peers over 2,000 s, height frozen, no signed evidence
Loading the test widget…
The same streak with the fork resolver's beyond-bound verdict sets the wedge reason
Loading the test widget…
The daemon loop's cadences
A stated value: there is nothing to compute. A compatible node shows the same value.
- selection_seconds
1- main_loop_seconds
1- registration_refresh_seconds
5- candidate_attempt_seconds
10- deferred_spine_checks_seconds
10- newer_release_notice_blocks
5760- peer_ahead_window_seconds
120- chain_lock_wait_seconds
30- streak
10 failed resolutions, 2 peers, 1800 s, at most once per 86400 s
Defects to match. None.
§6 What persists across restarts
Purpose. The on-disk state an implementation keeps, and what it rebuilds.
Inputs. The data directory (the directory of db_path).
Output and effect. As listed.
How to compute it.
- The database (
blockchain.dbwith its-waland-shm): every table of07(chain, state, registry, scores, receipts, consensus parameters, pool and staging), the localrule_activation_record(29§4c),spine_promiseandspine_refused(25§10),node_address_info(27§6),producer_signed_parent(per parent block this node signed a block over: the side of the recovery limit it signed on and the signed block's wire bytes and position, so that after a restart the producer hands the same signed block back instead of signing a second one over that parent,35§1),node_notification_outbox(the claim e-mails of §2:event_key= transaction id +:announcementor:execution,subject,body,first_attempt,next_attempt,attempts,status0 queued / 1 sent / 2 given up,block_height). Must contain block 0 before the first start (built by the genesis builder from the two genesis configs). genesis-config.json,spine-genesis-config.json: kept beside the database for the rebuild; the node does not read them.spine-pin.txt(§4b), when the release ships one.node.conf;logs/node.logandnode.log.1(atmax_log_file_sizethe file is renamed to.1, replacing the previous one, and a new file starts with a rotation line; the size check runs only on the logger's own writes, so output a service manager appends to the same file is not counted);logs/archival.log,logs/bridge.log,logs/updater.log.snapshots/<base64url(SHA3)>/(26);pieces/and the piece manifest (11); the archival chunk directory (archival role).- Markers:
RESYNC_REQUIRED(the reason, one line),.last_resync(epoch of the last rebuild),blockchain.db.wedged*(a chain set aside, deleted after 7 days),updater.state(ok|failed <release> <epoch>),bridge.json(the keeper's configuration). - Rebuilt at every start: the peer table (
28), the topology cache, the candidate pool, the relay caches, the health samples, the balance cache, the rate and charge records.
Rule activation. None. Rejections and errors. None.
Vector. computed: a node with db_path = /var/lib/zoobc/blockchain.db keeps its markers in
/var/lib/zoobc/, its snapshots in $HOME/.zoobc/snapshots/ and its log in log_path.
Test cases · §6
1 case · 1 valid · 1 reference
Where a node with db_path = /var/lib/zoobc/blockchain.db keeps its files
A stated value: there is nothing to compute. A compatible node shows the same value.
- markers
/var/lib/zoobc/- snapshots
$HOME/.zoobc/snapshots/- log
log_path- wedged_kept_days
7
Defects to match. None.
§7 Timers
Purpose. Every periodic activity of the process in one table (the P2P loops are 28's).
Inputs / Output. As listed.
How to compute it.
| Activity | Cadence |
|---|---|
| selection | 1 s (§5) |
| main loop / registration refresh / candidate attempt | 1 s / 5 s / 10 s (§5) |
| health sample | 500 ms (28 §12) |
| load sampler | 4 s (27 §16) |
| heartbeat, sync, discovery, recovery, announcement | 30 / 10 ± 2 / 60 / 30 (10) / 30 s (28) |
| storage maintenance and proofs | ~5 s poll, acts per epoch (240 blocks; DevNet 10); waits for a peer up to 2 min; re-fetches archive chunks every 60 s (11, 26 §10b) |
| gateway-registry liveness | 60 s, entries older than 3,600 s dropped |
| pool expiry | 300 s; a transaction leaves at its own stated expiry (04) |
| deferred spine checks | 10 s, and at start (25 §7) |
| own-duty re-send | 120 s (28 §8) |
| newer-release notice | at start, then every 5,760 blocks (§5) |
| roll-call answer (genesis registered nodes) | re-sent every 120 s within the window (36) |
| snapshot | per block, at H mod main_snapshot_interval = 0 plus the stagger (26 §1) |
| spine blocksmith | per spine period (86,400 / 3,600 s) (25 §5) |
| UPnP renewal | lease 3,600 s, re-added every 1,200 s |
| supervised child restart | 2, 4, 8, 16, 30, 30… s (§8) |
| self-update check (outside the node) | 15 min after boot, then every 10 min ± 2 min (§9) |
Rule activation. None. Rejections and errors. None.
Vector. computed: in one hour a registered node runs 120 heartbeat cycles, about 360 sync passes, 60
discovery asks and 120 announcement rounds.
Test cases · §7
1 case · 1 valid · 1 reference
One hour of a registered node's peer loops
A stated value: there is nothing to compute. A compatible node shows the same value.
- heartbeat_cycles
120- sync_passes
about 360- discovery_asks
60- announcement_rounds
120
Defects to match. None.
§8 Roles and supervisors
Purpose. What an implementation runs besides itself.
Inputs. [archival], [bridge], [rpc], [storage].
Output and effect. Child processes and in-process adapters.
How to compute it.
- Archival (
archival_node = true): after start-up, with free disk on the data directory ≥archive_min_disk_gb, the archival program (archive_binary, else found beside the node, else on the path) runs as a child with the node's configuration path as its only argument, its output appended tologs/archival.log; restarted after 2 s doubling to 30 s; stopped with SIGTERM then SIGKILL. The node itself reportsarchival_nodein/node/info. - Bridge keeper (
[bridge] enabled): started only whenconfig_pathexists, free disk ≥min_disk_gband available memory ≥min_ram_mb; arguments--config <path> --watch; loglogs/bridge.log; same restart and stop rules. - Ethereum / Bitcoin adapters: in-process, translating wallet RPC to the node's API on loopback.
- Storage (on by default): the piece service, its maintenance, the archive keeper (
26§10b). - Service manager (the shipped unit): restart always after 10 s, at most 10 starts per 600 s, 65,536
open files, the resync check (§9) before every start, output appended to
logs/node.log, a read-only system with only the data directory writable.
Rule activation. None. Rejections and errors. A supervisor that cannot start its child logs and retries; a child that cannot run exits 127 and is restarted.
Vector. computed: an archival node with 4 GB free and archive_min_disk_gb = 5 does not start the
archival program.
Test cases · §8
2 cases · 2 valid · 2 reference
An archival node with 4 GB free and archive_min_disk_gb = 5
A stated value: there is nothing to compute. A compatible node shows the same value.
- value
the archival program is not started
Supervised child restarts and the service unit
A stated value: there is nothing to compute. A compatible node shows the same value.
- child_restart_seconds
2, 4, 8, 16, 30, 30, …- unit_restart_seconds
10- unit_start_limit
10 per 600 s- open_files
65536
Defects to match. None.
§8a The gateway identity file
Purpose. Where a gateway keeps the key it is registered under, so that a client can check that an answer comes from the gateway the chain's gateway registry lists. The node itself reads none of it; the file belongs to the gateway program, which runs beside a node on a gateway machine.
Inputs. The gateway key (an Ed25519 seed, 64 hex characters), given to the installer of the gateway
role explicitly or typed at its prompt; the gateway's setting identity_key_path (default
/etc/zoobc/gateway-identity.env).
Output and effect. The file /etc/zoobc/gateway-identity.env, owned by root, mode 0600: comment lines
and one line GATEWAY_KEY=<64 hex>, the 32-byte seed of the gateway key, whose public key is the
gateway_key of the gateway's registry row and whose ZBG_ address the installer prints for the
operator to compare with the registry. The key holds no funds. With the file in place the gateway signs
every response it produces with three headers (scheme ZBG-RESP-V1): ZBG-Key (the public key, 64
hex), ZBG-Time (unix seconds, decimal) and ZBG-Signature (128 hex); the same key signs the gateway's
on-chain GatewayHeartbeat (17 §7). Without the file the gateway runs unsigned, says so once in its log
("[identity] responses are NOT signed: <why>") and GET /gateway/identity answers "signed": false.
How to compute it.
- The installer stores the file only when a key is given; an existing file is kept unless a key is given explicitly, which replaces it; a key that is not exactly 64 hex characters is refused.
- The gateway reads the first line beginning
GATEWAY_KEY=(leading blanks and trailing blanks or a carriage return ignored, one pair of matching quotes removed); no file → unsigned; no such line or a value that is not 64 hex characters → unsigned. - The signed message:
SHA3-256("ZBG-RESP-V1" ‖ 0x0A ‖ method ‖ 0x0A ‖ target ‖ 0x0A ‖ ZBG-Time ‖ 0x0A ‖ SHA3-256(body)), where method and target are the request's as sent (the target is the path and query of the request line), ZBG-Time is the ASCII decimal of the header, and the inner hash is the 32 raw bytes of the hash of the response body as sent;ZBG-Signature= Ed25519 over those 32 bytes. - Signed: every response with a string body, the gateway's own routes and the node answers it proxies alike. Not signed: release file downloads (verified by their signed checksum manifest), WebSocket upgrades and the relay's pass-through connections.
- A client checks that
ZBG-Keyis the key the gateway registry lists for the gateway's domain (or one it pinned earlier), thatZBG-Timeis within a few minutes of its clock, and that the signature verifies over the method and target it sent and the body it received.
Rule activation. None.
Rejections and errors. The installer: "the gateway key must be 64 hex characters (got N)" or "(got a non-hex character)". The gateway: unsigned operation, as above.
Vector. computed. INPUT: GET /api/v1/blockchain/height, ZBG-Time 1794211200, response body
{"height":0} (12 bytes). EXPECTED OUTPUT: SHA3-256(body) =
f947796a2d6baaae145426dc76446c7f400a6aef337b627885ad7b422d734628; the 85-byte message hashes to
f00b9bf1fc198ce9c4dab690eed03dcdf404b1816b2a4fa938faaba6802da2e1, the 32 bytes the gateway key signs.
INVALID: the same answer with the body {"height":1} → the hashed message becomes
577753ad4545a61823de61619ebb99dc852088580bef76a6ce9b12a0e9b12562 and the signature made over the first
does not verify. A GATEWAY_KEY= value of 63 characters → the installer refuses it; written by hand,
the gateway runs unsigned.
Test cases · §8a
7 cases · 3 valid · 4 invalid
The message a gateway signs for {"height":0}
Loading the test widget…
The same answer with the body {"height":1}: the signature made over the first does not verify
Loading the test widget…
A gateway key of 63 characters is refused by the installer
Loading the test widget…
A gateway key with a character that is not hex is refused by the installer
Loading the test widget…
The gateway reads its key from the identity file and signs
Loading the test widget…
A quoted value with a carriage return is read the same
Loading the test widget…
A GATEWAY_KEY= value of 63 characters written by hand: the gateway runs unsigned
Loading the test widget…
Defects to match. None.
§9 Self-update and the wedge rebuild
Purpose. How the fleet follows the on-chain release registry (17 §6) and recovers a wedged node.
Inputs. /api/v1/release/list, /release/authority, /node/info, /nodes?status=all (31); the
authority's and the owner's datasets; [update].
Output and effect. The installer re-run with a pinned release; a restart on the new binary or a rollback; a rebuilt chain.
How to compute it. The node provides only the API; the update mechanism lives outside the node, so
an implementation updated by it must be installed by the same installer with the same layout, and
otherwise must follow /release/list itself. A timer (first run 15 min after boot, then every
10 min ± 2 min) runs the updater:
[update]:auto_update=on(default) |off|chain(the owner's datasetnode.auto_update, its newest row;off/0/false/no= off);auto_update_delay_blocks(the installer writes 11,520 on the TestNet and 120 on the DevNet into a newnode.conf; an existing value is kept),auto_update_window_blocks(240, a minimum),auto_update_nodes_per_block(2, 0.01…50),auto_update_retry_hours(12),auto_update_chain,release_base_url.- From the node's API: the running version, height and key; the release rows of this chain and
architecture (
v<maj>.<min>.<patch>-<chain>-<arch>, amd64 / arm64), the newest row per version; candidates = not revoked and newer than the running version; target = the highest. - Slot:
N= distinct registered node keys;rank= this key's index in ascending hex order (a key not in the registry: its SHA-256 mod N); pacek= the authority's datasetrelease.nodes_per_blockwhen in 0.01…50, else the configured value;window = ceil(N / k), raised to at least 240 only when the authority sets no pace;slot = rank × window div N;due = registration height + delay + slot. - Below
due: wait. Otherwise fetch the installer from a gateway that serves the target's signature (the configured base URL, the recorded install source, then every registered gateway) and run it as an update pinned to the target version and manifest hash; success = the node reports the target version; a failure is recorded and retried after 12 h. - The installer verifies the bundle signature and the manifest hash against the chain, installs beside the running version, switches, restarts, health-checks and rolls back on failure.
Wedge rebuild (the check before every start): with RESYNC_REQUIRED present and no rebuild within
86,400 s: move the database to blockchain.db.wedged*, build block 0 from the two genesis configs, stamp
.last_resync, remove the marker; the node then syncs the spine (storing it ahead of its main chain) and
fast-syncs from the newest snapshot (26 §5); without the configs or on a build failure the old chain is
restored and the node starts anyway. .wedged files older than 7 days are deleted at every start.
Rule activation. None.
Rejections and errors. The updater logs and retries; it marks the service failed only for an update that did not verify.
Vector. computed: 11 registered keys, pace 2, no authority pace: window = max(240, ceil(11/2)) = 240; slots rank × 240 div 11 = 0, 21, 43, 65, 87, 109, 130, 152, 174, 196, 218 blocks after
registration + delay.
Test cases · §9
4 cases · 4 valid · 1 reference
11 registered keys, pace 2, no authority pace
Loading the test widget…
11 registered keys, the authority's pace 2: the window is exact
Loading the test widget…
11 registered keys, the authority's pace 0.1 (one node every 10 blocks)
Loading the test widget…
The updater's timer and defaults
A stated value: there is nothing to compute. A compatible node shows the same value.
- first_run
15 min after boot- period
10 min ± 2 min- delay_testnet_blocks
11520- delay_devnet_blocks
120- window_minimum_blocks
240- nodes_per_block
2 (0.01 … 50)- retry_hours
12- rebuild_at_most_every_seconds
86400
Defects to match. None.
§9a Relaunching a chain
Purpose. How a node moves onto a new chain (a relaunch: a new genesis, every rule at 0, as both chains do for 0.6.1), and how the genesis registered nodes start it together. A relaunch is never automatic: the self-updater (§9) installs releases of the chain it runs, and an operator installs the relaunch release.
Inputs. The relaunch release: its main and spine genesis configs and its spine pin; the node's data directory and database; the chain the installing gateway serves (its block 0); a launch timestamp.
Output and effect. The node's database replaced by the new block 0 (or kept, or the install refused); the genesis files and the pin beside it (§6); after the launch, a chain whose block 0 every node shares.
How to compute it.
- What the release carries.
genesis-config.jsonandspine-genesis-config.json, listing every rule at 0 (29§2), andspine-pin.txtnaming spine block 0 of those files (0 <hash>, §4b). Both genesis files carry the same launch timestamp, the main file undertimestamp, the spine file undergenesis_timestamp; a timestamp of 0 stops the install ("genesis-config.json has no timestamp (it ships as 0)", and the same for the spine file). A launch timestamp the operator gives rewrites both files together. An install given a launch timestamp re-derives a pin at block 0 from the database it builds (0 <spine block 0 of that genesis>, logged with the release's own pin when they differ; a build whose spine block 0 cannot be read stops the install, nothing installed); a pin above block 0 names a block of the running chain and is kept. - Stop first. A running node is stopped before its database is touched.
- Build aside. Block 0 is built into a temporary database from the two files by the genesis builder
(in its existing-chain mode,
29§2) and its hash read back. - Same chain as the gateway. When the gateway the release came from serves a chain (its
GET /api/v1/blocks/0, else/api/v1/node/infogenesis_hash), its block-0 hash must equal the new one, else the install is refused before anything is written ("REFUSING to install: this release is not the chain at <gateway>"), unless the operator states that a chain of its own is intended. A gateway that answers nothing is reported as not checked. - Same chain as the node? The genesis hash of the database the node runs (its
chain_metadatagenesis_hash) is compared with the new one: equal → the database is kept and the node resumes at its height; different →"THIS RELEASE IS A DIFFERENT CHAIN — the existing chain will be discarded.", the old database is deleted and the new block 0 takes its place. An explicit forced resync discards it in either case. - Peers. The seed-peer list of
node.confis replaced by the release's list when the release ships one (the old chain's addresses would otherwise be dialled for ever, every handshake refused"Genesis hash mismatch - different chain configuration"); the rest ofnode.conf(key, owner, settings) is kept, withrequire_signed_receipt_requests = trueadded when the file does not name it (§2). - Stage, then flip. Every genesis registered node is first installed on the release's timestamp, set
ahead of the launch: all build one genesis hash, peer with each other and produce nothing before the
genesis time (§5 step 4), so a node installed last is not behind. Staging also sets
require_signed_receipt_requests = truein the last[node]section of every node'snode.conf(replacing whatever value it held; a node where the line does not then read as on stops the relaunch), so both chains refuse unsigned receipt requests from block 0. Then one launch timestamp a few minutes ahead, computed once, is written into both genesis files of every node and block 0 is rebuilt locally (the rest ofnode.confuntouched); the nodes start producing together at that second. A timestamp computed on each node separately gives each a different genesis hash: separate chains, never a slow start. - The spine pin follows the new genesis. A new timestamp builds a new spine block 0, so the pin the
release installed names a block the new chain does not have (a pin at block 0 would stop the node at
start, §4b; one above block 0 would stall the new chain at that spine height). The re-timestamp tool
has two modes. As a relaunch (used at the stage and at the flip) it rewrites
spine-pin.txtto0 <spine block 0 of the genesis just built>whatever it named before and logs the old and the new pin ("spine pin was: …","spine pin now: 0 <64 hex> …"); a spine block 0 it cannot read, or a pin that does not read back, leaves the node stopped. As a repair onto an existing chain a pin at block 0 must already name the spine block 0 just built, else the timestamp is not that chain's and the tool stops before starting the node, the pin unchanged; a pin above block 0 is the running chain's anchor and is kept; a missing or malformed pin is left as it is. Before the stage and before the flip the relaunch tool first installs this release's copy of the re-timestamp tool on every node (a node keeps the copy of the release last installed on it, and an older copy ignores the relaunch mode) and refuses to go on when a node did not take it. Each node's report shows its genesis hash and its new pin; every node must show the same hash. - After the launch every node reports the same
genesis_hashinGET /api/v1/node/info; the genesis registered nodes answer the roll call (36); withsurvival_min_producers5 in both shipped genesis files the chain is in survival mode until five distinct blocksmiths have produced in the last 120 blocks (19§10). Nodes that join later install the release as published after the flip, whose genesis files carry the launch timestamp, and sync from the gateways.
Rule activation. None.
Rejections and errors. As listed in steps 1, 4, 5, 7 and 8; a genesis build that fails leaves the node's existing database untouched and the node not started.
Vector. computed. INPUT: a TestNet node holding a chain with genesis hash X, given the relaunch
release built from the shipped TestNet files on their own timestamp, from a gateway that serves
3A2897E7…863D (06 §3). EXPECTED OUTPUT: the temporary block 0 hashes to 3A2897E7…863D = the
gateway's → X ≠ that → the old database is discarded and the node starts on the new block 0, its
spine pin 0 7CD929C4…545C (spine block 0 of those files, §4b). The same from a gateway still serving
X → refused, nothing written. A flip to timestamp T on every node → genesis hash
SHA3-256(01000000 00000000 LE64(T) 00×32 ‖ config_hash) (06 §12), the same on every node given the
same T, and every node's pin rewritten to 0 <spine block 0 built on T>. INVALID: the repair mode
given a timestamp other than the chain's on a node whose pin is 0 7CD929C4…545C → the tool stops
("the spine pin does not name the genesis just built: <T> is not this chain's genesis timestamp."), the
node left stopped, the pin unchanged.
Test cases · §9a
7 cases · 5 valid · 2 invalid · 3 reference
The relaunch release built aside: its block 0 hashes to the genesis the gateway serves
Loading the test widget…
The release's spine pin names spine block 0 of those files
Loading the test widget…
A TestNet node holding another chain X, given that release
A stated value: there is nothing to compute. A compatible node shows the same value.
- value
X differs from the new block 0: the old database is discarded and the node starts on the new block 0 with the spine pin 0 7CD929C4D52D9C9455ED179D24A65F90ECBF3D1A3E1214A19611635791B3545C
The same release from a gateway still serving X
A stated value: there is nothing to compute. The statement is a refusal: the exact text a compatible node answers.
- refusal
REFUSING to install: this release is not the chain at <gateway>- written
nothing
A flip to the launch timestamp T: every node builds the same genesis hash
Loading the test widget…
And every node's spine pin is rewritten to spine block 0 built on T
Loading the test widget…
The repair mode given a timestamp that is not the chain's, on a node pinned at 0 7CD929C4…545C
A stated value: there is nothing to compute. The statement is a refusal: the exact text a compatible node answers.
- refusal
the spine pin does not name the genesis just built: <T> is not this chain's genesis timestamp.- node
left stopped- pin
unchanged
Defects to match. None.
§10 Consensus and local
Nothing in this chapter is consensus. What an implementation must reproduce to be this node: the key rules and the node id of §3, the genesis-in-database requirement and the chain identity of §4 step 3, and the behaviour the other chapters fix. Every file name, timer, supervisor and configuration key is local.
A question about this chapter, or a statement that does not match the network? Discuss on zoobc.pro.