On this page
- §0 The area in one paragraph
- 1. The storage-rent primitive
- 2. The fee floor
- 2.1 The floor of a batch
- 3. The fee scale
- 4. The escrow rent
- 5. What is charged and refunded (consensus)
- 6. Admission: the checks a transaction passes before it is pooled (node-local)
- 7. The reservation of spendable balance (node-local)
- 8. Fee per byte and the pool's order (node-local)
- 9. The worst-case ZBC outflow of a transaction
- 10. Block assembly: selecting transactions for a candidate (blocksmith policy)
- 11. The rejection log and the status route (node-local observability)
- 12. The fee-estimate and fee-parameter routes
- 13. What in this document is consensus, and what is not
04 — Fees, admission and the mempool
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):
- If
cost_per_mib ≤ 0,multiplier_ppm ≤ 0orbytes = 0the result is 0. base = ceil_div(bytes, cost_per_mib, 1,048,576).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 MiB
Loading the test widget…
The rent of 16 bytes at 5,000,000 units per MiB
Loading the test widget…
The rent of 24 bytes at 5,000,000 units per MiB
Loading the test widget…
The rent of 76 bytes at 5,000,000 units per MiB
Loading the test widget…
The rent of 137 bytes at 5,000,000 units per MiB
Loading the test widget…
The rent of 1,048,576 bytes at 5,000,000 units per MiB
Loading the test widget…
The rent of 8 bytes at 100,000,000 units per MiB
Loading the test widget…
The rent of 75 bytes at 100,000,000 units per MiB
Loading the test widget…
The rent of 394 bytes at 100,000,000 units per MiB
Loading the test widget…
The rent of 8 bytes at 1 units per MiB
Loading the test widget…
The rent of 0 bytes at 5,000,000 units per MiB
Loading the test widget…
The fee-estimate route reports the same period rents at the TestNet prices
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.
weight = body_length + message_length(u64).period_rent = storage_rent(weight, cost_per_mib, multiplier_ppm)(§1).persistence_rent = ceil_div(period_rent, pb, period)withpb = min_payload_persistence_blocks(0 whenperiod = 0, which the cycle never is). 3b. (rulepermanent_state_priced) whenpersistence_rent > 0:persistence_rent ×= registry_size, the number of registered nodes at the previous block (never below 1), saturating atINT64_MAX: every node keeps these bytes, so the price is per replica. A node that cannot read the registry size prices the transaction atINT64_MAX(an unpayable floor, never at one replica).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).scaled_base = ceil_div(base_fee, fee_scale, 1,000,000)(fee_scalefrom §3, 1,000,000 = 1.0×; at the fee scale's floor of 1 unit the base is 3 units, never 0).- (rule
uniform_fee_refund) The escrow rent is not part of the floor: it is debited on its own at escrow creation (§4). floor = scaled_base + persistence_rent, checked: an overflow givesINT64_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
feeof 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
fee2,500,043 (one below the floor) → refused "Transaction fee too low"; a SubmitStorageProof (41) withfee1 → refused "Transaction fee must be exactly 0: a node duty declares a fee of exactly zero (this one declares 1)"; an Empty (0) transaction withfee0 → refused.
Test cases · §2
16 cases · 13 valid · 3 invalid
The floor of the default SendZBC at the TestNet parameters (11 registered nodes)
Loading the test widget…
The floor of a 24-byte body (a CreateApp) at the TestNet parameters
Loading the test widget…
A SendZBCBatch of three payments pays three one-action floors
Loading the test widget…
The floor with one registered node: body 8, message 0
Loading the test widget…
The floor with one registered node: body 16, message 0
Loading the test widget…
The floor with one registered node: body 65,536, message 256
Loading the test widget…
The floor on DevNet prices with one node: body 8
Loading the test widget…
The floor on DevNet prices with one node: body 394
Loading the test widget…
The scaled base fee at a fee scale of 2,000,000
Loading the test widget…
The scaled base fee at a fee scale of 500,000
Loading the test widget…
The scaled base fee at a fee scale of 1
Loading the test widget…
A SendZBC declaring one unit below its floor is refused
Loading the test widget…
A SendZBC declaring exactly its floor is accepted
Loading the test widget…
A storage proof (a node duty) with a fee of 1 is refused
Loading the test widget…
A storage proof declaring 0 is accepted
Loading the test widget…
An Empty transaction with a fee of 0 is refused
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:
- If no latest row exists, insert
(1,000,000, 0, 1). - If the block's height
his not a multiple ofL, stop. 2b. (rulesurvival_mode) If the chain is in survival mode ath(the flag the block is judged by,19), stop: no row is written, the cycle's reveals lapse. today= the latest row's value.nodes= the counted registered nodes as ofh − 1, in node-id order; whenquorum_flooris active and the registry floor is not met,nodesis empty.next = todaywhennodesis empty; otherwisenext= the bounded average of the votes:t = clamp(today, 1, 10^8), every registered node without a vote countst, 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 novern = max(|nodes|, |votes|)(rounded to nearest, 128-bit sum) and is clamped to[1, 10^8].- 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 block
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 scale
Loading the test widget…
Five registered nodes, three votes: each vote limited, the silent registered nodes count today's scale
Loading the test widget…
The same count block in survival mode writes no row
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.
- If there is no escrow part, or its approver is empty: 0.
esc_bytes= the length of the serialised escrow part:len(approver) + 8 + 8 + 4 + len(instruction) + 1, plus4 + len(co_signer_signature) + 8whenmulti_party = 1. (A ZBC approver is 36 bytes, so a single-party escrow with ann-byte instruction is57 + nbytes.)esc_period_rent = storage_rent(esc_bytes, cost_per_mib, multiplier_ppm)(§1).dur_secs = max(timeout − timestamp, 0)(i64);dur_blocks = ceil(dur_secs / 15)(u64; a part block of lock counts as a block).escrow_rent = ceil_div(epr, dur_blocks, period)(§1) withepr = esc_period_rentandperiodthe 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 prices
Loading the test widget…
The same escrow at DevNet prices
Loading the test widget…
The fee-estimate route's answer for that escrow (11 registered nodes)
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 refused
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.
- The charge. The type's executor debits the declared
feefrom 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 (rulefee_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 paysclamp(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+feeand event 47−feeon the sender (so the declared fee intotal_feenever 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, ruleattendance_fee_floor,09.) - 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_noopthis includes a fee vote from an account that is not a registered node's key.SettleAppthat changes nothing is free by design (16). - 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+feeand 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. - The overpay is refunded. If the overpay is refundable,
excess = fee − floor(block height), and whenexcess > 0the payer is creditedexcessand one event-22+excessrow is written. Refundable: every type fromuniform_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). - 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: fromuniform_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+feeand 47−feeare written and nothing moves. Step 4 and step 5 agree. - 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. - The block's pool (
21):total_feein the block header is the sum of the declared fees, and block validation requirestotal_feeto equal that sum exactly. The amount distributed istotal_fee + coinbase − Σ(event 22 of the block) + |Σ event 70|, plus (rulelongevity_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.21verifies 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 rest
Loading the test widget…
A fee-in-token TransferToken (a 17-byte body, the flag byte included) has the floor 2,500,099
Loading the test widget…
That transfer whose token's backing was drained earlier in the block, sender holding 6,000,000 ZBC
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 charged
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 TestNet
Loading the test widget…
The same transaction declaring exactly its floor gets no refund row
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:
- Pool not over its hard limit, 1.5 × its maximum (37,500 at the default 25,000):
"Transaction pool overloaded - try again later". 1b. (ruleforeign_carrier_bound) No pooled transaction holds the same native carrier id:"ForeignCarrierReplayed", a duplicate (DuplicateTransaction). - 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 (rulesurvival_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. - The local timestamp window (
03§5):timestamp + W < now, withWthe 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". - 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>". - 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 keyof 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 sinceadmission_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). - 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)". - NodeRegistration whose node public key (body bytes 0–31) is registered and not Deleted:
"NodeAlreadyRegistered". - 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". - The pool does not already hold the hash:
"Transaction already in pool". - 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)". - 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). - 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". - 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 window
Loading the test widget…
The same transaction submitted more than an hour before its timestamp
Loading the test widget…
The same transaction inside its window
Loading the test widget…
A 51st pending transaction of one sender
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 window
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 mode
Loading the test widget…
An AttestEvent (the bridge category) in the same state
Loading the test widget…
A SendZBC in the same state is admitted
Loading the test widget…
A carrier with nonce 7 while nonce 5 is pooled and none with 6 is refused
Loading the test widget…
The same with nonce 6 is admitted and pooled behind the first
Loading the test widget…
At block assembly the nonce-6 carrier waits: the account nonce is still 5
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 survival
Loading the test widget…
The same with one unit less spendable
Loading the test widget…
The same with commission -1 is refused
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 byte
Loading the test widget…
Declaring exactly the floor ranks the same
Loading the test widget…
Declaring 9,000,000 ranks the same
Loading the test widget…
The version-3 SendZBC (189 signed bytes)
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.
- QueueAttendance (
9): return 0. total = max(fee, 0).- By type: SendZBC, AddPrepaidStorage → add
i64@0. SendZBCBatch → add every payment's amount (when the body parses). IssueToken → addi64@10(backing). CreateTrigger, FundLongevity, FinanceToken → addi64@8. StoreFile → addi64@44. FundStoredFile → addi64@32. RegisterGateway → add the votedgateway_registration_cost, clamped to its governed bounds (1 .. 1,000,000,000,000). CreateMarket → addclamp(market_creation_cost, 1, 1,000,000,000,000)(the governed bounds). MintToken → when the token (i64@0) hasbacking > 0,supply > 0andamount = i64@8 > 0:q = ceil(amount × backing / supply)in 128-bit, thenq += (q >> 40) + 2, addq(saturated). NodeRegistration → add the body's locked balance; NodeRegistrationUpdate → add the whole new locked balance. LiquidPayment → add amount whentoken_id = 0. ScheduledTransfer → addper_fire × fireswhenfunding_mode = 0andtoken_id = 0(saturating). CreateSwapOffer → addi64@8wheni64@0 = 0(gives ZBC). AcceptSwapOffer → add the offer'swant_amountwhen itswant_token_id = 0. PlaceOrder → sell on a market whose base is ZBC: addamount(i64@17); buy on a market whose quote is ZBC withamount > 0andprice = i64@9 > 0: addamount × price / 100,000,000(i128, saturated). CreateApp → addstake_amountwhenstake_token_id = 0. JoinApp → add the app'sstake_amountwhen its stake token is ZBC. Everything else: nothing. - Add the explicit survival payment of a token transaction (
14). - Add
survivalof a version-2 envelope when > 0. - If an escrow part with a non-empty approver is present: add
commissionand the escrow rent (§4; ruleuniform_fee_refund). - A ScheduledTransfer in pull mode (
funding_mode ≠ 0) adds nothing more: its draws are judged when they fire (ruleschedule_fire_member_gate,8,18). - (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 SendZBC
Loading the test widget…
A SetupAccountDataset: the fee only
Loading the test widget…
A sell order of 7 ZBC on a ZBC-based market adds the amount and the market-rent share
Loading the test widget…
A QueueAttendance takes nothing from a balance
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.
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.- 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 + WwhereWis 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 forheight— 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 envelopetimestamp, then the smallest id; the others stay pooled for later blocks, whatever they pay. - Sort eligible by §8, then move the duty-lane transactions to the front in that
same order, at most
2 × registry_sizeof 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. - 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 overmax_count(keep looking for smaller ones); its length would push the running payload overmax_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 thedfs: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 keyrelease_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 ofoutover the taken transactions of the same balance holder (the group for a member) plus this one exceeds the holder's confirmedbalance(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". - The blocksmith then drops any selected transaction whose id is already confirmed or duplicated in
the list, and builds the block (
05,20). Under ruleblock_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 mostmax_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 taken
Loading the test widget…
With a confirmed balance of 115,001,001 the sender gate skips it
Loading the test widget…
With a confirmed balance of exactly 115,001,002 the sender gate takes it
Loading the test widget…
Two pooled envelopes around one Ethereum carrier: the one that arrived first is taken
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 saw
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 500
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).
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 parameters
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 parameters
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 SendZBC
Loading the test widget…
A storage proof must declare exactly 0
Loading the test widget…
The fee estimate of a storage proof (type=41)
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)
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 refused
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.