On this page
  1. §0 The area in one paragraph
  2. 1. Who may vote: attesters, counted registered nodes and quorums
  3. 1a. Governance in survival mode
  4. 2. FeeVoteCommitment (7) and FeeVoteReveal (263)
  5. 3. The fee-scale count
  6. 4. AttestEvent (17) and the oracle resolution
  7. 5. SetConsensusParam (51) and the price count
  8. 6. RegisterRelease (32), ReleaseAuthorityPropose (33), ReleaseAuthorityAccept (34), RevokeRelease (35)
  9. 7. RegisterGateway (36), GatewayHeartbeat (37), UnregisterGateway (38) and the prune
  10. 8. RegisterArchival (46), UnregisterArchival (47), RegisterRelay (48), UnregisterRelay (49)
  11. 9. The announcement registry (node-local)
  12. 10. Ledger rows, views and the consensus/local split

17 — Governance and registries: fee votes, parameter votes, oracle attestations, releases, gateways, archivals, relays

Edition 0.6.1 · verified against the reference implementation, version 0.6.1

Out of scope the fee floor's use of the scale (04 §2–§3); the queue minimum's use at entry (09 §3, §9); CreateTrigger and height-fired triggers (08 §5); the node registry and the active set (09); the bridge's deposit and withdrawal resolution, its mint and its burn (34); the survival flag itself (19, 36); the self-updater's choice of a release and the readiness tally a registration floors (29); the prune of votes and survival flags (13 §8); the block seed and the priority list (05)

§0 The area in one paragraph

Four things on this chain are decided by the registry rather than by one account, and three registries are kept by their owners. The registry here is always the counted registered nodes: registered and not suspended, as of the block before the decision; the spine's own count is the one exception (25). Prices — the eight governable parameters of §5 (the taker fee and the queue minimum among them) and the transfer-fee scale of §3 — move once per snapshot cycle, at the cycle's last block, to the average over the counted registered nodes: a registered node's latest vote of the cycle counts, limited first to +20 % up, half down and the price's bounds, and a registered node that did not vote counts as today's value; below the registry floor nothing moves. The transfer fee keeps its two steps, a sealed FeeVoteCommitment in the first half of the cycle and a FeeVoteReveal that hashes to it in the second; the other prices are voted with SetConsensusParam. Every vote is a fee-free duty sent by a node's own key. Oracle attestations (AttestEvent) are rows (event id, attester, value); a generic event resolves when two thirds of the counted registered nodes attest the same value, and fires the triggers that name it. The release registry is a singleton authority (set in genesis, handed over by propose-and-accept) that publishes version strings with a 32-byte manifest hash and may revoke them; a version registers once, and two thirds of the counted registered nodes may veto a release or, after a week, replace the authority, their votes counting for 30 days (§6); a registration is also the floor from which a rule bundle may activate (§6, 29). Gateways lock the voted gateway_registration_cost (10 ZBC at genesis), prove liveness with signed heartbeats and are pruned with a refund after 720 blocks of silence; archivals and relays are declared by node owners for free and withdrawn by them. While the chain is in survival mode (too few distinct blocksmiths, 19, 36) the whole governance category and every attestation are frozen: no vote, no release transaction and no AttestEvent is accepted, a cycle's counts are skipped, the resolutions wait, and the days a vote counts for are not spent (§1a). The announcement registry that nodes keep in memory for the same services is node-local gossip, not consensus.

1. Who may vote: attesters, counted registered nodes and quorums

Purpose. The identity and the threshold every tally below uses.

Inputs. The registry and the suspended set as of the previous block's height (09, 36); the parameters bridge_quorum_num / bridge_quorum_den (2 / 3 on TestNet and DevNet; compiled 2 / 3), min_registry_size (mainnet and TestNet 7, DevNet 3).

Output and effect. A node's attester account is the 36-byte typed account 00000000 ‖ node_public_key (a registry row whose key is not 32 bytes cannot attest). A bare 32-byte key is a node key, never an account: a transaction whose sender is 32 bytes (other than a Cardano account, 01) is refused (03), so every vote and attestation is sent by the typed node-key account and the node is found from it by taking its last 32 bytes when its type is 0. The counted registered nodes at height h are the registered rows in force at h minus the registered nodes suspended at h (a failed read fails the block). Under oracle_full_registry_quorum (height 0) the authorized set for every generic event, the release votes and the bridge is the counted registered nodes' attester accounts, and the quorum is SupermajorityQuorum(n, num, den) = ceil(n × num / den) (den 0 → n), at least 1, with n the counted registered nodes: a suspended registered node neither attests nor sits in the denominator. Under quorum_floor (height 0) no registry-wide decision resolves (the price counts §3/§5, the release veto/hand-off §6, a bridge deposit or withdrawal 34, a generic oracle fact §4) while the counted registered nodes are fewer than floor = max(3, min_registry_size) or held by fewer than floor distinct owner accounts (two registered nodes of one operator are one voice). The required spine signatures are a ceiling, not a truncation (25), and count every registered node among the spine signers, suspended or not. The vote types are fee-free duties (duty_fee_free, §2/§4/§5): the fee is exactly 0 and the sender must be a registered node's key account (admission: "a fee-free duty transaction must be sent by a registry attester account (the node's own key)").

How to compute it. As stated.

Rule activation. oracle_full_registry_quorum, quorum_floor, duty_fee_free, typed_accounts_only (height 0).

Rejections and errors. None here.

Vector. computed.

  • Input: 11 counted registered nodes, num/den 2/3. Expected: quorum ceil(22 / 3) = 8.
  • Input: two of them suspended (n 9). Expected: quorum 6.
  • Input: n 6 on TestNet (floor max(3, 7) = 7). Expected: nothing resolves at all.
  • Input: a node with key 66A2B2C675658EB327982F0EC7539DE1AB51F528D586FF2F9381AFA15F86EB7E. Expected: its attester account is 0000000066A2B2C675658EB327982F0EC7539DE1AB51F528D586FF2F9381AFA15F86EB7E; a vote sent with the bare 32-byte key as sender is refused with "accounts are typed: a bare 32-byte key is not an account on this chain".
  • computed (from the TestNet genesis file: 11 genesis nodes, floor 7): while all 11 are registered and none suspended, GET /api/v1/governance/proposals in the first cycle answers "counted_seats":11, "floor_met":true, "count_height":172800, "cycle_first_block":1.

Test cases · §1

6 cases · 5 valid · 1 invalid · 1 reference

Eleven counted registered nodes need eight17-1-quorum-11valid

Loading the test widget…

Two of them suspended: nine registered nodes need six17-1-quorum-9valid

Loading the test widget…

Six counted registered nodes on TestNet: nothing resolves17-1-below-floorvalid

Loading the test widget…

A node key's attester account17-1-attestervalid

Loading the test widget…

A vote sent with the bare 32-byte node key as sender17-1-bare-keyinvalid

Loading the test widget…

The governance view in the first cycle of a chain whose 11 genesis nodes are all registered17-1-governance-viewvalidreference

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

counted_seats
11
floor_met
true
count_height
172800
cycle_first_block
1

Defects to match. The authorized set is read at the previous block's height; a node admitted in this block cannot count until the next. Below the floor of quorum_floor a genuine supermajority still does not resolve (a small chain cannot govern itself, by design).

1a. Governance in survival mode

Purpose. While too few distinct blocksmiths make blocks, nothing the chain governs can change and no attestation is taken.

Inputs. The survival flag of the block a transaction lands in (19: the flag at height h is true when the genesis parameter survival_min_producers N is > 0 and fewer than N distinct blocksmiths made the main-chain blocks [max(1, h − 120), h − 1]; the flag at h − 1 does not enter, so the chain is in survival mode below N and out of it at N or more). N: TestNet and DevNet 5; the mainnet template does not name it, so a chain built from it unchanged has N = 0, survival mode off; the genesis builder refuses N outside 0 … 10,000, N > 1 on a one-node chain and N above the genesis node count − 2.

