On this page
The ZooBC protocol specification
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:
- Purpose. What an implementation must do, in one sentence.
- Inputs. Every input with its type, width, byte order, encoding and origin.
- Output and effect. The contract: the bytes produced, the rows written, or the decision with its exact condition, including integer width, overflow and rounding.
- 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.
- 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. - 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.
- 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.
- 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.