On this page
  1. §0 The area in one paragraph
  2. 1. The state of this area and its read views
  3. 2. SetupAccountDataset (3) to an ordinary recipient: create an object or rewrite its row
  4. 3. Writing and removing a record of a dataset
  5. 4. RemoveAccountDataset (259) of an ordinary row
  6. 5. AddPrepaidStorage (9)
  7. 6. TransferDataset (42) and AcceptDataset (44)
  8. 7. SetDatasetPolicy (43)
  9. 8. Funding a dataset: the deposit list and the unconsumed parts
  10. 9. DeleteDataset (45): the vote and the deletion
  11. 10. DFS files: the metadata record, the path rules and the chunks
  12. 11. DFSCreateFile (8), DFSUpdateFile (264), DFSDeleteFile (520)
  13. 12. Dataset rent: the per-block billing step
  14. 13. The reserved namespaces
  15. 14. Ledger rows and the consensus/local split

10 — Datasets, dataset objects, the DFS file layer and dataset rent

Edition 0.6.1 · verified against the reference implementation, version 0.6.1

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.

Inputs. The writes of §2–§12; HTTP requests for the three read views.

Output and effect. Five tables (full columns and keys in 07 §1):

  • account_dataset — one row family per (setter, recipient, property), versioned by height (07 §2: a write at height h marks the key's older rows latest = 0 and 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 to creating_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 has is_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.
  • dataset_object — keyed by object_id, versioned by height: 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, rule dataset_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 no dataset_object row 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 next seq is 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>}):

  1. GET /api/v1/objects/<object_id> — object_id exactly 64 hex digits (else 400 object_id must be 64 hex); no dataset_object row → 404 object 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 (the ZBC_ 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 whose object_id is this object), monthly_fee (§12's formula over size_bytes at the chain's own price: the consensus_parameters values of dataset_storage_cost_per_mib and storage_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 ascending height, 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).
  2. GET /api/v1/dataset-address/<id> — <id> is a ZBS_ text (else 400 Invalid ZBS_ address) or 64 hex digits with an optional 0x (else 400 tx 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).
  3. GET /api/v1/accounts/<address>/datasets[?property=<prefix>] — <address> a ZBC_ text or hex; the newest active rows whose height ≤ the confirmed height (31) where the address is the setter or the recipient (a 32-byte hex query also matches 00000000 ‖ key), optionally only properties beginning with the prefix, in descending height; answer {"address", "datasets":[{setter, recipient, role ("setter" | "recipient" | "both"), property, value, value_b64, height, creating_tx_hash}]}. Querying a dataset's ZBS_ address in hex lists its records (role recipient). Errors 400 Invalid 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 price10-1-objectsvalid

Loading the test widget…

The same view at the TestNet price10-1-objects-testnetvalid

Loading the test widget…

GET /api/v1/dataset-address of the same object, nothing ever paid to it10-1-dataset-addressvalidreference

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…F18110-1-depositvalid

Loading the test widget…

The deposit address of the object id 32 × 0010-1-deposit-zerovalid

Loading the test widget…

The view's monthly_fee of 306 bytes at the DevNet price10-1-monthly-feevalid

Loading the test widget…

GET /api/v1/objects/00 is refused10-1-bad-idinvalidreference

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 found10-1-unknowninvalidreference

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:

  1. Foreign row (rule dataset_owner_only_write): when the newest row of (sender, recipient, property) exists, is active, and its object (its object_id, else its creating_tx_hash) has a dataset_object row 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 no dataset_object row is not foreign.)
  2. The fee is debited (row event 6, −fee); a sender that cannot pay makes the block invalid.
  3. Keeps binding: when the newest row of the key is active and has a creating_tx_hash, the new version keeps that row's creating_tx_hash, last_billing_height, object_id and added_by (the same object; rule dataset_update_keeps_deposit). Otherwise the new row gets creating_tx_hash = object_id = this transaction's hash, last_billing_height = h, added_by = the sender, and, when no dataset_object row exists for this hash, a new object (object_id = hash, owner = sender, pending_owner empty, manage_mode 0, height h) is written.
  4. The row (sender, recipient, property) at h: value, is_active = 1.
  5. 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 hash10-2-wallet-releasevalid

