On this page
- §0 The area in one paragraph
- 1. The transaction signing digest and the transaction hash
- 2. Verification dispatch by account type
- 3. Ed25519 (native, Solana, Cardano, Tezos)
- 3.1 Native accounts (type 0, type 11, unknown types) and raw node-key signatures
- 3.2 Key-carrying envelope (Cardano type 13, Tezos type 16)
- 4. secp256k1 ECDSA, Bitcoin style (types 1, 5, 6, 7, 14)
- 5. secp256k1 ECDSA, Ethereum style (types 4, 15)
- 6. BIP-340 Schnorr (Taproot, type 9)
- 7. sr25519 (Polkadot, type 12)
- 8. Accounts that cannot sign
- 9. Native foreign transactions carried in the message field
- 10. Multi-signature accounts
- 11. Everything else a key signs on this chain
- 12. Off-chain message signing (tools and wallets, not consensus)
- 13. Encrypted messages (not consensus)
- 14. Key derivation (not consensus)
02 — Signatures and signing
Out of scope the byte layout of a transaction (03, this document only names it); fees and admission (04); block, receipt, spine, proof-of-ownership, heartbeat and handshake preimages (owned by 05, 23, 25, 09, 17, 27, listed here in §11 so that an implementer knows every use of a key); the multisig state tables and the inner transaction's effects (12); group semantics (18); the API endpoints that accept signatures (31); the VRF itself (01 §8); the equivocation report's validity and effect (35)
§0 The area in one paragraph
A ZooBC transaction is authorised by one signature over one digest, and the digest is bound to
one chain: SHA3-256("ZBC-TX" ‖ genesis_hash ‖ unsigned transaction bytes). The sender's account
type decides how that 32-byte digest is signed and verified: a native, Solana, Cardano or Tezos
account signs it with Ed25519; a Bitcoin, Ripple, Ethereum or Tron account signs it with
secp256k1 ECDSA after the hashing its home chain uses (double SHA-256 or Keccak-256) and carries
or lets the verifier recover the public key, which must hash to the account's payload; a Taproot
account signs it with BIP-340 Schnorr; a Polkadot account with sr25519. Three foreign wallets may
instead sign their own native transaction (MetaMask, Phantom, a Bitcoin wallet) and carry it in the
transaction's message field; the node then verifies the native signature, requires the native
transfer to agree with the ZooBC one, requires the native transaction to be bound to this chain
(its EVM chain id, a recent main chain block, or the genesis hash as the spent outpoint) and spends
its native transaction id once. The transaction hash is SHA3-256(unsigned bytes ‖ signature) and the transaction id is its first eight bytes. Multi-signature accounts collect
participant signatures over the same chain-bound digest of an inner, unsigned transaction.
Every signature consensus verifies for an Ethereum- or Tron-typed key (the envelope, a multisig
participant's signature, an escrow co-signature, a group consent, a fee-vote reveal) writes its
recovery byte as 27 or 28 and nothing else, so one signer's signature has one byte string.
Everything else a key signs on this chain (blocks, seeds, receipts, spine blocks, proofs of
ownership, votes, consents) is a raw Ed25519 signature over a preimage its own document fixes;
this document lists them so no raw-signed object can be confused with a transaction. Key
derivation and message encryption are conveniences of wallets and tools, not consensus.
A sender is always a typed account (01 §4): a bare 32-byte key is refused before any signature is
checked. Beyond transactions, a node key signs or proves: the block seed (a VRF proof); a block's
signed bytes, which include that 80-byte proof; the two signed block headers an equivocation report
carries; liveness attestations, equivocation reports, a genesis registered node's roll call and storage-proof
batches, as transactions of the node's own typed account; a node-key rotation (proved by the new
key, effective 120 blocks later); a spine block, which signs a fingerprint of the main chain block it
refers to, and its spine signatures, each a signing commitment not to sign another spine block
candidate at that spine height; a signed non-signing statement on a spine block candidate; a request for a receipt (the sender of a block or
transaction signs that the recipient may credit it); a handshake, judged against the receiver's
clock; every call it makes to another node, signed for that node (§11); and a request for an old
archive chunk.
1. The transaction signing digest and the transaction hash
Purpose. Define what a transaction signer signs, what identifies a transaction, and why a signature is valid on exactly one chain.
Inputs. The unsigned transaction bytes U (03 defines them: every field of the envelope
except the signature); the chain's genesis block hash G (32 bytes, 06); the signature S.
Output and effect.
| name | value | width |
|---|---|---|
| signing digest (v2) | SHA3-256( "ZBC-TX" ‖ G ‖ U ), where "ZBC-TX" is the six ASCII bytes 5A 42 43 2D 54 58, no terminator |
32 bytes |
| transaction hash | SHA3-256( U ‖ S ) |
32 bytes |
| transaction id | the first 8 bytes of the transaction hash read as a little-endian int64 |
8 bytes |
The digest is what every account type's signer signs (the per-type schemes in §3–§7 may hash it
again as their native primitive requires). Only the v2 digest is accepted; the unbound digest
SHA3-256(U) ("signing v1", bound to no chain) is never accepted by consensus. A node that does
not know its genesis hash refuses to compute the digest and therefore refuses every transaction
rather than falling back to v1. The genesis hash is the chain's only identity: there is no
network-id field anywhere, and nodes compare this hash before they peer (27).
How to compute it.
- Build
Uas03specifies (type, version, timestamp, sender, recipient, fee, survival for versions 2 and 3, expiry for version 3, body, escrow part, message). digest = SHA3-256(5A42432D5458 ‖ G ‖ U).- Sign
digestas the sender's account type requires (§2–§7). Place the signature bytes afterUto obtain the signed transaction bytes. hash = SHA3-256(U ‖ S);id = int64 LE(hash[0..8]).
Rule activation. None for the digest: the v2 digest is the only accepted digest at every
height. Transaction version 3 (rule tx_expiry_field, at 0 on every chain) only adds its expiry
field to U; the digest formula is the same. Rule typed_accounts_only (at 0 on every chain): a
bare 32-byte sender or recipient is refused before the signature is checked, and U cannot be
built for one (03 §1).
Rejections and errors. A transaction whose sender or recipient is a bare 32-byte key is refused
with accounts are typed: a bare 32-byte key is not an account on this chain before verification. A
transaction whose signature does not verify over the v2 digest is
refused at admission and makes a block invalid (19). The refusal text distinguishes two cases:
"Invalid transaction signature: legacy unbound digest (signing v1); this chain requires signing v2"
when the signature would have verified over SHA3-256(U), and "Invalid transaction signature: not
signed for this chain (genesis xxxxxxxx) with the sender key" otherwise, where xxxxxxxx is the first
four bytes of the verifying node's genesis hash in lower-case hex; both are rejections. An empty signature is rejected ("Empty signature").
Vector (computed with the 32-byte chain identity G below as the genesis hash; the reference's
zbc-cli send-zbc --offline with that genesis produces the same unsigned bytes, digest, signature
and hash, and an independent implementation with another Ed25519 library agrees). A version-3
SendZBC of 1 ZBC with a 7,200-second expiry, sender the key of m/44'/883'/0' and recipient the key
of m/44'/883'/1' of the §14 mnemonic. Every vector of this specification that needs a genesis hash uses
this G; a chain's real G is read from GET /api/v1/node/info (06 §11).
| field | value |
|---|---|
G (the vectors' chain identity) |
E003E4E3557EF19F0519BD345009DEA7FB43B3445EAA043920C5DC23B3302871 |
| sender seed | 51bae95d58f32304a5c9d894819989a4fb04da6115d9a43612a026e7a5dd5d96 (public key 5e8eb28d…2152, ZBC_L2HLFDOM_VKKKTEXX_C2P2M6LG_EB6ZNKSV_356SJUWW_5QPVHDE7_EFJA3PEX) |
| recipient | 00000000fd4472bbdec43b919aa37b9b3366a3318f2902a753a15f5fd6d43c44b5121b67 (ZBC_7VCHFO66_YQ5ZDGVD_PONTGZVD_GGHSSAVH_KOQV6X6W_2Q6EJNIS_DNTVIFT4) |
U (125 bytes, version 3) |
01000000 03 fbc8e66a00000000 000000005e8eb28dccaa94a992f7169fa67966207d96aa55df7d24d2d6ec1f538c9f2152 00000000fd4472bbdec43b919aa37b9b3366a3318f2902a753a15f5fd6d43c44b5121b67 404b4c0000000000 0000000000000000 201c0000 08000000 00e1f50500000000 02000000 00000000: type 1, version 3, timestamp 1,793,509,627, sender, recipient, fee 5,000,000, survival 0, expiry 7,200, body length 8, body 1 ZBC, empty escrow part, empty message (spaces separate fields; remove them) |
| digest | 1ca35831c3eb645739a67034bacebe0a8a95b7ffde0c8656f6fcb58dbe11be1b |
signature S |
f0fc0b0500bad022ba97a355c6cb6f809ab8f79852039744a670dbdc8b090ef838db33715abfdad302f13236caecc7b1f27e486bfef56d716060a9bee363a406 |
| transaction hash | 058c3078711492773af075a3b4dd07b44a7e17bd3b3ea985f64677af96a4e467 |
| transaction id | 8,615,971,514,693,487,621 |
SHA3-256(U) = 5d2daae2b808ba51e7a234bce18cd0e4c4328594bfb6f374ad63e411b524bb48 is the unbound
(v1) digest: a signature over it is refused ("Invalid transaction signature: legacy unbound digest (signing v1);
this chain requires signing v2"). The same U signed for any other genesis is refused by a node
whose genesis hash is G ("Invalid transaction signature: not signed for this chain (genesis
e003e4e3) with the sender key"). 03 §1 carries a second computed vector (version 2, escrow and
message).
Test cases · §1
6 cases · 3 valid · 3 invalid
Sign a version-3 SendZBC for the vectors' chain identity G
Loading the test widget…
The unbound digest SHA3-256(U), which is refused
Loading the test widget…
The signed version-3 SendZBC passes the signature check of a node whose genesis hash is G
Loading the test widget…
A signature over the unbound digest SHA3-256(U) is refused
Loading the test widget…
The same U signed for another genesis is refused
Loading the test widget…
An empty signature is refused
Loading the test widget…
Defects to match. None.
2. Verification dispatch by account type
Purpose. Given the sender address, the signature bytes and the digest, decide which scheme verifies and what the signature must look like.
Inputs. digest (32 bytes), signature (bytes), address (the sender's account address,
01 §4).
Output and effect. Accepted or rejected, by this procedure in this order:
- If
addressis exactly 32 bytes: if its first 4 bytes read asint32 LEequal 13 and the signature is 98 bytes, verify as Cardano (§3.2); otherwise treat the 32 bytes as an Ed25519 public key and verify as native (§3.1). (A transaction never reaches this branch with a bare key: it is refused before verification, §1. The branch verifies the raw node-key signatures of §11 and a typed 32-byte Cardano account.) - If
addressis shorter than 4 bytes: reject. - If the type is 16: verify as Tezos (§3.2). If the type is 13: verify as Cardano (§3.2).
- Map the type to a scheme family: 0 → native; 1, 5, 6, 7, 8, 14 → Bitcoin; 4, 15 → Ethereum; 9 → Taproot; 12 → Polkadot; 3 → Estonia eID; 2 → Empty; 10 → DataSet; 11 and every other value → native.
- Decide whether the address is compact: Ethereum family with a 20-byte payload; Bitcoin family (1, 5, 6, 7, 14) with a 20-byte payload; types 8 and 9 with a 32-byte payload. Compact means "the payload is a hash or program, not a key".
- If not compact, the payload after the 4-byte type must be non-empty (it is taken as the public key).
- Check the signature size for the family: native 64; Ethereum 65; Bitcoin family at least 99
(
2 + 33 + 64, the envelope's minimum: a compressed key and the 64-byte compact signature); Taproot 64; Polkadot 64; Estonia eID 96; Empty and DataSet must be non-empty. A wrong size is a rejection ("Invalid signature size for account type"). These are the same lengths the envelope parser takes for each sender type (03§9), so a signature reaches this step exactly as it was signed. - Verify by family: native §3.1; Ethereum §5; Bitcoin §4 (type 8 is rejected: "Bitcoin P2WSH (script) accounts cannot sign transactions on ZooBC"); Taproot §6; Polkadot §7; Estonia eID rejected ("Estonia eID signature verification not implemented"); Empty rejected; DataSet rejected ("Unknown account type").
Rule activation. None.
Rejections and errors. Every "reject" above is a signature failure (§1 Rejections).
Vector (computed). Input: address 08000000 ‖ 1863143c…3262 (type 8, P2WSH) with any 99-byte
or longer signature → expected output: refused ("Bitcoin P2WSH (script) accounts cannot sign transactions on ZooBC"). Input: address
00000000 ‖ 5e8eb28d…2152 with a 65-byte signature → refused ("Invalid signature size for account
type", the native family takes 64). Input: address 05000000 ‖ 61dd2f1c…a456 (§4) with a 98-byte
field → refused ("Invalid signature size for account type", below 99). The accepted cases are the
vectors of the family sections.
Test cases · §2
3 cases · 3 invalid
A P2WSH (script) account cannot sign
Loading the test widget…
A 65-byte signature on a native account is the wrong size
Loading the test widget…
A 98-byte field on a P2WSH account is refused by its size first
Loading the test widget…
Defects to match. (a) An unknown type number is verified as native Ed25519 over the payload;
an implementation must not reject unknown types earlier than the reference does (a transaction from such an
account fails only if the payload is not the signing key). (b) Type 11 (Solana) has no entry in
the dispatcher's enum and reaches the native branch through the default. (c) Type 1 is still
dispatched to the Bitcoin family although the text decoder never produces it (01 §6).
3. Ed25519 (native, Solana, Cardano, Tezos)
3.1 Native accounts (type 0, type 11, unknown types) and raw node-key signatures
Purpose. The scheme of ZooBC's own keys.
Inputs. digest (32 bytes), signature (64 bytes), public key (32 bytes = the address
payload).
Output and effect. Valid when the signature is a valid Ed25519 (RFC 8032, pure, no prehash)
signature of the 32-byte digest itself under the public key, as checked by libsodium's detached
verification: the scalar S must be canonical (less than the group order) and a
public key or R of small order is rejected. A public key whose 32 bytes are not a canonical
encoding (its y value, the low 255 bits read little-endian, is not below p = 2²⁵⁵ − 19) is rejected
too; this is what makes the burn address of 01 §7 unspendable, and libsodium 1.0.18 refuses
that key (tested). I think the complete list is libsodium's from 1.0.16 on: S canonical, R not
of small order, the key canonical and not of small order, and the equation checked without the
cofactor, as encode(S·B − h·A) equal to the 32 R bytes with h = SHA-512(R ‖ A ‖ digest)
reduced mod ℓ (the library's source was not read for this list). An implementation using another library must apply the same checks or it will accept
signatures the reference rejects. Signing is deterministic: the same key and digest always give the
same 64 bytes.
How to compute it. signature = Ed25519.sign(secret, digest); R ‖ S in the standard
64-byte encoding. The ZooBC "private key" of a native account is the 32-byte Ed25519 seed; the
64-byte libsodium secret key is seed ‖ public key.
Rule activation. None.
Rejections and errors. Wrong key size (not 32), wrong signature size (not 64), or a failed verification.
Vector (computed). Input: digest 1ca35831…be1b, public key 5e8eb28d…2152, signature
f0fc0b05…a406 (all of 02 §1) → expected output: valid. The same signature with its first byte
changed to f1 → invalid. The public key FF × 32 (the burn address payload) with any signature
→ invalid.
Test cases · §3.1
5 cases · 5 valid
A native signature verifies
Loading the test widget…
The same signature with its first byte changed does not
Loading the test widget…
The burn payload is not a key: nothing verifies under it
Loading the test widget…
The §1 signature verifies for the typed native account
Loading the test widget…
Nothing verifies for the burn address
Loading the test widget…
Defects to match. None.
3.2 Key-carrying envelope (Cardano type 13, Tezos type 16)
Purpose. Accounts whose payload is a hash of an Ed25519 key, so the key must travel with the signature and be bound to the account.
Inputs. digest; a 98-byte signature field; the address payload (28 bytes for Cardano, 20 for
Tezos).
Output and effect. Signature field layout:
| offset | length | field |
|---|---|---|
| 0 | 2 | public key length, uint16 LE, must be 32 |
| 2 | 32 | Ed25519 public key |
| 34 | 64 | Ed25519 signature of digest under that key |
Valid when the address is exactly 4 + 28 (Cardano) or 4 + 20 (Tezos) bytes, the field is
exactly 98 bytes, the declared length is 32, BLAKE2b-28(public key) (Cardano) or
BLAKE2b-20(public key) (Tezos) equals the address payload, and the 64-byte signature verifies as
in §3.1.
How to compute it. Sign the digest with the key as in §3.1; prepend 20 00 and the key.
Rule activation. None.
Rejections and errors. Address length, field length, declared length, hash mismatch ("Tezos public key does not hash to the account address", or "Cardano public key does not hash to the account address" for a Cardano account), or a failed verification.
Vector (computed). Key 5e8eb28dccaa94a992f7169fa67966207d96aa55df7d24d2d6ec1f538c9f2152
(the §1 sender). Its Tezos payload BLAKE2b-20(key) = ad9198e1ee79f6ba8bd1d834f14b8ca87cc07ed0
(address 10000000 ‖ ad9198e1…7ed0), its Cardano payload BLAKE2b-28(key) =
22abc5de5f77d9fe9d496f361214aad065e66fdcf2f250e2f845d243 (address 0d000000 ‖ 22abc5de…d243).
Input: digest 1ca35831…be1b (§1), the 98-byte field
2000 5e8eb28dccaa94a992f7169fa67966207d96aa55df7d24d2d6ec1f538c9f2152 f0fc0b0500bad022ba97a355c6cb6f809ab8f79852039744a670dbdc8b090ef838db33715abfdad302f13236caecc7b1f27e486bfef56d716060a9bee363a406
and either address → expected output: valid. The same field with the Tezos address
10000000 ‖ 00 × 20 → refused ("Tezos public key does not hash to the account address").
Test cases · §3.2
4 cases · 3 valid · 1 invalid
Tezos and Cardano payloads of a key
Loading the test widget…
A key-carrying signature for the Tezos account of the §1 key
Loading the test widget…
The same field for the Cardano account of the §1 key
Loading the test widget…
The same field for a Tezos account of another key is refused
Loading the test widget…
Defects to match. None.
4. secp256k1 ECDSA, Bitcoin style (types 1, 5, 6, 7, 14)
Purpose. The scheme of Bitcoin-shaped and Ripple accounts, whose payload is HASH160 of a
key or script.
Inputs. digest; a signature field of 99 or more bytes (99 with a compressed key, 131 with an
uncompressed one); the address. In a transaction this field is the last one of the envelope and
runs to its end, for all five types, Ripple included (03 §9).
Output and effect. Signature field layout:
| offset | length | field |
|---|---|---|
| 0 | 2 | public key length L, uint16 LE, 1 ≤ L ≤ 65 (33 or 65 in practice) |
| 2 | L |
secp256k1 public key, SEC1 compressed (33) or uncompressed (65) |
2 + L |
64 | ECDSA signature in compact form r ‖ s, 32 bytes each, big-endian |
Valid when all of: the field has at least one byte after the key (then the remaining bytes must be
exactly 64, or the ECDSA parse fails); the key parses; the key binds to the account:
HASH160(key) equals the stored hash for types 1, 5, 7 and 14, and for type 6
HASH160(00 14 ‖ HASH160(key)) equals it (the account is assumed to be a P2SH-P2WPKH script);
and ECDSA.verify(key, DoubleSHA256(digest), r ‖ s) succeeds. The stored hash is the payload for
a compact (20-byte) address and HASH160(stored key) for the 37- or 69-byte full forms; a full form
is not an account (rule canonical_account_forms, 01 §4), so on a chain only the compact form
reaches this verifier. The
reference verifies with libsecp256k1, which accepts only low-s signatures (s ≤ n/2); a high-s
signature is invalid.
How to compute it. m = SHA256(SHA256(digest)); (r, s) = ECDSA_secp256k1.sign(key, m) with
s normalised low; field = LE16(len(pub)) ‖ pub ‖ r ‖ s.
Rule activation. None.
Rejections and errors. Field shorter than 2 bytes; L = 0 or > 65; no bytes after the key;
hash mismatch ("Bitcoin signature public key does not match account address hash"); parse or
verification failure. Type 8 (P2WSH) is rejected before any of this ("Bitcoin P2WSH (script) accounts cannot sign transactions on ZooBC").
Vector (computed with an independent secp256k1 implementation; the private key is the
SHA-256 of the ASCII string zoobc spec vector key, a published test key). Public key
(compressed) 030d0fdb91231f43aa7416753deddd09c461b7db68d65441bff3e0fc4d3610cdf9, HASH160 =
61dd2f1c61e9972ddeef0a7cd1279034893da456. Input: digest 1ca35831…be1b (§1), address
05000000 ‖ 61dd2f1c61e9972ddeef0a7cd1279034893da456 (P2PKH), the 99-byte field
2100 030d0fdb91231f43aa7416753deddd09c461b7db68d65441bff3e0fc4d3610cdf9 01e8100696bd1d8b9a2516000796c47de37534f8ba082ced211e6b7db7b7fb8d 7bd5900a90925153988895cc14d912487353d78e33ce4b44c0ed83146f9ffbc0
(spaces separate L, key, r, s) → expected output: valid (ECDSA over
SHA256(SHA256(digest)), low s). The same field with the last byte of s changed to c1 →
invalid. The same field with address 05000000 ‖ 00 × 20 → refused ("Bitcoin signature public key does not
match account address hash"). With a 65-byte key the field is 131 bytes. The same field cut to its
first 98 bytes → refused before any hashing ("Invalid signature size for account type").
Test cases · §4
6 cases · 4 valid · 2 invalid
The published secp256k1 test key
Loading the test widget…
A Bitcoin-style signature for a P2PKH account
Loading the test widget…
The same field with the last byte of s changed
Loading the test widget…
The same field cut to its first 98 bytes is refused before any hashing
Loading the test widget…
The same field for another P2PKH account is refused
Loading the test widget…
The same signature with s replaced by n - s (high s) is invalid
Loading the test widget…
Defects to match. A type-6 account can only be spent as P2SH-P2WPKH; any other script hash is unspendable.
5. secp256k1 ECDSA, Ethereum style (types 4, 15)
Purpose. The scheme of Ethereum and Tron accounts, whose payload is the last 20 bytes of
Keccak-256(uncompressed public key).
Inputs. digest; a 65-byte signature (the envelope parser takes exactly 65 bytes for a type-4
and for a type-15 sender, 03 §9); the address (compact 24 bytes; the 68-byte full form carrying
the 64-byte key is not an account, rule canonical_account_forms, 01 §4).
Output and effect. Signature layout: r(32) ‖ s(32) ‖ v(1), r and s big-endian, v the
recovery id written as 27 or 28. Rule eth_signature_canonical_v holds every signature an
Ethereum- or Tron-typed key makes to that form: a signature by a signer of type 4 or 15 (a 32-byte
address is never one) must be exactly 65 bytes with byte 64 equal to 27 or 28, at each of these
sites, each with its own refusal:
| site | refusal | where |
|---|---|---|
| the transaction envelope of a type-4 or type-15 sender whose message is not an Ethereum carrier (§9; a carrier keeps its own chain's form) | "Ethereum signature recovery id must be 27 or 28" | the first stateless check after the signature verified (03 §12): admission and block validation |
a participant signature carried in a MultiSignature body (an empty one is no signature) |
"MultiSignature: participant signature: Ethereum signature recovery id must be 27 or 28" | stateless: admission and block validation |
| a stored participant signature at completion (§10) | none: it does not count toward the threshold | execution |
| a multi-party escrow co-signature by a type-4 or type-15 recipient | "Multi-party escrow: the recipient's co-signature: Ethereum signature recovery id must be 27 or 28" | stateless (12) |
| an account-group consent of kind 0 or 2 | "LinkAccount: member consent: the consent signature: Ethereum signature recovery id must be 27 or 28", or the same after "TransferGroupControl: new controller consent: " (18) |
stateless |
| each participant signature of a kind-1 consent | "LinkAccount: member consent: multisig consent: a participant signature: Ethereum signature recovery id must be 27 or 28" (or after "TransferGroupControl: new controller consent: ") | stateless |
| a fee-vote reveal's voter signature | "FeeVoteReveal: voter_signature: Ethereum signature recovery id must be 27 or 28" | stateless (17) |
a branch's node-registry transaction that the fork weigher must find signed by the node's owner (24) |
none: the transaction is not taken as the owner's | fork choice |
The verifier itself would also read 29, 30 and 0..3; the rule keeps those spellings out.
The signed message is m = Keccak-256(digest) (the digest is hashed once more).
For a compact address: recover the uncompressed key from (m, r, s, v); a high-s signature is
rejected explicitly; the recovered key's address (Keccak-256(key)[12..32]) must equal the
payload. For a full address (reached by no transaction on a chain, above): verify (r, s) against
the stored 64-byte key over m (libsecp256k1 again accepts only low-s). Note that this is not EIP-191 personal_sign: an Ethereum wallet
signing a ZooBC transaction signs Keccak-256(digest) directly; personal_sign appears only in
group consents (§11) and the native-transaction path (§9) is what MetaMask actually uses.
How to compute it. m = Keccak-256(digest); (r, s, recid) = ECDSA_secp256k1.sign_recoverable(key, m)
with low s; field = r ‖ s ‖ (recid + 27).
Rule activation. eth_signature_canonical_v, active from height 0 on every chain: v is 27
or 28 at every site of the table, at admission and in block validation (each refusal is part of the
stateless validation of 03 §12, so a block carrying such a signature at any refusing site is
invalid). Rule canonical_account_forms, active from height 0 on every chain: the full form is not
an account.
Rejections and errors. The signature check runs first: a wrong size is "Invalid signature size
for account type"; high-s ("Non-canonical (high-s) signature rejected"); recovery failure; address
mismatch ("Recovered ETH public key does not match account address"); for the full form a bad stored
key. For the envelope the signature is verified first, so a signature that verifies with byte 64
outside 27..28 is then refused by the envelope's text; at every other site of the table the 27/28
test comes before that site's own verification.
Vector (computed with an independent secp256k1 and Keccak-256 implementation; the §4 test
key). The uncompressed public key of the §4 key hashes to the Ethereum address
36590dc6986e0755e42c7d4c8f385389403230fc. Input: digest 1ca35831…be1b (§1), so
m = Keccak-256(digest) = 2554f428398a1d73d01cb74f1602c0e6a2a27abe1116e3e3b3af3ae0bfd170d5;
address 04000000 ‖ 36590dc6986e0755e42c7d4c8f385389403230fc; the 65-byte signature
01e8100696bd1d8b9a2516000796c47de37534f8ba082ced211e6b7db7b7fb8d 1574799329c0f40c76b79c8221baf5d7ecbfcc55fa435700f40570a473bded63 1b
(r, s, v = 27) → expected output: valid (the recovered key's address equals the payload).
The same signature with v = 1c recovers another key (address 1e3c278c…65e5) → refused
("Recovered ETH public key does not match account address"). The same signature with v = 00
(the same recovery id written as 0) → refused "Ethereum signature recovery id must be 27 or 28".
The same v = 00 copy carried in a MultiSignature body as the signature of participant
04000000 ‖ 36590dc6…30fc → refused "MultiSignature: participant signature: Ethereum signature
recovery id must be 27 or 28" (computed from the rule; nothing is verified first); with v = 1b
it is accepted there and counts at completion if it verifies over the inner digest.
Test cases · §5
9 cases · 6 valid · 3 invalid
Recover the Ethereum signer of the §1 digest
Loading the test widget…
An Ethereum-style signature for the compact Ethereum account
Loading the test widget…
With v = 28 another key is recovered
Loading the test widget…
With v = 28 the signature is refused for the account
Loading the test widget…
The same signature with v written as 0 is refused at the envelope
Loading the test widget…
The verifier itself recovers the same key from v = 0
Loading the test widget…
With v = 27 the envelope's recovery id passes
Loading the test widget…
The v = 0 copy as a MultiSignature participant signature is refused
Loading the test widget…
With v = 27 the participant signature is accepted in the body
Loading the test widget…
Defects to match. None. (The pinned byte matters because the transaction hash covers the
signature bytes: the verifier would recover the same key from v written as 27 or as 0, so a second
spelling of one signature would be a second transaction id.)
6. BIP-340 Schnorr (Taproot, type 9)
Purpose. The scheme of a Taproot account, whose payload is the 32-byte x-only output key.
Inputs. digest; a 64-byte signature; the 36-byte address.
Output and effect. Valid when schnorrsig_verify(output_key = payload, message = digest, signature) holds under BIP-340 with the 32-byte digest as the message (no further hashing, no
tagged-hash of the digest beyond what BIP-340 itself prescribes). The output key is the tweaked
key; the wallet applies the BIP-341 tweak when signing. No public key is carried.
How to compute it. signature = BIP340.sign(tweaked_secret, digest).
Rule activation. None for signing. Taproot accounts as recipients of a SendZBC are gated by
rule taproot_recipients (at 0 on every chain; 08).
Rejections and errors. Address not 4 + 32; signature not 64; invalid x-only key; failed
verification.
Vector (computed with an independent BIP-340 implementation, auxiliary randomness 32 zero
bytes; the §4 test key). Input: digest 1ca35831…be1b (§1), address 09000000 ‖ 0d0fdb91231f43aa7416753deddd09c461b7db68d65441bff3e0fc4d3610cdf9 (the untweaked x-only key is used
as the output key here), signature
b6a33b3465b752f84aefef551e7243f57a9a03a3a9f3960fbc3b062b93b9e07ab3ef746bfc80007bcbb0160bc9dd3c6677f4b7559ff9374b4bafa2bf520ce68b
→ expected output: valid. The same signature over the digest with its first byte changed to 1d
→ invalid.
Test cases · §6
2 cases · 2 valid
A BIP-340 signature for a Taproot account
Loading the test widget…
The same signature over the digest with its first byte changed
Loading the test widget…
Defects to match. None.
7. sr25519 (Polkadot, type 12)
Purpose. The scheme of a Polkadot account, whose payload is the sr25519 public key (AccountId).
Inputs. digest; a 64-byte signature; the 36-byte address.
Output and effect. Signature layout: R(32) ‖ s(32) (compressed Ristretto point, scalar
little-endian). Valid when all of: bit 7 of byte 63 is set (schnorrkel's marker; it is cleared
before use); the cleared s is canonical (reducing s ‖ 32 zero bytes modulo the group order
gives s back); and with the Merlin transcript below, R == s·B − k·PK where B is the
Ristretto basepoint, PK the AccountId, and k the challenge.
Transcript (Merlin over STROBE-128 with the label "Merlin v1.0", exactly as schnorrkel's
signing_context(b"substrate").bytes(msg) followed by verify):
| step | operation | label | bytes |
|---|---|---|---|
| 1 | new transcript | dom-sep |
"SigningContext" |
| 2 | append message | "" (empty label) |
"substrate" |
| 3 | append message | "sign-bytes" |
the 32-byte digest |
| 4 | append message | "proto-name" |
"Schnorr-sig" |
| 5 | append message | "sign:pk" |
PK (32) |
| 6 | append message | "sign:R" |
R (32) |
| 7 | challenge bytes | "sign:c" |
64 bytes, reduced modulo the order to k |
Each "append message" is meta_ad(label) ; meta_ad(LE32(len), more=true) ; ad(bytes); "challenge
bytes" is meta_ad(label) ; meta_ad(LE32(len), more=true) ; prf(len).
How to compute it. Sign with any schnorrkel implementation under the context "substrate"
with the digest as the message. Signatures are randomised; only verification is deterministic.
Rule activation. None.
Rejections and errors. Address not 4 + 32; signature not 64; marker bit clear;
non-canonical s; equation fails.
Vector (observed from the @polkadot/util-crypto library, recorded in the reference's test vectors).
AccountId a4d007a95b28ce117e4051904503612abdcbd22b60475121f92a8b5dedac375a; message (UTF-8)
ZooBC<>Polkadot sr25519 bridge; signature
b4de19f408c1db93087415d018db53565ffab640f4f985a5b690b3fbeb07b605dd1cc4722c1251800ad4cfb55bfd745bf21a8742e9af984f224b2167631a4a80
verifies under context substrate. (On the chain the message is a 32-byte digest; the algorithm
is identical.)
Test cases · §7
2 cases · 2 valid
An sr25519 signature under the context substrate
Loading the test widget…
The same signature over a changed message
Loading the test widget…
Defects to match. None.
8. Accounts that cannot sign
Purpose. State which address types never authorise anything.
Inputs. The sender type.
Output and effect. Type 2 (Empty) and type 8 (P2WSH) are rejected by the dispatcher; type 3
(Estonia eID) is rejected as not implemented; type 10 (DataSet) is refused by the dispatcher ("Unknown account type"). The keyless addresses of
01 §7 (pools, groups, multisig accounts) are type 0: they reach the native branch and fail because
their payload (a hash) is not a key for which a signature can exist.
A bare 32-byte key is not an account and is refused before any of this (§1). Group consents, the
escrow approver, the swap counterparty and app seats additionally refuse up front every address
outside the signing list of 01 §4 (types 2, 3, 8, 10, any unknown type, and a bare key).
How to compute it. Nothing to compute.
Rule activation. None.
Rejections and errors. Signature failure, or "Bitcoin P2WSH (script) accounts cannot sign transactions on ZooBC", "Estonia eID signature verification not implemented" or "Unknown account type".
Vector (computed). Input: a transaction whose sender is 0A000000 ‖ <32 bytes> (a ZBS_
address) with any 64-byte signature → expected output: refused ("Unknown account type"). Input:
sender 03000000 ‖ <32 bytes> with a 96-byte signature → refused
("Estonia eID signature verification not implemented"). Input: sender
5e8eb28d…2152 (32 bytes, bare) → refused before verification, accounts are typed: a bare 32-byte key is not an account on this chain.
Test cases · §8
3 cases · 3 invalid
A dataset (ZBS_) account cannot sign
Loading the test widget…
An Estonia eID account is refused as not implemented
Loading the test widget…
A bare 32-byte sender is refused before any signature
Loading the test widget…
Defects to match. None.
9. Native foreign transactions carried in the message field
Purpose. Let a MetaMask, Phantom or Bitcoin wallet authorise a ZooBC transfer by signing its own chain's transaction; the node verifies the native signature and binds the native transfer to the ZooBC one.
Inputs. The ZooBC transaction (sender type, recipient, body, message); the chain identity is not involved.
Output and effect. Before the digest path of §1, the verifier tries a native path when the
sender type and the message allow it. If the message is present but does not parse as the native
transaction, the verifier falls through to §1 (the message is then ordinary data). If it parses,
the native rules decide and the §1 digest is not checked at all (the ZooBC signature field
is ignored on this path; it must still be non-empty).
Ethereum (sender type 4, non-empty message). Parse the message as a signed Ethereum
transaction: a leading byte 0x02 (EIP-1559: 12 RLP items, [chainId, nonce, maxPriorityFee, maxFee, gasLimit, to, value, data, accessList, yParity, r, s]) or 0x01 (EIP-2930: 11 items,
[chainId, nonce, gasPrice, gasLimit, to, value, data, accessList, yParity, r, s]), else a
legacy/EIP-155 list of 9 items [nonce, gasPrice, gasLimit, to, value, data, v, r, s]. The access
list must be empty. RLP nesting deeper than 32 is rejected. v ≥ 35 means EIP-155 with
chain_id = (v − 35) / 2 and recovery id (v − 35) mod 2; v = 27 or 28 means legacy; any other
v is rejected; typed transactions carry yParity 0/1. Recover the sender from the signing hash:
EIP-1559 Keccak-256(0x02 ‖ RLP([chainId, nonce, maxPriorityFee, maxFee, gasLimit, to, value, data, []])),
EIP-2930 Keccak-256(0x01 ‖ RLP([chainId, nonce, gasPrice, gasLimit, to, value, data, []])),
EIP-155 Keccak-256(RLP([nonce, gasPrice, gasLimit, to, value, data, chainId, 0, 0])), legacy
Keccak-256(RLP([nonce, gasPrice, gasLimit, to, value, data])), with value in its minimal
big-endian RLP form; high-s is rejected. Then require: Keccak-256(recovered key)[12..32] equals
the sender payload; to equals the recipient's 20-byte payload; the SendZBC amount equals
value_wei / 10^10 computed at full precision (long division over the big-endian value), rejecting
a quotient above INT64_MAX.
Solana (sender type 11, non-empty message). Parse a legacy Solana transaction: shortvec
signature count 1..8, 64-byte signatures, a 3-byte header, shortvec account count 1..64, 32-byte
keys, a 32-byte recent blockhash, shortvec instruction count, each instruction program index(1) ‖ shortvec account indexes ‖ shortvec data. A System-program transfer is recognised by: program
key all zeros, data at least 12 bytes with uint32 LE instruction index 2, at least two account
indexes [from, to], lamports uint64 LE at data offset 4; at least one must be present, and
when several are, the last one in the transaction is the one taken. Verify signature[0] as Ed25519
over the message bytes (everything after the signatures) under keys[0]; require keys[0] == from == sender payload; the recipient must be a type-11 account whose payload is to; the
amount (SendZBC body, or the int64 LE at offset 8 of a TransferToken body) must equal the
lamports; any other ZooBC type is rejected.
Bitcoin (sender type 7 or 5, non-empty message). Parse a Bitcoin transaction (legacy or
SegWit serialisation, trailing bytes rejected). The native path applies only when it parses
and has exactly one input and one or two outputs; otherwise the verifier falls through to §1
(unlike the Ethereum and Solana paths, where any parseable native transaction commits the
verifier to the native rules). The spent amount is pinned to the sum of the outputs (zero miner fee; BIP-143 commits to it, so a
transaction that paid a fee does not verify). Type 7: witness [DER signature ‖ hashtype, compressed key(33)], hashtype must be 0x01 (SIGHASH_ALL), DER s must be low, verified under
BIP-143 with scriptCode = 76a914 ‖ HASH160(key) ‖ 88ac. Type 5: scriptSig of two pushes
<DER ‖ 0x01> <key 33 or 65>, verified under the legacy sighash with the same scriptCode.
Then require: HASH160(signer key) equals the sender payload; output 0 is P2WPKH (0014‖h) or
P2PKH (76a914‖h‖88ac) and h equals the recipient payload; an output 1, if present, pays the
signer's own hash; the amount (SendZBC body, or TransferToken amount at body offset 8) equals
output 0's value in satoshis.
Binding to this chain and once-only use (rule foreign_carrier_bound). The stateless
validation of a carrier (03 §12, at admission and in block validation) also requires, in this
order:
- The envelope:
expiry0 ("A foreign-signed carrier cannot carry an expiry"); no escrow part ("A foreign-signed carrier cannot carry an escrow"); the type SendZBC, or TransferToken for a Solana carrier only ("A foreign-signed carrier has the wrong transaction type");survival0 (checked before these, above). - The chain binding of a Solana or Bitcoin carrier (step 4 and 3 below), judged for the block the transaction lands in.
- Ethereum. The message is one minimally encoded RLP value that re-encodes to itself byte for
byte: no trailing bytes, no leading zero byte in
chainId,nonce, the gas fields,value,r,soryParity,yParity0 or 1 on a typed transaction, no scalar carried as a list, an empty access list ("Ethereum carrier is not canonical: …"). ItschainIdis non-zero and equals this chain's EVM chain id ("Ethereum carrier chain id does not match this chain"), so a legacy transaction without EIP-155 is refused. The envelopefeeequals the fee the signed gas fields name:gas_price × gas_limit / 10^10atomic units,gas_pricebeingmaxFeePerGason an EIP-1559 transaction, computed in unsigned 64-bit arithmetic and read as 100,000,000 (1 ZBC) when the product overflows 64 bits ("Ethereum carrier fee must equal the signed gas fields"); the fee floor of04still applies, so the gas fields must name at least the floor. The recipient is a type-4 account ("Ethereum carrier recipient must be an Ethereum-typed account"). The EVM chain id of a chain with genesis hashGis(0x0883 << 16) | (G[0] << 8) | G[1]: for the vectors'G=E003E4E3…,0x0883E003= 142,860,291. (The reference maps one fixed historical 32-byte value to 883; no chain built from 0.6.1 has that hash.) - Bitcoin. The message equals the canonical re-serialization of what it parses to: minimal
CompactSize lengths, the SegWit marker only when some input carries a witness ("Bitcoin carrier
is not canonically serialized"); a type-7 spend carries no scriptSig on its input ("Bitcoin
carrier P2WPKH input carries a scriptSig"); a type-5 spend is not SegWit-serialized ("Bitcoin
carrier P2PKH spend carries a witness"); the recipient's type follows output 0's script,
0014 ‖ h→ type 7 and76a914 ‖ h ‖ 88ac→ type 5 ("Bitcoin carrier recipient type does not match the paid output's script"). The single input (step 2) spends the outpoint whose 32 txid bytes are this chain's genesis block hash, in the byte order ZooBC stores it, at index0xFFFFFFFF("Bitcoin carrier needs exactly one genesis outpoint", "Bitcoin carrier input must spend the ZooBC genesis hash at index 0xFFFFFFFF"). - Solana. Exactly one signature in a one-byte count, and a header that requires exactly one:
message[0] = 01andmessage[65] = 01("Solana carrier must carry exactly one signature"). The signedrecent_blockhash(step 2) is the hash of a main chain block in the including block's own ancestry at most 720 blocks below it (SNAPSHOT_BLOCK_REFERENCE_REACH, the blocks every node holds): at admission judged for tip + 1, re-judged for the target height at block assembly, and for the block height in validation ("Solana carrier recent_blockhash is not a main chain ancestor within 720 blocks"); the carrier therefore expires with that window. A TransferToken carrier moves the genesis tokenZSOLonly ("Solana carrier moves ZSOL or ZBC only") and never pays its fee in the token ("Solana carrier cannot pay its fee in the token"). - Once only, by native id. The carrier id is
Keccak-256of the canonical Ethereum bytes, the Solana transaction's first signature (the 64 bytes at message offset 1), or the Bitcoin txid. A carrier whose id, or theSHA3-256of whose raw message, is recorded as spent is refused: at the staging entry, before the stateless validation, with "ForeignCarrierReplayed" (an invalid transaction); in the stateless validation itself (admission out of staging, any other caller) with "Foreign carrier transaction already used". (Every carrier executed on a chain started at 0.6.1 records its native id; the raw-message key is still consulted.) A carrier whose id a pooled or a staged transaction already holds is refused as a duplicate, "ForeignCarrierReplayed" (04§6); block assembly takes only the oldest pooled copy of an id and never a spent one (04§10); a block carrying a spent id, or two transactions with one id, is invalid ("ForeignCarrierReplayed",19). A carrier that executes records its id as spent in the same block. - The Ethereum nonce. At admission (the staging entry, the pool, and the HTTP route's
pre-admission check) the carrier's
noncemust equal the next free nonce: the first nonce at or above the sender account's nonce (07) that no pooled or staged Ethereum carrier of the same sender carries, the judged carrier itself (a pooled or staged copy with the same message bytes) not counted. A second send within the pool's latency therefore queues behind the first; a carrier whose nonce is already queued, or one that leaves a gap, is refused ("carrier nonce N, account nonce M", with M the next free nonce,04§6); a carrier queued behind one that expired or was dropped waits until a carrier with the missing nonce arrives, or expires itself. At block assembly and in the executor the nonce must equal the account's nonce exactly, so of queued nonces M and M+1 only M enters a block and M+1 waits for the next one. A block carrying a carrier whose nonce is not the sender account's nonce is invalid: the executor judges the carrier's nonce before anything else of the transaction is applied and refuses it with "ForeignCarrierNonce: carrier nonce N, account nonce M (a block carrying it is invalid)", so nothing of it is charged, the nonce does not move and the id is not recorded as spent; the block is refused like one carrying a replayed carrier id (19). One transaction per account per block means nothing earlier in the block moves that nonce, and the pool and block assembly refuse a wrong nonce first, so an honest blocksmith never builds such a block. A carrier that executes increments its sender's nonce, as every other mined transaction of any type but Empty does.GET /api/v1/accounts/<eth>/eth-tx-countanswerscount(the account nonce) andpending(the next free nonce over this node's pool and staging, the judged carrier being none); the node's Ethereum RPC answerseth_getTransactionCount(address, "pending")withpendingand every other tag withcount(31).
How to compute it (wallet side). Produce the native transaction with the wallet; set the
ZooBC sender to the wallet's own mirrored account, the recipient to the mirrored destination, the
amount to the converted value, put the raw native transaction in message, and any non-empty
bytes in signature.
Rule activation. foreign_carrier_bound, active from height 0 on every chain: the binding,
the once-only id and the nonce rule above. Without a rule: the native verification itself, the
4,096-byte message limit and the refusal of a non-zero survival on a carrier (03, 04).
Rejections and errors. The native checks reject with "Recovered ETH sender does not match sender account address", "ETH transaction recipient does not match", "ETH transaction amount does not match", "Solana signer does not match sender account", "Bitcoin signature invalid: …", "Bitcoin 2nd output must be change to sender", and their siblings; all are signature failures. The binding checks reject with the quoted texts of steps 1–7; they are stateless refusals at admission and invalidate a block, except the pooled or staged id (step 6), a duplicate refusal at admission only; the spent id, which is "ForeignCarrierReplayed" in a block; and the nonce (step 7), refused at admission with "carrier nonce N, account nonce M" (M the next free nonce) and invalidating a block with "ForeignCarrierNonce: carrier nonce N, account nonce M (a block carrying it is invalid)" (M the account nonce).
Vector. None computed in this chapter (a native foreign transaction must be produced by a
foreign wallet); the reference's own tests carry two raw EIP-1559 transactions (02f876…) that
33 can use. Invalid inputs: a type-4 sender whose message parses as an EIP-1559 transaction
paying a to other than the recipient's 20-byte payload → refused ("ETH transaction recipient
does not match"); the same with to right but chainId 1 on a chain whose genesis hash starts
E003 → refused ("Ethereum carrier chain id does not match this chain"); a type-11 sender whose
Solana transfer names a recent_blockhash that is no main chain block of the last 720 → refused
("Solana carrier recent_blockhash is not a main chain ancestor within 720 blocks"); a type-4 sender
whose account nonce is 4, with nothing of its own pooled or staged, submitting a carrier signed with
nonce 5 → refused at admission ("carrier nonce 5, account nonce 4"), and a block carrying that
carrier while the account nonce is 4 → invalid ("ForeignCarrierNonce: carrier nonce 5, account
nonce 4 (a block carrying it is invalid)"), nothing charged.
Test cases · §9
14 cases · 6 valid · 8 invalid
A SendZBC carrying the signed EIP-1559 transaction it mirrors
Loading the test widget…
The same carrier with another ZooBC recipient is refused
Loading the test widget…
A carrier signed for this chain's EVM chain id passes the signature check
Loading the test widget…
The same carrier passes the binding: chain id 0x0883E003, fee equal to the signed gas fields
Loading the test widget…
The same transfer signed with chain id 1 is refused on a chain whose genesis hash starts E003
Loading the test widget…
Its native signature itself verifies
Loading the test widget…
The bound carrier with an envelope fee other than its signed gas fee is refused
Loading the test widget…
The reference's raw test transaction in a version-3 envelope with an expiry is refused
Loading the test widget…
A Solana carrier naming the main chain block 100, in block 101
Loading the test widget…
The same carrier in block 820, the cited block 720 blocks below
Loading the test widget…
In block 821 the cited block is no main chain block of the last 720
Loading the test widget…
A carrier naming a hash that is no main chain block is refused
Loading the test widget…
A carrier signed with nonce 5 from an account whose nonce is 4, nothing pooled
Loading the test widget…
A block carrying that carrier while the account nonce is 4 is invalid
Loading the test widget…
Defects to match. (a) On a native path the ZooBC signature field is unchecked beyond being
non-empty, so two signed transactions with the same native payload and different signature
bytes have different ZooBC hashes; they share one carrier id, so only one can ever execute, and
the Ethereum path indexes the Keccak of the canonical bytes to answer wallets by the Ethereum
hash (31). (b) The legacy parser keeps a 64-bit value field that wraps; consensus uses
value_be, never that field. (c) The native signature covers the sender, the recipient and the
amount, and on Ethereum the fee and the nonce; the ZooBC timestamp, and on a Solana or Bitcoin
carrier the fee above the floor, are chosen by whoever wraps the payload. Neither moves value: the
overpay is refunded in the same block (04 §5) and the timestamp only places the carrier inside
its admission window; every other envelope field is fixed by the rule.
10. Multi-signature accounts
Purpose. Let an account that no single key controls spend by a threshold of participant signatures over an inner transaction.
Inputs. A MultiSignature transaction (type 5) whose body carries any of: the multisig info,
the inner unsigned transaction bytes, and participant signatures; the pending state (12).
Output and effect. The multisig account is the typed address 00000000 ‖ hash, where hash
is 01 §7's hash of (minimum_signatures, nonce, sorted participant addresses); the inner
transaction's sender is this typed account (a bare 32-byte sender is refused like any other, §1).
Body layout:
| offset | length | field |
|---|---|---|
| 0 | 4 | info present: uint32 LE 1 = present, 0 = absent |
| 4 | 4 | minimum_signatures uint32 LE (only if present) |
| 8 | 8 | nonce int64 LE |
| 16 | 4 | participant count N |
| 20 | … | N addresses, each LE32(type) ‖ payload with the payload length of 01 §4.1 |
| … | 4 | inner transaction length L uint32 LE |
| … | L |
inner transaction, unsigned bytes (03 layout without a signature) |
| … | 4 | signature info present: 1 or 0 |
| … | 32 | inner transaction hash H = SHA3-256(inner unsigned bytes) (only if present) |
| … | 4 | signature count M |
| … | … | M entries: address (as above) ‖ uint32 LE signature length ‖ signature |
A participant signs the chain-bound digest of the inner bytes, SHA3-256("ZBC-TX" ‖ G ‖ inner), with its own account type's scheme (§2–§7); H (the bare hash) is only the key under
which signatures are collected. The wrapper itself is signed by its submitter over its own digest
like any transaction. A pending inner transaction is complete when at least minimum_signatures
of its stored signatures, one per distinct participant address, verify; a signature from a
non-participant or one that does not verify is ignored, never an error. A participant signature
by an Ethereum- or Tron-typed participant is the 27/28 form (§5): a body carrying another form is
refused (stateless, so a block carrying it is invalid), and a stored one in another form does not
count toward the threshold. A nested-multisig
participant (a participant entry that is itself a multisignature) is never counted. At completion the inner
transaction's sender must equal the multisig account whose info was found, and the inner
transaction is applied as 12 specifies.
How to compute it. Build the info, the inner unsigned bytes and the signatures with the layout above; each participant computes the digest of §1 over the inner bytes and signs with its type's scheme; submit any subset of (info, inner bytes, signatures) in one or several wrappers.
Rule activation. All at 0 on every chain: multisig_no_replay (a body naming an
already-settled inner hash is refused at admission and is a paid no-op in a block),
group_spend_invalid_block (an inner transaction a group member may not send fails the block),
state_answer_noop (a repeated participant signature in the same block is ignored instead of
failing the block), eth_signature_canonical_v (the 27/28 form of an Ethereum- or Tron-typed
participant's signature). Without a rule: the inner transaction must carry at least its own type's fee
floor, checked at admission and before execution; and a block may run at most one inner
transaction per multisig account (12 §10).
Rejections and errors. At admission: a body that does not parse; minimum_signatures of 0 or
greater than the participant count; an inner transaction that does not parse; an inner type other
than Empty, SendZBC, the four node-registration types, SetSplitPolicy and the four group types;
an inner transaction failing its own stateless rules or its fee floor (from the rule above); a
settled inner hash (from multisig_no_replay); a non-empty participant signature of an Ethereum-
or Tron-typed participant that is not 65 bytes ending in 27 or 28 ("MultiSignature: participant
signature: Ethereum signature recovery id must be 27 or 28", also in block validation). In a block: an info whose stored address disagrees
with its participants makes the block invalid; an unparseable inner transaction at completion
makes the block invalid; an inner sender other than the multisig account makes the block invalid.
Vector (computed). Participants A = 00000000 ‖ 01×32 and B = 00000000 ‖ 02×32, nonce 7,
threshold 2: preimage 02000000 0700000000000000 02000000 ‖ A ‖ B (sorted ascending, A first),
address 298f43489d6a12915582969116cc480a4b492616dff5396897be91284c0dc733. Invalid input: a
body whose signature entries carry participant 04000000 ‖ 36590dc6…30fc with the 65-byte
signature of §5 ending in 00 → refused "MultiSignature: participant signature: Ethereum signature
recovery id must be 27 or 28".
Test cases · §10
2 cases · 1 valid · 1 invalid
A two-of-two multi-signature account
Loading the test widget…
A MultiSignature body whose participant signature ends in 00 is refused
Loading the test widget…
Defects to match. (a) The participant match at completion is a byte-exact comparison of the
stored participant address with the signing address; both come from the typed body layout above,
so no canonicalisation is applied or needed. (b) Nested multisig participants are unsupported
(fail-closed). (c) The multisig info is
stored under the raw 32-byte hash while the inner sender is the 36-byte typed account; the
reference strips the 00000000 prefix of a 36-byte type-0 inner sender before the lookup. An implementation
may key the info by the typed account instead, as long as it finds the same info.
11. Everything else a key signs on this chain
Purpose. Enumerate every other signature consensus or the node verifies, so that an implementer implements each with its own preimage and so that no raw-signed object can be mistaken for a transaction digest.
Inputs. As listed.
Output and effect. All rows use Ed25519 as in §3.1 unless the "scheme" column says
"by account type" (then §2 dispatch applies to the digest named) or "ECVRF" (01 §8).
| object | signer | preimage (verified) | scheme | document |
|---|---|---|---|---|
| block | blocksmith node key | the signed header bytes: the 204-byte layout, followed by the 80-byte seed proof under rule seed_vrf (284 bytes on every chain); one shared layout for the blocksmith, the validator, the candidate pool, the branch replay and the equivocation check |
Ed25519 | 05 |
| block seed | blocksmith node key | a VRF proof over alpha = SHA3-256(previous block seed); the 64-byte seed is the VRF output and the 80-byte proof travels in the header (rule seed_vrf, at 0 on every chain) |
ECVRF | 01 §8, 05, 20 |
| published receipt | recipient node key | the unsigned receipt bytes (sender key, recipient key, datum type, datum hash, reference block height and hash, RMR) | Ed25519 | 23 |
| spine block and spine signatures | spine blocksmith and spine signer node keys | the unsigned spine block bytes (204, no seed proof); under rule spine_reference_commit the payload hash inside them also covers the block's reference commitment LE32(reference height) ‖ referenced main chain block hash(32) ‖ its cumulative difficulty as decimal ASCII, which the spine block carries (payload format 3), so a node that is behind can check the signatures before its main chain reaches that height. A spine block candidate's identity is SHA3-256(unsigned spine block bytes); the stored block has the same identity. A registered node gives its spine signature only on content it can check against its own chain (rule spine_content_validated): it refuses a commitment naming another block at that height and abstains when it does not hold that height yet; it refuses a candidate older than its collection window (60 s) or stamped more than the network tolerance (150 s) ahead of its clock; it refuses a block whose reference does not advance. Its signature is a signing commitment: under rule cosign_promise_binds it signs no other candidate at that spine height until a spine block is stored there, unless signed non-signing statements on the candidate it committed to (row below) show that candidate can no longer gather the required spine signatures; a registered node always re-signs exactly the candidate it committed to, the collection window not applying to it. Signing a candidate and giving a non-signing statement on the same candidate is provable equivocation (row "spine equivocation evidence"); signing two different candidates at one height is not reportable, because a registered node freed by non-signing statements may sign a new one |
Ed25519 | 25 |
| spine non-signing statement | a spine signer's node key | SHA3-256("ZBC-SPINE-REFUSE" ‖ G(32) ‖ LE32(spine height) ‖ identity of the candidate not signed(32)), "ZBC-SPINE-REFUSE" the 16 ASCII bytes without terminator; "I did not sign candidate P at height H". Counted only when it verifies, by distinct keys of the spine signers, for the height and identity in question. A registered node never gives one for a candidate it signed at that height and never signs a candidate it gave one for (rule cosign_promise_binds) |
Ed25519 | 25, 27 |
| receipt request | the sending node's key | SHA3-256("ZBC-RCPT" ‖ G(32) ‖ datum type(1) ‖ datum hash ‖ recipient node key(32)), "ZBC-RCPT" the 8 ASCII bytes without terminator; datum type 1 = a block (datum hash = the block hash the request claims), 2 = a transaction (SHA3-256 of the served transaction bytes), 3 = a batch (SHA3-256 of the served transactions' bytes concatenated in order). Carried in the SenderSignature field of SendBlock, SendTransaction and SendBlockTransactions; a recipient signs no receipt for a request whose signature does not verify for the claimed sender key, itself and this chain; a request with no signature is receipted only while the node setting require_signed_receipt_requests is off (30). An implementation must always send the signature |
Ed25519 | 23, 27 |
| proof of ownership (node registration) | node key; on an UpdateNodeRegistration that rotates the key (rule node_key_rotation), the new node key. The new key takes effect 120 blocks after the block that carries the change; until then the old key signs everything the node signs |
account address(36) ‖ block hash(32) ‖ height(4) = 72 bytes |
Ed25519 | 09 |
| fee-vote reveal | the sender account | the 44 FeeVoteInfo bytes recent block hash(32) ‖ height(4) ‖ fee vote(8) |
by account type (an Ethereum- or Tron-typed voter in the 27/28 form, §5) | 17 |
| gateway heartbeat | gateway key | the 68-byte prefix gateway key(32) ‖ reference height(4) ‖ reference hash(32) |
Ed25519 | 17 |
| node address info (P2P) | node key | the unsigned address-info bytes | Ed25519 | 27 |
| every P2P call (gRPC metadata) | the calling node's key, for the node called | "ZBC-P2P-RPC-V3" ‖ 00 ‖ method name ‖ 00 ‖ len(receiver key)(1) ‖ receiver key(32, or empty) ‖ LE64(timestamp) ‖ SHA3-256(serialized request)(32) ‖ call nonce(8 random bytes); carried as the metadata entries zbc-sender-key-bin, zbc-request-timestamp (decimal), zbc-request-digest-bin, zbc-request-nonce-bin, zbc-receiver-key-bin and zbc-request-signature-bin; the method name is the gRPC method the caller invokes; the receiver is the key of the node called, absent only on a Handshake made by address; the receiver refuses (gRPC UNAUTHENTICATED) a call with no entries ("P2P calls must be signed by a node key"), a malformed one, a stamp outside ±600 s of its clock ("signed request timestamp outside the 600 s window; check NTP", no strike), a receiver that is not its own key ("signed request was made to another node"), a signature that does not verify, a digest that is not the body's, or a signature it has seen inside the window (replay); the caller is charged under the key that signed (27, 28) |
Ed25519 | 27 |
| handshake request / response (P2P) | node key | request: node key(32) ‖ version text ‖ height(4) ‖ genesis hash(32) ‖ listen address text ‖ timestamp(8); response: peer key(32) ‖ height(4) ‖ genesis hash(32) ‖ timestamp(8); the timestamp must be within ±600 s of the receiver's clock ("handshake timestamp out of window: your clock is ±N s from ours (limit 600 s); check NTP"); a handshake verifies the key, never the address: an advertised address is dialled on the node's own initiative and trusted only once that dial reaches the key |
Ed25519 | 27 |
| API signed scope | account key; for the operator scope (the node's own diagnostics, and a rebuild of an old snapshot by the archive's read path) this node's key | ASCII METHOD:PATH:TIMESTAMP:BODY |
Ed25519 | 31 |
| gateway/archival/relay registry attestation (API) | owner key | the ASCII string KIND ":" lower-case hex of the registered key ":" decimal Unix timestamp, KIND one of GATEWAY, GATEWAY_REMOVE, ARCHIVAL, RELAY |
Ed25519 | 31 |
| cancel a pending transaction (API) | sender account | SHA3-256("ZBC-CANCEL" ‖ G ‖ transaction hash) |
by account type | 31 |
| group link consent | the joining address | SHA3-256("ZBC-GROUP-LINK" ‖ G ‖ len(u8) ‖ controller ‖ len(u8) ‖ member ‖ valid_until(4) ‖ link_seq(4)), addresses canonical |
kind 0: by account type; kind 1: multisig participants over the same digest; kind 2: for an Ethereum-typed address EIP-191 personal_sign, i.e. the Ethereum scheme over "\x19Ethereum Signed Message:\n32" ‖ digest, and for a Tron-typed address (rule canonical_account_forms) TronLink's message signature, the same scheme over "\x19TRON Signed Message:\n32" ‖ digest; every signature by an Ethereum- or Tron-typed key in the 27/28 form (§5) |
18 |
| group control consent | the new controller | same shape under "ZBC-GROUP-CONTROL", current controller first |
as above | 18 |
| multi-party escrow co-signature | the recipient | the §1 digest of the transaction with the co-signer signature field emptied | by account type (an Ethereum- or Tron-typed recipient in the 27/28 form, §5) | 12 |
| app move voucher | the player | SHA3-256(app id(8) ‖ seq(4) ‖ previous state hash ‖ move bytes) |
by account type, always a 64-byte signature, so only ZooBC, Solana, Polkadot and Taproot players can sign one (rule canonical_account_forms, 16) |
16 |
| multisig participant | each participant | §10 | by account type (an Ethereum- or Tron-typed participant in the 27/28 form, §5) | 12 |
| equivocation evidence | the accused blocksmith's node key | each of the two signed header byte strings carried in an EquivocationReport (type 60): 204 bytes, or 284 with the seed proof; the report transaction itself is signed over the §1 digest by the typed account (00000000 ‖ node key) of the node that files it |
Ed25519 | 35 |
| spine equivocation evidence | the accused registered node's node key | one registered node's spine signature on a spine block candidate and its non-signing statement on the same candidate, carried in a SpineEquivocationReport (type 62, rule spine_equivocation_report) whose body is spine height (uint32 LE) ‖ the accused node key (32) ‖ L (uint32 LE, 1..4,096) ‖ the candidate's unsigned header bytes (L bytes: 204, or 284 with a seed proof) ‖ spine signature (64) ‖ statement signature (64), nothing more; the spine signature is verified over the header bytes under the named key, the statement over the ZBC-SPINE-REFUSE digest of the row above with identity SHA3-256(header bytes) and the body's spine height; the report is sent fee-free by a registered node's typed account over the §1 digest; the accused is charged one miss once per (node, spine height) (35 §7) |
Ed25519 | 35 |
| liveness attestation | an active node's typed account (00000000 ‖ node key) |
a QueueAttendance transaction (body: referenced block height and hash) over the §1 digest, fee exactly 0 (rule liveness_attestation) |
by account type (type 0) | 09, 36 |
| roll call | a genesis registered node's typed node account | a RollCall transaction (type 61, empty body) over the §1 digest, fee exactly 0, valid only in blocks 1 .. roll_call_blocks |
by account type (type 0) | 09 |
| storage-proof batch | a registered node's typed account | a SubmitStorageProofBatch transaction (type 297) over the §1 digest, fee exactly 0; the proofs inside are hashes, not signatures |
by account type (type 0) | 11 |
| archive chunk request (P2P, node-local) | the requesting node's key | "ZBC-PIECE-REQ" ‖ genesis hash(32) ‖ piece id(32) ‖ LE64(timestamp) ‖ requester key(32), carried in the GetStoragePiece request's requester_public_key, timestamp and signature fields; the holder accepts it within ±300 s of its own clock and only from a registered node key, and requires it only for chunks of archived snapshots older than the newest three |
Ed25519 | 11, 27 |
How to compute it. Per row, by the owning document.
Rule activation. Per owning document.
Rejections and errors. Per owning document.
Vector (computed). Tag bytes: "ZBC-TX" = 5a42432d5458; "ZBC-CANCEL" =
5a42432d43414e43454c; "ZBC-GROUP-LINK" = 5a42432d47524f55502d4c494e4b; "ZBC-RCPT" =
5a42432d52435054; "ZBC-SPINE-REFUSE" = 5a42432d5350494e452d524546555345; "ZBC-P2P-RPC-V3"
= 5a42432d5032502d5250432d5633; the EIP-191 prefix for a 32-byte digest =
19457468657265756d205369676e6564204d6573736167653a0a3332; the Tron prefix for a 32-byte digest
("\x19TRON Signed Message:\n32", 24 bytes) = 1954524f4e205369676e6564204d6573736167653a0a3332.
Receipt request (computed, signer the §1 sender key standing in for a node key): input genesis
E003E4E3…2871, datum type 01, datum hash B3B7639928C0CF729714459FA7F23DD7E5111DB937AD7C732F2648D12E28AD53
(an example block hash), recipient node key 02A50719C01D3B81030D5BB866B25E69F15668DE15160BA51B43CD0C1B352CA2
→ expected digest 12b0e6a67dc60fe7f47f5c93b0651641a9bdeca15e5ef1cb10d2465f53e5a706, signature
c40da5175bdf1a5e393c04b3d3e925fe9d750899d215fe325619c3fa1896cc3cba17451e698c63f2e920ad0c85b4f8adb5390d3d8f943d6127bad1cc417c1309.
The same signature presented to any other recipient key → does not verify (no receipt).
Spine non-signing statement (computed, same key): input genesis E003E4E3…2871, spine height 10,
candidate identity 11 × 32 → expected digest
cc5a80026d9cdd6c1461ce4f1b9c6dccdaa6fddb30c5cff017287d63d5e831be, signature
2db8faff8be6956e112ab504d5e42c5466f1a3ea6b103fd3fbf7a311756f18abd86eed26d5119a51a3962a85488397ee0b92a8545f9b72ca14b1c40ffc517d01.
Registry attestation (computed, same key): input KIND GATEWAY, key 02A50719…2CA2, timestamp
1,793,509,627 → message GATEWAY:02a50719c01d3b81030d5bb866b25e69f15668de15160ba51b43cd0c1b352ca2:1793509627,
signature b9ba2d479c92a87f0bef922f1940252bfb1f30cfaebcd40af2eae6f562619757060cab1669ec61892fcf7bf71af6ca1c09d249212c0e64e9897ab497cca6360e.
Test cases · §11
13 cases · 13 valid
Sign a receipt request for a block
Loading the test widget…
Sign a non-signing statement (the SpineRefusal digest)
Loading the test widget…
Sign a gateway registry attestation
Loading the test widget…
The tag ZBC-TX
Loading the test widget…
The tag ZBC-CANCEL
Loading the test widget…
The tag ZBC-GROUP-LINK
Loading the test widget…
The tag ZBC-RCPT
Loading the test widget…
The tag ZBC-SPINE-REFUSE
Loading the test widget…
The tag ZBC-P2P-RPC-V3
Loading the test widget…
The tag EIP-191-32
Loading the test widget…
The tag TRON-32
Loading the test widget…
The receipt request verifies for its recipient
Loading the test widget…
The same signature presented to another recipient does not verify
Loading the test widget…
Defects to match. The handshake and heartbeat preimages embed uint32 and int64 fields by
copying the host's memory bytes, which on the x86-64 and ARM64 hosts the reference runs on is
little-endian; an implementation must write them little-endian explicitly.
12. Off-chain message signing (tools and wallets, not consensus)
Purpose. Prove control of a native address off-chain with a signature that can never be a transaction, a proof of ownership or a participant signature.
Inputs. A message (bytes), the chain's genesis hash, an Ed25519 key.
Output and effect. ZBC-MSG-v2: digest = SHA3-256("ZBC-MSG-v2" ‖ G ‖ message);
signature = Ed25519.sign(seed, digest) (64 bytes). ZBC-MSG-v1: digest = SHA3-256("ZBC-MSG" ‖ message), accepted by the reference tools' verifier only until Unix time 1,796,083,200
(2026-12-01 00:00 UTC). The node has no endpoint for these; they are a convention of the CLI
and integrators. The reference's web wallet source contains no ZBC-MSG code, so I think the web
wallet does not sign messages (the served wallet was not checked).
How to compute it. As above.
Rule activation. None (not consensus).
Rejections and errors. Tool-level.
Vector (computed; the reference's zbc-cli sign-message prints the same digest and signature).
Input: the seed 51bae95d…5d96 (§14), genesis E003E4E3557EF19F0519BD345009DEA7FB43B3445EAA043920C5DC23B3302871,
message hello zoobc (68656c6c6f207a6f6f6263) → expected digest
81815516b0023b4e7ca02fa983c14cba810108185caf0236eb8212beec3d4603, signature
826c0af15d1c5f3e3e55c850e3cd1232a6a23c74126e77a6d0078f08e652891c6a42be711e0efdf750ad112e3c39702595f30e8b352340d3ef9b42bbad19a500.
The same signature checked against the message hello zoobc! → invalid.
Test cases · §12
3 cases · 3 valid
Sign an off-chain message
Loading the test widget…
The message signature verifies
Loading the test widget…
The same signature against hello zoobc! does not
Loading the test widget…
Defects to match. None.
13. Encrypted messages (not consensus)
Purpose. Carry a message only the recipient can read.
Inputs. Plaintext; the recipient's Ed25519 public key (a type-0 account).
Output and effect. The message field is "ZBE1" (5A 42 45 31) followed by a libsodium
sealed box to the recipient's key converted from Ed25519 to Curve25519 (the standard
Ed25519-to-X25519 public-key conversion):
ephemeral X25519 public key(32) ‖ XSalsa20-Poly1305 ciphertext (plaintext + 16-byte tag) with the
nonce BLAKE2b-24(ephemeral public key ‖ recipient Curve25519 public key); overhead 48 bytes plus
the 4-byte marker. Consensus treats the field as opaque bytes; the only consensus effect of the
marker is the size limit: an encrypted message may be up to 256 + 64 = 320 bytes where a plain
message is limited to 256 (03, 04), so the plaintext may be at most 268 bytes.
How to compute it. A libsodium-compatible sealed box as above, prefixed with the marker.
Rule activation. None.
Rejections and errors. Admission: "Encrypted message too large" above 320 bytes.
Vector. None (the ephemeral key makes the output random).
Test cases · §13
1 case · 1 valid · 1 reference
Encrypted messages have no vector (the ephemeral key makes the output random)
A stated value: there is nothing to compute. A compatible node shows the same value.
- value
none- marker
5a424531- max_bytes
320
Defects to match. None.
14. Key derivation (not consensus)
Purpose. How wallets and tools make keys; nothing here is checked by the chain.
Inputs. A BIP-39 mnemonic and optional passphrase, or a raw 32-byte seed.
Output and effect. BIP-39: seed64 = PBKDF2-HMAC-SHA512(mnemonic, "mnemonic" ‖ passphrase, 2048, 64); the reference validates a mnemonic only by word count (12, 15, 18, 21 or 24) and
generates mnemonics with the standard checksum from the English wordlist. SLIP-10 for Ed25519:
master I = HMAC-SHA512("ed25519 seed", seed64), key I[0..32], chain code I[32..64]; child
I = HMAC-SHA512(chain, 00 ‖ key ‖ BE32(index)) with every index hardened; ZooBC accounts use
m/44'/883'/n' (coin type 883). The 32-byte result is the Ed25519 seed; the account is
00000000 ‖ public key and the node, relay and gateway forms are the same key under ZNK, ZBR,
ZBG (01 §5). Foreign-chain keys in the reference tools: secp256k1 (Ethereum, Bitcoin) and the
others are derived by the bridge key generator, outside this specification. Deriving a key as
the hash of a passphrase string is not part of any ZooBC format.
How to compute it. As above.
Rule activation. None.
Rejections and errors. None.
Vector (computed, cross-checked against the reference's vector file). Mnemonic abandon
× 11 + about, empty passphrase, m/44'/883'/0' → seed
51bae95d58f32304a5c9d894819989a4fb04da6115d9a43612a026e7a5dd5d96, public key
5e8eb28dccaa94a992f7169fa67966207d96aa55df7d24d2d6ec1f538c9f2152; m/44'/883'/1' → seed
2c0f8a5722d5701a7a4e7d61219c5235a9b74ba46fdbaff9f7978ec7bc14f85d, public key
fd4472bbdec43b919aa37b9b3366a3318f2902a753a15f5fd6d43c44b5121b67.
Test cases · §14
2 cases · 2 valid
Derive account 0 from the test mnemonic
Loading the test widget…
Derive account 1 from the test mnemonic
Loading the test widget…
Defects to match. None.
A question about this chapter, or a statement that does not match the network? Discuss on zoobc.pro.