On this page
  1. §0 The area in one paragraph
  2. §1 Command line, process and signals
  3. §2 The configuration file
  4. §3 Key material and identity
  5. §4 Start-up sequence
  6. §4a The clock
  7. §4b The spine pin
  8. §4c The node's signed P2P calls, from the operator's view
  9. §5 The daemon loop
  10. §6 What persists across restarts
  11. §7 Timers
  12. §8 Roles and supervisors
  13. §8a The gateway identity file
  14. §9 Self-update and the wedge rebuild
  15. §9a Relaunching a chain
  16. §10 Consensus and local

30 — Node operation: configuration, key material, start-up, persistence, timers, roles, self-update

Edition 0.6.1 · verified against the reference implementation, version 0.6.1

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 line30-1-clivalidreference

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 file30-2-chain-idvalid

Loading the test widget…

The chain id of a DevNet built from the shipped genesis file30-2-chain-id-devnetvalid

Loading the test widget…

The retired TestNet genesis keeps 88330-2-chain-id-retiredvalid

Loading the test widget…

A genesis sharing only the retired genesis's first eight bytes derives its own id30-2-chain-id-prefix-onlyvalid

Loading the test widget…

public_ip with a port stops the node30-2-public-ip-portinvalid

Loading the test widget…

public_ip stated as an IPv4 address30-2-public-ipvalid

Loading the test widget…

api_enabled = on is false in [api]30-2-api-onvalid

Loading the test widget…

api_enabled = True is false in [api] (exact spelling only)30-2-api-Truevalid

Loading the test widget…

auto_resync = Off and upnp_enabled = ON read in any case outside [api] and [rpc]30-2-node-Onvalid

Loading the test widget…

max_log_file_size = 10 is 10 MiB30-2-log-mibvalid

Loading the test widget…

max_log_file_size = 20000 is 20,000 bytes30-2-log-bytesvalid

Loading the test widget…

The defaults of the keys read here30-2-defaultsvalid

Loading the test widget…

[notifications] with notify_email and no smtp_from stops the node30-2-notify-no-frominvalid

Loading the test widget…

smtp_tls must be starttls, tls or off30-2-notify-tlsinvalid

Loading the test widget…

smtp_port 0 stops the node30-2-notify-portinvalid

Loading the test widget…

A complete [notifications] section30-2-notify-okvalid

Loading the test widget…

A node.conf without require_signed_receipt_requests reads false30-2-receipts-defaultvalid

Loading the test widget…

require_signed_receipt_requests = true under [node]30-2-receipts-onvalid

Loading the test widget…

What the installer and the relaunch write for require_signed_receipt_requests30-2-receipts-installervalidreference

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 section30-2-outside-sectioninvalid

Loading the test widget…

A configuration without an owner address30-2-no-ownerinvalid

Loading the test widget…

The Bitcoin-style adapter refuses the pair zoobc / zoobc30-2-btc-default-pairinvalid

Loading the test widget…

The Bitcoin-style adapter needs both user and password30-2-btc-no-passwordinvalid

Loading the test widget…

Operator-chosen credentials are usable30-2-btc-okvalid

Loading the test widget…

The default ports and limits30-2-portsvalidreference

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.

  1. 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.
  2. node_public_key (ZNK_ text, 01, or 32-byte hex) must equal the derived public key.
  3. 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).
  4. 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.
  5. 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 key30-3-node-idvalid

Loading the test widget…

A 32-byte private key is a seed: its public key and node id30-3-seedvalid

Loading the test widget…

A 64-byte private key: the public key is its last 32 bytes30-3-secret-keyvalid

Loading the test widget…

node_public_key given as a ZNK_ address30-3-znkvalid

Loading the test widget…

A ZNK_ text whose checksum is that of the ZBC_ form is refused30-3-znk-bad-checksuminvalid

Loading the test widget…

A 33-byte private key is refused30-3-wrong-lengthinvalid

Loading the test widget…

A public key that does not match the private key is refused30-3-mismatchinvalid

