On this page
  1. §0 The area in one paragraph
  2. 1. The envelope byte layout
  3. 2. Transaction type identifiers
  4. 3. Sender and recipient
  5. 4. Version, fee, survival and expiry
  6. 5. Timestamp
  7. 6. The body
  8. 7. The escrow part
  9. 8. The message
  10. 9. The signature field, the hash and the id
  11. 10. Wire and submission forms
  12. 11. Parsing an envelope
  13. 12. What makes a well-formed envelope unacceptable

03 — The transaction envelope

Edition 0.6.1 · verified against the reference implementation, version 0.6.1

Out of scope the body layout of each type (the family documents 08–18); fees, the fee floor and everything else admission checks (04); what a block does with the transaction (19, 21); the signing schemes (02); the JSON shape of a transaction when the node answers a query (31)

§0 The area in one paragraph

Every transaction on ZooBC is one byte string, the envelope, laid out the same way for all 78 transaction types (§2): a 4-byte type number, a 1-byte version, an 8-byte timestamp, the sender and recipient addresses, the fee, in versions 2 and 3 a survival deposit, in version 3 an expiry window, a length-prefixed type-specific body, an escrow part, a length-prefixed message, and finally the signature. The unsigned envelope is what the signer's digest covers (02); the signed envelope is what travels between nodes, what the transaction hash is taken over, and what a block carries. Nothing about the envelope is negotiable per node: an implementation must produce byte-identical envelopes for the same fields, parse any envelope into the same fields, refuse the same malformed ones, and compute the same hash and id. The JSON a wallet posts to a node is only a convenient spelling of these fields; the node turns it into the envelope before anything else happens, so the JSON form has no independent meaning. The type number also tells the chain which rule gates the type: a few types are refused below a height, one is refused from a height, and all others are valid at every height. Every genesis file lists every rule at 0, so every gated type is accepted from block 1 and the retired one is refused from block 1. Every sender and recipient is a typed account: a bare 32-byte key cannot even be written into an envelope. Version 3 adds four bytes that state how long after its timestamp a block may still carry the transaction (up to a day instead of the fixed hour); three batch types (257, 267, 297) carry several actions of one kind with their recipients in the body and an empty envelope recipient.


1. The envelope byte layout

Purpose. Fix the bytes of every transaction, unsigned and signed.

Inputs. The fields of a transaction: type, version, timestamp, sender, recipient, fee, survival (versions 2 and 3), expiry (version 3), body, escrow (optional), message (optional), signature (signed form only).

Output and effect. The unsigned envelope U is the concatenation below; the signed envelope is U ‖ signature. Offsets are given for a transaction whose sender and recipient are 36-byte type-0 addresses; the address fields are variable (01 §4.1), so every later offset shifts with them.

offset length field encoding
0 4 transaction_type uint32 LE (§2)
4 1 version one byte: 01, 02 or 03 (§4)
5 8 timestamp int64 LE, Unix seconds (§5)
13 36 sender_account_address LE32(type) ‖ payload, payload length by type (§3)
49 36 or 4 recipient_account_address the same, or the 4-byte empty marker 02 00 00 00 (§3)
85 8 fee int64 LE, atomic units
93 8 survival int64 LE, atomic units; present only when version ≥ 2
101 4 expiry uint32 LE, seconds; present only when version ≥ 3 (§4, §5)
93 / 101 / 105 4 body_length uint32 LE = length of the body
… body_length transaction_body_bytes opaque to the envelope; the type's own layout (§6)
… 4 or more escrow part 02 00 00 00 when there is no escrow, else the full escrow part (§7)
… 4 message_length uint32 LE
… message_length message bytes (§8)
… by sender type signature signed form only (§9)

The smallest well-formed unsigned envelope is 29 bytes (type, version, timestamp, an empty recipient marker standing in for both addresses, fee, body length); the reference's parser refuses anything shorter before reading a field.

How to compute it. Write the fields in order with the encodings of 01 §1. A sender or recipient that is a bare 32-byte key (32 bytes whose first four are not 0D 00 00 00, 01 §4) is not written at all: building the envelope fails with accounts are typed: a bare 32-byte key is not an account on this chain, so no digest, hash or id exists for such a transaction. An empty recipient, or one whose type is 2, is written as 02 00 00 00; a sender or recipient of 24 bytes or more (a 32-byte typed Cardano account included) is written as given; a sender that is empty is written as nothing (such an envelope is malformed and refused later); any other length is an error ("Invalid sender/recipient account address size"). The survival field is written when and only when the version byte is ≥ 2, and the expiry field when and only when it is ≥ 3, regardless of their values. The escrow part is written in full when the transaction has an escrow with a non-empty approver address, else as the 4-byte marker.

Rule activation. None for the layout itself. Version 2 is accepted only from rule survival_field, version 3 only from rule tx_expiry_field as well (§4); both are at 0 on every chain. The bare-key refusal is rule typed_accounts_only, at 0 on every chain.

Rejections and errors. See §11 (parsing) and §12 (what the validator refuses in a well-formed envelope).

