On this page
  1. §0 The area in one paragraph
  2. 1. The storage-rent primitive
  3. 2. The fee floor
  4. 2.1 The floor of a batch
  5. 3. The fee scale
  6. 4. The escrow rent
  7. 5. What is charged and refunded (consensus)
  8. 6. Admission: the checks a transaction passes before it is pooled (node-local)
  9. 7. The reservation of spendable balance (node-local)
  10. 8. Fee per byte and the pool's order (node-local)
  11. 9. The worst-case ZBC outflow of a transaction
  12. 10. Block assembly: selecting transactions for a candidate (blocksmith policy)
  13. 11. The rejection log and the status route (node-local observability)
  14. 12. The fee-estimate and fee-parameter routes
  15. 13. What in this document is consensus, and what is not

04 — Fees, admission and the mempool

Edition 0.6.1 · verified against the reference implementation, version 0.6.1

Out of scope the envelope fields themselves and the timestamp windows (03); each type's body, executor and ledger rows (08–18); what a block does with total_fee and the reward pool (21); the fee-vote transactions and the parameter governance that feed the fee scale (17); the account-group gate's state and the member window (18); account rent and the survival deposit's life (13); the HTTP API as a whole (31)

§0 The area in one paragraph

Every transaction declares a fee in its envelope. The chain computes a floor for it from two things it can see without any node-local information: a fixed base action fee multiplied by a network-wide fee scale, and a bytes charge for keeping the transaction's own body and message for a fixed minimum number of blocks multiplied (rule permanent_state_priced) by the number of registered nodes that keep those bytes; an escrow's rent is charged on its own, outside the floor (§4). Every stage of every computed charge rounds up, so nothing becomes free when a price is voted down to one atomic unit. A batch pays the sum of what its actions would pay as separate one-action transactions. A transaction whose fee is under its floor is invalid: refused at admission and, if a block carries it, the block is invalid; a node's fee-free duty must declare exactly zero. When the transaction is mined, the declared fee leaves the payer and everything above the floor comes straight back in the same block as a ledger row of its own; all of a block's fees go to the coinbase lottery (21), none to its blocksmith. A transaction that took nothing from the payer records that nothing was collected, so the block's lottery never pays out a fee nobody paid, and a fee paid out of a node's lock instead of a balance goes to the longevity pool. The fee scale moves once per snapshot cycle, to the average of the counted registered nodes' votes, except in survival mode, when the count is skipped. While the chain is in survival mode the governance transactions and every AttestEvent (the bridge category, type 17) are refused at admission and left in the pool by blocksmiths. A foreign-signed carrier (02 §9) is pooled once per native id and, for Ethereum, in nonce order. This document specifies that floor, the fee scale it depends on, the escrow rent, what is charged and refunded (consensus: it changes balances), and then the node-local life of a transaction before a block: staging (with the pool's cheap checks before the signature check), admission, the reservation of spendable balance, the pool's capacity, eviction and expiry (each transaction's own window), the duty lane that keeps node duties flowing under load, the ordering by the effective fee per byte, and the blocksmith's selection of transactions for a block (one per account, its oldest). Only the floor (with its registry multiplier), the charge/refund rules, the escrow rent, the worst-case outflow used by the account-group gate, the fee-scale count and the two block ceilings (count and bytes) are consensus; everything else here is policy that a Follower (L1) may implement differently and a Blocksmith (L2) should reproduce to build blocks that other nodes accept (one transaction per account per block is a block rule, 19). The protocol takes from this area the exact fee charged per transaction (the reward pool, 21), the reservation that keeps a sender from overspending across pending transactions, and the worst-case outflow that the account-group gate measures (18).

1. The storage-rent primitive

Purpose. One function prices a number of bytes for one billing period; the fee floor, the escrow rent, dataset rent (10), stored-file rent (11) and the survival deposit (13) all use it.

Inputs. bytes (u64); cost_per_mib (i64, consensus parameter dataset_storage_cost_per_mib); multiplier_ppm (i64, consensus parameter storage_oracle_multiplier_ppm).

Output and effect. An i64 amount in atomic units, the rent of bytes for one billing period (one snapshot cycle, main_snapshot_interval blocks, §2): ceil(ceil(bytes × cost_per_mib / 1,048,576) × multiplier_ppm / 1,000,000), both stages rounded up, computed exactly in 128 bits and saturating at INT64_MAX. A whole MiB at 1.0× costs exactly cost_per_mib; any non-zero number of bytes costs at least one unit; zero bytes cost 0.

How to compute it. ceil_div(a, b, c) = ⌈a × b / c⌉ on the unsigned 128-bit product, saturated to INT64_MAX (0 when c = 0):

  1. If cost_per_mib ≤ 0, multiplier_ppm ≤ 0 or bytes = 0 the result is 0.
  2. base = ceil_div(bytes, cost_per_mib, 1,048,576).
  3. rent = ceil_div(base, multiplier_ppm, 1,000,000).

Rule activation. None. dataset_storage_cost_per_mib is governable down to 1 atomic unit (ceiling 100 ZBC/MiB) and storage_oracle_multiplier_ppm within 100,000 .. 10,000,000 (17).

Rejections and errors. None; the function cannot fail.

Vector. computed. Input (bytes, cost, ppm) → expected rent: (8, 5,000,000, 1,000,000) → 39; (16, 5,000,000, 1,000,000) → 77; (24, 5,000,000, 1,000,000) → 115; (76, 5,000,000, 1,000,000) → 363; (137, 5,000,000, 1,000,000) → 654; (1,048,576, 5,000,000, 1,000,000) → 5,000,000 exactly; (8, 100,000,000, 1,000,000) → 763; (75, 100,000,000, 1,000,000) → 7,153; (394, 100,000,000, 1,000,000) → 37,575; (8, 1, 1,000,000) → 1; (0, 5,000,000, 1,000,000) → 0. GET /api/v1/blockchain/estimate-fee reports the first three as survival_rent_per_period 39 for 8 bytes, 115 for 24 bytes and 654 for 137 bytes (§12). The function refuses nothing.

Test cases · §1

12 cases · 12 valid · 1 reference

The rent of 8 bytes at 5,000,000 units per MiB04-1-rent-8-5000000valid

Loading the test widget…

The rent of 16 bytes at 5,000,000 units per MiB04-1-rent-16-5000000valid

Loading the test widget…

The rent of 24 bytes at 5,000,000 units per MiB04-1-rent-24-5000000valid

Loading the test widget…

The rent of 76 bytes at 5,000,000 units per MiB04-1-rent-76-5000000valid

Loading the test widget…

The rent of 137 bytes at 5,000,000 units per MiB04-1-rent-137-5000000valid

Loading the test widget…

The rent of 1,048,576 bytes at 5,000,000 units per MiB04-1-rent-1048576-5000000valid

Loading the test widget…

The rent of 8 bytes at 100,000,000 units per MiB04-1-rent-8-100000000valid

Loading the test widget…

The rent of 75 bytes at 100,000,000 units per MiB04-1-rent-75-100000000valid

Loading the test widget…

The rent of 394 bytes at 100,000,000 units per MiB04-1-rent-394-100000000valid

Loading the test widget…

The rent of 8 bytes at 1 units per MiB04-1-rent-8-1valid

Loading the test widget…

The rent of 0 bytes at 5,000,000 units per MiB04-1-rent-0-5000000valid

Loading the test widget…

The fee-estimate route reports the same period rents at the TestNet prices04-1-routevalidreference

The survival_rent_per_period field of GET /api/v1/blockchain/estimate-fee (§12).

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

survival_rent_per_period_8_bytes
39
survival_rent_per_period_24_bytes
115
survival_rent_per_period_137_bytes
654

Defects to match. None.

2. The fee floor

Purpose. The smallest fee a transaction may declare, computed identically by every node from the transaction and chain parameters.

Inputs. From the envelope (03): transaction_type (u32), body_length (u32, the declared body length) and the message length (bytes); for a batch, its action count (§2.1). From consensus parameters: dataset_storage_cost_per_mib, storage_oracle_multiplier_ppm (both governable), min_payload_persistence_blocks and the billing period period = main_snapshot_interval (both genesis-fixed; the snapshot cycle, 172,800 when the parameter is absent or 0, never below 2). From state: the current fee scale (§3). From the active registry: its size at the previous block (rule permanent_state_priced). From the rule clock: whether uniform_fee_refund and permanent_state_priced are active at the height the transaction is judged for (admission: tip + 1; in a block: the block height).

Parameter TestNet / mainnet DevNet Compiled fallback when absent
dataset_storage_cost_per_mib 5,000,000 100,000,000 100,000,000
storage_oracle_multiplier_ppm 1,000,000 1,000,000 1,000,000
min_payload_persistence_blocks 17,280 240 17,280
billing period = main_snapshot_interval 172,800 240 172,800
base action fee (MIN_FEE, also MIN_NODE_REGISTRATION_FEE) 2,500,000 2,500,000 constant
INITIAL_FEE_SCALE (the 1.0× scale) 1,000,000 1,000,000 constant

(TestNet values: the TestNet genesis file, which the mainnet template matches, and what GET /api/v1/blockchain/fee-params reports on a chain built from it; DevNet: the DevNet genesis file. There are no separate dataset_billing_period_blocks and account_rent_period_blocks parameters: the genesis builder refuses either unless it equals main_snapshot_interval, and every rent period is the snapshot cycle; the fee-params route reports both as the cycle.)

Output and effect. floor (i64 atomic units). A transaction is valid only if fee ≥ floor, and for type 0 (Empty) additionally fee > 0. A node's fee-free duty (rule duty_fee_free: SubmitStorageProof 41, SubmitStorageProofBatch 297, AttestEvent 17, SetConsensusParam 51, FeeVoteCommitment 7, FeeVoteReveal 263, EquivocationReport 60, RollCall 61 and SpineEquivocationReport 62; and, under liveness_attestation, a registered node's QueueAttendance 59) must instead declare exactly 0; any other fee makes it invalid. The floor is what is kept when the transaction is mined (§5) and what the mempool orders by (§8).

