On this page
  1. §0 The area in one paragraph
  2. 1. The transaction signing digest and the transaction hash
  3. 2. Verification dispatch by account type
  4. 3. Ed25519 (native, Solana, Cardano, Tezos)
  5. 3.1 Native accounts (type 0, type 11, unknown types) and raw node-key signatures
  6. 3.2 Key-carrying envelope (Cardano type 13, Tezos type 16)
  7. 4. secp256k1 ECDSA, Bitcoin style (types 1, 5, 6, 7, 14)
  8. 5. secp256k1 ECDSA, Ethereum style (types 4, 15)
  9. 6. BIP-340 Schnorr (Taproot, type 9)
  10. 7. sr25519 (Polkadot, type 12)
  11. 8. Accounts that cannot sign
  12. 9. Native foreign transactions carried in the message field
  13. 10. Multi-signature accounts
  14. 11. Everything else a key signs on this chain
  15. 12. Off-chain message signing (tools and wallets, not consensus)
  16. 13. Encrypted messages (not consensus)
  17. 14. Key derivation (not consensus)

02 — Signatures and signing

Edition 0.6.1 · verified against the reference implementation, version 0.6.1

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.

  1. Build U as 03 specifies (type, version, timestamp, sender, recipient, fee, survival for versions 2 and 3, expiry for version 3, body, escrow part, message).
  2. digest = SHA3-256(5A42432D5458 ‖ G ‖ U).
  3. Sign digest as the sender's account type requires (§2–§7). Place the signature bytes after U to obtain the signed transaction bytes.
  4. 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 G02-1-sign-v3valid

Loading the test widget…

The unbound digest SHA3-256(U), which is refused02-1-unbound-digestvalid

Loading the test widget…

The signed version-3 SendZBC passes the signature check of a node whose genesis hash is G02-1-tx-validvalid

Loading the test widget…

A signature over the unbound digest SHA3-256(U) is refused02-1-tx-v1invalid

Loading the test widget…

The same U signed for another genesis is refused02-1-tx-other-chaininvalid

Loading the test widget…

An empty signature is refused02-1-tx-empty-signatureinvalid

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:

  1. If address is exactly 32 bytes: if its first 4 bytes read as int32 LE equal 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.)
  2. If address is shorter than 4 bytes: reject.
  3. If the type is 16: verify as Tezos (§3.2). If the type is 13: verify as Cardano (§3.2).
  4. 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.
  5. 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".
  6. If not compact, the payload after the 4-byte type must be non-empty (it is taken as the public key).
  7. 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.
  8. 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").

How to compute it. Follow the steps; §3–§7 give each family's bytes.

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 sign02-2-p2wshinvalid

Loading the test widget…

A 65-byte signature on a native account is the wrong size02-2-native-65invalid

Loading the test widget…

A 98-byte field on a P2WSH account is refused by its size first02-2-p2wsh-98invalid

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 verifies02-3_1-verifyvalid

Loading the test widget…

The same signature with its first byte changed does not02-3_1-tamperedvalid

Loading the test widget…

The burn payload is not a key: nothing verifies under it02-3_1-burn-keyvalid

Loading the test widget…

The §1 signature verifies for the typed native account02-3_1-native-accountvalid

Loading the test widget…

Nothing verifies for the burn address02-3_1-burn-accountvalid

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 key02-3_2-key-hashvalid

Loading the test widget…

A key-carrying signature for the Tezos account of the §1 key02-3_2-tezosvalid

Loading the test widget…

The same field for the Cardano account of the §1 key02-3_2-cardanovalid

Loading the test widget…

The same field for a Tezos account of another key is refused02-3_2-tezos-wrong-hashinvalid

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 key02-4-test-keyvalid

Loading the test widget…

A Bitcoin-style signature for a P2PKH account02-4-p2pkhvalid

Loading the test widget…

The same field with the last byte of s changed02-4-p2pkh-tamperedvalid

Loading the test widget…

The same field cut to its first 98 bytes is refused before any hashing02-4-p2pkh-98invalid

Loading the test widget…

The same field for another P2PKH account is refused02-4-p2pkh-wrong-hashinvalid

Loading the test widget…

The same signature with s replaced by n - s (high s) is invalid02-4-p2pkh-high-svalid

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 digest02-5-recovervalid

Loading the test widget…

An Ethereum-style signature for the compact Ethereum account02-5-ethereumvalid

Loading the test widget…

With v = 28 another key is recovered02-5-recover-v28valid

Loading the test widget…

With v = 28 the signature is refused for the account02-5-ethereum-v28invalid

Loading the test widget…

The same signature with v written as 0 is refused at the envelope02-5-v0-envelopeinvalid

Loading the test widget…

The verifier itself recovers the same key from v = 002-5-v0-verifiesvalid

Loading the test widget…

With v = 27 the envelope's recovery id passes02-5-v27-envelopevalid

Loading the test widget…

The v = 0 copy as a MultiSignature participant signature is refused02-5-v0-multisiginvalid

Loading the test widget…

With v = 27 the participant signature is accepted in the body02-5-v27-multisigvalid

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 account02-6-taprootvalid

Loading the test widget…

The same signature over the digest with its first byte changed02-6-taproot-tamperedvalid

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 substrate02-7-polkadotvalid

