On this page
- §0 The area in one paragraph
- 1. The envelope byte layout
- 2. Transaction type identifiers
- 3. Sender and recipient
- 4. Version, fee, survival and expiry
- 5. Timestamp
- 6. The body
- 7. The escrow part
- 8. The message
- 9. The signature field, the hash and the id
- 10. Wire and submission forms
- 11. Parsing an envelope
- 12. What makes a well-formed envelope unacceptable
03 — The transaction envelope
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 envelope
Loading the test widget…
A version-2 SendZBC with survival, an escrow and a message
Loading the test widget…
Sign the version-2 envelope
Loading the test widget…
An envelope with an empty recipient (type 3, 77 bytes)
Loading the test widget…
Sign the version-3 envelope: signature and hash
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 02010000
Loading the test widget…
Type 770 is written as 02030000
Loading the test widget…
Type 309 is written as 35010000
Loading the test widget…
Type 60 is written as 3c000000
Loading the test widget…
Type 61 is written as 3d000000
Loading the test widget…
Type 62 is written as 3e000000
Loading the test widget…
Type 257 is written as 01010000
Loading the test widget…
Type 267 is written as 0b010000
Loading the test widget…
Type 297 is written as 29010000
Loading the test widget…
An envelope of type 53 (CancelLongevity) is refused on every chain
Loading the test widget…
An envelope of the unknown type 999 still parses (the body is opaque)
Loading the test widget…
Validation refuses the unknown type 999 once the fee check has passed
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 (rulecanonical_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 beginsZBW1|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 examplethe 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 (rulerecipient_address_shape). A LiquidPayment, ScheduledTransfer or CreateTrigger whose envelope recipient is a type nobody can spend from (outside the signing list of01§4, aZBS_dataset address excepted; Taproot under ruletaproot_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).
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 refused
Loading the test widget…
A bare 32-byte sender is the first refusal of validation
Loading the test widget…
A SendZBC to a recipient of the unknown type 99 is refused
Loading the test widget…
A SendZBC with an empty recipient is refused
Loading the test widget…
A 20-byte sender is refused
Loading the test widget…
A SendZBC whose recipient is a 68-byte full-key form is refused
Loading the test widget…
The same SendZBC to the 24-byte Ethereum account of that key passes
Loading the test widget…
An escrow approver in a full-key form is refused the same way
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 isTRANSACTION_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
int64of atomic units; what it must be at least is04's business; what survival buys is13'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 checks
Loading the test widget…
The version-2 envelope (survival of exactly the minimum deposit) passes
Loading the test widget…
A version-3 expiry of 90,000 s is over the cap
Loading the test widget…
A version-1 transaction with a survival is refused
Loading the test widget…
A survival below the minimum deposit is refused
Loading the test widget…
A negative survival is refused
Loading the test widget…
Version 4 is not a transaction version
Loading the test widget…
A version-2 JSON submission with expiry 5 is refused before the hash
Loading the test widget…
A version-3 JSON submission with expiry 90,000 is refused before the hash
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 timestamp
Loading the test widget…
One second later the block would carry an expired transaction
Loading the test widget…
The version-2 envelope may be carried until 3,600 s after its timestamp
Loading the test widget…
A block stamped one second later carrying it is invalid
Loading the test widget…
The version-3 envelope in a block stamped 3,601 s before it is refused
Loading the test widget…
A timestamp of 0 is refused
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 bytes
Loading the test widget…
A body of 65,537 bytes is refused
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 refused
Loading the test widget…
The version-2 escrow part with commission ffffffffffffffff (-1) is refused
Loading the test widget…
An escrow on a dataset transaction is refused
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 refused
Loading the test widget…
A plain message of 257 bytes is refused
Loading the test widget…
A plain message of 256 bytes is accepted
Loading the test widget…
An encrypted (ZBE1) message of 321 bytes is refused
Loading the test widget…
An encrypted (ZBE1) message of 320 bytes with zero bytes is accepted
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 64
Loading the test widget…
The signature of a Solana sender is read as 64
Loading the test widget…
The signature of a Polkadot sender is read as 64
Loading the test widget…
The signature of an Ethereum sender is read as 65
Loading the test widget…
The signature of a Tron sender is read as 65
Loading the test widget…
The signature of a Cardano sender is read as 98
Loading the test widget…
The signature of a Tezos sender is read as 98
Loading the test widget…
The signature of an Estonia eID sender is read as 96
Loading the test widget…
The signature of a Bitcoin sender is read as all remaining bytes
Loading the test widget…
The signature of a P2PKH sender is read as all remaining bytes
Loading the test widget…
The signature of a P2SH sender is read as all remaining bytes
Loading the test widget…
The signature of a P2WPKH sender is read as all remaining bytes
Loading the test widget…
The signature of a P2WSH sender is read as all remaining bytes
Loading the test widget…
The signature of a Ripple sender is read as all remaining bytes
Loading the test widget…
The signature of a Taproot sender is read as all remaining bytes
Loading the test widget…
The signature of the empty type is read as 64
Loading the test widget…
The signature of a dataset address is read as 64
Loading the test widget…
The signature of an unknown type is read as 64
Loading the test widget…
A Tron sender's signed envelope is 178 bytes and parses back with its 65 signature bytes
Loading the test widget…
The same envelope cut to 177 bytes
Loading the test widget…
A Ripple sender with a compressed key: 113 + 99 = 212 bytes, the last 99 the signature
Loading the test widget…
With an uncompressed key: 244 bytes, the last 131 the signature
Loading the test widget…
A Taproot sender followed by 65 bytes: all 65 parse as the signature
Loading the test widget…
The Taproot verifier then refuses the 65 bytes
Loading the test widget…
An Estonia eID sender is read with a 96-byte signature
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 envelope
Loading the test widget…
The same JSON with a bare 32-byte sender is refused
Loading the test widget…
A fee written as a float is refused by name
Loading the test widget…
A signature with an odd number of hex digits is refused
Loading the test widget…
A submission without a signature is refused
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:
- Fewer than 29 bytes: "Transaction bytes too short".
type=uint32 LEat 0;version= byte 4;timestamp=int64 LEat 5. Offset 13.- 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). - Recipient: the same ("… (recipient type)", "… (recipient address)").
fee=int64 LE, 8 bytes ("… (fee)").- If
version ≥ 2:survival=int64 LE, 8 bytes ("… (survival)"); else survival = 0. Ifversion ≥ 3:expiry=uint32 LE, 4 bytes ("Unexpected end of bytes (expiry)"); else expiry = 0. body_length=uint32 LE("… (body length)"); body = that many bytes ("… (body)").- 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.
message_length=uint32 LE("… (message length)"); message = that many bytes ("… (message)").- If a signature is expected: length by the sender type as in §9; read it ("… (signature)").
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 back
Loading the test widget…
28 bytes are too short
Loading the test widget…
Cut inside the survival field
Loading the test widget…
The unsigned bytes read with a signature expected
Loading the test widget…
Read the unsigned version-2 envelope back
Loading the test widget…
Read the 77-byte envelope with an empty recipient back
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 first
Loading the test widget…
A typed sender and an expiry on a version-2 transaction: the expiry is refused
Loading the test widget…
The version-3 envelope with fee 0 from an ordinary sender
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.