Output and effect. The frozen set is the governance category, the transaction types 7 FeeVoteCommitment, 263 FeeVoteReveal, 32 RegisterRelease, 33 ReleaseAuthorityPropose, 34 ReleaseAuthorityAccept, 35 RevokeRelease and 51 SetConsensusParam, and the bridge category, type 17 AttestEvent (every attestation: oracle fact, bridge deposit or withdrawal, release vote, snapshot attestation). While the flag of block h is true:

  1. a transaction of a frozen type is refused at admission for the block it would land in (tip + 1); a blocksmith leaves admitted ones in its pool (an unreadable flag holds them too); a block at h that carries one is invalid;
  2. the fee-scale count (§3) and the parameter-vote count (§5) at a cycle's last block h are skipped: nothing is counted, no fee_scale row is written (the next count's "this cycle" then starts after the older row), and the cycle's votes lapse;
  3. the oracle resolution (§4), the two bridge steps (34 §4, §6) and the release-governance step (§6) do not run: attestations already on chain stay pending and are tallied at the first block whose flag is false, and the windows they are judged by do not count the survival heights (§6, 34; the rows are kept accordingly, 13 §8);
  4. every other transaction and every other registry change proceeds (expulsions are paused, 36).

How to compute it. The flag as 19 specifies; a failed read of the flag refuses the transaction and fails the block.

Rule activation. survival_mode (active from height 0 on every chain).

Rejections and errors. Admission: "SurvivalMode: transaction type T is not accepted while fewer than survival_min_producers distinct producers made the last 120 blocks (survival mode: governance and bridge are frozen until N produce again)" ("producers" in these texts means distinct blocksmiths; the letter N is literal). The same check, with the same text, is part of the transaction's validity that block validation runs at the block's height (19 §2 step 11), so a block carrying such a transaction is invalid with that text; the execution step re-runs that validity first, so it never produces a text of its own. A flag that cannot be read: "SurvivalMode: the survival state could not be read: …".