Loading the test widget…

The 386-byte body of that transaction: 306 bytes counted, the 72-byte tail not read10-2-wallet-release-bodyvalid

Loading the test widget…

The body of property bio, value hello10-2-bodyvalid

Loading the test widget…

Trailing bytes after the value are kept in the body (and not read)10-2-body-tailvalid

Loading the test widget…

The bio body passes the stateless checks10-2-validvalid

Loading the test widget…

The bio body with a 72-byte tail passes10-2-valid-tailvalid

Loading the test widget…

An empty property name is refused10-2-empty-nameinvalid

Loading the test widget…

A property in the dfs: namespace is refused10-2-dfsinvalid

Loading the test widget…

A 7-byte body is refused10-2-shortinvalid

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:

  1. No live dataset at the object id → Dataset: no dataset at ZBS_….
  2. 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.
  3. 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 refused10-3-privateinvalid

Loading the test widget…

The same write after the owner opens the dataset10-3-openvalid

Loading the test widget…

The writer removes its own record10-3-remove-ownvalid

Loading the test widget…

A third account cannot remove that record10-3-remove-otherinvalid

Loading the test widget…

In a public dataset another account's record of the key is taken10-3-public-takeninvalid

Loading the test widget…

A write to the deposit address of 32 × 00 finds no dataset10-3-no-datasetinvalid

Loading the test widget…

A record write to a ZBS_ recipient passes the stateless checks10-3-record-checkvalid

Loading the test widget…

The write after the owner opens the dataset: the writer's record, bound to the dataset10-3-write-effectvalid

Loading the test widget…

The writer removes its record: an inactive version, the counter back to 010-3-remove-effectvalid

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:

  1. 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's added_by (§11); anyone else → paid no-op.
  2. Foreign row (rule dataset_owner_only_write, as §2 step 1) → paid no-op.
  3. The fee is debited (row event 7; unpayable → block invalid).
  4. 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_by and last_billing_height (rule dataset_rent_object_clock; a property never set gets an empty creating_tx_hash, clock 0, and so object_id empty and added_by = the setter); when the newest version was active, the sender's dataset_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).
  5. When the removed row was active: let obj = its object_id (else its creating_tx_hash). If obj now has no active row and has no live dataset (no dataset_object row, or one with an empty owner), the deposit address of obj is 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 live dataset_object row 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 checks10-4-validvalid

Loading the test widget…

A 7-byte removal body is refused10-4-shortinvalid

Loading the test widget…

The owner removes its ordinary row: the inactive version keeps the object, its writer and its clock10-4-effectvalid

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 checks10-5-validvalid

Loading the test widget…

AddPrepaidStorage of 0 is refused10-5-zeroinvalid

Loading the test widget…

AddPrepaidStorage of 1 ZBC from a balance of 5 ZBC10-5-effectvalidreference

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 checks10-6-transfervalid

Loading the test widget…

A TransferDataset to a bare 32-byte key is refused10-6-bare-ownerinvalid

Loading the test widget…

A TransferDataset to an Ethereum full-key form is refused10-6-fullkey-ownerinvalid

Loading the test widget…

A TransferDataset to a P2WSH script hash (it cannot sign) is refused10-6-p2wsh-ownerinvalid

Loading the test widget…

A TransferDataset to a 24-byte Ethereum account passes the stateless checks10-6-eth-ownervalid

Loading the test widget…

The Transfer names the pending owner; the owner stays10-6-transfer-effectvalid

Loading the test widget…

The Accept by the pending owner makes it the owner10-6-accept-effectvalid

Loading the test widget…

An AcceptDataset body passes the stateless checks10-6-acceptvalid

Loading the test widget…

