On this page
- §0 The area in one paragraph
- 1. The configuration files
- 2. Consensus parameters and rule heights
- 3. The config hash and the genesis hash
- 4. The genesis block of the main chain
- 5. Accounts, tokens and token balances at height 0
- 6. The node registry, node accounts and scores at height 0
- 7. The spine genesis block
- 8. The coinbase ceiling
- 9. Everything else at height 0
- 10. Build-time invariants
- 11. How the node reads genesis
- 12. Launching a chain, and the live chains
- 13. Appendix: the genesis texts every snapshot carries
06 — Genesis
Out of scope the meaning of each consensus parameter and rule (the documents that use them; the index is 29 and 32); the state objects' full shape (07); the spine chain's later blocks (25); the handshake procedure (27); the launch scripts that restamp a bundle (operations, 30)
§0 The area in one paragraph
A ZooBC chain is created off-line by a builder that reads one JSON file for the main chain and
one for the spine chain and writes a database holding block 0 of each chain and the whole initial
state. Every genesis file lists every one of the 125 rules at height 0, so every rule is on
from block 1. There is no genesis transaction: the configuration is the state. The builder
commits to everything that matters in one config hash (chain id, every consensus parameter and
rule height, every funded account, every registered node, every genesis token and token balance,
every vesting schedule, the supply ceiling and the opening balances' defaults, the four role keys —
release authority, page authority, treasury, market maker — the registries and the apps treasury)
and derives the genesis hash from the block's version, height, timestamp, a zero previous hash
and that config hash. The genesis hash is the chain's identity: peers refuse each other at
handshake when it differs, every transaction signature binds to it (02 §1), and the public API
reports it. The genesis block itself is a block of the format of 05 with all-zero seed, seed
proof, blocksmith key, signature, previous hash and payload, whose hash is not the hash of its
own bytes but the config-derived value; the spine genesis block, by contrast, is hashed exactly
like any spine block (05 §2–§4) over a payload that lists the initial spine blocksmiths. Every
account the builder writes is typed (00000000 ‖ key, 01 §4) and, because rule
genesis_rent_clock is on from genesis, every funded account that is not rent-exempt is on the
rent clock from height 0. Every genesis registered node starts at 20 % of the maximum score, as
every later registered node does, and the first blocks run a roll call in which each genesis
registered node proves it is running this genesis (09). A genesis may name
survival_min_producers, the number of distinct blocksmiths below which the chain freezes its
governance and bridge transactions (19); the builder refuses a value the genesis registered
nodes could never leave, and a chain that names it starts in survival mode, since no blocksmith
precedes block 1 (§9). The running node never rebuilds genesis: it refuses to start without block 0
and reads the committed parameters, the rule heights and the coinbase ceiling from the tables the
builder wrote. An implementation must either accept the reference's genesis database as input or
reproduce every table of §9 from the configuration; either way it must compute the two hashes of
§3 and §7 exactly, or it is on a chain of its own. Beside the committed values the builder writes
texts of its own, a description beside every consensus parameter and the nine values of
chain_metadata: they are in neither hash, but every snapshot carries them, so an implementation
writes them byte for byte (§13). The shipped files' identities are in §12; a launch restamps them.
1. The configuration files
Purpose. The inputs: what a chain's creator writes.
Inputs. genesis-config.json (main chain) and spine-genesis-config.json (spine), JSON with
// and /* */ comments allowed.
Output and effect. The sections and keys the builder reads (anything else is ignored):
| Key | Type | Required | Used for |
|---|---|---|---|
chain_id |
string | no (default zoobc-mainnet) |
committed (§3); stored in chain_metadata |
timestamp |
integer > 0 | yes | block 0's timestamp; in the genesis hash |
total_supply |
integer | no (default 3,333,333,333,333,333) | the emission ceiling the coinbase pool is derived from (§8); committed (§3 step 8, TS:) |
consensus_params |
object | no | the 81 parameters of §2, min_registry_size, survival_min_producers and spine_late_vote_after_seconds (each committed only when named) and node_operating_balance (seeds node accounts; committed as NOB:, §3 step 8); naming a removed parameter fails the build |
rule_activation |
object name → height |
no | rule.<name> parameters (§2); every shipped file lists all 125 rules at 0 |
rule_off |
object name → height |
no | rule_off.<name> parameters (§2); a rule switches off at that height (29); empty on every live config |
accounts[] |
{address, balance, label?, balances?{symbol→amount}} |
no | ZBC and token balances at height 0 |
genesis_tokens[] |
{token_id, symbol, name?, decimals?, total_supply?, chain?, asset?, deposit_address?, allocations?[], holder?, balance?} |
no | the fixed token set (14) and bridge coins |
genesis_token_holder_zbc |
integer | no (default 10,000,000,000) | ZBC stipend for a token holder that is not in accounts; committed (GTH:) |
vesting[] |
{funder, recipient, token_id?, per_fire_amount, interval_seconds?, remaining_fires, cliff_seconds?, cancel_policy?, funding_mode?} |
no | schedules at height 0 (08) |
nodes[] |
{node_public_key, owner_account} |
at least one entry | the registry at height 0 (09) |
release_authority |
{address} |
no (a warning when absent) | the release authority (17); committed as RA:; may be given at most 1,000 ZBC in total by accounts and ZBC vesting, and no other coin (§10) |
page_authority |
{address} |
no (a warning when absent) | the foundation-page authority (17); committed as PA:; may be given nothing (§10) |
treasury |
{address} |
no (a warning when absent) | the treasury role key; committed as TR:; a name and an identity check only, no state row of its own |
market_maker |
{address} |
no (a warning when absent) | the market-maker role key; committed as MM:; a name and an identity check only |
genesis_release |
{version, manifest_hash, release_address} |
no | an initial release record (17); absent on both live chains |
gateways[], archival_nodes[], relays[] |
{gateway_key / node_public_key / relay_key, owner_account, domain, url, gateway_key? (relays)} |
no | the registries (17) |
apps_treasury |
object symbol → amount |
no | the apps pool's opening balances (16) |
games_treasury |
— | refused | an obsolete name of apps_treasury; the build fails |
The builder takes a flag --existing-chain (or the environment variable
ZBC_GENESIS_EXISTING_CHAIN=1): without it, a config that leaves out any rule this binary knows is
refused (a new chain must list every rule); with it, unlisted rules keep their compiled default
height and are not committed (an installer rebuilding the genesis of a chain that already runs). A
second flag --list-rules prints the name of every rule the binary knows, one per line, and exits
0. A third, --check-rules <main file> [spine file], validates rule_activation and the
consensus parameters without writing a database and prints Rule check passed: N rules are listed and the consensus parameters validate. (exit 0) or the refusal (exit 1); a relaunch bundle is
published only when it passes. A usage mistake exits 2; a refused config exits 1.
Spine file: spine_chain_id (string, printed only, not committed), genesis_timestamp
(default: the main timestamp), version (default 1), consensus_params (the spine_* subset,
overriding the main file's), initial_blocksmiths[] {node_public_key}.
Addresses are the text forms of 01 §5: ZBC_ accounts, ZNK_ node keys; a key field also
accepts 64 hex characters, and a ZBG_/ZBR_ text decodes to the same 32 raw bytes as a
ZNK_ (the prefix is display-only). Every account address and owner must decode, or the build
fails. A decoded account key K becomes the typed account 00000000 ‖ K in every row the builder
writes (accounts, stipends, the release authority, the genesis release address, the registries'
owners); node, gateway and relay keys stay the bare 32 bytes.
The published files: the TestNet pair (genesis-config.json and spine-genesis-config.json;
chain_id zoobc-test, 11 nodes, 61 accounts, 14 tokens, 6 vesting entries, the four role keys,
one gateway, one archival node, one relay, all 125 rules at 0, survival_min_producers 5,
min_registry_size 7, timestamp 1,793,509,027 in the file); the DevNet pair (zoobc-dev, the
same accounts, nodes, tokens and registries, all 125 rules at 0, survival_min_producers 5,
spine_late_vote_after_seconds 10,800, min_registry_size 3, the DevNet parameter values of §2,
the same timestamp in the file); and a third genesis-config.json, the mainnet template
(zoobc-mainnet, 13 accounts, 11 nodes, 14 tokens, all 125 rules at 0, no
survival_min_producers, timestamp 1,788,220,800). Every file's timestamp is restamped at launch
(§12), so a launched chain's genesis hash differs from the shipped file's (§3).
Rule activation. None.
Rejections and errors. The builder exits with an error (nothing written) when: timestamp is
missing or ≤ 0; a token has a non-positive or duplicate token_id or decimals outside 0–18; a
vesting entry has funder == recipient, a funding_mode other than 0 or 1, a token with mode 0,
a non-positive per_fire_amount or remaining_fires, interval_seconds ≤ 0 with more than one
fire, a negative cliff, a cancel_policy other than 0 or 1, or an overflowing principal; any
account address, node owner or role address does not decode; nodes[] is empty; a spine
blocksmith key does not decode or is not one of this chain's nodes; apps_treasury names an
undefined coin; games_treasury is present; the premine exceeds total_supply; the coinbase
ceiling read back from the three places it is stored disagrees; a removed parameter is present
(turn_window_multiplier, max_concurrent_turns, coinbase_maturity_blocks,
increase_score_divider, oracle_attester_set, storage_proof_reward,
storage_proof_score_penalty); dataset_billing_period_blocks or account_rent_period_blocks is
present with a value other than the snapshot cycle; survival_min_producers is outside 0 ..
10,000 ("ERROR: survival_min_producers must be 0 (off) or 1..10000, got N");
spine_late_vote_after_seconds is outside 0 .. 31,536,000 ("ERROR: spine_late_vote_after_seconds must be 0..31536000, got N"); a rule the binary knows is unlisted and --existing-chain was not
given; a rule_activation key names no rule of the binary or is not an integer (§2); or any
invariant of §10 fails.
Vector (computed). The shipped TestNet pair builds to the config hash and genesis hash of §3.
Invalid inputs: the TestNet file with "survival_min_producers": 10001 → "ERROR: survival_min_producers must be 0 (off) or 1..10000, got 10001", exit 1; the TestNet file with the
rule receipt_once removed from rule_activation, without --existing-chain → the line "Rules not listed in rule_activation (1, each at its compiled default height on a chain launched from this genesis): receipt_once=1000000" (1,000,000 is the compiled placeholder height of the 24
rules of bundle 601, 29) followed by "ERROR: 1 rule(s) of this binary are not listed in rule_activation. A NEW chain lists every rule ("<rule>": 0), or those rules only switch on at the compiled default height.", exit 1.
Test cases · §1
4 cases · 1 valid · 3 invalid · 2 reference
The shipped TestNet pair builds to the config hash and genesis hash of §3
The file as shipped; a launch restamps the timestamp, so a launched chain's genesis hash differs (§12).
A stated value: there is nothing to compute. A compatible node shows the same value.
- config_hash
b4d46ec1c521cbd143109591bdc5188c76e120779a048f858a5b2c29125ab381- genesis_hash
3a2897e7c5ad6143429bab33a92d14d11ffd6fc281f2b62a6fd6b49c183b863d- rules_listed
125- accounts
61- nodes
11- tokens
14- vesting_entries
6- chain_id
zoobc-test- survival_min_producers
5- min_registry_size
7- timestamp
1793509027
A survival_min_producers of 10001 is refused at build time
Loading the test widget…
A spine_late_vote_after_seconds above 31,536,000 is refused
Loading the test widget…
A new chain must list every rule the builder knows
The TestNet file with receipt_once removed from rule_activation, without --existing-chain; 1,000,000 is the compiled placeholder height of the 24 rules of bundle 601 (29).
A stated value: there is nothing to compute. The statement is a refusal: the exact text a compatible node answers.
- line
Rules not listed in rule_activation (1, each at its compiled default height on a chain launched from this genesis): receipt_once=1000000- refusal
ERROR: 1 rule(s) of this binary are not listed in rule_activation. A NEW chain lists every rule ("<rule>": 0), or those rules only switch on at the compiled default height.- exit_code
1
Defects to match. spine_chain_id is printed and never read or hashed (a label). The role
entries' note fields and an account's label are not committed (labels are display only).
2. Consensus parameters and rule heights
Purpose. The numbers every rule of the protocol reads; fixed for the life of the chain, except
the eight votable prices, whose genesis value is only their starting value (17).
Inputs. consensus_params of both files; rule_activation; rule_off.
Output and effect. A map name → i64 of exactly these 81 names, the value the config's when
present else the default shown, plus min_registry_size, plus survival_min_producers and
spine_late_vote_after_seconds each only when the config names it, plus rule.<name> for
every listed rule and rule_off.<name> for every rule the config switches off. The map is
committed (§3) and written to the consensus_parameters table
(07: columns parameter_name text primary key, parameter_value i64, description text), one
row per name with the builder's description text of §13, except two names that get no row
(coinbase_number_rewards_per_second and coinbase_max_number_rewards_per_block, which the node
reads from chain_metadata), and
coinbase_total_distribution, whose row holds the derived pool of §8 and no description; the
node reads it by name. Mainnet and TestNet have the same values.
| Name | Default | Mainnet = TestNet | DevNet |
|---|---|---|---|
| max_priority_blocksmiths | 4 (compiled default; the files say 10, at most 10, §10) | 10 | 10 |
| block_time_interval | 10 | 15 | 15 |
| smithing_period | 15 | 15 | 15 |
| blocksmith_time_gap | 10 | 15 | 15 |
| blocksmith_network_tolerance | 15 | 5 | 5 |
| blocksmith_block_creation_time | 30 | 15 | 15 |
| max_rollback_height | 720 | 720 | 60 |
| default_participation_score (20 % of the maximum 10^13) | 2,000,000,000,000 | same | same |
| cumulative_difficulty_divisor | 1,000,000 | same | same |
| max_transactions_per_block | 1,000 | 2,000 | 2,000 |
| max_block_size_bytes | 2,097,152 | 524,288 | 524,288 |
| coinbase_total_distribution | 3,300,000,000,000,000 | 3,333,333,333,333,333 (committed value; the stored value is the derived pool, §8) | same |
| coinbase_number_rewards_per_second | 1 | 1 | 1 |
| coinbase_max_number_rewards_per_block | 600 | 600 | 600 |
| topology_period_blocks | 40 | 40 | 40 |
| max_assigned_peers | 5 (clamped to ≥ 2) | 12 | 8 |
| receipt_batch_size | 100 | 100 | 100 |
| node_admission_base_delay | 259,200,000 | 51,840,000 (600 days) | 180 |
| node_admission_min_delay | 86,400 | 604,800 (7 days) | 60 |
| node_admission_max_delay | 2,592,000 | 7,776,000 (90 days) | 300 |
| node_admission_genesis_delay | 604,800 | 604,800 (7 days) | 600 |
| max_node_admittance_per_cycle | 1 | 1 | 1 |
| min_registry_size (stored beside the map, committed) | 3 | 7 | 3 |
| min_node_registration_balance (the queue minimum, a votable price) | 100,000,000 | 10,000,000,000 (100 ZBC) | 100,000,000 (1 ZBC) |
| min_node_registration_balance_ceiling | 25,000,000,000 (250 ZBC) | 25,000,000,000 | 250,000,000 (2.5 ZBC) |
| queue_median_fraction_bps | 5,000 | 5,000 | 5,000 |
| linked_receipt_score, unlinked_receipt_score | 1, 1 | 1, 1 | 1, 1 |
| batch_receipt_lookback_height | 40 | 40 | 40 |
| decrease_score_divider | 2 | 2 | 2 |
| score_loss_per_unit_bps | 500 | 500 | 500 |
| score_unit_floor_blocks | 2,880 | 2,880 | 120 |
| score_climb_ratio | 8 | 8 | 8 |
| maturity_units | 4 | 4 | 4 |
| liveness_miss_limit | 4 | 4 | 4 |
| node_lock_at_risk_bps | 1,000 | 1,000 | 1,000 |
| admission_genesis_seat_cap | 11 | 11 | 11 |
| roll_call_blocks | 20 | 20 | 20 |
| exit_cooldown_blocks | 40,320 | 40,320 | 1,680 |
| bridge_quorum_num, bridge_quorum_den | 2, 3 | 2, 3 | 2, 3 |
| min_block_interval | 10 | 15 | 15 |
| spine_smithing_period | 86,400 | 86,400 | 3,600 |
| spine_blocksmith_time_gap | 100 | 100 | 100 |
| spine_blocksmith_block_creation_time | 300 | 300 | 300 |
| spine_blocksmith_network_tolerance | 150 | 150 | 150 |
main_snapshot_interval (the snapshot cycle: every rent and vote period, 04 §2) |
0 (the cycle then falls back to 172,800) | 172,800 | 240 |
| main_snapshot_min_height | 1,440 | 760 | 80 |
| receipt_lifecycle | 0 | 518,400 | 1,440 |
| snapshot_manifest_expiration_seconds | 0 | 0 | 0 |
| spine_snapshot_interval | 0 | 0 | 0 |
| spine_snapshot_min_height | 1,440 | 1,440 | 1,440 |
| dataset_storage_cost_per_mib | 100,000,000 | 5,000,000 | 100,000,000 |
| storage_oracle_multiplier_ppm | 1,000,000 | same | same |
| min_payload_persistence_blocks | 17,280 | 17,280 | 240 |
| token_persist_period_cost | 100,000,000 | 10,000,000 | 100,000,000 |
| token_free_persist_blocks | = the snapshot cycle when absent | 172,800 | 240 |
| account_rent_period_cost | 100,000,000 | 1,000,000 | 100,000,000 |
| account_group_max_members | 100 | 100 | 100 |
| oracle_quorum (the storage tally's quorum) | 3 | 3 | 3 |
| storage_proof_epoch_blocks | 240 | 240 | 10 |
| storage_replication | 5 | 5 | 5 |
| snapshot_reward_share_ppm (the archive's share of the longevity pool per epoch) | 100,000 | 100,000 | 100,000 |
| chunk_size_blocks, chunk_replicas | 1,440, 5 | same | same |
| gateway_registration_cost | 1,000,000,000 | same | same |
| exchange_taker_fee_bps | 10 | 10 | 10 |
| market_creation_cost | 5,000,000,000 | same | same |
| gateway_heartbeat_interval, gateway_heartbeat_freshness_window, gateway_prune_grace | 240, 20, 480 | 240, 20, 480 | 240, 20, 480 |
| app_open_timeout_blocks | 161,280 | 161,280 | 200 |
| app_unused_share_bps | 1,000 | 1,000 | 1,000 |
| spine_min_signatures | 2 | 5 (spine file) | 5 (spine file) |
| spine_signature_threshold_percent | 67 | 67 | 67 |
| spine_signature_collection_timeout | 60 | 60 | 60 |
| spine_fallback_periods (main or spine file) | 3 | 3 (default; not in the files) | 3 (default) |
| spine_finality_depth | 3 | 3 | 3 |
| spine_enabled | 1 | 1 | 1 |
| spine_level | 1 | 1 | 1 |
| spine_parent_period_multiplier | 10 | 10 | 10 |
| spine_hierarchy_enabled | 0 | 0 | 0 |
| survival_min_producers (stored and committed only when named; absent = 0 = off; §10) | 0 | TestNet file: 5; mainnet template: not named (the builder warns, §10) | 5 |
| spine_late_vote_after_seconds (stored and committed only when named; 0 .. 31,536,000; the node reads 10,800 when absent, 25) | 10,800 | not named | 10,800 |
Rule heights: every shipped file lists all 125 rules at height 0 (the full set is 29), so
every rule is on from block 1 and rule_off is empty. The builder refuses a rule_activation key
it does not know ("rule_activation names no rule of this binary: <name>") and a value that is not
an integer ("rule_activation.<name> must be a block height."), so a stale name cannot reach the
genesis hash. A rule the binary knows and the config does not list switches on at its compiled
default height; without --existing-chain the build is refused rather than silently deferring it
(§1). Booleans are committed and stored as 0/1. Values are i64; the builder parses unsigned fields
as 32-bit and the rest as 64-bit, then widens.
How to compute it. Start from the defaults; refuse the build if a removed parameter is present
(§1); overwrite from the main file's consensus_params; refuse dataset_billing_period_blocks /
account_rent_period_blocks unless equal to the snapshot cycle (and never store them); clamp
max_assigned_peers to ≥ 2; overwrite the spine_* names (and spine_fallback_periods) from the
spine file's consensus_params; set token_free_persist_blocks to the snapshot cycle when it is
still −1; add min_registry_size (default 3); add survival_min_producers and
spine_late_vote_after_seconds when named; add rule.<name> and rule_off.<name> entries.
Rule activation. The heights themselves (29).
Rejections and errors. The bounds of §10.
Vector (computed from the shipped files). The TestNet file's committed map has 208
entries (81 base + min_registry_size + survival_min_producers + 125 rules); the DevNet file's
209 (it also names spine_late_vote_after_seconds); the mainnet template's 207 (neither named).
The consensus_parameters rows written: TestNet 205 (the 208 entries less the three names without a
row), DevNet 206, the mainnet template 204 (§13). Invalid input: "score_climb_ratio": 0 → refused (§10, score_climb_ratio ≥ 1); a
rule_activation entry "canonical_account_form": 0 (a misspelt name) → refused
"rule_activation names no rule of this binary: canonical_account_form".
Test cases · §2
5 cases · 2 valid · 3 invalid · 1 reference
The committed parameter maps of the shipped files
TestNet: 81 + min_registry_size + survival_min_producers + 125 rules; DevNet also names spine_late_vote_after_seconds; the mainnet template names neither.
A stated value: there is nothing to compute. A compatible node shows the same value.
- testnet_entries
208- devnet_entries
209- mainnet_template_entries
207- base_parameters
81- rules
125
A score_climb_ratio of 0 is refused
Loading the test widget…
A rule_activation entry naming no rule (a misspelt name) is refused
Loading the test widget…
The correctly spelt name builds
Loading the test widget…
A rule_activation value that is not an integer is refused
Loading the test widget…
Defects to match. (1) The committed value of coinbase_total_distribution (the config's number,
3,333,333,333,333,333 on every live config) and the stored value (the derived pool, §8) differ by
design; an implementation recomputing the config hash must use the config's number and one reading
the pool must use the stored one. node_operating_balance (1,000,000,000 on every live config) is
not in consensus_parameters; it enters the hash through NOB: (§3 step 8). (2)
exit_cooldown_blocks must be at least 2 × score_unit_floor_blocks; a config that sets the DevNet
value 1,680 without the DevNet unit floor of 120 is refused. (3) A main file that omits
receipt_lifecycle but names spine_snapshot_min_height takes that value as
main_snapshot_min_height (an old spelling the builder still honours); every shipped file names
receipt_lifecycle, so the fallback never fires on them.
3. The config hash and the genesis hash
Purpose. The chain's identity: a 32-byte digest of the whole configuration, and the block-0 hash derived from it.
Output and effect. config_hash (32 bytes, stored in chain_metadata) and genesis_hash
(32 bytes, block 0's block_hash, stored in chain_metadata and in genesis-hash.txt of a
release bundle; compared at handshake; the signing domain of 02). id of block 0 = the
little-endian i64 of the first 8 hash bytes (05 §4).
How to compute it. config_data is the concatenation below; all integers little-endian;
str(s) = LE32(len) ‖ bytes; strings are the config's UTF-8 text verbatim; "sorted" = byte-wise
order of the sort key.
str(chain_id).- For each committed parameter of §2 in name order (byte-wise):
str(name) ‖ LE64(value)— the 81 base names,min_registry_size,survival_min_producersandspine_late_vote_after_secondswhen named, everyrule.<name>and everyrule_off.<name>. LE32(count of accounts); then for each account sorted by its address text: the 32 decoded key bytes (01§5, the raw key without type prefix) ‖LE64(balance).LE32(count of nodes); for each node sorted by its node key text: 32 key bytes ‖ 32 owner key bytes.- For each genesis token sorted by
token_id:LE64(token_id) ‖ LE64(decimals) ‖ LE64(total_supply) ‖ str(symbol) ‖ str(chain) ‖ str(asset) ‖ str(deposit_address), wheredecimalsdefaults to 8,assetto"native",chainanddeposit_addressto"", andtotal_supply, when the config omits it, is the sum of the token'sallocationsplus every account'sbalances[symbol]. A file whoserule_activationlists a rule of bundle 601 or later (every shipped file) appends‖ str(name) ‖ str(issuer)to each token:namedefaults to the symbol;issueris the address text of the firstallocationsholder (or ofholder), else of the first entry ofaccountsin file order, else"", verbatim. An older file appends nothing. - Every token balance, as a map keyed by (holder address text, token_id), summing
allocationsand the accounts'balances(symbols that name no genesis token are skipped), iterated in key order:LE32(len(holder)) ‖ holder ‖ LE64(token_id) ‖ LE64(amount). No count prefix. The apps treasury's token balances are not in this map. - If any vesting entry exists:
LE32(n)then each entry sorted by (funder text, recipient text, token_id):str(funder) ‖ str(recipient) ‖ LE64(token_id) ‖ LE64(per_fire_amount) ‖ LE64(interval_seconds) ‖ LE32(remaining_fires) ‖ LE64(cliff_seconds) ‖ LE32(cancel_policy) ‖ LE32(funding_mode)(the two 32-bit fields are signed i32). - Registry seeds, raw text with no length prefixes, in this order:
"TS:" ‖ decimal(total_supply)(the config's value or the default 3,333,333,333,333,333),"NOB:" ‖ decimal(node_operating_balance),"GTH:" ‖ decimal(genesis_token_holder_zbc)(default 10,000,000,000) — the three effective values as decimal text, always present; then"RA:" ‖ addresswhenrelease_authorityexists;"PA:" ‖ addresswhenpage_authorityexists;"TR:" ‖ addresswhentreasuryexists;"MM:" ‖ addresswhenmarket_makerexists; the address is the config's text verbatim;"GR:" ‖ version ‖ manifest_hash ‖ release_addresswhengenesis_releaseexists; for each entry ofgateways, thenarchival_nodes, thenrelays, in file order:tag ‖ key ‖ owner_account ‖ domain ‖ urlwith tags"GW:","AR:","RL:"and the key fieldgateway_key/node_public_key/relay_key; a file that lists a rule of bundle 601 (step 5) appends a relay's owngateway_keyafter itsurl, an older file does not; missing fields are""; then, whenapps_treasuryexists,"GT:"followed by, for each symbol in byte order,symbol ‖ ":" ‖ the value's JSON text(an integer prints as its decimal digits). config_hash = SHA3-256(config_data).genesis_hash = SHA3-256(LE32(1) ‖ LE32(0) ‖ LE64(timestamp) ‖ 32 × 0x00 ‖ config_hash)— version 1, height 0, the main file'stimestamp, an all-zero previous hash.
Rule activation. None.
Rejections and errors. None at this step; a mismatch shows up as handshake refusal (27).
Vector (computed by an independent implementation of this section from the shipped TestNet
pair; run on the same file with the 24 rules of bundle 601 and survival_min_producers removed, the
same implementation gives config_hash 0f5d5ffa…cf2b and genesis_hash e003e4e3…2871, the
value the reference builder wrote for that earlier file, so it reproduces the builder byte for
byte; that hash is the vectors' G of 02 §1, and the genesis-hash.txt shipped beside the
TestNet file still carries it, while the file as shipped builds to the hash below). Input: the
TestNet's genesis-config.json and spine-genesis-config.json (208 committed parameters, 61
accounts, 11 nodes, 14 tokens, 378 token balances, 6 vesting entries, 25 registry seeds) →
config_hash b4d46ec1c521cbd143109591bdc5188c76e120779a048f858a5b2c29125ab381. Step 10 with the
file's timestamp 1,793,509,027: SHA3-256(01000000 00000000 a3c6e66a00000000 00×32 b4d46ec1…b381) →
genesis_hash 3a2897e7c5ad6143429bab33a92d14d11ffd6fc281f2b62a6fd6b49c183b863d, block 0's
id 4,855,352,938,787,711,034. The DevNet pair (209 committed parameters) → config_hash
442a9ea5…b9d6, genesis_hash a37b1692ec47c7b17a7f9cb4c13cc8a73a1d5e843565a5733b9da2a544df99f8,
id −5,636,457,327,242,085,469; the mainnet template (207) → config_hash 180875c0…1f4e,
genesis_hash bc589a2aadbd9d8bc38a446d879a7512507c7a569afc4e249af3a405e006a92f. A launch restamps timestamp, which
changes step 10 and the genesis hash but not the config hash; the live value is what
GET /api/v1/node/info reports. Invalid input: the TestNet file with one account's balance
changed by one unit → another config_hash, another genesis_hash, and every peer of the chain
refuses the handshake.
Test cases · §3
10 cases · 10 valid · 1 reference
The shipped TestNet pair: config hash, genesis hash and spine genesis block
Loading the test widget…
The shipped DevNet pair
Loading the test widget…
The mainnet template
Loading the test widget…
The TestNet pair without its bundle-601 rules: the older layout, the vectors' G
Loading the test widget…
The config hashes of the shipped files
testnet_stripped: the TestNet file with the 24 rules of bundle 601 and survival_min_producers removed, whose builder hash is the vectors' G (02 §1).
A stated value: there is nothing to compute. A compatible node shows the same value.
- testnet
b4d46ec1c521cbd143109591bdc5188c76e120779a048f858a5b2c29125ab381- devnet
442a9ea5cd5ab99f49ecaf80cc581e1961485e3909a6ab1a3c5c81380eb4b9d6- mainnet_template
180875c0f239e4a219c88670a7adea49ff151adffe62045c7fa2ab0e67561f4e- testnet_stripped
0f5d5ffa2db1f8ecdd128d051d0a03236a8eed73b55fdfc63ffadd786259cf2b
The TestNet genesis hash from the file's timestamp and config hash
Loading the test widget…
The DevNet genesis hash
Loading the test widget…
The mainnet template's genesis hash (timestamp 1,788,220,800)
Loading the test widget…
The stripped TestNet file's genesis hash is the vectors' G
Loading the test widget…
A different config hash gives a different genesis hash
Loading the test widget…
Defects to match. spine_chain_id is a printed label that nothing in the node reads: it is not
committed. A role entry's note and an account's label are not committed either.
4. The genesis block of the main chain
Purpose. Block 0 as a block.
Inputs. timestamp, genesis_hash.
Output and effect. A main_block row (05 §1) with: height 0, id from the hash,
block_hash = genesis_hash, previous_block_hash 32 × 0x00, timestamp, block_seed 64 × 0x00,
block_seed_proof 80 × 0x00, block_signature 64 × 0x00, cumulative_difficulty "0",
payload_length 0, payload_hash 32 × 0x00, blocksmith_public_key 32 × 0x00, total_amount 0,
total_fee 0, total_coinbase 0, version 1 (not a bundle id; block 0 is never signalled, 05 §8), merkle_root 32 × 0x00, merkle_tree empty, reference_block_height 0, no transactions, no
receipts. Its hash is not SHA3-256 of its bytes (05 §4 does not hold at height 0); block 1's
previous_block_hash is this value, block 1's seed is the VRF output over SHA3-256(64 zero bytes),
and block 1's cumulative difficulty is "0" plus its own increment.
How to compute it. As listed; §3 for the hash.
Rule activation. None.
Rejections and errors. A node refuses to start without a block at height 0
("No genesis block found. Use genesis-builder to create genesis.db with chain configuration.");
block validation never runs on block 0 (the seed, signature and difficulty checks exempt height 0,
05 §10).
Vector (computed, the shipped TestNet file). GET /api/v1/blocks/height/0 answers height
0, version 1, timestamp 1,793,509,027, previous_block_hash, block_seed, block_seed_proof
(80 bytes), block_signature, blocksmith_public_key all zero, cumulative_difficulty "0",
block_hash 3a2897e7…863d (§3). Block 1 then carries previous_block_hash 3a2897e7…863d,
cumulative_difficulty "1000000" when its blocksmith is first in its round, total_coinbase 0,
and a seed over alpha = SHA3-256(64 × 0x00) = 070fa1ab…81e0 (05 §5).
Test cases · §4
3 cases · 2 valid · 1 invalid · 3 reference
Block 0 of a chain built from the shipped TestNet file
GET /api/v1/blocks/height/0.
A stated value: there is nothing to compute. A compatible node shows the same value.
- height
0- version
1- timestamp
1793509027- previous_block_hash
0000000000000000000000000000000000000000000000000000000000000000- block_seed
00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000- block_seed_proof
0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000- block_signature
00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000- blocksmith_public_key
0000000000000000000000000000000000000000000000000000000000000000- cumulative_difficulty
0- block_hash
3a2897e7c5ad6143429bab33a92d14d11ffd6fc281f2b62a6fd6b49c183b863d
Block 1 after that block 0
cumulative_difficulty 1000000 when its blocksmith is first in its round; the seed is over SHA3-256(64 x 0x00) (05 §5).
A stated value: there is nothing to compute. A compatible node shows the same value.
- previous_block_hash
3a2897e7c5ad6143429bab33a92d14d11ffd6fc281f2b62a6fd6b49c183b863d- cumulative_difficulty
1000000- total_coinbase
0- seed_alpha
070fa1ab6fcc557ed14d42941f1967693048551eb9042a8d0a057afbd75e81e0
A node refuses to start without block 0
A stated value: there is nothing to compute. The statement is a refusal: the exact text a compatible node answers.
- refusal
No genesis block found. Use genesis-builder to create genesis.db with chain configuration.
Defects to match. None.
5. Accounts, tokens and token balances at height 0
Purpose. The opening balances.
Inputs. accounts[], genesis_tokens[], genesis_token_holder_zbc, apps_treasury; rule
genesis_rent_clock as the config lists it; the snapshot cycle.
Output and effect. State rows at height 0 (07 gives each object's full shape):
- For every entry of
accounts: anaccount_balancerow keyed by the typed 36-byte address (00000000 ‖ key,01§4) withbalance = spendable_balance = balance,pop_revenue0,latest1. A configured balance of 0 still creates the row. - For every genesis token, sorted as listed: a
tokenrowtoken_id,issuer= the firstallocationsholder, else the first entry ofaccounts(typed),symbol,name(default = symbol),decimals(default 8),total_supply(explicit, or the sum of §3 step 5),backing_asset0,backing_amount0,flags8 (bit 3: unbacked mirror of a foreign asset),persist_height0 (never expires,14), height 0, latest 1. Every token with a non-emptychainand a non-emptydeposit_addressalso gets abridge_coinrow (token_id,symbol,chain,asset("native"when empty),deposit_address,decimals); a token with a chain but no deposit address gets none. - One
account_token_balancerow per (holder, token) summingallocationsand the accounts'balances, typed address,balance = spendable = amount, height 0, latest 1. - A holder of a token balance that is not in
accountsreceives a ZBC account with the stipendgenesis_token_holder_zbc(default 100 ZBC), counted into the premine. apps_treasury: the apps pool account00000000 ‖ "ZBCAPPS" ‖ 25 × 0x00(01§7) gets a ZBC row with theZBCamount (counted into the premine) and one token-balance row per other symbol, which must be a genesis token.- The rent clock (rule
genesis_rent_clocklisted at 0, or absent from a config whose binary defaults it to 0): after every account row is written, everyaccount_balancerow withlatest = 1, a positive balance,rent_due_height0 and an address that is not rent-exempt (the three system pools, the apps pool, every type-10ZBS_address,01§7) getsrent_due_height =the snapshot cycle (one cycle after height 0), in place. A genesis that lists the rule above 0 leaves every row at 0 (the rule arms them in the block at its height,13). Every account row, the node accounts of §6 included, is written before this step, so a node account funded with its operating balance is armed too.
How to compute it. As listed; typed addresses throughout.
Rule activation. genesis_rent_clock: at 0 on every live chain.
Rejections and errors. An undefined coin in an account's balances is skipped with an error
print; an undefined coin in apps_treasury fails the build. A role key creates no account row of its
own: only an accounts entry for its address does (allowed for the release authority up to 1,000
ZBC, §10).
Vector (computed from the shipped TestNet file; every row type listed).
14 token rows (flags 8, persist_height 0, decimals 8); 4 bridge_coin rows (ZBTC, ZETH,
ZUSDC, ZUSDT: the tokens with both a chain and a deposit_address), the first
(4, "ZBTC", "bitcoin", "native", "bc1q02eahpuu87g85zka8eapmwzc0rv56yw2s226c4", 8); 392
account_token_balance rows (the 378 committed balances + the apps treasury's 14); 73
account_balance rows (61 accounts + 11 node accounts + the apps pool), none of them 32 bytes long;
65 rows with rent_due_height 172,800 (the TestNet cycle: the 54 accounts funded above 0 and the
11 node accounts) and 8 at 0: seven accounts funded with 0 and the apps pool
000000005A42434150505300…00 (1,000,000,000,000,000 = 10,000,000 ZBC, rent-exempt). The mainnet
template gives 11 bridge_coin rows (every token but ZUSD, ZEUR and ZCNY names a deposit address
there).
Test cases · §5
2 cases · 2 valid · 2 reference
The rows the builder writes for the shipped TestNet file
A stated value: there is nothing to compute. A compatible node shows the same value.
- token_rows
14- bridge_coin_rows
4- first_bridge_coin
4 ZBTC bitcoin native bc1q02eahpuu87g85zka8eapmwzc0rv56yw2s226c4 8- account_token_balance_rows
392- account_balance_rows
73- rent_due_172800
65- rent_due_0
8- apps_pool
000000005a42434150505300000000000000000000000000000000000000000000000000- apps_pool_balance
1000000000000000
The mainnet template's bridge_coin rows
Every token but ZUSD, ZEUR and ZCNY names a deposit address there.
A stated value: there is nothing to compute. A compatible node shows the same value.
- bridge_coin_rows
11
Defects to match. None.
6. The node registry, node accounts and scores at height 0
Purpose. Who may produce blocks from block 1, and what they start with.
Inputs. nodes[], node_operating_balance, default_participation_score,
node_admission_genesis_delay.
Output and effect. For each node in file order:
node_id= the little-endian i64 of the first 8 bytes of the node key with the sign bit cleared (& 0x7FFFFFFFFFFFFFFF); a result of 0 takes the next value of a counter starting at 1.- A
node_registryrow:id,node_public_key(32 bytes),account_address=00000000 ‖ owner key(36 bytes),registration_height0,locked_balance0,registration_status0 (Registered; 1 = Queued),latest1,height0. The node's network address is not in genesis (node.conf). - The node's own typed account
00000000 ‖ node_public_keywithnode_operating_balance(default 1,000,000,000 = 10 ZBC) as balance and spendable, counted into the premine. - A
participation_scorerownode_id,score = default_participation_score, latest 1, height 0: 2,000,000,000,000 = 20 % of the maximum, so every registered node starts at 20 %, genesis registered nodes included, and a key that registers later also starts there (36). - No liveness, roll-call or exit row is written: a genesis registered node starts unseen, not missing, and has
answered no roll call; its roll call (type 61) is due in blocks 1 ..
roll_call_blocks(09). - One
node_admission_timestamprow:timestamp = genesis timestamp + node_admission_genesis_delay, height 0, latest 1 (09). - A
network_topologyrow for period 0 (28): the genesis hash as the seed and the node count.
How to compute it. As listed.
Rule activation. None.
Rejections and errors. Two genesis node keys with one node id fail the build (§10).
Vector (computed from the shipped TestNet file). Input: the nodes[] entry with key
ZNK_AKSQOGOA_…_FSRL4CNJ = 02A50719C01D3B81…2CA2 → LE i64 of 02a50719c01d3b81 with the sign
bit cleared = 88,697,328,554,714,370, the node_id GET /api/v1/registry/nodes reports; owner
account 00000000BCCB8082…B4D6, registration_height 0, locked_balance 0. Key
EB89F581…AD65 (ZNK_5OE7LAMS_…) → 1,417,521,806,099,974,635; the file's first entry,
715EA8E2…FBAC, → 4,016,115,710,591,262,321. The build has 11 registry rows, 11 score rows of
2,000,000,000,000, 11 node accounts of 1,000,000,000, one admission row 1,794,113,827 =
1,793,509,027 + 604,800 (the file's timestamp; a restamp moves it), and a topology row
(0, 3a2897e7…863d, 11).
Test cases · §6
7 cases · 7 valid · 1 reference
A genesis registered node's node id: its key's first 8 bytes, sign bit cleared
Loading the test widget…
A second registered node's node id
Loading the test widget…
The same id from the key's ZNK_ text
Loading the test widget…
The node id of the file's first nodes[] entry
Loading the test widget…
The sign bit is cleared: a key starting ff..ff gives 2^63 - 1
Loading the test widget…
A key whose id would be 0 takes the counter
Loading the test widget…
The registry rows at height 0 of the shipped TestNet file
The admission row is the file's timestamp + 604,800; a restamp moves it.
A stated value: there is nothing to compute. A compatible node shows the same value.
- registry_rows
11- score_rows
11- score
2000000000000- node_accounts
11- node_account_balance
1000000000- admission_timestamp
1794113827- topology_row
0 3a2897e7c5ad6143429bab33a92d14d11ffd6fc281f2b62a6fd6b49c183b863d 11- owner_account
00000000bccb80820d3e3fce6e62f1c283acf6b0ab884a937af47120de2ffe88a393b4d6- registration_height
0- locked_balance
0
Defects to match. The period-0 topology seed the builder writes (the genesis hash) is dead: the
node rewrites the period-0 row from block 0's seed (64 zero bytes) when it builds the scramble
(23, 28). The node-id derivation collides for two keys sharing their first 8 bytes, or
differing only in the bit the id clears; the builder refuses such a genesis (§10) and after genesis
a colliding registration is refused at admission and is a paid no-op in a block (09).
7. The spine genesis block
Purpose. Block 0 of the spine chain and the initial spine signers.
Inputs. The spine file: genesis_timestamp, version, initial_blocksmiths; spine_enabled.
Output and effect. When spine_enabled is 1: a spine block (25) at height 0 and one
spine_public_key row per listed blocksmith (node_public_key, node_id as §6,
public_key_action 0 = AddKey, main_block_height 0, latest 1, height 0). Every listed blocksmith
must be one of the main file's nodes, else the build fails.
How to compute it.
payload= for each blocksmith key sorted by its 32 bytes:LE32(0) ‖ key ‖ LE32(0) ‖ LE32(0)(main height, key, action AddKey = 0, spine height), 44 bytes each.payload_hash = SHA3-256(payload)(of the empty string when there are no keys),payload_length = len(payload).blocksmith_public_key= the key whose text sorts first amonginitial_blocksmiths(string order, so aZNK_3…precedes aZNK_A…); all zeros when the list is empty.- The header of
05§2 withversion(spine file, default 1),timestamp = genesis_timestamp(default the main timestamp), totals 0, the payload fields of step 2, seed 64 × 0x00, previous hash 32 × 0x00, no seed proof, signature 64 × 0x00;block_hash = SHA3-256of the 268 signed bytes (05§4 holds here);idfrom the hash;cumulative_difficulty"0",merkle_root32 × 0x00,reference_block_height0.
Rule activation. None.
Rejections and errors. A blocksmith key that does not decode, or is not a genesis node of this chain, fails the build.
Vector (computed independently from the shipped TestNet spine-genesis-config.json). Input:
the 11 initial_blocksmiths, timestamp 1,793,509,027, version 1 → payload_length 484 = 11 × 44,
payload_hash 2098ca36d85ba3c06988129c4e1a68a0e77473850d04bf9002680f0980764485,
blocksmith_public_key eb89f581920cac9343663a33911d76cef5c89390f25865651d902792b881ad65 (the
decode of ZNK_5OE7LAMS_…, the first key in text order), the 268 signed bytes hash to
block_hash 7cd929c4d52d9c9455ed179d24a65f90ecbf3d1a3e1214a19611635791b3545c, id
−7,738,259,663,586,993,796; GET /api/v1/spine/blocks/0 reports these on a chain built from the
file as shipped (a restamp changes the timestamp and so the hash). The DevNet spine file →
payload_hash 843de4b2…793b, blocksmith dfdbe4a8…67aa, block_hash 5876b908…eef3. Invalid
input: a spine file naming a key that is not in the main file's nodes → the build fails.
Test cases · §7
5 cases · 4 valid · 1 invalid · 2 reference
The TestNet spine genesis block from its 11 initial blocksmiths
Loading the test widget…
The DevNet spine genesis block
Loading the test widget…
The spine block 0 a chain built from the shipped TestNet file serves
GET /api/v1/spine/blocks/0; a restamp changes the timestamp and so the hash.
A stated value: there is nothing to compute. A compatible node shows the same value.
- block_hash
7cd929c4d52d9c9455ed179d24a65f90ecbf3d1a3e1214a19611635791b3545c- blocksmith_public_key
eb89f581920cac9343663a33911d76cef5c89390f25865651d902792b881ad65- timestamp
1793509027
A spine genesis with no blocksmiths hashes the empty payload and names no blocksmith
Loading the test widget…
A spine file naming a key that is not one of the chain's nodes fails the build
A stated value: there is nothing to compute. The statement is a refusal: the exact text a compatible node answers.
- refusal
*
Defects to match. The blocksmith of the spine genesis block is chosen by text order while the
payload is in byte order; both must be reproduced. spine_chain_id is not committed anywhere.
8. The coinbase ceiling
Purpose. How much ZBC the chain may ever mint after genesis.
Inputs. total_supply (default 3,333,333,333,333,333 = 33,333,333.33333333 ZBC), everything
credited at height 0.
Output and effect. pool = total_supply − premine − nodes × node_operating_balance, where
premine = Σ accounts[].balance + token-holder stipends + the apps treasury's ZBC + Σ over
mint-mode (funding_mode 0) ZBC vesting entries of per_fire_amount × remaining_fires (pull-mode
entries move existing balances and are not added). A negative pool fails the build. The pool is
written to chain_metadata.coinbase_total_distribution, chain_metadata.coinbase_total_supply
and consensus_parameters.coinbase_total_distribution; the node reads the first (then the
second; then a compiled 33,000,000 ZBC) as the ceiling of the emission curve that fixes every
block's total_coinbase (05 §8, 21). The configured total_supply itself is written to
chain_metadata.total_supply, the bound above which a SendZBC amount is refused (08). The
builder re-sums the written account rows and refuses a genesis where anything credited was not
counted, and one where the three stored copies disagree.
How to compute it. As stated, in i64.
Rule activation. None.
Rejections and errors. "premine (P) exceeds total_supply (T)"; the uncounted-credit and
three-copies checks.
Vector (computed from the shipped TestNet file). total_supply 3,333,333,333,333,333;
premine 1,265,040,102,000,000 (the 61 balances, the apps treasury's 10,000,000 ZBC and the two
mint-mode vesting entries of 52 × 100 ZBC; no stipend, every token holder is in accounts); node
balances 11 × 1,000,000,000 → pool 2,068,282,231,333,333, written to
chain_metadata.coinbase_total_distribution, coinbase_total_supply and
consensus_parameters.coinbase_total_distribution; chain_metadata.total_supply
3,333,333,333,333,333. The DevNet file gives the same numbers. Invalid input: the
same file with one account funded at 3,333,333,333,333,333 → "premine (…) exceeds total_supply (3333333333333333)".
Test cases · §8
2 cases · 1 valid · 1 invalid
The coinbase pool of the shipped TestNet (and DevNet) file
Loading the test widget…
A premine of the whole supply leaves nothing for the 11 node accounts
Loading the test widget…
Defects to match. None (the ceiling is committed through TS:, §3).
9. Everything else at height 0
Purpose. The remaining rows an implementation must have before block 1.
Inputs. vesting[], release_authority, genesis_release, gateways[], archival_nodes[],
relays[]; the rule list.
Output and effect.
- Vesting (
08): onetrigger_schedulerow per entry, in file order with indexi:trigger_id= the little-endian i64 of the first 8 bytes ofSHA3-256(funder36 ‖ recipient36 ‖ LE64(token_id) ‖ LE64(i) ‖ "VEST")with the sign bit cleared (0 →i + 1);owner= funder,recipient, typed 36-byte forms;amount0,fire_height0,status0,fire_time = timestamp + cliff_seconds,interval_seconds,remaining_fires,end_time0,per_fire_amount,token_id,funding_mode,locked_remaining = per_fire × firesin mode 0 and 0 in mode 1,cancel_policy,kind2 (vesting),consecutive_skips0, height 0. No balance is credited to anyone at genesis; the schedule pays the recipient tranche by tranche (08,22). A pull-mode funder must hold its total principal at genesis, per token, or the build fails. - Release authority (
17): arelease_authorityrow id 1,authority_address= the configured address (typed), no pending address, height 0. Page authority, treasury and market maker: committed asPA:,TR:,MM:(§3); no row of their own. Genesis release: arelease_registryrecordversion, 32-bytemanifest_hash,release_address(typed), not revoked (absent on both live chains). - Gateways:
gateway_key(32 bytes), owner (typed),domain,url,locked_stake0,last_heartbeat_height0,status0. Archival nodes: node key, owner, domain, url, status 0. Relays: relay key, owner, boundgateway_key(may be empty), domain, url, status 0. Malformed entries are skipped with an error print, not fatal. - The builder creates every table the node uses (
07); a node creates missing tables itself at start, so the set of tables is not part of the protocol. It seeds thefee_scalerow(1,000,000, height 0, latest 1)so the fee vote counts from the first snapshot cycle (04§3), and writes arule_activation_recordrow for every rule listed in the config (its on-height), carrying the genesis hash (the node checks these against its binary at start,29); neither is committed to the genesis hash. Nosurvival_staterow is written at height 0: height 0 has no survival flag (false). The flag of block 1 is computed from that and the blocksmiths of the blocks before it, of which there are none, so on a chain whose genesis namessurvival_min_producersabove 0 block 1 is in survival mode (its row is writtentruewhen it is applied) and the chain stays in it until the window holds that many distinct blocksmiths (19): governance and bridge transactions are refused meanwhile, payments and registrations are not (04§6).
How to compute it. As listed.
Rule activation. None.
Rejections and errors. As listed.
Vector (computed from the shipped TestNet file). Six trigger_schedule rows at height 0, all
kind 2; one release_authority row (id 1, the typed address of ZBC_PWF5RJA5_…); one gateway,
one archival node and one relay (domain zoobc.network and relay.zoobc.network, owner the typed
account of ZBC_5VJEDDEI_…); fee_scale [(1000000, 0, 1)]; 125 rule_activation_record rows
(the 125 listed rules); no survival_state row, and block 1 in survival mode
(survival_min_producers 5).
Test cases · §9
1 case · 1 valid · 1 reference
The other rows the builder writes for the shipped TestNet file
A stated value: there is nothing to compute. A compatible node shows the same value.
- trigger_schedule_rows
6- trigger_kind
2- release_authority_rows
1- gateways
1- archival_nodes
1- relays
1- registry_domain
zoobc.network- relay_domain
relay.zoobc.network- fee_scale
1000000 0 1- rule_activation_record_rows
125- survival_state_rows
0- block_1_in_survival_mode
true
Defects to match. None.
10. Build-time invariants
Purpose. The checks that make an unbuildable chain fail before it exists; an implementation that builds its own genesis should apply them, one that imports the reference's database needs them only to understand the live values.
Inputs. The parameters of §2, the counts of nodes and accounts.
Output and effect. Fatal unless noted:
- When
main_snapshot_interval > 0:main_snapshot_min_height > 0;main_snapshot_interval ≥ 3 × main_snapshot_min_height;max(max(100, 2 × nodes) + 1, receipt_lifecycle) ≥ main_snapshot_interval + main_snapshot_min_height; an explicitsnapshot_manifest_expiration_seconds≥3 × interval × block_time_interval. max_rollback_height ≤ 1,440(MIN_ROLLBACK_BLOCKS);main_snapshot_min_height ≥ max_rollback_height + 20(the depth margin);receipt_lifecycle = 0or≥ 2 × main_snapshot_interval + main_snapshot_min_height.- Role keys: every present role entry (
release_authority,page_authority,treasury,market_maker) decodes, no two are the same key, the release authority receives at most 1,000 ZBC (itsaccountsrows plus ZBC vesting to it, saturating) and no coin (token balances, allocations, token vesting), and the page authority receives nothing; a missing role is only a warning. min_registry_size ≥ 3, and on a chain whose id containsmainnetbothmin_registry_size ≥ 7and at least 7 nodes.survival_min_producers: 0 .. 10,000 when named; on a chain of two or more genesis registered nodes at most their number − 2 ("survival_min_producers (N) must not exceed node_count - 2 (M)."); on a one-node chain at most 1 ("survival_min_producers (N) must be 1 on a one-node chain, or survival mode could never end."). Not fatal: a genesis withmin_registry_size ≥ 7that does not name it builds with the warning"WARNING: survival_min_producers is not set: survival mode is OFF on this chain. …".spine_late_vote_after_seconds: 0 .. 31,536,000 when named (§1).spine_signature_collection_timeout > 0(the signing commitment of a registered node that gave its spine signature is released only after the window closes,25);max_block_size_bytes ≥ 4,096(a header and the receipts a block carries must fit,05§10.1);main_snapshot_min_height ≥ max(40, batch_receipt_lookback_height)("main_snapshot_min_height (N) must be at least M, the published-receipt lookback.").- Neither
turn_window_multipliernormax_concurrent_turnsis present; everyrule_off.<name>names a retirable rule of this binary and sits above its on-height. 1 ≤ bridge_quorum_num ≤ bridge_quorum_den,den > 0;1 ≤ oracle_quorum ≤ storage_replication;0 < node_admission_min_delay ≤ node_admission_max_delay;node_admission_base_delay > 0;node_admission_genesis_delay > 0.- Minimums:
max_assigned_peers ≥ 2,cumulative_difficulty_divisor ≥ 1,decrease_score_divider ≥ 1,block_time_interval ≥ 1,min_block_interval ≥ 1,dataset_storage_cost_per_mib ≥ 1,storage_oracle_multiplier_ppm ≥ 1,token_persist_period_cost ≥ 1,token_free_persist_blocks ≥ 1,account_rent_period_cost ≥ 1,account_group_max_members ≥ 2, the three coinbase parameters ≥ 1,max_node_admittance_per_cycle ≥ 1,receipt_batch_size ≥ 1,max_priority_blocksmiths ≥ 1,max_transactions_per_block ≥ 1,max_rollback_height ≥ 1; at least one node; every account address and owner decodes. - No two genesis node keys share a node id (§6):
"genesis node keys A and B share node id N (the same key listed twice): every genesis registry node needs its own id."or"genesis node keys A and B share node id N (a node's id is its key's first 8 bytes, sign bit cleared): every genesis registry node needs its own id.". score_loss_per_unit_bps1 .. 10,000;score_unit_floor_blocks ≥ 1;score_climb_ratio ≥ 1;maturity_units ≥ 0;liveness_miss_limit ≥ 1;node_lock_at_risk_bps0 .. 10,000;admission_genesis_seat_cap ≥ 1;roll_call_blocks ≥ 2;exit_cooldown_blocksfrom2 × score_unit_floor_blocksto 4,294,967,295;min_node_registration_balance_ceiling ≥ 1;queue_median_fraction_bps0 .. 10,000; each of the eight votable prices (storage_oracle_multiplier_ppm,dataset_storage_cost_per_mib,account_rent_period_cost,token_persist_period_cost,gateway_registration_cost,exchange_taker_fee_bps,market_creation_cost,min_node_registration_balance) within its governed floor and ceiling (17; the queue minimum's ceiling ismin_node_registration_balance_ceiling);snapshot_reward_share_ppm0 .. 500,000;app_open_timeout_blocks1 .. 4,294,967,295;app_unused_share_bps0 .. 10,000;max_priority_blocksmiths ≤10 (the stall threshold: above it a demoted blocksmith's block would count as a stall and charge no misses);spine_fallback_periods ≥ 1.- Warnings only: fewer nodes than
max_priority_blocksmiths; fewer than 50 nodes; no accounts;batch_receipt_lookback_height ≥the receipt retention;min_payload_persistence_blocks >the snapshot cycle; a cycle under a day; a missing role key; fewer nodes thanmin_registry_size(every registry-wide decision stays frozen until that many registered nodes of distinct owners register,17§1,34);survival_min_producersnot named on a genesis withmin_registry_size ≥ 7.
How to compute it. As listed.
Rule activation. None.
Rejections and errors. The messages name the check and the values; nothing is written.
Vector (computed). The live files pass. DevNet: max_rollback_height 60 ≤ 1,440,
main_snapshot_min_height 80 ≥ 60 + 20, receipt_lifecycle 1,440 ≥ 2 × 240 + 80 = 560,
main_snapshot_interval 240 ≥ 3 × 80, exit_cooldown_blocks 1,680 ≥ 2 × 120, 11 registered nodes so
survival_min_producers 5 ≤ 11 − 2 = 9. TestNet and mainnet: rollback 720 ≤ 1,440, min height 760
≥ 740, receipt 518,400 ≥ 2 × 172,800 + 760 = 346,360, interval 172,800 ≥ 3 × 760, exit cool-down
40,320 ≥ 2 × 2,880, survival_min_producers 5 ≤ 11 − 2; the mainnet template, which names no
survival_min_producers, builds with the warning (min_registry_size 7). Invalid inputs: the
DevNet file with survival_min_producers 10 (11 registered nodes) → "survival_min_producers (10) must not exceed node_count - 2 (9)."; a one-node file with survival_min_producers 2 →
"survival_min_producers (2) must be 1 on a one-node chain, or survival mode could never end.".
The TestNet file with "max_block_size_bytes": 4095 → "block size: max_block_size_bytes (4095) must be at least 4096 (a header and the receipts a block carries)."; with
"main_snapshot_min_height": 700 (< 720 + 20) → refused ("main_snapshot_min_height (700) must exceed max_rollback_height (720) by at least 20 blocks: …");
its spine file with "spine_signature_collection_timeout": 0 → "spine_signature_collection_timeout (0) must be > 0: a co-sign promise is released only after the window closes." (the text's "co-sign
promise" is the signing commitment; the spine file's
value overrides the main file's, so the check is on the spine file). Each exits 1.
Test cases · §10
10 cases · 3 valid · 7 invalid
The shipped TestNet parameters pass the build-time invariants
Loading the test widget…
The mainnet template, which names no survival_min_producers, builds
Loading the test widget…
The DevNet parameters pass the build-time invariants
Loading the test widget…
survival_min_producers above the registered nodes less two is refused
Loading the test widget…
A one-node file with survival_min_producers 2 is refused
Loading the test widget…
A max_block_size_bytes of 4095 is refused
Loading the test widget…
A main_snapshot_min_height of 700 is less than the rollback depth plus 20
Loading the test widget…
A main_snapshot_min_height below the published-receipt lookback is refused
Loading the test widget…
A spine_signature_collection_timeout of 0 is refused
Loading the test widget…
An exit cool-down of 1,680 blocks needs the DevNet unit floor of 120
Loading the test widget…
Defects to match. None.
11. How the node reads genesis
Purpose. What a running node takes from block 0 and the tables beside it.
Inputs. The database written by the builder (and copied to every node of a chain).
Output and effect. At start the node creates any missing tables and refuses to run unless
main_block has a row. It then reads: the consensus parameters by name from
consensus_parameters (20, 32; each reader has its own compiled fallback when a name is
missing; survival_min_producers absent reads 0 = off); the rule heights rule.<name> and
rule_off.<name> once at start, and the rule-edge records the builder wrote, which it checks
against its own binary and refuses to run on a disagreement (29); min_registry_size as the
resolution floor and the admission cap's bound (09, 34); chain_metadata.genesis_timestamp
(else block 0's timestamp) for the emission curve; the coinbase ceiling (§8); the
rewards-per-second and max-rewards-per-block keys (21); block 0's hash as the chain identity for
the handshake (27: a peer with a different or empty genesis hash is refused) and for transaction
signing (02). GET /api/v1/node/info reports genesis_hash (a node's also reports
spine_genesis_hash and spine_height).
How to compute it. Read, do not derive: the node never recomputes the config hash. Node-local: the node trusts the database it is given and does not check §3 on it; an implementation that imports a database checks §3 itself before trusting it.
Rule activation. None.
Rejections and errors. "No genesis block found. Use genesis-builder to create genesis.db with chain configuration." at start.
Vector (computed). On a chain built from the shipped TestNet pair, GET /api/v1/node/info
reports "genesis_hash":"3A2897E7C5AD6143429BAB33A92D14D11FFD6FC281F2B62A6FD6B49C183B863D" (§3,
upper-case hex), "spine_genesis_hash":"7CD929C4…545C" (§7), "signing_tag":"ZBC-TX",
"signing_version":2 and "node_version" as 0.6.1+ followed by the build's commit id; a
restamped launch reports its own two hashes.
Test cases · §11
1 case · 1 valid · 1 reference
A node of a chain built from the shipped TestNet pair reports its identity and signing domain
GET /api/v1/node/info; a restamped launch reports its own two hashes.
A stated value: there is nothing to compute. A compatible node shows the same value.
- genesis_hash
3A2897E7C5AD6143429BAB33A92D14D11FFD6FC281F2B62A6FD6B49C183B863D- spine_genesis_hash
7CD929C4D52D9C9455ED179D24A65F90ECBF3D1A3E1214A19611635791B3545C- signing_tag
ZBC-TX- signing_version
2- node_version
0.6.1+<the build's commit id>
Defects to match. None.
12. Launching a chain, and the live chains
Purpose. The operational facts an implementation's operator must know, and the identity of the live chains.
Inputs. The two files, the builder, a fleet.
Output and effect. Every node of a chain runs on a copy of one database built from one pair
of files; the timestamp is the only field meant to change between a staged bundle and the launch
(the reference's launch scripts restamp the main and the spine file alike), and changing it changes
both genesis hashes, so every node must rebuild from the same restamped files before block 1. Block 1
may come any time after the genesis timestamp (19), and the first node admission is possible from
timestamp + node_admission_genesis_delay (7 days on mainnet and TestNet). The roll call
(09): in blocks 1 .. roll_call_blocks (20) each genesis registered node sends a fee-free RollCall;
once at least half of the genesis registered nodes have answered, from block 2 a registered node that
has not answered is not drawn and earns nothing, and at block roll_call_blocks every registered
node that never answered leaves the registry (never below three registered nodes). A registered
node's answer is visible before the genesis time (every
node shows the RollCalls at height 0 in /api/v1/nodes, 31).
Both public chains launch from genesis on 0.6.1, each from its shipped pair with every rule at 0
and survival_min_producers 5, so both start in survival mode until five distinct blocksmiths
have produced (§9). The identities below are those of the files as shipped; the launch
restamps timestamp, and the live identity is what GET /api/v1/node/info reports:
| Chain | Shipped timestamp | Genesis hash of the shipped file | Spine genesis hash of the shipped file |
|---|---|---|---|
TestNet (zoobc-test) |
1,793,509,027 | 3A2897E7C5AD6143429BAB33A92D14D11FFD6FC281F2B62A6FD6B49C183B863D |
7CD929C4D52D9C9455ED179D24A65F90ECBF3D1A3E1214A19611635791B3545C |
DevNet (zoobc-dev) |
1,793,509,027 | A37B1692EC47C7B17A7F9CB4C13CC8A73A1D5E843565A5733B9DA2A544DF99F8 |
5876B908090A5BCA4BD735DD96A559FD8FBBE64C1419C053DE227BE3CACCEEF3 |
A chain built from 0.6.1 runs with the newest active bundle 601 from block 1 (05 §8): every
block it accepts carries version ≥ 601, and a later bundle reaches it only through the release
registry and the readiness gate (29).
Node settings are not genesis: nothing in node.conf is committed or read from the genesis
database. One of them changes what a node pays for at launch: require_signed_receipt_requests
(the [node] section; the node's default when the line is missing is false, 23, 30). Off, a
node still signs a receipt for a block or transaction request that carries no sender signature; on,
such a request earns nothing. Both relaunched chains run with it on from block 0: the reference
installer writes true into a new node.conf for every chain and adds true to a kept node.conf
that does not name the setting (a kept node.conf that names it keeps the operator's value), and
the relaunch tool's staging step sets it to true in every node's node.conf, replacing a false
an earlier installer wrote. Every 0.6.1 node signs its requests (23).
The release's spine pin (spine-pin.txt, "<height> <64 hex>", 30 §4b) names spine block 0 of
the shipped files. A new timestamp builds a new spine block 0 (§7), so the relaunch re-derives the
pin from the genesis each node has just built: the re-timestamp tool, run as a relaunch (at the
stage and again at the flip), writes 0 <spine block 0 of the genesis just built> whatever the pin
named before; run as a repair onto an existing chain, it stops before starting the node when a pin
at block 0 does not name the spine block 0 just built, and keeps a pin above block 0; an install
with an explicit genesis timestamp re-derives a block-0 pin the same way (30 §9a).
How to compute it. Build, distribute, start.
Rule activation. None: every rule is at 0.
Rejections and errors. None.
Vector (computed). The table above, from the shipped files by §3 and §7; a file restamped to
timestamp T gives genesis_hash = SHA3-256(01000000 00000000 LE64(T) 00×32 ‖ config_hash) with
the same config_hash, and a spine genesis block hashed over a header carrying T. The TestNet
release's spine pin is 0 7cd929c4…545c; after a relaunch to T it is 0 <the spine block 0 hash for T>. A repair run with a timestamp that is not the chain's, while the pin is at block 0 →
stopped, the node not started ("the spine pin does not name the genesis just built: T is not this chain's genesis timestamp.").
Test cases · §12
5 cases · 4 valid · 1 invalid · 4 reference
The two genesis hashes of the shipped files
Both chains launch from their shipped pair with every rule at 0 and survival_min_producers 5; the launch restamps timestamp.
A stated value: there is nothing to compute. A compatible node shows the same value.
- testnet_timestamp
1793509027- testnet_genesis_hash
3A2897E7C5AD6143429BAB33A92D14D11FFD6FC281F2B62A6FD6B49C183B863D- testnet_spine_genesis_hash
7CD929C4D52D9C9455ED179D24A65F90ECBF3D1A3E1214A19611635791B3545C- devnet_timestamp
1793509027- devnet_genesis_hash
A37B1692EC47C7B17A7F9CB4C13CC8A73A1D5E843565A5733B9DA2A544DF99F8- devnet_spine_genesis_hash
5876B908090A5BCA4BD735DD96A559FD8FBBE64C1419C053DE227BE3CACCEEF3
A file restamped to another timestamp keeps its config hash and gets a new genesis hash
Loading the test widget…
The TestNet release's spine pin names spine block 0 of the shipped files
After a relaunch to T the pin is 0 and the spine block 0 hash for T.
A stated value: there is nothing to compute. A compatible node shows the same value.
- spine_pin
0 7cd929c4d52d9c9455ed179d24a65f90ecbf3d1a3e1214a19611635791b3545c
A repair run with a timestamp that is not the chain's, the pin at block 0, is stopped
The node is not started.
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.
Both relaunched chains run with require_signed_receipt_requests on from block 0
A node setting, not genesis: the installer writes true for every chain; a kept node.conf that names it keeps its value.
A stated value: there is nothing to compute. A compatible node shows the same value.
- require_signed_receipt_requests
true- node_default_when_missing
false
Defects to match. None.
13. Appendix: the genesis texts every snapshot carries
Purpose. The builder writes text of its own beside the committed values: a description beside
every consensus parameter, and the nine values of chain_metadata. Neither enters the config hash
or the genesis hash (§3), but both tables travel whole in every snapshot (26 §2, tables 55 and
65), whose bytes every node must reproduce. An implementation whose genesis writes other texts holds
the same genesis hash as the chain and still writes snapshots that no other node can use or attest.
This section gives every text byte for byte.
Output and effect.
Where each text goes.
consensus_parameters.descriptionenters the snapshot document only: the first cell of every row of the state-table entryconsensus_parameters(columnsdescription,parameter_name,parameter_value, in that order; rows byparameter_name,26§2), and through it the document'sfull_file_hash, every chunk hash and chunk file name (26§3), the manifest a spine block publishes (25§4), theZBCSNAP1:attestation, and the archive's chunk names, holders and sample (26§10b). It is not in the config hash (§3 step 2 commits a parameter's name and value only), the genesis hash, a block, a transaction or a signature, and no rule reads it. A governance change of the parameter (17), and its rollback, change the value only: the row keeps its text.chain_metadata.valueenters the same bytes through the entrychain_metadata(columnskey,value), and is read by the coinbase and the SendZBC supply bound (§8, §11). Three of its values repeat the chain's identity (chain_id,config_hash,genesis_hash, §3); the others are derived numbers.- Texts copied verbatim from the configuration (a token's
symbolandname, a bridge coin'ssymbol,chain,assetanddeposit_address, a registry entry'sdomainandurl, a genesis release'sversion) travel in their tables' entries too; every one of them is committed (§3 steps 5 and 8), a token'snameonly by a file that lists a rule of bundle 601, as every shipped file does. - Not carried by a snapshot: the rule-activation record (§9; node-local,
26§2) and the spine tables (25).
The consensus_parameters rows of a genesis. One row per name: the 79 names of the table below
that carry a text and are marked "all three"; survival_min_producers and
spine_late_vote_after_seconds, each only when the main file's consensus_params names it; one
rule.<name> row per key of rule_activation and one rule_off.<name> row per key of rule_off,
each holding its height; every one of these with the description the table gives. Then
coinbase_total_distribution, written last by the pool step of §8, with the pool as its value and
a null description (no text at all; not the empty text).
Two committed names get no row: coinbase_number_rewards_per_second and
coinbase_max_number_rewards_per_block (both in chain_metadata instead). Values are i64
(booleans 0/1), as in §2. The TestNet file gives 206 rows (79 + survival_min_producers + 125
rules + coinbase_total_distribution), the DevNet file 207 (it adds
spine_late_vote_after_seconds), the mainnet template 205.
The descriptions, by parameter_name in byte order (the order of the snapshot's rows). Each text
is exactly the UTF-8 bytes between the backquotes: no terminator, no surrounding space, no escaping.
The apostrophe of six texts is the single byte 27. Two texts are not ASCII: the one of
topology_period_blocks ends (PoP: ΔΥh) = 28 50 6F 50 3A 20 CE 94 CE A5 68 29 (U+0394 GREEK
CAPITAL LETTER DELTA, then U+03A5 GREEK CAPITAL LETTER UPSILON, not the Latin Y), and the one of
min_block_interval ends (PoP: ΔBt) = 28 50 6F 50 3A 20 CE 94 42 74 29. "bytes" is the UTF-8
length. The texts are opaque: no rule reads them, and every text is reproduced as it stands only
because its bytes travel. "rows on" names the
shipped files that write the row (TestNet, DevNet, the mainnet template).
| # | parameter_name |
description (UTF-8, exactly these bytes) |
bytes | rows on |
|---|---|---|---|---|
| 1 | account_group_max_members |
Account groups: addresses per group, the controller included (100) |
66 | all three |
| 2 | account_rent_period_cost |
Account survival: atomic ZBC charged per period from an account's balance |
73 | all three |
| 3 | admission_genesis_seat_cap |
Genesis registry nodes counted in the admission pace at most (newcomers count fully, suspended nodes in neither) |
112 | all three |
| 4 | app_open_timeout_blocks |
Apps: blocks after its creation a multiplayer app nobody started stays open before it closes itself (161280 = 28 days at 15 s) |
126 | all three |
| 5 | app_unused_share_bps |
Apps: basis points of each stake an app nobody started keeps for the longevity pool when it closes itself (1000 = 10 %) |
119 | all three |
| 6 | batch_receipt_lookback_height |
Blocks to look back for receipts |
32 | all three |
| 7 | block_time_interval |
Target time between blocks in seconds |
37 | all three |
| 8 | blocksmith_block_creation_time |
Time allowed for block creation in seconds |
42 | all three |
| 9 | blocksmith_network_tolerance |
Network tolerance for block propagation in seconds |
50 | all three |
| 10 | blocksmith_time_gap |
Time gap between blocksmith windows in seconds |
46 | all three |
| 11 | bridge_quorum_den |
Bridge custody quorum denominator |
33 | all three |
| 12 | bridge_quorum_num |
Bridge custody quorum numerator (ceil(active*num/den) approvals) |
64 | all three |
| 13 | chunk_replicas |
History chunks: R nodes expected to hold each chunk (reserved; subsystem not built yet) |
87 | all three |
| 14 | chunk_size_blocks |
History chunks: blocks per chunk (chunk boundary; consensus - holders must agree where a chunk starts) |
102 | all three |
| 15 | coinbase_total_distribution |
null (no text: CBOR F6) |
— | all three |
| 16 | cumulative_difficulty_divisor |
Divisor for cumulative difficulty calculation |
45 | all three |
| 17 | dataset_storage_cost_per_mib |
Storage rent: atomic ZBC charged per MiB per billing period |
59 | all three |
| 18 | decrease_score_divider |
Weeks to drop from max to zero score |
36 | all three |
| 19 | default_participation_score |
Default participation score for new nodes |
41 | all three |
| 20 | exchange_taker_fee_bps |
Exchange: taker fee in basis points, paid to the block producer from the asset the taker receives (makers pay nothing) |
118 | all three |
| 21 | exit_cooldown_blocks |
The exit's hold: a registered node whose owner exits stays registered and in the draw this many blocks, then leaves with its lock (less node_lock_at_risk_bps if it missed a turn or was suspended meanwhile, or was missing at the exit) (40320 = 7 days at 15 s) |
258 | all three |
| 22 | gateway_heartbeat_freshness_window |
Gateway registry: max tip-distance (blocks) of the reference block a heartbeat may cite |
87 | all three |
| 23 | gateway_heartbeat_interval |
Gateway registry: expected liveness-beat cadence in blocks |
58 | all three |
| 24 | gateway_prune_grace |
Gateway registry: blocks past last beat before a stale gateway is auto-pruned |
77 | all three |
| 25 | gateway_registration_cost |
Gateway registry: atomic ZBC stake locked at registration (refunded on unregister/prune) |
88 | all three |
| 26 | linked_receipt_score |
Score weight for linked receipts |
32 | all three |
| 27 | liveness_miss_limit |
A node is suspended at this many consecutive missed turns |
57 | all three |
| 28 | main_snapshot_interval |
Main-chain snapshot cadence in main blocks (0 = disabled) |
57 | all three |
| 29 | main_snapshot_min_height |
Main-chain rollback/finality safety gap before snapshots begin |
62 | all three |
| 30 | market_creation_cost |
Exchange: atomic ZBC to open a trading pair (CreateMarket) - NON-REFUNDABLE, markets are permanent |
98 | all three |
| 31 | maturity_units |
Units after its admission (and one produced block) before a newcomer earns anything |
83 | all three |
| 32 | max_assigned_peers |
Priority-peer count (PoP receipt/topology/scoring); default 5 |
61 | all three |
| 33 | max_block_size_bytes |
Maximum block size in bytes |
27 | all three |
| 34 | max_node_admittance_per_cycle |
Nodes admitted per admission cycle |
34 | all three |
| 35 | max_priority_blocksmiths |
Maximum number of nodes that can produce non-empty blocks |
57 | all three |
| 36 | max_rollback_height |
Maximum number of blocks that can be rolled back |
48 | all three |
| 37 | max_transactions_per_block |
Maximum number of transactions per block |
40 | all three |
| 38 | min_block_interval |
Minimum time between blocks in seconds (PoP: ΔBt) |
50 | all three |
| 39 | min_node_registration_balance |
The queue minimum: the stake a node locks to enter the admission queue, a votable price |
87 | all three |
| 40 | min_node_registration_balance_ceiling |
The queue minimum's voting ceiling on this chain (250 ZBC on mainnet and testnet, 2.5 ZBC on devnet) |
100 | all three |
| 41 | min_payload_persistence_blocks |
Minimum blocks a tx payload is paid to persist (size x duration fee floor; 17280 = 3 days) |
90 | all three |
| 42 | min_registry_size |
Registry floor: below it the admission ceiling is 7 days (rule admission_small_registry_cap) and resolutions are refused |
120 | all three |
| 43 | node_admission_base_delay |
Base delay for admission (delay = base / numActiveNodes) |
56 | all three |
| 44 | node_admission_genesis_delay |
Delay after genesis before first admission |
42 | all three |
| 45 | node_admission_max_delay |
Maximum admission delay (slowest with few nodes) |
48 | all three |
| 46 | node_admission_min_delay |
Minimum admission delay (fastest with many nodes) |
49 | all three |
| 47 | node_lock_at_risk_bps |
Basis points of a registered node's lock lost to the longevity pool on expulsion and on an exit while missing or suspended |
122 | all three |
| 48 | oracle_quorum |
Gateway-oracle: agreeing attesters required to resolve an event (3-of-5) |
72 | all three |
| 49 | queue_median_fraction_bps |
At entry, this share of the median queued stake can lift the queue minimum (5000 = one half) |
92 | all three |
| 50 | receipt_batch_size |
Receipt batch size for Merkle tree |
34 | all three |
| 51 | receipt_lifecycle |
Published-receipt retention in blocks (0 = runtime floor max(100,2*registry)+1; larger keeps history longer) |
108 | all three |
| 52 | roll_call_blocks |
The pre-genesis roll call: a genesis registry node's RollCall counts in blocks 1 .. this; from block 2 one that has not answered is not drawn, and at this block it leaves the registry (never below three registry nodes) |
218 | all three |
| 53 | rule.name |
Block height at which this consensus rule takes effect |
54 | TestNet 125, DevNet 125, template 125 |
| 54 | rule_off.name |
Block height at which this consensus rule switches off (the rule is active from its on-height to the block before this one) |
123 | none of the three files (every rule_off is empty) |
| 55 | score_climb_ratio |
Own blocks with a full receipt set (one receipt per priority peer of either kind) climb this many times slower than a missing node falls |
136 | all three |
| 56 | score_loss_per_unit_bps |
Basis points of the maximum score a missing node loses per unit, prorated per block (500 = 5 points of 100) |
107 | all three |
| 57 | score_unit_floor_blocks |
The score unit's minimum in blocks: unit = max(selectable nodes, this) (2880 = 12 h at 15 s) |
92 | all three |
| 58 | smithing_period |
Wait time after previous block before first blocksmith can produce |
66 | all three |
| 59 | snapshot_manifest_expiration_seconds |
Snapshot manifest lifetime in seconds: the node uses the largest of this, three snapshot cycles and 30 days (0 = no override) |
125 | all three |
| 60 | snapshot_reward_share_ppm |
Archive reward: millionths of the longevity pool paid each storage epoch to the honest holders of the sampled snapshot chunks (0..500000) |
137 | all three |
| 61 | spine_blocksmith_block_creation_time |
Time allowed for spine block creation |
37 | all three |
| 62 | spine_blocksmith_network_tolerance |
Network tolerance for spine block propagation |
45 | all three |
| 63 | spine_blocksmith_time_gap |
Time between spine blocksmith windows |
37 | all three |
| 64 | spine_enabled |
Enable spine chain production |
29 | all three |
| 65 | spine_fallback_periods |
Spine periods without a stored spine block after which more than half of the signer list suffices |
97 | all three |
| 66 | spine_finality_depth |
Blocks for spine finality |
25 | all three |
| 67 | spine_hierarchy_enabled |
Enable multi-level spine hierarchy |
34 | all three |
| 68 | spine_late_vote_after_seconds |
Seconds after a spine block is due when YES votes must outnumber NO votes (default 10800) |
89 | DevNet |
| 69 | spine_level |
Level in spine hierarchy (1=spine, 2=meta-spine) |
48 | all three |
| 70 | spine_min_signatures |
Minimum signatures for spine block validity |
43 | all three |
| 71 | spine_parent_period_multiplier |
Meta-spine period multiplier |
28 | all three |
| 72 | spine_signature_collection_timeout |
Seconds to wait for signature collection |
40 | all three |
| 73 | spine_signature_threshold_percent |
Percentage of nodes needed for spine consensus |
46 | all three |
| 74 | spine_smithing_period |
SpineChain smithing period (24h prod, 600s test) |
48 | all three |
| 75 | spine_snapshot_interval |
Spine self-snapshot cadence in spine blocks (0 = off; reserved for super-spine) |
79 | all three |
| 76 | spine_snapshot_min_height |
Reserved: spine self-snapshot safety gap |
40 | all three |
| 77 | storage_oracle_multiplier_ppm |
Storage rent: oracle price multiplier in ppm (1000000 = 1.0x, neutral placeholder) |
82 | all three |
| 78 | storage_proof_epoch_blocks |
Storage: blocks per proof/rotation epoch (proof tally cadence; small in dev/test) |
81 | all three |
| 79 | storage_replication |
Storage: K replicas per piece (expected-holder count; must match node.conf replication) |
87 | all three |
| 80 | survival_min_producers |
Survival mode: below this many distinct producers in the last 120 blocks governance freezes; 0 = off |
100 | TestNet, DevNet |
| 81 | token_free_persist_blocks |
Token survival: blocks a newly issued token lives before any survival payment is due |
84 | all three |
| 82 | token_persist_period_cost |
Token survival: atomic ZBC to keep one token alive for one billing period |
73 | all three |
| 83 | topology_period_blocks |
Network topology period in blocks (PoP: ΔΥh) |
46 | all three |
| 84 | unlinked_receipt_score |
Score weight for unlinked receipts |
34 | all three |
The chain_metadata rows, by key in byte order. Every value is text (CBOR type 3); a number is
written in decimal digits without sign or leading zero, a hash as 64 lower-case hex digits.
key |
value |
|---|---|
chain_id |
the main file's chain_id, verbatim (default zoobc-mainnet) |
coinbase_max_number_rewards_per_block |
the parameter of §2 (600 on every shipped file) |
coinbase_number_rewards_per_second |
the parameter of §2 (1 on every shipped file) |
coinbase_total_distribution |
the coinbase pool of §8 |
coinbase_total_supply |
the coinbase pool of §8 (the same text) |
config_hash |
the config hash (§3 step 9) |
genesis_hash |
block 0's hash (§3 step 10), so it follows a restamped timestamp |
genesis_timestamp |
the main file's timestamp |
total_supply |
the configured total_supply (default 3333333333333333) |
How to compute it. Write the rows above at genesis; the snapshot encodes them as 26 §2 says:
a text as CBOR type 3 with its UTF-8 byte length, a null as F6, an integer in its minimal width.
Rule activation. None for the texts. The two tables travel under the gates of 26 §2
(chain_metadata under escrow_commission_nonnegative), active from height 0 on every chain.
Rejections and errors. None: no node checks a text. A wrong text shows only as another snapshot hash.
Vector (computed from the shipped files). INPUT: the TestNet pair → 206 consensus_parameters
rows. The state-table entry consensus_parameters alone (the map {"Columns": […], "Rows": […]},
CBOR as 26 §2) is 18,781 bytes with SHA3-256
C1243461D81BA42E14F590E5C5A7E16F4ED73F413065D16C486DEC688E707BF3; it begins A2 67 "Columns" 83 6B "description" 6E "parameter_name" 6F "parameter_value" 64 "Rows" 98 CE (206 rows), its first row is 83 78 42 "Account groups: addresses per group, the controller included (100)" 78 19 "account_group_max_members" 18 64, the row of topology_period_blocks is
83 78 2E "Network topology period in blocks (PoP: " CE 94 CE A5 "h)" 76 "topology_period_blocks" 18 28
and the row of coinbase_total_distribution is
83 F6 78 1B "coinbase_total_distribution" 1B 00 07 59 17 7B B1 A1 D5 (null, the name, 2,068,282,231,333,333).
The DevNet pair → 207 rows, 18,871 bytes, SHA3-256
9F34975C0ACCD49A85E289C8883B98D27039A2718F8A58982B741BCB2A3F6132; the mainnet template → 205 rows,
18,654 bytes, SHA3-256 3274D6EB16E12EB51C0A8020011A050A1E177CBCFB72875ADD3BFB2EF8F2FCED. The
TestNet's first snapshot (S = 172,040, below the first price count at 172,800, 17) carries this
entry unchanged. The entry chain_metadata of the TestNet file as shipped (its timestamp
1,793,509,027; a launch restamps genesis_timestamp and genesis_hash) holds chain_id
zoobc-test, coinbase_max_number_rewards_per_block 600, coinbase_number_rewards_per_second
1, coinbase_total_distribution and coinbase_total_supply 2068282231333333, config_hash
b4d46ec1c521cbd143109591bdc5188c76e120779a048f858a5b2c29125ab381, genesis_hash
3a2897e7c5ad6143429bab33a92d14d11ffd6fc281f2b62a6fd6b49c183b863d, genesis_timestamp
1793509027, total_supply 3333333333333333: 437 bytes, SHA3-256
9C2D23390791E0BD06021F4579FF25C49ACDFAE87E8BB554A4BBA45C5E39B7CE. INVALID: the TestNet pair built with
the Latin Y (59) in place of Υ (CE A5) in the description of topology_period_blocks → the
same config hash and genesis hash, but an entry of 18,780 bytes with SHA3-256
644A454336E20378FB26C5E9545EFCF7948B496416A88E1968D1C05CEBEE0BC3, so every snapshot of that genesis has
another full_file_hash: a joiner fetching the chunk that holds the entry against the chain's
manifest refuses it ("Chunk i verification failed", 26 §6), and its ZBCSNAP1: attestations
name a hash no other node attests (26 §10b).
Test cases · §13
7 cases · 6 valid · 1 invalid
The TestNet pair's consensus_parameters entry, and its first row
Loading the test widget…
The row of topology_period_blocks: Greek capital delta and upsilon
Loading the test widget…
The row of coinbase_total_distribution: a null description and the pool
Loading the test widget…
The DevNet pair's consensus_parameters entry
Loading the test widget…
The mainnet template's consensus_parameters entry
Loading the test widget…
The TestNet pair's chain_metadata entry (the file's own timestamp)
Loading the test widget…
A genesis whose topology_period_blocks text has the Latin Y in place of the Greek upsilon
Loading the test widget…
Defects to match. (1) The descriptions are free text outside the config hash: two builders
whose texts differ build the same genesis hash and write different snapshots, so an implementation
uses the bytes of the table exactly. (2) coinbase_total_distribution has a null description. (3) A
file that lists no rule of bundle 601 commits neither a token's name and issuer nor a relay's
gateway_key (§3 steps 5 and 8), although the snapshot carries them (no shipped file is such a
file). (4) A bridge coin whose asset is given as the empty text commits that
empty text (§3 step 5) and stores native in bridge_coin (no shipped file does so).
A question about this chapter, or a statement that does not match the network? Discuss on zoobc.pro.