On this page
- §0 The area in one paragraph
- 1. The state of this area and its read views
- 2. SetupAccountDataset (3) to an ordinary recipient: create an object or rewrite its row
- 3. Writing and removing a record of a dataset
- 4. RemoveAccountDataset (259) of an ordinary row
- 5. AddPrepaidStorage (9)
- 6. TransferDataset (42) and AcceptDataset (44)
- 7. SetDatasetPolicy (43)
- 8. Funding a dataset: the deposit list and the unconsumed parts
- 9. DeleteDataset (45): the vote and the deletion
- 10. DFS files: the metadata record, the path rules and the chunks
- 11. DFSCreateFile (8), DFSUpdateFile (264), DFSDeleteFile (520)
- 12. Dataset rent: the per-block billing step
- 13. The reserved namespaces
- 14. Ledger rows and the consensus/local split
10 — Datasets, dataset objects, the DFS file layer and dataset rent
Out of scope the stored-file system StoreFile / FundStoredFile / SubmitStorageProof and its rent (11); account rent (13; every ZBS_ address is exempt from it, 07 §3.2); how the longevity pool pays out (21); the generic fee floor and refund (04 §2, §5); how a group link re-keys a member's rows (18); the full table schemas (07); the complete HTTP API (31)
§0 The area in one paragraph
A dataset is one object in which accounts keep records: text key-value pairs (a key of at
most 256 bytes, a value of at most 4,096 bytes). The object is created by the first ordinary
SetupAccountDataset of an account and is named by that transaction's 32-byte hash, the
object id; it has an owner, a two-step transferable ownership, a mode (0 private: only the
owner writes; 1 open: anyone writes, each in its own key space; 2 public: anyone writes, one shared
key space, first come first served) and a deposit address 0A000000 ‖ object_id (account type
10, text ZBS_…). A record is written or removed by a SetupAccountDataset or RemoveAccountDataset
whose envelope recipient is the dataset's ZBS_ address; a record belongs to the account that
wrote it and only that account edits or removes it. Anyone can fund a dataset by paying ZBC to its
deposit address; every such payment is recorded in order with its payer, and rent consumes the
oldest money first, so each funder's unconsumed part is defined at every height. Once per billing
period (the snapshot cycle) the chain charges each object a rent proportional to the bytes of
all its records, first from the deposit, then from the owner (its prepaid storage first, then its
balance); the rent goes to the longevity pool, and an object nobody can pay for has its records
deactivated. Deleting a dataset is a vote of its owner and of the funders who still have money
on it, carried by more than half of that money; the deletion deactivates every record, takes each
record's bytes off its own writer's storage counter and sweeps the deposit to the longevity pool
(ZBC is never refunded from a dataset). The DFS layer stores a file as a row in the reserved
dfs: namespace whose value is a hex-encoded metadata record; the content itself lives in each
node's local chunk store, not in consensus state; payments into a file's deposit address are
refunded per payer when the file is deleted. Four property prefixes carry rules (dfs:,
dfs:dir:, tokenicon:, inv:). Every row, object, vote and deposit entry is consensus state
(07 §1); the ledger rows, the chunk store and the read views are not.
1. The state of this area and its read views
Purpose. The rows every mechanism below reads and writes, and how a client reads them.
Output and effect. Five tables (full columns and keys in 07 §1):
account_dataset— one row family per (setter, recipient, property), versioned byheight(07§2: a write at height h marks the key's older rowslatest = 0and inserts the row at h; a second write of the same key in the same block replaces the row at h). Columns that matter here:value(text, stored exactly as sent),is_active(1 = the record or row exists; 0 = a removed or deactivated version),creating_tx_hash(32 bytes, the object the row bills against),object_id(32 bytes; when a writer leaves it empty it is set tocreating_tx_hash),added_by(the account that wrote the row; when a writer leaves it empty it is set to the setter),last_billing_height(the row's rent clock). A row is active when its newest version hasis_active = 1.- An ordinary row: setter = the sender, recipient = any account that is not a
ZBS_address (the sender itself in practice, or empty),creating_tx_hash = object_id= the hash of the transaction that created the object. - A record of a dataset: setter = the record's writer (its owner), recipient = the
dataset's
ZBS_address,creating_tx_hash = object_id= the dataset's object id,added_by= the writer. - A DFS file: setter = recipient = the file's owner, property
dfs:‖ path, the value of §10.
- An ordinary row: setter = the sender, recipient = any account that is not a
dataset_object— keyed byobject_id, versioned byheight:owner_account(the typed owner; empty = deleted, a tombstone),pending_owner(empty = none),manage_mode(0 private, 1 open, 2 public; a new object is 0; −1 marks a billing-only object row that the rent step writes for an object that had none, §12, and reads as private),last_billing_height(the object's one rent clock, ruledataset_rent_object_clock; 0 until the first charge). A dataset is live when its newest row exists and has a non-empty owner. A DFS file has nodataset_objectrow until its first rent charge gives it a billing-only one (§12).file_deposit— the payments into a deposit address, in arrival order:(object_id, seq, payer_address, amount, block_height),seq= 0, 1, 2, … per object (the nextseqis one more than the highest of the object, 0 for the first),payer_address= the typed account that paid (resolved to its balance holder: a group for a linked member) or empty when the crediting path names no payer. Entries are written once, never changed, never pruned.dataset_delete_vote—(object_id, voter_address, height, latest), keyed by (object, voter): one row per standing vote to delete a dataset (§9). The deletion itself does not touch these rows; they are removed only by a reorganisation (07§10).- The account row (
account_balance,07§3):dataset_storage_bytes(bytes of the rows this account set; adjusted by §2–§4, §9, §11; no rule decides on it),prepaid_storage_balance(§5, pays the account's own rents first).
The deposit address of an object or a DFS file is the 36 bytes 0A000000 ‖ object_id; its text
form is the 01 §5 codec with prefix ZBS. It is an ordinary account row: a SendZBC (or any ZBC
credit) to it credits it (type 10 receives ZBC, 08 §3); it pays no account rent (07 §3.2); it
never signs, so nothing spends from it except the rent step of §12, the deletion of §9, the file
refund of §11 and the sweeps to the longevity pool.
Funding record. Every ZBC credit of amount > 0 that lands on a 36-byte address beginning
0A000000 appends a file_deposit entry for its object id when, at that moment, the object id
is either (a) the object_id of an active newest account_dataset row whose property begins
dfs:/ (a live DFS file), or (b) a live dataset (newest dataset_object row with a non-empty
owner). The payer is the one the crediting path names: SendZBC, every payment of a SendZBCBatch, a
schedule fire, a split-policy share and a trigger name their payer; a path that names none (for
example a token's expiry payout) writes an empty payer. A credit to any other ZBS_ address (a
deleted dataset, a removed file, an address nobody created) is credited but not recorded.
Read views (node API, JSON; errors are {"success":false,"error":"<text>","code":<status>}):
GET /api/v1/objects/<object_id>—object_idexactly 64 hex digits (else 400object_id must be 64 hex); nodataset_objectrow → 404object not found(a deleted dataset still answers, with an empty owner). Answer, keys in this order:object_id(the request's hex),zbs_address(lowercase hex of the 36 deposit-address bytes),owner(theZBC_text of the owner's key when it is a 36-byte account, else hex),pending_owner(hex,""for none),manage_mode(integer),mode("open"for 1,"public"for 2,"private"otherwise),own_deposit_balance(the deposit address's balance, 0 when it has no row),size_bytes(Σ |property| + |value| over the active rows whoseobject_idis this object),monthly_fee(§12's formula oversize_bytesat the chain's own price: theconsensus_parametersvalues ofdataset_storage_cost_per_mibandstorage_oracle_multiplier_ppm, each the compiled default 100,000,000 / 1,000,000 only when its row is missing, as the billing reads them),entries(those rows in ascendingheight, each{property, value, value_bytes, owner (the setter, hex), added_by (hex), height}),funders(§8's per-payer list without the empty payer, each{account (hex), paid, unconsumed}),delete_votes(the standing voters, hex, in byte order).GET /api/v1/dataset-address/<id>—<id>is aZBS_text (else 400Invalid ZBS_ address) or 64 hex digits with an optional0x(else 400tx hash must be 32 bytes (64 hex)). Answer:tx_hash(lowercase hex),zbs_address(text),account_hex(lowercase hex of the 36 bytes),balance,exists(an account row exists),payers(§8's list without the empty payer, each{address (hex), paid, unconsumed}),no_payer_unconsumed(the empty payer's unconsumed part, 0 when none).GET /api/v1/accounts/<address>/datasets[?property=<prefix>]—<address>aZBC_text or hex; the newest active rows whoseheight≤ the confirmed height (31) where the address is the setter or the recipient (a 32-byte hex query also matches00000000 ‖ key), optionally only properties beginning with the prefix, in descendingheight; answer{"address", "datasets":[{setter, recipient, role ("setter" | "recipient" | "both"), property, value, value_b64, height, creating_tx_hash}]}. Querying a dataset'sZBS_address in hex lists its records (rolerecipient). Errors 400Invalid ZBC address,Invalid address encoding.
How to compute it. The deposit address is a concatenation; everything else is a lookup of the
newest row of a key. monthly_fee is one charge of §12's rent for the object's current bytes at
the chain's price (31 §6), the amount the billing step charges per period.
Rule activation. None.
Rejections and errors. As listed for the read views; none for the state.
Vector. computed. INPUT: a dataset whose object id is
567A1B2FAEFAA85A1446B93299DFAFAF29E0E228C2363F69487C8C337521F181, created at height 141 by the
owner 000000007D8BD8A41DCEEA4986D1E99DFE99CA9303874B7C3AAC7EEECD60A82F61902572 with one record
wallet.release of 292 value bytes, mode 0, never funded, not yet charged, on a chain at the DevNet
price (dataset_storage_cost_per_mib 100,000,000, storage_oracle_multiplier_ppm 1,000,000);
GET /api/v1/objects/567a1b2faefaa85a1446b93299dfafaf29e0e228c2363f69487c8c337521f181
→ EXPECTED OUTPUT {"object_id":"567a1b2f…f181","zbs_address":"0a000000567a1b2faefaa85a1446b93299dfafaf29e0e228c2363f69487c8c337521f181","owner":"ZBC_PWF5RJA5_Z3VETBWR_5GO75GOK_SMBYOS34_HKWH53WN_MCUC6YMQ_EVZAAFOQ","pending_owner":"","manage_mode":0,"mode":"private","own_deposit_balance":0,"size_bytes":306,"monthly_fee":29183,"entries":[{"property":"wallet.release","value":"…","value_bytes":306,"owner":"000000007d8bd8a41dceea4986d1e99dfe99ca9303874b7c3aac7eeecd60a82f61902572","added_by":"000000007d8bd8a41dceea4986d1e99dfe99ca9303874b7c3aac7eeecd60a82f61902572","height":141}],"funders":[],"delete_votes":[]}
(306 = 14 + 292 bytes; 29,183 = ⌈306 × 100,000,000 / 1,048,576⌉, then ⌈29,183 × 1,000,000 /
1,000,000⌉). The same object at the TestNet price (5,000,000 per MiB) answers "monthly_fee":1460
(⌈306 × 5,000,000 / 1,048,576⌉ = ⌈1,459.12⌉).
INPUT GET /api/v1/dataset-address/567A1B2FAEFAA85A1446B93299DFAFAF29E0E228C2363F69487C8C337521F181
on a chain where nothing was ever paid to that address → EXPECTED OUTPUT
{"tx_hash":"567a1b2f…f181","zbs_address":"ZBS_KZ5BWL5O_7KUFUFCG_XEZJTX5P_V4U6BYRI_YI3D62KI_PSGDG5JB_6GA23DX7","account_hex":"0a000000567a1b2f…f181","balance":0,"exists":false,"payers":[],"no_payer_unconsumed":0}.
Invalid: INPUT GET /api/v1/objects/00 → 400 {"success":false,"error":"object_id must be 64 hex","code":400};
INPUT GET /api/v1/objects/0000…0000 (64 zeros, no such object) → 404 {"success":false,"error":"object not found","code":404}.
Test cases · §1
8 cases · 6 valid · 2 invalid · 3 reference
GET /api/v1/objects of the dataset of §2 at the DevNet price
Loading the test widget…
The same view at the TestNet price
Loading the test widget…
GET /api/v1/dataset-address of the same object, nothing ever paid to it
A stated value: there is nothing to compute. A compatible node shows the same value.
- zbs_address
ZBS_KZ5BWL5O_7KUFUFCG_XEZJTX5P_V4U6BYRI_YI3D62KI_PSGDG5JB_6GA23DX7- account_hex
0a000000567a1b2faefaa85a1446b93299dfafaf29e0e228c2363f69487c8c337521f181- balance
0- exists
false- payers
[]- no_payer_unconsumed
0
The deposit address of the TestNet object 567A…F181
Loading the test widget…
The deposit address of the object id 32 × 00
Loading the test widget…
The view's monthly_fee of 306 bytes at the DevNet price
Loading the test widget…
GET /api/v1/objects/00 is refused
A stated value: there is nothing to compute. The statement is a refusal: the exact text a compatible node answers.
- refusal
{"success":false,"error":"object_id must be 64 hex","code":400}
GET /api/v1/objects of 64 zeros is not found
A stated value: there is nothing to compute. The statement is a refusal: the exact text a compatible node answers.
- refusal
{"success":false,"error":"object not found","code":404}
Defects to match. (1) An ordinary row may name any recipient: the
recipient's consent is never asked, and the recipient's listing shows the row (role tells which
side wrote it).
2. SetupAccountDataset (3) to an ordinary recipient: create an object or rewrite its row
Purpose. Write a row that is not a record of an existing dataset; the first such write of a key creates a dataset object owned by the sender.
Inputs. The envelope (sender, recipient that is not a ZBS_ address — empty allowed, block
height h, transaction hash, fee). Body, little-endian:
| Offset | Length | Field | Encoding |
|---|---|---|---|
| 0 | 4 | property_length p |
u32, ≤ 256 |
| 4 | p | property |
bytes, stored as text |
| 4+p | 4 | value_length v |
u32, ≤ 4,096 |
| 8+p | v | value |
bytes, stored as text |
| 8+p+v | any | (not read) | trailing bytes are allowed, hashed and charged (04 §2), never read |
Category DataStorage (08 §11).
Output and effect. In this order:
- Foreign row (rule
dataset_owner_only_write): when the newest row of (sender, recipient, property) exists, is active, and its object (itsobject_id, else itscreating_tx_hash) has adataset_objectrow whose owner is not the same account as the sender (07§3, "the same account"), the transaction is a paid no-op: the fee is charged (row event 1) when the sender can pay, nothing else changes. (A missing row, an inactive row, a row with no object id, or an object id with nodataset_objectrow is not foreign.) - The fee is debited (row event 6, −fee); a sender that cannot pay makes the block invalid.
- Keeps binding: when the newest row of the key is active and has a
creating_tx_hash, the new version keeps that row'screating_tx_hash,last_billing_height,object_idandadded_by(the same object; ruledataset_update_keeps_deposit). Otherwise the new row getscreating_tx_hash = object_id= this transaction's hash,last_billing_height = h,added_by= the sender, and, when nodataset_objectrow exists for this hash, a new object(object_id = hash, owner = sender, pending_owner empty, manage_mode 0, height h)is written. - The row
(sender, recipient, property)at h:value,is_active = 1. - The sender's
dataset_storage_bytes: −(old p + v) when an active row was replaced, then +(p + v). (A failure of this counter update does not fail the block.)
Then the fee settlement of 04 §5.
How to compute it. Stateless (admission and block validation): body ≥ 8 bytes
("SetupAccountDataset body too short"); property_length ≤ 256 and within the body ("Invalid SetupAccountDataset property length"); property_length > 0 ("SetupAccountDataset: the property name cannot be empty"); the property does not begin dfs: ("SetupAccountDataset: the dfs: property namespace is written by DFS transactions only"); the value length present ("SetupAccountDataset missing value length"), ≤ 4,096 and within the body ("Invalid SetupAccountDataset value length");
the namespace shapes of §13. Admission also refuses the foreign row of step 1:
"Dataset: the object of this entry (<property>) now belongs to another account; only its owner may write or remove it".
Rule activation. dataset_owner_only_write, dataset_property_nonempty,
dfs_namespace_reserved, dataset_update_keeps_deposit: active from height 0 on every chain.
Rejections and errors. The stateless checks refuse admission and make a block invalid; the foreign row is refused at admission and a paid no-op in a block; an unpayable fee in step 2 makes the block invalid.
Vector. computed. INPUT: sender = recipient = 00000000 7D8BD8A4…61902572 (the release
authority), fee 5,000,000, body (386 bytes) = 0E000000 ‖ 77616C6C65742E72656C65617365
(wallet.release, 14) ‖ 24010000 (292) ‖ a 292-byte JSON value ‖ a 72-byte tail (not read),
mined at height 141 in a transaction whose hash is
567A1B2FAEFAA85A1446B93299DFAFAF29E0E228C2363F69487C8C337521F181. EXPECTED OUTPUT: row
(7D8B…, 7D8B…, "wallet.release") at height 141, active, creating_tx_hash = object_id = 567A1B2F…F181, added_by = the sender, clock 141; object 567A1B2F…F181 owner = the sender,
mode 0, clock 0; storage counter +306; the fee charged is the floor of 04 §2 for 386 body bytes
and the rest of the 5,000,000 refunded (04 §5). computed: body
0300000062696F0500000068656C6C6F = property bio, value hello (p + v = 8).
Invalid: body 0000000005000000 68656C6C6F (empty property) → "SetupAccountDataset: the property name cannot be empty"; body 040000006466733A00000000 (property dfs:, empty value) → "SetupAccountDataset: the dfs: property namespace is written by DFS transactions only".
Test cases · §2
9 cases · 6 valid · 3 invalid
A SetupAccountDataset of wallet.release creates the object of its own hash
Loading the test widget…
The 386-byte body of that transaction: 306 bytes counted, the 72-byte tail not read
Loading the test widget…
The body of property bio, value hello
Loading the test widget…
Trailing bytes after the value are kept in the body (and not read)
Loading the test widget…
The bio body passes the stateless checks
Loading the test widget…
The bio body with a 72-byte tail passes
Loading the test widget…
An empty property name is refused
Loading the test widget…
A property in the dfs: namespace is refused
Loading the test widget…
A 7-byte body is refused
Loading the test widget…
Defects to match. (1) Trailing bytes after the value are accepted and charged but never read. (2) A rewrite of an inactive row (a removed property) binds to the new hash and creates a new object; the old object keeps its deposit. (3) An empty recipient is a valid row key.
3. Writing and removing a record of a dataset
Purpose. Add, replace or remove one record in a live dataset, by the rules of its mode.
Inputs. A SetupAccountDataset (3) or RemoveAccountDataset (259) whose envelope recipient is a
ZBS_ address (36 bytes beginning 0A000000; its last 32 bytes are the object id); the body of
§2 (for a removal the value is not used); the dataset's newest dataset_object row; the records.
Output and effect. The record decision (the same at admission and execution), first match
wins, <k> = the property, ZBS_… = the text of the object id:
- No live dataset at the object id →
Dataset: no dataset at ZBS_…. - Write: mode is neither 1 nor 2 and the sender's bytes differ from the owner's →
Dataset: ZBS_… is private; only its owner writes records. Mode 2 and an active record<k>of this dataset exists whose setter differs from the sender →Dataset: the record '<k>' of ZBS_… belongs to another account; only its owner may write or remove it. Otherwise allowed. - Remove: the sender has an active row (sender,
ZBS_address,<k>) → allowed, in every mode (a record's writer always removes its own record, private mode included). Else mode 2 and an active record<k>owned by another setter → the "belongs to another account" text. Else →Dataset: no record '<k>' of yours in ZBS_….
"An active record <k> of this dataset" is the active newest account_dataset row with
object_id = the object id and property <k> with the lowest version height (this includes
the dataset's creating ordinary row of §2, whose object_id is the same object). A failed read is
a fault that fails the block on that node, never an answer.
When allowed: the fee is debited (event 6 for a write, 7 for a removal; unpayable → block
invalid); the row (sender, ZBS_ address, <k>) gets a version at h with value (empty for a
removal), is_active = 1 for a write / 0 for a removal, creating_tx_hash = object_id = the
dataset's object id, added_by = the sender, last_billing_height = the replaced active row's
clock, else h; the sender's dataset_storage_bytes −(old p + v) when an active row was replaced,
+(p + v) for a write. No dataset_object row is written. When refused: a paid no-op (fee row
event 1 when the sender can pay; nothing else). Then 04 §5.
In mode 1 (open) two writers' records of the same key are two rows (the row key includes the setter); in mode 2 (public) the key space is shared.
How to compute it. The stateless checks of §2 apply first (for a removal, those of §4); then the record decision; then the writes.
Rule activation. None beyond §2's (the dataset model is in force on every chain);
dataset_rent_object_clock (the owner of a shared key, Defects (1)): active from height 0 on
every chain.
Rejections and errors. The record decision's texts are admission refusals; in a block the same cases are paid no-ops; a failed read is a fault that fails the block on that node.
Vector. computed (the dataset of §2: object 567A1B2F…F181, owner
00000000 7D8BD8A4…61902572, mode 0). INPUT: SetupAccountDataset from another account
00000000 BCCB8082…A393B4D6, recipient 0A000000567A1B2FAEFAA85A1446B93299DFAFAF29E0E228C2363F69487C8C337521F181,
body 0300000062696F0500000068656C6C6F (bio = hello) → EXPECTED: refused at admission
Dataset: ZBS_KZ5BWL5O_7KUFUFCG_XEZJTX5P_V4U6BYRI_YI3D62KI_PSGDG5JB_6GA23DX7 is private; only its owner writes records. After the owner's SetDatasetPolicy to mode 1 (§7) the same transaction at
height h → EXPECTED: row (00000000 BCCB…, 0A000000 567A…, bio) = hello, active,
object_id = creating_tx_hash = 567A1B2F…F181, clock h; the writer's storage counter +8; fee row
event 6. INPUT: RemoveAccountDataset from 00000000 BCCB…, same recipient, body
0300000062696F00000000 → EXPECTED: inactive version of that row at the block's height, value
empty, counter −8, fee row event 7. Invalid: INPUT the same removal from a third account →
Dataset: no record 'bio' of yours in ZBS_KZ5BWL5O_7KUFUFCG_XEZJTX5P_V4U6BYRI_YI3D62KI_PSGDG5JB_6GA23DX7;
INPUT a write to 0A000000 ‖ 32 × 00 → Dataset: no dataset at ZBS_AAAAAAAA_AAAAAAAA_AAAAAAAA_AAAAAAAA_AAAAAAAA_AAAAAAAA_AAABMDL6.
Test cases · §3
9 cases · 5 valid · 4 invalid
Another account writing to a private dataset is refused
Loading the test widget…
The same write after the owner opens the dataset
Loading the test widget…
The writer removes its own record
Loading the test widget…
A third account cannot remove that record
Loading the test widget…
In a public dataset another account's record of the key is taken
Loading the test widget…
A write to the deposit address of 32 × 00 finds no dataset
Loading the test widget…
A record write to a ZBS_ recipient passes the stateless checks
Loading the test widget…
The write after the owner opens the dataset: the writer's record, bound to the dataset
Loading the test widget…
The writer removes its record: an inactive version, the counter back to 0
Loading the test widget…
Reference behaviour to match
Defects to match. (1) ⚠ DEFECT: after an owner switches an open dataset to public, two writers
may hold active records of one key; the "owner" of that shared key is the setter of the active
record with the lowest version height, and an ordinary rewrite moves a record's version to h,
so the writer that rewrites last loses the key to the other; moreover a rent charge (§12) writes a
new version of every active record of the object at the charging height, so after the first charge
both records sit at one height and the owner is whichever row the store yields first for that
height (the reference yields them in the order its billing wrote them, ascending by setter
address — I think; an implementation that must agree takes the lowest setter address among equal
heights). (2) A record's inactive version keeps creating_tx_hash = object_id = the object id
and its added_by, like an ordinary removal under dataset_rent_object_clock (§4).
4. RemoveAccountDataset (259) of an ordinary row
Purpose. Deactivate an ordinary row (or a DFS file's dfs: row).
Inputs. The body of §2 (the value is stored in the inactive version, not compared); the
envelope recipient (not a ZBS_ address).
Output and effect. In order:
- A group member acting for its group on an active
dfs:row of the group: allowed only for the group's controller or the row'sadded_by(§11); anyone else → paid no-op. - Foreign row (rule
dataset_owner_only_write, as §2 step 1) → paid no-op. - The fee is debited (row event 7; unpayable → block invalid).
- An inactive version of (sender, recipient, property) at h carrying the body's value and, when
the key had a newest version (active or not), that version's
creating_tx_hash,object_id,added_byandlast_billing_height(ruledataset_rent_object_clock; a property never set gets an emptycreating_tx_hash, clock 0, and soobject_idempty andadded_by= the setter); when the newest version was active, the sender'sdataset_storage_bytes−(its p + v). No existence check: removing a property that was never set writes an inactive row. When the object has a billing-only object row (§12) and no active row is left, that row is tombstoned (owner and pending owner emptied). - When the removed row was active: let
obj= itsobject_id(else itscreating_tx_hash). Ifobjnow has no active row and has no live dataset (nodataset_objectrow, or one with an empty owner), the deposit address ofobjis settled by the file refund of §11 (each recorded payer gets its unconsumed part back, the rest goes to the longevity pool). An object with a livedataset_objectrow keeps its deposit and its record: emptying a dataset does not end it.
Then 04 §5.
How to compute it. Stateless: body ≥ 8 ("RemoveAccountDataset body too short"), property ≤ 256
and within the body ("Invalid RemoveAccountDataset property length"), value length present
("RemoveAccountDataset missing value length"), ≤ 4,096 and within the body ("Invalid RemoveAccountDataset value length"). Admission refuses step 1 ("Account group: only the group's controller or the file's original owner may change or delete the group's file <path>") and step 2
(the text of §2).
Rule activation. dataset_owner_only_write, survival_field, dataset_rent_object_clock:
active from height 0 on every chain.
Rejections and errors. As listed.
Vector. computed. INPUT: the owner of the ordinary row (A, A, bio = hello, object O,
clock c, mode 0, deposit 0) sends RemoveAccountDataset, recipient A, body
0300000062696F00000000 → EXPECTED: inactive version at h (value empty, creating_tx_hash = object_id = O, added_by = A, clock c), counter −8, fee row event 7; object O keeps its owner
and stays live (step 5 does nothing). Invalid: body 03000000 62696F (7 bytes) →
"RemoveAccountDataset body too short".
Test cases · §4
3 cases · 2 valid · 1 invalid
The removal body of bio passes the stateless checks
Loading the test widget…
A 7-byte removal body is refused
Loading the test widget…
The owner removes its ordinary row: the inactive version keeps the object, its writer and its clock
Loading the test widget…
Defects to match. (1) A removal of a property that was never set is mined and charged.
5. AddPrepaidStorage (9)
Purpose. Move ZBC into the account's prepaid-storage field, which pays its own rents first.
Inputs. Body: amount (8, i64 LE, > 0).
Output and effect. Sender −(amount + fee): rows event 1 (−fee) and event 68 (−amount); the
sender's prepaid_storage_balance +amount. The field pays the account's account rent (13) and,
as an object owner, its objects' shortfall after their deposits (§12) before its balance does; when
the account is pruned what is left goes to the longevity pool with the balance (13). It is never
refunded. Then 04 §5.
How to compute it. Stateless: body ≥ 8 ("AddPrepaidStorage body too short"), amount > 0
("AddPrepaidStorage amount must be positive"). Execution: amount + fee checked ("Transaction amount overflow"); the sender row must exist ("Sender account not found"); the confirmed balance
must cover amount + fee (block invalid otherwise); debit, two rows, the field update.
Rule activation. None.
Rejections and errors. As listed; the execution failures make the block invalid.
Vector. computed. INPUT: body 00E1F50500000000 (100,000,000), fee 2,600,000, sender balance
500,000,000 → EXPECTED: balance 397,400,000 before the refund, rows −2,600,000 (event 1) and
−100,000,000 (event 68), prepaid_storage_balance +100,000,000, then the overpay above the floor
for an 8-byte body is refunded (04 §5). Invalid: body 0000000000000000 → "AddPrepaidStorage amount must be positive".
Test cases · §5
3 cases · 2 valid · 1 invalid · 1 reference
AddPrepaidStorage of 1 ZBC passes the stateless checks
Loading the test widget…
AddPrepaidStorage of 0 is refused
Loading the test widget…
AddPrepaidStorage of 1 ZBC from a balance of 5 ZBC
A stated value: there is nothing to compute. A compatible node shows the same value.
- balance_before_refund
397400000- rows
1:-2600000, 68:-100000000- prepaid_storage_balance
+100000000
Defects to match. None.
6. TransferDataset (42) and AcceptDataset (44)
Purpose. Two-step transfer of an object's ownership.
Inputs. TransferDataset body: object_id (32) ‖ new_owner (the rest, a typed account).
AcceptDataset body: object_id (32; longer bodies accepted, only the first 32 bytes read).
Output and effect. Both charge the fee first (row event 1; an unpayable fee writes nothing and
the transaction is a no-op). Transfer: when the object's newest row exists and its owner equals
the sender byte for byte, a new object version at h with pending_owner = the body's bytes from
offset 32; otherwise nothing more. Accept: when the object's newest row exists, has a pending
owner, and the pending owner is the same account as the sender (07 §3, "the same account"), a new version at h
with owner_account = the sender's bytes and no pending owner, and a ledger row event 33 with
change 0 on the sender; otherwise nothing more. Then 04 §5. Every record keeps its own writer
across a transfer; only the object's owner (who writes in private mode, sets the mode, transfers,
votes with weight 0 unless it also funds, and pays the rent shortfall) changes.
How to compute it. Stateless (admission and block validation): Transfer body ≥ 36
("TransferDataset body too short"), then the new owner, which must later sign the AcceptDataset
(rule canonical_account_forms), in this order: a well-formed account (07 §3.1;
"TransferDataset: invalid new-owner address"); not a full-key form ("TransferDataset: new owner: a full-key account form (an Ethereum or Tron key, a Bitcoin key) is not an account: no transaction can be sent from it; name the 20-byte address (rule canonical_account_forms)"); of a kind that can
sign (07 §3.1; "TransferDataset: the new owner's kind cannot sign, so it could never accept the dataset"). Accept body ≥ 32 ("dataset object tx body too short"). Admission (rule
dataset_owner_only_write): a Transfer of an object that exists, has a
non-empty owner, and whose owner's bytes differ from the sender's is refused with Dataset: the object ZBS_… now belongs to another account; only its owner may transfer it; a missing or deleted
object is left to the executor (a paid no-op).
Rule activation. dataset_owner_only_write, state_answer_noop, canonical_account_forms:
active from height 0 on every chain.
Rejections and errors. As listed; the stateless ones refuse admission and make a block invalid; every state condition is a paid no-op in a block; a failed read of the object (for a Transfer, an Accept or a SetDatasetPolicy) is a fault that fails the block on that node, and only an object that does not exist is a paid no-op.
Vector. computed. INPUT: TransferDataset from 00000000 7D8BD8A4…61902572, body
567A1B2FAEFAA85A1446B93299DFAFAF29E0E228C2363F69487C8C337521F181 ‖ 00000000BCCB80820D3E3FCE6E62F1C283ACF6B0AB884A937AF47120DE2FFE88A393B4D6
(68 bytes) → EXPECTED: object 567A…F181 version at h, owner unchanged, pending_owner =
00000000 BCCB…B4D6. INPUT: AcceptDataset from 00000000 BCCB…B4D6, body 567A1B2F…F181 →
EXPECTED: owner = 00000000 BCCB…B4D6, no pending owner, row event 33 change 0. Invalid: INPUT the
same TransferDataset from a third account → Dataset: the object ZBS_KZ5BWL5O_7KUFUFCG_XEZJTX5P_V4U6BYRI_YI3D62KI_PSGDG5JB_6GA23DX7 now belongs to another account; only its owner may transfer it; INPUT a Transfer body
567A…F181 ‖ a bare 32-byte key (64 bytes) → "TransferDataset: invalid new-owner address";
INPUT a Transfer body 567A…F181 ‖ 04000000 ‖ 64 × 66 (100 bytes; an Ethereum full-key form) →
"TransferDataset: new owner: a full-key account form (an Ethereum or Tron key, a Bitcoin key) is not an account: no transaction can be sent from it; name the 20-byte address (rule canonical_account_forms)"; INPUT a Transfer body 567A…F181 ‖ 08000000 ‖ 32 × AA (68 bytes; a
P2WSH script hash) → "TransferDataset: the new owner's kind cannot sign, so it could never accept the dataset"; with 04000000 ‖ 20 × 66 (an Ethereum account, 56 bytes) the Transfer passes.
Test cases · §6
9 cases · 5 valid · 4 invalid · 1 reference
A TransferDataset to a typed account passes the stateless checks
Loading the test widget…
A TransferDataset to a bare 32-byte key is refused
Loading the test widget…
A TransferDataset to an Ethereum full-key form is refused
Loading the test widget…
A TransferDataset to a P2WSH script hash (it cannot sign) is refused
Loading the test widget…
A TransferDataset to a 24-byte Ethereum account passes the stateless checks
Loading the test widget…
The Transfer names the pending owner; the owner stays
Loading the test widget…
The Accept by the pending owner makes it the owner
Loading the test widget…
An AcceptDataset body passes the stateless checks
Loading the test widget…
A TransferDataset by a third account is refused at admission
A stated value: there is nothing to compute. The statement is a refusal: the exact text a compatible node answers.
- refusal
Dataset: the object ZBS_KZ5BWL5O_7KUFUFCG_XEZJTX5P_V4U6BYRI_YI3D62KI_PSGDG5JB_6GA23DX7 now belongs to another account; only its owner may transfer it
Defects to match. (1) No admission check exists for AcceptDataset; a wrong acceptor pays the fee for nothing.
7. SetDatasetPolicy (43)
Purpose. The owner sets the dataset's mode.
Inputs. Body, exactly 33 bytes:
| Offset | Length | Field | Encoding |
|---|---|---|---|
| 0 | 32 | object_id |
|
| 32 | 1 | mode |
0 private, 1 open, 2 public |
Output and effect. The fee is charged first (event 1; unpayable → no-op). When the object's
newest row exists, has a non-empty owner, and that owner equals the sender byte for byte: a new
object version at h with manage_mode = mode (owner and pending owner kept). Otherwise a paid
no-op. Then 04 §5. The mode decides §3 from the next transaction on.
How to compute it. Stateless (admission and block validation): body length ≠ 33 →
"SetDatasetPolicy: the body is object_id (32 bytes) and mode (1 byte)"; mode > 2 →
"SetDatasetPolicy: mode must be 0 (private), 1 (open) or 2 (public)". Admission (rule
dataset_owner_only_write): an existing object with a non-empty owner that differs from the sender
→ Dataset: the object ZBS_… now belongs to another account; only its owner may set its policy.
Rule activation. dataset_owner_only_write, state_answer_noop: active from height 0 on every chain.
Rejections and errors. As listed.
Vector. computed. INPUT: from the owner 00000000 7D8BD8A4…61902572, body
567A1B2FAEFAA85A1446B93299DFAFAF29E0E228C2363F69487C8C337521F18101 (33 bytes) → EXPECTED:
object version at h, manage_mode 1; /objects/<id> then answers "manage_mode":1,"mode":"open".
Invalid: body 567A…F18103 → "SetDatasetPolicy: mode must be 0 (private), 1 (open) or 2 (public)"; body 567A…F181 (32 bytes) → "SetDatasetPolicy: the body is object_id (32 bytes) and mode (1 byte)".
Test cases · §7
3 cases · 1 valid · 2 invalid
SetDatasetPolicy to mode 1 passes the stateless checks
Loading the test widget…
Mode 3 is refused
Loading the test widget…
A 32-byte policy body is refused
Loading the test widget…
Defects to match. None.
8. Funding a dataset: the deposit list and the unconsumed parts
Purpose. Who has how much money left on a dataset or a DFS file at any height.
Inputs. The object's file_deposit entries in seq order; left = the deposit address's
current balance (0 when it has no row).
Output and effect. The per-payer list: total = Σ amount over the entries (amounts > 0,
128-bit, saturating at 2⁶³ − 1); consumed = max(0, total − max(left, 0)); walking the entries in
seq order, each entry's used part is min(amount, consumed remaining) and consumed shrinks by it;
each payer (the empty payer is one payer) collects paid (Σ its amounts) and unconsumed
(Σ amount − used), payers listed in the order of their first entry. When left exceeds total
nothing is consumed and the excess belongs to nobody on the list.
How to compute it. As stated, integers only.
Rule activation. None.
Rejections and errors. None.
Vector. computed. INPUT: entries A 10, B 5, C 5, A 5 (seq 0–3), left 10 → EXPECTED:
[A paid 15 unconsumed 5, B paid 5 unconsumed 0, C paid 5 unconsumed 5] (consumed 15 = A's first
10 and B's 5). INPUT: the same entries, left 30 → EXPECTED: A 15/15, B 5/5, C 5/5 and 5 belonging
to nobody.
Test cases · §8
2 cases · 2 valid
Four deposits, 10 left on the address
Loading the test widget…
The same deposits, 30 left on the address
Loading the test widget…
Defects to match. None.
9. DeleteDataset (45): the vote and the deletion
Purpose. End a dataset when its owner and the money still on it agree.
Inputs. Body: object_id (32; longer bodies accepted, only the first 32 bytes read); the
dataset's newest object row; §8's list for the object; the standing votes.
Output and effect.
- The fee is charged (event 1; unpayable → no-op, nothing written).
- Who may vote (the same at admission and execution): no live dataset →
Dataset: no dataset at ZBS_…; the sender's bytes equal the owner's → allowed; the sender (in its typed form) is a payer of §8 withunconsumed > 0→ allowed; otherwiseDataset: only ZBS_…'s owner or a funder with money left on it may vote to delete it. A refusal in a block is a paid no-op. - Tally: over §8's list, skipping the empty payer and payers with
unconsumed ≤ 0:total= Σ unconsumed;voted= Σ unconsumed of the payers that have a standing vote row or are the sender (sums saturate at 2⁶³ − 1). - When
total > 0: unless the sender already has a standing vote row, a rowdataset_delete_vote(object_id, sender, h, latest 1)is written; the dataset is deleted iffvoted × 2 > total(128-bit); otherwise nothing more. Whentotal ≤ 0(nobody has money left, or nobody ever funded it) only the owner reaches this point (step 2) and the dataset is deleted at once, with no vote row. - Deletion: every active row whose
object_idis the object (records of every writer and the creating ordinary row) gets an inactive version at h (value and bindings kept); each such row's p + v leaves its own setter'sdataset_storage_bytes; the deposit address's whole balance, when > 0, goes to the longevity pool (row event 50 −balance on the deposit address, row event 50 +balance onZBCLONGV); the object gets a version at h with empty owner and empty pending owner (mode kept). The vote rows are left as they are.
A vote stands until the dataset is deleted; a second DeleteDataset from a standing voter writes no
row and re-counts (the unconsumed parts shrink as rent is paid). Then 04 §5.
How to compute it. Stateless: body ≥ 32 ("dataset object tx body too short"). Then steps 1–5.
Rule activation. survival_field, state_answer_noop: active from height 0 on every chain.
Rejections and errors. Step 2's texts at admission; paid no-ops in a block; a failed read fails the block on that node.
Vector. computed. State: dataset O owned by W (not a funder), deposit entries A 10, B 5,
C 5, A 5, deposit balance 10 (so A 5 and C 5 unconsumed, total 10). INPUT: DeleteDataset from W,
body O → EXPECTED: vote row (O, W, h); voted 0, 0 > 10 false: not deleted. INPUT: from A →
vote row (O, A, h'); voted 5, 10 > 10 false: not deleted. INPUT: from C → voted 10 (A 5 + C 5),
20 > 10: every record of O gets an inactive version, each writer's counter loses its bytes, the
10 on the deposit address go to the longevity pool (event 50), O is tombstoned. Invalid: INPUT
from B (unconsumed 0) → Dataset: only ZBS_<O>'s owner or a funder with money left on it may vote to delete it; INPUT body 00…00 (32 zero bytes, no such dataset) → Dataset: no dataset at ZBS_AAAAAAAA_AAAAAAAA_AAAAAAAA_AAAAAAAA_AAAAAAAA_AAAAAAAA_AAABMDL6. A dataset nobody funded
(funders empty, as the object of §2): a DeleteDataset from its owner deletes it in that block.
Test cases · §9
7 cases · 5 valid · 2 invalid
The owner (not a funder) votes: nothing deleted
Loading the test widget…
A votes after the owner: 5 of 10, not deleted
Loading the test widget…
C votes after A: 10 of 10, deleted
Loading the test widget…
B (nothing left on it) may not vote
Loading the test widget…
A dataset that does not exist
Loading the test widget…
The owner of a dataset nobody funded deletes it at once
Loading the test widget…
A DeleteDataset body passes the stateless checks
Loading the test widget…
Defects to match. (1) The vote rows survive the deletion (they are history). (2) The owner's vote weighs nothing unless the owner also funded the dataset, so a dataset whose funders hold money cannot be deleted by its owner alone.
10. DFS files: the metadata record, the path rules and the chunks
Purpose. How a file is represented.
Inputs. A path and a content.
Output and effect. A file of owner at path is the row (owner, owner, "dfs:" ‖ normalize(path)) whose value is the lowercase hex of this record:
| Offset | Length | Field | Encoding |
|---|---|---|---|
| 0 | 4 | hash_len |
u32 LE = 32 |
| 4 | 32 | content_hash |
SHA3-256(content) |
| 36 | 8 | size |
u64 LE, bytes of content |
| 44 | 4 | permissions |
u32 LE = 420 (0644) |
| 48 | 8 | created_at |
i64 LE, the creating transaction's timestamp |
| 56 | 8 | modified_at |
i64 LE, the last changing transaction's timestamp (= created_at on create) |
| 64 | 4 | chunk_count |
u32 LE |
| 68 | 36 × n | chunks | each 20000000 ‖ SHA3-256(chunk) |
Content is cut into chunks of 1,048,576 bytes; a body is at most 65,536 bytes (03), so a file has
one chunk, or none when empty. Chunks are kept in a node-local store keyed by their hash (shared
between files with identical content), never consensus state, never in a snapshot (07 §9). A file
is read by decoding the hex value and fetching its chunks; a dfs: row whose creating transaction
is not a DFS type is not served as a file.
Path rules: non-empty, ≤ 1,024 bytes, starts with /, contains neither // nor .., no byte
0x00, 0x0A, 0x0D. Normalization (applied when building the property): a trailing / removed except
for the root, // collapsed, a leading / ensured; so /a/b/ and /a/b name one row. Directory
markers dfs:dir: ‖ path are reserved; no transaction creates one. A group's file is a row of the
group's address (a member's files move to its group when it joins, keeping the member as
added_by, 18), so a member names a group file by the group's path.
How to compute it. As stated; for a one-chunk file the content hash and the chunk hash are the same SHA3-256.
Rule activation. None.
Rejections and errors. None here (§11).
Vector. computed. INPUT: content 68656C6C6F207A6F6F62630A (hello zoobc\n, 12 bytes), creating
and changing timestamp 1,793,511,272 → EXPECTED: SHA3-256 = ab806bec9845200aa4b7ad50a4aa69d096ee2c21319aac3cc0ab5250a21b2fcf;
record (104 bytes) = 20000000 ‖ ab806bec…2fcf ‖ 0c00000000000000 ‖ a4010000 ‖
68cfe66a00000000 ‖ 68cfe66a00000000 ‖ 01000000 ‖ 20000000 ‖ ab806bec…2fcf; the row's value
is these 104 bytes as 208 lowercase hex characters. Path /p19/hello.txt/ normalizes to
/p19/hello.txt (property dfs:/p19/hello.txt, 18 bytes). Invalid paths: p19/x (no leading
/), /a//b, /a/../b.
Test cases · §10
4 cases · 1 valid · 3 invalid
The metadata record of a 12-byte file
Loading the test widget…
The path p19/x is refused
Loading the test widget…
The path /a//b is refused
Loading the test widget…
The path /a/../b is refused
Loading the test widget…
Defects to match. (1) The content is not consensus state: a node that joins from a snapshot holds the metadata and cannot serve the bytes. (2) The hex encoding doubles the value's length: rent (§12) bills the doubled length while the storage counter (§11) adds the binary length.
11. DFSCreateFile (8), DFSUpdateFile (264), DFSDeleteFile (520)
Purpose. Create, replace and remove a file.
Inputs. Create and Update body: path_len (4, u32 LE) ‖ path ‖ content_len (4, u32 LE) ‖
content. Delete body: path_len (4) ‖ path. Longer bodies are accepted (only the fields are
read). Envelope recipient: empty.
Output and effect. Every existence test reads the newest row (sender, sender, dfs: ‖ path)
and asks whether it is active.
- Create: an active file already at the path → paid no-op (rule
dfs_moved_state). Else sender −fee (row event 8; unpayable → block invalid); the row of §10 at h withcreating_tx_hash= this hash, clock h,added_by= the acting member when a group member creates it for its group, else the sender; the sender'sdataset_storage_bytes+(|property| + 68 + 36·n) (the binary record length); the chunks stored locally. - Update: no active file → paid no-op. A group member that is neither the group's controller
nor the file's
added_by→ paid no-op. Else sender −fee (row event 264); a new version of the row with a new record (new hash, size, chunks;created_atcopied from the old record when it parses, else this timestamp;modified_at= this transaction's timestamp); the row keeps itscreating_tx_hashand clock; the storage counter is unchanged; old chunks stay locally. - Delete: no active file → paid no-op (rule
dfs_moved_state); the group-member restriction of Update; else sender −fee (row event 520); an inactive version with empty value, nocreating_tx_hash, clock 0; then, when the deleted row had acreating_tx_hash, the file refund: with the deposit address's balanceleftand §8's list in first-payment order, each non-empty payer withunconsumed > 0getsmin(unconsumed, left − refunded so far)by a plain credit (no split policy; to its group when it has joined one since), rows event 32 (−part on the deposit address, +part on the payer); a part whose credit is refused stays on the address; what remains on the address is swept to the longevity pool (event 50 −rest on the address, +rest onZBCLONGV). The chunks are deleted locally; the storage counter is unchanged.
Group files. When the sender is a group member acting for its group, an update or a delete of
an active group file (and a RemoveAccountDataset of its dfs: row, §4) is allowed only for the
group's controller or the file's original owner (added_by, compared as typed accounts); a member
that leaves the group loses the right.
Then 04 §5 for all three.
How to compute it. Stateless (admission and block validation): body ≥ 8 (delete ≥ 4), lengths
within the body, the path valid per §10 ("DFS file body too short", "DFS file path truncated",
"DFS file: invalid path", "DFS file content truncated", "DFS delete body too short", "DFS delete path truncated", "DFS delete: invalid path"). Admission only: create → no active file at
the path ("DFS file: a file already exists at <path> (DFSUpdateFile changes it)"); update and
delete → an active file ("DFS file: file not found: <path>"); the group restriction ("Account group: only the group's controller or the file's original owner may change or delete the group's file <path>").
Rule activation. dfs_moved_state, survival_field: active from height 0 on every chain.
Rejections and errors. As listed; the execution paths named "paid no-op" are not failures.
Vector. computed. INPUT: DFSCreateFile body (34 bytes)
0E0000002F7031392F68656C6C6F2E7478740C00000068656C6C6F207A6F6F62630A (path /p19/hello.txt,
content hello zoobc\n), timestamp 1,793,511,272, at height h → EXPECTED: row (S, S,
dfs:/p19/hello.txt) with the 208-character value of §10, creating_tx_hash = this hash, clock h;
counter +122 (18 + 104); fee row event 8. INPUT: DFSDeleteFile body (18 bytes)
0E0000002F7031392F68656C6C6F2E747874 after the file's deposit address received 10 from the owner
A, 5 from B, 5 from C and 5 from A and holds 10 → EXPECTED: inactive row; C +5 and A +5 (event 32
pairs), nothing to the pool. Invalid: a second identical create → admission "DFS file: a file already exists at /p19/hello.txt (DFSUpdateFile changes it)", in a block a paid no-op; body
0E0000002F70 (6 bytes) → "DFS file body too short"; body 0E0000002F7031392F (9 bytes, the path
runs past it) → "DFS file path truncated".
Test cases · §11
8 cases · 5 valid · 3 invalid · 2 reference
The create and delete bodies of /p19/hello.txt
Loading the test widget…
The DFSCreateFile body passes the stateless checks
Loading the test widget…
The DFSDeleteFile body passes the stateless checks
Loading the test widget…
Deleting a file whose deposit address received A 10, B 5, C 5, A 5 and holds 10
Loading the test widget…
The refund rows of that delete
A stated value: there is nothing to compute. A compatible node shows the same value.
- value
C +5 and A +5 (event 32 pairs), nothing to the pool
A second identical create is refused at admission
A stated value: there is nothing to compute. The statement is a refusal: the exact text a compatible node answers.
- refusal
DFS file: a file already exists at /p19/hello.txt (DFSUpdateFile changes it)
A 6-byte create body is refused
Loading the test widget…
A create body whose path runs past the body is refused
Loading the test widget…
Defects to match. (1) The ledger event numbers of the three fee rows are the transaction type numbers 8, 264 and 520. (2) A delete leaves the storage counter untouched, so the counter drifts upward over a file's life. (3) An update never removes superseded chunks locally.
12. Dataset rent: the per-block billing step
Purpose. What every object pays, when, from where, to whom.
Inputs. The consensus parameters dataset_storage_cost_per_mib (rate) and
storage_oracle_multiplier_ppm (ppm), read fresh on every use (else the compiled 100,000,000 and
1,000,000); the billing period period = main_snapshot_interval; the account rows; the block.
| Parameter | TestNet | DevNet |
|---|---|---|
dataset_storage_cost_per_mib |
5,000,000 | 100,000,000 |
storage_oracle_multiplier_ppm |
1,000,000 | 1,000,000 |
period (main_snapshot_interval) |
172,800 | 240 |
The prices are governable (17): rate ∈ [1, 10,000,000,000], ppm ∈ [100,000, 10,000,000].
Output and effect. The step runs after every block (its place among the per-block steps is
22). Every object has one rent clock (rule dataset_rent_object_clock): the
last_billing_height of its dataset_object row when that is above 0, else the lowest
last_billing_height among its active rows (a clock that reads 0 is due at once). An object here
is the object_id of a row, else its creating_tx_hash. The due set = one row per object
whose clock C satisfies h − C ≥ period, among the active newest account_dataset rows that
carry a creating_tx_hash: the object's first such row in byte order of (object, setter,
recipient, property), the objects taken in that order. Re-clock of an object = (a) a new
version of its dataset_object row at h with last_billing_height = h, owner, pending owner and
mode kept — an object that has no such row (a DFS file, §10) gets a billing-only object row
instead: owner = the due row's setter, no pending owner, manage_mode −1 — then (b) a new version
at h of every active row of the object, in byte order of (setter, recipient, property), with
last_billing_height = h and every other field kept (setter, recipient, property, value, active,
creating_tx_hash, object_id, added_by).
Charging: bytes = Σ (|property| + |value|) over the active rows whose object_id column is
obj (the hex length for a DFS row), or the due row's own when there are none; fee = StorageFee(bytes); the object is re-clocked; fee ≤ 0 ends the case. deposit = the confirmed
balance of 0A000000 ‖ obj; owner = the object's owner when an object row exists (else the due
row's setter); the owner's balance and prepaid storage are confirmed values.
deposit ≥ fee: the deposit paysfee(row event 17 on the deposit address).- else, when the owner's prepaid storage plus its balance cover
fee − deposit(prepaid storage, floored at 0, ≥ the shortfall, or balance ≥ shortfall − prepaid storage): the deposit pays all it holds (event 17, when > 0), and the owner paysfee − deposit, its prepaid storage first and its balance for the rest (rows on the owner: event 83 +what the prepaid storage paid, when > 0, and event 17 −(fee − deposit)). - else: every active row of
obj(the due row itself when there are none) gets an inactive version at h keeping its fields (creating_tx_hash,object_id,added_by, clock); the deposit, when > 0, is swept to the longevity pool (event 50 −deposit on the address, +deposit onZBCLONGV); a row event 18 with change 0 on the deposit address. The object row is not changed (a billing-only object whose last active row goes is tombstoned) and the writers' storage counters are not reduced.
A part is collected (its row written, its amount counted) only when its debit happened. After the
loop the sum collected in this block is credited to the longevity pool ZBCLONGV with a row event
19 (transaction id 0); a pool credit that fails refuses the block. Every row of this step carries
transaction id 0 and the block's timestamp. A read of the due set, of an object's rows or of its
object row that fails is a fault that fails the block on that node.
How to compute it. StorageFee(bytes) = 0 when rate ≤ 0, ppm ≤ 0 or bytes = 0; else
a = ⌈bytes × rate / 1,048,576⌉, fee = ⌈a × ppm / 1,000,000⌉, both in 128-bit integers,
saturating at 2⁶³ − 1. The first charge of an object falls in the first block with h ≥ C + period, C the lowest clock among its active rows (the creating row's height, for an object
written once); later charges every period blocks counted from the last re-clock, whatever
records were added or rewritten in between (a new record's clock never makes the object due
earlier: the object's own clock, once set, decides).
Rule activation. survival_field, dataset_rent_object_clock: active from height 0 on every
chain.
Rejections and errors. None; a debit that is refused collects nothing.
Vector. computed (TestNet parameters). INPUT: the object of §2 (306 bytes, created at
height 141, deposit 0, owner the release authority with balance 100,000,000,000, prepaid 0): first
due at height 141 + 172,800 = 172,941 → EXPECTED: fee = ⌈306 × 5,000,000 / 1,048,576⌉ = 1,460
(ppm 1,000,000 leaves it), row event 17 −1,460 on the owner, the object row re-clocked to 172,941
(a version at 172,941 with last_billing_height 172,941) and the record's row rewritten at
172,941 with clock 172,941, row event 19 +1,460 on ZBCLONGV; the next charge at 345,741. The
same object on DevNet: 29,183. One MiB on the TestNet: exactly 5,000,000. An 8-byte object: 39
(TestNet), 763 (DevNet). INPUT: an open dataset with two records, written at heights 100 (by A)
and 200 (by B), never charged → EXPECTED: one charge at the first block with h ≥ 172,900, both
records rewritten at that height with that clock, the object row too; nothing at 173,000. INPUT:
an object with deposit 0 whose owner holds 1,000 and fee 1,460 → EXPECTED: every active row of
the object inactive at h, row event 18 change 0 on the deposit address, nothing collected.
Test cases · §12
9 cases · 9 valid · 2 reference
Rent of 306 bytes on the TestNet
Loading the test widget…
Rent of 306 bytes on the DevNet
Loading the test widget…
Rent of One MiB on the TestNet
Loading the test widget…
Rent of 8 bytes on the TestNet
Loading the test widget…
Rent of 8 bytes on the DevNet
Loading the test widget…
The first rent charge of the dataset of §2 (TestNet)
A stated value: there is nothing to compute. A compatible node shows the same value.
- due
172941- rows
17:-1460 on the owner, 19:+1460 on ZBCLONGV- object_clock
172941- record
rewritten at 172941 with clock 172941- next_charge
345741
The dataset of §2 is charged at 172,941 and again at 345,741
Loading the test widget…
An open dataset with records written at 100 and 200 is charged once, at 172,900
Loading the test widget…
An object whose owner cannot pay its rent
A stated value: there is nothing to compute. A compatible node shows the same value.
- value
every active row of the object inactive at h, row event 18 change 0 on the deposit address, nothing collected
Defects to match. (1) A rent charge writes a new version of every active record of the object
at the charging height, so a record's version height (the height the read views show) is the
height of its last charge, not of its last write, and the first-write order among the records of
one object is lost at the first charge (§3 Defects (1)). (2) The first charge of an object that has
no dataset_object row (a DFS file, §10) writes a billing-only object row (owner = the file's
owner, manage_mode −1), which every rule that asks for a live dataset then sees: its owner may
write records under the file's object id (the mode reads as private), vote to delete it (§9), and
the read view of §1 answers for it; the row is tombstoned when the file's last active row goes
(§4, §11). (3) A pruned object keeps its live dataset_object row (writes can resume) and its
writers' storage counters. (4) A row without creating_tx_hash is never billed.
13. The reserved namespaces
Purpose. The value shapes the chain enforces on four property prefixes.
Inputs. The property and value of a SetupAccountDataset (ordinary or record).
Output and effect.
| Prefix | Rule | Requirement |
|---|---|---|
dfs: |
dfs_namespace_reserved |
refused: only the DFS types write there |
dfs:dir: |
(same prefix) | refused with dfs: |
tokenicon: |
always | a PNG or WebP of 1…512 × 1…512 pixels, 16…4,096 bytes |
inv: |
invoice_namespace_shape |
a JSON object with no negative number anywhere |
tokenicon:: length in [16, 4,096]; PNG = the signature 89 50 4E 47 0D 0A 1A 0A, bytes 12…15 =
IHDR, width and height = the big-endian u32 at offsets 16 and 20, both in [1, 512]; WebP = RIFF
at 0, WEBP at 8, then at 12: VP8 (bytes 23…25 = 9D 01 2A, width = LE16 at 26 & 0x3FFF, height
= LE16 at 28 & 0x3FFF, both in [1, 512]), VP8L (byte 20 = 0x2F, bits = LE32 at 21, width =
(bits & 0x3FFF) + 1, height = ((bits ≫ 14) & 0x3FFF) + 1, both ≤ 512) or VP8X (width = LE24 at
24 + 1, height = LE24 at 27 + 1, both ≤ 512); anything else is refused. inv:: the value must parse
as JSON, the top-level value must be an object, and no number token anywhere may be negative.
How to compute it. The prefix test is a byte comparison at offset 0 of the property (invoice:
is not inv:).
Rule activation. dfs_namespace_reserved, invoice_namespace_shape: active from height 0 on every chain.
Rejections and errors. "tokenicon: values must be a PNG or WebP image of at most 512x512 and 4096 bytes"; "inv: values must be a JSON object with no negative number in it (<why>)" with why
∈ {not JSON, not a JSON object, a negative number}; the dfs: text of §2. All stateless:
refused at admission, block invalid.
Vector. computed. INPUT: property tokenicon:ABC, value (68 bytes)
89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c4890000000b49444154789c6360000200000500017a5eab3f0000000049454e44ae426082
(a 1 × 1 PNG) → accepted. INPUT: property inv:1, value {"total":-1} → "inv: values must be a JSON object with no negative number in it (a negative number)"; value [1] → (… (not a JSON object)); property invoice:1, value {"total":-1} → accepted (not the prefix).
Test cases · §13
5 cases · 2 valid · 3 invalid
A 1 × 1 PNG under tokenicon: is accepted
Loading the test widget…
An invoice with a negative number is refused
Loading the test widget…
An invoice that is not an object is refused
Loading the test widget…
The prefix invoice: is not inv:
Loading the test widget…
A tokenicon: value that is not an image is refused
Loading the test widget…
Defects to match. The tokenicon: check reads the declared dimensions only; a valid header over
garbage passes, and WebP animation or alpha flags are not inspected.
14. Ledger rows and the consensus/local split
| Event | Row | Written by |
|---|---|---|
| 6 / 7 | sender −fee | SetupAccountDataset / RemoveAccountDataset (ordinary row or record) |
| 8 / 264 / 520 | sender −fee | the three DFS types (the type number as event) |
| 1, 68 | sender −fee, −amount | AddPrepaidStorage |
| 1 | sender −fee | Transfer / Accept / SetPolicy / Delete, and every paid no-op of §2–§4, §11 |
| 33 | sender, change 0 | AcceptDataset |
| 32 | deposit −d, payer +d | a DFS file's refund (DFSDeleteFile, the removal of its dfs: row) |
| 50 | deposit −d, ZBCLONGV +d |
sweep to the longevity pool (DeleteDataset, rent prune, a file refund's remainder) |
| 17 | deposit or owner −fee | rent charged (the owner's row the whole shortfall) |
| 83 | owner +p | what the owner's prepaid storage paid of that shortfall |
| 18 | deposit, change 0 | object pruned for unpaid rent |
| 19 | longevity pool +Σ | rent collected in the block |
| 22, 47 | per 04 §5 |
the generic settlement |
Consensus: account_dataset, dataset_object, dataset_delete_vote, file_deposit, the deposit
and owner balances, the account row's dataset_storage_bytes and prepaid_storage_balance, and
every accept/refuse rule of §2–§13. Local: the ledger rows, the chunk store, the read views, and the
admission-only checks (a blocksmith may mine what they refuse; the execution decides).
A question about this chapter, or a statement that does not match the network? Discuss on zoobc.pro.