On this page
  1. §0 The area in one paragraph
  2. 1. The token row, the balances and the asset kinds
  3. 2. The symbol and name rules
  4. 3. IssueToken (10)
  5. 4. TransferToken (11)
  6. 4a. TransferTokenBatch (267)
  7. 5. A fee paid in the token
  8. 6. MintToken (12)
  9. 7. BurnToken (13)
  10. 8. FinanceToken (14)
  11. 9. Persistence and expiry, as the operations see them
  12. 10. Ledger rows, API views and the consensus/local split

14 — Tokens: IssueToken, TransferToken, MintToken, BurnToken, FinanceToken

Edition 0.6.1 · verified against the reference implementation, version 0.6.1

Out of scope the fee floor, the refund and the reward pool (04, 21); the genesis token set and its balances (06); the longevity side of persistence and the expiry payout to holders (13 §10); the exchange (15); the apps pool's token stakes (16); account groups as holders (18); split and transact policies (08); the bridge's own mint and burn of wrapper tokens (34); the token icon namespace of the datasets (10)

§0 The area in one paragraph

A token is a row keyed by a 64-bit id: issuer, symbol, name, decimals, total supply, a ZBC backing and four flag bits, plus the persistence height of 13. Every balance of every asset counts in atomic units of 10⁻⁸: ZBC (id 0) is not a token row, the fourteen genesis coins (ids 1–14) are rows written by block 0 that nobody can mint, burn or expire, and a user token is created by an IssueToken, whose id is the first eight bytes of its transaction hash. decimals is not a scale: it declares how many of the eight places are visible, and every amount that moves a token must be a multiple of the step 10^(8−decimals). The issuer's declared backing leaves its balance into the row; it comes back only pro rata to a BurnToken (if the token is redeemable), as the ZBC a fee paid in the token releases, or to the holders when the token expires. A TransferTokenBatch moves several tokens to several recipients in one transaction, all or nothing. A mintable token lets its issuer add supply at the same backing ratio, rounded against the minter. Every token operation is a paid no-op when the token has expired or the sender's units are gone, and a hard refusal (the block is invalid) only for faults every node computes identically. A token's name may not read as an account address, and units are only ever sent to an account of a kind that can sign. Every token transaction inherits the fee rules of 04 through its "Then 04 §5": the fee floor (persistence rent × active-registry size, every stage rounded up), the refund of the overpay above it (event 22), and the coinbase lottery that every fee kept goes to (21 §2). A fee paid in the token settles the floor out of the token's backing even when the transfer becomes a no-op, and when the backing cannot settle it the sender pays the floor in ZBC: nothing on the chain is free.

1. The token row, the balances and the asset kinds

Purpose. The state every mechanism below reads and writes.

Inputs. Block 0 (06), IssueToken and the operations below.

Output and effect. token(token_id, issuer_address, symbol, name, decimals, total_supply, backing_asset, backing_amount, flags, persist_height, block_height, latest), key token_id, versioned (07 §2); backing_asset is always 0 (ZBC). account_token_balance(account_address, token_id, balance, spendable_balance, block_height, latest), key (account_address, token_id), versioned; spendable_balance is written equal to balance on every write: token balances have no reserve, no hold and no admission reservation. Types: token_id signed 64-bit; issuer_address and account_address typed account bytes (01); symbol and name byte strings as given; decimals and flags 0…255; total_supply, backing_amount, balance, spendable_balance signed 64-bit; backing_asset signed 64-bit (always 0); persist_height and block_height unsigned 32-bit; latest 0/1. Reads: "the token" at height h is the row of token_id with the greatest block_height ≤ h (the newest row when no height is given); a balance is the row of (account, token_id) with latest 1, 0 when none. A write appends a version at the block's height (07 §2); a rollback to H deletes the rows above H. A holder address is stored canonical and, for a group member, is its group (18). A token credit to an account applies the recipient's split policy before the units arrive (08); a debit never does.

Kind id Row Mint / burn Expiry
ZBC 0 none; the account balance (07) never never
genesis coin 1…14 on every chain (both live genesis files) written by block 0: decimals 8, backing 0, flags 8, persist_height 0, issuer = the configured holder mint mode 0, not redeemable → every MintToken and BurnToken on it is refused at admission and a paid no-op if mined never (a FinanceToken on it is refused, §8)
user token LE i64 of the first 8 bytes of the IssueToken's hash, 1 when that is 0 §3 by its flags §9

flags: bit 0 redeemable; bits 1–2 mint mode, 0 fixed supply, 1 mintable (2 and 3 are refused at admission; the executor treats anything but 1 as not mintable); bit 3 "unbacked", stored and reported verbatim, never read by any rule; bits 4–7 stored, never read. step = 10^(8−decimals) for decimals 0…7, 1 for 8.

How to compute it. As stated. A token id is printed as a signed decimal string in every API view; amount_step in the views is the step.

Rule activation. None.

Rejections and errors. None.

