On this page
- §0 The area in one paragraph
- 1. Who may vote: attesters, counted registered nodes and quorums
- 1a. Governance in survival mode
- 2. FeeVoteCommitment (7) and FeeVoteReveal (263)
- 3. The fee-scale count
- 4. AttestEvent (17) and the oracle resolution
- 5. SetConsensusParam (51) and the price count
- 6. RegisterRelease (32), ReleaseAuthorityPropose (33), ReleaseAuthorityAccept (34), RevokeRelease (35)
- 7. RegisterGateway (36), GatewayHeartbeat (37), UnregisterGateway (38) and the prune
- 8. RegisterArchival (46), UnregisterArchival (47), RegisterRelay (48), UnregisterRelay (49)
- 9. The announcement registry (node-local)
- 10. Ledger rows, views and the consensus/local split
17 — Governance and registries: fee votes, parameter votes, oracle attestations, releases, gateways, archivals, relays
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 is0000000066A2B2C675658EB327982F0EC7539DE1AB51F528D586FF2F9381AFA15F86EB7E; 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/proposalsin 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 eight
Loading the test widget…
Two of them suspended: nine registered nodes need six
Loading the test widget…
Six counted registered nodes on TestNet: nothing resolves
Loading the test widget…
A node key's attester account
Loading the test widget…
A vote sent with the bare 32-byte node key as sender
Loading the test widget…
The governance view in the first cycle of a chain whose 11 genesis nodes are all registered
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:
- 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;
- 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_scalerow is written (the next count's "this cycle" then starts after the older row), and the cycle's votes lapse; - 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); - 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 window
Loading the test widget…
An AttestEvent in the same block is refused like the vote
Loading the test widget…
A SendZBC in the same block
Loading the test widget…
A cycle's last block in survival mode counts nothing
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 accepted
Loading the test widget…
A window of four distinct blocksmiths at 1,002 turns the flag on again
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_height100 (64000000),fee_vote2,000,000 (80841E0000000000),sig_len64 (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 whosevoter_signatureis 65 bytes ending in00(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 0
Loading the test widget…
Block 120 is in the first half of cycle 0
Loading the test widget…
Block 121 is in the second half of cycle 0
Loading the test widget…
A commitment at block 130
Loading the test widget…
A reveal at block 240 counts for cycle 0
Loading the test widget…
A reveal of 2,000,000 at recent height 100
Loading the test widget…
A 31-byte commitment fails at execution
Loading the test widget…
A 31-byte commitment is refused before execution
Loading the test widget…
An Ethereum-typed reveal whose voter signature ends in 00
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_scalerow (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-paramsanswers"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 scale
Loading the test widget…
No reveal: the scale stays
Loading the test widget…
From a scale of 1 every registered node votes 5
Loading the test widget…
Below the registry floor no registered node counts
Loading the test widget…
The fee parameters before the first count block (the seeded row)
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 idPRICE:X1, value105). - Expected output: the row (
PRICE:X1, the attester,105, h); with 11 counted registered nodes the eighth distinct attester of105resolves it in the block that mines that eighth attestation:oracle_result(PRICE:X1,105, h) and every Pending trigger onPRICE:X1fires. - Invalid input: body
00000000 00000000(empty event id) →"AttestEvent: event_id cannot be empty"(stateless); body08000000 5052(truncated) →"AttestEvent: truncated event_id"; body120000005a4243474f56313a626173655f6665653a390100000031(27 bytes: event idZBCGOV1:base_fee:9, value1) →"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:X1
Loading the test widget…
An empty event id
Loading the test widget…
A truncated event id
Loading the test widget…
An attestation under the parameter-vote prefix ZBCGOV1:
Loading the test widget…
ZBCGOV1: further in the event id is not the prefix
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 withevent_idZBCGOV1:dataset_storage_cost_per_mib:10000000(45 bytes), value10000000. - Invalid input: name
min_fee→"SetConsensusParam: parameter is not governable: min_fee"; value 0 forexchange_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 1
Loading the test widget…
The market creation cost: six registered nodes vote 1
Loading the test widget…
A price at one unit voted up by every registered node
Loading the test widget…
A vote of 0.1 ZBC per MiB for the storage price
Loading the test widget…
min_fee is not governable
Loading the test widget…
A taker fee of 0
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/listholds{"version":"v0.6.1-testnet-arm64","manifest_hash":"908214389dbb341555c3d85b3bf030a0b5f2dd12b037344f799fd21459e247be","release_address":"0000000088661ffab0a2333edf0b51bdc3cda35ce3dbf7ab8857ef8e7c44ceb30c7c7469","revoked":false,"block_height":348};/release/latestis that version (the newest unrevoked by height) and/release/authorityis{"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 withvlen0 →"RegisterRelease: version length out of range"(stateless). A ReleaseAuthorityPropose whose body is theZBS_address0A000000 ‖ 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 form04000000 ‖ 79BE667EF9DCBBAC55A06295CE870B07029BFCDB2DCE28D959F2815B16F81798483ADA7726A3C4655DA4FBFC0E1108A8FD17B448A68554199C47D08FFB10D4B8(68 bytes: the 64-byte key of the secp256k1 private key 1, whose 20-byte form is04000000 ‖ 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 asrelease_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 authority
Loading the test widget…
The release views after that registration at height 348
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 again
Loading the test widget…
The same body from another account
Loading the test widget…
A version length of 0
Loading the test widget…
A ReleaseAuthorityPropose naming a ZBS_ address, which cannot sign
Loading the test widget…
A ReleaseAuthorityPropose naming an Ethereum account in its full-key form
Loading the test widget…
A RegisterRelease whose release_address is a full-key form (124 bytes)
Loading the test widget…
An authority vote spelled in upper case is one event
Loading the test widget…
An authority vote spelled in lower case is one event
Loading the test widget…
A veto vote cast at 20,000 counts through 192,800
Loading the test widget…
After 10,000 survival heights the same veto vote still counts at 200,000 and stops at 202,801
Loading the test widget…
A veto at quorum marks the release revoked
Loading the test widget…
An authority event naming a ZBS_ address resolves and changes nothing
Loading the test widget…
An authority event naming a full-key form resolves and changes nothing
Loading the test widget…
An authority event naming a ZooBC account replaces the authority
Loading the test widget…
The version string v0.6.1-testnet-arm64 parses to bundle 601
Loading the test widget…
The version string 0.6.1 parses to bundle 601
Loading the test widget…
The version string v0.6.1-rc1 parses to bundle 601
Loading the test widget…
The version string 0.7 parses to bundle 0
Loading the test widget…
The version string v0.6.100 parses to bundle 0
Loading the test widget…
The version string 0.6.1.2 parses to bundle 0
Loading the test widget…
Registrations at 348 and 400 give bundle 601 the floor 6,108
Loading the test widget…
A revocation of the first at 7,000 leaves the floor 6,160
Loading the test widget…
A revocation of both leaves no floor
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), urlhttps://gw.example.org(22 bytes): bodyK ‖ 0E000000 ‖ 67772E6578616D706C652E6F7267 ‖ 16000000 ‖ 68747470733A2F2F67772E6578616D706C652E6F7267(76 bytes), at TestNet height h. Expected: the sender −1,000,000,000 (row event 64); the row Active withlocked_stake1,000,000,000,last_heartbeat_heighth; 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"; domaingw_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 from
Loading the test widget…
An http:// url
Loading the test widget…
A domain with an underscore
Loading the test widget…
A heartbeat of 131 bytes
Loading the test widget…
A heartbeat naming the block at tip - 5
Loading the test widget…
A heartbeat naming the block at tip - 21
Loading the test widget…
A heartbeat naming the block at tip - 5, signed by the gateway key
Loading the test widget…
The same body with 64 other bytes in place of the signature
Loading the test widget…
Mined, that heartbeat is a paid no-op: the row is unchanged
Loading the test widget…
The gateway view before any gateway transaction: the genesis gateway
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, urlhttps://ar.example.org: bodyN ‖ 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 archival
Loading the test widget…
Another account declares node N archival
Loading the test widget…
An UnregisterArchival of 33 bytes
Loading the test widget…
The archival and relay registries before any registry transaction, from the genesis file
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 vector
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.