On this page
  1. How a chapter is built
  2. The chapters
  3. Glossary
  4. Conformance levels
  5. The conformance tests
  6. The two chains
  7. Where to discuss
  8. Licence

The ZooBC protocol specification

Edition 0.6.1 · 36 chapters · 1,007 tests stated in the chapters (33 §4) · 2,508 cases in the test catalogue · 4 conformance levels

ZooBC is a public blockchain whose blocks are made by registered nodes drawn by lot from the previous block's seed, without mining. Each registered node carries a participation score that rises while it makes blocks and is seen by its peers and falls while it is absent; the score sets its share of the rewards, and a node whose score reaches zero leaves the registry. Next to plain payments the chain carries tokens, an exchange, escrow and multisignature accounts, account groups, datasets and decentralised file storage, on-chain apps, on-chain governance of prices and releases, a bridge to foreign chains, and a second chain, the spine chain, whose spine blocks, signed by the registered nodes, let a new node start from a verified snapshot. Accounts of foreign families (Bitcoin, Ethereum, Solana, Polkadot, Cardano, Tron, Ripple, Tezos) hold and send ZBC with their own keys, and a transaction signed by an Ethereum, Solana or Bitcoin wallet can be carried as it is. An account that holds a balance pays a small rent to keep its place, so the state does not grow for ever, and ZBC is never burned: penalties, forfeits and dust go to the longevity pool, which pays them back out over time.

This is the specification of the ZooBC protocol, written so that an implementer can recode a compatible node in any language from these documents alone. A compatible node accepts exactly the blocks and transactions the network accepts, refuses exactly what it refuses with the same reasons, computes the same hashes, selections, balances and state after every block, makes blocks the network accepts, and speaks the same wire protocol and HTTP API. What is specified is everything observable: the bytes on the wire, the bytes that are hashed or signed, every decision (accepted or refused, selected or not, active or not), the state after each block and its storage model, and what a blocksmith must emit. How an implementation reaches these results internally is its own choice.

This edition, 0.6.1, is verified against the reference implementation, version 0.6.1, which both chains run from their genesis block. Every rule of the protocol is active from height 0 on both chains, so each chapter describes one behaviour per mechanism; chapter 29 keeps the activation machinery a future rule will use.

How a chapter is built

Every chapter opens with a header (its status, the version it was verified against, what is out of scope and where that is specified) and §0, the area in one paragraph. Then comes one section per mechanism, always with the same eight headings in this order:

  1. Purpose. What an implementation must do, in one sentence.
  2. Inputs. Every input with its type, width, byte order, encoding and origin.
  3. Output and effect. The contract: the bytes produced, the rows written, or the decision with its exact condition, including integer width, overflow and rounding.
  4. How to compute it. Numbered steps, formulas and offset tables an implementation can follow; any other way that gives the same bytes and decisions is equally valid.
  5. Rule activation. The rule that switches the behaviour on and its height (29); "active from height 0 on every chain" for every rule of this edition, "None" when no rule is involved.
  6. Rejections and errors. What is refused and how: at admission only, as an invalid block, or as a paid no-op; with the exact error text where a peer or a client sees it.
  7. Vector. At least one complete INPUT → EXPECTED OUTPUT example with every value written out, and, where the mechanism refuses things, an invalid input with its exact refusal.
  8. Defects to match. Behaviour of the network that looks wrong but that a compatible node must reproduce (marked ⚠ DEFECT where it matters most), or "None".

Read "Output and effect" first. Where data is stored, the chapter names the tables and describes every read and write in words; chapter 07 holds the full schema. Where a statement could not be verified, the sentence says "I think". A summary section at the end of a chapter (what is consensus and what is node-local) does not carry the eight headings.

The chapters

Chapters 01–07 are the foundation: read them first. 08–18 specify the transaction types, one family per chapter. 19–24 specify what a node does with blocks: validation, blocksmith selection, application and rewards, the periodic steps, receipts, fork choice and sync. 25–26 specify the spine chain and snapshots, 27–28 the peer-to-peer network, 29 the activation of rules by height, 30 the operation of a node, 31 the HTTP API, 32 every constant and parameter, 33 the tests and the conformance checklists, and 34–36 the bridge, equivocation and liveness. The level is the lowest conformance level (below) that needs the chapter.