Vector. computed (survival_min_producers 5, the value of both live genesis files).

  • Input: a SetConsensusParam judged for block 1,000 when the blocks 880…999 were made by 4 distinct blocksmiths. Expected: refused at admission "SurvivalMode: transaction type 51 is not accepted while fewer than survival_min_producers distinct producers made the last 120 blocks (survival mode: governance and bridge are frozen until N produce again)"; a block 1,000 carrying it is invalid with the same text. A SendZBC in the same block is accepted; an AttestEvent (type 17) is refused like the vote.
  • Input: the same chain with L = 240 and h = 1,200 (a cycle's last block) in survival mode. Expected: no fee-scale row and no parameter change at 1,200, whatever the votes.
  • Input: the window 881…1,000 made by 5 distinct blocksmiths, the flag at 1,000 true. Expected: the flag at 1,001 is false (N distinct blocksmiths end survival mode) and the vote is accepted in block 1,001; a window of 4 distinct blocksmiths at 1,002 turns the flag on again.

Test cases · §1a

6 cases · 3 valid · 3 invalid · 1 reference

A SetConsensusParam while four distinct blocksmiths made the window17-1a-frozeninvalid

Loading the test widget…

An AttestEvent in the same block is refused like the vote17-1a-attest-frozeninvalid

Loading the test widget…

A SendZBC in the same block17-1a-send-passesvalid

Loading the test widget…

A cycle's last block in survival mode counts nothing17-1a-skipped-countvalidreference

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

fee_scale_row
none
parameter_change
none
Five distinct blocksmiths end survival mode and the vote is accepted17-1a-exactly-nvalid

Loading the test widget…

A window of four distinct blocksmiths at 1,002 turns the flag on again17-1a-on-againinvalid

Loading the test widget…

Defects to match. None.

2. FeeVoteCommitment (7) and FeeVoteReveal (263)

Purpose. A registered node's two-step vote on the transfer-fee scale, one commit-reveal per snapshot cycle.

Inputs. Commitment body: vote_hash, exactly 32 bytes. Reveal body:

Offset Length Field Encoding
0 32 recent_block_hash a block hash (any 32 bytes are accepted)
32 4 recent_block_height u32 LE
36 8 fee_vote i64 LE > 0; the scale itself (a vote of 1,000,000 is the start scale, 1×)
44 4 sig_len u32 LE
48 sig_len voter_signature over the first 44 bytes, by the sender's address type (02): Ed25519 of the node key

vote_hash = SHA3-256 of the reveal's first 44 bytes (the FeeVoteInfo). The cycle is the snapshot cycle (snapshot_cycle): L = main_snapshot_interval (172,800 on mainnet and TestNet, 240 on DevNet), cycle k the blocks kL + 1 … (k + 1)L; position = (h − 1) mod L; the first half is position < L / 2, the second half position ≥ L / 2.

Output and effect. Both: the sender must be a registered node, found by the sender as an owner account (the registry row whose owner account is byte-equal to it) or as the node's key account (type 0: the node whose key is its last 32 bytes); a non-voter → paid no-op. Only node-key votes count: admission refuses an owner-signed vote by the duty-sender rule of §1, and the count of §3 reads only reveals whose voter is a key account 00000000 ‖ node key, so a mined owner-signed reveal is stored and counts for no registered node. A commitment in a block outside the first half of the cycle → paid no-op (nothing stored); a reveal outside the second half, or whose FeeVoteInfo does not hash to a commitment by the same voter (byte-equal sender) at a height above the latest fee_scale row's height, → paid no-op. A failed read of the commitments or of the latest fee_scale height refuses the transaction at admission and fails the block in execution. The fee is debited when > 0 (event 11 / 12; a duty declares 0 and touches no account). A commitment writes fee_vote_commitment_vote(vote_hash, voter_address, block_height) (insert or replace); a reveal writes fee_vote_reveal_vote(recent_block_hash, recent_block_height, fee_vote, voter_address, voter_signature, block_height). Then 04 §5.

How to compute it. Stateless (admission and block validation): "FeeVoteCommitment: body must be 32 bytes"; "FeeVoteReveal: invalid body: …" (< 48 bytes or the signature longer than the body), "FeeVoteReveal: recent_block_hash must be 32 bytes", "… fee_vote must be positive"; for an Ethereum- or Tron-typed sender (type 4 or 15) a voter_signature that is not 65 bytes ending in 27 or 28 → "FeeVoteReveal: voter_signature: Ethereum signature recovery id must be 27 or 28" (rule eth_signature_canonical_v); "… voter_signature does not verify for the sender over the FeeVoteInfo bytes". Admission, judged at the height the vote would land in: "FeeVoteCommitment: voter is not a registered node" / "FeeVoteReveal: voter is not a registered node", "FeeVoteCommitment: outside the commit phase (the first half of the snapshot cycle)", "FeeVoteReveal: outside the reveal phase (the second half of the snapshot cycle)", "FeeVoteReveal: no commitment by this voter in this cycle matches the vote", the duty-sender refusal of §1 and the survival-mode refusal of §1a. Execution (block invalid): "ParseFeeVoteCommitBody: expected 32 bytes, got N", "ExecuteFeeVoteReveal: recent_block_hash must be 32 bytes", "… fee_vote must be positive".

Rule activation. fee_vote_noop, duty_fee_free, survival_mode (§1a), eth_signature_canonical_v (the voter signature's recovery byte), active from height 0 on every chain; the phases have no rule.

Rejections and errors. As listed.

Vector. computed (DevNet, L 240).

  • Input: positions. Expected: blocks 1 … 120 are the first half of cycle 0 (position (h − 1) mod 240 < 120), 121 … 240 the second; a commitment at 130 is refused at admission ("FeeVoteCommitment: outside the commit phase (the first half of the snapshot cycle)") and a paid no-op if mined; a reveal at 240 (the count block) counts for cycle 0.
  • Input: a reveal with recent_block_hash = 32 × 11, recent_block_height 100 (64000000), fee_vote 2,000,000 (80841E0000000000), sig_len 64 (40000000) and the node key's Ed25519 signature over those 44 bytes. Expected: a 112-byte body; the matching commitment body is SHA3-256 of the 44 bytes.
  • Invalid input: a commitment body of 31 bytes → "FeeVoteCommitment: body must be 32 bytes": refused at admission, and a block carrying it is invalid (the execution text "ParseFeeVoteCommitBody: expected 32 bytes, got 31" is never reached by an honest blocksmith). A reveal sent by an Ethereum-typed account whose voter_signature is 65 bytes ending in 00 (the 0/1 copy of a recovery id 27) → "FeeVoteReveal: voter_signature: Ethereum signature recovery id must be 27 or 28", stateless as well (such a sender's reveal could not count anyway: only node-key votes count).

Test cases · §2

9 cases · 5 valid · 4 invalid

Block 1 is in the first half of cycle 017-2-phase-1valid

Loading the test widget…

Block 120 is in the first half of cycle 017-2-phase-120valid

Loading the test widget…

Block 121 is in the second half of cycle 017-2-phase-121valid

Loading the test widget…

A commitment at block 13017-2-late-commitinvalid

Loading the test widget…

A reveal at block 240 counts for cycle 017-2-reveal-240valid

Loading the test widget…

A reveal of 2,000,000 at recent height 10017-2-reveal-bodyvalid

Loading the test widget…

A 31-byte commitment fails at execution17-2-commit-31invalid

Loading the test widget…

A 31-byte commitment is refused before execution17-2-commit-31-statelessinvalid

Loading the test widget…

An Ethereum-typed reveal whose voter signature ends in 0017-2-reveal-eth-v0invalid

Loading the test widget…

Defects to match. (1) A mined reveal whose signature is wrong still counts (the signature is a stateless admission check, so an honest blocksmith never mines one).

3. The fee-scale count

Purpose. Turning the cycle's reveals into the fee scale of 04 §3.

Inputs. The fee_scale row with latest 1 (seeded with INITIAL_FEE_SCALE 1,000,000 at height 0 on first use; the genesis builder writes the same row); the reveals of the cycle; the counted registered nodes as of the previous block (§1).

Output and effect. At the end of every block, after its transactions (step order 22): when no fee_scale row exists one is seeded (a failed read or write fails the block). At the cycle's last block (h mod L = 0), unless the block is in survival mode (§1a: then nothing more): today = the row's scale; nodes = the counted registered nodes at h − 1, or none when they fail the registry floor; votes = for each registered node (node-id order) its latest reveal of the cycle's blocks [first, h] keyed by node key (the newest height, the lower value on a tie; a reveal from any account that is not a key account is no registered node's vote); new = CountAverage(votes, |nodes|, today, 1, 100,000,000) (no counted registered node → new = today), where

  • LimitVote(v, t, lo, hi) = clamp(v, max(lo, ⌈t / 2⌉), min(hi, t + max(1, ⌊t / 5⌋))), with t = clamp(today, lo, hi): at most +20 % (at least one unit) up, at most half down;
  • CountAverage = clamp(round((Σ LimitVote(vote) + (n − |votes|) × t) / n), lo, hi), n = max(|nodes|, |votes|), round = (sum + ⌊n / 2⌋) div n in 128-bit (a half rounds up).

A new fee_scale row (new, h, 1) is written every cycle, changed or not, so "this cycle" for the commitment match is always "after the last row" (except after a count skipped in survival mode). The bounds are one atomic unit and 1 ZBC (100,000,000 = 100 × the start).

How to compute it. As stated.

Rule activation. None for the count itself; quorum_floor gates the registered nodes; survival_mode skips it (§1a).

Rejections and errors. None; a failed read of the row, the registered nodes or the reveals fails the block.

Vector. computed.

  • Input: today 1,000,000; 11 counted registered nodes; at the count block three registered nodes' latest reveals are 1,500,000, 900,000 and 400,000.
  • Expected output: limited to 1,200,000, 900,000, 500,000 (bounds [500,000, 1,200,000]); sum = 2,600,000 + 8 × 1,000,000 = 10,600,000; (10,600,000 + 5) div 11 = 963,636; a new fee_scale row (963,636, h, 1).
  • Input: no reveal. Expected: a new row (1,000,000, h, 1).
  • Input: today 1; every registered node votes 5. Expected: limited to 2 (+1, the step's floor); the new scale 2.
  • Input: the counted registered nodes are fewer than the floor. Expected: no registered node counts; the row is rewritten at today's value.
  • computed: before the first count block (172,800 on TestNet) GET /api/v1/blockchain/fee-params answers "fee_scale":1000000, "initial_fee_scale":1000000 (the seeded row).

Test cases · §3

5 cases · 5 valid · 1 reference

Three registered nodes vote 1.5, 0.9 and 0.4 times the start scale17-3-three-votesvalid

Loading the test widget…

No reveal: the scale stays17-3-no-votevalid

Loading the test widget…

From a scale of 1 every registered node votes 517-3-from-onevalid

Loading the test widget…

Below the registry floor no registered node counts17-3-below-floorvalid

Loading the test widget…

The fee parameters before the first count block (the seeded row)17-3-fee-paramsvalidreference

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

fee_scale
1000000
initial_fee_scale
1000000

Defects to match. One registered node of n moves the scale by at most 1/n of the step; a cartel of k registered nodes by k/n of it per cycle.

4. AttestEvent (17) and the oracle resolution

Purpose. Registry nodes agree on an external value; the agreement fires triggers.

Inputs. Body: id_len (u32 LE) ‖ event_id[id_len] ‖ val_len (u32 LE) ‖ value[val_len], each length ≤ 4,096, event_id non-empty; bytes beyond ignored.

Output and effect. Execution: a malformed body or a negative fee → paid no-op; a sender that is not an attester account of the active registry at the previous height → paid no-op (rule oracle_registered_only); the fee (unaffordable → free no-op); the row oracle_attestation(event_id, attester = sender as presented, value, block_height), a versioned row keyed (event_id, attester): a second attestation by the same account writes a new version at its height and the earlier one stops being current (it stays as history until pruned, 13 §8); a rollback deletes the versions above the target height and makes the newest remaining version of each (event id, attester) current again; every tally reads the current versions only. At the end of every block (after the storage proofs, before the bridge and governance steps, 22), and only when the registry floor of §1 is met (quorum_floor) and the block's survival flag is false (§1a; while it is true the step does not run and pending events wait for the first block whose flag is false): for every event id that has attestations and no result, except the bridge prefixes ZBRDEP1: / ZBWDR1: and (rule release_registry_veto) the governance prefix ZBCGOV1: and the release prefix ZBCREL1:, which their own later steps (34, §5, §6) resolve; so a parameter vote is never consumed by this step, and the price count of §5 always finds the cycle's votes. The archive's snapshot attestations (ZBCSNAP1:<reference height> with the value <full_file_hash, 64 hex>:<chunk count>, a fee-free AttestEvent duty each node sends after building a snapshot) are not skipped: this step resolves them like any fact, and their oracle_result rows are the archive's membership (11, 26 §10b): count, in table order, the attestations whose attester is in the authorized set (§1), per value; the first value whose count reaches the quorum is written to oracle_result(event_id, value, resolved_height) (no ledger row), and every Pending trigger with that event_id (08 §5), in trigger_id order, pays its recipient (an incoming credit from the trigger's owner, 08 §10, row event 23, transaction_id = the trigger id) and becomes Fired. A failed read of the events, the previous block or the registered nodes, or a storage fault in the resolution, fails the block.

How to compute it. Stateless: "AttestEvent: truncated event_id", "… event_id cannot be empty", "… truncated value", and an event id that begins with the parameter-vote prefix ZBCGOV1: (the prefix of the vote rows only SetConsensusParam writes, §5) → "AttestEvent: the event id prefix ZBCGOV1: is reserved for parameter votes (SetConsensusParam)", refused at admission and making a block that carries it invalid. An id that merely contains ZBCGOV1: further in is not refused. No admission state check beyond the duty-sender rule of §1. At execution a ZBCREL1: event id is first canonicalised (§6).

Rule activation. oracle_full_registry_quorum, oracle_registered_only, quorum_floor, release_registry_veto (the prefix skip), survival_mode (an AttestEvent is refused in survival mode like a governance vote, and the step does not run, §1a) and admission_checks_in_block (the reserved ZBCGOV1: prefix), all active from height 0 on every chain.

Rejections and errors. As listed.

Vector. computed.

  • Input: AttestEvent (type 17), fee 0, by the attester account of a counted registered node, body 08000000 ‖ "PRICE:X1" ‖ 03000000 ‖ "105" = 080000005052494345 3A5831 03000000313035 (19 bytes: event id PRICE:X1, value 105).
  • Expected output: the row (PRICE:X1, the attester, 105, h); with 11 counted registered nodes the eighth distinct attester of 105 resolves it in the block that mines that eighth attestation: oracle_result (PRICE:X1, 105, h) and every Pending trigger on PRICE:X1 fires.
  • Invalid input: body 00000000 00000000 (empty event id) → "AttestEvent: event_id cannot be empty" (stateless); body 08000000 5052 (truncated) → "AttestEvent: truncated event_id"; body 120000005a4243474f56313a626173655f6665653a390100000031 (27 bytes: event id ZBCGOV1:base_fee:9, value 1) → "AttestEvent: the event id prefix ZBCGOV1: is reserved for parameter votes (SetConsensusParam)".

Test cases · §4

5 cases · 2 valid · 3 invalid

An attestation of 105 for PRICE:X117-4-attestvalid

Loading the test widget…

An empty event id17-4-empty-idinvalid

Loading the test widget…

A truncated event id17-4-truncatedinvalid

Loading the test widget…

An attestation under the parameter-vote prefix ZBCGOV1:17-4-vote-prefixinvalid

Loading the test widget…

ZBCGOV1: further in the event id is not the prefix17-4-vote-prefix-insidevalid

Loading the test widget…

Defects to match. (1) Tally order is table order; with one row per attester and a quorum above half the set, two values can never both reach it, so the order is unobservable (34 §2). (2) A release-authority proposal is recorded under its address in one spelling (§6), so its id may differ from the one the attester sent. (3) An attester that attests v1 at 100 and v2 at 110 on a branch rolled back to 105 is left with v1 current on every node, the rolled-back one included: the versions make a rollback exact.

5. SetConsensusParam (51) and the price count

Purpose. A registered node's vote on one of the eight governable prices.

Inputs. Body: name_len (u32 LE, 1…128) ‖ name ‖ value (i64 LE); bytes beyond ignored. The governable names and their hard bounds:

Name Min Max
storage_oracle_multiplier_ppm 100,000 10,000,000
dataset_storage_cost_per_mib 1 10,000,000,000
account_rent_period_cost 1 10,000,000,000 (1,000,000,000 under governance_window)
token_persist_period_cost 1 10,000,000,000 (1,000,000,000 under governance_window)
gateway_registration_cost 1 1,000,000,000,000
exchange_taker_fee_bps 1 100
market_creation_cost 1 1,000,000,000,000
min_node_registration_balance 1 the chain's min_node_registration_balance_ceiling (mainnet and TestNet 25,000,000,000 = 250 ZBC; DevNet 250,000,000 = 2.5 ZBC), else 25,000,000,000

Their genesis values: storage_oracle_multiplier_ppm 1,000,000, dataset_storage_cost_per_mib 5,000,000 (DevNet 100,000,000), account_rent_period_cost 1,000,000 (DevNet 100,000,000), token_persist_period_cost 10,000,000 (DevNet 100,000,000), gateway_registration_cost 1,000,000,000, exchange_taker_fee_bps 10, market_creation_cost 5,000,000,000, min_node_registration_balance 10,000,000,000 (DevNet 100,000,000). Every charge reads the value held to these bounds; a value outside the table is never charged.

Output and effect. Execution: a malformed body, a name not in the table, or a value outside [min, the ceiling in force] → paid no-op; the fee (a duty: 0, the node key, §1); an attestation row with event_id = "ZBCGOV1:" ‖ name ‖ ":" ‖ decimal(value), attester = the sender, value = decimal(value) (a later vote of the same registered node for the same event is a new version of the row, §4; the count reads current versions). The generic oracle resolver skips the prefix (§4). A vote beyond the step is not refused: it is limited at the count.

The order inside a block. A vote is written when its transaction executes. After the block's transactions the end-of-block steps run in this order (22): the fee-scale count (§3), …, the oracle resolution (§4, which skips ZBCGOV1: and ZBCREL1:), the bridge deposits and withdrawals (34), the price count (below), then the release governance (§6). So a vote mined in the cycle's last block counts in that block's count.

The count (at the cycle's last block h, h mod L = 0, unless the block is in survival mode, §1a), with nodes = the counted registered nodes at h − 1 (nothing when they fail the registry floor): for each governable name in the table's order with in_force = its row in consensus_parameters, or its compiled value when the chain has no row (the value every charge of that price reads, 32: storage_oracle_multiplier_ppm 1,000,000, dataset_storage_cost_per_mib 100,000,000, and the compiled values of the others), and today = in_force held to the bounds of the table, votes = each registered node's latest vote for that name cast in the cycle's blocks [first, h] (by node key, the newest height, the lower value on a tie; a row that does not parse as a vote for this name is passed over); no vote → nothing; else new = CountAverage(votes, |nodes|, today, min, the ceiling in force at h) (§3); new ≠ in_force → the name's consensus_parameters value set to new (the row keeps its description, 07 §8) and a consensus_parameter_change(parameter, had_row, old, new, height) row written (the rollback record); a write that fails fails the block. No ledger row. A price therefore changes at most once per cycle, and only from votes of that cycle.

How to compute it. Stateless: "SetConsensusParam: truncated body", "… bad parameter-name length", "SetConsensusParam: parameter is not governable: NAME", "SetConsensusParam: NAME below its floor (V < MIN)" / "… above its ceiling (V > MAX)" (the bounds only). No admission state check beyond the duty-sender rule.

Rule activation. governance_window (the 10 ZBC ceiling of the two pruning rents), quorum_floor, duty_fee_free, release_registry_veto (the resolver's skip), survival_mode (§1a), height 0. The count has no rule of its own.

Rejections and errors. As listed.

Vector. computed (TestNet, 11 counted registered nodes): exchange_taker_fee_bps today 10; three registered nodes vote 100 (limited to 12), one votes 1 (limited to 5): sum = 36 + 5 + 7 × 10 = 111, round(111 / 11) = 10.09 → 10 (unchanged). market_creation_cost today 5,000,000,000; six registered nodes vote 1 (limited to 2,500,000,000): sum = 15,000,000,000 + 5 × 5,000,000,000 = 40,000,000,000 → 3,636,363,636. A price at 1 unit voted up by every registered node rises to 2 (the +1 floor of the step).

  • Input: SetConsensusParam (type 51), fee 0, from a node-key account, body 1C000000 ‖ "dataset_storage_cost_per_mib" ‖ 8096980000000000 (40 bytes: name length 28, value 10,000,000). Expected: an attestation row with event_id ZBCGOV1:dataset_storage_cost_per_mib:10000000 (45 bytes), value 10000000.
  • Invalid input: name min_fee → "SetConsensusParam: parameter is not governable: min_fee"; value 0 for exchange_taker_fee_bps → "SetConsensusParam: exchange_taker_fee_bps below its floor (0 < 1)" (stateless, a block carrying it is invalid).

Test cases · §5

6 cases · 4 valid · 2 invalid

The taker fee: three registered nodes vote 100, one votes 117-5-taker-feevalid

Loading the test widget…

The market creation cost: six registered nodes vote 117-5-market-costvalid

Loading the test widget…

A price at one unit voted up by every registered node17-5-from-onevalid

Loading the test widget…

A vote of 0.1 ZBC per MiB for the storage price17-5-votevalid

Loading the test widget…

min_fee is not governable17-5-not-governableinvalid

Loading the test widget…

A taker fee of 017-5-below-floorinvalid

Loading the test widget…

Defects to match. None.

6. RegisterRelease (32), ReleaseAuthorityPropose (33), ReleaseAuthorityAccept (34), RevokeRelease (35)

Purpose. One authority publishes and withdraws release hashes; the registry may veto a release or replace the authority.

Inputs. RegisterRelease body: vlen (u32 LE, 1…256) ‖ version[vlen] ‖ manifest_hash (32, opaque; the publisher's tools put a file's SHA-256 there) ‖ release_address (the rest, a valid address, 01; at least 1 byte). Propose body: the new authority address (whole body, valid). Accept body: ignored. Revoke body: vlen ‖ version.

Output and effect. Register, Propose, Revoke: the sender's canonical address must equal the authority (release_authority row id 1, latest 1; set from the genesis file's release_authority.address, 06) else a paid no-op; the fee; Register writes release_registry(version, manifest_hash, release_address, revoked 0, height) and marks every earlier row of that version latest 0 (one visible row per version string); a version registers once (rule release_registry_veto), so a second RegisterRelease for a version that already has a record (revoked or not) is a paid no-op (admission refuses it); a hot-fix uses a new version string. Propose keeps the authority and sets pending_address. Revoke: an unknown version → nothing more (fee kept), else a new version of the row with revoked 1. Accept: no pending address, or the sender neither byte-equal to it nor the same account (18 §1) → paid no-op; the fee; the authority becomes the pending address and the pending field is cleared. Then 04 §5. Each of the four is refused in survival mode (§1a).

How to compute it. Stateless: "RegisterRelease body too short", "… version length out of range", "… manifest_hash/release_address truncated", "… invalid release_address: …", "RegisterRelease: release_address: a full-key account form (an Ethereum or Tron key, a Bitcoin key) is not an account: no transaction can be sent from it; name the 20-byte address (rule canonical_account_forms)" (a full-key form, 01: an Ethereum or Tron type followed by a 64-byte key, a Bitcoin legacy, P2PKH or P2WPKH type followed by a 33- or 65-byte key); "ReleaseAuthorityPropose: invalid new authority address: …", "ReleaseAuthorityPropose: new authority: a full-key account form (…, as above)", "ReleaseAuthorityPropose: the new authority's kind cannot sign, so it could never accept" (the new authority must later send ReleaseAuthorityAccept, so it must be of a kind that signs, 01); "RevokeRelease body too short", "… version length out of range", "… version truncated". Admission: "not the current release authority", "not the pending release authority", "RegisterRelease: version V is already registered; a version string registers once, use a new one". Execution (block invalid): "RegisterRelease body malformed", "ReleaseAuthorityPropose: empty new authority address", "RevokeRelease body malformed", "Fee cannot be negative".

Rule activation. state_answer_noop, release_registry_veto, survival_mode (§1a), canonical_account_forms (the address forms and kinds above), active from height 0 on every chain.

Rejections and errors. As listed.

Vector. computed (the TestNet genesis file names the release authority ZBC_PWF5RJA5_Z3VETBWR_5GO75GOK_SMBYOS34_HKWH53WN_MCUC6YMQ_EVZAAFOQ = 000000007D8BD8A41DCEEA4986D1E99DFE99CA9303874B7C3AAC7EEECD60A82F61902572).

  • Input: RegisterRelease (type 32) by that authority at height 348, fee 5,000,000, body (92 bytes) 14000000 ‖ 76302E362E312D746573746E65742D61726D3634 (v0.6.1-testnet-arm64) ‖ 908214389DBB341555C3D85B3BF030A0B5F2DD12B037344F799FD21459E247BE (manifest) ‖ 0000000088661FFAB0A2333EDF0B51BDC3CDA35CE3DBF7AB8857EF8E7C44CEB30C7C7469 (release address); no earlier registration of that version.
  • Expected output: the fee's floor kept and its overpay refunded (04); /release/list holds {"version":"v0.6.1-testnet-arm64","manifest_hash":"908214389dbb341555c3d85b3bf030a0b5f2dd12b037344f799fd21459e247be","release_address":"0000000088661ffab0a2333edf0b51bdc3cda35ce3dbf7ab8857ef8e7c44ceb30c7c7469","revoked":false,"block_height":348}; /release/latest is that version (the newest unrevoked by height) and /release/authority is {"found":true,"authority_address":"000000007d8bd8a41dceea4986d1e99dfe99ca9303874b7c3aac7eeecd60a82f61902572","pending_address":""}. The version parses to bundle id 601 (below), so from this registration bundle 601 has the floor 348 + 5,760 = 6,108 on that chain.
  • Invalid input: the same body sent again → refused at admission "RegisterRelease: version v0.6.1-testnet-arm64 is already registered; a version string registers once, use a new one"; mined, a paid no-op. The same body from any other account → "not the current release authority" (admission); mined, a paid no-op. A body with vlen 0 → "RegisterRelease: version length out of range" (stateless). A ReleaseAuthorityPropose whose body is the ZBS_ address 0A000000 ‖ 32 × 00 (type 10, which cannot sign) → "ReleaseAuthorityPropose: the new authority's kind cannot sign, so it could never accept"; whose body is the full-key form 04000000 ‖ 79BE667EF9DCBBAC55A06295CE870B07029BFCDB2DCE28D959F2815B16F81798483ADA7726A3C4655DA4FBFC0E1108A8FD17B448A68554199C47D08FFB10D4B8 (68 bytes: the 64-byte key of the secp256k1 private key 1, whose 20-byte form is 04000000 ‖ 7E5F4552091A69125D5DFCB7B8C2659029395BDF) → "ReleaseAuthorityPropose: new authority: a full-key account form (an Ethereum or Tron key, a Bitcoin key) is not an account: no transaction can be sent from it; name the 20-byte address (rule canonical_account_forms)"; the RegisterRelease body above with that 68-byte form as release_address (124 bytes) → "RegisterRelease: release_address: a full-key account form (…)". All stateless: refused at admission, and a block carrying one is invalid.

Test cases · §6

25 cases · 19 valid · 6 invalid · 1 reference

The RegisterRelease of v0.6.1-testnet-arm64 by the genesis release authority17-6-registervalid

Loading the test widget…

The release views after that registration at height 34817-6-register-viewsvalidreference

The authority is the genesis file's ZBC_PWF5RJA5_Z3VETBWR_5GO75GOK_SMBYOS34_HKWH53WN_MCUC6YMQ_EVZAAFOQ decoded.

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

list_entry
{"version":"v0.6.1-testnet-arm64","manifest_hash":"908214389dbb341555c3d85b3bf030a0b5f2dd12b037344f799fd21459e247be","release_address":"0000000088661ffab0a2333edf0b51bdc3cda35ce3dbf7ab8857ef8e7c44ceb30c7c7469","revoked":false,"block_height":348}
latest
v0.6.1-testnet-arm64
authority
{"found":true,"authority_address":"000000007d8bd8a41dceea4986d1e99dfe99ca9303874b7c3aac7eeecd60a82f61902572","pending_address":""}
The same version registered again17-6-againinvalid

Loading the test widget…

The same body from another account17-6-not-authorityinvalid

Loading the test widget…

A version length of 017-6-vlen-0invalid

Loading the test widget…

A ReleaseAuthorityPropose naming a ZBS_ address, which cannot sign17-6-propose-zbsinvalid

Loading the test widget…

A ReleaseAuthorityPropose naming an Ethereum account in its full-key form17-6-propose-full-keyinvalid

Loading the test widget…

A RegisterRelease whose release_address is a full-key form (124 bytes)17-6-release-full-keyinvalid

Loading the test widget…

An authority vote spelled in upper case is one event17-6-authority-uppervalid

Loading the test widget…

An authority vote spelled in lower case is one event17-6-authority-lowervalid

Loading the test widget…

A veto vote cast at 20,000 counts through 192,80017-6-vetovalid

Loading the test widget…

After 10,000 survival heights the same veto vote still counts at 200,000 and stops at 202,80117-6-veto-survivalvalid

Loading the test widget…

A veto at quorum marks the release revoked17-6-veto-appliedvalid

Loading the test widget…

An authority event naming a ZBS_ address resolves and changes nothing17-6-authority-zbsvalid

Loading the test widget…

An authority event naming a full-key form resolves and changes nothing17-6-authority-full-keyvalid

Loading the test widget…

An authority event naming a ZooBC account replaces the authority17-6-authority-replacedvalid

Loading the test widget…

The version string v0.6.1-testnet-arm64 parses to bundle 60117-6-bundle-v0_6_1-testnet-arm64valid

Loading the test widget…

The version string 0.6.1 parses to bundle 60117-6-bundle-0_6_1valid

Loading the test widget…

The version string v0.6.1-rc1 parses to bundle 60117-6-bundle-v0_6_1-rc1valid

Loading the test widget…

The version string 0.7 parses to bundle 017-6-bundle-0_7valid

Loading the test widget…

The version string v0.6.100 parses to bundle 017-6-bundle-v0_6_100valid

Loading the test widget…

The version string 0.6.1.2 parses to bundle 017-6-bundle-0_6_1_2valid

Loading the test widget…

Registrations at 348 and 400 give bundle 601 the floor 6,10817-6-floorvalid

Loading the test widget…

A revocation of the first at 7,000 leaves the floor 6,16017-6-floor-revokedvalid

Loading the test widget…

A revocation of both leaves no floor17-6-floor-nonevalid

Loading the test widget…

Defects to match. (1) release_address is stored as sent. (2) Accept accepts a group member of the pending address; Propose and Register do not accept a member of the authority.

Release governance (rule release_registry_veto). Guarantee: the registry, not only the authority, can revoke a bad release and, over a long window, replace a compromised authority key. Inputs: the current AttestEvent rows under the ZBCREL1: prefix from registry attester accounts (§4); the counted registered nodes at the previous height (§1); the stored survival flags (19); the release vote window RELEASE_VOTE_WINDOW_BLOCKS = 4 × 60 × 24 × 30 = 172,800 blocks (30 days on every chain: a safety delay stays in days) and the authority delay RELEASE_AUTHORITY_DELAY_BLOCKS = 4 × 60 × 24 × 7 = 40,320 (a week). The age of a vote at block h is h − its height − the survival heights in (its height, h] (the heights whose stored survival flag is on; 13 §8): a frozen chain does not spend the window or the delay, so a freeze longer than the window does not expire the votes cast before it, and they count at the first unfrozen block. At execution an AttestEvent with a ZBCREL1:authority: id is recorded under the canonical id: the payload hex (either case) is decoded, and when it is a valid typed address (01 §4) the id becomes "ZBCREL1:authority:" ‖ lower-case hex of those bytes; any other id (a bare 32-byte key included: it is no address) is stored as sent. Effect (the end-of-block step right after the price count of §5, skipped while the block is in survival mode, §1a; the oracle resolver skips these events): for each unresolved ZBCREL1: event whose newest current vote has age ≤ 172,800, over the counted registered nodes' attesters (and only when the §1 floor is met over the counted registered nodes): oldest = the lowest height of a current vote of the event with age ≤ 172,800 (an older vote's age is never smaller, so every current vote at or above oldest is in the window); the votes tallied are the current votes at or above oldest by attesters of the counted set, in table order, grouped by value, at quorum_for = QuorumAgainstDenominator(n_now, n_then, num, den) = ceil(max(n_now, n_then) × num / den), n_then = the counted registered nodes at oldest − 1: a ZBCREL1:veto:<version> at quorum marks that release row revoked (exactly as RevokeRelease; an unregistered or already-revoked version does nothing); a ZBCREL1:authority:<hex> is tallied only once the vote at oldest has age ≥ 40,320, and on quorum replaces the release_authority with that address and clears the pending field (a proposal naming the current authority does nothing). The tally is one-shot: the first value to reach the quorum writes oracle_result(event_id, value, h) and the event is never tallied again. How to compute: VetoEventId(version) = "ZBCREL1:veto:" ‖ version; AuthorityEventId(hex) = "ZBCREL1:authority:" ‖ lowercase hex of the 36-byte address; the quorum is QuorumAgainstDenominator above. An authority event that reaches its quorum resolves (its oracle_result row is written and it is never tallied again) but changes nothing when its address is not a valid typed address, is a full-key form, is of a kind that cannot sign (rule canonical_account_forms: such an authority could never send a RegisterRelease), or is the current authority; the node logs the reason ("authority proposal names an account that can never sign" for the two cases of the rule). Rule activation: release_registry_veto, governance_window, survival_mode, canonical_account_forms (active from height 0 on every chain). Rejections: none (a block step; a malformed or unknown event is logged and skipped). Vector: computed: the AttestEvent ids ZBCREL1:authority:000000007D8BD8A41DCEEA4986D1E99DFE99CA9303874B7C3AAC7EEECD60A82F61902572 and ZBCREL1:authority:000000007d8bd8a41dceea4986d1e99dfe99ca9303874b7c3aac7eeecd60a82f61902572 are recorded as one event, the second spelling; with 11 counted registered nodes now and 12 at the oldest vote the quorum is ceil(24 / 3) = 8. On a chain never in survival mode: an authority vote first cast at height 20,000 can resolve no earlier than 60,320; a veto vote cast at 20,000 counts through height 192,800 and not at 192,801. On a chain whose survival flag was on for 10,000 heights after 20,000: that veto vote still counts at 200,000 (age 170,000) and stops at 202,801; the authority vote resolves no earlier than 70,320. ZBCREL1:veto:v0.6.1-testnet-arm64 at quorum marks the row of the vector above revoked, and bundle 601 then has no floor from that registration (below). An authority event ZBCREL1:authority:0a000000 ‖ 64 × 0 (a ZBS_ address), or one naming the 68-byte full-key form of the invalid vector above, that reaches its quorum is resolved and leaves the authority as it was. Defect: a veto needs the same supermajority as a parameter change; a minority cannot pull a release, and below the floor of quorum_floor even a supermajority cannot.

Release votes are AttestEvent duties: fee 0, sent by the node-key account.

The registry as the readiness floor (rule readiness_registry_schedule). Guarantee: a rule bundle (29) can activate only after its release has been registered for a day, and every node, whatever binary it runs, computes that floor from the registry alone. Inputs: the release_registry rows as of a height. How to compute: a version string parses to a bundle id as an optional leading v or V, then major.minor.patch in decimal (minor and patch ≤ 99, each part at least one digit), the rest of the string (a suffix such as -testnet-arm64) ignored; anything else parses to 0 (no bundle); the id is major × 10,000 + minor × 100 + patch (v0.6.1-testnet-arm64 → 601). As of a height, the bundle's floor is the lowest block_height among the rows in force at that height (the newest row of each version at or below it) whose version parses to the id and whose revoked is 0, plus ACTIVATION_FLOOR_BLOCKS = 5,760 blocks (a day); with no such row the bundle has no floor and does not activate at that height. The floor is the bundle's whole schedule: it activates at the first height at or after the floor where the readiness tally of 29 passes (the binary's compiled height is not consulted). So the authority's RegisterRelease of a version of the release starts that clock; a RevokeRelease, or a registry veto, of every registration of the bundle's versions before activation stops the pending bundle; a revocation after activation changes nothing. The registry is versioned, so a node rebuilding over history answers for a past height what the chain answered then. Rule activation: readiness_registry_schedule (active from height 0 on every chain). Vector: computed: v0.6.1-testnet-arm64 → 601, 0.6.1 → 601, v0.6.1-rc1 → 601, 0.7 → 0, v0.6.100 → 0, 0.6.1.2 → 0; registrations of v0.6.1-testnet-arm64 at 348 and v0.6.1-testnet-amd64 at 400 give bundle 601 the floor 348 + 5,760 = 6,108 as of every height from 348; a revocation of the first at 7,000 leaves the floor 400 + 5,760 = 6,160 as of 7,000 and a revocation of both leaves none. Defects: none.

7. RegisterGateway (36), GatewayHeartbeat (37), UnregisterGateway (38) and the prune

Purpose. A gateway proves ownership of a stake and of liveness.

Inputs. Register body: gateway_key (32) ‖ dlen (u32 LE, 1…256) ‖ domain ‖ ulen (u32 LE, 1…1,024) ‖ url (to the end). Heartbeat body (exactly 132): gateway_key (32) ‖ ref_height (u32 LE) ‖ ref_hash (32) ‖ signature (64, over the first 68 bytes, by the gateway key: Ed25519). Unregister body: gateway_key (32).

Output and effect. Domain: 1…256 bytes of A-Z a-z 0-9 . -; url: begins https:// (or http:// when the parameter registry_url_allow_http ≠ 0; absent in both live genesis files), ≤ 1,024 bytes, no byte < 0x21, no 0x7F, none of " ' < > `` ``. Register: the fee; an Active row for the key → nothing more (fee kept); the stake = the voted gateway_registration_cost held to its bounds (§5; genesis 1,000,000,000 = 10 ZBC; the compiled value when absent), read when the transaction is checked, reserved and executed, leaves the sender (row event 64; unaffordable → block invalid after returning the fee); the row gateway_registry(gateway_key, owner = canonical sender, domain, url, locked_stake = that stake, last_heartbeat_height = height, verified_count 0, status 0); unregistering or the prune returns the locked_stake recorded, whatever the price is by then. Heartbeat: the fee; a missing or inactive gateway → nothing more; the signature over the first 68 bytes must verify for the gateway key the registry holds (never a key the body supplies), else nothing more (rule admission_checks_in_block: a paid no-op); ref_height must be ≤ the tip and within GATEWAY_HEARTBEAT_FRESHNESS_WINDOW 20 blocks of it (at execution the block being applied is not yet stored, so the tip is its parent, h − 1, on every node), and the main-chain block at ref_height must have hash ref_hash, else nothing more; last_heartbeat_height = height (new version). Unregister: the fee; inactive or unknown → nothing more; sender ≠ owner → nothing more; the owner +locked_stake (row event 65); status 1. Prune, every block (after the schedules, before the storage rent, 22): every Active row with a version height > 0 and last_heartbeat_height < height − (gateway_heartbeat_interval + gateway_prune_grace) (240 + 480 on TestNet and DevNet; compiled 5,760 + 11,520), in version order: owner +stake (row event 31, transaction_id 0, the block's timestamp), status 1; a credit refused for a reason every node computes (the owner's balance would overflow, or its address fails the typed-address check of 01) sends the stake to the longevity pool instead (row event 50 on the pool, transaction_id 0; rule failed_credit_to_pool, 13 §10), never nowhere. Then 04 §5.

How to compute it. Stateless: the length texts "RegisterGateway body too short", "… domain length out of range", "… domain/url truncated", "… url length out of range", "… url length mismatch", "RegisterGateway: domain must be 1-256 chars of A-Z a-z 0-9 . -", "…: url must begin https:// and contain no whitespace, control character, quote, angle bracket or backtick"; "GatewayHeartbeat body must be exactly 132 bytes"; "UnregisterGateway body must be exactly 32 bytes". Admission: "RegisterGateway: gateway already active", "… cost+fee overflow", "… insufficient balance for stake+fee" (balance, not spendable); "GatewayHeartbeat: gateway not active", "… signature does not verify against the registered gateway key", "… reference block not fresh", "… reference block not found", "… reference block hash mismatch"; "UnregisterGateway: gateway not active", "… not the gateway owner". Execution (block invalid): "RegisterGateway body malformed (domain)", "… (url)", "GatewayHeartbeat bad body length", "UnregisterGateway bad body length", "Fee cannot be negative". The stake is reserved at admission (04 §7).

Rule activation. admission_checks_in_block (the heartbeat's signature at execution), failed_credit_to_pool (the prune's refund), active from height 0 on every chain.

Rejections and errors. As listed.

Vector. computed (from the TestNet genesis file, whose gateways[] names one gateway): GET /api/v1/registry/gateways before any gateway transaction answers one row, the genesis gateway {"domain":"zoobc.network","gateway_address":"ZBG_SPF4XQ7D_2O3ULG4I_D2X5X4HM_IYUCIWM5_4IK74SGR_QGAFIQN7_SCFK2UQO","gateway_key":"93CBCBC3E3D3B7459B881EAFDBF0EC462824599DE215FE48D181805441BF908A","height":0,"last_heartbeat_height":0,"locked_stake":0,"owner":"ZBC_5VJEDDEI_U3PTD7CN_VYSSHQLH_HSZOFBTR_BMGRZGPP_DOZHKAIB_IRIQ4P5D","owner_address":"00000000ED52418C88A6DF31FC4DAE2523C1673CB2E286710B0D1C99EF1BB27501014451","status":0,"url":"https://zoobc.network","verified_count":0} (version height 0: never pruned until a heartbeat rewrites it; the key and owner are the genesis file's ZBG_ and ZBC_ texts decoded, 01 §5).

computed:

  • Input: RegisterGateway (type 36) with key K (32 bytes), domain gw.example.org (14 bytes), url https://gw.example.org (22 bytes): body K ‖ 0E000000 ‖ 67772E6578616D706C652E6F7267 ‖ 16000000 ‖ 68747470733A2F2F67772E6578616D706C652E6F7267 (76 bytes), at TestNet height h. Expected: the sender −1,000,000,000 (row event 64); the row Active with locked_stake 1,000,000,000, last_heartbeat_height h; with no heartbeat it is pruned at the first block > h + 720 (the owner +1,000,000,000, event 31).
  • Input: a GatewayHeartbeat of 132 bytes naming the main-chain block at tip − 5 with its hash and K's signature over the first 68 bytes. Expected: last_heartbeat_height = the block's height. The same body with 64 other bytes in place of the signature → refused at admission "GatewayHeartbeat: signature does not verify against the registered gateway key"; mined, a paid no-op (the row unchanged).
  • Invalid input: url http://gw.example.org → "RegisterGateway: url must begin https:// and contain no whitespace, control character, quote, angle bracket or backtick"; domain gw_example.org → "RegisterGateway: domain must be 1-256 chars of A-Z a-z 0-9 . -"; a heartbeat of 131 bytes → "GatewayHeartbeat body must be exactly 132 bytes" (all stateless); a heartbeat naming the block at tip − 21 → "GatewayHeartbeat: reference block not fresh" (admission).

Test cases · §7

10 cases · 5 valid · 5 invalid · 1 reference

A gateway registered at 1,000 and never heard from17-7-registervalid

Loading the test widget…

An http:// url17-7-httpinvalid

Loading the test widget…

A domain with an underscore17-7-underscoreinvalid

Loading the test widget…

A heartbeat of 131 bytes17-7-heartbeat-131invalid

Loading the test widget…

A heartbeat naming the block at tip - 517-7-freshvalid

Loading the test widget…

A heartbeat naming the block at tip - 2117-7-staleinvalid

Loading the test widget…

A heartbeat naming the block at tip - 5, signed by the gateway key17-7-heartbeatvalid

Loading the test widget…

The same body with 64 other bytes in place of the signature17-7-heartbeat-bad-signatureinvalid

Loading the test widget…

Mined, that heartbeat is a paid no-op: the row is unchanged17-7-heartbeat-bad-signature-minedvalid

Loading the test widget…

The gateway view before any gateway transaction: the genesis gateway17-7-genesis-gatewayvalidreference

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

value
{"domain":"zoobc.network","gateway_address":"ZBG_SPF4XQ7D_2O3ULG4I_D2X5X4HM_IYUCIWM5_4IK74SGR_QGAFIQN7_SCFK2UQO","gateway_key":"93CBCBC3E3D3B7459B881EAFDBF0EC462824599DE215FE48D181805441BF908A","height":0,"last_heartbeat_height":0,"locked_stake":0,"owner":"ZBC_5VJEDDEI_U3PTD7CN_VYSSHQLH_HSZOFBTR_BMGRZGPP_DOZHKAIB_IRIQ4P5D","owner_address":"00000000ED52418C88A6DF31FC4DAE2523C1673CB2E286710B0D1C99EF1BB27501014451","status":0,"url":"https://zoobc.network","verified_count":0}

Defects to match. (1) Any account may send a heartbeat; liveness is proven by the gateway key's signature alone, re-verified at execution, and the freshness and the hash are re-checked at execution against the block's parent, the same on every node. (2) A genesis gateway is never pruned until it is rewritten by a heartbeat. (3) The freshness window is the compiled 20, not the parameter.

8. RegisterArchival (46), UnregisterArchival (47), RegisterRelay (48), UnregisterRelay (49)

Purpose. Node owners declare public archival endpoints and relays.

Inputs. RegisterArchival body: node_public_key (32) ‖ dlen ‖ domain ‖ ulen ‖ url (the §7 rules). RegisterRelay body: relay_key (32) ‖ gateway_key (32) ‖ dlen ‖ domain ‖ ulen ‖ url. Unregister bodies: the key (32).

Output and effect. RegisterArchival: the fee; the key must be a registered node whose owner is the sender (canonical), else nothing more; an Active row owned by someone else → nothing more; the row archival_registry(node_public_key, owner, domain, url, status 0) (a new version replaces the owner's own). RegisterRelay: the fee; from relay_owner_gates the gateway must be an Active gateway owned by the sender, and the relay key must not be another owner's registered node key, else nothing more; an Active row owned by someone else → nothing more; the row relay_registry(relay_key, owner, gateway_key, domain, url, status 0). Unregister (both): the fee; unknown, withdrawn or not the owner → nothing more; status 1. No stake moves. Then 04 §5.

How to compute it. Stateless: the length and domain/url texts of §7 with the type's name; "UnregisterArchival body must be exactly 32 bytes", "UnregisterRelay body must be exactly 32 bytes". Admission (archival), judged against the registry at the next height: "RegisterArchival: node_public_key is not a registered node", "RegisterArchival: only the node's owner may declare it archival". Execution (block invalid): "RegisterArchival body too short", "… body malformed", "RegisterRelay body too short", "… body malformed", the 32-byte texts, "Fee cannot be negative".

Rule activation. relay_owner_gates (height 0).

Rejections and errors. As listed.

Vector. computed (from the TestNet genesis file's archival_nodes[] and relays[], the ZNK_ / ZBR_ texts decoded, 01 §5): before any registry transaction GET /api/v1/registry/archivals → {"archivals":[{"domain":"zoobc.network","url":"https://zoobc.network","node_public_key":"eb89f581920cac9343663a33911d76cef5c89390f25865651d902792b881ad65","owner_address":"00000000ed52418c88a6df31fc4dae2523c1673cb2e286710b0d1c99ef1bb27501014451","block_height":0,"status":0}]}; /registry/relays holds one genesis relay (relay.zoobc.network, relay key 37008FC9…, bound to the genesis gateway 93CBCBC3…908A, the same owner).

computed:

  • Input: RegisterArchival (type 46) by the owner of node N (key N, 32 bytes), domain ar.example.org, url https://ar.example.org: body N ‖ 0E000000 ‖ "ar.example.org" ‖ 16000000 ‖ "https://ar.example.org" (76 bytes). Expected: the fee; the row (N, owner, domain, url, status 0).
  • Invalid input: the same from another account → refused at admission "RegisterArchival: only the node's owner may declare it archival"; mined, a paid no-op (nothing written). UnregisterArchival with a 33-byte body → "UnregisterArchival body must be exactly 32 bytes".

Test cases · §8

4 cases · 2 valid · 2 invalid · 1 reference

The owner of node N declares it archival17-8-registervalid

Loading the test widget…

Another account declares node N archival17-8-not-ownerinvalid

Loading the test widget…

An UnregisterArchival of 33 bytes17-8-unregister-33invalid

Loading the test widget…

The archival and relay registries before any registry transaction, from the genesis file17-8-genesis-registriesvalidreference

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

archivals
{"archivals":[{"domain":"zoobc.network","url":"https://zoobc.network","node_public_key":"eb89f581920cac9343663a33911d76cef5c89390f25865651d902792b881ad65","owner_address":"00000000ed52418c88a6df31fc4dae2523c1673cb2e286710b0d1c99ef1bb27501014451","block_height":0,"status":0}]}
relays
one genesis relay, relay.zoobc.network, relay key 37008FC9..., bound to the genesis gateway 93CBCBC3...908A, the same owner

Defects to match. An archival registration by a non-owner is admission-refused but, if mined, a paid no-op.

9. The announcement registry (node-local)

Purpose. What a node keeps in memory about gateways, archivals and relays it hears of.

Inputs. POST /api/v1/gateway/announce, /archival/announce, /relay/announce and peer gossip, each carrying owner_address (ZBC text), a 32-byte service key, a 32-byte node key, a timestamp and the owner's signature over the ASCII string TYPE ‖ ":" ‖ lowercase hex(service key) ‖ ":" ‖ decimal(timestamp) with TYPE GATEWAY, ARCHIVAL, RELAY or GATEWAY_REMOVE.

Output and effect. Accepted when the signature verifies for the owner's key, the node key is a registered node of that owner, the host or url is public (unless configured otherwise), the entry is not re-announced within 300 s, and the table holds fewer than 1,000 entries; entries start unverified, are verified by the node's own health check, and expire when not verified within the node's TTL. None of this is consensus; /gateways, /archivals, /relays serve it.

How to compute it. As stated.

Rule activation. None.

Rejections and errors. The announcement routes answer with texts such as "Invalid owner signature", "Gateway announcement rate limited", "Gateway registry is full" (31).

Vector. None needed.

Test cases · §9

1 case · 1 valid · 1 reference

The node-local announcement registry has no consensus vector17-9-nonevalidreference

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

value
none needed

Defects to match. None: an implementation may keep any registry it likes.

10. Ledger rows, views and the consensus/local split

Event Row Written by
11 / 12 voter −fee FeeVoteCommitment / FeeVoteReveal (their fee row; none for a duty's fee 0)
23 recipient +amount a trigger fired by an event
64 / 65 / 31 owner −stake / +stake / +stake RegisterGateway / UnregisterGateway / the prune
1, 22, 47 per 04 §5 every type here

Views: /release/list (releases[]: version, manifest_hash, release_address, revoked, block_height; visible rows only), /release/latest (found, version, manifest_hash, release_address), /release/authority (found, authority_address, pending_address), /registry/gateways (domain, gateway_address (ZBG_ text), gateway_key, height, last_heartbeat_height, locked_stake, owner (ZBC_ text), owner_address, status, url, verified_count), /registry/archivals (archivals[]), /registry/relays, /governance/params (transaction_type 51, rule "average", up_limit_pct 20, down_limit "half", cycle_length, cycle_first_block, count_height, counted_seats, registry_floor, floor_met, parameters[] with current, min, max, votable_min, votable_max, votes_this_cycle, projected), /governance/proposals (the same cycle fields and each parameter's votes), /blockchain/fee-params (31 has the full shapes). No step writes a ledger row for an oracle resolution or a parameter change.

The tables (every height an unsigned 32-bit integer; text columns are byte strings; a versioned table has latest 0/1 and keeps one row per change, 07 §2; a rollback to H deletes every row above H and restores latest on the newest remaining row of each key):

Table Columns Key Versioned
fee_vote_commitment_vote vote_hash (32 bytes), voter_address (typed account), block_height (voter_address, vote_hash, block_height) no (rows above H deleted on rollback)
fee_vote_reveal_vote recent_block_hash (32), recent_block_height, fee_vote (i64), voter_address, voter_signature, block_height (block_height, voter_address) no
fee_scale fee_scale (i64), block_height, latest block_height yes (one row, latest 1, is in force)
oracle_attestation event_id (text), attester (typed account), value (text), block_height, latest (event_id, attester, block_height) yes: a later attestation by the same account is a new version and the older one keeps latest 0 (§4); pruned by 13 §8
oracle_result event_id (text), value (text), resolved_height event_id no
consensus_parameters the parameter's name and value (07) name the change record below restores it
consensus_parameter_change id (ascending), parameter_name, had_row (0/1), old_value, new_value (i64), block_height id no: a rollback above H undoes each change in reverse id order (restoring old_value, or deleting the row when had_row is 0)
release_registry version (text), manifest_hash (32), release_address, revoked (0/1), block_height, latest (version, block_height) yes
release_authority id (always 1), authority_address, pending_address (empty when none), block_height, latest (id, block_height) yes
gateway_registry gateway_key (32), owner_address, domain, url, locked_stake (i64), last_heartbeat_height, verified_count, status (0 Active / 1 gone), block_height, latest (gateway_key, block_height) yes
archival_registry node_public_key (32), owner_address, domain, url, status, block_height, latest (node_public_key, block_height) yes
relay_registry relay_key (32), owner_address, gateway_key (32), domain, url, status, block_height, latest (relay_key, block_height) yes

Reads the logic depends on: a registered node's latest reveal (or vote) in a block range, newest height first, the lower value on a tie; whether a commitment (voter, hash) exists above a height; the unresolved event ids (current attestations with no oracle_result), and for the release step those whose newest current vote's survival-adjusted age is inside the window, with the oldest such vote; the survival heights between two heights (19); a release by version (its latest row), and every version's row in force at a height (§6, the floor); the Active gateways whose last_heartbeat_height is below a height, in version order.

Consensus: every table of this document except the announcement registry; the attester identity, the counted registered nodes and the quorum; the count of every price; the tally order; the resolution order (oracle, bridge, governance, release); the release authority rule; the gateway stake; the prune horizon; the accept/no-op/invalid outcome of each type. Local: the ledger rows, the announcement registry, the views.

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