Vector. computed (from the TestNet genesis file, 06 §3: a genesis coin's total_supply is the sum of its allocations and every account's balance of it, the apps treasury's balance not counted; its issuer is the first allocation holder, else the first entry of accounts, the treasury 00000000120EE4CA…E807).

  • Input: GET /api/v1/tokens/1 at height 12,490.
  • Expected output: {"token_id":"1","issuer":"00000000120ee4ca9d258d75656901ec4837373e07763369ad75ed8d63fa31c7e0b7e807","symbol":"ZUSD","name":"Zoo US Dollar","decimals":8,"amount_step":1,"total_supply":450000000000000,"backing_asset":0,"backing_amount":0,"redeemable":0,"mintable":0,"unbacked":1,"persist_height":0,"current_height":12490} (flags 8: bit 3 "unbacked" set, not redeemable, mint mode 0).
  • GET /api/v1/tokens before any IssueToken: 14 rows, ids 1–14 ZUSD ZEUR ZCNY ZBTC ZETH ZSOL ZDOT ZBNB ZADA ZXRP ZTRX ZXTZ ZUSDC ZUSDT, all with decimals 8, step 1, backing 0, issuer the treasury, persist_height 0; supplies 450,000,000,000,000 (ZUSD, ZEUR, ZCNY, ZADA, ZXRP, ZTRX), 45,000,000,000 (ZBTC), 450,000,000,000 (ZETH, ZBNB), 4,500,000,000,000 (ZSOL, ZDOT), 45,000,000,000,000 (ZXTZ, ZUSDC, ZUSDT). The DevNet genesis file allocates the same supplies.
  • computed (the step): decimals 0 → 100,000,000; 2 → 1,000,000; 7 → 10; 8 → 1.

Test cases · §1

6 cases · 6 valid · 2 reference

The genesis coin ZUSD as the token view reports it, from the TestNet genesis file14-1-zusdvalidreference

A stated value: there is nothing to compute. A compatible node shows the same value.

value
{"token_id":"1","issuer":"00000000120ee4ca9d258d75656901ec4837373e07763369ad75ed8d63fa31c7e0b7e807","symbol":"ZUSD","name":"Zoo US Dollar","decimals":8,"amount_step":1,"total_supply":450000000000000,"backing_asset":0,"backing_amount":0,"redeemable":0,"mintable":0,"unbacked":1,"persist_height":0,"current_height":12490}
The fourteen genesis coins of the TestNet genesis file14-1-genesis-listvalidreference

The DevNet genesis file allocates the same supplies.

A stated value: there is nothing to compute. A compatible node shows the same value.

ids
1-14
symbols
ZUSD ZEUR ZCNY ZBTC ZETH ZSOL ZDOT ZBNB ZADA ZXRP ZTRX ZXTZ ZUSDC ZUSDT
decimals
8
step
1
backing_amount
0
persist_height
0
supplies
450000000000000 (ZUSD ZEUR ZCNY ZADA ZXRP ZTRX), 45000000000 (ZBTC), 450000000000 (ZETH ZBNB), 4500000000000 (ZSOL ZDOT), 45000000000000 (ZXTZ ZUSDC ZUSDT)
issuer
00000000120ee4ca9d258d75656901ec4837373e07763369ad75ed8d63fa31c7e0b7e807
The step of a token with 0 decimals14-1-step-0valid

Loading the test widget…

The step of a token with 2 decimals14-1-step-2valid

Loading the test widget…

The step of a token with 7 decimals14-1-step-7valid

Loading the test widget…

The step of a token with 8 decimals14-1-step-8valid

Loading the test widget…

Defects to match. (1) Symbols are not unique: nothing compares a new token's symbol with the existing rows, so two IssueTokens with one symbol both create a token. (2) A token lookup without a height returns the latest row even when the token has expired; the operations test expiry themselves.

2. The symbol and name rules

Purpose. What an IssueToken may call its token.

Inputs. The symbol and name bytes of the body.

Output and effect. Symbol: 2 to 10 bytes, each A–Z or 0–9; refused when reserved: length 4 or 5 and the first or the last byte is Z (the bridge namespace: ZBTC, BTCZ, …); refused when blocked (compared after upper-casing, which the charset already forces):

USD EUR CNY CNH JPY GBP CHF AUD CAD HKD SGD KRW INR BRL RUB ZAR MXN
USDT USDC DAI BUSD TUSD USDP GUSD USDD FRAX PYUSD FDUSD USDE USDS LUSD EURC EURT EUROC USTC
BTC ETH BNB SOL XRP ADA DOGE TRX DOT MATIC POL LTC BCH AVAX SHIB LINK XLM ATOM XMR ETC XTZ FIL
HBAR ICP APT NEAR ARB OP UNI AAVE MKR ALGO VET GRT TON SUI SEI TIA INJ RUNE KAS LDO CRV

Name: 1 to 64 bytes of well-formed UTF-8 (no overlong form, no surrogate, nothing above U+10FFFF); none of < > " ' `; no code point in U+0000–001F, U+007F–009F, U+00AD, U+061C, U+180E, U+200B–200F, U+2028–202E, U+2060–2064, U+2066–2069, U+FEFF, U+FFF9–FFFB, U+E0000–E007F; no space other than U+0020 (so none of U+00A0, U+1680, U+2000–200A, U+202F, U+205F, U+3000); no leading or trailing U+0020. Byte rules only: no normalisation, no case folding. Last (rule token_name_not_address), the name is refused when it reads as an account address: when the node's own address-text parser (01) accepts it, whatever kind it decodes to (the native ZBC_ / ZBS_ text forms with or without the _ separators, Ethereum 0x…, every Bitcoin form, Solana base58, Polkadot SS58, Cardano addr1…, Ripple, Tron, Tezos, and a bare 64-hex key), or when the name, after removing one leading 0x or 0X (only when more characters follow), is exactly 72 hexadecimal digits (a typed account in hex). What counts as an address is decided by the parser, not by a pattern: an implementation runs its own address parser of 01 over the name.

How to compute it. As stated, in that order; the first violated rule names the reason.

Rule activation. token_name_shape (the name rule at admission; the executor applies the shape at every height) and token_name_not_address (the address check, at admission and at execution), both height 0. The symbol rules are unconditional at both.

Rejections and errors. Admission: "Invalid token symbol (must be uppercase A-Z/0-9, length 2-10): S", "Reserved token symbol (bridge namespace): S", "Blocked token symbol (well-known asset, cannot be impersonated): S", "Invalid token name: <reason>" with reasons name is empty, name is longer than 64 bytes, name has a leading or trailing space, name is not valid UTF-8, name contains one of < > " ' `` ``, name contains a control, zero-width or bidi character, name contains a space other than U+0020, name is an account address (the name is never echoed). Execution (block invalid): "Invalid token symbol (uppercase A-Z/0-9, length 2-10): S", "Reserved token symbol (bridge namespace): S", "Blocked token symbol (well-known asset): S", "Invalid token name: <reason>".

Vector. computed (each input is an IssueToken symbol or name; expected = accepted, or the admission refusal).

  • PQLQ, D214252, ZABCDE (6 bytes) → accepted.
  • ZUSD1 → "Reserved token symbol (bridge namespace): ZUSD1"; ABCZ → "Reserved token symbol (bridge namespace): ABCZ".
  • usdc → "Invalid token symbol (must be uppercase A-Z/0-9, length 2-10): usdc"; USDC → "Blocked token symbol (well-known asset, cannot be impersonated): USDC"; A → the charset text; a zero-length symbol (slen 0) → "Invalid token symbol (must be uppercase A-Z/0-9, length 2-10): " (the symbol echoed empty), at admission and in block validation alike.
  • Name Dust Two → accepted. Name of 65 × a → "Invalid token name: name is longer than 64 bytes". Name Dust → "Invalid token name: name has a leading or trailing space". Name a<b → "Invalid token name: name contains one of < > \" ' `` ``". Name bytes 44 75 E2 80 8B 73 74(a U+200B inside) →"Invalid token name: name contains a control, zero-width or bidi character". Name bytes C0 80→"Invalid token name: name is not valid UTF-8"` (overlong).
  • Names ZBCCIHOJSU5EWGXKZLJAHWEQNZXHYDXMM3JVV263DLD7IY4PYFX5ADSND7R (no separators, 59 bytes) and 120ee4ca9d258d75656901ec4837373e07763369ad75ed8d63fa31c7e0b7e807 (64 hex) → each "Invalid token name: name is an account address", at admission and at execution. The names ZBC_CIHOJSU5_EWGXKZLJ_AHWEQNZX_HYDXMM3J_VV263DLD_7IY4PYFX_5ADSND7R (66 bytes) and 0x00000000120ee4ca9d258d75656901ec4837373e07763369ad75ed8d63fa31c7e0b7e807 (74 bytes) meet the length rule first: "Invalid token name: name is longer than 64 bytes" (a name of 72 hexadecimal digits is always longer than 64 bytes, so the typed-hex test never decides a name).

Test cases · §2

19 cases · 4 valid · 15 invalid

The symbol PQLQ is accepted14-2-sym-pqlqvalid

Loading the test widget…

The symbol D214252 is accepted14-2-sym-d214252valid

Loading the test widget…

The symbol ZABCDE is accepted14-2-sym-zabcdevalid

Loading the test widget…

ZUSD1 is in the bridge namespace14-2-sym-bad-zusd1invalid

Loading the test widget…

ABCZ is in the bridge namespace14-2-sym-bad-abczinvalid

Loading the test widget…

A lower-case symbol is refused14-2-sym-bad-lower-usdcinvalid

Loading the test widget…

USDC is a blocked symbol14-2-sym-bad-usdcinvalid

Loading the test widget…

A one-letter symbol is refused14-2-sym-bad-ainvalid

Loading the test widget…

A zero-length symbol is refused statelessly, the symbol echoed empty14-2-sym-emptyinvalid

Loading the test widget…

The name Dust Two is accepted14-2-name-okvalid

Loading the test widget…

A 65-byte name is refused14-2-name-65invalid

Loading the test widget…

A leading space is refused14-2-name-spaceinvalid

Loading the test widget…

A < in the name is refused14-2-name-markupinvalid

Loading the test widget…

A zero-width space is refused14-2-name-zwspinvalid

Loading the test widget…

An overlong UTF-8 form is refused14-2-name-overlonginvalid

Loading the test widget…

A ZBC address with separators (66 bytes) is not a name14-2-name-zbcinvalid

Loading the test widget…

A ZBC address without separators is not a name14-2-name-zbc-bareinvalid

Loading the test widget…

A 64-hex key is not a name14-2-name-hex64invalid

Loading the test widget…

A typed account in hex after 0x (74 bytes) is not a name14-2-name-hex72invalid

Loading the test widget…

Defects to match. None. (The symbol rules run whenever the body holds slen bytes after offset 20, a zero-length symbol included, so an IssueToken with an empty symbol is refused at admission and makes a block invalid, never a failed candidate.)

3. IssueToken (10)

Purpose. Create a user token and give its issuer the whole supply.

Inputs. The body; tx.recipient is ignored.

Offset Length Field Encoding
0 1 decimals u8, 0…8
1 1 flags u8 (§1)
2 8 total_supply i64 LE, > 0, multiple of the step
10 8 backing_amount i64 LE, ≥ 0, ZBC atomic
18 2 slen u16 LE
20 slen symbol bytes (§2)
20+slen 2 nlen u16 LE
22+slen nlen name bytes (§2)
22+slen+nlen 8 (optional) survival payment i64 LE ≥ 0 (13 §10); absent = 0; anything after it is ignored

Output and effect. The sender's balance −(backing + fee) in one debit (unaffordable → paid no-op: the fee is charged, nothing else); rows event 1 −fee and event 52 −backing (no row for a zero amount); the survival payment is debited separately (row event 45; unaffordable → nothing moves and it buys nothing); the token row: token_id from the hash (§1), issuer = the sender as the dispatcher presents it (an enabled member's group, 08, 18), symbol, name, decimals, supply, backing_asset 0, backing, flags verbatim, persist_height = height + free blocks + bought blocks, capped at 2³²−1, at least height + 1 (13 §10); the sender's balance of the token = total_supply (a group member's group, 18). Then 04 §5. The backing is not an account: it is a number in the row, and the ZBC it holds is in no balance.

How to compute it. Stateless (admission and block validation, every height): the length walk ("IssueToken body too short (header)", … (supply), … (backing), … (symbol length), "IssueToken symbol truncated", … (name length), "IssueToken name truncated"); "Token supply must be positive"; "Token decimals must be 0..8"; "Token mint mode must be 0 (fixed supply) or 1 (mintable); flags bits 1-2 had an undefined value"; "Token supply is finer than the declared decimals allow"; the symbol and name rules of §2; "Token survival payment cannot be negative" (payment with the top bit set). Admission only (state): backing ≥ 0 ("IssueToken: backing cannot be negative"), "IssueToken: backing + fee overflow", spendable ≥ backing + fee ("IssueToken: declared ZBC backing is more than the account holds — backing is real collateral, locked until the token expires (need N atomic incl. fee, have H)"). Execution (block invalid): "Invalid IssueToken body", the §2 texts ("Invalid token name: name is an account address" included), "Token supply must be positive", "Invalid token parameters" (backing < 0, decimals outside 0…8, fee < 0), "Token supply is finer than the declared decimals allow", "Token already exists", "Backing + fee overflow".

Rule activation. token_name_shape (admission), token_name_not_address, uniform_fee_refund, state_answer_noop (height 0).

Rejections and errors. As listed.

Vector. computed (TestNet: free period 172,800, cost 10,000,000 per 172,800 blocks).

  • Input: IssueToken (type 10) at height h, fee F, body (43 bytes) 020800E1F505000000000000000000000000050044555354320800447573742054776F00E1F50500000000 = decimals 2, flags 8, supply 100,000,000, backing 0, symbol DUST2, name Dust Two, survival payment 100,000,000; the transaction's hash begins ABCCD7C45A2A4E43.
  • Expected output: token id 4,849,860,418,062,503,083 (the LE i64 of ABCCD7C45A2A4E43); the row: issuer = the sender, DUST2, Dust Two, decimals 2, supply 100,000,000, backing 0, flags 8, persist_height = h + 172,800 + (100,000,000 div 10,000,000) × 172,800 = h + 1,900,800; the issuer's DUST2 balance 100,000,000 (1.00 at two decimals); rows on the sender: event 1 −F, event 45 −100,000,000; on ZBCLONGV: event 50 +100,000,000. On DevNet (240 free, 100,000,000 per 240) persist_height = h + 480.
  • Invalid input: the same body with supply 100,000,001 (020801E1F505000000000000000000000000050044555354320800447573742054776F00E1F50500000000) → "Token supply is finer than the declared decimals allow" (stateless: refused at admission, makes a block invalid). A body of 1 byte → "IssueToken body too short (header)". Decimals 9 → "Token decimals must be 0..8". Flags 4 (mint mode 2) → "Token mint mode must be 0 (fixed supply) or 1 (mintable); flags bits 1-2 had an undefined value".

Test cases · §3

6 cases · 2 valid · 4 invalid

IssueToken DUST2 at height 12,500 with a survival payment of 1 ZBC14-3-dust2valid

Loading the test widget…

The same IssueToken on DevNet at height 12,50014-3-dust2-devnetvalid

Loading the test widget…

A supply of 100,000,001 is finer than two decimals allow14-3-finer-supplyinvalid

Loading the test widget…

A one-byte IssueToken body14-3-one-byteinvalid

Loading the test widget…

Nine decimals are refused14-3-decimals-9invalid

Loading the test widget…

Mint mode 2 is undefined14-3-mint-mode-2invalid

Loading the test widget…

Defects to match. (1) The executor's refusal of an id already in use ("Token already exists", block invalid) is not mirrored at admission. The token id is the IssueToken's own transaction id, and a repeated transaction id is refused as a duplicate before execution, so the refusal is reachable only once the earlier IssueToken's transaction row has been pruned from the transaction table. (2) The backing is not reserved at admission; a sender who spends it earlier in the same block gets a mined no-op that still pays the fee. (3) For an enabled group member the sender every token executor sees is the group's address (08 prelude): the issuer stored is the group, and any enabled member may later mint.

4. TransferToken (11)

Purpose. Move units of a token to a recipient.

Inputs. tx.recipient (required); the body below. The escrowed form (12 §2) is not specified here.

Offset Length Field Encoding
0 8 token_id i64 LE (0 is refused: ZBC is not a token)
8 8 amount i64 LE > 0, multiple of the step
16 1 (optional) fee_in_token 1 = pay the fee in the token (§5); any other value = ZBC
17 8 (optional) survival payment i64 LE ≥ 0 (13 §10); needs the flag byte present

Output and effect. In this order: the policy bounce of 08 (a sender or recipient that opted out of Payments: fee charged, nothing else); unknown token → block invalid; expired token (persist_height > 0 and < height) with the fee in ZBC → paid no-op (a fee in the token: the no-op of §5, judged after the recipient test); no recipient → block invalid; the fee: in ZBC (the fee charge of 04 §5; unaffordable → block invalid) or in the token (§5; a token without ZBC backing at the block → the no-op of §5); sender's units −(amount + fee units) (checked add; overflow → block invalid after returning a ZBC fee); insufficient units → paid no-op (a ZBC fee is kept; a fee in the token is settled by the no-op of §5); recipient's units +amount through the split policy (08); for a fee in the token the row's supply −fee units and backing −released ZBC (both clamped at 0); persist_height, when > 0, = max(persist_height, height) + blocks bought by the payment; a new token version when the row changed. Then 04 §5.

How to compute it. Stateless (admission and block validation): body ≥ 16 ("Token tx body too short (need token_id + amount)"), "Token amount must be positive", "Token survival payment cannot be negative", and (rule admission_checks_in_block) a recipient whose account type is not one that can sign (the list of 01: types 0, 1, 4, 5, 6, 7, 9, 11, 12, 13, 14, 15, 16 can; so a type 2, 3, 8 or 10 (ZBS_) recipient is refused): "TransferToken: recipient address type cannot hold tokens (it cannot sign a later spend)", so a block carrying such a transfer is invalid. Before these, the envelope rule of 03 (rule canonical_account_forms): a sender or recipient in a full-key form (an Ethereum or Tron type followed by a 64-byte key, a Bitcoin legacy, P2PKH or P2WPKH type followed by a 33- or 65-byte key, 01) is 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)" (the transaction bytes cannot carry one, since they carry the 20-byte form of those types; the named-field form of a relayed block can). Then (rule bridge_withdrawal_credit, 34): a TransferToken whose message begins ZBW1| is a bridge withdrawal and is refused unless its token is a bridge coin whose withdrawals are open, it carries no escrow, its recipient is that coin's custody account and its destination suits the coin's chain (34 §5, in that order; for example "TransferToken: withdrawals of ZUSDC are not open: no release of an ethereum token contract exists in this release"), and any TransferToken whose recipient is a custody account without being such a withdrawal is refused (34 §5a). Admission mirrors: "Token transaction body too short" (< 8), "Unknown or expired token: ID" (judged at the next height), "Token amount is finer than the token's decimals allow (token ID moves multiples of STEP)", "TransferToken: missing recipient", "TransferToken: paying the fee in the token needs a token with ZBC backing (token ID has none)", "Insufficient token balance for transfer/burn: ID" (held < amount; the fee units are not counted). Execution (block invalid): "Invalid TransferToken body", "Transfer amount must be positive", "Fee cannot be negative", "Unknown token", "Transfer amount is finer than the token's decimals allow", "Missing token recipient", "TransferToken: amount+fee overflow".

Rule activation. uniform_fee_refund, fee_in_token_step, token_exact_backing, state_answer_noop, admission_checks_in_block, canonical_account_forms, bridge_withdrawal_credit (active from height 0 on every chain). Several transfers in one transaction: §4a.

Rejections and errors. As listed.

Vector. computed (the DUST2 token of §3: id 4,849,860,418,062,503,083, decimals 2, step 1,000,000).

  • Input: TransferToken (type 11) from the issuer to a type-0 account R, fee in ZBC, body (17 bytes) ABCCD7C45A2A4E4300E1F5050000000000 (1.00 DUST2, flag 0).
  • Expected output: the fee charged in ZBC; the issuer's DUST2 −100,000,000, R's +100,000,000 (through R's split policy); persist_height unchanged (no payment).
  • Invalid input: body ABCCD7C45A2A4E4360E3160000000000 (1,500,000 = 0.015) → refused at admission "Token amount is finer than the token's decimals allow (token 4849860418062503083 moves multiples of 1000000)"; in a block: invalid, "Transfer amount is finer than the token's decimals allow". The 17-byte body to a recipient of type 10 (a ZBS_ address) → "TransferToken: recipient address type cannot hold tokens (it cannot sign a later spend)" (stateless: refused at admission, and a block carrying it is invalid). An amount above the holding → "Insufficient token balance for transfer/burn: 4849860418062503083".

Test cases · §4

6 cases · 1 valid · 5 invalid

The issuer sends 1.00 DUST2 to a type-0 account14-4-transfervalid

Loading the test widget…

0.015 DUST2 is finer than the token's step14-4-finerinvalid

Loading the test widget…

Mined, the same transfer makes the block invalid14-4-finer-minedinvalid

Loading the test widget…

A ZBS_ deposit address cannot receive tokens14-4-zbs-recipientinvalid

Loading the test widget…

An envelope recipient in a full-key form is refused before the type checks14-4-full-key-recipientinvalid

Loading the test widget…

Sending more than the sender holds14-4-insufficientinvalid

Loading the test widget…

Defects to match. (1) Units are not reserved at admission: two transfers admitted against the same balance are both mined and the second is a paid no-op. (2) A transfer to the sender's own address is mined and paid, and the sender's split policy forwards shares of the arriving units. (3) For a fee paid in ZBC the expiry test precedes the recipient test: an expired token with no recipient is a paid no-op, a live one is a block failure; for a fee paid in the token the recipient test comes first, so an expired token with no recipient is a block failure.

4a. TransferTokenBatch (267)

Purpose. Several token transfers (any tokens, any recipients) from one sender in one transaction, all or nothing, the fee in ZBC.

Inputs. tx.recipient must be empty (the recipients are in the body); the body, all integers little endian:

Offset Length Field Encoding
0 2 count u16, 1…32 (at most 32 transfers)
2 per action count × action see below

Each action: token_id (8, i64 LE, ≠ 0) ‖ addr_len (1, u8, ≥ 24) ‖ addr (addr_len bytes, a typed address, 01 §4) ‖ amount (8, i64 LE, > 0). The body ends exactly after the last action. A recipient may repeat; a token may repeat. There is no fee-in-token flag and no survival payment.

Output and effect. Order: the per-token sums Σ amount (an amount ≤ 0 or an overflow → block invalid); then the state check of every action, before any applies, as of the block: each token known and not expired, each amount a multiple of the token's step, no recipient refusing Tokens by its transact policy (08 §11), and for each token (in ascending id) the sender's balance ≥ the sum across the batch; any failure → the whole batch is a paid no-op (the fee charged, nothing else); the ZBC fee (charged as in 04 §5; unaffordable → block invalid, as for TransferToken); each token's sum debited from the sender (ascending token id); then each action in body order credited as a token credit (the recipient's split policy applies, 08 §10). No token row changes (no persistence extension). Then 04 §5.

The minimum fee (04 §2) is the sum of what each action would pay alone: the floor of a TransferToken with a 16-byte body and the batch's message for the first action, plus (count − 1) times the floor of the same with no message (saturating at 2⁶³−1). The block's transaction ceiling max_transactions_per_block counts each action of the batch (19 §2, 04 §10).

How to compute it. Stateless (admission and block validation), in this order: a non-empty envelope recipient ("TransferTokenBatchTransaction: a batch names its recipients in its body; the envelope recipient must be empty"); the parse, whose texts are prefixed "TransferTokenBatch: " ("TransferTokenBatch: body too short for the action count", "…: a batch carries at least one action", "…: more than 32 actions", "…: the body is shorter than its action count" when count > remaining bytes / 41, "…: truncated token id", "…: truncated or too short recipient", "…: truncated amount", "…: trailing bytes after the last transfer"); then per action, prefixed "TransferTokenBatchTransaction: ": "transfer i: token id 0 is ZBC, which SendZBCBatch moves", "transfer i: the amount must be positive", "transfer i: recipient address: …" (the address shape of 01 §4), "transfer i: 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 recipient in a full-key form, §4), "transfer i: recipient address type cannot hold tokens (nobody could ever spend them)" (a recipient whose type cannot sign, as in §4), "amount overflow for token T"; i counts from 0. These are stateless, so they make a block invalid. Admission also refuses the state check's answer ("TransferTokenBatchTransaction: transfer i: unknown or expired token T", "… the amount is finer than the token's decimals allow (token T moves multiples of S)", "Refused by transact policy: TransferTokenBatchTransaction: transfer i: …", "TransferTokenBatchTransaction: insufficient token balance: token T needs N across the batch, H held").

Rule activation. canonical_account_forms (the full-key recipient), active from height 0 on every chain.

Rejections and errors. As listed.

Vector. computed.

  • Input: TransferTokenBatch (type 267), empty envelope recipient, body (108 bytes) 0200ABCCD7C45A2A4E432400000000120EE4CA9D258D75656901EC4837373E07763369AD75ED8D63FA31C7E0B7E80700E1F50500000000ABCCD7C45A2A4E432400000000120EE4CA9D258D75656901EC4837373E07763369AD75ED8D63FA31C7E0B7E80740420F0000000000 = count 2; 1.00 DUST2 (id 4,849,860,418,062,503,083) to the 36-byte account A = 00000000120EE4CA9D258D75656901EC4837373E07763369AD75ED8D63FA31C7E0B7E807; 0.01 DUST2 to A.
  • Expected output: the sender's DUST2 −101,000,000 in one debit; A +100,000,000 then +1,000,000; the fee in ZBC.
  • Invalid input: the same body with count 0100 → "TransferTokenBatch: trailing bytes after the last transfer"; with a non-empty envelope recipient → "TransferTokenBatchTransaction: a batch names its recipients in its body; the envelope recipient must be empty"; with the token id of the first action set to 0 → "TransferTokenBatchTransaction: transfer 0: token id 0 is ZBC, which SendZBCBatch moves"; the one-action body (87 bytes) 0100 ABCCD7C45A2A4E43 44 04000000 79BE667EF9DCBBAC55A06295CE870B07029BFCDB2DCE28D959F2815B16F81798483ADA7726A3C4655DA4FBFC0E1108A8FD17B448A68554199C47D08FFB10D4B8 00E1F50500000000 (1.00 DUST2 to an Ethereum account written in its full-key form: the 64-byte key of the secp256k1 private key 1, whose 20-byte form is 04000000 ‖ 7E5F4552091A69125D5DFCB7B8C2659029395BDF) → "TransferTokenBatchTransaction: transfer 0: 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)"; the same action naming 18 04000000 7E5F4552091A69125D5DFCB7B8C2659029395BDF (43 bytes) is accepted; all stateless (a block carrying one is invalid).

Test cases · §4a

6 cases · 2 valid · 4 invalid

Two DUST2 transfers to one account in one batch14-4a-batchvalid

Loading the test widget…

A count of one leaves trailing bytes14-4a-count-oneinvalid

Loading the test widget…

A batch with an envelope recipient14-4a-envelope-recipientinvalid

Loading the test widget…

A batch action naming an Ethereum account in its full-key form14-4a-full-keyinvalid

Loading the test widget…

The same action naming the 20-byte form of that account is accepted14-4a-twenty-bytevalid

Loading the test widget…

Token id 0 in a batch14-4a-token-zeroinvalid

Loading the test widget…

Defects to match. (1) Units are not reserved at admission (as for TransferToken). (2) The amounts of a refused (no-op) batch stay in its stored body; only the movements say what arrived.

5. A fee paid in the token

Purpose. A holder with no ZBC pays the transfer fee from the token's backing.

Inputs. Flag byte 1 and tx.fee > 0; the row's supply and backing.

Output and effect. A transfer that goes through needs backing_asset 0, backing > 0, supply > 0 at the block. released = the fee floor at the block (04 §2) when that is below the declared fee, else the declared fee; units = ceil(released × supply / backing) in 128-bit, at least 1 (saturating at 2⁶³−1), rounded up to the step. The sender pays no ZBC; its units −(amount + units); the row: supply −units, backing −released (each clamped at 0). A declared fee above the floor writes two rows, event 22 +(fee − released) and event 46 −(fee − released), that move nothing; the reward pool therefore receives released (04 §5 step 7) and the fee counts as collected. The ZBC released leaves the backing and reaches the blocksmiths through the pool; no balance row records it; released reaches the coinbase lottery with every other fee (04 §5, 21 §2).

The no-op of a fee-in-token transfer (the token expired at the block, the sender's units short of amount + units, or no ZBC backing at the block: all answers of chain state, never block faults) still pays the floor, in this order:

  1. through the backing when it can: units is computed as above (0 when the row has no backing or no supply), and the sender's units −units alone (the amount does not move), the row: supply −units, backing −released, a new token version, the two overpay rows above when the declared fee exceeds released; this path needs backing_asset 0, released ≤ backing, units ≤ supply and the sender holding units;
  2. else in ZBC: the sender's balance −the declared fee (row event 1) and the overpay above the floor credited back at once (row event 22 +(fee − released), a real credit): the sender pays exactly the floor;
  3. else (the sender cannot pay the declared fee in ZBC either) nothing is charged, and the rows event 22 +fee and event 47 −fee tell the reward pool the fee was not collected.

The generic settlement of 04 §5 adds no second refund: the overpay of a flag-1 transfer is always returned by this mechanism, in the token (step 1, rows 22/46) or in ZBC (step 2, row 22).

How to compute it. As stated.

Rule activation. fee_in_token_step, token_exact_backing, uniform_fee_refund, state_answer_noop (the no-op on a token without backing), fee_collected_explicit (the fee of steps 1 and 2 counts as collected), active from height 0 on every chain.

Rejections and errors. §4.

Vector. computed.

  • Input: a TransferToken with flag byte 1 (a 17-byte body, no message) on a chain with 11 registered nodes and the TestNet parameters, whose floor is 2,500,099 (04 §2: the period rent of 17 bytes is 82, ceil(82 × 17,280 / 172,800) = 9, × 11 = 99, plus the scaled base 2,500,000), with declared fee 2,500,099 equal to the floor, on a token with supply 100,000,000,000, backing 100,000,000, decimals 2 (step 1,000,000).
  • Expected output: released 2,500,099; units = ceil(2,500,099 × 10¹¹ / 10⁸) = 2,500,099,000, rounded up to the step = 2,501,000,000; the sender's units −(amount + 2,501,000,000); the row: supply 97,499,000,000, backing 97,499,901; no ZBC leaves the sender. (With one registered node the same body's floor is 2,500,009, and the units are again 2,501,000,000.)
  • Input (the no-op through the backing): the same transfer when the sender holds 2,501,000,000 units but less than amount + 2,501,000,000. Expected: the amount does not move; the sender's units −2,501,000,000; the row: supply 97,499,000,000, backing 97,499,901; no ZBC moves.
  • Input (the no-op in ZBC): the same transfer with declared fee 3,000,000 on a token whose backing is 0 at the block, the sender holding 10,000,000 ZBC. Expected: refused at admission "TransferToken: paying the fee in the token needs a token with ZBC backing (token ID has none)" (with the id); mined (the backing was drained earlier in the block): no units move, the sender's ZBC −3,000,000 (row event 1) then +499,901 (row event 22): the sender paid the floor 2,500,099, which the reward pool receives.
  • Input: the same with a sender holding no ZBC. Expected: nothing moves; rows event 22 +3,000,000 and event 47 −3,000,000 on the sender; the pool receives nothing for it.

Test cases · §5

6 cases · 5 valid · 1 invalid

A transfer whose fee, the floor 2,500,099, is paid in the token14-5-fee-in-tokenvalid

Loading the test widget…

With one registered node the same body's floor is 2,500,009 and the units are again 2,501,000,00014-5-one-nodevalid

Loading the test widget…

The sender holds the fee units but not amount + units: the floor is settled through the backing14-5-noop-backingvalid

Loading the test widget…

A fee in the token needs a backed token14-5-no-backinginvalid

Loading the test widget…

Mined on a token whose backing is 0, the sender pays the floor in ZBC and gets the overpay back14-5-noop-zbcvalid

Loading the test widget…

The same with a sender holding no ZBC: nothing moves and the fee is not collected14-5-noop-no-zbcvalid

Loading the test widget…

Defects to match. (1) The rounding to the step takes units the released ZBC did not pay for; they are burned, not credited. (2) Admission reserves no ZBC for such a transfer (only its survival payment, 04 §7) and the units are not reserved either; but staging still requires the paying account's spendable ZBC to cover the declared fee (04 §6 staging step 6, "Sender has insufficient balance for fee"), so a holder with no ZBC at all is refused and cannot use the flag, and step 3 above is reached only by a sender that spent its ZBC after staging.

6. MintToken (12)

Purpose. The issuer adds supply at the current backing ratio.

Inputs. Body as §4 offsets 0–15 (the flag byte at 16 is ignored; a payment at 17).

Output and effect. Order: unknown token → block invalid; expired → paid no-op; mint mode ≠ 1 or sender ≠ issuer (byte-equal) → paid no-op; add_backing = 0 when backing or supply is 0, else ceil(amount × backing / supply) in 128-bit; add_backing + fee overflow → paid no-op; the sender −(add_backing + fee) in one debit (unaffordable → paid no-op); rows event 1 −fee, event 52 −add_backing; supply or backing overflow → the backing is returned (row event 52 +add_backing) and the fee kept, nothing else; otherwise the row: supply +amount, backing +add_backing, persist_height as §4; the sender's units +amount (no split policy). Then 04 §5.

How to compute it. Stateless as §4 ("Token tx body too short …", "Token amount must be positive"). Admission mirrors: the token and step texts of §4, "Only the issuer can mint: ID", "Token is not mintable: ID", "MintToken: supply overflow: ID". Execution (block invalid): "Invalid MintToken body", "Invalid mint amount/fee", "Unknown token", "Mint amount is finer than the token's decimals allow".

Rule activation. token_exact_backing, uniform_fee_refund, state_answer_noop.

Rejections and errors. As listed.

Vector. computed.

  • Input: MintToken (type 12) by the issuer of a mintable token with supply 3, backing 10, amount 1. Expected: add_backing = ceil(1 × 10 / 3) = 4; the issuer −(4 + fee), rows event 52 −4 and event 1 −fee; supply 4, backing 14; the issuer's units +1.
  • Input: a mintable token with backing 0, supply 100,000,000,000; mint 100,000,000. Expected: no backing added; supply 100,100,000,000.
  • Invalid input: MintToken on ZUSD, body 010000000000000000E1F50500000000 → from any sender but its issuer "Only the issuer can mint: 1" (checked first), from the issuer "Token is not mintable: 1"; mined, a paid no-op.

Test cases · §6

4 cases · 2 valid · 2 invalid

Minting 1 unit of a token with supply 3 and backing 1014-6-ratiovalid

Loading the test widget…

Minting 1.00 of an unbacked mintable token14-6-unbackedvalid

Loading the test widget…

A stranger minting ZUSD is not its issuer14-6-zusd-strangerinvalid

Loading the test widget…

ZUSD's issuer cannot mint it either14-6-zusd-issuerinvalid

Loading the test widget…

Defects to match. (1) The issuer test is byte equality between the stored issuer and the sender as the dispatcher presents it (08): a token issued by a group is mintable by any enabled member, a token issued by a plain account only by that account.

7. BurnToken (13)

Purpose. Destroy units and, if the token is redeemable, take their share of the backing.

Inputs. Body as §6.

Output and effect. Order: unknown → block invalid; expired → paid no-op; not redeemable (bit 0 clear) → paid no-op; held < amount → paid no-op; refund = 0 when backing or supply is 0, else floor(amount × backing / supply) in 128-bit, capped at the backing; the fee (charged as in 04 §5; unaffordable → block invalid); the sender's units −amount (a refusal here → nothing more, the fee stays); the row: backing −refund, supply −amount, persist_height as §4; the sender +refund with a row event 53 (when refund > 0). The fee counts as collected although the refund credits the sender in the same transaction (fee_collected_explicit, 04 §5): it reaches the reward pool and its overpay is refunded. Then 04 §5.

How to compute it. Stateless as §4. Admission mirrors: the §4 texts, "Insufficient token balance for transfer/burn: ID", "Token is not redeemable: ID". Execution (block invalid): "Invalid BurnToken body", "Invalid burn amount/fee", "Unknown token", "Burn amount is finer than the token's decimals allow".

Rule activation. token_exact_backing, uniform_fee_refund, fee_collected_explicit (active from height 0 on every chain).

Rejections and errors. As listed.

Vector. computed.

  • Input: BurnToken (type 13) of 2,000,000,000 units on a redeemable token (flags 3) with supply 10,000,000,000 and backing 10,000,000,000, body token_id ‖ 0094357700000000. Expected: refund floor(2 × 10⁹ × 10¹⁰ / 10¹⁰) = 2,000,000,000, row event 53 +2,000,000,000 on the sender; supply 8,000,000,000, backing 8,000,000,000.
  • Input: supply 3, backing 10, burn 1. Expected: refund 3; supply 2, backing 7.
  • Input: a redeemable token with backing 0, supply 100,000,000, burn 100,000,000. Expected: supply 0, refund 0, no event 53 row.
  • Invalid input: BurnToken on ZUSD → "Token is not redeemable: 1" (admission); mined, a paid no-op.

Test cases · §7

4 cases · 3 valid · 1 invalid

Burning 20 units of a fully backed redeemable token14-7-redeemvalid

Loading the test widget…

Burning 1 unit of a token with supply 3 and backing 1014-7-floorvalid

Loading the test widget…

Burning the whole supply of an unbacked redeemable token14-7-unbackedvalid

Loading the test widget…

ZUSD is not redeemable14-7-zusdinvalid

Loading the test widget…

Defects to match. The refund is a plain credit to the sender as the dispatcher presents it (a member's group, 08); no split policy applies to it.

8. FinanceToken (14)

Purpose. Buy persistence for any token.

Inputs. Body: token_id (8, i64 LE) ‖ payment (8, i64 LE, required, > 0).

Output and effect. Order: fee ≤ 0 → block invalid; a missing or non-positive payment → block invalid (never reached: stateless validation refuses it); unknown → block invalid; expired → paid no-op; persist_height 0 (a never-expiring token: every genesis coin) → paid no-op; the fee (charged as in 04 §5); base = max(persist_height, height); the payment is debited (row event 45; unaffordable → nothing more, the fee stays, persistence unchanged); the row: persist_height = base + blocks bought, a new version. Then 04 §5.

How to compute it. Stateless: "FinanceToken needs token_id + amount: the fee no longer buys persistence" (< 16 bytes), "FinanceToken amount must be positive". Admission mirrors: "Token transaction body too short", "Unknown or expired token: ID", "Token ID never expires: FinanceToken has nothing to fund". Execution: "Invalid FinanceToken body" (< 8), "FinanceToken needs a fee to fund persistence", "FinanceToken amount must be positive", "Unknown token".

Rule activation. uniform_fee_refund (height 0). The never-expiring refusal has no rule (unconditional).

Rejections and errors. As listed.

Vector. computed (TestNet).

  • Input: FinanceToken (type 14) at height 131,300, body token_id ‖ 40787D0100000000 (payment 25,000,000), on a token with persist_height 179,902.
  • Expected output: the fee; the sender −25,000,000 (event 45), ZBCLONGV +25,000,000 (event 50); persist_height = 179,902 + 2 × 172,800 + (5,000,000 × 172,800) div 10,000,000 = 611,902.
  • Invalid input: body 0100000000000000 8096980000000000 (ZUSD, 10,000,000) → refused at admission "Token 1 never expires: FinanceToken has nothing to fund"; if mined, the fee is charged and nothing changes. Body 0100000000000000 (8 bytes) → "FinanceToken needs token_id + amount: the fee no longer buys persistence" (stateless).

Test cases · §8

3 cases · 1 valid · 2 invalid

FinanceToken with 0.25 ZBC on a token due at 179,90214-8-financevalid

Loading the test widget…

FinanceToken on ZUSD, which never expires14-8-zusdinvalid

Loading the test widget…

An 8-byte FinanceToken body14-8-shortinvalid

Loading the test widget…

Defects to match. It cannot revive an expired token (a paid no-op); the payment is not taken.

9. Persistence and expiry, as the operations see them

Purpose. The rule every operation above shares (the arithmetic is in 13 §10).

Inputs. The row's persist_height; the block height.

Output and effect. persist_height 0 = never; otherwise the token is live at heights ≤ persist_height and expired at any height above it: every operation is a paid no-op, the admission mirror refuses ("Unknown or expired token" judged at the next height), the API views hide it, and the first block above persist_height with backing > 0 pays the backing out (13 §10) and writes a token version with backing 0. Transfer, Mint and Burn extend a live token only when persist_height > 0, from max(persist_height, height), by what the payment buys.

How to compute it. As stated.

Rule activation. uniform_fee_refund, token_expiry_to_holders.

Rejections and errors. §4–§8.

Vector. computed (DevNet, free period 240).

  • Input: a token with backing 8,000,000,000 issued at height 447 with no payment.
  • Expected output: persist_height 687; operations are accepted at heights ≤ 687; at 688 every operation is refused at admission ("Unknown or expired token: <id>") and a paid no-op if mined, and block 688 writes a token version with backing 0, the supply unchanged (the backing paid to the holders, 13 §10). A transfer at 450 with no survival payment leaves persist_height 687.

Test cases · §9

4 cases · 3 valid · 1 invalid

A token issued at 447 with no payment on DevNet14-9-issuedvalid

Loading the test widget…

A transfer at 450 with no payment leaves persist_height at 68714-9-livevalid

Loading the test widget…

A transfer at 687 is still accepted14-9-lastvalid

Loading the test widget…

At height 688 the token is gone14-9-expiredinvalid

Loading the test widget…

Defects to match. A settled token keeps its supply and its holders' balances; the units exist but cannot move.

10. Ledger rows, API views and the consensus/local split

Event Row Written by
1 sender −fee Issue, Mint, Transfer in ZBC, TransferTokenBatch, Burn, Finance, every no-op; the ZBC floor of a fee-in-token no-op (§5 step 2)
52 sender −backing / +returned backing Issue, Mint
53 sender +refund Burn
45 sender −payment the survival payment of any of the five
22 / 46 sender +x / −x, no movement a fee paid in the token (§5, the overpay settled in the token)
22 sender +(fee − floor) the ZBC overpay of a fee-in-token no-op (§5 step 2)
22, 47 per 04 §5 the generic settlement (the overpay above the floor refunded as event 22; +fee / −fee when nothing was collected, §5 step 3 included)
50 pool +payment the survival payment's credit to the longevity pool (13 §10)

Views: /tokens (current_height, tokens[] with token_id (string), issuer (hex, lower case), symbol, name, decimals, amount_step, total_supply, backing_amount, redeemable, mintable, unbacked, persist_height); /tokens/<id> (the same plus backing_asset, current_height); /accounts/<a>/tokens (address, current_height, tokens[] with balance); /tokens/<id>/icon, /tokens/volume (local). Expired tokens are left out of the lists.

Consensus: the token rows (every field), the balance rows, the step rule, the symbol and name rules, the id derivation, every rounding above, the accept/no-op/invalid outcome of each operation, and the amounts of event-22 rows (04). Local: the ledger rows otherwise, the views.

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