# Chapter What it specifies Level
01 Primitives and addresses integers and byte order, hash functions, text encodings, the typed account address, its one canonical form per type and its text forms, keyless and derived addresses, the verifiable random function L1
02 Signatures and signing the chain-bound signing digest, verification for every account family and its signature form, carried foreign transactions, multisignature accounts, every other digest a key signs L1
03 The transaction envelope the byte layout of a transaction in every version, the type numbers, sender and recipient, fee, survival, expiry, escrow part, message, the signature length per account type, hash and id L1
04 Fees, admission and the mempool the fee floor and fee scale, what is charged and refunded, the checks before a transaction is pooled, reservation, the worst-case outflow, block assembly L1
05 The block format header fields and bytes, block signature, hash, id and seed, payload hash, Merkle root, the serialized size, wire and API forms L1
06 Genesis the configuration files, parameters and rule heights, the config hash and genesis hash, everything that exists at height 0, the spine genesis, the relaunch L1
07 The state model the schema of every consensus table, versioned rows, accounts, tokens, the ledger, what a reorganisation and a snapshot do to the state L1
08 Transfers, streams, schedules, triggers and the two account policies SendZBC and its batch, liquid payments, triggers, scheduled transfers, split and transact policies L1
09 The node registry registration, update and key rotation, the exit, the claim, attendance, the admission timer and queue, expulsion, maturity, the roll call L1
10 Datasets, dataset objects, the DFS file layer and dataset rent account datasets, object ownership, transfer and policy, deletion votes, DFS files, dataset rent, reserved namespaces L1
11 Decentralised storage stored files, their rent and pool, replica placement, proofs of possession, the epoch tally, access control, the snapshot archive L1, L4
12 Escrow and multisignature accounts sender-issued and receiver-issued escrow, co-signatures, approval, expiry, decline, the multisignature account and its transactions L1
13 Survival the survival field, paid longevity, longevity rent and payout, the pruning horizon, account rent and pruning, token persistence L1
14 Tokens the token row and asset kinds, symbol and name rules, issue, transfer and batch, mint, burn, finance, fees paid in a token L1
15 The exchange swap offers, markets, the order book, matching, cancellation, order expiry and market rent L1
16 On-chain apps app rows and players, create, join, move, resign, timeout, solo draws and payout tables, the rules engine, channel settlement L1
17 Governance and registries who may vote, the survival-mode freeze, fee votes, oracle attestations, parameter votes, releases and the release authority, gateways, archivals, relays L1
18 Account groups group addresses, consent proofs, linking and unlinking members, permissions and limits, rent and dissolution L1
19 Block validation the ordered checks on a received block, application, the candidate pool, outcomes, the serialized size, receipt-once, survival mode L1
20 Blocksmith selection and timing the selection generator, rounds and windows, priority, making a block, skipped blocksmiths, difficulty L1, L2
21 Block application and rewards the order of application, the coinbase, pool and lottery, participation scores, registry changes, ledger rows L1
22 Periodic processors every step that runs at the end of a block: expiries, rents, counts, triggers, tallies, resolutions, the prune L1
23 Receipts the receipt bytes, signed requests, batches and roots, publication and validation, selection, the scramble, linked receipts, the score L1, L2
24 Fork choice and sync cumulative difficulty, the sync loop, fork resolution, checkpoints, rollback, the incomplete-block queue, the wedge L1
25 The spine chain the spine block, its payload, the spine signers, manifests, production, the signature floor and the aggregate signature, signing commitments and non-signing statements, validation L1, L4
26 Snapshots and fast sync when a snapshot is taken, its document and chunks, serving, the manifest walk, download, attestation and application, the archive L1, L4
27 P2P wire protocol transport and framing, the signed call, every message and field, handshake, heartbeat, discovery, receipt requests, block and transaction delivery, sync queries L1, L2
28 P2P behaviour the peer table and nodes behind NAT, bootstrap, failure accounting, charging and rate limits, propagation, sync drivers, production gates L2
29 Rule-activation index the activation clock, where a height comes from, type gates, the table of 125 rules, bundles and the readiness gate, the rules API L1
30 Node operation command line, configuration file, key material, start-up, persistence, timers, roles, self-update, the relaunch and the wedge rebuild L2
31 HTTP API every route with its parameters, response fields, errors and limits, signed requests, the gateway form L3
32 Constants and consensus parameters every value, where it comes from and which one each chain uses, ledger event types, governable bounds, chain types L1
33 Vectors and conformance the chain identity, the primitive vectors, the index of every test, the checklist of each conformance level all
34 The multichain bridge, on-chain side bridge coins, attesters and quorum, deposit attestations and mints, withdrawal requests and burns, the idle window, the keeper, foreign-signed carriers L1
35 Equivocation one block per parent, the EquivocationReport and its charge, the resume exemption, the peer-side verdict, the SpineEquivocationReport L1
36 Liveness and the score road the liveness row and unit clock, loss and climb, suspension, expulsion at zero, signs of life, maturity, the roll call, survival mode L1

