On this page
- §0 The area in one paragraph
- §1 Transport, admission and errors
- §2 Signed requests and scopes
- §3 Conventions shared by the read routes
- §4 Chain and block routes
- §5 Transaction routes
- §6 Account routes
- §7 Markets, apps, tokens, bridge, releases, registries, governance, longevity, storage
- §8 Node, admin, internal and announce routes
- §9 The gateway form
- §10 Consensus and local; summary of defects
31 — HTTP API: every route, its parameters, response fields, errors, limits and authentication
Out of scope what the state routes read (07 and the transaction documents); the mempool and staging rules behind POST /transactions (04); the Ethereum and Bitcoin RPC adapters (separate programs on 8545 / 8332, 30); the internals of the archival service beyond the answers it gives (§9)
§0 The area in one paragraph
Every node serves one plaintext HTTP/1.1 API on api_host:api_port (default 0.0.0.0:8080): 107 routes, 104 of them under /api/v1/, plus / and /wallet (the bundled wallet page) and one loopback-only POST /internal/attest. All but a handful are unauthenticated reads of the node's own state; the others are a transaction submission, a signed cancel of a pending transaction, three local service-registry announcements and a delete, a storage upload, an admin reset, and a signed public-IP echo. Every request first passes a pre-routing step that adds permissive CORS headers, answers OPTIONS at once, and applies per-client admission: 300 write requests per minute, reads unlimited unless configured, and a 300-second lockout after 20 failed signed authentications in 5 minutes, all keyed by the caller's IP unless the caller is a trusted proxy. Signed requests prove possession of an Ed25519 key over the ASCII string METHOD:PATH:TIMESTAMP:BODY within a 300-second window. Responses are JSON; byte strings are lowercase hex; addresses are the hex of their stored form; 64-bit identifiers are decimal strings on some routes and numbers on others (§3); errors are {"success":false,"error":"…","code":N} after a sanitiser that strips internal detail. Nothing here is consensus: an implementation offers these routes with these shapes so that the wallet, the explorer, the updater and the other tools can drive it; it may add routes freely. The public TestNet domain is answered first by a different program, the archival service, whose route set overlaps the node's and whose JSON differs (§9).
§1 Transport, admission and errors
Purpose. An implementation must accept HTTP requests, refuse floods per client, and answer every failure in one shape.
Inputs. The [api] keys of node.conf (30): api_host (default 0.0.0.0), api_port (8080), trusted_proxies (default 127.0.0.0/8, ::1), write_requests_per_minute (300), read_requests_per_minute (0 = off), auth_failure_lockout_threshold (20), auth_failure_lockout_seconds (300).
Output and effect. HTTP responses; per-client counters in memory (nothing persisted).
How to compute it.
- Server limits. HTTP/1.1 without TLS (the public domains terminate TLS at a gateway); 8 worker threads; read and write timeouts 5 s; keep-alive 5 s and at most 100 requests per connection; request body cap 1,048,576 bytes: a larger body is refused with 413 before any route runs (this applies to
POST /storage/uploadtoo). - CORS, every response.
Access-Control-Allow-Origin: *,Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS,Access-Control-Allow-Headers: Content-Type, X-Node-Public-Key, X-Timestamp, X-Signature. AnOPTIONSrequest to any path is answered 200 with an empty body and nothing else runs. - The client key. The TCP peer address with its port removed (an IPv6 peer keeps its form, including a
::ffff:prefix). If that address matches an entry oftrusted_proxies(an exact IP,localhost, or an IPv4 CIDR; the match ignores a::ffff:prefix) the client is the one the proxy names:X-Real-IPwhen it is a public IPv4 address, else the last public IPv4 entry of the comma listX-Forwarded-For, else the last public IPv4for=ofForwarded(quotes and ports removed, private and loopback addresses skipped); a trusted proxy that names no client is itself the client and is never limited. - Admission, in this order. (a) A request carrying
X-SignatureorX-Node-Public-Keyfrom a client under lockout → 429 withRetry-After= the seconds of lockout left and body{"success":false,"error":"too many failed authentications from this client; try again later","code":429}. (b) The write limiter for POST, PUT and DELETE (and forPOST /accounts/profiles, a read sent as POST) or the read limiter for GET (skipped when its limit is 0): a sliding window of 60 s per client admitting at mostlimitrequests; a refusal is 429 withRetry-After: <60 − age of the oldest admitted request + 1>and body{"success":false,"error":"too many write requests from this client; try again later","code":429}(reads:too many requests from this client; try again later). The per-client tables are compacted when they exceed 20,000 clients. (c) The lockout counter: every failed signed authentication (§2) counts for the client;auth_failure_lockout_thresholdfailures within 300 s lock it forauth_failure_lockout_seconds; a success clears its failures. - Error shape. Every handler answers
{"success":false,"error":E,"code":N}with HTTP status N. E is sanitised: every error-kind name such asValidationError:orCryptoError:is removed wherever it stands (Invalid ZBC address: CryptoError: Address checksum validation failed→Invalid ZBC address: Address checksum validation failed); a JSON-library message becomesInvalid request: <the text after "] ">(a bracketed tag in the middle of a message is removed); a bare message of the integer parser becomesInvalid numeric value, and a message<prefix>: <the parser's name>becomes<prefix>: invalid numeric value; a message that still names an internal of the implementation (its JSON library, its language runtime or its database engine) becomesInternal errorfor 5xx andInvalid requestfor 4xx. An error escaping a handler is mapped: an invalid number → 400Invalid numeric value in the request; an out-of-range number → 400A number in the request is out of range; a JSON error → 400Invalid request: the body is not the JSON this route expects; anything else → 500 with the sanitised message. - Two kinds of 404. A path that matches no route is 404 with an empty body; a 404 with a JSON body is a real answer of a route.
- Content types.
application/jsonfor every handler body, except the wallet page (text/html), a token icon (its image type) and a stored file's content (application/octet-stream).
Rule activation. None.
Rejections and errors. As above.
Vector. computed (the route definitions; the answers do not depend on chain data).
- INPUT:
GET /api/v1/nonexistent404→ EXPECTED OUTPUT: 404, 0-byte body. - INPUT:
GET /api/v1/transactions/zzz→ EXPECTED OUTPUT: 400{"success":false,"error":"Invalid transaction id: expected 64 hex characters, the ZTX_ form, or the decimal transaction id","code":400}. - INPUT:
GET /api/v1/blocks/hash/12→ EXPECTED OUTPUT: 400{"success":false,"error":"Invalid block hash: expected 64 hex characters","code":400}. - INPUT:
GET /api/v1/apps/18446744073709551616→ EXPECTED OUTPUT: 400{"success":false,"error":"invalid app id","code":400}. - INPUT:
OPTIONS /api/v1/node/infoat the node → 200 with the headers of step 2 and an empty body (a gateway in front of the node may answerOPTIONSitself with its own headers, §9).
Test cases · §1
5 cases · 1 valid · 4 invalid · 5 reference
A path that matches no route answers 404 with an empty body
A stated value: there is nothing to compute. The statement is a refusal: what a compatible node does with this input.
- request
GET /api/v1/nonexistent404- status
404- body
A transaction id of the wrong shape
A stated value: there is nothing to compute. The statement is a refusal: what a compatible node does with this input.
- request
GET /api/v1/transactions/zzz- status
400- body
{"success":false,"error":"Invalid transaction id: expected 64 hex characters, the ZTX_ form, or the decimal transaction id","code":400}
A block hash of the wrong length
A stated value: there is nothing to compute. The statement is a refusal: what a compatible node does with this input.
- request
GET /api/v1/blocks/hash/12- status
400- body
{"success":false,"error":"Invalid block hash: expected 64 hex characters","code":400}
An app id above the 64-bit range
A stated value: there is nothing to compute. The statement is a refusal: what a compatible node does with this input.
- request
GET /api/v1/apps/18446744073709551616- status
400- body
{"success":false,"error":"invalid app id","code":400}
OPTIONS at the node answers 200 with the CORS headers and an empty body
Headers: Access-Control-Allow-Origin: *; Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS; Access-Control-Allow-Headers: Content-Type, X-Node-Public-Key, X-Timestamp, X-Signature. A gateway in front of the node may answer OPTIONS itself with its own headers (§9).
A stated value: there is nothing to compute. A compatible node shows the same value.
- request
OPTIONS /api/v1/node/info- status
200- body
Defects to match. None.
§2 Signed requests and scopes
Purpose. An implementation must check proof of possession of a key on the few routes that act in a key's name.
Inputs. Headers X-Node-Public-Key (64 hex), X-Timestamp (decimal unix seconds), X-Signature (128 hex); the request method, path and body; the clock.
Output and effect. Admission to the route, or 401; a failure counts toward the client's lockout (§1); a success clears it.
How to compute it.
- Preimage = ASCII
METHOD ":" PATH ":" TIMESTAMP ":" BODY: METHOD as sent, PATH without the query string, TIMESTAMP the header's exact text, BODY the raw body (empty for GET). Signature = plain Ed25519 over those bytes (02; no tag, no hashing). - Checks, in order, each failure → 401
{"success":false,"error":"Authentication failed: <reason>","code":401}: the three headers present (Missing X-Node-Public-Key header,Missing X-Timestamp header,Missing X-Signature header); the key is 64 characters (Invalid X-Node-Public-Key: must be 64 hex characters); the signature is 128 characters (Invalid X-Signature: must be 128 hex characters); the timestamp parses (Invalid X-Timestamp: must be a valid unix timestamp);|now − timestamp| ≤ 300(Request expired: timestamp must be within 5 minutes of current time); the key is hex (Invalid public key format); the signature is hex (Invalid signature format); the signature verifies (Invalid signature, orSignature verification failed: …when verification itself fails). Nothing binds a signed request to one use: the same request is accepted again within the 300-second window. - Scope: any key (the holder of the key), or this node's operator (the key equals this node's own key; else 401
Unauthorized: only this node's operator can perform admin actions).
| route | scope |
|---|---|
GET /node/public-ip |
any key, always signed |
POST /admin/clear-blacklist |
operator, always signed |
GET /node/system-stats |
operator when X-Node-Public-Key is present; an unsigned call from an unrelayed loopback is the operator; any other unsigned call gets the public view (§8) |
GET /blocks/height/:h, GET /blocks/hash/:hash, GET /transactions/:id (the archive read path, §4, §5) |
operator, only when a pruned item must be rebuilt; a failed signature → 401 Authentication failed: … |
GET /accounts/:address/stored-files |
any key, when X-Signature is present; then the key must be the account or a member of its group, else 403 the signing key is not this account or a member of its group; a failed signature → 401 signature rejected: <reason> |
GET /storage/files/:root/content |
any key, when the file (or a file sharing its pieces) is private; 401 this file is private: sign the request with the account that stored it (<reason>) or this file shares content with a private file: …; 403 this file is private and that account is not permitted to read it or … shares content with a private file that account is not permitted to read |
An unrelayed loopback caller: the peer address is 127.x.x.x, ::1, ::ffff:127.x.x.x or localhost, and the request carries none of X-Forwarded-For, X-Real-IP, Forwarded, CF-Connecting-IP, no Origin, and no user agent naming the ZooBC gateway.
Rule activation. None.
Rejections and errors. As listed.
Vector. computed (the method of the start-up public-IP discovery, 30).
- INPUT: key from the Ed25519 seed = the 32 ASCII bytes
ZooBC-spec-signed-request-key-01,X-Timestamp: 1793715000,GET /api/v1/node/public-ip, empty body. EXPECTED: public key59fa151ccaaff39645ac675ef5e4cfef87a35c958b970d8eadb4daad7b3cce02; preimage = the ASCII bytesGET:/api/v1/node/public-ip:1793715000:(4745543a2f6170692f76312f6e6f64652f7075626c69632d69703a313739333731353030303a);X-Signature: c312bd27eb0e2f285734b8c31e94f5a32291b933e8494ef486870568ac32f0d53cf017c3cfbe6fc137c67047f12ea15960c81dd55d900a017a383fe9ded35c06; the node answers 200{"ip":…,"port":…,"remote_addr":…,"remote_port":…}when the clock is within 300 s of 1,793,715,000. - INVALID INPUT: the same request without headers → 401
{"success":false,"error":"Authentication failed: Missing X-Node-Public-Key header","code":401}; with a 130-character signature → 401… Invalid X-Signature: must be 128 hex characters.
Test cases · §2
7 cases · 3 valid · 4 invalid · 1 reference
Sign GET /api/v1/node/public-ip at 1,793,715,000
Loading the test widget…
The signed request is accepted within 300 s of its timestamp
Loading the test widget…
The same request without headers
Loading the test widget…
A 130-character signature
Loading the test widget…
The request 301 s after its timestamp
Loading the test widget…
The signature does not cover another path
Loading the test widget…
The answer of the signed public-IP request
The fields of the answer, when the clock is within 300 s of 1,793,715,000; the values are the caller's.
A stated value: there is nothing to compute. A compatible node shows the same value.
- request
GET /api/v1/node/public-ip (signed)- status
200- body
{"ip":…,"port":…,"remote_addr":…,"remote_port":…}
Defects to match. None.
§3 Conventions shared by the read routes
Purpose. An implementation must read address parameters and write values exactly as the clients expect.
Inputs. Path and query parameters.
Output and effect. The account bytes a route looks up; the spelling of every value in its answer.
How to compute it.
- Typed parse (routes marked T). A
ZBC_…text (01) → the typed account00000000 ‖ key(36 bytes); a bad checksum → 400Invalid ZBC address: <reason>(e.g.Invalid ZBC address: Address checksum validation failed). Otherwise hex of any even length (a0xprefix removed) is taken as the stored bytes as they are — except0xfollowed by exactly 40 hex, an Ethereum address, which becomes its typed 24-byte form04000000 ‖ address. Any other text goes through the general address decoder of01(Ethereum, Bitcoin, Cardano, Solana, Polkadot, Taproot, …); failure → 400Invalid address: <reason>. - Two-form match (routes marked 2). The parameter is parsed as in step 1 except that a
ZBC_…text gives the bare 32-byte key; rows are then matched under both forms: for 32 bytes[key, 00000000 ‖ key], for 36 bytes of type 0[the 36 bytes, their last 32]. (No account row on a chain with ruletyped_accounts_onlyis stored bare; the second form matches nothing there.) ZBC_or hex only (routes marked Z): aZBC_…text or hex; other encodings are refused with the route's own 400 (bad addresson/objectsand/stored-files, where the bytes must be 32 or 36 long).- Group scope (escrows, escrow requests): the account itself, its group when it is an active member, the group's members when it is a group; each row carries
matched_via(self,group,member) andmatched_address./accounts/:a/objectsrows carry onlymatched_address;/survivalrows carryrole(owner/funder). - Values. Byte strings: lowercase hex without
0x. Addresses in answers: the hex of the stored form (a native account is 36 bytes beginning00000000), unless a field says_zbcor the route saysZBC_. Balances and fees: integers in atomic units (10⁸ per ZBC;one_zbcis echoed where relevant). Heights: integers. Timestamps: unix seconds. - 64-bit identifiers. Decimal strings: escrow
idandid_str,token_idon/tokens,/tokens/:id,/accounts/:a/tokens,/bridge/coins, appid, marketid, order and offerid, liquid-payment, schedule, trigger, longevity (target_tx_id) and historyid. Numbers:node_idon/nodes(withnode_id_strthe string), on/governance/proposalsvotes, on/internal/attestand/peers/archival(−1 when the key is not registered; withnode_id_str), escrow-requestidandescrow_transaction_id(each with an_strstring twin), andtoken_idon/tokens/volume,/apps/pool,/schedules,/bridge/withdrawals/:hash,/bridge/withdrawal-requestsrows,give_token_id/want_token_idon offers,base_token_id/quote_token_idon markets,stake_token_idon app rows. - Text. Escaping: invalid UTF-8 → U+FFFD;
"\newline, carriage return and tab escaped; other control characters as\u00XX;/,<,>and non-ASCII written raw. Dataset values are given twice,value(escaped) andvalue_b64(standard base64 of the raw bytes). The DFS routes escape without the UTF-8 replacement. - Which height a read reflects. Balance reads: the confirmed height (tip − the confirmation depth,
19/21); listings: the newest rows (latest = 1);current_height/chain_heightfields echo the tip.
Rule activation. liquid_exact_vesting decides how /liquid computes vested (08); survival_field and account_groups are echoed as booleans by the survival and link-preview routes; all active from height 0 on every chain.
Rejections and errors. As listed.
Vector. computed (the parse of 01). INPUT: GET /api/v1/address/00000000bccb80820d3e3fce6e62f1c283acf6b0ab884a937af47120de2ffe88a393b4d6 → EXPECTED OUTPUT: {"input":"00000000bccb80820d3e3fce6e62f1c283acf6b0ab884a937af47120de2ffe88a393b4d6","address":"00000000bccb80820d3e3fce6e62f1c283acf6b0ab884a937af47120de2ffe88a393b4d6","account_type":0,"type_name":"ZooBC","bytes":36}. INVALID INPUT: the text form of that key, ZBC_XTFYBAQN_HY7443TC_6HBIHLHW_WCVYQSUT_PL2HCIG6_F77IRI4T_WTLOGT6O, with its first base32 character changed (ZBC_YTFYBAQN_HY7443TC_6HBIHLHW_WCVYQSUT_PL2HCIG6_F77IRI4T_WTLOGT6O: the three check bytes no longer match SHA3-256(key ‖ ZBC)) → on a T route such as GET /api/v1/accounts/<it> 400 {"success":false,"error":"Invalid ZBC address: Address checksum validation failed","code":400}; on GET /api/v1/address/<it> 400 not an address this chain can hold.
Test cases · §3
5 cases · 3 valid · 2 invalid
GET /api/v1/address/ of a typed native account
Loading the test widget…
The ZBC_ text of the same account
Loading the test widget…
The ZBC_ text with its first base32 character changed, on a route marked T
Loading the test widget…
The same text on GET /api/v1/address/
Loading the test widget…
0x and 40 hex digits is an Ethereum account
Loading the test widget…
Defects to match. The id spelling (string versus number) differs by route (step 6); a client must accept the spelling each route uses. ⚠ /node/blacklist writes the ban reason without JSON escaping, so a reason holding " or \ makes that answer invalid JSON.
§4 Chain and block routes
Purpose. An implementation must serve blocks, chain status, fee parameters and rules.
Inputs. As per route.
Output and effect. Reads only.
How to compute it.
| route | parameters | response (fields in emitted order) | errors |
|---|---|---|---|
GET /api/v1/blockchain/height |
— | {height (the tip), confirmed_height, finalized_height (the floor signed by the spine signers, 24/26; 0 when unknown)} |
— |
GET /api/v1/blockchain/status |
— | {height, confirmed_height, finalized_height, escrow_release_height, escrow_timeout_cap_seconds, burned_total, latest_block_hash, survival_mode, survival_mode_tip, survival_min_producers, survival_distinct_producers, latest_block_time} — escrow_release_height = the escrow horizon for tip + 1 (12); escrow_timeout_cap_seconds = (escrow_release_height − (tip + 1)) × 15 (0 when the release height is 0): the longest an escrow sent now may ask for without a survival deposit; burned_total = the sum of ledger rows of event type 74 (0: nothing writes it); survival_mode = the survival flag the next block (tip + 1) is judged by, computed as 36 §12 computes it (false where rule survival_mode is not active at tip + 1); survival_mode_tip = the stored flag of the tip block; survival_min_producers = N (0 = off), the fewest distinct blocksmiths before survival mode; survival_distinct_producers = distinct blocksmiths of the main-chain blocks [max(1, tip + 1 − 120), tip] |
500 Failed to get blockchain status when the tip cannot be read |
GET /api/v1/blocks/latest |
— | block object | 404 No blocks found |
GET /api/v1/blocks/height/:height |
decimal; above 4,294,967,295 → 404 | block object; a block this node has pruned is read from the snapshot the decentralised storage keeps for its height and answered as the block object plus source:"snapshot", snapshot_reference_height, spine_height; a snapshot not rebuilt here yet is rebuilt from its holders only for this node's operator (§2) |
403 old blocks are served by archival nodes; this node rebuilds them only for its operator; 401 Authentication failed: …; 404 Block not found: <reason> (Block not found when no archive is configured); 400 Invalid numeric value |
GET /api/v1/blocks/hash/:hash |
64 hex (0x allowed); height (optional: the snapshot to read a pruned block from) |
block object; the same archive path | 400 Invalid block hash: expected 64 hex characters; as above |
GET /api/v1/blocks/height/:h/touched-accounts |
digits only (anything else is a route miss: empty 404); ⚠ a height above 4,294,967,295 is read modulo 2³² (/blocks/height/4294967296/touched-accounts serves block 0 while echoing "height":4294967296) |
{height, block_hash, merkle_root, transactions:[{tx_index, tx_hash, type, [app_id], accounts:[hex…]}], derived_credits:[hex…]} — accounts = every account of at least 24 bytes the transaction names (sender, recipient, body accounts, a CreateApp's invited opponent); for an app transaction (CreateApp: its own id; JoinApp, AppMove, ResignApp, ClaimAppTimeout, SettleApp: the body's app id) app_id (string) is added and accounts is extended, without duplicates, with the app's creator, every player and the invited opponent; derived_credits = the accounts of the ledger rows at that height |
404 Block not found |
GET /api/v1/blockchain/fee-params |
— | {min_fee 2,500,000, min_node_registration_fee 2,500,000, fee_scale (the newest fee_scalerow when positive, else 1,000,000), initial_fee_scale 1,000,000, effective_min_fee = ⌈2,500,000 × fee_scale / 1,000,000⌉, one_zbc, dataset_storage_cost_per_mib (row, else 100,000,000), storage_oracle_multiplier_ppm (row, else 1,000,000), min_payload_persistence_blocks (row, else 17,280), dataset_billing_period_blocks (the snapshot cycle =main_snapshot_interval, else 172,800, at least 2), block_time_interval (row, else 10), token_persist_period_cost (row, else 100,000,000), token_free_persist_blocks (row, else the snapshot cycle), min_token_persist_blocks 5,760, account_rent_period_cost (row, else 100,000,000), account_rent_period_blocks (the snapshot cycle), node_registration_minimum (the voted queue minimum, 09), node_registration_entry_minimum (the higher of it and queue_median_fraction_bps of the median queued stake; the voted minimum when the queue cannot be read), queue_median_fraction_bps (row clamped to 0…10,000, else 5,000), producer_share_bps 0, overpay_kept false, fee_above_minimum "refunded"} |
— |
GET /api/v1/blockchain/estimate-fee |
type (default 1), body_length (default 8, 0…1,048,576), message_length (default 0, 0…1,048,576), actions (a batch type's action count, 1 … 25 payments / 32 token transfers / 1,000 storage proofs), sender (an address, T; prices a queue attendance by its sender), escrow=1, escrow_approver_length (8…256, default 36), escrow_instruction_length, escrow_lock_seconds, escrow_kind (single, request, cosigned, cosigned_request), survival, survival_periods. A numeric parameter that does not parse takes its default. |
{minimum_fee, duty, fee_exactly_zero, [note], [batch_actions], survival, survival_active, transaction_version (2 when survival > 0), survival_minimum 10,000,000, survival_below_minimum, survival_payload_bytes (max(1, body + message), a batch's own body), survival_rent_per_period, survival_periods, survival_free_until_height, survival_paid_through_height, [survival_periods_requested, survival_for_periods], total_debit_excluding_amount (= fee + escrow rent + survival), fee_above_minimum ("refunded", or "refused" for a duty), producer_share_bps 0, escrow_rent, overpay_refunded (false when fee_exactly_zero), one_zbc, [escrow_kind, escrow_envelope_bytes], timestamp} — the minimum fee of 04 at tip + 1; duty = a node-duty type; fee_exactly_zero = a fee-free duty (minimum 0, any other fee refused); note for duties and queue attendance; batch_actions = the actions priced (the sum of one-action minimums over a synthetic batch body); with survival_periods and no survival, survival is set to the amount those periods need (longevity maths of §7) |
400 sender: …; 400 escrow_kind must be single, request, cosigned or cosigned_request |
GET /api/v1/blockchain/rules |
— | an object with keys in alphabetical order: activation_floor_blocks (5,760), bundle_id (this binary's bundle, 601 for 0.6.1), bundles[], counted_seats (the counted registered nodes), current_height, next_height, production_halt (empty or the reason), rules[], signal_window_blocks (= min(max(720, 5 × counted registered nodes), 1,440) for the next block, 29); each bundle entry, keys alphabetical: bundle (the bundle id), checked_for_height, effective_height (or null), floor_blocks, floor_height (or null), gated, observation_only (true for a release registered above this binary's bundle: watched, its readiness only stops this node's production), registered, registry_size, rules[], scheduled_height, signalling_producers, state, threshold, window_blocks with state one of active, activating, pending, not gated (compiled height stands), unregistered (never activates until the release is registered), watching a registered future release, readiness observed; this binary must be upgraded (the list is empty on a chain whose every rule is at 0); each rule, keys alphabetical: accumulating, active, active_next_block, blocks_until_active, bundle, default_height, default_off_height, description, height, name, off_height, off_source, recorded_off, recorded_on ({block_hash, height} or null), retirable, retired, scheduled_height, source ("consensus_parameters" or "compiled_default"), transaction_types ([{name, type}]), warm_up_blocks — one entry per rule of the activation table (29: 125 on a 0.6.1 build, 24 of them in bundle 601) |
— |
GET /api/v1/blockchain/reserved-symbols |
— | {charset_regex:"^[A-Z0-9]{2,10}$", reserved_z_namespace, blocklist:[sorted symbols]} (14) |
— |
GET /api/v1/spine/blocks/:height |
decimal; above 4,294,967,295 → 404 | keys alphabetical: {hash, height, previous_hash, reference_block_height, timestamp} of the spine block (25) |
404 Spine chain not enabled; 404 Spine block not found; 400 Bad request: invalid numeric value |
GET / and GET /wallet |
— | the wallet page (text/html) from $ZOOBC_WALLET_HTML, ~/.zoobc/wallet.html, beside the binary, wallet.html or web/wallet.html, first found |
404 JSON when none |
Block object, fields in order: height, version (601 for a block by a 0.6.1 blocksmith; 1 for block 0), timestamp, previous_block_hash, block_seed, block_seed_proof (the 80-byte ECVRF proof, hex), block_signature, cumulative_difficulty (string), blocksmith_public_key, total_amount, total_fee, total_coinbase, block_hash, merkle_root, merkle_tree, reference_block_height, transaction_count, transactions: [transaction hash hex…] (hashes only).
Rule activation. None in the API; the fields report the rules' current effect.
Rejections and errors. As in the table.
Vector. computed (the TestNet genesis file, 32 §12, and the survival rule of 36 §12).
- INPUT:
GET /api/v1/blockchain/fee-paramson a fresh TestNet chain (no vote applied, the fee scale at its initial value) → EXPECTED OUTPUT:{"min_fee":2500000,"min_node_registration_fee":2500000,"fee_scale":1000000,"initial_fee_scale":1000000,"effective_min_fee":2500000,"one_zbc":100000000,"dataset_storage_cost_per_mib":5000000,"storage_oracle_multiplier_ppm":1000000,"min_payload_persistence_blocks":17280,"dataset_billing_period_blocks":172800,"block_time_interval":15,"token_persist_period_cost":10000000,"token_free_persist_blocks":172800,"min_token_persist_blocks":5760,"account_rent_period_cost":1000000,"account_rent_period_blocks":172800,"node_registration_minimum":10000000000,"node_registration_entry_minimum":10000000000,"queue_median_fraction_bps":5000,"producer_share_bps":0,"overpay_kept":false,"fee_above_minimum":"refunded"}(node_registration_entry_minimumequals the voted minimum while the queue is empty). - INPUT:
GET /api/v1/blockchain/estimate-fee?type=1→ EXPECTED OUTPUT: the fields in this order,{"minimum_fee":<the floor of 04 §2 for a type-1 transaction of 8 body bytes at tip + 1>,"duty":false,"fee_exactly_zero":false,"survival":0,"survival_active":true,"transaction_version":1,"survival_minimum":10000000,"survival_below_minimum":false,"survival_payload_bytes":8,"survival_rent_per_period":<13 §2 for 8 bytes>,"survival_periods":0,"survival_free_until_height":<the free window's end for tip + 1, 13 §2>,"survival_paid_through_height":<the same>,"total_debit_excluding_amount":<= minimum_fee>,"fee_above_minimum":"refunded","producer_share_bps":0,"escrow_rent":0,"overpay_refunded":true,"one_zbc":100000000,"timestamp":<the node's clock>}; withescrow_kind=other→ 400escrow_kind must be single, request, cosigned or cosigned_request. - INPUT:
GET /api/v1/blockchain/statuson a fresh TestNet chain (tip 0; the genesis file'ssurvival_min_producers5,main_snapshot_interval172,800,main_snapshot_min_height760) → EXPECTED OUTPUT{"height":0,"confirmed_height":0,"finalized_height":0,"escrow_release_height":345600,"escrow_timeout_cap_seconds":5183985,"burned_total":0,"latest_block_hash":"<the chain's block-0 hash>","survival_mode":true,"survival_mode_tip":false,"survival_min_producers":5,"survival_distinct_producers":0,"latest_block_time":1793509027}:escrow_release_height= (1 div 172,800 + 2) × 172,800 = 345,600 (345,600 − 172,800 ≥ 760, so the minimum height does not move it) and the cap = (345,600 − 1) × 15; block 1 is judged in survival mode (no producer in the empty window[1, 0], 0 < 5), and the next block leaves it once 5 distinct blocksmiths made the blocks of its window. - INPUT: the same chain (N = 5, as in both genesis files) at tip 10,000 with 4 distinct blocksmiths in
[9,881, 10,000]and the stored flag at 10,000 true → EXPECTED OUTPUT contains"survival_mode":true,"survival_mode_tip":true,"survival_min_producers":5,"survival_distinct_producers":4; with 5 distinct blocksmiths in that window and the stored flag at 10,000 true →"survival_mode":false,"survival_mode_tip":true,…,"survival_distinct_producers":5. At tip 12,473:escrow_release_height= (12,474 div 172,800 + 2) × 172,800 = 345,600 andescrow_timeout_cap_seconds= (345,600 − 12,474) × 15 = 4,996,890. - INPUT:
GET /api/v1/blockchain/ruleson either chain with its 11 genesis registered nodes counted →bundle_id601,counted_seats11,signal_window_blocks720 (= min(max(720, 55), 1,440)),activation_floor_blocks5760,bundles[],production_halt"", 125 rules each with"height":0,"source":"consensus_parameters"; the entry ofsplit_policy:{"accumulating":true,"active":true,"active_next_block":true,"blocks_until_active":0,"bundle":0,"default_height":30000,"default_off_height":null,"description":…,"height":0,"name":"split_policy","off_height":null,"off_source":"compiled_default","recorded_off":null,"recorded_on":{"block_hash":<the chain's block-0 hash>,"height":0},"retirable":false,"retired":false,"scheduled_height":0,"source":"consensus_parameters","transaction_types":[{"name":"SetSplitPolicyTransaction","type":54}],"warm_up_blocks":0}(default_heightis the height the binary carries for the rule when a genesis names none, 30,000 for this one;heightis the genesis's 0); the entry ofspine_equivocation_reportlists"transaction_types":[{"name":"SpineEquivocationReportTransaction","type":62}]and"bundle":601. - INPUT:
GET /api/v1/blocks/height/4294967296→ 404Block not found(above 4,294,967,295);GET /api/v1/blocks/height/0→ block 0 with"version":1and"transaction_count":0.
Test cases · §4
15 cases · 13 valid · 2 invalid · 9 reference
The fee parameters of a fresh TestNet chain
No vote applied, the fee scale at its initial value; node_registration_entry_minimum equals the voted minimum while the queue is empty.
A stated value: there is nothing to compute. A compatible node shows the same value.
- request
GET /api/v1/blockchain/fee-params- status
200- body
{"min_fee":2500000,"min_node_registration_fee":2500000,"fee_scale":1000000,"initial_fee_scale":1000000,"effective_min_fee":2500000,"one_zbc":100000000,"dataset_storage_cost_per_mib":5000000,"storage_oracle_multiplier_ppm":1000000,"min_payload_persistence_blocks":17280,"dataset_billing_period_blocks":172800,"block_time_interval":15,"token_persist_period_cost":10000000,"token_free_persist_blocks":172800,"min_token_persist_blocks":5760,"account_rent_period_cost":1000000,"account_rent_period_blocks":172800,"node_registration_minimum":10000000000,"node_registration_entry_minimum":10000000000,"queue_median_fraction_bps":5000,"producer_share_bps":0,"overpay_kept":false,"fee_above_minimum":"refunded"}
effective_min_fee at the initial fee scale
Loading the test widget…
The fee estimate of a SendZBC: the fields in order
minimum_fee is the floor of 04 §2 for a type-1 transaction of 8 body bytes at tip + 1 and total_debit_excluding_amount equals it; survival_rent_per_period is 13 §2 for 8 bytes; the two heights are the free window's end for tip + 1 (13 §2); timestamp is the node's clock.
A stated value: there is nothing to compute. A compatible node shows the same value.
- request
GET /api/v1/blockchain/estimate-fee?type=1- status
200- body
{"minimum_fee":…,"duty":false,"fee_exactly_zero":false,"survival":0,"survival_active":true,"transaction_version":1,"survival_minimum":10000000,"survival_below_minimum":false,"survival_payload_bytes":8,"survival_rent_per_period":…,"survival_periods":0,"survival_free_until_height":…,"survival_paid_through_height":…,"total_debit_excluding_amount":…,"fee_above_minimum":"refunded","producer_share_bps":0,"escrow_rent":0,"overpay_refunded":true,"one_zbc":100000000,"timestamp":…}
An escrow kind the estimate does not know
A stated value: there is nothing to compute. The statement is a refusal: what a compatible node does with this input.
- request
GET /api/v1/blockchain/estimate-fee?type=1&escrow_kind=other- status
400- body
{"success":false,"error":"escrow_kind must be single, request, cosigned or cosigned_request","code":400}
The status of a fresh TestNet chain (tip 0)
The genesis file's survival_min_producers 5, main_snapshot_interval 172,800 and main_snapshot_min_height 760.
A stated value: there is nothing to compute. A compatible node shows the same value.
- request
GET /api/v1/blockchain/status- status
200- body
{"height":0,"confirmed_height":0,"finalized_height":0,"escrow_release_height":345600,"escrow_timeout_cap_seconds":5183985,"burned_total":0,"latest_block_hash":"<the chain's block-0 hash>","survival_mode":true,"survival_mode_tip":false,"survival_min_producers":5,"survival_distinct_producers":0,"latest_block_time":1793509027}
escrow_timeout_cap_seconds at tip 0: (345,600 − 1) × 15
Loading the test widget…
The survival fields at tip 0: block 1 is judged in survival mode
Loading the test widget…
The survival fields at tip 10,000 with 4 distinct blocksmiths in [9,881, 10,000] and the stored flag true
Loading the test widget…
The same tip with 5 distinct blocksmiths in that window and the stored flag true
Loading the test widget…
escrow_timeout_cap_seconds at tip 12,473: (345,600 − 12,474) × 15
Loading the test widget…
The rules route on either chain with its 11 genesis registered nodes counted
125 rules, each with "height":0,"source":"consensus_parameters"; signal_window_blocks = min(max(720, 55), 1,440).
A stated value: there is nothing to compute. A compatible node shows the same value.
- request
GET /api/v1/blockchain/rules- status
200- body
{"activation_floor_blocks":5760,"bundle_id":601,"bundles":[],"counted_seats":11,…,"production_halt":"",…,"rules":[…],"signal_window_blocks":720}
The rules route's entry of split_policy
default_height is the height the binary carries for the rule when a genesis names none; height is the genesis's 0.
A stated value: there is nothing to compute. A compatible node shows the same value.
- request
GET /api/v1/blockchain/rules- status
200- body
{"accumulating":true,"active":true,"active_next_block":true,"blocks_until_active":0,"bundle":0,"default_height":30000,"default_off_height":null,"description":…,"height":0,"name":"split_policy","off_height":null,"off_source":"compiled_default","recorded_off":null,"recorded_on":{"block_hash":"<the chain's block-0 hash>","height":0},"retirable":false,"retired":false,"scheduled_height":0,"source":"consensus_parameters","transaction_types":[{"name":"SetSplitPolicyTransaction","type":54}],"warm_up_blocks":0}
The rules route's entry of spine_equivocation_report
A stated value: there is nothing to compute. A compatible node shows the same value.
- request
GET /api/v1/blockchain/rules- status
200- body
{…,"bundle":601,…,"name":"spine_equivocation_report",…,"transaction_types":[{"name":"SpineEquivocationReportTransaction","type":62}],…}
A block height above 4,294,967,295
A stated value: there is nothing to compute. The statement is a refusal: what a compatible node does with this input.
- request
GET /api/v1/blocks/height/4294967296- status
404- body
{"success":false,"error":"Block not found","code":404}
Block 0
A stated value: there is nothing to compute. A compatible node shows the same value.
- request
GET /api/v1/blocks/height/0- status
200- body
{…,"version":1,…,"transaction_count":0,…}
Defects to match. None.
§5 Transaction routes
Purpose. An implementation must accept, show, track and cancel transactions over HTTP.
Inputs. The POST /api/v1/transactions JSON body; path ids; the cancel signature.
Output and effect. Admission to the node's staging pool or mempool (04), a broadcast to peers (28), reads.
How to compute it. POST /api/v1/transactions, in order:
- Load gates, each 503 with its message: node not accepting (
Service temporarily unavailable - node in emergency mode); CPU limit (… - high CPU load); P2P load High, or Medium with received TPS > 2 (… - too many P2P requests); thread level High (… - thread limit reached); file-descriptor level Medium or above (… - file descriptor limit reached); mempool above 10,000 (… - mempool backpressure). - Body: a JSON object (else 400
Request body must be a JSON object; unparsable → 400Invalid JSON: …). Fields:version(integer, default 1),timestamp(integer),transaction_type(integer),fee(integer),survival(integer or decimal string; whole atomic units, else 400survival must be a whole number of atomic units; non-zero below version 2 → 400survival needs transaction version 2 or 3: …),expiry(integer or decimal string, seconds 0…86,400, 0 = the default hour; else 400expiry must be between 0 and 86400 seconds/expiry must be a whole number of seconds; non-zero below version 3 → 400expiry needs transaction version 3: a version-N transaction carries no expiry (its signed bytes have no place for one)),sender_account_address(hex),recipient_account_address(hex, may be empty),transaction_body_bytes(hex, may be empty,0xallowed),signature(hex, required, non-empty),message_hex(hex) ormessage(text;message_hexwins), and optionallyescrow: {approver_address (hex, required: else 400 Escrow requires approver_address), timeout (integer, required: else Escrow requires timeout), commission (integer), instruction (text), multi_party (boolean: else escrow: field 'multi_party' must be true or false), co_signer_signature (hex), escrow_request_id (integer or decimal string: else escrow_request_id must be a decimal 64-bit integer (number or string))}. Unknown fields are ignored;versionandtransaction_typeaccept any JSON integer and are cut to the field width (a version above 255 is written as its low byte; an implementation may refuse out-of-range values instead); a wrong type → 400 naming the field (field 'version' must be an integer); a missing or null signature →field 'signature' is required, followed by(this route takes the transaction fields listed in the API guide, each signed by its sender; 'tx' and 'signatures' are not among them)when the body carries atxor asignatureskey. - Hash the assembled transaction (
03); a failure → 400Invalid transaction: …. Already in a block → 202{"status":"success","duplicate":true,"state":"confirmed","block_height":h,"message":"Transaction already confirmed at height h - not resubmitted","transaction_hash":hex}. - When neither staging nor the pool holds the hash: serialise with its signature and parse back (
03): failure → 400Transaction validation failed: the transaction bytes do not parse: …; the stateless pre-admission check of04→ 400Transaction validation failed: <error>; both are recorded in the rejection log with stagesubmission. - Stage it (or add it to the pool when there is no staging pool); a duplicate counts as accepted; any other error → 400
Transaction validation failed: …and a rejection-log entry. - Accepted, not a duplicate: broadcast to every connected peer (
28); reply 202{"status":"success","duplicate":false,"state":"new","message":"Transaction submitted successfully","transaction_hash":hex}; a duplicate: 202 withduplicate:true, state:"pending", message:"Transaction already known - this node is holding it already".
GET /api/v1/transactions/:id: id = 64 hex (0x allowed), ZTX_…, or a decimal transaction id (03) resolved through the chain. Lookup order: the pool, the chain, the pending-multisig table, then the archive read path (the snapshot the decentralised storage keeps for the transaction's height: ?height=, else this node's activity index, else only snapshots already rebuilt here; answer with source:"snapshot", snapshot_reference_height, spine_height; the operator rule, 401 and 403 of /blocks/height). A decimal id the chain does not hold goes straight to the archive. A found transaction answers the transaction object plus transaction_bytes (the canonical signed bytes, hex); a pending multisig inner transaction answers {transaction_hash, pending_multisig:true, multisig_address (the bare 32-byte hash, hex), transaction_type (inner), status, block_height, transaction_bytes}; else 404 Transaction not found; another shape → 400 (§1 vector).
Transaction object, in order: transaction_hash, version, timestamp, transaction_type, sender_account_address, recipient_account_address, fee, survival (0 below version 2), expiry (0 below version 3), signature, block_height, transaction_index, transaction_body_bytes, then message_hex and, when the bytes hold no control character other than tab, LF and CR, message; then, when an approver is set, escrow: {approver_address, commission, timeout, instruction, multi_party, status, [id, sender_address, recipient_address, amount, block_height]}.
GET /api/v1/transactions/:id/status: {transaction_hash (as given; the hex when a decimal id was resolved, plus transaction_id), status, …} with status = staging (+ description) | mempool (+ description, mempool_position, mempool_size, and last_skip_reason, last_skip_at when the rejection log holds a non-final note) | confirmed (+ block_height, description Transaction is confirmed in a block) | rejected (+ description, reason, stage, rejected_at) | not_found (HTTP 404, description Transaction not found in staging pool, mempool, or blockchain). No archive lookup.
GET /api/v1/transactions/pending?limit=&address=: a bare JSON array of up to limit pool transactions as transaction objects (limit default and cap 1,000; negative → 0; not a number → 1,000), optionally only those whose sender or recipient matches the address (2); a bad address → 400 Invalid ZBC address, Invalid address or Invalid address hex.
DELETE /api/v1/transactions/pending/:hash (64 hex): body {"signature": 128 hex} (else 400 signature (128 hex, Ed25519 over the cancel digest) is required); no pool → 503 Transaction pool not available; not pending here → 404 {"success":false,"removed":false,"message":"Not pending on this node (already mined, expired, or never received here)","transaction_hash"}; digest = SHA3-256(ASCII ZBC-CANCEL ‖ genesis hash (32) ‖ transaction hash (32)); the signature must verify for the pending transaction's sender with that account type's scheme (02), else 403 signature does not verify for the transaction's sender (counted as an authentication failure); removal failure → 409; success → 200 {"success":true,"removed":true,"transaction_hash","message":"Removed from this node's pool and its reservation released. Other nodes keep their copy until it expires; …"} and a rejection-log entry with stage cancelled. Only this node's copy is removed.
Rule activation. None in the routes (04 applies inside).
Rejections and errors. As listed; any other error in the submit route → 500 Internal error.
Vector. computed.
- INPUT:
POST /api/v1/transactionswith body{"version":"x"}→ EXPECTED OUTPUT: 400field 'version' must be an integer. - INPUT: body
{}→ 400field 'signature' is required; body{"tx":1}→ 400field 'signature' is required (this route takes the transaction fields listed in the API guide, each signed by its sender; 'tx' and 'signatures' are not among them). - INPUT: a version-1 body with
"expiry":600→ 400expiry needs transaction version 3: a version-1 transaction carries no expiry (its signed bytes have no place for one). - INPUT: the cancel digest for the 32-byte genesis hash
e003e4e3557ef19f0519bd345009dea7fb43b3445eaa043920c5dc23b3302871(an example value: a chain substitutes its own block-0 hash) and the transaction hashf1d31b42df64c11031b32a16a24a1431f88320553509e9920b2045556b493d85→ EXPECTED: the digest SHA3-256(5a42432d43414e43454c‖ genesis ‖ hash) (74 bytes in) =29a3616beb95955d8c2cd1744346a43255439a9927cfffc39381bd527a22c074; the cancel body is{"signature":"<128 hex: the sender's signature over that digest>"}.
Test cases · §5
5 cases · 1 valid · 4 invalid
A body with "version":"x"
Loading the test widget…
An empty object
Loading the test widget…
A body {"tx":1} in another envelope
Loading the test widget…
A version-1 body with an expiry of 600
Loading the test widget…
The cancel digest for the vectors' genesis hash and a transaction hash
Loading the test widget…
Defects to match. None.
§6 Account routes
Purpose. An implementation must answer everything a wallet asks about one account.
Inputs. :address parsed as marked (§3: T, 2, Z); query parameters.
Output and effect. Reads only.
How to compute it.
| route | address | parameters | response | errors |
|---|---|---|---|---|
GET /accounts/:address |
T; a bare 32-byte hex key → 404 | — | {address (as given), spendable_balance, balance, locked_balance (the stake of a non-deleted node owned by this account), total_balance = balance + locked, pop_revenue (Σ ledger events 8 and 19 up to the confirmed height), transact_policy}, plus a group object (below) when the address is a group member or a group; an unknown account answers zeros with 200 |
404 accounts are typed: a bare 32-byte key is not an account on this chain; 400 §3 |
GET /wallet/snapshot?address=&include= |
T | include = names matched by substring among balance, tokens, apps, schedules, escrows, liquid, movements (all when absent) |
{address, height, confirmed_height, finalized_height, sections:{<name>: that route's object, or {"error": the raw message}}}; the movements section holds at most 50 rows of a fixed event set, names other than events 8, 14, 19, 28, 29, 30 and 100 shown as movement, no booked_on |
— |
GET /accounts/:address/eth-tx-count |
an Ethereum address (0x + 40 hex, or the 40 hex alone) or its 48-hex typed form 04000000 ‖ address |
— | {address (48 hex), count (the account nonce, the same on every node), pending (the nonce the sender's next Ethereum carrier must carry: the first nonce at or above countthat no Ethereum carrier of this sender in this node's mempool or staging area already carries, the nonce read from each carrier's signed Ethereum transaction,04, 34§10; equal tocountwith nothing queued, andcount when the queue cannot be read)}; the Ethereum RPC adapter (30) answers eth_getTransactionCount with pending for the pending block tag and count for every other |
400 Invalid ETH address (any other form or length); 500 eth-tx-count error: … |
GET /dataset-address/:txhash |
64 hex or ZBS_ |
— | {tx_hash, zbs_address, account_hex ("0a000000" ‖ hash), balance, exists, payers:[{address, paid, unconsumed}], no_payer_unconsumed}: a DFS file's or dataset's payers in order and what each has not consumed; no_payer_unconsumed = money that came with no named payer |
400 |
GET /address/:any |
any text | — | {input, address (hex of the stored form), account_type, type_name, bytes} |
400 not an address this chain can hold |
GET /accounts/:address/pubkey |
a ZBC_… text, hex (0x + 40 hex = an Ethereum account) or another chain's address text (01); anything unreadable is the 400 |
— | {address, account_type, type_name, curve ("ed25519" for types 0, 11, 12, 13, 16; "secp256k1" for 1, 4, 5–9, 14, 15; else null), public_key, source ("address"/"dataset"/"transaction"/null), transaction_hash (only for source "transaction"), verified, note}. The key is found in this order, the first that verifies wins: (1) the address itself for ZooBC (0), Solana (11), Polkadot (12) and Taproot (9), whose 32-byte program is the x-only output key its BIP-340 signatures verify against (note a BIP-340 x-only output key (Taproot, the tweaked key): 32 bytes, no parity byte); (2) the newest active pubkey dataset property the account set on itself (hex text or raw bytes); (3) the newest transaction the account sent: an Ethereum or Tron foreign carrier gives the key recovered from its signed Ethereum transaction, a 65-byte Ethereum or Tron envelope signature the key recovered over the signing digest of 02 §1, a carried-key signature (03) the key it carries. A key verifies against the address by the chain's rule for the type: Ethereum and Tron, the last 20 bytes of Keccak-256 of the 64-byte key (a 65-byte key starting 04 loses that byte first); P2SH (6), HASH160(00 14 ‖ HASH160(key)), the BIP49 script hash; Bitcoin legacy (1), P2PKH, P2WPKH, P2WSH and Ripple, HASH160(key); Tezos, BLAKE2b-160(key); Cardano, BLAKE2b-224(key). Nothing verified: public_key and source null, verified false, note the key this account published does not hash to its address; ignored when a published key failed, else this account has not published a key and has not sent a transaction yet |
400 not an address this chain can hold (fewer than 5 bytes); 503 unavailable |
GET /accounts/:address/transactions |
2 | limit (0…100, default 100), scan_blocks (held to at most 500: an absent or larger value scans 500; a negative one 0), include_pending (default true), from_height, to_height (a ranged scan upward: from_height below 1 → 1, to_height default 4,294,967,295); a numeric parameter that does not parse takes its default |
{address, limit, finalized_height, [from_height, scanned_to], pending:[…], confirmed:[…]}; pending = at most limit matching mempool transactions; normal mode scans the last scan_blocks blocks downward from the tip (a block it cannot read is skipped) and stops at limit rows, inside a block if need be; ranged mode (no pending list) scans whole blocks upward and stops at scan_blocks blocks or limit rows, scanned_to = the last height read (a block the node cannot read is not passed over). Each entry: the transaction object fields plus pending, block_hash (confirmed), finalized (confirmed only: block height ≤ finalized_height), expiry, and amount when the body names a ZBC amount (SendZBC, CreateTrigger, the sum of a SendZBCBatch); a batch is listed to each of its recipients with recipient_account_address = that recipient, amount = its ZBC share, batch_leg:true and, for a token batch, token_transfers:[{token_id (string), amount}]; the entry's escrow object has no id, sender_address, recipient_address, amount, block_height |
400 from_height and to_height must be block heights; scan_blocks is capped at 500; 400 Invalid ZBC address: …; 400 Invalid address encoding |
GET /accounts/:address/movements |
2 | limit (1…1,000, default 100), events (comma list of integers, else 400), system_only=1 (= events 8, 14, 19, 22, 23, 28, 29, 30, 41, 42, 48, 49, 100) |
{address, movements:[{block_height, timestamp, event_type, event (the 07 name), balance_change (signed), direction "in"/"out", reference_id (string), [booked_on (group address hex)]}]}, newest first, the group's rows for transactions the member sent included |
400 |
GET /accounts/:address/history |
2 | limit (1…1,000, default 100), offset, cursor = <height>:<id> (400 when malformed) |
{address, limit, offset, transactions:[{id (string), block_height, timestamp, transaction_type, direction, sender, recipient, amount, fee, transaction_hash}], next_cursor (string or null)} from the per-account index |
400 |
GET /accounts/:address/liquid |
2 | — | {address, now (timestamp of the confirmed block), liquid:[{id (string), sender, recipient, direction, amount, applied_time, complete_minutes, complete_time, vested, remaining, block_height}]} (08) |
400 |
GET /accounts/:address/datasets |
2 | property (prefix filter) |
{address, datasets:[{setter, recipient, role setter/recipient/both, property, value, value_b64, height, creating_tx_hash}]} at the confirmed height |
400 |
GET /objects/:object_id |
64 hex | — | {object_id, zbs_address, owner (the ZBC_text of the last 32 bytes when 36 bytes, whatever the account type; else hex), pending_owner, manage_mode (integer), mode ("private" for 0, "open" for 1, "public" for 2, "private" otherwise), own_deposit_balance, size_bytes, monthly_fee (the storage fee of10forsize_bytes= the sum of every entry's property and value lengths, at the chain's owndataset_storage_cost_per_mibandstorage_oracle_multiplier_ppm(the consensus parameter rows, else 100,000,000 and 1,000,000), the price/accounts/:a/objects and the per-block billing read), entries:[{property, value, value_bytes, owner (the setter, hex), added_by (hex), height}], funders:[{account (hex), paid, unconsumed}] (the deposit payers, empty payers skipped), delete_votes:[hex…] (the standing voters)} (10) |
400 object_id must be 64 hex; 404 object not found; 503 state unavailable |
GET /accounts/:address/objects |
Z (32 or 36 bytes) | — | {address, chain_height, dataset_storage_cost_per_mib, storage_oracle_multiplier_ppm, dataset_billing_period_blocks, objects:[{object_id, zbs_address, owner_address, matched_address, entry_count, size_bytes, own_deposit_balance, monthly_fee, rent_per_period, billing_period_blocks, charges_per_period, next_billing_height, periods_covered, paid_through_height, owner_account_pays_after:true, manage_mode}], stored_files:[public stored-file rows]} (group-aware) |
400 bad address |
GET /accounts/:address/stored-files |
Z (32 or 36 bytes) | signed (§2) to see private files | {address, chain_height, includes_private, files:[stored-file row], private_not_listed}; stored-file row = {file_root, owner_address, total_size, piece_size, piece_count, deposit, status, access_mode, block_height, last_billed_height, rent_per_period, billing_period_blocks, next_billing_height, periods_covered, deposit_remainder, paid_through_height} (11) |
400 bad address; 401; 403 |
GET /accounts/:address/split-policy |
T | — | {account, entries:[{address, share_bp}], total_bp, remainder_bp, scale_bp: 10000} (08) |
400 |
GET /accounts/:address/link-preview |
T | controller |
{member, controller, founding, group_address, rule_active_next_block, can_link, refusal, refusals:[…], moves:{zbc_balance, spendable_balance, prepaid_storage_balance, items}, moving_items, max_moved_items, exceeds_item_limit, stays:{pending_escrows, active_streams, app_seats}, members, max_members, link_seq, current_height, max_valid_until_height = tip + 1 + 5,760, [controller_moves]} (18) |
400 |
GET /accounts/:address/group, GET /groups/:address |
T | — | {address, role none/member/controller/group, max_members} or, in a group, {…, group_address, group_address_zbc, controller, status active/dissolved, link_seq, created_height, max_members, balance, spendable_balance, rent_due_height, weight_bytes, rent_per_period, members:[{address, address_zbc, role, linked_height, permissions}]} (18) |
400 |
GET /accounts/:address/escrows |
T, group scope | group=0 turns the group scope off |
{address, [group_address], escrows:[{id, id_str, transaction_hash, sender_address, recipient_address, approver_address, amount, commission, timeout, status (0 pending, 1 approved, 2 rejected, 3 expired, 4 declined), status_name, decline_reason, role approver/sender/recipient, instruction, instruction_hex, token_id, created_height, longevity_financed, survives_to_height, settled_height, matched_via, matched_address}]} (12) |
400 |
GET /accounts/:address/offers |
2 | status (absent: every status) |
the swap offers this account made: {address, offers:[{id, maker, give_token_id, give_amount, want_token_id, want_amount, counterparty, expiry, status}]} (15) |
400 |
GET /accounts/:address/orders, GET /exchange/orders?account= |
Z, matched 2 | status |
{orders:[{id, market_id, side, price, amount, remaining, status, ts}]} (15) |
400 |
GET /accounts/:address/triggers |
Z, matched 2 | status |
{triggers:[{trigger_id, recipient, amount, fire_height, status, event_id}]} (08) |
400 |
GET /accounts/:address/multisig-pending |
Z, matched 2 | — | {pending:[{tx_hash, multisig_address, min_signatures, inner_tx_type, block_height, signed_by_me, participants:[…], signed:[…]}]}, incomplete ones only (12) |
400 |
GET /accounts/:address/apps |
Z | — | {apps:[app row]} where the account is a player or the named opponent, among the newest 1,000 app rows (§7) |
400 |
GET /accounts/:address/schedules |
Z | limit (1…1,000, default 200), status |
{schedules:[{id, role sender/recipient, kind, funding_mode, owner, recipient (ZBC_ when native), token_id, per_fire_amount, interval_seconds, remaining_fires, locked_remaining, next_fire_time, end_time, cancel_policy, consecutive_skips, status}]} (08) |
400 |
GET /accounts/:address/files |
Z | — | {files:[{path, size, created_at, modified_at, content_hash, creating_tx_hash, zbs_address, original_owner}], dfs_enabled} (10) |
400 |
GET /accounts/:address/files/content?path= |
Z | path required |
{path, size, content_base64} |
400 Missing 'path' query parameter; 404 File not found; 404 DFS not enabled on this node |
GET /accounts/:address/tokens |
2 | — | {address, current_height, tokens:[{token_id (string), symbol, name, decimals, amount_step = 10^(8 − decimals), balance, total_supply, backing_amount, redeemable, mintable, persist_height}]} (14) |
400 |
GET /accounts/:address/survival |
Z | limit (default 100, not clamped) |
{account, chain_height, billing_period_blocks, survival_field_active, count, items:[longevity row + {role owner/funder, your_total, your_unconsumed, your_vote, can_close, close:{transaction_type 309, transaction_body_bytes (target id, 8 bytes LE), is_a_vote:true, leftover_goes_to}}]} (13) |
400 |
GET /accounts/:address/profile; POST /accounts/profiles ({"addresses":[…]}, at most 500); GET /accounts/:address/balance-average?from_height&to_height |
2 | — | {first_tx_timestamp, first_tx_height, tx_count, balance}; {profiles:{address: profile}}; {avg_balance (block-weighted over the range), from_height, to_height} |
400 |
group object: for a member {role controller/member, group_address, group_address_zbc, controller, linked_height, permissions:{controller, can_spend, may_move_tokens, flags, spend_limit, period_blocks, window_start, spent_in_window}, note}; for a group address {role:"group", group_address, group_address_zbc, controller, status}.
Rule activation. As in §3.
Rejections and errors. As in the table; 503 unavailable when the state is not available.
Vector. computed (the TestNet genesis file, 32 §15).
- INPUT:
GET /api/v1/accounts/ZBC_CIHOJSU5_EWGXKZLJ_AHWEQNZX_HYDXMM3J_VV263DLD_7IY4PYFX_5ADSND7R(the treasury) at any confirmed height before its first schedule fire (86,400 s after genesis,08) → EXPECTED OUTPUT:{"address":"ZBC_CIHOJSU5_EWGXKZLJ_AHWEQNZX_HYDXMM3J_VV263DLD_7IY4PYFX_5ADSND7R","spendable_balance":100000000000000,"balance":100000000000000,"locked_balance":0,"total_balance":100000000000000,"pop_revenue":0,"transact_policy":0}(its genesis row: 1,000,000 ZBC, no node, no reward yet, no policy). - INPUT:
GET /api/v1/accounts/<a sender's address>/history?limit=1→ EXPECTED OUTPUT shape:{"address":<as given>,"limit":1,"offset":0,"transactions":[{"id":<decimal string>,"block_height":…,"timestamp":…,"transaction_type":…,"direction":"out","sender":<hex>,"recipient":<hex or "">,"amount":…,"fee":…,"transaction_hash":<64 hex>}],"next_cursor":"<height>:<id>"}; with no transaction yet{"address":…,"limit":1,"offset":0,"transactions":[],"next_cursor":null}. - INPUT:
GET /api/v1/accounts/09000000dff1d77f2a671c5f36183726db2341be58feae1da2deced843240f7b502ba659/pubkey(the Taproot account of the first BIP-340 key of33§3) → EXPECTED OUTPUT:{"address":"09000000dff1d77f2a671c5f36183726db2341be58feae1da2deced843240f7b502ba659","account_type":9,"type_name":"Bitcoin Taproot","curve":"secp256k1","public_key":"dff1d77f2a671c5f36183726db2341be58feae1da2deced843240f7b502ba659","source":"address","transaction_hash":null,"verified":true,"note":"a BIP-340 x-only output key (Taproot, the tweaked key): 32 bytes, no parity byte"}. INPUT:GET /api/v1/accounts/040000003bc64c92d9bb1c5826643b081108b892e2e7f590/pubkey(the Ethereum account of33§3) before it published a key or sent anything →{"address":"040000003bc64c92d9bb1c5826643b081108b892e2e7f590","account_type":4,"type_name":"Ethereum","curve":"secp256k1","public_key":null,"source":null,"transaction_hash":null,"verified":false,"note":"this account has not published a key and has not sent a transaction yet"}; after it sent a transaction signed with v 27 or 28 →"public_key":"2c67e6ec6aa795e8ae01447ac9f3a57616dc2cf17ddbe367d8dfc564e923c1e268487e15e10d153c32c41a2820a383628098d155fc6eefb44ba37e93e99f05f1","source":"transaction"with that transaction's hash and"verified":true(the 64-byte key whose Keccak-256 ends in the address). INVALID INPUT:GET /api/v1/accounts/0400/pubkey→ 400not an address this chain can hold. - INVALID INPUT (a node, not the archival):
GET /api/v1/accounts/bccb80820d3e3fce6e62f1c283acf6b0ab884a937af47120de2ffe88a393b4d6(a bare 32-byte key) → 404{"success":false,"error":"accounts are typed: a bare 32-byte key is not an account on this chain","code":404}. (The public domain answers this path from the archival service, §9.) - INVALID INPUT:
GET /api/v1/accounts/<any>/history?cursor=abc→ 400;GET /api/v1/accounts/<any>/transactions?from_height=x→ 400from_height and to_height must be block heights; scan_blocks is capped at 500.
Test cases · §6
10 cases · 6 valid · 4 invalid · 6 reference
The TestNet treasury before its first schedule fire
Its genesis row: 1,000,000 ZBC, no node, no reward yet, no policy; at any confirmed height before the first fire, 86,400 s after genesis (08).
A stated value: there is nothing to compute. A compatible node shows the same value.
- request
GET /api/v1/accounts/ZBC_CIHOJSU5_EWGXKZLJ_AHWEQNZX_HYDXMM3J_VV263DLD_7IY4PYFX_5ADSND7R- status
200- body
{"address":"ZBC_CIHOJSU5_EWGXKZLJ_AHWEQNZX_HYDXMM3J_VV263DLD_7IY4PYFX_5ADSND7R","spendable_balance":100000000000000,"balance":100000000000000,"locked_balance":0,"total_balance":100000000000000,"pop_revenue":0,"transact_policy":0}
The shape of an account's newest history row
A stated value: there is nothing to compute. A compatible node shows the same value.
- request
GET /api/v1/accounts/<a sender's address>/history?limit=1- status
200- body
{"address":<as given>,"limit":1,"offset":0,"transactions":[{"id":<decimal string>,"block_height":…,"timestamp":…,"transaction_type":…,"direction":"out","sender":<hex>,"recipient":<hex or "">,"amount":…,"fee":…,"transaction_hash":<64 hex>}],"next_cursor":"<height>:<id>"}
The history of an account with no transaction yet
A stated value: there is nothing to compute. A compatible node shows the same value.
- request
GET /api/v1/accounts/<an account>/history?limit=1- status
200- body
{"address":…,"limit":1,"offset":0,"transactions":[],"next_cursor":null}
The key of a Taproot account is its address's 32-byte program
Loading the test widget…
An Ethereum account that has not published a key nor sent anything
Loading the test widget…
The same account after it sent a transaction signed with v 27 or 28
Loading the test widget…
A 2-byte address on the pubkey route
Loading the test widget…
A node refuses a bare 32-byte key as an account
A node's answer; the public domain answers this path from the archival service (§9).
A stated value: there is nothing to compute. The statement is a refusal: what a compatible node does with this input.
- request
GET /api/v1/accounts/bccb80820d3e3fce6e62f1c283acf6b0ab884a937af47120de2ffe88a393b4d6- status
404- body
{"success":false,"error":"accounts are typed: a bare 32-byte key is not an account on this chain","code":404}
A malformed history cursor
A stated value: there is nothing to compute. The statement is a refusal: what a compatible node does with this input.
- request
GET /api/v1/accounts/<any>/history?cursor=abc- status
400
A from_height that is not a block height
A stated value: there is nothing to compute. The statement is a refusal: what a compatible node does with this input.
- request
GET /api/v1/accounts/<any>/transactions?from_height=x- status
400- body
{"success":false,"error":"from_height and to_height must be block heights; scan_blocks is capped at 500","code":400}
Defects to match. /accounts/:address/transactions is a block scan loading whole blocks (cost proportional to scan_blocks, at most 500); /history is the index to use. /accounts/:address/apps and the apps section of /wallet/snapshot look only at the newest 1,000 app rows of the chain, so an older app the account sits in is not listed.
§7 Markets, apps, tokens, bridge, releases, registries, governance, longevity, storage
Purpose. An implementation must serve the remaining state reads and the one state-writing upload.
Inputs. As per route.
Output and effect. Reads; the upload stores pieces (11).
How to compute it.
| route | parameters | response | errors |
|---|---|---|---|
GET /exchange/offers |
give, want (token ids) |
{offers:[offer row]}, open offers only |
400 |
GET /exchange/markets |
— | {markets:[{id (string), base_token_id, quote_token_id, deposit}]} |
— |
GET /exchange/orderbook?market=, GET /exchange/markets/:id/orderbook, GET /exchange/orderbook/:id |
depth (1…500, default 50) |
{market, bids:[[price, amount]…] (descending), asks:[…] (ascending)}, aggregated per price over open orders |
400 market required; 400 invalid market id |
GET /exchange/trades?market=, GET /exchange/trades/:id |
limit (1…500, default 100) |
{trades:[{price, amount, ts}]}; the query form oldest first, the path form newest first |
400 market required; 400 invalid market id |
GET /tokens/volume |
— | {now, tokens:[{token_id, volume_24h, volume_7d, trades_24h, trades_7d}]} over the last 7 days of trades (quote volume = amount × price div 10⁸) |
— |
GET /apps |
status, limit (1…500, default 200; both integers, else 400), category solo/pvp/party |
{apps:[app row]}; an app row is, in this order: id (string), app_type, status, seats, creator (hex), players (array, each player's typed account as stored, lower-case hex), opponent (hex, "" when none), stake_token_id, stake_amount, pot, state (hex), turn, created_height, last_move_height, deadline_height, resolve_height, winner (hex, "" when none), channel, owed_payout; the stored paid_payout is not shown (16 §1) |
400 |
GET /apps/open |
limit (≤ 500, default 100) |
{apps:[{id (string), app_type, seats, maker (ZBC_), stake_token, stake_amount}]}: open two-player apps with no named opponent |
— |
GET /apps/pool |
— | {zbc, tokens:[{token_id, balance, decimals, symbol}], channels:true} |
— |
GET /apps/stats |
— | {apps_total, apps_open, apps_active, apps_finished, players_active, pot_at_stake} |
— |
GET /apps/:id |
int64, string or number spelling | app row + settlement:{claimant, final_seq, outcome, winner_seat, turn, challenge_deadline_height, resolved} when a settlement row exists |
400 invalid app id; 404 {"error":"app not found"}; 500 app lookup failed |
GET /tokens, GET /tokens/:id |
— | {current_height, tokens:[{token_id (string), issuer, symbol, name, decimals, amount_step, total_supply, backing_amount, redeemable, mintable, unbacked, persist_height}]}; one token: the row plus backing_asset and current_height |
404 token not found |
GET /tokens/:id/icon |
— | the issuer's tokenicon:<SYMBOL> dataset value as an image (PNG, JPEG, GIF or WebP, 16…4,096 bytes, at most 512 × 512) with X-Content-Type-Options: nosniff, Content-Disposition: inline, Content-Security-Policy: default-src 'none'; sandbox, Cache-Control: public, max-age=300 |
404 with an empty text/plain body |
GET /bridge/coins |
— | {bridge_withdrawal_credit (the rule's state for tip + 1), coins:[{token_id (string), symbol, chain, asset, deposit_address, [custody_account (hex, 00000000 ‖ SHA3-256("ZBC-BRIDGE-CUSTODY" ‖ LE64(token_id))), zbc_withdraw_address (its ZBC_ form), withdrawals_open (bool), withdrawals_closed_reason ("" when open)], decimals}]}, the bracketed keys only while the rule is active for tip + 1 (34 §1a, §8) |
503 unavailable |
GET /bridge/deposits?recipient=, GET /bridge/withdrawals?account= |
— | the keeper's files ($ZOOBC_BRIDGE_DEPOSITS / $ZOOBC_BRIDGE_WITHDRAWALS, else ~/.zoobc/bridge-deposits.json / bridge-withdrawals.json) filtered by address substring and served as the keeper wrote them, not validated: {deposits:[…]}, {withdrawals:[…]}; empty when absent |
— |
GET /bridge/deposits/:event_id |
letters, digits, :, ., _, -; must begin ZBRDEP1: |
keys alphabetical: {bridge_withdrawal_credit (the rule's state for tip + 1), event_id, pending, reason (the refusal a pending event is stuck on, else ""), resolved, value (the result value; while pending the value that the attesters of every node with status registered, suspended ones included (attester account 00000000 ‖ node key), agree on at the compiled two-thirds quorum max(1, ⌈size × 2/3⌉), never the genesis bridge_quorum_num/bridge_quorum_den rows; else "")} (34 §8); another character in the path is a route miss (empty 404) |
503 bridge state unavailable (checked first); 404 not a bridge deposit event; 500 with the read error |
GET /bridge/withdrawal-requests?custody=&from_height=&to_height=&scan_blocks= |
custody (hex account) required |
keys alphabetical: {bridge_withdrawal_credit (the rule's state for tip + 1), finalized_height, [from_height (floored at 1), scanned_to], requests:[{amount, block_height, destination, finalized (block_height ≤ finalized_height), message ("ZBW1|" ‖ destination), recipient_account_address (the custody, hex), token_id (number), transaction_hash (the trigger)}]}; scan_blocks is held to at most 500 (its default 2,000 included, so 500 when absent); to_height defaults to and is held to finalized_height; scanned_to = from_height − 1 when scan_blocks is 0 or from_height exceeds that to_height, else min(to_height, from_height + scan_blocks − 1); without from_height the answer has neither key and requests is empty; the rows are the live request rows whose stored custody address ends with the bytes of custody (the 36-byte account and its bare 32-byte key both select it), with from_height ≤ block_height ≤ scanned_to, by height then trigger hash, read only while the rule is active for tip + 1 (34 §5, §8) |
503 bridge state unavailable (checked first); 400 custody (hex account address) is required; 400 invalid height range (a height or scan_blocks that does not parse); 500 with the read error |
GET /bridge/withdrawals/:hash |
hex digits, any length (other characters: route miss) | in order: {event_id ("ZBWDR1:" ‖ the hex as given), trigger_transaction_hash (as given), request_recorded (true when rule bridge_withdrawal_creditis active for tip + 1), oracle_result_height (0 while pending), withdrawal_id ("0x" ‖ Keccak-256(trigger hash bytes ‖ oracle_result_height as uint32 LE) once resolved under the rule, else ""), resolved, token_id (number), amount, release_amount_wei (under the rule and once resolved, amount × 10¹⁰ as "0x" ‖ 64 hex digits, big-endian, the wei the keepers sign for; else ""), destination (from the result when resolved, else from the first counted attestation, else 0/0/""), registry_size (n = the nodes with status registered, suspended ones included, each counted by its attester account00000000 ‖ node key), quorum = max(1, ⌈2n/3⌉), quorum_num 2, quorum_den 3 (the compiled two thirds, never the genesis bridge_quorum_num/bridge_quorum_den rows), signature_count, signatures:[{attester (hex), signature}]}; under the rule signatures is empty while pending and, once resolved, holds the attestations of those n nodes that agree with the result and whose signature part reads R<oracle_result_height>|<signature>, shown without that prefix; an attestation pruned below the receipt horizon (13) is no longer listed (34 §8) |
503 bridge state unavailable (checked first); 404 no executed custody credit for this trigger (under the rule, no live request row for the trigger); 500 with the read error |
GET /release/authority, /release/latest, /release/list |
— | {found, authority_address, pending_address}; {found, version, manifest_hash, release_address}; {releases:[{version, manifest_hash, release_address, revoked, block_height}]} (17; the updater of 30 reads the list) |
— |
GET /registry/gateways, /registry/relays, /registry/archivals |
— | {gateways:[{domain, url, gateway_key, owner_address, verified_count, last_heartbeat_height, status}]}; {relays:[{domain, url, relay_key, gateway_key, owner_address, block_height, status}]} (only relays whose gateway is active and has the same owner); {archivals:[{domain, url, node_public_key, owner_address, block_height, status}]} (17) |
— |
GET /governance/params |
— | {transaction_type 51, rule:"average", up_limit_pct:20, down_limit:"half", cycle_length, cycle_first_block, count_height (= first + cycle − 1), counted_seats, registry_floor, floor_met, parameters:[{name, source "consensus_parameters"/"compiled_default", current, min, max, votable_min, votable_max, votes_this_cycle, projected}], transfer_fee:{name "fee_scale", commit_transaction_type 7, reveal_transaction_type 263, current, min, max, votable_min, votable_max, votes_this_cycle (reveals), projected}} for the 8 governable prices (17); votable_min/votable_max = one vote's reach from current (half down, +20 % up, within the bounds); counted_seats = the number of counted registered nodes; projected = the average over the counted registered nodes with silent ones at today's value, each vote limited, or current when the floor is not met or nothing was cast |
— |
GET /governance/proposals |
— | {rule:"average", cycle_first_block, count_height, counted_seats, floor_met, parameters:[{parameter, current, source, votes:[{node_id (number), node_id_str, node_public_key, value, counts_as}], votes_counted, projected}]}; counted_seats = the number of counted registered nodes (17 §1) |
— |
GET /longevity?sponsor=&limit=, GET /longevity/:target_id |
hex sponsor; limit default 100, not clamped; int64 |
{chain_height, billing_period_blocks, count, longevity:[row]}; one row; row = {target_tx_id (string), target_tx_hash, sponsor_address, deposit, payload_bytes, cost_per_mib_locked, rent_per_period, periods_remaining, funded_at_height, last_change_height, paid_through_height, free_until_height, billing_period_blocks, expires_at_height, blocks_remaining, still_in_free_window, owner_address, funded_total, funders:[{address, total, last_height}], payers:[{address, paid, unconsumed, voted}], close_votes_missing} (13) |
404 |
GET /longevity/quote?target=&amount=&periods= |
target = decimal id or 64 hex | {target_tx_id, target_tx_hash, target_on_this_node, target_height, state_target_height, state_target_bytes, first_funding_last_height, payload_bytes, price_now, billing_period_blocks, min_deposit 10,000,000, chain_height, existing:{…}, after:{amount, below_minimum, deposit, cost_per_mib_locked, rent_per_period, periods_remaining, expires_at_height, blocks_remaining}, [periods_requested, amount_for_periods]} |
404 when the target is neither on this node nor funded |
GET /storage/files |
— | {files:[{file_root, owner_address, total_size, piece_size, piece_count, deposit, block_height}]}, public files only |
— |
GET /storage/files/:root |
— | {file_root, owner_address, total_size, piece_size, deposit, status, access_mode, last_billed_height, rent_per_period, billing_period_blocks, next_billing_height, periods_covered, deposit_remainder, paid_through_height, piece_ids:[…]} (no piece_count, no block_height); served for private files too: ⚠ the reference shows a private file's owner, size and piece ids to anyone, unsigned; only /content checks the access list |
404 |
GET /storage/files/:root/content |
signed when private (§2) | the reassembled bytes (application/octet-stream, trimmed to total_size) |
404 file not found; 404 {… "anchored":true,"expired":true …} when its rent ran out; 404 {… "anchored":true,"error":"content unavailable - …"} when no holder served a piece; §2's 401/403 |
GET /storage/quote?bytes=&blocks= |
— | {bytes, cost_per_mib, storage_oracle_multiplier_ppm, billing_period_blocks, block_time_seconds (row, else 15), rent_per_period (the fee for ⌈bytes / MiB⌉ MiB), requested_blocks, periods_covered = ⌈blocks / period⌉, deposit = max(rent × periods, 1,000,000), min_deposit 1,000,000} |
400 |
POST /storage/upload |
raw body = the file (at most 1,048,576 bytes, §1) | gates in order: storage enabled (503); non-empty (400); free disk ≥ 2 GiB (507 storage refused: this node is low on disk); not-yet-anchored pieces on this node + body ≤ 256 MiB (507 … budget for not-yet-anchored uploads is full …); per client at most 10 uploads per 600 s and 32 MiB per 3,600 s (429 with Retry-After); then the file is split into 1 MiB pieces (11), each stored and pushed to its replica set (27); reply {file_root, piece_size, total_size, piece_count, seeded_replicas, piece_ids:[…]} |
as listed |
App row: {id (string), app_type, status, seats, creator (hex), players:[hex… (one per player, each a typed account of its own length, 16)], opponent (hex of the stored bytes), stake_token_id (number), stake_amount, pot, state (hex), turn, …} (16).
Longevity quote maths (mirrors 13): rent = ⌈bytes × price / 1,048,576⌉ (at least 1); a top-up's locked price = (deposit × locked + amount × price_now) div (deposit + amount) in 128-bit integers (at least 1); periods = ⌈deposit / rent⌉; expiry = max(free_until, paid_through) + periods × period, capped at 2³² − 1; the amount for n periods starts at n × rent_now (at least the 10,000,000 minimum) and adds rent_now until the projection reaches n periods, at most 256 steps.
Rule activation. None in the API itself.
Rejections and errors. As in the table; a numeric parameter that does not parse gives §1's 400.
Vector. computed (the TestNet genesis file, 32 §12–§13).
- INPUT:
GET /api/v1/governance/paramson a fresh TestNet chain in its first cycle (11 counted registered nodes, no vote) → EXPECTED OUTPUT begins{"transaction_type":51,"rule":"average","up_limit_pct":20,"down_limit":"half","cycle_length":172800,"cycle_first_block":1,"count_height":172800,"counted_seats":11,"registry_floor":7,"floor_met":true,"parameters":[{"name":"storage_oracle_multiplier_ppm","source":"consensus_parameters","current":1000000,"min":100000,"max":10000000,"votable_min":500000,"votable_max":1200000,"votes_this_cycle":0,"projected":1000000},{"name":"dataset_storage_cost_per_mib","source":"consensus_parameters","current":5000000,"min":1,"max":10000000000,"votable_min":2500000,"votable_max":6000000,"votes_this_cycle":0,"projected":5000000},…(eight prices, thentransfer_feewith"commit_transaction_type":7,"reveal_transaction_type":263). - INPUT:
GET /api/v1/release/liston a fresh chain → EXPECTED OUTPUT:{"releases":[]}; after the release authority registersv0.6.1-testnet-arm64at height 348 with manifest hashM→{"releases":[{"version":"v0.6.1-testnet-arm64","manifest_hash":"<M, 64 hex>","release_address":"<the authority's 36-byte account, hex>","revoked":false,"block_height":348}]}. - INPUT (quote maths): 60,025 bytes at 1 ZBC/MiB → rent = ⌈60,025 × 100,000,000 / 1,048,576⌉ = 5,724,431 per period; a 10,000,000 deposit buys ⌈10,000,000 / 5,724,431⌉ = 2 periods.
- INPUT:
GET /api/v1/bridge/withdrawal-requests?custody=00on a chain without a request row →{"bridge_withdrawal_credit":true,"finalized_height":<the floor>,"requests":[]}; with&from_height=10&to_height=5→{"bridge_withdrawal_credit":true,"finalized_height":<the floor>,"from_height":10,"requests":[],"scanned_to":9}. - INPUT (the withdrawal id): a trigger
d75df025be21ac74af3327c20186b415927367402a5b5028447e95c224f74d21resolved at height 1,200 → Keccak-256 over the 36 bytesd75df025…4d21 ‖ b0040000→"oracle_result_height":1200,"withdrawal_id":"0x3b4a638b4f6e7f3f3bc034171f0c22d4473966d1227b86260a049f6a15419a8e"; for its 100,000,000 units of ZETH"release_amount_wei":"0x0000000000000000000000000000000000000000000000000de0b6b3a7640000"(10¹⁸ wei). - INPUT:
GET /api/v1/bridge/coinson either shipped chain → the ZETH entry{"token_id":"5","symbol":"ZETH","chain":"ethereum","asset":"native","deposit_address":"0x9A080FFFE4105361b023220bD21Be0B9418E908e","custody_account":"00000000b070ddf68c3270c38319c7c4c76166a2c76d8e9a75c368c6769d0fe5cf4f4df2","zbc_withdraw_address":"ZBC_WBYN35UM_GJYMHAYZ_Y7CMOYLG_ULDW3DU2_OXBWRRTW_TUH6LT2P_JXZAEBCI","withdrawals_open":true,"withdrawals_closed_reason":"","decimals":8}; ZBTC, ZUSDC and ZUSDT answer"withdrawals_open":falsewith their reasons (34§1a). - INVALID INPUT:
GET /api/v1/exchange/orderbook(nomarket) → 400market required;GET /api/v1/bridge/deposits/ZBWDR1:00ff→ 404not a bridge deposit event;GET /api/v1/bridge/withdrawals/00ffwith no request row → 404{"success":false,"error":"no executed custody credit for this trigger","code":404};GET /api/v1/bridge/withdrawal-requests→ 400custody (hex account address) is required;…?custody=00&from_height=x→ 400invalid height range.
Test cases · §7
14 cases · 9 valid · 5 invalid · 10 reference
The governable prices of a fresh TestNet chain in its first cycle
11 counted registered nodes, no vote. The beginning of the answer; eight prices, then transfer_fee with commit_transaction_type 7 and reveal_transaction_type 263.
A stated value: there is nothing to compute. A compatible node shows the same value.
- request
GET /api/v1/governance/params- status
200- body
{"transaction_type":51,"rule":"average","up_limit_pct":20,"down_limit":"half","cycle_length":172800,"cycle_first_block":1,"count_height":172800,"counted_seats":11,"registry_floor":7,"floor_met":true,"parameters":[{"name":"storage_oracle_multiplier_ppm","source":"consensus_parameters","current":1000000,"min":100000,"max":10000000,"votable_min":500000,"votable_max":1200000,"votes_this_cycle":0,"projected":1000000},{"name":"dataset_storage_cost_per_mib","source":"consensus_parameters","current":5000000,"min":1,"max":10000000000,"votable_min":2500000,"votable_max":6000000,"votes_this_cycle":0,"projected":5000000},…
The release registry of a fresh chain
A stated value: there is nothing to compute. A compatible node shows the same value.
- request
GET /api/v1/release/list- status
200- body
{"releases":[]}
The release registry after one registration
The release authority registers v0.6.1-testnet-arm64 at height 348 with manifest hash M.
A stated value: there is nothing to compute. A compatible node shows the same value.
- request
GET /api/v1/release/list- status
200- body
{"releases":[{"version":"v0.6.1-testnet-arm64","manifest_hash":"<M, 64 hex>","release_address":"<the authority's 36-byte account, hex>","revoked":false,"block_height":348}]}
60,025 bytes at 1 ZBC per MiB, a 0.1 ZBC deposit
Loading the test widget…
The withdrawal requests of a custody on a chain without a request row
A stated value: there is nothing to compute. A compatible node shows the same value.
- request
GET /api/v1/bridge/withdrawal-requests?custody=00- status
200- body
{"bridge_withdrawal_credit":true,"finalized_height":<the floor>,"requests":[]}
An empty height range: scanned_to is from_height − 1
A stated value: there is nothing to compute. A compatible node shows the same value.
- request
GET /api/v1/bridge/withdrawal-requests?custody=00&from_height=10&to_height=5- status
200- body
{"bridge_withdrawal_credit":true,"finalized_height":<the floor>,"from_height":10,"requests":[],"scanned_to":9}
The withdrawal id of a trigger resolved at height 1,200
Loading the test widget…
The same withdrawal's release_amount_wei for its 100,000,000 units of ZETH
Loading the test widget…
The ZETH entry of /bridge/coins on either shipped chain
Loading the test widget…
The order book without a market
A stated value: there is nothing to compute. The statement is a refusal: what a compatible node does with this input.
- request
GET /api/v1/exchange/orderbook- status
400- body
{"success":false,"error":"market required","code":400}
A deposit view of an id that is not a deposit event
A stated value: there is nothing to compute. The statement is a refusal: what a compatible node does with this input.
- request
GET /api/v1/bridge/deposits/ZBWDR1:00ff- status
404- body
{"success":false,"error":"not a bridge deposit event","code":404}
A withdrawal view of a trigger with no request row
A stated value: there is nothing to compute. The statement is a refusal: what a compatible node does with this input.
- request
GET /api/v1/bridge/withdrawals/00ff- status
404- body
{"success":false,"error":"no executed custody credit for this trigger","code":404}
The withdrawal requests without a custody
A stated value: there is nothing to compute. The statement is a refusal: what a compatible node does with this input.
- request
GET /api/v1/bridge/withdrawal-requests- status
400- body
{"success":false,"error":"custody (hex account address) is required","code":400}
A from_height that does not parse
A stated value: there is nothing to compute. The statement is a refusal: what a compatible node does with this input.
- request
GET /api/v1/bridge/withdrawal-requests?custody=00&from_height=x- status
400- body
{"success":false,"error":"invalid height range","code":400}
Defects to match. None.
§8 Node, admin, internal and announce routes
Purpose. An implementation must say what the node is and serve the local service registry.
Inputs. As per route.
Output and effect. Reads; the local registry and blacklist in memory.
How to compute it.
| route | auth | response | errors |
|---|---|---|---|
GET /node/info |
— | in order: {node_id (this node's public key hex, or "standalone"), version ("<VERSION>+<git commit>"), height, blockchain_height (same), peer_count (connected peers), synced:true, syncing:false, p2pAddress (advertised), archival_node, public_api_url, genesis_hash, signing_version:2, signing_tag:"ZBC-TX", wedge_reason, spine_genesis_hash, spine_height, pending_claim (null or {claimer, announced_height, due_height}), newer_release (null or the newest release registered on this chain that is newer than this binary, with its readiness: version, blocksmiths already running it, blocksmiths needed, the earliest block its rules could switch on, 30)} |
500 Internal error: … |
GET /node/peers |
— | [{address, node_public_key, chain_height, last_seen, connected}] for every non-blacklisted peer in the table (28) |
— |
GET /node/blacklist |
— | [{node_public_key, reason, offense_count, banned_until, time_remaining_seconds}] |
— |
GET /node/public-ip |
signed, any key | {ip (the client's public IP from the proxy headers, else the peer IP), port, remote_addr, remote_port, [forwarded, x_forwarded_for, x_real_ip]} |
§2 |
GET /node/system-stats |
§2 | operator view {scope:"operator", sampled, cpu_usage_percent, memory_usage_percent, thread_count, disk_total_bytes, disk_free_bytes}; otherwise {scope:"public", height, confirmed_height, finalized_height, version, note} |
§2 |
GET /nodes?status= |
— | {nodes:[row…], roll_call:{window_end, open, answered, absent, removed, pending, seats:[{node_id, node_id_str, node_public_key, registration_status, state, …}] (one entry per genesis registered node)}} for active (default; any unknown value), queued or all. Row: {node_id (number), node_id_str, node_public_key, account_address (36-byte hex), registration_height, locked_balance (both 0 for a genesis registered node), registration_status, participation_score (the effective score the chain counts now, 36), stored_participation_score, earns (registered, not missing, mature, not left out by the roll call at the next block), mature, height, [roll_call], [liveness], [expelled_height], [pending_claim], [pending_key_change], [leaving], [queue_position, expected_attendance_windows, attendance_fee_per_window, effective_minimum_stake] (queued rows), node_address (last)} — liveness (only when a row exists) = {misses, produced, last_seen_height, last_block_height, missing, suspended, suspended_since}; expelled_height when the node has an expulsion row; pending_claim = {claimer, announced_height, due_height, tx_id, tx_id_str}; pending_key_change = {new_node_public_key, announced_height, due_height, tx_id, tx_id_str}; leaving = {announced_height, leave_height, tx_id, tx_id_str, missed_during_hold, expected_return}; a genesis registered node's roll_call = {state:"answered"|"removed", height}, or {state:"pending", transaction_id (decimal string)} (no mined answer, the window open, a RollCall from the node's key waiting in this node's pool; the lowest such id), or {state:"absent"[, kept:true]} (kept once the window has closed); roll_call.open = tip < window_end (= roll_call_blocks) |
503 (no registry) |
GET /peers/archival |
— | [{node_public_key, api_url, address, chain_height, node_id (−1 when not registered), node_id_str}] |
— |
POST /admin/clear-blacklist |
signed, operator | {"status":"success","message":"Blacklist cleared successfully"} |
§2 |
POST /internal/attest (not under /api/v1/) |
unrelayed loopback only | body {data_hash (64 hex), data_type (block/transaction/account/receipt), block_height (integer)} → {signature (base64 of the 64-byte Ed25519 signature by the node key over data_hash ‖ data_type ‖ 0x00 ‖ block_height (8 bytes LE) ‖ timestamp (8 bytes LE)), node_public_key (hex), node_id, node_id_str, timestamp} |
403 Forbidden: /internal/attest is loopback-only; 400 Missing or invalid 'data_hash' (likewise 'data_type', 'block_height'), data_hash must be 64 hex characters (32 bytes), Invalid hex in data_hash, data_type must be one of: …, JSON parse error: … |
POST /gateway/announce, DELETE /gateway/announce, GET /gateways; POST /archival/announce, GET /archivals; POST /relay/announce, GET /relays |
— | the in-memory service registry (entries expire after 3,600 s, 30). Announce bodies carry base_domain/api_url/url, public_hostname, owner_address (ZBC_), announced_at, gateway_public_key/archival_public_key/relay_public_key (64 hex; another length is stored empty), node_public_key (64 hex), owner_signature (hex), capabilities:[…]; the node key must be registered; ⚠ the reference's owner check compares owner_address with a ZBC_ text made from the stored 36-byte owner, which comes out empty, so the 403 Owner address does not match node registry never fires (nor does the registry's own owner check), and anyone can announce a service for any registered node, or overwrite an existing announcement, under an owner key of their own; a registry refusal is answered with its own error text. Success: {"success":true,"message":"Gateway registered successfully"} (Archival node …, Relay node …). Lists: arrays of the stored records with announced_at and last_verified |
400 Invalid request: … (bad JSON or types); 404 Node not found in registry; 400 (POST) / 404 (DELETE) with the registry's refusal; DELETE: 400 Invalid gateway_public_key |
GET /escrow_requests?address=&group=, GET /escrow_requests/by_requester?address= |
T, group scope | {address, [group_address], escrow_requests:[{id (number), id_str, requester_address, proposed_sender, proposed_amount, approver_address, commission, timeout, instruction, instruction_hex, expiry, status, status_name, escrow_transaction_id (number), escrow_transaction_id_str, decline_reason, block_height, token_id:"0", created_height, settled_height, [escrow_status, escrow_status_name, escrow_settled_height], matched_via, matched_address}]} (12), newest 100 |
400 |
Rule activation. None.
Rejections and errors. As listed.
Vector. computed (the genesis files: 11 genesis registered nodes on either chain, 36 §7–§8). INPUT: GET /api/v1/nodes at tip 0 → EXPECTED OUTPUT: 11 rows, each {"node_id":<number>,"node_id_str":<the same, decimal>,"node_public_key":<the file's node key, 64 hex>,"account_address":<the file's owner account, 72 hex>,"registration_height":0,"locked_balance":0,"registration_status":0,"participation_score":2000000000000,"stored_participation_score":2000000000000,"earns":true,"mature":true,"height":0,"roll_call":{"state":"absent"} (or {"state":"pending","transaction_id":<decimal string>} once its RollCall waits in this node's pool),…,"node_address":…} and "roll_call":{"window_end":20,"open":true,"answered":0,"absent":<11 − pending>,"removed":0,"pending":<the RollCalls in this node's pool>,"seats":[11 entries]}; from block 20 on, with every node answered in block 1, each row's "roll_call":{"state":"answered","height":1} and the summary {"window_end":20,"open":false,"answered":11,"absent":0,"removed":0,"pending":0,…}. INVALID INPUT: POST /internal/attest from a non-loopback caller → 403 Forbidden: /internal/attest is loopback-only; POST /api/v1/internal/attest → 404 with an empty body (no such route).
Test cases · §8
4 cases · 2 valid · 2 invalid · 4 reference
A registry row at tip 0
11 rows; a row whose RollCall waits in this node's pool reads "roll_call":{"state":"pending","transaction_id":<decimal string>}; the summary "roll_call":{"window_end":20,"open":true,"answered":0,"absent":<11 − pending>,"removed":0,"pending":<the RollCalls in this node's pool>,"seats":[11 entries]}.
A stated value: there is nothing to compute. A compatible node shows the same value.
- request
GET /api/v1/nodes- status
200- body
{"node_id":<number>,"node_id_str":<the same, decimal>,"node_public_key":<the file's node key, 64 hex>,"account_address":<the file's owner account, 72 hex>,"registration_height":0,"locked_balance":0,"registration_status":0,"participation_score":2000000000000,"stored_participation_score":2000000000000,"earns":true,"mature":true,"height":0,"roll_call":{"state":"absent"},…,"node_address":…}
The roll call from block 20 on, every node answered in block 1
Each row's "roll_call":{"state":"answered","height":1}.
A stated value: there is nothing to compute. A compatible node shows the same value.
- request
GET /api/v1/nodes- status
200- body
"roll_call":{"window_end":20,"open":false,"answered":11,"absent":0,"removed":0,"pending":0,…}
/internal/attest from a caller that is not loopback
A stated value: there is nothing to compute. The statement is a refusal: what a compatible node does with this input.
- request
POST /internal/attest- status
403- body
{"success":false,"error":"Forbidden: /internal/attest is loopback-only","code":403}
There is no /api/v1/internal/attest route
A route miss: an empty body.
A stated value: there is nothing to compute. The statement is a refusal: what a compatible node does with this input.
- request
POST /api/v1/internal/attest- status
404- body
Defects to match. The /internal/attest response timestamp is read separately from the signed one and may differ from it by a second.
§9 The gateway form
Purpose. What a client of the public domains actually talks to, so an implementation can serve the same clients.
Inputs. Requests to https://<domain>/api/v1/….
Output and effect. A gateway (installer role gateway, not the node) terminates TLS and proxies /api/v1/* first to the archival service (a separate program fed from the node into a database, 30) and, when that answers an empty-body 404, to the node.
How to compute it. The archival serves: /node/info, /health, /blocks, /blocks/latest, /blocks/:height, /blocks/:height/transactions, /blocks/:height/movements, /transactions, /transactions/:hash, /transactions/id/:id, /search/transactions, /spine/blocks, /spine/blocks/latest, /spine/blocks/:height, /receipts/block/:height, /receipts/sender/:key, /receipts/recipient/:key, /blocksmiths/:key/blocks, /skipped-blocksmiths/block/:height, /schedules/:id, /movements/latest, /network/map, /registry/nodes, /registry/nodes/:id, /registry/scores, /registry/gateways, /registry/relays, /registry/archival, /stats/{overview,chain,daily,blocksmiths,tx-types,top-accounts,account-growth}, /archive/stats, /monitoring/stats, /accounts/:address, /accounts/:address/transactions, /accounts/:address/movements, /accounts/:address/stats, and, outside /api/v1/, /archival/v1/chunks/<start>_<end> (and its /metadata). Where both programs serve a path the shapes differ:
- its block:
{block_hash, hash, block_seed, block_seed_proof, blocksmith_public_key, height, payload_length, previous_block_hash, previous_hash, release, timestamp, total_coinbase, total_fee, transaction_count, tx_count, version}in uppercase hex, without signature or difficulty; - its
/node/info:{archival_node:true, archival_version, blockchain_height, blocks_behind, confirmed_depth, genesis_hash (uppercase), height, newer_release, node_id:"archival-api", node_version, p2pAddress:"", peer_count:0, public_api_url:"", signing_tag, signing_version, source_height, synced, syncing, version}: the mirror indexes only blocksconfirmed_depthbelow the node's tip, sosynced=source_height − height ≤ confirmed_depth; - its
/accounts/:address:{account, account_address (uppercase hex), address (theZBC_text, or the foreign form the caller wrote), balance, locked_balance, spendable_balance, [pop_revenue, total_balance, transact_policy]}for any written form, a bare 32-byte key included; - its
/accounts/:address/transactions: a bare array of{amount, block_height, expiry, fee, recipient_account_address, sender, sender_account_address, survival, timestamp, transaction_hash, transaction_index, transaction_type, transaction_type_name, version}(uppercase hex); - its
/accounts/:address/movements:limitdefault 100, at most 500; rows as the node's, a group member's rows withbooked_on; - its
/registry/gateways: a bare array whose rows carrygateway_address(ZBG_),owner(ZBC_),locked_stake,heightbesides the node's fields. Routes only the node has (/blocks/height/:h,/blockchain/*, most of/accounts/:a/*,/transactions/pending, …) reach the node unchanged.
Rule activation. None.
Rejections and errors. The archival's own.
Vector. computed (the archival program's field sets and its default settings; the values are the relaunched chain's).
- INPUT:
GET https://zoobc.network/api/v1/node/info→ EXPECTED OUTPUT: an object with exactly the keysarchival_node(true by default),archival_version,blockchain_height,blocks_behind,confirmed_depth(3, the default depth, while a mirror database serves; 0 when the node's own database is served directly),genesis_hash(the chain's block-0 hash, uppercase hex),height,newer_release,node_id("archival-api"),node_version,p2pAddress(""),peer_count(0),public_api_url(https://<the configured public hostname>,""when none is configured),signing_tag("ZBC-TX"),signing_version(2),source_height,synced,syncing,version(plussync_noteonly when the node's database reports no height);synced=source_height> 0 andsource_height − height ≤ confirmed_depth. - INPUT:
GET https://zoobc.network/api/v1/spine/blocks/0→{"block_hash":<the spine genesis hash, uppercase>,"blocksmith_public_key":<uppercase>,"hash":<the same hash>,"height":0,"previous_block_hash":…,"previous_hash":…,"timestamp":1793509027}(the shipped spine file'sgenesis_timestamp). - INPUT:
GET https://zoobc.network/api/v1/accounts/00000000bccb80820d3e3fce6e62f1c283acf6b0ab884a937af47120de2ffe88a393b4d6→{"account":"ZBC_XTFYBAQN_HY7443TC_6HBIHLHW_WCVYQSUT_PL2HCIG6_F77IRI4T_WTLOGT6O","account_address":"00000000BCCB80820D3E3FCE6E62F1C283ACF6B0AB884A937AF47120DE2FFE88A393B4D6","address":"ZBC_XTFYBAQN_HY7443TC_6HBIHLHW_WCVYQSUT_PL2HCIG6_F77IRI4T_WTLOGT6O","balance":…,"locked_balance":…,"pop_revenue":…,"spendable_balance":…,"total_balance":…,"transact_policy":…}(the text form of01over the 36 bytes; the balances are the chain's).
Test cases · §9
3 cases · 3 valid · 3 reference
The archival service's node info: its keys
Exactly these keys (plus sync_note only when the node's database reports no height), at the archival program's defaults: confirmed_depth is 3 while a mirror database serves and 0 when the node's own database is served directly; public_api_url is "" when no public hostname is configured; synced = source_height > 0 and source_height − height ≤ confirmed_depth.
A stated value: there is nothing to compute. A compatible node shows the same value.
- request
GET https://zoobc.network/api/v1/node/info- status
200- body
{"archival_node":true,"archival_version":…,"blockchain_height":…,"blocks_behind":…,"confirmed_depth":3,"genesis_hash":<the chain's block-0 hash, uppercase hex>,"height":…,"newer_release":…,"node_id":"archival-api","node_version":…,"p2pAddress":"","peer_count":0,"public_api_url":"https://<the configured public hostname>","signing_tag":"ZBC-TX","signing_version":2,"source_height":…,"synced":…,"syncing":…,"version":…}
Spine block 0 from the archival service
The timestamp is the shipped spine file's genesis_timestamp.
A stated value: there is nothing to compute. A compatible node shows the same value.
- request
GET https://zoobc.network/api/v1/spine/blocks/0- status
200- body
{"block_hash":<the spine genesis hash, uppercase>,"blocksmith_public_key":<uppercase>,"hash":<the same hash>,"height":0,"previous_block_hash":…,"previous_hash":…,"timestamp":1793509027}
An account from the archival service
The text form of 01 over the 36 bytes; the balances are the chain's.
A stated value: there is nothing to compute. A compatible node shows the same value.
- request
GET https://zoobc.network/api/v1/accounts/00000000bccb80820d3e3fce6e62f1c283acf6b0ab884a937af47120de2ffe88a393b4d6- status
200- body
{"account":"ZBC_XTFYBAQN_HY7443TC_6HBIHLHW_WCVYQSUT_PL2HCIG6_F77IRI4T_WTLOGT6O","account_address":"00000000BCCB80820D3E3FCE6E62F1C283ACF6B0AB884A937AF47120DE2FFE88A393B4D6","address":"ZBC_XTFYBAQN_HY7443TC_6HBIHLHW_WCVYQSUT_PL2HCIG6_F77IRI4T_WTLOGT6O","balance":…,"locked_balance":…,"pop_revenue":…,"spendable_balance":…,"total_balance":…,"transact_policy":…}
Defects to match. A client cannot tell from a 200 which program answered except by the field set; the archival's hex is uppercase, the node's lowercase; the same path can answer a bare 32-byte key on the public domain (archival) and refuse it on a node.
§10 Consensus and local; summary of defects
Nothing in this chapter is consensus. What an implementation must match for the clients: the routes, parameters, field names and order where stated, hex case, id spellings, status codes, the 202 of a submission, the two 404 kinds, the submit body, the signed-request preimage and the cancel digest. The limits, timeouts and the gateway's fall-through are operational.
Defects: (1) 64-bit ids are strings on some routes and numbers on others; /node/blacklist can answer invalid JSON (§3). (2) /accounts/:address/transactions loads up to 500 whole blocks per call, and the account's app list reads only the newest 1,000 app rows (§6). (3) The /internal/attest response timestamp may differ from the signed one, and the route sits outside /api/v1/ (§8). (4) The two programs behind one domain answer different JSON for the same path family (§9). The ⚠ notes in §3, §4, §7 and §8 describe the reference's behaviour; an implementation need not reproduce them.
A question about this chapter, or a statement that does not match the network? Discuss on zoobc.pro.