Vector (computed with the vectors' chain identity G = E003E4E3…2871 of 02 §1; the reference's zbc-cli send-zbc --offline with that genesis produces the same bytes, digest, signature and hash, and an independent implementation agrees). Sender 00000000 ‖ 5e8eb28d…2152 (seed 51bae95d…5d96, 02 §14), recipient 00000000 ‖ fd4472bb…1b67 (m/44'/883'/1' of the same mnemonic). A version-3 SendZBC, 125 unsigned bytes:

offset length field bytes
0 4 type 01000000 (SendZBC)
4 1 version 03
5 8 timestamp fbc8e66a00000000 (1,793,509,627)
13 36 sender 000000005e8eb28dccaa94a992f7169fa67966207d96aa55df7d24d2d6ec1f538c9f2152
49 36 recipient 00000000fd4472bbdec43b919aa37b9b3366a3318f2902a753a15f5fd6d43c44b5121b67
85 8 fee 404b4c0000000000 (5,000,000)
93 8 survival 0000000000000000
101 4 expiry 201c0000 (7,200 s)
105 4 body length 08000000
109 8 body 00e1f50500000000 (1 ZBC)
117 4 escrow part 02000000 (none)
121 4 message length 00000000

Followed by the 64-byte signature of 02 §1 (signed length 189); hash 058c3078711492773af075a3b4dd07b44a7e17bd3b3ea985f64677af96a4e467.

A version-2 SendZBC of 1 ZBC with survival 0.1 ZBC, an escrow and a message (same sender, the recipient also the approver, same genesis and timestamp), 204 unsigned bytes:

offset length field bytes
0 4 type 01000000
4 1 version 02
5 8 timestamp fbc8e66a00000000 (1,793,509,627)
13 36 sender 00000000 5e8eb28d…2152
49 36 recipient 00000000 fd4472bb…1b67
85 8 fee 404b4c0000000000 (5,000,000)
93 8 survival 8096980000000000 (10,000,000)
101 4 body length 08000000
105 8 body 00e1f50500000000
113 36 escrow approver 00000000 fd4472bb…1b67
149 8 commission e803000000000000 (1,000)
157 8 timeout 1be5e66a00000000 (1,793,516,827 = timestamp + 7,200)
165 4 instruction length 13000000 (19)
169 19 instruction release on delivery
188 1 multi-party flag 00
189 4 message length 0b000000 (11)
193 11 message hello zoobc

Digest a462239f2e42c8c727edd68641fb3a8c07203a7d5f336f6b8864cae5566ec001, signature 9912c7472a9f2098d9ddd7a837829584fee1b16076a053b2448fdb81a56c862fb1dd7187ee46f61ab68b10730035196663bdbfe8238fbe8fb396e9919f5adc03, hash 4c337c698be6890c83c2f073c37440b653954c6a37ad304c0c726f2b9e02ab08.

An envelope with an empty recipient, type 3, 77 unsigned bytes (computed): 03000000 01 03f1536500000000 ‖ sender(36) ‖ 02000000 ‖ 40420f0000000000 ‖ 04000000 ‖ deadbeef ‖ 02000000 ‖ 00000000.

Test cases · §1

5 cases · 5 valid

A version-3 SendZBC envelope03-1-v3valid

Loading the test widget…

A version-2 SendZBC with survival, an escrow and a message03-1-v2-escrowvalid

Loading the test widget…

Sign the version-2 envelope03-1-v2-signvalid

Loading the test widget…

An envelope with an empty recipient (type 3, 77 bytes)03-1-empty-recipientvalid

Loading the test widget…

Sign the version-3 envelope: signature and hash03-1-v3-signvalid

Loading the test widget…

Defects to match. None in the layout.


2. Transaction type identifiers

Purpose. Name every type number, its meaning and the rule that gates it.

Inputs. The 4-byte transaction_type.

Output and effect. A type number is group + 256 × subtype (group = id & 0xFF, subtype = (id >> 8) & 0xFF); the two upper bytes are always zero. The types that exist:

id group,sub name gate
0 0,0 Empty —
1 1,0 SendZBC —
2 2,0 NodeRegistration —
258 2,1 NodeRegistrationUpdate —
514 2,2 RemoveNodeRegistration —
770 2,3 ClaimNodeRegistration —
3 3,0 SetupAccountDataset —
259 3,1 RemoveAccountDataset —
4 4,0 ApprovalEscrow —
260 4,1 EscrowRequest —
516 4,2 DeclineEscrowRequest from escrow_request
5 5,0 MultiSignature —
6 6,0 LiquidPayment —
262 6,1 LiquidPaymentStop —
7 7,0 FeeVoteCommitment —
263 7,1 FeeVoteReveal —
8 8,0 DFSCreateFile —
264 8,1 DFSUpdateFile —
520 8,2 DFSDeleteFile —
9 9,0 AddPrepaidStorage —
10 10,0 IssueToken —
11 11,0 TransferToken —
12 12,0 MintToken —
13 13,0 BurnToken —
14 14,0 FinanceToken —
15 15,0 CreateTrigger —
16 16,0 CancelTrigger —
17 17,0 AttestEvent —
18 18,0 CreateSwapOffer —
19 19,0 AcceptSwapOffer —
20 20,0 CancelSwapOffer —
21 21,0 CreateMarket —
22 22,0 PlaceOrder —
23 23,0 CancelOrder —
24 24,0 CreateApp —
25 25,0 JoinApp —
26 26,0 AppMove —
27 27,0 ResignApp —
28 28,0 ClaimAppTimeout —
29 29,0 ScheduledTransfer —
30 30,0 CancelSchedule —
31 31,0 ReassignSchedule —
32 32,0 RegisterRelease —
33 33,0 ReleaseAuthorityPropose —
34 34,0 ReleaseAuthorityAccept —
35 35,0 RevokeRelease —
36 36,0 RegisterGateway —
37 37,0 GatewayHeartbeat —
38 38,0 UnregisterGateway —
39 39,0 SettleApp —
40 40,0 StoreFile —
296 40,1 FundStoredFile from stored_file_topup
41 41,0 SubmitStorageProof —
42 42,0 TransferDataset —
43 43,0 SetDatasetPolicy —
44 44,0 AcceptDataset —
45 45,0 DeleteDataset —
46 46,0 RegisterArchival —
47 47,0 UnregisterArchival —
48 48,0 RegisterRelay —
49 49,0 UnregisterRelay —
50 50,0 SetTransactPolicy —
51 51,0 SetConsensusParam —
52 52,0 FundLongevity —
53 53,0 CancelLongevity retired from survival_field
309 53,1 CloseLongevity from survival_field
54 54,0 SetSplitPolicy from split_policy
55 55,0 LinkAccount from account_groups
56 56,0 UnlinkAccount from account_groups
57 57,0 SetMemberPermissions from account_groups
58 58,0 TransferGroupControl from account_groups
59 59,0 QueueAttendance — (its own rule queue_attendance is active from height 0 on every chain, 09)
60 60,0 EquivocationReport from equivocation_miss
61 61,0 RollCall — (valid only in blocks 1 .. roll_call_blocks, 09)
257 1,1 SendZBCBatch —
267 11,1 TransferTokenBatch —
297 41,1 SubmitStorageProofBatch —
62 62,0 SpineEquivocationReport from spine_equivocation_report (a fee-free duty of a registered node's typed account; body = spine height (uint32 LE) ‖ the accused node key (32) ‖ header length L (uint32 LE, 1..4,096) ‖ the spine block candidate's header bytes its spine signature covers (L; the type's validation then requires 204, or 284 with a seed proof) ‖ that spine signature (64) ‖ the non-signing statement signature on the same candidate (64), nothing more: "SpineEquivocationReport body too short", "SpineEquivocationReport header length out of range", "SpineEquivocationReport: the body must be the header and two 64-byte signatures, nothing more"; the accused is charged one miss once per (node, spine height); 02 §11, 35 §7, 04)

"—" means the type is accepted at every height. A gated type is refused below its rule's height; a retired type is refused from its rule's height. Any other number is an unknown type: the envelope still parses (the body is opaque), and what happens to it is decided by admission and execution (the stateless validation refuses it with "Unknown transaction type: N" at admission and in block validation; the executor refuses it too). The string names in the table are the ones the reference's API uses with the suffix Transaction (for example SendZBCTransaction), except that type 258 is UpdateNodeRegistrationTransaction and 7/263 are FeeVoteCommitmentVoteTransaction / FeeVoteRevealVoteTransaction. Type 60 is EquivocationReportTransaction, 61 RollCallTransaction, 62 SpineEquivocationReportTransaction, 257 SendZBCBatchTransaction, 267 TransferTokenBatchTransaction, 297 SubmitStorageProofBatchTransaction. Types 61, 257, 267 and 297 have no gating rule: every chain accepts them from block 1.

How to compute it. LE32(id).

Rule activation. split_policy, escrow_request, account_groups, survival_field, stored_file_topup, equivocation_miss and spine_equivocation_report: active from height 0 on every chain, so every gated type is accepted from block 1 and CancelLongevity (53) is refused from block 1. The types are additionally gated by the executor at the same heights, so a block carrying a too-early or retired type is invalid on every node. Rule survival_mode, active from height 0 on every chain: while the chain is in survival mode at a block (19; a chain whose genesis names survival_min_producers is in it from block 1 until that many distinct blocksmiths have produced, 06 §9), that block may not carry a transaction of the governance category (types 7, 263, 32, 33, 34, 35, 51) nor of the bridge category (type 17); 04 §6 and 19.

The batch types 257, 267 and 297 carry several actions of one kind (up to 25 ZBC payments, 32 token transfers, or 1,000 storage proofs of one node for one epoch), all or nothing, every action checked up front; their bodies are in 08, 14 and 11, their minimum fee (the sum of the one-action minimums) in 04. A batch's envelope recipient must be empty (§3). There is no mixed bundle of several kinds.

Rejections and errors. "Transaction type N is not active until height H (rule R)"; "Transaction type 53 is retired from height H"; under survival mode "SurvivalMode: transaction type N is not accepted while fewer than survival_min_producers distinct producers made the last 120 blocks (survival mode: governance and bridge are frozen until N produce again)" ("producers" means distinct blocksmiths), at admission and, judged at the block's height by the same stateless validation, as the refusal that makes a block carrying one invalid (19 §2 step 11; the executor runs that validation before its own gate, so no other survival text is produced); "SurvivalMode: the survival state could not be read: …" when the flag cannot be read.

Vector (computed). 258 = 2 + 256·1 → bytes 02 01 00 00; 770 = 2 + 256·3 → 02 03 00 00; 309 = 53 + 256·1 → 35 01 00 00; 60 → 3c 00 00 00; 61 → 3d 00 00 00; 62 → 3e 00 00 00; 257 = 1 + 256·1 → 01 01 00 00; 267 = 11 + 256·1 → 0b 01 00 00; 297 = 41 + 256·1 → 29 01 00 00. Invalid inputs: an envelope of type 53 (35 00 00 00) on any chain → refused "Transaction type 53 is retired from height 0"; an envelope of type 999 (e7 03 00 00) → parses (the body is opaque), then refused by validation with "Unknown transaction type: 999" once the fee check (04) has passed.

Test cases · §2

12 cases · 10 valid · 2 invalid

Type 258 is written as 0201000003-2-type-258valid

Loading the test widget…

Type 770 is written as 0203000003-2-type-770valid

Loading the test widget…

Type 309 is written as 3501000003-2-type-309valid

Loading the test widget…

Type 60 is written as 3c00000003-2-type-60valid

Loading the test widget…

Type 61 is written as 3d00000003-2-type-61valid

Loading the test widget…

Type 62 is written as 3e00000003-2-type-62valid

Loading the test widget…

Type 257 is written as 0101000003-2-type-257valid

Loading the test widget…

Type 267 is written as 0b01000003-2-type-267valid

Loading the test widget…

Type 297 is written as 2901000003-2-type-297valid

Loading the test widget…

An envelope of type 53 (CancelLongevity) is refused on every chain03-2-retired-53invalid

Loading the test widget…

An envelope of the unknown type 999 still parses (the body is opaque)03-2-parse-999valid

Loading the test widget…

Validation refuses the unknown type 999 once the fee check has passed03-2-unknown-999invalid

Loading the test widget…

Defects to match. The type numbering is sparse (no 6,2 or 7,2; 296, 309 and the batches 257, 267, 297 sit under groups 40, 53, 1, 11 and 41); an implementation must not infer a type from its group alone.


3. Sender and recipient

Purpose. How the two addresses are written, read and judged.

Inputs. The sender's and recipient's account addresses (01 §4).

Output and effect. Writing: as in §1. Reading: 4 bytes of type; if the type is 2 (Empty) the field is those 4 bytes and the address is empty; otherwise the payload length is the fixed-layout length of 01 §4.1 for that type (32 for an unknown type) and the whole 4 + length bytes are the address. Consequences an implementation must reproduce:

  • A bare 32-byte key as sender or recipient (01 §4) is refused first, before the signature is checked: accounts are typed: a bare 32-byte key is not an account on this chain. A parsed address is always typed, so the bare form can only arrive through the JSON submission (§10) or the proto's named fields (§10); the serialiser refuses it (§1).
  • A full-key form (01 §4 consequence 4: the 68-byte Ethereum or Tron form, the 37- or 69-byte form of types 1, 5 and 7) as sender, recipient or escrow approver is refused (rule canonical_account_forms): a full-key account form (an Ethereum or Tron key, a Bitcoin key) is not an account: no transaction can be sent from it; name the 20-byte address (rule canonical_account_forms). A parsed envelope cannot carry one (the parser reads the 20-byte form of these types), so it can only arrive in the proto's named fields (§10); the check is part of the stateless validation, so a block carrying one is invalid.
  • Right after it (rule bridge_withdrawal_credit, 34): a TransferToken whose message begins ZBW1| is a bridge withdrawal and must be one of an open bridge coin, carry no escrow, be sent to that coin's custody account and name a destination its chain can be paid at (34 §5); and no transaction names a bridge coin's custody account (34 §1a) as its sender, as its recipient (a withdrawal excepted) or as its escrow approver, or carries that account's 32 bytes anywhere in its body (34 §5a; for example the recipient is the custody account of ZETH, which receives only withdrawals of ZETH (a TransferToken with a ZBW1| message): nothing else sent to it could ever leave it). Both are part of the stateless validation: refused at admission, a block carrying one is invalid.
  • A sender can never be empty in a valid transaction ("Missing sender address"); a sender whose type byte reads 2 parses to an empty sender and is refused for that reason.
  • The validator then accepts a sender of exactly 32 bytes (only a typed Cardano account reaches this point with 32 bytes) or of at least 24 bytes; anything else is "Invalid sender address size". The same bounds apply to a SendZBC recipient, which must also be present ("Missing recipient address") and well-formed per 01 §4.2 ("Recipient address: …").
  • For every other type that names a recipient, the 01 §4.2 shape check applies (rule recipient_address_shape). A LiquidPayment, ScheduledTransfer or CreateTrigger whose envelope recipient is a type nobody can spend from (outside the signing list of 01 §4, a ZBS_ dataset address excepted; Taproot under rule taproot_recipients) is refused: "Recipient address type cannot hold spendable funds (transfer would be permanently locked)".
  • A batch (types 257, 267, 297) must have an empty envelope recipient ("<TypeName>: a batch names its recipients in its body; the envelope recipient must be empty"); each recipient inside its body passes the 01 §4.2 shape check.
  • Which types require, allow or ignore a recipient is each type's business (08–18).

How to compute it. As in §1 and 01 §4.

Rule activation. typed_accounts_only, canonical_account_forms, bridge_withdrawal_credit and recipient_address_shape (compiled default 30,000): active from height 0 on every chain. The unspendable-recipient check of LiquidPayment, ScheduledTransfer and CreateTrigger has no rule of its own; under canonical_account_forms a full-key form is one of the types that cannot hold spendable funds.

Rejections and errors. As listed; all are admission refusals and, for a block, invalidity (19).

Vector (computed). §1's vectors: a 36-byte type-0 sender; an empty recipient as 02000000. Invalid input: the §1 version-3 transaction with its sender given as the bare 32 bytes 5e8eb28dccaa94a992f7169fa67966207d96aa55df7d24d2d6ec1f538c9f2152 → refused accounts are typed: a bare 32-byte key is not an account on this chain (no envelope, hash or id exists for it). A SendZBC with recipient 63000000 ‖ 32 bytes (type 99, unknown) → refused "Recipient address: Invalid account address type". A SendZBC delivered in the proto's named fields with recipient 04000000 ‖ 79be667e…1798 ‖ 483ada77…d4b8 (the 68-byte full-key form of 01 §4's vector) → refused a full-key account form (an Ethereum or Tron key, a Bitcoin key) is not an account: no transaction can be sent from it; name the 20-byte address (rule canonical_account_forms); with recipient 04000000 ‖ 7e5f4552091a69125d5dfcb7b8c2659029395bdf it passes this check.

Test cases · §3

8 cases · 1 valid · 7 invalid

A bare 32-byte sender is refused03-3-bare-senderinvalid

Loading the test widget…

A bare 32-byte sender is the first refusal of validation03-3-bare-sender-checkinvalid

Loading the test widget…

A SendZBC to a recipient of the unknown type 99 is refused03-3-recipient-type-99invalid

Loading the test widget…

A SendZBC with an empty recipient is refused03-3-missing-recipientinvalid

Loading the test widget…

A 20-byte sender is refused03-3-short-senderinvalid

Loading the test widget…

A SendZBC whose recipient is a 68-byte full-key form is refused03-3-full-key-recipientinvalid

Loading the test widget…

The same SendZBC to the 24-byte Ethereum account of that key passes03-3-eth-recipientvalid

Loading the test widget…

An escrow approver in a full-key form is refused the same way03-3-full-key-approverinvalid

Loading the test widget…

Defects to match. The parser reads 32 payload bytes for any unknown type, so an envelope with an unknown sender type is sliced as if the payload were 32 bytes; an implementation that refused such a sender earlier would still agree on the outcome (the transaction is invalid) but must not fail to parse a block carrying it differently from the reference. Such a transaction fails signature verification (02 §2) and is never mined; it can only be met on the wire.


4. Version, fee, survival and expiry

Purpose. The three versions and what the fee, survival and expiry fields mean to the envelope.

Inputs. version, fee, survival, expiry.

Output and effect.

version fields after fee accepted from
1 none every height
2 survival (int64 LE) rule survival_field
3 survival (int64 LE), then expiry (uint32 LE, seconds) rules tx_expiry_field and survival_field
  • A version-1 object must carry survival 0 and a version-1 or version-2 object must carry expiry 0: their bytes have no field for them, so a non-zero value "was never signed" and is refused.
  • Survival (versions 2 and 3) must be 0 or at least LONGEVITY_MIN_DEPOSIT = 10,000,000 atomic units (0.1 ZBC), never negative.
  • Expiry (version 3) is the window, in seconds after the transaction's timestamp, within which a block may carry the transaction (§5). 0 means the default window of TRANSACTION_EXPIRATION_OFFSET = 3,600 s; the most is TRANSACTION_EXPIRY_CAP = 86,400 s (a day). A smaller value than the default is allowed and shortens the window.
  • A transaction whose authorisation is a foreign native transaction carried in the message (02 §9) may not carry a non-zero survival (the foreign signature does not cover it).
  • Any version other than 1, 2 or 3 is "Invalid transaction version".
  • The fee is an int64 of atomic units; what it must be at least is 04's business; what survival buys is 13's.

How to compute it. Write version as one byte; write survival only for version ≥ 2 and expiry only for version ≥ 3. The window a transaction gets is W = min(expiry, 86,400) when the version is 3 and expiry > 0, else W = 3,600.

Rule activation. survival_field (compiled default 30,000) and tx_expiry_field (compiled default 0): at 0 on every chain. The pool keeps a transaction until timestamp + W (node-local, on its clock, 04). Every chain keeps transaction ids, the replay guard, for at least TRANSACTION_REPLAY_WINDOW_SECONDS = 86,400 + 3,600 = 90,000 s (25 h), counted in blocks at the fastest legal pace, ceil(90,000 / max(min_block_interval − 2, 1)) = 6,924 blocks at 15-s blocks: the prune never deletes a transaction row closer than that to the tip, and a snapshot carries the transactions of that window (26).

Rejections and errors. Checked in this order: "A version-N transaction carries no expiry; use transaction version 3" (a version 1 or 2 with expiry ≠ 0); "A version-1 transaction carries no survival; use transaction version 2"; for version 3, "Transaction version 3 (expiry) is not active until height H" and "Expiry above the cap of 86400 s"; for versions 2 and 3, "Transaction version 2 (survival) is not active until height H", "Survival must not be negative", "Survival below the minimum deposit of 10000000 units (0 means none)"; "Invalid transaction version"; later, with the message checks, "A foreign-signed carrier transaction cannot carry survival (the foreign signature does not cover it); fund it with FundLongevity instead".

Vector (computed). The §1 version-3 envelope has survival 0 at offset 93 and expiry 201c0000 = 7,200 at offset 101; the §1 version-2 envelope has survival 8096980000000000 = 10,000,000 (the minimum deposit) at offset 93 and no expiry field. A version-2 JSON submission with "expiry":5 is refused by the reader (§10) before the hash is computed; a version-3 one with "expiry":90000 likewise ("expiry must be between 0 and 86400 seconds").

Test cases · §4

9 cases · 2 valid · 7 invalid

The version-3 envelope passes the envelope checks03-4-v3-validvalid

Loading the test widget…

The version-2 envelope (survival of exactly the minimum deposit) passes03-4-v2-validvalid

Loading the test widget…

A version-3 expiry of 90,000 s is over the cap03-4-expiry-capinvalid

Loading the test widget…

A version-1 transaction with a survival is refused03-4-v1-survivalinvalid

Loading the test widget…

A survival below the minimum deposit is refused03-4-survival-dustinvalid

Loading the test widget…

A negative survival is refused03-4-survival-negativeinvalid

Loading the test widget…

Version 4 is not a transaction version03-4-version-4invalid

Loading the test widget…

A version-2 JSON submission with expiry 5 is refused before the hash03-4-json-v2-expiryinvalid

Loading the test widget…

A version-3 JSON submission with expiry 90,000 is refused before the hash03-4-json-expiry-90000invalid

Loading the test widget…

Defects to match. The version byte is compared as ≥ 2 and ≥ 3 by the serialiser and the parser but the validator accepts only 1, 2 and 3; a version byte of 4 or more therefore parses as a version-3 layout (survival and expiry read) and is then refused. An implementation must parse it the same way to agree on the hash of such a (refused) transaction.


5. Timestamp

Purpose. When the transaction claims to have been made, and the windows that bound it.

Inputs. timestamp (int64 LE, Unix seconds); the transaction's window W (§4).

Output and effect. Must be positive ("Invalid transaction timestamp"). Two further bounds:

where rule consensus?
admission (node-local clock) refused when timestamp + W < now ("Transaction expired: its timestamp T is more than W s in the past; sign it again") or timestamp > now + 3600 ("… in the future; check the signer's clock") no: each node's own clock
block validation invalid when block.timestamp > timestamp + W ("Block contains an expired transaction"); from rule tx_timestamp_bound, also invalid when timestamp > block.timestamp + 3600 ("Block contains a transaction dated more than 3600 s after the block"); height 0 is exempt yes

W is 3,600 s unless a version-3 transaction states another (§4); the future bound TRANSACTION_FUTURE_TOLERANCE = 3,600 s is the same for every version. A blocksmith's own selection skips a pooled transaction whose timestamp + W is below the block's timestamp (node-local, 04). The timestamp is also the time base of an escrow's expiry (§7) and of the transaction's own identity (a re-signed copy with a new timestamp is a different transaction).

How to compute it. LE64(unix_seconds).

Rule activation. tx_timestamp_bound (compiled default 30,000) and tx_expiry_field: at 0 on every chain.

Rejections and errors. As in the table.

Vector (computed). The §1 version-3 envelope: timestamp 1,793,509,627 with W = 7,200, so a block may carry it until block timestamp 1,793,516,827; the §1 version-2 envelope (same timestamp, W = 3,600) until 1,793,513,227, and a block stamped 1,793,513,228 that carries it is invalid ("Block contains an expired transaction"). Invalid input: the version-3 envelope in a block stamped 1,793,506,026 (3,601 s before the transaction) → "Block contains a transaction dated more than 3600 s after the block".

Test cases · §5

6 cases · 2 valid · 4 invalid

The version-3 envelope may be carried until 7,200 s after its timestamp03-5-v3-windowvalid

Loading the test widget…

One second later the block would carry an expired transaction03-5-v3-window-overinvalid

Loading the test widget…

The version-2 envelope may be carried until 3,600 s after its timestamp03-5-v2-windowvalid

Loading the test widget…

A block stamped one second later carrying it is invalid03-5-v2-window-overinvalid

Loading the test widget…

The version-3 envelope in a block stamped 3,601 s before it is refused03-5-futureinvalid

Loading the test widget…

A timestamp of 0 is refused03-5-zero-timestampinvalid

Loading the test widget…

Defects to match. None.


6. The body

Purpose. The type-specific payload, as the envelope sees it.

Inputs. transaction_body_bytes.

Output and effect. A uint32 LE length followed by exactly that many bytes. The envelope imposes one limit: at most 65,536 bytes ("Transaction body exceeds maximum length of 65536"). The length written is always the body's actual length (the serialiser ignores any separately stored length). The meaning of the bytes is the type's own and is specified per family; the envelope does not require the body to parse (a body that does not parse is refused by the type's own validation, 04 and the family documents).

How to compute it. LE32(len(body)) ‖ body.

Rule activation. None.

Rejections and errors. The 65,536-byte limit; "Unexpected end of bytes (body)" when the declared length exceeds the remaining bytes.

Vector (computed). A SendZBC body is the 8-byte amount: 00e1f50500000000 = 100,000,000 atomic units (1 ZBC), written 08000000 00e1f50500000000. Invalid input: a body of 65,537 bytes → refused "Transaction body exceeds maximum length of 65536"; a body length field of 09000000 followed by only 8 body bytes and nothing else → "Unexpected end of bytes (body)".

Test cases · §6

2 cases · 2 invalid

A body length of 9 followed by 8 bytes03-6-short-bodyinvalid

Loading the test widget…

A body of 65,537 bytes is refused03-6-body-65537invalid

Loading the test widget…

Defects to match. None.


7. The escrow part

Purpose. The optional escrow condition on a transfer, carried in the envelope and covered by the signature.

Inputs. The escrow fields: approver address, commission, timeout, instruction, multi-party flag, co-signer signature, escrow request id.

Output and effect. When the transaction has an escrow (an approver address that is non-empty), the part is:

offset length field encoding
0 4 + n approver address LE32(type) ‖ payload, payload length by type
… 8 commission int64 LE, atomic units, paid to the approver
… 8 timeout int64 LE, an absolute Unix timestamp; the escrow expires when it is below the block timestamp
… 4 instruction length uint32 LE
… that instruction bytes, at most 128,000, no 0x00 byte
… 1 multi-party flag 00 or 01
… 4 co-signer signature length uint32 LE; only when the flag is 01
… that co-signer signature the recipient's signature (02 §11)
… 8 escrow request id int64 LE; only when the flag is 01

When there is no escrow the part is the 4-byte marker 02 00 00 00. The reader is lenient at the tail: if the bytes end after the instruction, the flag is taken as 00; if they end after the flag, or after the length, the missing fields are empty/zero. The writer always emits the flag, and for a multi-party escrow always emits the length (even 0), the signature bytes and the request id.

The validator refuses, in this order: an approver that is not a well-formed address (01 §4.2) or whose type cannot sign (outside the signing list of 01 §4) ("Escrow approver address type cannot sign: it could never approve or reject"); an escrow whose timeout is not after the transaction's own timestamp ("Escrow timeout must be a future Unix timestamp (now + lock duration); got T <= tx time S"); an escrow on any type other than SendZBC and TransferToken ("Escrow is only supported for SendZBC and TransferToken transactions"); under rule escrow_commission_nonnegative a negative commission ("Escrow commission cannot be negative") and, for a SendZBC, an amount + fee + commission + escrow rent (04 §4) that overflows an int64 ("Escrow amount + fee + commission + rent overflow"); an instruction over 128,000 bytes or containing a 0x00; and, from rule escrow_request, a multi-party escrow with neither a co-signature nor a request id, a request id on a type other than SendZBC, or a co-signature that does not verify (02 §11, 12). Under rule escrow_timeout_cap it also refuses a timeout beyond the prune horizon reachable from the transaction's block, unless the transaction's own survival deposit is at least what keeping it until the timeout costs ("Escrow timeout T is beyond the reachable prune horizon (cap C, block B); a header survival deposit of N units keeps it until the timeout (rule escrow_timeout_cap)"; the cap and the cost are 12). What the escrow does once mined is 12.

How to compute it. Write the fields in the order of the table.

Rule activation. escrow_request (multi-party verification), escrow_timeout_cap and escrow_commission_nonnegative (the commission sign and the overflow check, also applied by the pool's reservation, 04 §7): active from height 0 on every chain. The approver check has no rule.

Rejections and errors. As above; parse errors "Escrow data too short", "Escrow instruction too long". A parse error inside the escrow part is ignored by the envelope parser: the escrow is dropped and parsing continues at the same offset, so such bytes most likely fail at the message length or the signature instead; an implementation must behave identically (never reject on the escrow parse alone).

Vector (computed). The escrow part of the §1 version-2 envelope (offsets 113–188): approver 00000000fd4472bbdec43b919aa37b9b3366a3318f2902a753a15f5fd6d43c44b5121b67, commission e803000000000000 = 1,000, timeout 1be5e66a00000000 = 1,793,516,827 (7,200 s after the transaction's timestamp), instruction length 13000000, instruction release on delivery (19 bytes), flag 00. Invalid input: the same part with commission ffffffffffffffff (−1) → refused "Escrow commission cannot be negative".

Test cases · §7

3 cases · 3 invalid

An escrow whose timeout is not after the transaction's timestamp is refused03-7-escrow-past-timeoutinvalid

Loading the test widget…

The version-2 escrow part with commission ffffffffffffffff (-1) is refused03-7-escrow-commission-negativeinvalid

Loading the test widget…

An escrow on a dataset transaction is refused03-7-escrow-wrong-typeinvalid

Loading the test widget…

Defects to match. (a) The lenient tail parse above. (b) The parser does not re-check that multi_party is exactly 00 or 01: any non-01 byte means "not multi-party", but the byte is part of the signed bytes either way. (c) The escrow part has no "present" marker of its own: a recipient-less escrow is impossible to express because the first 4 bytes of the part double as the approver's type, and an approver of type 2 means "no escrow".


8. The message

Purpose. Free bytes any transaction may carry, with their size rules.

Inputs. message.

Output and effect. uint32 LE length then the bytes; absent means length 0. Limits, applied at admission and in block validation:

kind how recognised limit
plain neither of the below ≤ 256 bytes, no 0x00 byte ("Message exceeds maximum length of 256" / "Message contains null bytes")
encrypted the first 4 bytes are ZBE1 (5A 42 45 31) ≤ 320 bytes ("Encrypted message too large")
native carrier the sender is type 4 and the message parses as an Ethereum transaction; or type 11 and it parses and verifies as a Solana transfer; or type 7 or 5 and it parses as a Bitcoin transaction ≤ 4,096 bytes ("Foreign transaction message too large")

The carrier classification is also what switches the signature rule to the native path (02 §9). The message is opaque to consensus otherwise; a few types read it (an Empty transaction is "a message with no transfer").

How to compute it. LE32(len) ‖ bytes.

Rule activation. foreign_carrier_bound, active from height 0 on every chain: a native carrier's envelope carries no escrow part and expiry 0, is a SendZBC (or, for a Solana carrier, a TransferToken), and its message is the canonical byte form of the native transaction, bound to this chain and usable once by its native id (02 §9). The size limits have no rule.

Rejections and errors. As in the table; "Unexpected end of bytes (message)"; the carrier refusals of 02 §9.

Vector (computed). The §1 version-2 envelope: message length 0b000000, bytes 68656c6c6f207a6f6f6263 (hello zoobc) at offset 193. Invalid inputs (type-0 sender): the message 68 00 69 (3 bytes with a zero byte, not ZBE1) → refused "Message contains null bytes"; a plain message of 257 bytes → refused "Message exceeds maximum length of 256"; a message starting 5A424531 of 321 bytes → refused "Encrypted message too large".

Test cases · §8

5 cases · 2 valid · 3 invalid

A plain message with a zero byte is refused03-8-null-byteinvalid

Loading the test widget…

A plain message of 257 bytes is refused03-8-plain-257invalid

Loading the test widget…

A plain message of 256 bytes is accepted03-8-plain-256valid

Loading the test widget…

An encrypted (ZBE1) message of 321 bytes is refused03-8-encrypted-321invalid

Loading the test widget…

An encrypted (ZBE1) message of 320 bytes with zero bytes is accepted03-8-encrypted-320valid

Loading the test widget…

Defects to match. (1) The plain-message rule forbids 0x00 anywhere, so binary data that is not a recognised carrier or ZBE1 ciphertext must avoid zero bytes. (2) A native carrier's foreign signature does not cover the ZooBC timestamp, nor, on a Solana or Bitcoin carrier, the fee above the floor; both are chosen by whoever wraps the payload, and neither moves value (02 §9, Defects (c)).


9. The signature field, the hash and the id

Purpose. Where the signature goes and how its length is known when parsing.

Inputs. The signed envelope.

Output and effect. The signature is the last field. Its length when parsing is decided by the sender's type, and it is exactly the length that type's verifier takes (02 §2), so every sending type's envelope parses back to the bytes that were signed:

sender type signature length when parsing
1, 5, 6, 7, 14 (the carried-key field [2-byte LE key length][33- or 65-byte key][64-byte signature], 02 §4), and 8 (a script hash, cannot sign) all remaining bytes (99 with a compressed key, 131 with an uncompressed one)
9 (Taproot) all remaining bytes; its verifier then accepts only 64 (02 §6), so a longer field is refused there instead of being cut
0, 11, 12 64
4, 15 65 (r ‖ s ‖ v)
13, 16 98
3 (Estonia eID, nothing verifies it) 96
2, 10 and any unknown type (none can send) 64

A parse with "has signature" reads exactly that many bytes ("Unexpected end of bytes (signature)" if fewer remain) and ignores anything after them; a parse without a signature stops after the message. The transaction hash and id are 02 §1: SHA3-256(U ‖ signature) and the first 8 bytes as int64 LE. The parser computes the hash over all the bytes it was given, not over the bytes it consumed. Bytes after a fixed-length signature therefore give a hash and id that differ from the canonical ones (the signature check re-serialises the parsed fields), and such a transaction is refused: at admission with "Transaction ID mismatch" (04 §6 step 8), and a block that carries it is invalid.

How to compute it. Append the signature of 02 after the message.

Rule activation. None: the parser has no height. The table holds on every chain (every chain is built from 0.6.1).

Rejections and errors. The length check above; trailing bytes after a fixed-length signature ("Transaction ID mismatch"); a signature that does not verify is 02's rejection.

Vector (computed from the §1 version-3 envelope with its sender replaced; a 24-byte sender makes U 113 bytes). A Tron sender 0f000000 ‖ 682a115d32d5f6c7c0ac3d74c48099a8d83526f4 with a 65-byte signature: the signed envelope is 178 bytes and parses back with all 65 signature bytes, its hash taken over the 178; the same envelope cut to 177 bytes → "Unexpected end of bytes (signature)". A Ripple sender 0e000000 ‖ 7607d55d98d18578c275d413da80a77d529a3693 with a carried-key field of a compressed key: 113 + 99 = 212 bytes, the last 99 the signature (with an uncompressed key 244 bytes, the last 131). A Taproot sender (36 bytes, U 125 bytes) followed by 65 bytes: all 65 parse as the signature, and the verifier refuses them ("Invalid signature size for account type"). An Estonia eID sender is read with a 96-byte signature and then refused by the verifier (02 §8).

Test cases · §9

25 cases · 23 valid · 2 invalid

The signature of a native sender is read as 6403-9-siglen-0valid

Loading the test widget…

The signature of a Solana sender is read as 6403-9-siglen-11valid

Loading the test widget…

The signature of a Polkadot sender is read as 6403-9-siglen-12valid

Loading the test widget…

The signature of an Ethereum sender is read as 6503-9-siglen-4valid

Loading the test widget…

The signature of a Tron sender is read as 6503-9-siglen-15valid

Loading the test widget…

The signature of a Cardano sender is read as 9803-9-siglen-13valid

Loading the test widget…

The signature of a Tezos sender is read as 9803-9-siglen-16valid

Loading the test widget…

The signature of an Estonia eID sender is read as 9603-9-siglen-3valid

Loading the test widget…

The signature of a Bitcoin sender is read as all remaining bytes03-9-siglen-1valid

Loading the test widget…

The signature of a P2PKH sender is read as all remaining bytes03-9-siglen-5valid

Loading the test widget…

The signature of a P2SH sender is read as all remaining bytes03-9-siglen-6valid

Loading the test widget…

The signature of a P2WPKH sender is read as all remaining bytes03-9-siglen-7valid

Loading the test widget…

The signature of a P2WSH sender is read as all remaining bytes03-9-siglen-8valid

Loading the test widget…

The signature of a Ripple sender is read as all remaining bytes03-9-siglen-14valid

Loading the test widget…

The signature of a Taproot sender is read as all remaining bytes03-9-siglen-9valid

Loading the test widget…

The signature of the empty type is read as 6403-9-siglen-2valid

Loading the test widget…

The signature of a dataset address is read as 6403-9-siglen-10valid

Loading the test widget…

The signature of an unknown type is read as 6403-9-siglen-99valid

Loading the test widget…

A Tron sender's signed envelope is 178 bytes and parses back with its 65 signature bytes03-9-tron-178valid

Loading the test widget…

The same envelope cut to 177 bytes03-9-tron-177invalid

Loading the test widget…

A Ripple sender with a compressed key: 113 + 99 = 212 bytes, the last 99 the signature03-9-ripple-212valid

Loading the test widget…

With an uncompressed key: 244 bytes, the last 131 the signature03-9-ripple-244valid

Loading the test widget…

A Taproot sender followed by 65 bytes: all 65 parse as the signature03-9-taproot-65valid

Loading the test widget…

The Taproot verifier then refuses the 65 bytes03-9-taproot-65-verifyinvalid

Loading the test widget…

An Estonia eID sender is read with a 96-byte signature03-9-estonia-96valid

Loading the test widget…

Defects to match. None.


10. Wire and submission forms

Purpose. The two ways an envelope reaches a node, and what each adds or drops.

Inputs. The signed envelope, or its JSON spelling.

Output and effect.

P2P. The canonical signed envelope travels as is: in SendTransactionRequest.TransactionBytes (gossip and relay), in SendBlockTransactionsRequest.TransactionsBytes (each element one envelope), and inside the proto Transaction message's field 32 TransactionBytes (block download and block candidates). The proto Transaction also carries the named fields (version, id, block id, height, timestamp, type, fee, body length, index, multisig child, survival (field 34), expiry (field 35, uint32), sender, recipient, body, signature, hash, message) for readers that do not use field 32; the expiry is read from field 35 only for version 3 and is 0 otherwise, as the survival is only for versions 2 and 3; a receiver that finds field 32 parses it and takes the sending node's TransactionHash (field 10) as the hash when present, ignoring the named fields; one that finds no field 32 rebuilds the transaction from the named fields, which cannot carry an escrow, so an escrow-bearing transaction sent that way fails its signature check on every node. A bare 32-byte sender or recipient, or a full-key form, in the named fields is kept as sent and refused by name at validation (§3). The proto message and the RPCs are 27.

HTTP API. POST /api/v1/transactions with a JSON object; the node builds the envelope from it, hashes it, and admits or refuses. Fields (all others are ignored):

field type meaning
version integer, default 1 envelope version
timestamp integer, default 0 Unix seconds
transaction_type integer, default 0 type id
fee integer, default 0 atomic units
survival integer or decimal string, default 0 version-2 and version-3 survival; non-zero on a version-1 transaction is refused by the reader
expiry integer or decimal string, default 0 version-3 expiry window in seconds, 0 to 86,400; refused by the reader outside that range, and refused by the reader when non-zero on a version 1 or 2 transaction, before the hash is computed
sender_account_address hex (optional 0x), may be empty the typed account bytes; a bare 32-byte key is refused (below)
recipient_account_address hex, may be empty or absent empty means no recipient
transaction_body_bytes hex, may be empty the body
signature hex, required, non-empty the signature
message_hex hex the message bytes; takes precedence over message
message string the message as UTF-8 text
escrow object or null approver_address (hex, required), timeout (integer, required), commission (integer), instruction (string), multi_party (boolean), co_signer_signature (hex), escrow_request_id (integer or decimal string)

The reader accepts any JSON integer for version and transaction_type and truncates it to the field width (a version outside uint8 is written as its low byte); this is the node's API input handling (31), not an envelope rule.

An integer field given as a float, string, boolean or object is refused by name ("field 'fee' must be an integer"); an expiry outside 0 to 86,400 is "expiry must be between 0 and 86400 seconds"; a non-zero expiry below version 3 is "expiry needs transaction version 3: a version-N transaction carries no expiry (its signed bytes have no place for one)", and a non-zero survival on version 1 is "survival needs transaction version 2 or 3: a version-1 transaction carries no survival (its signed bytes have no place for one)" (both HTTP 400, also for a transaction the node already holds); a bare 32-byte sender or recipient is refused when the envelope is built, HTTP 400 "Invalid transaction: accounts are typed: a bare 32-byte key is not an account on this chain"; a hex field with an odd number of digits or a non-hex character is refused ("field 'signature' must be an even number of hex characters"); a missing signature is "field 'signature' is required". The reply on acceptance is HTTP 202 with {"status":"success","duplicate":false,"state":"new","message":"Transaction submitted successfully","transaction_hash":"<hex>"}; a transaction the node already holds answers 202 with "duplicate":true,"state":"pending", and so does a foreign carrier whose native id a transaction the node holds already carries (a second envelope around one native transaction, 02 §9 step 6, 04 §6: the reply names the new hash, which is not staged); one already mined answers 202 with "duplicate":true,"state":"confirmed","block_height":N and the message "Transaction already confirmed at height N - not resubmitted". A refusal is HTTP 400 {"success":false,"error":"Transaction validation failed: <reason>","code":400} (or "Invalid transaction: …" when the envelope cannot be built); a node under load answers 503. Before admission the node re-parses the envelope it built ("the transaction bytes do not parse: …" on failure) so that the checks see the canonical typed addresses. There is no raw-bytes submission endpoint on the node API; the raw form exists only on the P2P wire.

Block placement fields. id, block_id, height, transaction_index and multisig_child describe where a mined transaction sits; they are not envelope fields, are not signed, and are carried only in the proto's named fields and in state (07, 21).

How to compute it. Build the envelope from the JSON exactly as §1 (a bare 32-byte sender or recipient is refused; an empty recipient becomes the marker).

Rule activation. None.

Rejections and errors. As above.

Vector (computed; this is the payload the reference's zbc-cli send-zbc --offline prints for the §1 version-3 envelope). {"version":3,"timestamp":1793509627,"sender_account_address":"000000005e8eb28dccaa94a992f7169fa67966207d96aa55df7d24d2d6ec1f538c9f2152","recipient_account_address":"00000000fd4472bbdec43b919aa37b9b3366a3318f2902a753a15f5fd6d43c44b5121b67","transaction_type":1,"fee":5000000,"survival":0,"expiry":7200,"transaction_body_bytes":"00e1f50500000000","signature":"f0fc0b05…a406"} yields the 125-byte unsigned envelope of §1 and the hash 058c3078…e467; a node whose genesis hash is the vectors' G (02 §1) answers a first submission HTTP 202 with "duplicate":false,"state":"new" and that hash (I think; the vector was not submitted, the account is unfunded). The same JSON with the sender written as the bare 32 bytes 5e8eb28d…2152 is refused HTTP 400 "Invalid transaction: accounts are typed: a bare 32-byte key is not an account on this chain".

Test cases · §10

5 cases · 1 valid · 4 invalid

The JSON submission of the version-3 envelope03-10-json-v3valid

Loading the test widget…

The same JSON with a bare 32-byte sender is refused03-10-json-bareinvalid

Loading the test widget…

A fee written as a float is refused by name03-10-json-fee-floatinvalid

Loading the test widget…

A signature with an odd number of hex digits is refused03-10-json-odd-hexinvalid

Loading the test widget…

A submission without a signature is refused03-10-json-no-signatureinvalid

Loading the test widget…

Defects to match. None.


11. Parsing an envelope

Purpose. The exact procedure that turns bytes into fields, so that two implementations agree on every malformed input too.

Inputs. The bytes; whether a signature is expected.

Output and effect. The fields, the hash and the id; or one of the errors below. Procedure:

  1. Fewer than 29 bytes: "Transaction bytes too short".
  2. type = uint32 LE at 0; version = byte 4; timestamp = int64 LE at 5. Offset 13.
  3. Sender: need 4 bytes ("Unexpected end of bytes (sender type)"); read the type; if it is 2, advance 4 and the sender is empty; else the address is 4 + length(type) bytes ("… (sender address)" if short).
  4. Recipient: the same ("… (recipient type)", "… (recipient address)").
  5. fee = int64 LE, 8 bytes ("… (fee)").
  6. If version ≥ 2: survival = int64 LE, 8 bytes ("… (survival)"); else survival = 0. If version ≥ 3: expiry = uint32 LE, 4 bytes ("Unexpected end of bytes (expiry)"); else expiry = 0.
  7. body_length = uint32 LE ("… (body length)"); body = that many bytes ("… (body)").
  8. Escrow: read 4 bytes as the approver type ("… (escrow approver type)" if short); if 2, advance 4 and there is no escrow; otherwise try the §7 layout; on success attach it; on any failure keep the offset where the failure left it and continue without an escrow.
  9. message_length = uint32 LE ("… (message length)"); message = that many bytes ("… (message)").
  10. If a signature is expected: length by the sender type as in §9; read it ("… (signature)").
  11. hash = SHA3-256(all input bytes); id = int64 LE(hash[0..8]).

How to compute it. As above, with no step reordered.

Rule activation. None.

Rejections and errors. The quoted strings; the API prefixes them with "the transaction bytes do not parse: ".

Vector (computed). §1's three envelopes parse to the fields shown. Invalid inputs: the first 28 bytes of the §1 version-3 envelope → "Transaction bytes too short"; the first 100 bytes of it (cut inside the survival field) → "Unexpected end of bytes (survival)"; the 125 unsigned bytes parsed with a signature expected → "Unexpected end of bytes (signature)".

Test cases · §11

6 cases · 3 valid · 3 invalid

Read the signed version-3 envelope back03-11-parse-signedvalid

Loading the test widget…

28 bytes are too short03-11-too-shortinvalid

Loading the test widget…

Cut inside the survival field03-11-cut-survivalinvalid

Loading the test widget…

The unsigned bytes read with a signature expected03-11-no-signatureinvalid

Loading the test widget…

Read the unsigned version-2 envelope back03-11-parse-v2valid

Loading the test widget…

Read the 77-byte envelope with an empty recipient back03-11-parse-empty-recipientvalid

Loading the test widget…

Defects to match. Steps 8 and 10–11 as described in §7 and §9. Note also that step 8, on a failure inside the escrow part, leaves the offset after the bytes it consumed before failing (the reference advances offset field by field), so the message length is then read from the middle of the escrow data; an implementation must advance identically to produce the same error or the same (wrong) fields.


12. What makes a well-formed envelope unacceptable

Purpose. Collect, in the order the reference applies them, the envelope-level refusals that are not type-specific, so that an implementation refuses the same transactions for the same first reason.

Inputs. A parsed transaction and the height it is judged at (04 explains "the height it is judged at").

Output and effect. A bare 32-byte sender or recipient is refused first (§3); then the signature is checked (02); then, in this order (the stateless step that block validation also runs): the Ethereum recovery id of a type-4 or type-15 sender that is not an Ethereum carrier (02 §5); the bare-key check again; a full-key sender, recipient or escrow approver (§3); version, expiry and survival (§4); timestamp positive (§5); type retired, then type not yet active (§2); the survival-mode freeze of the governance and bridge categories (§2, 04); sender present and sized (§3); SendZBC recipient present, sized and shaped (§3); other recipients shaped (rule recipient_address_shape) and, for LiquidPayment, ScheduledTransfer and CreateTrigger, of a spendable type (§3); message rules, the carrier/survival rule and the carrier binding (§8, §4, 02 §9); escrow instruction limit, approver able to sign, escrow timeout, the escrow timeout cap, escrow-capable type, commission sign and overflow, multi-party rules (§7); body length (§6); fee (04); then the type's own validation (family documents; a batch's empty envelope recipient is checked there). The in-block timestamp bounds (§5) are checked by block validation, not here.

How to compute it. Apply the checks in that order and stop at the first failure.

Rule activation. As in the sections referenced.

Rejections and errors. As in the sections referenced.

Vector (computed). Input: the §1 version-2 envelope with its sender written as the bare 32 bytes and, in addition, version 2 with expiry 5 → expected: the first refusal is accounts are typed: a bare 32-byte key is not an account on this chain. Input: the §1 version-2 envelope (typed sender) with expiry 5 and a valid signature over that object → "A version-2 transaction carries no expiry; use transaction version 3". Input: the §1 version-3 envelope with fee 0 and a sender that is not a node's fee-free duty → "Transaction fee too low" (04).

Test cases · §12

3 cases · 3 invalid

A bare sender and an expiry on a version-2 transaction: the bare sender is refused first03-12-first-bareinvalid

Loading the test widget…

A typed sender and an expiry on a version-2 transaction: the expiry is refused03-12-first-expiryinvalid

Loading the test widget…

The version-3 envelope with fee 0 from an ordinary sender03-12-fee-zeroinvalid

Loading the test widget…

Defects to match. The order matters only for which error string a client sees; every listed condition is a refusal regardless of order.

A question about this chapter, or a statement that does not match the network? Discuss on zoobc.pro.