Glossary

The words this specification uses, and the chapter that defines each. Protocol names (rules, wire messages and fields, JSON keys, error texts, tables) keep their original spelling even where they use an older word; the text around them explains them with these words.

Term Meaning Defined in
registered node (also: registry node) a node in the node registry, status Registered, allowed to make main chain blocks and to give spine signatures 09 §1
queued node a node waiting in the queue for a place in the registry, status Queued, until the admission timer admits it 09 §7–§10
blocksmith the registered node that makes a main chain block 20
blocksmith selection who may make the next main chain block: the draw from the previous block's seed, by round 20 §1–§3
round one step of blocksmith selection: draw n is round n, each opening 15 seconds after the previous round's target 20 §2
main chain, main chain block the chain of transactions and its blocks 05
spine chain, spine block the slow companion chain and its blocks, one per spine period, carrying key changes and snapshot manifests 25 §1
spine blocksmith the registered node that builds a spine block candidate 25 §5
spine block candidate a spine block that is built and asking for spine signatures, not stored yet 25 §5–§6
spine signature, spine signers a registered node's signature on a spine block candidate; the registered nodes whose spine signatures count 25 §3, §6
signature floor how many spine signatures a spine block needs 25 §6
signing commitment a registered node that gave a spine signature does not sign a different candidate at that height 25 §6a
non-signing statement a registered node's signed statement "I did not sign that candidate"; enough of them free the others from their commitment 25 §6b
producer an older word for blocksmith, kept in parameter names (survival_min_producers) 20
older words inside protocol names "refusal" = non-signing statement, "promise" = signing commitment, "cosign" = spine signature, "threshold" and "bar" = the signature floor, "proposal" = spine block candidate, "checkpoint" = spine block; in 16, "seats" (in error texts and field names) are the players' places in an app 25, 16
node key a bare 32-byte Ed25519 key that identifies a node; never an account 01 §4, 09 §2
owner account the account that registers a node and locks its stake 09 §1
node registry the record of every node with its node key, owner account, stake and status (Registered, Queued, Deleted) 09 §1
account, typed account what holds a balance and signs transactions, written as a 4-byte type number and a payload whose meaning the type decides; every account is typed 01 §4
canonical account form the one byte form of each account type that a transaction can carry; an Ethereum or Tron account is its 20-byte Keccak address, a Bitcoin key-hash account its 20-byte HASH160, and the full-key forms of these types are refused wherever a transaction names an account 01 §4
chain-bound signing digest what every account signs: SHA3-256 over a domain, the chain's genesis hash and the transaction bytes, so a signature is valid on one chain only 02 §1
carrier (foreign carrier) a transaction signed by an Ethereum, Solana or Bitcoin wallet in its own format and carried in the message field of a ZooBC transaction; usable once, bound to this chain 02 §9, 34 §10
paid no-op a transaction that lands in a block, pays its fee and changes nothing else 04 §5
invalid block a block that every node refuses as a whole; its blocksmith loses the block and its turn 19
block seed a verifiable random value per block that nobody can choose: the input of blocksmith selection, the coinbase lottery, receipt selection and the apps draws 05 §5
receipt a registered node's signed statement that it received a block or a transaction from another registered node; it counts as a sign of life 23
participation score a registered node's score that rises while it takes part and falls while it is missing; it sets its share of the rewards, and at zero the node is expelled 36 §2
survival mode the chain's state while fewer than survival_min_producers distinct blocksmiths made the last 120 blocks: governance, the bridge and expulsions freeze until enough make blocks again 36 §12
rule, rule activation a named change of behaviour that takes effect from a block height fixed per chain 29
bundle, readiness gate the rules a release adds, signalled in the block version; on a chain that lists them at a future height, the gate decides from the registry and the signals when they activate 29 §4b
snapshot the state at a reference height in chunks, which a new node downloads instead of replaying history 26
longevity pool the pool that receives penalties, forfeits and dust and pays them back over time; ZBC is never burned 13 §7
account rent the small periodic charge that keeps an account in the state; an account below the rent when it falls due is pruned 13 §9
signed call every peer-to-peer call carries the calling node's key, a stamp, the request digest, a nonce, the receiver's key and a signature over them 27 §1a