Loading the test widget…

The same signature over a changed message02-7-polkadot-tamperedvalid

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 sign02-8-dataset-senderinvalid

Loading the test widget…

An Estonia eID account is refused as not implemented02-8-estoniainvalid

Loading the test widget…

A bare 32-byte sender is refused before any signature02-8-bare-senderinvalid

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:

  1. The envelope: expiry 0 ("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"); survival 0 (checked before these, above).
  2. The chain binding of a Solana or Bitcoin carrier (step 4 and 3 below), judged for the block the transaction lands in.
  3. 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, s or yParity, yParity 0 or 1 on a typed transaction, no scalar carried as a list, an empty access list ("Ethereum carrier is not canonical: …"). Its chainId is 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 envelope fee equals the fee the signed gas fields name: gas_price × gas_limit / 10^10 atomic units, gas_price being maxFeePerGas on 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 of 04 still 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 hash G is (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.)
  4. 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 and 76a914 ‖ 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 index 0xFFFFFFFF ("Bitcoin carrier needs exactly one genesis outpoint", "Bitcoin carrier input must spend the ZooBC genesis hash at index 0xFFFFFFFF").
  5. Solana. Exactly one signature in a one-byte count, and a header that requires exactly one: message[0] = 01 and message[65] = 01 ("Solana carrier must carry exactly one signature"). The signed recent_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 token ZSOL only ("Solana carrier moves ZSOL or ZBC only") and never pays its fee in the token ("Solana carrier cannot pay its fee in the token").
  6. Once only, by native id. The carrier id is Keccak-256 of 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 the SHA3-256 of 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.
  7. The Ethereum nonce. At admission (the staging entry, the pool, and the HTTP route's pre-admission check) the carrier's nonce must 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-count answers count (the account nonce) and pending (the next free nonce over this node's pool and staging, the judged carrier being none); the node's Ethereum RPC answers eth_getTransactionCount(address, "pending") with pending and every other tag with count (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 mirrors02-9-eth-carriervalid

Loading the test widget…

The same carrier with another ZooBC recipient is refused02-9-eth-carrier-wrong-toinvalid

Loading the test widget…

A carrier signed for this chain's EVM chain id passes the signature check02-9-carrier-signaturevalid

Loading the test widget…

The same carrier passes the binding: chain id 0x0883E003, fee equal to the signed gas fields02-9-carrier-boundvalid

Loading the test widget…

The same transfer signed with chain id 1 is refused on a chain whose genesis hash starts E00302-9-carrier-chain-1invalid

Loading the test widget…

Its native signature itself verifies02-9-carrier-chain-1-signaturevalid

Loading the test widget…

The bound carrier with an envelope fee other than its signed gas fee is refused02-9-carrier-feeinvalid

Loading the test widget…

The reference's raw test transaction in a version-3 envelope with an expiry is refused02-9-carrier-expiryinvalid

Loading the test widget…

A Solana carrier naming the main chain block 100, in block 10102-9-solana-boundvalid

Loading the test widget…

The same carrier in block 820, the cited block 720 blocks below02-9-solana-window-edgevalid

Loading the test widget…

In block 821 the cited block is no main chain block of the last 72002-9-solana-staleinvalid

Loading the test widget…

A carrier naming a hash that is no main chain block is refused02-9-solana-unknowninvalid

Loading the test widget…

A carrier signed with nonce 5 from an account whose nonce is 4, nothing pooled02-9-nonce-admissioninvalid

Loading the test widget…

A block carrying that carrier while the account nonce is 4 is invalid02-9-nonce-blockinvalid

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 account02-10-multisigvalid

Loading the test widget…

A MultiSignature body whose participant signature ends in 00 is refused02-10-v0-participantinvalid

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 block02-11-receipt-requestvalid

Loading the test widget…

Sign a non-signing statement (the SpineRefusal digest)02-11-non-signing-statementvalid

Loading the test widget…

Sign a gateway registry attestation02-11-attestationvalid

Loading the test widget…

The tag ZBC-TX02-11-tag-zbc-txvalid

Loading the test widget…

The tag ZBC-CANCEL02-11-tag-zbc-cancelvalid

Loading the test widget…

The tag ZBC-RCPT02-11-tag-zbc-rcptvalid

Loading the test widget…

The tag ZBC-SPINE-REFUSE02-11-tag-zbc-spine-refusevalid

Loading the test widget…

The tag ZBC-P2P-RPC-V302-11-tag-zbc-p2p-rpc-v3valid

Loading the test widget…

The tag EIP-191-3202-11-tag-eip-191-32valid

Loading the test widget…

The tag TRON-3202-11-tag-tron-32valid

Loading the test widget…

The receipt request verifies for its recipient02-11-receipt-request-verifyvalid

Loading the test widget…

The same signature presented to another recipient does not verify02-11-receipt-request-othervalid

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 message02-12-messagevalid

Loading the test widget…

The message signature verifies02-12-message-verifyvalid

Loading the test widget…

The same signature against hello zoobc! does not02-12-message-changedvalid

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)02-13-no-vectorvalidreference

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 mnemonic02-14-derive-0valid

Loading the test widget…

Derive account 1 from the test mnemonic02-14-derive-1valid

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.