Loading the test widget…

A key rotation takes effect 120 blocks after its block30-3-rotationvalidreference

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 registry30-3-observervalidreference

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 start30-3-registry-unreadableinvalidreference

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.

  1. Configuration: load (§2), the mode guard, the load sampler (27 §16), the health monitor (28 §12); the P2P port from listen_address (8001 when unparsable). With P2P on, the public IP (28 §2): public_ip as 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, auto or listen-equal value takes the discovered one.
  2. Database: open the SQLite file (one connection for the chain, one for the pool and staging), a WAL checkpoint.
  3. 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.
  4. 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.
  5. 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).
  6. Receipts and topology (23).
  7. Block services: validator, blocksmith, the snapshot scheduler (when the spine exists and main_snapshot_interval > 0, 26), the candidate pool.
  8. 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: with auto_resync on the resync marker is written; the node stops.
  9. P2P: UPnP (a 3,600 s mapping of the P2P port, renewed every 1,200 s) when enabled; the require_bidirectional checks; the network node (28), which signs every call it makes (§4c), with require_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).
  10. 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.
  11. 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 030-4-no-genesisvalidreference

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 mapping30-4-upnpvalidreference

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 UTC30-4a-clockvalid

Loading the test widget…

The stand-in timestamp 1,794,211,200 is 2026-11-09 08:00:00 UTC30-4a-clock-27valid

Loading the test widget…

The clock bounds30-4a-boundsvalidreference

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 node30-4b-pinnedvalid

Loading the test widget…

The shipped pin on a node whose genesis was rebuilt on another timestamp without the pin re-derived30-4b-rebuilt-timestampvalid

Loading the test widget…

The pin with its last character changed, auto_resync on: the marker is written, the node stops30-4b-conflict-resyncvalid

Loading the test widget…

The same with auto_resync off: the node exits30-4b-conflict-offvalid

Loading the test widget…

The same with a marker already there: the node exits, no new marker30-4b-conflict-markervalid

Loading the test widget…

The line 12 7CD9: no pin30-4b-malformedvalid

Loading the test widget…

64 characters that are not hex: a warning, no pin30-4b-not-hexvalid

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.

  1. 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.
  2. 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.
  3. 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).
  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 as UNAUTHENTICATED "<Method>: <why>".
  5. 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.
  6. 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.
  7. 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.
  8. Receipts. Every 0.6.1 node signs its receipt requests whatever require_signed_receipt_requests says; 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 refused30-4c-clock-aheadinvalid

Loading the test widget…

A clock 599 s behind is still inside the window30-4c-clock-withinvalid

Loading the test widget…

Nine unregistered nodes behind 203.0.113.7 handshake with one peer: the ninth is refused30-4c-nine-behind-onevalid

Loading the test widget…

Two unregistered nodes in one IPv6 /64 count against one host30-4c-ipv6-one-hostvalid

Loading the test widget…

A node advertising 0.0.0.0:8001 behind NAT gets an entry with no address30-4c-behind-natvalid

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.

  1. The start-up sync gate (28 §2) first.
  2. Every 10 s the deferred spine checks (25 §7); the alarm: with auto_resync on the resync marker is written; the node stops with exit code 3.
  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/info newer_release reports the same (31).
  4. Selection, every 1 s: with auto_resync on, a non-empty wedge reason (24) is written to <db dir>/RESYNC_REQUIRED and 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/rules production_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.
  5. 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.
  6. 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 there30-5-production-haltvalid

Loading the test widget…

12 failed fork resolutions against 3 peers over 2,000 s, height frozen, no signed evidence30-5-streak-log-onlyvalid

Loading the test widget…

The same streak with the fork resolver's beyond-bound verdict sets the wedge reason30-5-streak-evidencevalid

Loading the test widget…