How to compute it. ceil_div as in §1.

  1. weight = body_length + message_length (u64).
  2. period_rent = storage_rent(weight, cost_per_mib, multiplier_ppm) (§1).
  3. persistence_rent = ceil_div(period_rent, pb, period) with pb = min_payload_persistence_blocks (0 when period = 0, which the cycle never is). 3b. (rule permanent_state_priced) when persistence_rent > 0: persistence_rent ×= registry_size, the number of registered nodes at the previous block (never below 1), saturating at INT64_MAX: every node keeps these bytes, so the price is per replica. A node that cannot read the registry size prices the transaction at INT64_MAX (an unpayable floor, never at one replica).
  4. base_fee = 2,500,000 (the same constant is used for type 2 NodeRegistration under its own name; there is no per-type base fee).
  5. scaled_base = ceil_div(base_fee, fee_scale, 1,000,000) (fee_scale from §3, 1,000,000 = 1.0×; at the fee scale's floor of 1 unit the base is 3 units, never 0).
  6. (rule uniform_fee_refund) The escrow rent is not part of the floor: it is debited on its own at escrow creation (§4).
  7. floor = scaled_base + persistence_rent, checked: an overflow gives INT64_MAX.

With pb/period = 0.1 (TestNet) the bytes charge is one tenth of one period's rent (rounded up); with pb = period (DevNet) it is a whole period. The envelope's fixed fields, the escrow part and the signature are not in weight: only the body and the message are charged here.

2.1 The floor of a batch

A batch (types 257, 267, 297, 03 §2) whose body parses to n ≥ 1 actions pays what its actions would pay as separate one-action transactions: floor(batch) = floor(one_1) + (n − 1) × floor(one), checked (overflow → INT64_MAX), where one is a transaction of the one-action type (SendZBC for 257, TransferToken for 267, SubmitStorageProof for 297) with the batch's version and timestamp, body_length = the one-action body (8, 16 and 72 bytes respectively), no message and no escrow, and one_1 is the same with the batch's message: the message is charged once. So each action pays one scaled base fee and the bytes charge of its one-action body. A body that does not parse (n = 0) is priced by steps 1–7 like any transaction (and is refused by the type's own validation). SubmitStorageProofBatch is a fee-free duty and declares 0 whatever this computes.

Rule activation. uniform_fee_refund, active from height 0 on every chain: the floor carries no escrow rent, which is debited separately at creation (§4, 12). permanent_state_priced, active from height 0 on every chain: step 3b. duty_fee_free and liveness_attestation (at 0 on every chain): the exactly-zero duties. The rounding up and the batch rule have no rule.

Rejections and errors. fee < floor → refused at admission and makes a block invalid (the same function runs in block validation at the block's height). Empty with fee = 0 → the same. A duty with a fee other than 0 → the same. A negative fee is below every floor. The observable admission reason is the validator's fee message (document 03 §12 lists the order of envelope refusals).

Vector (computed). Input → expected floor, TestNet parameters (cost 5,000,000, ppm 1,000,000, pb 17,280, period 172,800, fee scale 1,000,000) with 11 registered nodes (the 11 genesis registered nodes of the TestNet file, 06 §6):

  • Type 1, body 8, no message → 2,500,044: period rent 39, persistence ceil(39 × 17,280 / 172,800) = 4, × 11 = 44, plus the scaled base 2,500,000.
  • Body 24 (a CreateApp) → 2,500,132: period rent 115, persistence 12, × 11 = 132; with a declared fee of 5,000,000 the transaction is charged 2,500,132 and refunded 2,499,868 (§5).
  • Type 257 with 3 actions → 7,500,132 = 3 × 2,500,044.
  • One registered node: body 8 → 2,500,004; body 16 → 2,500,008; a 65,536-byte body with a 256-byte message → 2,531,373 (period rent 313,721). DevNet parameters (cost 100,000,000, pb = period = 240), one node: body 8 → 2,500,763; body 394 → 2,537,575.
  • Fee scale 2,000,000 → scaled base 5,000,000; 500,000 → 1,250,000; 1 (the floor) → 3.
  • Invalid inputs: the default SendZBC with fee 2,500,043 (one below the floor) → refused "Transaction fee too low"; a SubmitStorageProof (41) with fee 1 → refused "Transaction fee must be exactly 0: a node duty declares a fee of exactly zero (this one declares 1)"; an Empty (0) transaction with fee 0 → refused.

Test cases · §2

16 cases · 13 valid · 3 invalid

The floor of the default SendZBC at the TestNet parameters (11 registered nodes)04-2-testnet-defaultvalid

Loading the test widget…

The floor of a 24-byte body (a CreateApp) at the TestNet parameters04-2-testnet-body24valid

Loading the test widget…

A SendZBCBatch of three payments pays three one-action floors04-2-testnet-batch3valid

Loading the test widget…

The floor with one registered node: body 8, message 004-2-one-node-8-0valid

Loading the test widget…

The floor with one registered node: body 16, message 004-2-one-node-16-0valid

Loading the test widget…

The floor with one registered node: body 65,536, message 25604-2-one-node-65536-256valid

Loading the test widget…

The floor on DevNet prices with one node: body 804-2-devnet-8valid

Loading the test widget…

The floor on DevNet prices with one node: body 39404-2-devnet-394valid

Loading the test widget…

The scaled base fee at a fee scale of 2,000,00004-2-scale-2000000valid

Loading the test widget…

The scaled base fee at a fee scale of 500,00004-2-scale-500000valid

Loading the test widget…

The scaled base fee at a fee scale of 104-2-scale-1valid

Loading the test widget…

A SendZBC declaring one unit below its floor is refused04-2-fee-one-belowinvalid

Loading the test widget…

A SendZBC declaring exactly its floor is accepted04-2-fee-at-floorvalid

Loading the test widget…

A storage proof (a node duty) with a fee of 1 is refused04-2-duty-feeinvalid

Loading the test widget…

A storage proof declaring 0 is accepted04-2-duty-zerovalid

Loading the test widget…

An Empty transaction with a fee of 0 is refused04-2-empty-zeroinvalid

Loading the test widget…

Defects to match. The two storage prices are read afresh for every computation; the genesis-fixed min_payload_persistence_blocks and the snapshot cycle never change. An implementation must have the registry size at the previous block, or it computes a different floor for every transaction that persists bytes. The rounding is per stage (§1, step 3, step 5), not once at the end: rounding bytes × cost × ppm × pb / (2^20 × 10^6 × period) once gives a different floor (normal amounts move by up to one unit at each stage).

3. The fee scale

Purpose. A network-wide multiplier of the base action fee (the "transfer fee"), meant to follow the value of ZBC by a vote of the registry once per snapshot cycle (17).

Inputs. The fee_scale state table (07): columns fee_scale (i64), block_height (u32, unique key), latest (0/1; at most one row has latest = 1). The survival flag of the count block (rule survival_mode, 19). For the count (17): the cycle length L = main_snapshot_interval (§2), the counted registered nodes as of the previous block (registered and not suspended, 36), the registry floor (min_registry_size, default 3, under rule quorum_floor), and the FeeVoteReveal rows of the cycle.

Output and effect. fee_scale (i64): the fee_scale value of the row with latest = 1 when such a row exists and its value is > 0; otherwise INITIAL_FEE_SCALE = 1,000,000. The genesis builder writes the row (1,000,000, 0, 1), and a block that finds no latest row seeds the same row, so the latest row always exists. The floor uses it as scaled_base = ceil(base_fee × fee_scale / 1,000,000) (§2 step 5). Bounds for ever: 1 ≤ fee_scale ≤ 100,000,000 (one atomic unit .. 1 ZBC, i.e. a base fee of 3 units .. 250 ZBC).

How to compute it. The read is the line above. The count, specified fully in 17, is summarised so an implementer knows what the floor depends on. Cycle k is blocks k·L + 1 .. (k+1)·L; a FeeVoteCommitment is valid in the first half of its block's cycle ((h − 1) mod L < L/2), a FeeVoteReveal in the second half; a reveal counts only from a node's typed account (00000000 ‖ node key) and only if it opens a commitment the same voter made after the latest fee_scale row; a registered node's latest reveal of the cycle (the lower value on a tie) is its vote. At the end of every block, after its transactions:

  1. If no latest row exists, insert (1,000,000, 0, 1).
  2. If the block's height h is not a multiple of L, stop. 2b. (rule survival_mode) If the chain is in survival mode at h (the flag the block is judged by, 19), stop: no row is written, the cycle's reveals lapse.
  3. today = the latest row's value. nodes = the counted registered nodes as of h − 1, in node-id order; when quorum_floor is active and the registry floor is not met, nodes is empty.
  4. next = today when nodes is empty; otherwise next = the bounded average of the votes: t = clamp(today, 1, 10^8), every registered node without a vote counts t, every vote is first limited to [max(1, ceil(t/2)), min(10^8, t + max(1, t div 5))], the average is (sum + n div 2) div n over n = max(|nodes|, |votes|) (rounded to nearest, 128-bit sum) and is clamped to [1, 10^8].
  5. Mark the latest row not latest and insert (next, h, 1): a row is written at every count, changed or not.

A rollback below a row's height deletes it and re-marks the highest remaining row latest.

Rule activation. quorum_floor and survival_mode (step 2b): active from height 0 on every chain. A chain whose genesis names survival_min_producers is in survival mode from block 1 until that many distinct blocksmiths have produced inside the window (06 §9), so a count block that falls inside that stretch writes no row.

Rejections and errors. None here (the votes' own refusals are 17). A failed read or write of the fee_scale row, the counted registered nodes, the reveals or the survival flag refuses the block on that node.

Vector. computed: from the genesis row, fee_scale is 1,000,000 and effective_min_fee 2,500,000 at every height before the first count block (172,800 on the TestNet parameters), which is what GET /api/v1/blockchain/fee-params reports there (§12). Input 5 counted registered nodes, today 1,000,000, votes 2,000,000, 400,000 and 1,100,000, two nodes silent → the votes are limited to 1,200,000, 500,000 and 1,100,000, the silent nodes count 1,000,000 each, sum 4,800,000, (4,800,000 + 2) div 5 = 960,000, the new scale (the base fee becomes 2,400,000). The same input at a count block in survival mode → no row; the scale stays 1,000,000.

Test cases · §3

4 cases · 4 valid · 1 reference

The fee scale from the genesis row, at every height before the first count block04-3-genesis-rowvalidreference

What GET /api/v1/blockchain/fee-params reports there (§12); 04-fee-floor computes the scaled base 2,500,000 at fee scale 1,000,000.

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

fee_scale
1000000
effective_min_fee
2500000
first_count_block
172800
The scaled base fee at the genesis fee scale04-3-genesis-scalevalid

Loading the test widget…

Five registered nodes, three votes: each vote limited, the silent registered nodes count today's scale04-3-countvalid

Loading the test widget…

The same count block in survival mode writes no row04-3-count-survivalvalid

Loading the test widget…

Defects to match. "This cycle" in the commitment test is "after the latest fee_scale row" (a commitment row with a height above that row's), at admission and in the executor alike. A count skipped in survival mode writes no row, so a commitment made in the skipped cycle still matches in the next cycle: its voter may reveal it in the next reveal phase without committing again, and the reveal counts. An implementation must apply the same "after the latest row" test to reproduce this.

4. The escrow rent

Purpose. The price of keeping an escrow object in chain state for its whole lock: its envelope bytes × its duration in blocks, at the storage rate.

Inputs. The escrow part of the envelope (03 §7): approver_address (typed address bytes; the rent exists only when it is non-empty), commission (i64), timeout (i64, absolute Unix seconds), instruction (bytes), multi_party (1 byte) and, when multi-party, co_signer_signature with its u32 length and escrow_request_id (i64); the envelope timestamp (i64); the four rent parameters of §2; SMITHING_PERIOD = 15 seconds.

Output and effect. escrow_rent (i64 atomic units). Under uniform_fee_refund it is debited from the payer at escrow creation as its own ledger row (event 45, survival_paid, negative) and credited to the longevity node pool (00000000‖"ZBCLONGV"‖24×00, event 50) in the same block; it is never refunded, whatever ends the escrow (12, 13). Admission reserves it with the fee (§7) and the block-assembly sender gate counts it (§9).

How to compute it.

  1. If there is no escrow part, or its approver is empty: 0.
  2. esc_bytes = the length of the serialised escrow part: len(approver) + 8 + 8 + 4 + len(instruction) + 1, plus 4 + len(co_signer_signature) + 8 when multi_party = 1. (A ZBC approver is 36 bytes, so a single-party escrow with an n-byte instruction is 57 + n bytes.)
  3. esc_period_rent = storage_rent(esc_bytes, cost_per_mib, multiplier_ppm) (§1).
  4. dur_secs = max(timeout − timestamp, 0) (i64); dur_blocks = ceil(dur_secs / 15) (u64; a part block of lock counts as a block).
  5. escrow_rent = ceil_div(epr, dur_blocks, period) (§1) with epr = esc_period_rent and period the billing period of §2 (the snapshot cycle); rounded up, so a non-empty escrow with any lock pays at least one unit.

Rule activation. uniform_fee_refund and survival_field (compiled default 30,000; at 0 on every chain): the rent is a separate debit to the longevity pool. An escrow whose timeout runs past the reachable prune horizon is refused unless the transaction carries the survival deposit to keep it that long (rule escrow_timeout_cap, 03 §7, 12).

Rejections and errors. None of its own. The escrow validation (12 §1) refuses a timeout at or before the transaction's timestamp ("Escrow timeout must be a future Unix timestamp (now + lock duration); got T <= tx time S", T the timeout and S the transaction timestamp), so the clamp at 0 is never reached by a valid transaction; 12 verifies it.

Vector. computed, the escrow of the version-2 envelope of 03 §1 (approver 36 bytes, commission 1,000, timeout = timestamp + 7,200, instruction release on delivery of 19 bytes, single-party): esc_bytes = 36 + 8 + 8 + 4 + 19 + 1 = 76; TestNet period rent of 76 bytes = 363 (§1); dur_blocks = ceil(7,200 / 15) = 480; escrow_rent = ceil(363 × 480 / 172,800) = 2. GET /api/v1/blockchain/estimate-fee?escrow=1&escrow_instruction_length=19&escrow_lock_seconds=7200 on a node with these parameters and 11 registered nodes answers escrow_kind "single", escrow_envelope_bytes 76, escrow_rent 2, total_debit_excluding_amount 2,500,046 = 2,500,044 + 2 (§12). The same escrow at DevNet rates: period rent 7,248 (76 bytes at 100,000,000/MiB), ceil(7,248 × 480 / 240) = 14,496. Invalid input: the same escrow with timeout = timestamp → refused by escrow validation ("Escrow timeout must be a future Unix timestamp (now + lock duration); got T <= tx time S", 03 §7).

Test cases · §4

4 cases · 3 valid · 1 invalid · 1 reference

The escrow of the version-2 envelope at TestNet prices04-4-testnetvalid

Loading the test widget…

The same escrow at DevNet prices04-4-devnetvalid

Loading the test widget…

The fee-estimate route's answer for that escrow (11 registered nodes)04-4-routevalidreference

GET /api/v1/blockchain/estimate-fee?escrow=1&escrow_instruction_length=19&escrow_lock_seconds=7200 (§12): 2,500,044 + 2.

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

escrow_kind
single
escrow_envelope_bytes
76
escrow_rent
2
total_debit_excluding_amount
2500046
An escrow whose timeout equals the transaction time is refused04-4-timeout-nowinvalid

Loading the test widget…

Defects to match. None.

5. What is charged and refunded (consensus)

Purpose. The exact movement of the fee when a transaction is mined: the declared fee leaves the payer, the overpay above the floor comes back in the same block, a fee a lock pays goes to the longevity pool, and a transaction that took nothing records it.

Inputs. The mined transaction (its fee, type, body, escrow part, version and survival), the block height, the floor of §2 at the block height, the payer's ZBC balance before and after the type's executor ran, and two flags the executor may raise ("the fee was collected even though the balance is unchanged"; "the fee was settled here, not from the balance").

Output and effect. Balances after the block and ledger rows (07). The ledger row is a node-local index except where this document says a sum of rows is read by consensus (21): the reward pool subtracts every event-22 row of the block, so the amounts of event 22 are consensus.

  1. The charge. The type's executor debits the declared fee from the paying account (the group's account when the sender is an enabled member, 18) as part of its own work. Most types record it as a row of event 1 (−fee); some fold it into their own row (an escrow creation records amount + commission + fee as one event-16 row; a dataset write records its fee under event 6). The type documents give the row; the amount is always the declared fee. A fee of 0 (a duty) touches no account and writes no row. Exceptions: a fee-in-token TransferToken debits no ZBC but releases the floor from the token's backing (step 4, 14), unless the backing cannot settle it (step 4); a fee paid out of a lock (step 1b); a MultiSignature inner transaction's fee is a row of event 70 (12). Every debit of the declared fee reports itself to the settlement (rule fee_collected_explicit): the charge of step 1, the no-op charge of step 2 and the direct debits of the few types that fold the fee into their own row. 1b. A fee out of a lock (QueueAttendance of a queued node; and, when the lock can cover it and still hold something, a registered node's exit by RemoveNodeRegistration or the owner's ClaimNodeRegistration, the removal of a queued node, a claim; 09 — a genesis registered node locks nothing, so its owner's balance pays the fee as in step 1): the lock pays clamp(floor, 0, fee) — the minimum, never the overpay, which simply stays in the lock — and that amount is credited to the longevity pool (event 80, positive, on the pool, naming the transaction; ZBC is never burned). The sender's balance does not move; the executor writes event 22 +fee and event 47 −fee on the sender (so the declared fee in total_fee never reaches the lottery) and raises "settled here": steps 3 and 4 do not run for it. (A queued node's attendance never takes its stake below the registration minimum, rule attendance_fee_floor, 09.)
  2. A no-op still pays. A mined transaction whose state-dependent condition fails (an approval of a settled escrow, a transfer of tokens spent earlier in the same block, a mint of an expired token, a FundLongevity outside its window, an action of a batch that cannot apply, …) is not an error: the executor charges the fee first (best-effort: a payer who can no longer cover it is simply not charged) and does nothing else. From fee_vote_noop this includes a fee vote from an account that is not a registered node's key. SettleApp that changes nothing is free by design (16).
  3. Nothing collected. After the type's work, when no debit of the declared fee reported itself (step 1; rule fee_collected_explicit) and the "settled here" flag is not raised, the payer's balance is compared with its balance before the dispatch: equal means nothing was taken, and two rows are written with no balance change — event 22 +fee and event 47 −fee (fee_not_collected) — unless the transaction is a fee-in-token transfer; no refund is paid. A reported debit is believed whatever the balance shows, so a type that credits its own sender inside the same transaction (CancelOrder, BurnToken, a stopped stream, a returned stake, an ApprovalEscrow whose approver is the escrow's sender or recipient) still reaches the pool and is refunded its overpay. This withholds, it never credits.
  4. The overpay is refunded. If the overpay is refundable, excess = fee − floor(block height), and when excess > 0 the payer is credited excess and one event-22 +excess row is written. Refundable: every type from uniform_fee_refund (escrowed transactions at creation; FinanceToken), except a fee-in-token TransferToken or LiquidPayment, which releases only the floor from the backing to the pool and keeps the rest in the token (rows 22 +excess, 46 −excess, 14). A fee-in-token transfer that becomes a no-op (step 2) settles the same way while its backing can pay the floor; when the backing cannot (the token was drained in the same block, is backed by another token, or the sender no longer holds the units) the sender pays the declared fee in ZBC and the overpay comes back as event 22, as for any transaction, and a sender that cannot pay in ZBC either is not charged and gets the rows of step 3 (22 +fee, 47 −fee). Nothing on the chain is free. The credit goes to the paying account (for a member, its group: 18).
  5. Early exits. A SendZBC or TransferToken bounced by a transact policy (17), a refused group member and a replayed foreign carrier (02 §9) exit before the type runs: from uniform_fee_refund, when the fee was taken the overpay is refunded as in step 4 (whatever the type: the ZBC fee was charged even for an escrowed or fee-in-token form, since neither ran); when it was not taken, rows 22 +fee and 47 −fee are written and nothing moves. Step 4 and step 5 agree.
  6. Then the header survival (version 2 and 3 envelopes, survival > 0) is debited as event 37 and the longevity record opened (13); it is never refunded and never counts as overpay.
  7. The block's pool (21): total_fee in the block header is the sum of the declared fees, and block validation requires total_fee to equal that sum exactly. The amount distributed is total_fee + coinbase − Σ(event 22 of the block) + |Σ event 70|, plus (rule longevity_continuous) a per-block slice of the longevity pool and whatever waits in the lottery carry (01 §7). All of it goes to the coinbase lottery: the blocksmith gets no share. A not-collected fee (rows 22 + 47) still nets to zero and its event-22 row keeps it out of the pool. Block 1 draws no lottery; its fees wait in the carry. 21 verifies the whole formula.

How to compute it. The steps above, in that order, once per mined transaction after its executor. The floor in steps 1b, 4 and 5 is §2 evaluated at the block height with the fee scale of §3 as of that block.

Rule activation. All active from height 0 on every chain. uniform_fee_refund: the 22 + 47 rows, the refund for escrowed and FinanceToken transactions, the escrow rent outside the fee, the fee-in-token floor release. fee_collected_explicit: the reported debits of steps 1 and 3. state_answer_noop: a fee-in-token transfer whose token has no ZBC backing is a no-op of step 2 instead of a block fault. duty_fee_free: a node-signed duty declares fee exactly 0 and the fee charge touches no account. fee_vote_noop: a fee vote from a non-node is a paid no-op instead of failing the block (17). survival_field: step 6 exists and event-45 payments go to the longevity pool.

Rejections and errors. None at this stage: a transaction that reached execution is valid; the only consensus error an executor may raise here is a storage fault, which fails the block on that node (not a rule of the chain).

Vector (computed). A CreateApp with a 24-byte body, declared fee 5,000,000 and floor 2,500,132 (§2, 11 registered nodes) → fee_charged 2,500,132 and fee_refund 2,499,868 (the event-22 row +2,499,868 on the sender, which GET /api/v1/transactions/<hash> reports under those names); the block header carries total_fee 5,000,000 (the declared fee). The version-2 escrowed SendZBC of 03 §1 on the TestNet parameters (11 nodes; weight = body 8 + message 11 = 19 bytes, period rent 91, persistence 10 × 11, floor 2,500,110), declared fee 5,000,000 → the sender's rows: event 16 −(100,000,000 + 1,000 + 5,000,000) = −105,001,000, event 45 −2 (escrow rent, §4), event 37 −10,000,000 (header survival, step 6), event 22 +2,499,890; the longevity pool +2 (event 50). A transaction declaring exactly its floor → no event-22 row. A fee-in-token TransferToken (a 17-byte body, the flag byte included; declared fee 5,000,000; floor 2,500,099 = 2,500,000 + ceil(82 × 17,280 / 172,800) = 9 × 11, the period rent of 17 bytes being 82) whose token's backing was drained earlier in the same block and whose sender holds 6,000,000 ZBC → the declared 5,000,000 is debited in ZBC (event 1) and 2,499,901 comes back (event 22), net 2,500,099; the same with a sender holding 3,000,000 ZBC → the debit of 5,000,000 fails, nothing is charged, rows 22 +5,000,000 and 47 −5,000,000.

Test cases · §5

6 cases · 6 valid · 2 reference

A CreateApp with a 24-byte body keeps its floor and refunds the rest04-5-createappvalid

Loading the test widget…

A fee-in-token TransferToken (a 17-byte body, the flag byte included) has the floor 2,500,09904-5-fee-in-token-floorvalid

Loading the test widget…

That transfer whose token's backing was drained earlier in the block, sender holding 6,000,000 ZBC04-5-fee-in-token-drainedvalidreference

The backing cannot pay the floor, so the declared fee is paid in ZBC and the overpay comes back.

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

debit_event_1
-5000000
refund_event_22
2499901
net
2500099
The same with a sender holding 3,000,000 ZBC: nothing is charged04-5-fee-in-token-unpaidvalidreference

The debit of 5,000,000 fails; the rows of step 3 are written with no balance change.

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

row_event_22
5000000
row_event_47
-5000000
charged
0
The rows of the version-2 escrowed SendZBC mined on the TestNet04-5-escrowed-sendvalid

Loading the test widget…

The same transaction declaring exactly its floor gets no refund row04-5-exact-floorvalid

Loading the test widget…

Defects to match. None. (An Ethereum carrier whose nonce is not the sender's account nonce never reaches these steps: it makes the block that carries it invalid, 02 §9 step 7.)

6. Admission: the checks a transaction passes before it is pooled (node-local)

Purpose. What this node demands before it relays a transaction and keeps it for a block; it is stricter than block validity on purpose and never looser.

Inputs. The submitted envelope bytes (HTTP POST /api/v1/transactions, 03 §10, or a peer's SendTransaction, 27), the node's wall clock, committed state at the tip, the pool's contents, the staging pool's contents, the node's configuration (max_pending_txs_per_sender, min_mempool_age_seconds, pool size).

Output and effect. Accepted (pooled, relayed, its reservation applied, §7) or refused with a reason string. Over HTTP a refusal before staging is the 400 body of 03 §10; a refusal at admission after a 202 is kept in the rejection log and answered by GET /api/v1/transactions/<id>/status (§11).

How to compute it. Two tiers. Staging (both entry paths): (1) not already staged ("Transaction already staged") or pooled ("Transaction already in mempool"), both DuplicateTransaction; (2) the pool's cheap checks, before the signature check, counting what is pooled and what is staged: a duty whose duty key (see the duty lane below) is already pending → "A duty transaction for this window is already pending from this node"; the sender (canonical address) already has max_pending_txs_per_sender (default 50) transactions pending → "Too many pending transactions from this sender (max 50)". Both are capacity refusals: the P2P handler does not relay the copy, pays no receipt for it, answers gRPC RESOURCE_EXHAUSTED and charges nobody (an honest relay forwards other people's bursts); every other refusal below is answered INVALID_ARGUMENT and counted toward the invalid-transaction threshold of the sender identity the handler charges: the registered key the request names when the caller's signed call binds that key to the connection, otherwise the connection's own charge key (key and host, or the host), never a bare key the request claims (27, 28); (3) memory pressure below the node's "High" level, else "System memory pressure - try again later"; (4) the signature verifies (02; failure → the signature-failure reason of 02 §2); (4b) a foreign carrier (02 §9) whose native id, or the SHA3-256 of whose raw message, is spent on the chain → refused "ForeignCarrierReplayed" as an invalid transaction (like the refusals below); one whose native id a pooled or a staged transaction already holds → "ForeignCarrierReplayed" as a duplicate (DuplicateTransaction, like (1)): nothing is staged, the HTTP route answers it as a transaction this node already holds (202 with "duplicate": true, 03 §10) and the P2P handler as an accepted duplicate (27); (5) the stateless validation of 03 and the type's document, including the fee floor, the carrier binding and the survival freeze at height tip + 1; (5b) an Ethereum carrier whose nonce is not the next free one (the first nonce at or above the account's that no pooled or staged carrier of the same sender holds, 02 §9) → "carrier nonce N, account nonce M" (in a block a carrier whose nonce is not the account nonce makes the block invalid, "ForeignCarrierNonce: carrier nonce N, account nonce M (a block carrying it is invalid)"); (6) when fee ≠ 0 and the type is not QueueAttendance, the paying account's spendable balance ≥ fee ("Sender has insufficient balance for fee"; a missing account → "Sender account does not exist") — a zero fee and an attendance need no account row (a node admitted after genesis has none until its account is funded); the cheap checks run again under the staging lock, so two variants checked at once cannot both fit; (7) staging capacity: fewer than 500,000 entries and at most 256 MiB of staged bytes, else "Staging pool full" / "Staging pool byte budget exhausted". The HTTP route additionally runs the pre-admission check (the state checks of the admission tier below, read-only, on the admitted form of the transaction) before answering 202, so the client sees the state reason at once. Staged transactions are admitted in arrival order, in batches whose size falls with the node's load, and a staged transaction not admitted within 3,600 s of arrival is dropped ("not admitted to the mempool within 60 minutes of arrival (the node was under load)").

Admission (the pool), in this order; the first failure wins:

  1. Pool not over its hard limit, 1.5 × its maximum (37,500 at the default 25,000): "Transaction pool overloaded - try again later". 1b. (rule foreign_carrier_bound) No pooled transaction holds the same native carrier id: "ForeignCarrierReplayed", a duplicate (DuplicateTransaction).
  2. Stateless validation again (signature skipped when the staging tier verified it); a carrier whose id was spent on the chain since it was staged is refused here with "Foreign carrier transaction already used" (02 §9). It includes the survival freeze (rule survival_mode): while the chain is in survival mode for the block the transaction would land in (tip + 1; the flag is computed from the stored flag of the tip and the distinct blocksmiths of the 120 blocks before tip + 1, 19), a transaction of the governance category (types 7, 263, 32, 33, 34, 35, 51) or of the bridge category (type 17) is refused "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" in the text means distinct blocksmiths; the mode ends when N or more distinct blocksmiths show in the window); a survival state that cannot be read refuses it too ("SurvivalMode: the survival state could not be read: …"). For a FeeVoteCommitment (7) it includes the body size: a body that is not exactly 32 bytes is refused ("FeeVoteCommitment: body must be 32 bytes"), at admission and in a block.
  3. The local timestamp window (03 §5): timestamp + W < now, with W the transaction's window (3,600 s, or a version-3 transaction's stated expiry up to 86,400 s, 03 §4) → "Transaction expired: its timestamp T is more than W s in the past; sign it again"; timestamp > now + 3,600 → "Transaction timestamp T is more than 3600 s in the future; check the signer's clock".
  4. Recipient shape for every type but SendZBC (which the validator already covers): a non-empty recipient whose type prefix is not an account type, or whose length is wrong for its type (01 §4), → "Recipient address: <reason>".
  5. The state mirrors: every type's "does the object exist, is it in the state this transaction needs, is the sender allowed" check, evaluated at tip + 1 against committed state. Among them: a fee-free duty's sender must be the typed account 00000000 ‖ node key of a node in the registry ("a fee-free duty transaction must be sent by a registry attester account (the node's own key)"); a FeeVoteCommitment or FeeVoteReveal must come from a registered node's typed account ("FeeVoteCommitment: voter is not a registered node", likewise for the reveal) inside its phase (17). They are listed in each type's document; they are admission policy — a block carrying a transaction that fails one is still valid if the executor's own rule turns it into a paid no-op (§5 step 2). Two former mirrors are stateless rules since admission_checks_in_block (a TransferToken to a recipient type that cannot sign, a CreateApp whose player or invited opponent cannot sign: 14, 16), so a block carrying one is invalid. Here too, for an Ethereum carrier, the nonce is judged against the pool: the first free nonce at or above the account's over the pooled and staged carriers of the sender, the carrier itself left out ("carrier nonce N, account nonce M"); a Solana or Bitcoin carrier's chain binding is judged for tip + 1 (02 §9).
  6. A limited group member's pending spend (§9's outflow summed over its pooled transactions plus this one) within what is left of its window (18): "the member's spending limit would be exceeded counting its pending transactions (P pending, this one up to X, R left this period)".
  7. NodeRegistration whose node public key (body bytes 0–31) is registered and not Deleted: "NodeAlreadyRegistered".
  8. The hash and id (03 §9): id 0 → "Invalid transaction ID (zero)"; an id already in the confirmed transaction table → "TransactionAlreadyConfirmed"; a submitted id that differs from the computed one → "Transaction ID mismatch".
  9. The pool does not already hold the hash: "Transaction already in pool".
  10. Fewer than max_pending_txs_per_sender (default 50) pooled transactions with the same sender bytes: "Too many pending transactions from this sender (max 50)".
  11. The balance check with pending reservations counted (§7): the type's required amount ≤ the payer's spendable balance, else "Insufficient balance (considering pending transactions)", or the type-specific reason of §7 (node-only types, orders, overflow).
  12. The reservation is applied (§7). Then capacity: if the pool holds max_pool_size (default 25,000) entries, the lowest fee-per-byte transaction is evicted when the newcomer's fee per byte (§8) is strictly higher — ties broken toward evicting the newest arrival, then the higher id — else the newcomer is refused with "Transaction pool is full and transaction fee is not high enough to replace existing transactions" (its reservation undone); still full after the attempt → "Transaction pool is full".
  13. Pooled: arrival time = now, byte size = the signed envelope length, fee per byte (§8), and the tip height at admission recorded; relayed to peers (28).

Node-local: the staging balance check (staging step 6) and the admission balance check (step 11) both run, so a transaction can pass staging and fail admission moments later; the pre-admission check on the HTTP route closes most of that gap.

Rule activation. The mirrors of step 5 follow each type's rules at tip + 1. Step 4 mirrors recipient_address_shape (active from height 0 on every chain) but runs at every height. The survival freeze of step 2 is rule survival_mode, the carrier checks of staging (4b, 5b) and steps 1b and 5 are rule foreign_carrier_bound, both active from height 0 on every chain. The staging cheap checks have no rule (node-local).

The duty lane (node-local). A duty transaction (QueueAttendance and the fee-free duties of §2 — SubmitStorageProof, SubmitStorageProofBatch, AttestEvent, SetConsensusParam, FeeVoteCommitment, FeeVoteReveal, EquivocationReport, RollCall and SpineEquivocationReport) is handled apart from the fee economy: admission requires its sender to be a node's typed account (00000000‖node key of a registered node; a queued one for an attendance; a genesis registered node's for a roll call, 09), it is admitted even when the pool is at capacity, it is never evicted for fee pressure, and at most one may be pending per node per duty object (the duty key: the sender bytes plus, for QueueAttendance |59| and the 120-block window of the referenced height, for SubmitStorageProof |41| and the piece id and epoch (body bytes 0–39), for SubmitStorageProofBatch |297| and the epoch (body bytes 0–7: one batch per node per epoch), for RollCall |61 (one per node), for AttestEvent |17| and the event id, for SetConsensusParam |51| and the parameter, for EquivocationReport |60| and the parent and blocksmith, |7 and |263 for the two fee-vote types, for SpineEquivocationReport |62| and the body's first 36 bytes, the spine height and the accused key). The staging tier applies the same key (step 2). A second duty for the same object from the same node is refused "A duty transaction for this window is already pending from this node". On the P2P entry path a queued node's key is privileged like a registered one under load, and each sender's transaction rate is limited by tier (27, 28).

Rejections and errors. As listed. None of them is a block rule: a Follower may accept more or less; a block is judged by 19.

Vector (computed; the reason strings are the observable output). Input: the §1 version-3 SendZBC of 02 §1 submitted at local time 1,793,509,627 + 7,201 → refused "Transaction expired: its timestamp 1793509627 is more than 7200 s in the past; sign it again". Input: the same at local time 1,793,509,627 − 3,601 → refused "Transaction timestamp 1793509627 is more than 3600 s in the future; check the signer's clock". Input: a 51st pending transaction of one sender with the default configuration → refused "Too many pending transactions from this sender (max 50)". Input: a second QueueAttendance of one node for the same 120-block window while the first is pending → refused "A duty transaction for this window is already pending from this node". Input, on a chain in survival mode (N = 5, four distinct blocksmiths in the window): a FeeVoteReveal → refused with the SurvivalMode text of step 2 for type 263, an AttestEvent → the same text for type 17; a SendZBC in the same state → admitted. Input: an Ethereum carrier with nonce 7 from an account whose nonce is 5 while a carrier with nonce 5 is pooled and none with 6 → refused "carrier nonce 7, account nonce 6"; the same with nonce 6 → admitted and pooled behind the first.

Test cases · §6

11 cases · 3 valid · 8 invalid · 2 reference

A version-3 SendZBC submitted after its 7,200-second window04-6-expiredinvalid

Loading the test widget…

The same transaction submitted more than an hour before its timestamp04-6-futureinvalid

Loading the test widget…

The same transaction inside its window04-6-in-windowvalid

Loading the test widget…

A 51st pending transaction of one sender04-6-pending-capinvalidreference

A stated value: there is nothing to compute. The statement is a refusal: the exact text a compatible node answers.

refusal
Too many pending transactions from this sender (max 50)
A second attendance of one node for the same window04-6-duty-duplicateinvalidreference

A stated value: there is nothing to compute. The statement is a refusal: the exact text a compatible node answers.

refusal
A duty transaction for this window is already pending from this node
A fee vote reveal while the chain is in survival mode04-6-survival-voteinvalid

Loading the test widget…

An AttestEvent (the bridge category) in the same state04-6-survival-attestinvalid

Loading the test widget…

A SendZBC in the same state is admitted04-6-survival-sendvalid

Loading the test widget…

A carrier with nonce 7 while nonce 5 is pooled and none with 6 is refused04-6-carrier-nonce-gapinvalid

Loading the test widget…

The same with nonce 6 is admitted and pooled behind the first04-6-carrier-nonce-nextvalid

Loading the test widget…

At block assembly the nonce-6 carrier waits: the account nonce is still 504-6-carrier-nonce-assemblyinvalid

Loading the test widget…

Defects to match. The only replay guard is "the id is already in the confirmed transaction table" (step 8; at apply "DuplicateTransaction", and the table's primary key); every chain keeps transaction rows for at least the 25-hour replay window, 6,924 blocks at 15-s blocks (03 §4), the longest a transaction can stay valid. A second envelope around a carrier id this node holds (4b) is answered like a duplicate of a held transaction although its own hash is held nowhere: over HTTP the 202 names a hash whose status is then "not_found" (§11; nothing is recorded in the rejection log), and over P2P the handler treats it as accepted: it pays the receipt it would pay for a new transaction and relays the new envelope once (each node then answers it the same way). Node-local; no block can carry two copies (§10, 19).

7. The reservation of spendable balance (node-local)

Purpose. Each account carries two numbers, balance and spendable_balance (07); the pool subtracts from the second what its pending transactions will take, so a sender cannot overspend across several pending transactions, and restores it when a transaction leaves the pool.

Inputs. The admitted transaction; for a few types the registry or state (a node's current stake, a market, an offer, an app, a token's backing); the node's view of the payer's spendable_balance.

Output and effect. On admission spendable_balance(payer) −= reserved(tx); on removal from the pool for any reason but inclusion in a block that was applied (eviction, expiry, a failed block, a reorganisation's backup) += reserved(tx), clamped so that spendable_balance ≤ balance always holds. Before a block is applied every pooled reservation is undone and after it every remaining one re-applied, so frozen account rows hold confirmed values only. A reorganisation rebuilds every reservation from spendable = balance plus the surviving pool. Nothing here is written to any block: spendable_balance is node-local state. The pool's expiry sweep (every 300 s) drops a pooled transaction once timestamp + W < now, its own window (03 §4, §5), with the rejection reason "expired in the mempool without being mined: its expiry window (W s after its timestamp) has ended".

How to compute it. Two tables. Checked before reserving (required, must be ≤ spendable; fee here is the declared fee, hs the header survival of a version-2 envelope, er the escrow rent of §4 when an escrow part with an approver is present on an escrowable type):

Type required
every type (start) fee + hs (+ er when escrowed)
SendZBC (1) + amount (body i64 at 0); escrowed: + commission
SendZBCBatch (257) + the sum of the payments' amounts (checked)
AddPrepaidStorage (9) + amount (i64 at 0)
NodeRegistration (2) + locked_balance (body; 9)
NodeRegistrationUpdate (258) + max(new locked − the node's current locked, 0) (the full new value when the payer has no node)
RemoveNodeRegistration (514), ClaimNodeRegistration (770), ApprovalEscrow (4), MultiSignature (5), LiquidPaymentStop (262) nothing more
LiquidPayment (6) + amount when token_id = 0
ScheduledTransfer (29) + per_fire_amount × remaining_fires when funding_mode = 0 and token_id = 0 (checked multiply)
TransferToken (11) escrowed: + commission (the token amount is not ZBC)
RegisterGateway (36) + the voted gateway_registration_cost (1,000,000,000 at genesis on both live chains)
FundStoredFile (296) + amount (i64 at 32)
StoreFile (40) + deposit (i64 at 44)
PlaceOrder (22) collateral: sell → amount (i64 at 17) of the base asset; buy → amount × price / 100,000,000 (i128, i64 at 9 and 17) of the quote asset; if that asset is ZBC it is added to required, if a token the sender's token balance must cover it ("insufficient free balance for this order: promises N, only M free (the rest is held by open orders)"); skipped when the market is unknown or amount/price ≤ 0
IssueToken (10) + backing (i64 at 10)
CreateTrigger (15) + amount (i64 at 8)
FundLongevity (52) + amount (i64 at 8)
CreateApp (24) + stake_amount when stake_token_id = 0
every other type + (worst-case outflow of §9 − fee) when positive

Node-only gates in the same check: SubmitStorageProof (41), SubmitStorageProofBatch (297), SetConsensusParam (51) and a bridge attestation (an AttestEvent whose body's first length-prefixed string starts with the bridge deposit or withdrawal prefix, 17) must come from the account 00000000‖node_public_key of a registered node ("SubmitStorageProof must be signed by a registered node", "SubmitStorageProofBatchTransaction must be signed by a registered node", "SetConsensusParam must be signed by a registered node", "Bridge attestation must be signed by a registered node") and then pass the ordinary balance check (their fee is 0 under duty_fee_free); EquivocationReport, RollCall and SpineEquivocationReport require fee 0 ("EquivocationReport: duty transactions are fee-free", "RollCall: duty transactions are fee-free", "SpineEquivocationReport: duty transactions are fee-free") and nothing else here; a registered node's QueueAttendance (its liveness attestation) requires fee 0 ("Liveness attestation: fee must be 0"); otherwise QueueAttendance (9) must come from a queued node's key ("QueueAttendance must come from a queued node") whose stake covers the fee ("QueueAttendance: stake does not cover the fee") and requires no balance at all. Before the type's own terms, an escrowed transaction's commission must be non-negative ("Escrow commission cannot be negative") and, for an escrowed SendZBC, fee + escrow rent + amount + commission must not overflow ("Escrow amount + fee + commission + rent overflow"), rule escrow_commission_nonnegative. A required that overflowed → "Transaction amount overflow". An unknown payer → insufficient.

Reserved (subtracted from spendable_balance; sp = the explicit survival payment a token transaction's body may carry, 14):

Type reserved
every type (start) fee + sp + hs
SendZBC plain + amount
SendZBCBatch + the sum of the payments' amounts
SendZBC escrowed fee + commission + er + amount (+ hs)
TransferToken escrowed fee + commission + er (+ hs)
TransferToken fee-in-token (body byte 16 = 1) sp + hs only (no ZBC fee)
AddPrepaidStorage + amount
IssueToken + backing (i64 at 10, when the body has ≥ 18 bytes)
CreateTrigger + amount (i64 at 8, ≥ 16 bytes)
CreateApp + stake_amount when stake_token_id = 0 and > 0
RegisterGateway + the voted gateway_registration_cost (read the same at reserve and undo: it moves only inside a block's apply)
FundLongevity + deposit (i64 at 8, ≥ 16 bytes)
FundStoredFile + amount (i64 at 32, ≥ 40 bytes)
StoreFile + deposit (i64 at 44, ≥ 52 bytes)
ScheduledTransfer + per_fire × fires when funding_mode = 0 and token_id = 0
NodeRegistration + locked_balance
NodeRegistrationUpdate + max(new − current, 0)
LiquidPayment, ZBC (token_id = 0) amount + fee (checked; the header survival is added by the outer step)
LiquidPayment, token nothing, not even the fee (+ hs)
MultiSignature, LiquidPaymentStop, FeeVoteCommitment, FeeVoteReveal fee (+ hs)
QueueAttendance fee + hs by the start row (no balance was checked for it; the executor takes the fee from the stake instead, 9)
every other type (incl. Empty, SubmitStorageProof, PlaceOrder, MintToken, JoinApp, AcceptSwapOffer, CreateMarket) fee + sp + hs

A negative total (overflow) refuses the transaction ("Transaction amount overflow"). The undo restores exactly the same amount, computed again from the body and the registry. A fee-free duty (rule duty_fee_free) has fee = 0, so it reserves only sp + hs (both 0 for a duty); the node key it is sent from has no account to debit.

Node-local: the two tables differ on purpose. A token LiquidPayment reserves nothing but must show fee spendable; a fee-in-token TransferToken reserves no ZBC but must show fee spendable (a token-rich, ZBC-poor sender is refused at admission though the executor would accept it); PlaceOrder, MintToken, JoinApp, AcceptSwapOffer and CreateMarket are checked for their worst-case outflow but reserve only the fee (a state-dependent amount is never reserved, so the block-assembly gate of §10 re-checks them). Only SendZBC and TransferToken carry an escrow part (12), so the escrow terms apply to those two types only.

Rule activation. survival_field, uniform_fee_refund (the explicit survival payment and the escrow rent are reserved) and escrow_commission_nonnegative (the commission sign and the overflow check): active from height 0 on every chain.

Rejections and errors. As listed; all admission-only.

Vector. computed: input the version-2 escrowed SendZBC of 03 §1 on the TestNet parameters (fee 5,000,000, commission 1,000, escrow rent 2, header survival 10,000,000, amount 100,000,000) → expected required = reserved = 5,000,000 + 1,000 + 2 + 100,000,000 + 10,000,000 = 115,001,002. Invalid input: the same with the sender's spendable balance 115,001,001 → refused "Insufficient balance (considering pending transactions)"; the same with commission −1 → refused "Escrow commission cannot be negative".

Test cases · §7

3 cases · 1 valid · 2 invalid

The version-2 escrowed SendZBC reserves fee, commission, escrow rent, amount and survival04-7-reservevalid

Loading the test widget…

The same with one unit less spendable04-7-shortinvalid

Loading the test widget…

The same with commission -1 is refused04-7-commission-negativeinvalid

Loading the test widget…

Defects to match. None.

8. Fee per byte and the pool's order (node-local)

Purpose. The priority of a pooled transaction, used for eviction and for block assembly.

Inputs. The transaction's effective fee at the next block's height: min(fee, floor), since the overpay is refunded for every type (§5); the signed envelope length size (u32, 03 §1 including the signature), the arrival time (local clock, seconds), the transaction id (i64).

Output and effect. fee_per_byte = (effective_fee × 10,000) div size (i64; × 10,000 alone when size = 0, which cannot happen for a parsed envelope). Pool order: fee_per_byte descending, then arrival ascending, then id ascending (stable sort). Overpaying (refunded) therefore buys no priority and no protection from eviction: every transaction that pays at least its floor ranks by its floor per byte. A duty (fee 0) ranks at 0 and is handled by the duty lane (§6, §10). The same value is computed when a transaction is admitted, when the pool is reloaded from its database after a restart, and for the persisted copy, so a restart does not reorder the pool.

How to compute it. As stated; integer division toward zero (all operands non-negative).

Rule activation. None (node-local).

Rejections and errors. None.

Vector. computed: input the version-2 escrowed SendZBC of 03 §1 (signed length 268 = 204 + 64, declared fee 5,000,000, TestNet floor with 11 nodes 2,500,110, §5) → expected fee_per_byte = (2,500,110 × 10,000) div 268 = 93,287,686; the same transaction with declared fee 2,500,110 or 9,000,000 ranks the same. The version-3 SendZBC of 02 §1 (signed length 189, no message, its own floor 2,500,044) → (2,500,044 × 10,000) div 189 = 132,277,460.

Test cases · §8

4 cases · 4 valid

The version-2 escrowed SendZBC ranks by its floor per byte04-8-v2valid

Loading the test widget…

Declaring exactly the floor ranks the same04-8-v2-at-floorvalid

Loading the test widget…

Declaring 9,000,000 ranks the same04-8-v2-overpayvalid

Loading the test widget…

The version-3 SendZBC (189 signed bytes)04-8-v3valid

Loading the test widget…

Defects to match. None known (node-local).

9. The worst-case ZBC outflow of a transaction

Purpose. An upper bound on the ZBC a transaction can take from its payer, computed from the body and committed state; the account-group gate measures a limited member's spending with it (18, consensus from group_spend_invalid_block), and admission (§6 step 6) and block assembly (§10) sum it.

Inputs. The transaction; the height it is judged at (tip + 1 at admission, the block height in assembly and execution); state: a token's backing and supply (MintToken), a swap offer (AcceptSwapOffer), a market (PlaceOrder), an app (JoinApp); the parameters gateway_registration_cost (both chains 1,000,000,000) and market_creation_cost (both chains 5,000,000,000).

Output and effect. max_outflow (i64 ≥ 0, saturating at 2^63 − 1).

How to compute it. add(v) adds v when v > 0 and saturates on overflow; i64@n is the little-endian i64 at body offset n, read as 0 when the body has fewer than n + 8 bytes.

  1. QueueAttendance (9): return 0.
  2. total = max(fee, 0).
  3. By type: SendZBC, AddPrepaidStorage → add i64@0. SendZBCBatch → add every payment's amount (when the body parses). IssueToken → add i64@10 (backing). CreateTrigger, FundLongevity, FinanceToken → add i64@8. StoreFile → add i64@44. FundStoredFile → add i64@32. RegisterGateway → add the voted gateway_registration_cost, clamped to its governed bounds (1 .. 1,000,000,000,000). CreateMarket → add clamp(market_creation_cost, 1, 1,000,000,000,000) (the governed bounds). MintToken → when the token (i64@0) has backing > 0, supply > 0 and amount = i64@8 > 0: q = ceil(amount × backing / supply) in 128-bit, then q += (q >> 40) + 2, add q (saturated). NodeRegistration → add the body's locked balance; NodeRegistrationUpdate → add the whole new locked balance. LiquidPayment → add amount when token_id = 0. ScheduledTransfer → add per_fire × fires when funding_mode = 0 and token_id = 0 (saturating). CreateSwapOffer → add i64@8 when i64@0 = 0 (gives ZBC). AcceptSwapOffer → add the offer's want_amount when its want_token_id = 0. PlaceOrder → sell on a market whose base is ZBC: add amount (i64@17); buy on a market whose quote is ZBC with amount > 0 and price = i64@9 > 0: add amount × price / 100,000,000 (i128, saturated). CreateApp → add stake_amount when stake_token_id = 0. JoinApp → add the app's stake_amount when its stake token is ZBC. Everything else: nothing.
  4. Add the explicit survival payment of a token transaction (14).
  5. Add survival of a version-2 envelope when > 0.
  6. If an escrow part with a non-empty approver is present: add commission and the escrow rent (§4; rule uniform_fee_refund).
  7. A ScheduledTransfer in pull mode (funding_mode ≠ 0) adds nothing more: its draws are judged when they fire (rule schedule_fire_member_gate, 8, 18).
  8. (rule market_rent) PlaceOrder and CancelOrder add their market-rent contribution, ceil(fee × 2,000 / 10,000) = 20% of the fee, rounded up (the exact amount fed to the market is capped at twenty-four periods of rent, never more than this, so the bound holds, 15).

Rule activation. schedule_fire_member_gate, uniform_fee_refund and market_rent (step 8): at 0 on every chain. TransferTokenBatch moves no ZBC beyond its fee; it is a token-moving type for the group gate (18).

Rejections and errors. None of its own.

Vector. computed: input the version-2 escrowed SendZBC of 03 §1 on the TestNet (fee 5,000,000) → expected max_outflow = 5,000,000 + 100,000,000 (amount) + 10,000,000 (header survival) + 1,000 (commission) + 2 (escrow rent) = 115,001,002. A SetupAccountDataset with fee 5,000,000 → 5,000,000 (fee only). A PlaceOrder with fee 2,500,044 selling 7 ZBC on a market whose base is ZBC → 2,500,044 + 700,000,000 + the market-rent share ceil(2,500,044 × 2,000 / 10,000) = 500,009 → 703,000,053. A QueueAttendance → 0.

Test cases · §9

4 cases · 4 valid

The worst-case outflow of the version-2 escrowed SendZBC04-9-v2valid

Loading the test widget…

A SetupAccountDataset: the fee only04-9-datasetvalid

Loading the test widget…

A sell order of 7 ZBC on a ZBC-based market adds the amount and the market-rent share04-9-ordervalid

Loading the test widget…

A QueueAttendance takes nothing from a balance04-9-attendancevalid

Loading the test widget…

Defects to match. For a limited group member this bound is a consensus input (18), so its margins are part of the protocol: the MintToken margin (q >> 40) + 2 and the NodeRegistrationUpdate "whole new stake" over-estimate must be reproduced exactly; the estimate is deliberately above what the executor takes.

10. Block assembly: selecting transactions for a candidate (blocksmith policy)

Purpose. Which pooled transactions a blocksmith puts in its block and in what order; every rule here only chooses what this blocksmith includes, and the resulting block is judged by 19 alone.

Inputs. The pool (§6–§8), the candidate's timestamp (the blocksmith's clock at assembly) and height (tip + 1), committed state at the tip, the survival flag of the candidate's height, the two ceilings: max_transactions_per_block and max_block_size_bytes (consensus parameters; 2,000 and 524,288 on both live chains; compiled fallbacks 500 and 88,000 = 176 × 500), the node's load level.

Output and effect. An ordered list of transactions; the block's transaction order is this order (05). Four rules here are consensus (19): a block whose ceiling count exceeds max_transactions_per_block (each transaction counts 1, except a SendZBCBatch or TransferTokenBatch, which counts its number of actions; a SubmitStorageProofBatch counts 1); a block whose payload_length exceeds max_block_size_bytes, or, under rule block_size_serialized, whose serialized size (05 §10.1) does; a block that carries two transactions from one account — the sender address (01 §4), each group member its own slot — or two inner executions of one multisig account; and, under rule survival_mode, a block in survival mode carrying a frozen type (§6 step 2). Each is invalid.

How to compute it.

  1. max_count = min(max_transactions_per_block, load limit); the load limit is node-local: 500 normally, 300 / 200 / 100 at the health monitor's warning / critical / emergency levels, and at emergency the blocksmith makes an empty block. max_payload = max_block_size_bytes.
  2. Eligible = every pooled transaction such that: (rule foreign_carrier_bound) if it is a foreign carrier, its native id is not spent and it is the oldest pooled copy of that id (smallest arrival time, then smallest transaction id; a later copy is skipped with the note "ForeignCarrierReplayed"); its signed length ≤ max_payload; the candidate timestamp ≤ timestamp + W where W is the transaction's expiry window (3,600 s, or its stated version-3 expiry up to 86,400 s, 03 §5) and the candidate timestamp is not 0; while the candidate's height is in survival mode (or its survival state cannot be read), it is not of a frozen type (it stays pooled); the state mirrors of §6 step 5 pass at (height, candidate timestamp) — an Ethereum carrier's nonce must here equal the account's nonce exactly (so of queued nonces M and M+1 only M is taken), and a Solana or Bitcoin carrier's chain binding is re-judged for height — a failure leaves it pooled and writes an advisory note (§11), it may be mined later. 2b. Keep only each account's oldest eligible transaction: per sender address, the one with the smallest envelope timestamp, then the smallest id; the others stay pooled for later blocks, whatever they pay.
  3. Sort eligible by §8, then move the duty-lane transactions to the front in that same order, at most 2 × registry_size of them and one per node key, so a flood of floor-fee transactions cannot starve a node's attestation or storage proof; the fee-ordered rest follows.
  4. Walk the sorted list, stopping when the running ceiling count reaches max_count; a transaction is skipped (left pooled) when: its ceiling count would push the running count over max_count (keep looking for smaller ones); its length would push the running payload over max_payload (keep looking for smaller ones); it is a node-registration-family type (2, 258, 514, 770) and one of that family from the same sender bytes is already taken; its one-shot object key is already taken in this block — keys: DFSCreateFile / DFSUpdateFile / DFSDeleteFile → dfs|<sender hex>|<normalised path property>; SetupAccountDataset / RemoveAccountDataset whose property is in the dfs: namespace → the same key; CancelSchedule / ReassignSchedule → schedule|<id> (u64 at body 0); ApprovalEscrow → escrow|<32-byte escrow hash hex>; RegisterRelease / ReleaseAuthorityPropose / ReleaseAuthorityAccept / RevokeRelease → the single key release_authority; NodeRegistration → node|<32-byte node key hex>; it is a MultiSignature whose multisig account (the account of the inner bytes it carries, or of the pending record its signatures name) already has a wrapper taken in this block; its sender is a member of a group, or is an address, frozen by a group-management transaction (55–58) already taken in this block (the sender of that transaction, its group, the member or new controller it names, and their groups are frozen); it is a limited member's spend and the sum of §9 over the member's taken transactions plus this one exceeds what is left of its window (18); the sender gate: out = the §9 outflow (which already counts the header survival and an escrow's commission and rent, each once); the sum of out over the taken transactions of the same balance holder (the group for a member) plus this one exceeds the holder's confirmed balance (not the spendable one; credits in the same block are ignored) — skipped with the advisory note "sender cannot cover the ZBC this transaction takes with its confirmed balance".
  5. The blocksmith then drops any selected transaction whose id is already confirmed or duplicated in the list, and builds the block (05, 20). Under rule block_size_serialized, once the published receipts are attached, it drops transactions from the end of the list until the block's serialized size (05) is at most max_block_size_bytes.

Node-local (blocksmith policy): the 10-second minimum age (min_mempool_age_seconds, default 10) is not applied by the blocksmith, so a transaction admitted one second ago is eligible (only a diagnostic listing honours it). The load limit of 500 is what caps a reference blocksmith while the chain allows 2,000; a blocksmith making up to 2,000 is valid by consensus and decodes on every node (the transport cap is the larger of 500 and max_transactions_per_block, 05 §11). Expiry is judged at the blocksmith's clock at assembly, not at the block's final timestamp (20); I think a transaction can therefore be selected and be past its window when the block's timestamp lands later, which block validation refuses (03 §5), and the blocksmith's next candidate drops it.

Rule activation. group_spend_invalid_block (at 0 on every chain): the member sums are enforced here, and a refused member spend in a block makes the block invalid (18). dfs_moved_state and reassign_schedule_moved turn the second operation on a moved object into a paid no-op; the one-shot keys still defer it. survival_mode, block_size_serialized and foreign_carrier_bound (the oldest copy, the spent id, the nonce and the binding at the target height): active from height 0 on every chain. One transaction per account per block is a block-validity rule with no rule name, at every height. Between different accounts the first one wins, and a later transaction that no longer makes sense is a paid no-op that honest blocksmiths leave out; the one-shot object keys of step 4, the duty-lane reorder and the per-transaction expiry window are blocksmith policy only, not block rules.

Rejections and errors. None; skipped transactions stay pooled until expiry (§6).

Vector. computed: input a pool holding, from one sender, the version-3 SendZBC of 02 §1 (timestamp 1,793,509,627) and the version-2 escrowed SendZBC of 03 §1 (same timestamp, hash 4c337c69…, id from its first 8 bytes) → expected: one of them is taken (the smaller id, the timestamps being equal: 058c3078… gives id 8,615,971,514,693,487,621 and 4c337c69… gives 903,506,686,709,085,004, so the version-2 one), the other stays pooled for a later block. A block carrying both is invalid (19). The sender gate takes the version-2 one with a confirmed balance of exactly 115,001,002 (its §9 outflow: fee 5,000,000 + amount 100,000,000 + header survival 10,000,000 + commission 1,000 + escrow rent 2) and skips it with 115,001,001 ("sender cannot cover the ZBC this transaction takes with its confirmed balance"). Two pooled envelopes around one Ethereum carrier (the same native id, different ZooBC timestamps), arrivals 100 and 101 → the one that arrived at 100 is taken, the other is skipped with the note "ForeignCarrierReplayed".

Test cases · §10

4 cases · 4 valid

Two transactions of one sender with equal timestamps: the smaller id is taken04-10-oldestvalid

Loading the test widget…

With a confirmed balance of 115,001,001 the sender gate skips it04-10-sender-gatevalid

Loading the test widget…

With a confirmed balance of exactly 115,001,002 the sender gate takes it04-10-sender-gate-exactvalid

Loading the test widget…

Two pooled envelopes around one Ethereum carrier: the one that arrived first is taken04-10-carrier-oldestvalid

Loading the test widget…

Defects to match. None.

11. The rejection log and the status route (node-local observability)

Purpose. A client that got 202 and never sees its transaction mined can ask this node why.

Inputs. Every drop (stage, reason string, final/advisory) recorded by this node; the hash or id in the request.

Output and effect. A bounded, node-local map: at most 20,000 entries, each kept 6 hours, reason strings cut at 1,024 bytes. Stages: submission (refused by the HTTP route), admission (dropped between staging and the pool), eviction, expiry (staging or pool), block_assembly (advisory: skipped by the last candidate, still pooled), fork_restore (not re-admitted after a reorganisation). An advisory note never overwrites a final one; an admitted transaction's entry is forgotten. GET /api/v1/transactions/<id>/status (<id> as ZTX_…, 64 hex characters, or the decimal id) answers JSON with transaction_hash (and transaction_id when queried by number) and status: "staging"; "mempool" with mempool_position, mempool_size and, when an advisory note exists, last_skip_reason and last_skip_at; "confirmed" with block_height; "rejected" with reason, stage, rejected_at; or "not_found" with HTTP 404. Each carries a description sentence.

How to compute it. As stated; the reason strings are those of §6, §10 and the expiry messages ("expired in the mempool without being mined: its expiry window (W s after its timestamp) has ended", extended with "; block assembly skipped it: <advisory reason>" when one was recorded; "evicted from a full mempool by a transaction paying a higher fee per byte").

Rule activation. None.

Rejections and errors. None.

Vector (computed). Input: GET /api/v1/transactions/0000000000000000000000000000000000000000000000000000000000000000/status on a node that never saw that hash → expected HTTP 404 with "status":"not_found". Input: the status of a transaction mined at height 500 → "status":"confirmed", "block_height":500.

Test cases · §11

2 cases · 2 valid · 2 reference

The status of a hash the node never saw04-11-not-foundvalidreference

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

http
404
status
not_found
The status of a transaction mined at height 50004-11-confirmedvalidreference

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

status
confirmed
block_height
500

Defects to match. None (diagnostics).

12. The fee-estimate and fee-parameter routes

Purpose. A wallet reads the exact floor from a node instead of re-implementing §2; an air-gapped wallet reads the parameters once.

Inputs. GET /api/v1/blockchain/estimate-fee query parameters, all optional: type (default 1), body_length (default 8, capped at 1,048,576), message_length (default 0, capped), escrow (0/1), escrow_instruction_length, escrow_lock_seconds, escrow_kind (single default, request, cosigned, cosigned_request; anything else → 400), escrow_approver_length (default 36, clamped to 8–256), survival, survival_periods, actions (a batch type's action count, default 1, clamped to 1 .. the type's maximum: 25, 32, 1,000) and sender (any address form; it decides whether a QueueAttendance is a registered node's fee-free attestation or a queued node's paid attendance; an unreadable one → 400 "sender: …"). GET /api/v1/blockchain/fee-params takes nothing.

Output and effect. estimate-fee prices a transaction of that shape for height tip + 1 and answers minimum_fee (the floor of §2, or 0 for a duty that must declare exactly 0), duty (true for the duty lane's types), fee_exactly_zero (true when this transaction must declare 0), note (a sentence, for duties only: "A node duty declares a fee of exactly 0; with any other fee it is refused.", or the queued-attendance and pre-rule variants), batch_actions (for a batch), escrow_rent (§4, 0 when the rent is inside the floor or there is no escrow), overpay_refunded (true from uniform_fee_refund or by the refundability of §5 step 4; false for an exactly-zero duty), fee_above_minimum ("refunded", or "refused" for an exactly-zero duty), producer_share_bps (always 0), total_debit_excluding_amount = minimum_fee + escrow_rent + survival, one_zbc 100,000,000, timestamp, and the survival projection fields (13): survival, survival_active, transaction_version (2 when survival > 0), survival_minimum 10,000,000, survival_below_minimum, survival_payload_bytes, survival_rent_per_period, survival_periods, survival_free_until_height, survival_paid_through_height, and with survival_periods survival_periods_requested, survival_for_periods; with an escrow also escrow_kind and escrow_envelope_bytes. fee-params answers min_fee, min_node_registration_fee, fee_scale, initial_fee_scale, effective_min_fee, one_zbc, dataset_storage_cost_per_mib, storage_oracle_multiplier_ppm, min_payload_persistence_blocks, dataset_billing_period_blocks (the snapshot cycle, main_snapshot_interval), block_time_interval, token_persist_period_cost, token_free_persist_blocks, min_token_persist_blocks, account_rent_period_cost, account_rent_period_blocks (the snapshot cycle too), node_registration_minimum (the voted queue minimum; when the queue cannot be read, the entry minimum below falls back to it), node_registration_entry_minimum (the minimum a new registration must lock now: the higher of that and the queue-median share, 09), queue_median_fraction_bps; then producer_share_bps (always 0), overpay_kept (always false) and fee_above_minimum (always "refunded"). effective_min_fee is ceil(2,500,000 × fee_scale / 1,000,000). The floor estimate-fee reports includes the permanent_state_priced multiplier.

How to compute it. §2 and §4 on a transaction shaped from the query (body of body_length zero bytes, message of message_length bytes, an approver of escrow_approver_length bytes, an instruction of escrow_instruction_length bytes, timeout = now + escrow_lock_seconds, and for the multi-party kinds a 64-byte co-signature and/or a request id, which only change the envelope length).

Rule activation. As §2 and §4 at tip + 1.

Rejections and errors. escrow_kind outside the four values → HTTP 400 "escrow_kind must be single, request, cosigned or cosigned_request".

Vector (computed: what the two routes answer on a chain built from the TestNet genesis file, 11 registered nodes, before the first count block and with the queue empty). GET fee-params → {"min_fee":2500000,"min_node_registration_fee":2500000,"fee_scale":1000000,"initial_fee_scale":1000000,"effective_min_fee":2500000,"one_zbc":100000000,"dataset_storage_cost_per_mib":5000000,"storage_oracle_multiplier_ppm":1000000,"min_payload_persistence_blocks":17280,"dataset_billing_period_blocks":172800,"block_time_interval":15,"token_persist_period_cost":10000000,"token_free_persist_blocks":172800,"min_token_persist_blocks":5760,"account_rent_period_cost":1000000,"account_rent_period_blocks":172800,"node_registration_minimum":10000000000,"node_registration_entry_minimum":10000000000,"queue_median_fraction_bps":5000,"producer_share_bps":0,"overpay_kept":false,"fee_above_minimum":"refunded"}. GET estimate-fee (no parameters) → minimum_fee 2,500,044, duty false, fee_exactly_zero false, survival 0, survival_active true, transaction_version 1, survival_minimum 10,000,000, survival_below_minimum false, survival_payload_bytes 8, survival_rent_per_period 39, survival_periods 0, total_debit_excluding_amount 2,500,044, fee_above_minimum "refunded", producer_share_bps 0, escrow_rent 0, overpay_refunded true, one_zbc 100,000,000; survival_free_until_height and survival_paid_through_height are tip + 1 plus two cycles (345,601 at tip 0) and timestamp is the node's clock (13). type=41 → minimum_fee 0, duty true, fee_exactly_zero true, note "A node duty declares a fee of exactly 0; with any other fee it is refused.", fee_above_minimum "refused", overpay_refunded false. type=257&actions=3 → minimum_fee 7,500,132, batch_actions 3, survival_payload_bytes 137. escrow=1&escrow_instruction_length=19&escrow_lock_seconds=7200 → escrow_kind "single", escrow_envelope_bytes 76, escrow_rent 2, total_debit_excluding_amount 2,500,046. Invalid input: escrow=1&escrow_kind=bogus → HTTP 400 {"success":false,"error":"escrow_kind must be single, request, cosigned or cosigned_request","code":400}.

Test cases · §12

7 cases · 6 valid · 1 invalid · 5 reference

The TestNet fee parameters04-12-fee-paramsvalidreference

What the route answers on a chain built from the TestNet genesis file, 11 registered nodes, before the first count block, the queue empty.

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

value
{"min_fee":2500000,"min_node_registration_fee":2500000,"fee_scale":1000000,"initial_fee_scale":1000000,"effective_min_fee":2500000,"one_zbc":100000000,"dataset_storage_cost_per_mib":5000000,"storage_oracle_multiplier_ppm":1000000,"min_payload_persistence_blocks":17280,"dataset_billing_period_blocks":172800,"block_time_interval":15,"token_persist_period_cost":10000000,"token_free_persist_blocks":172800,"min_token_persist_blocks":5760,"account_rent_period_cost":1000000,"account_rent_period_blocks":172800,"node_registration_minimum":10000000000,"node_registration_entry_minimum":10000000000,"queue_median_fraction_bps":5000,"producer_share_bps":0,"overpay_kept":false,"fee_above_minimum":"refunded"}
The fee estimate with no parameters04-12-estimate-defaultvalidreference

survival_free_until_height and survival_paid_through_height are tip + 1 plus two cycles; timestamp is the node's clock.

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

minimum_fee
2500044
duty
false
fee_exactly_zero
false
survival
0
survival_active
true
transaction_version
1
survival_minimum
10000000
survival_below_minimum
false
survival_payload_bytes
8
survival_rent_per_period
39
survival_periods
0
total_debit_excluding_amount
2500044
fee_above_minimum
refunded
producer_share_bps
0
escrow_rent
0
overpay_refunded
true
one_zbc
100000000
survival_free_until_height_at_tip_0
345601
Its minimum_fee is the floor of the default SendZBC04-12-estimate-default-floorvalid

Loading the test widget…

A storage proof must declare exactly 004-12-estimate-dutyvalid

Loading the test widget…

The fee estimate of a storage proof (type=41)04-12-estimate-duty-routevalidreference

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

minimum_fee
0
duty
true
fee_exactly_zero
true
note
A node duty declares a fee of exactly 0; with any other fee it is refused.
fee_above_minimum
refused
overpay_refunded
false
The fee estimate of a three-payment batch (type=257&actions=3)04-12-estimate-batchvalidreference

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

minimum_fee
7500132
batch_actions
3
survival_payload_bytes
137
An unknown escrow_kind is refused04-12-bogus-kindinvalidreference

A stated value: there is nothing to compute. The statement is a refusal: the exact text a compatible node answers.

refusal
escrow_kind must be single, request, cosigned or cosigned_request
http
400
body
{"success":false,"error":"escrow_kind must be single, request, cosigned or cosigned_request","code":400}

Defects to match. None.

13. What in this document is consensus, and what is not

Mechanism Consensus? Why
§1 storage rent, §2 floor (incl. the permanent_state_priced registry multiplier, the rounding up and the batch sum), §3 fee scale value and its per-cycle count, §4 escrow rent yes block validity (fee ≥ floor; a duty's fee exactly 0) and balances
§5 charge, overpay refunded, fees out of a lock to the longevity pool, fee-free duties (duty_fee_free), not-collected, early exits yes balances after the block and the reward pool's inputs
§9 worst-case outflow yes for limited group members (18), policy elsewhere the gate that makes a block invalid uses it
§10 the two ceilings (count with batch actions, bytes / serialized size) and one transaction per account per block; the survival freeze of §6 step 2 yes block validity (19)
§6 staging cheap checks, admission order and reasons, §7 reservation, §8 order by the effective fee, expiry by each transaction's window, §10 selection (oldest per account), §11 log, §12 routes no node-local; a Follower may differ, a Blocksmith should match §10 to build acceptable blocks

An implementation at level L1 must implement §1–§5 exactly and §9 for the group gate; at L2 it should implement §6–§10 as written so its blocks are the ones the reference would build; §11 and §12 are what its clients expect of a Server (L3).

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