Conformance levels

An implementation claims a level when every check of that level's list in 33 passes.

Level Name The node can Checklist
L1 Follower sync from genesis or from a snapshot, validate every block and transaction, hold the same state as the network, follow the same fork choice 33 §5
L2 Blocksmith be registered, make accepted blocks, sign and publish receipts, be scored, suspended and expelled by the same rules, send its fee-free duties 33 §6
L3 Server answer wallets, explorers, tools and gateways with the same HTTP routes, JSON shapes and errors 33 §7
L4 Keeper give spine signatures on spine block candidates, take, serve and attest snapshots, hold storage pieces and prove them 33 §8

The conformance tests

The "Vector" heading of every mechanism is a test: an INPUT with its EXPECTED OUTPUT, or an invalid input with its exact refusal. Every test is computed: it follows from the specification and, where a chain's data is needed, from the shipped genesis files, and it is reproducible offline. Chapter 33 §4 indexes every test of chapters 01–36 with its chapter, section and the number of valid and invalid cases; 33 §2–§3 add the primitive vectors (hashes, generators, keys and signatures) every other test rests on. A page of interactive tests can be built from that index.

The two chains

ZooBC runs two public chains on this release, the TestNet and the DevNet. A chain is identified by its genesis hash: there is no network byte, and every signature is bound to that hash (02 §1).

Field TestNet DevNet
Chain id / spine chain id zoobc-test / zoobc-spine-test zoobc-dev / zoobc-spine-dev
Block time 15 s 15 s
Genesis registered nodes 11 11
survival_min_producers 5 5
Rules 125, every one at height 0 125, every one at height 0
Ethereum RPC chain id 0x0883 followed by the first two bytes of the genesis hash (30) the same derivation
Public read API https://zoobc.network/api/v1/ (31 §9) —

The genesis timestamp is set when a chain is launched: the launch writes it into the genesis files and rebuilds block 0 and spine block 0 from them, so the genesis hash, the block-0 id and the spine block-0 hash a chain announces on its launch day (GET /api/v1/node/info, 33 §1) are its published identity. The genesis files as shipped carry the placeholder timestamp 1,793,509,027; rebuilt from them unchanged, they give the identities below, which 06 §3 and 33 §1 use to check a genesis builder:

Shipped file (timestamp 1,793,509,027) TestNet DevNet
Genesis hash 3A2897E7C5AD6143429BAB33A92D14D11FFD6FC281F2B62A6FD6B49C183B863D A37B1692EC47C7B17A7F9CB4C13CC8A73A1D5E843565A5733B9DA2A544DF99F8
Block-0 id 4,855,352,938,787,711,034 −5,636,457,327,242,085,469
Spine block-0 hash 7CD929C4D52D9C9455ED179D24A65F90ECBF3D1A3E1214A19611635791B3545C 5876B908090A5BCA4BD735DD96A559FD8FBBE64C1419C053DE227BE3CACCEEF3
Ethereum RPC chain id 142,817,832 (0x08833A28) 142,844,795 (0x0883A37B)

06 rebuilds both genesis hashes from the files, and 33 §1 lists how to check a running chain's identity against the API.

Where to discuss

Questions, reports of a statement that does not match the network, and proposals are discussed on the ZooBC forum: https://zoobc.pro.

Licence

© ZooBC Foundation. This specification and its test vectors are licensed under the Creative Commons Attribution 4.0 International licence (CC BY 4.0): you may share and adapt them for any purpose, crediting the ZooBC Foundation. The test code that computes the vectors is licensed under the MIT licence.