The daemon loop's cadences30-5-cadencesvalidreference

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.db with its -wal and -shm): every table of 07 (chain, state, registry, scores, receipts, consensus parameters, pool and staging), the local rule_activation_record (29 §4c), spine_promise and spine_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 + :announcement or :execution, subject, body, first_attempt, next_attempt, attempts, status 0 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.log and node.log.1 (at max_log_file_size the 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 files30-6-layoutvalidreference

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 loops30-7-hourvalidreference

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.

  1. 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 to logs/archival.log; restarted after 2 s doubling to 30 s; stopped with SIGTERM then SIGKILL. The node itself reports archival_node in /node/info.
  2. Bridge keeper ([bridge] enabled): started only when config_path exists, free disk ≥ min_disk_gb and available memory ≥ min_ram_mb; arguments --config <path> --watch; log logs/bridge.log; same restart and stop rules.
  3. Ethereum / Bitcoin adapters: in-process, translating wallet RPC to the node's API on loopback.
  4. Storage (on by default): the piece service, its maintenance, the archive keeper (26 §10b).
  5. 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 = 530-8-archival-diskvalidreference

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 unit30-8-restartvalidreference

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.

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. A client checks that ZBG-Key is the key the gateway registry lists for the gateway's domain (or one it pinned earlier), that ZBG-Time is 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}30-8a-responsevalid

Loading the test widget…

The same answer with the body {"height":1}: the signature made over the first does not verify30-8a-body-changedinvalid

Loading the test widget…

A gateway key of 63 characters is refused by the installer30-8a-installer-63invalid

Loading the test widget…

A gateway key with a character that is not hex is refused by the installer30-8a-installer-not-hexinvalid

Loading the test widget…

The gateway reads its key from the identity file and signs30-8a-filevalid

Loading the test widget…

A quoted value with a carriage return is read the same30-8a-file-quotedvalid

Loading the test widget…

A GATEWAY_KEY= value of 63 characters written by hand: the gateway runs unsigned30-8a-file-63invalid

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:

  1. [update]: auto_update = on (default) | off | chain (the owner's dataset node.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 new node.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.
  2. 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.
  3. 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); pace k = the authority's dataset release.nodes_per_block when 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.
  4. 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.
  5. 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 pace30-9-slotsvalid

Loading the test widget…

11 registered keys, the authority's pace 2: the window is exact30-9-authority-pacevalid

Loading the test widget…

11 registered keys, the authority's pace 0.1 (one node every 10 blocks)30-9-slow-pacevalid

Loading the test widget…

The updater's timer and defaults30-9-updatervalidreference

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.

  1. What the release carries. genesis-config.json and spine-genesis-config.json, listing every rule at 0 (29 §2), and spine-pin.txt naming spine block 0 of those files (0 <hash>, §4b). Both genesis files carry the same launch timestamp, the main file under timestamp, the spine file under genesis_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.
  2. Stop first. A running node is stopped before its database is touched.
  3. 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.
  4. 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/info genesis_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.
  5. Same chain as the node? The genesis hash of the database the node runs (its chain_metadata genesis_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.
  6. Peers. The seed-peer list of node.conf is 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 of node.conf (key, owner, settings) is kept, with require_signed_receipt_requests = true added when the file does not name it (§2).
  7. 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 = true in the last [node] section of every node's node.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 of node.conf untouched); 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.
  8. 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.txt to 0 <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.
  9. After the launch every node reports the same genesis_hash in GET /api/v1/node/info; the genesis registered nodes answer the roll call (36); with survival_min_producers 5 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 serves30-9a-relaunch-genesisvalid

Loading the test widget…

The release's spine pin names spine block 0 of those files30-9a-relaunch-pinvalid

Loading the test widget…

A TestNet node holding another chain X, given that release30-9a-relaunch-installvalidreference

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 X30-9a-gateway-other-chaininvalidreference

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 hash30-9a-flip-genesisvalid

Loading the test widget…

And every node's spine pin is rewritten to spine block 0 built on T30-9a-flip-pinvalid

Loading the test widget…

The repair mode given a timestamp that is not the chain's, on a node pinned at 0 7CD929C4…545C30-9a-repair-mismatchinvalidreference

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.