A TransferDataset by a third account is refused at admission10-6-thirdinvalidreference

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 checks10-7-openvalid

Loading the test widget…

Mode 3 is refused10-7-mode-3invalid

Loading the test widget…

A 32-byte policy body is refused10-7-shortinvalid

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 address10-8-left-10valid

Loading the test widget…

The same deposits, 30 left on the address10-8-left-30valid

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.

  1. The fee is charged (event 1; unpayable → no-op, nothing written).
  2. 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 with unconsumed > 0 → allowed; otherwise Dataset: 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.
  3. 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).
  4. When total > 0: unless the sender already has a standing vote row, a row dataset_delete_vote(object_id, sender, h, latest 1) is written; the dataset is deleted iff voted × 2 > total (128-bit); otherwise nothing more. When total ≤ 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.
  5. Deletion: every active row whose object_id is 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's dataset_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 on ZBCLONGV); 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 deleted10-9-ownervalid

Loading the test widget…

A votes after the owner: 5 of 10, not deleted10-9-avalid

Loading the test widget…

C votes after A: 10 of 10, deleted10-9-cvalid

Loading the test widget…

B (nothing left on it) may not vote10-9-binvalid

Loading the test widget…

A dataset that does not exist10-9-noneinvalid

Loading the test widget…

The owner of a dataset nobody funded deletes it at once10-9-unfundedvalid

Loading the test widget…

A DeleteDataset body passes the stateless checks10-9-bodyvalid

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 file10-10-recordvalid

Loading the test widget…

The path p19/x is refused10-10-no-slashinvalid

Loading the test widget…

The path /a//b is refused10-10-doubleinvalid

Loading the test widget…

The path /a/../b is refused10-10-dotsinvalid

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 with creating_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's dataset_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_at copied from the old record when it parses, else this timestamp; modified_at = this transaction's timestamp); the row keeps its creating_tx_hash and 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, no creating_tx_hash, clock 0; then, when the deleted row had a creating_tx_hash, the file refund: with the deposit address's balance left and §8's list in first-payment order, each non-empty payer with unconsumed > 0 gets min(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 on ZBCLONGV). 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.txt10-11-bodiesvalid

Loading the test widget…

The DFSCreateFile body passes the stateless checks10-11-createvalid

Loading the test widget…

The DFSDeleteFile body passes the stateless checks10-11-deletevalid

Loading the test widget…

Deleting a file whose deposit address received A 10, B 5, C 5, A 5 and holds 1010-11-refundvalid

Loading the test widget…

The refund rows of that delete10-11-refund-rowsvalidreference

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 admission10-11-againinvalidreference

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 refused10-11-six-bytesinvalid

Loading the test widget…

A create body whose path runs past the body is refused10-11-path-truncatedinvalid

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 pays fee (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 pays fee − 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 on ZBCLONGV); 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 TestNet10-12-testnet-306valid

Loading the test widget…

Rent of 306 bytes on the DevNet10-12-devnet-306valid

Loading the test widget…

Rent of One MiB on the TestNet10-12-mibvalid

Loading the test widget…

Rent of 8 bytes on the TestNet10-12-testnet-8valid

Loading the test widget…

Rent of 8 bytes on the DevNet10-12-devnet-8valid

Loading the test widget…

The first rent charge of the dataset of §2 (TestNet)10-12-chargevalidreference

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,74110-12-clockvalid

Loading the test widget…

An open dataset with records written at 100 and 200 is charged once, at 172,90010-12-two-recordsvalid

Loading the test widget…

An object whose owner cannot pay its rent10-12-prunevalidreference

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 accepted10-13-pngvalid

Loading the test widget…

An invoice with a negative number is refused10-13-inv-negativeinvalid

Loading the test widget…

An invoice that is not an object is refused10-13-inv-arrayinvalid

Loading the test widget…

The prefix invoice: is not inv:10-13-invoicevalid

Loading the test widget…

A tokenicon: value that is not an image is refused10-13-icon-textinvalid

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.