Skip to content

ZkMap v1 specification

Status: Implemented in source. Mainnet creation follows the same launch gates as every other Zordinal operation; the status page says what can complete today. Ruleset: zkmap-v1 Date: 2026-09-18

ZkMap assigns one number to every Zcash block. The number of block 1,500,000 is 1500000.zkmap; the number of the genesis block is 0.zkmap. A block number is claimed by inscribing it as a Zordinal. The first eligible claim completed on chain wins the block, and the block (its district) then belongs to whoever holds the output that carries the winning inscription.

A district is therefore a Zordinal with a verdict attached to it. It moves the way any Zordinal moves, lists and sells the way any Zordinal does, and is tracked by the same ownership rules. ZkMap adds exactly two things: the rule that decides which inscription wins a block, and a deterministic picture drawn from the block itself.

A claim is an inscription that satisfies all of the following:

  1. It is a complete, verified Universe Zordinals v1 inscription: the envelope parses under Zordinals v1, every piece has arrived, and the v1 content commitment verifies. Legacy inscriptions without the v1 commitment are never claims, whatever their text says.
  2. Its content type is exactly the ASCII string text/plain. No parameters, no charset, no other media type.
  3. Its body is exactly the ASCII text <height>.zkmap and nothing else: no leading zeros in the height, no whitespace, no newline, no byte order mark, no other bytes. 0.zkmap is valid. 007.zkmap, 7.zkmap followed by a newline, and 7.zkmap preceded by a space are not claims; they are ordinary Zordinals.
  4. The height is an unsigned decimal from 0 to 2147483647.

The grammar of the body is:

name = height ".zkmap"
height = "0" / ( %x31-39 *9DIGIT )

Because the bytes are fixed, so is the content hash: the SHA-256 of the ASCII text is the same for every claim of the same block, and the v1 commitment is SHA-256("UZRD1" || "text/plain" || 0x00 || name). The product generates these bytes on the server for every mint; nothing about the inscription is composed in the browser.

A claim targets the block numberd in its body. The target height must be strictly below the height of the block in which the claim completes (the block containing the reveal transaction that carries the final piece). A claim that names its own block, or a block that has not been mined yet, is ineligible and can never win, even if nobody else ever claims that block.

0.zkmap targets the genesis block and is eligible from block 1 onward.

For each target height, the winner is the first eligible claim completed on the active chain, in chain order:

  1. lower completion height first;
  2. within a block, lower transaction index first;
  3. within a transaction, lower inscription index first.

Every later eligible claim for the same height is a loser. A losing claim is not deleted, hidden or refunded by the protocol: it is an ordinary Zordinal, owned and transferable like any other, with a claim receipt whose verdict is loser and which names the winning inscription.

The product’s claim receipt (GET /api/zkmap/claims/{inscriptionId}) carries one of four verdicts: winner, loser, ineligible (a valid claim whose target was not strictly below its completion height) or invalid (the bytes or the commitment did not qualify). An inscription that is not a claim at all has no receipt.

The district belongs to the holder of the winning inscription’s carrying output, exactly as ownership lives on outputs for every Zordinal. Consequences:

  1. Sending the winning inscription sends the district. A market sale that settles the winning inscription’s output delivers the district to the buyer.
  2. The block number itself never changes hands; its inscription does. There is no transfer operation specific to ZkMap.
  3. A winner whose output is burned, or spent into a shielded pool where the protocol stops tracking it, keeps the block occupied forever. The block shows as claimed with no spendable owner. It can never be re-minted, and no later claim for that height can win.
  4. A chain reorganization can change the winner: if the block that completed the winning claim is disconnected, the verdict is recomputed on the new active chain, and the product reports the affected mint outcome as reorged. The map only ever shows the active chain at the indexer’s checkpoint.

The product reports one status per block, at the indexer’s qualified checkpoint:

StatusShown asMeaning
availableAvailableSafe history plus a fresh, complete owned-node observation show no matching mempool reveal
claimedClaimedA winner exists; the page names it and its holder
pendingMempoolA valid matching reveal is observed in the owned node mempool; it is not a winner or reservation
futureNot mined yetA fresh verified node tip proves that the height does not exist yet
ineligibleNot claimableThe height cannot be claimed, and the page says why
unknownNot yet checkedNothing is known about this height yet; never shown as available

Availability is never a reservation. A block shown as available can be won by someone else’s claim before yours completes, and a claim that loses on chain still paid for its inscription. A block nobody could check yet is shown as not yet checked, never as available and never with a question mark.

A status, once known, stays on screen. When a later check fails, is cut short or cannot decide a block, the map, the block list, the side panel, the block page and the mint review keep showing the last known status in its own words and colour, with when it was last checked. Nothing turns a known block back into “not yet checked” because one read went wrong.

The service keeps these last known statuses too, per network, chain and block, with the time each was first seen. They are shown for information only: they never decide who owns a ZkMap, and never allow a send, a listing or a purchase. A claimed block stays claimed until the owned node proves its winning transaction left the chain; the earlier winner is then kept in the block’s history, marked as reorganised away.

A claim is decided by the chain, not by what anyone observed first, so any valid block number can be minted: available, pending, already claimed, not mined yet, not claimable or not checked yet. Each mint is an attempt. The review says which blocks will probably not win and why, and asks you to accept the terms before anything is created:

  • the first valid claim completed on chain wins;
  • fees are spent whether or not your attempt wins;
  • on the pay-with-any-wallet path, the payment funds the attempt and is not refunded because another claim came first.

Nothing is reserved, and minting a block that already has a winner does not change its winner: your inscription is kept as an ordinary Zordinal, and the outcome says it lost. A block that is not mined yet only counts if its claim completes after the block exists.

These terms (attempt-any-v1) are recorded with the order when it is created and never change afterwards. Orders created before them, and clients that do not accept them, keep the earlier terms (legacy-conflict-check-v1): a block already known to be claimed, not mined or not claimable is refused, and an unspent invoice payment whose block was claimed before it was spent is refunded.

Range, detail and availability responses carry an additive occupancy envelope with schema zkmap-occupancy-v1 when the indexer supports the current observation contract. It is sourced only from the owned Zebra mempool (source: owned-zebra-mempool, decoder zkmap-mempool-v2; earlier indexers report zkmap-mempool-v1). A local order, invoice, accepted signature or broadcast acknowledgement is not membership proof.

The envelope binds network, genesisHash, snapshotId, sequenceAtomic and the observed node tip to the historical checkpoint. It records startedAt, observedAt, expiresAt, completeness: complete|partial|unavailable, an explicit reason, pendingCountAtomic, up to eight bounded candidates and candidatesTruncated. Each candidate includes the reveal txid, input index, exact name and target height, decoder version, content hash, commitment and observed times.

Only safe complete historical coverage plus a fresh, unexpired, same-tip, complete current-decoder observation with zero candidates can be available. A positive candidate may be pending even when the pool sample is partial, but that is advisory and does not elect an owner. A confirmed winner remains claimed, including when its owner is burned or shielded. Partial, stale, lagged, old-decoder or mismatched observations are unknown for current mint admission, and a missing block hash alone is not proof that a block is future.

The legacy HTTP status field remains the five-value rolling-deployment contract. Pending is serialized there as unknown with reason PENDING_CLAIM_OBSERVED; this page’s six-state status comes from occupancy.effectiveStatus. Clients without the additive envelope must normalize historical available to current unknown rather than mint from it. Pending candidates are evidence only; the confirmed scanner and chain order decide winners.

Every district has a picture, rendered by the product from the target block itself and served as an inert image. The current edition is zkmap-bitmap-v1, a PNG at GET /api/zkmap/blocks/{height}/art.png; the four SVG editions before it stay exactly as they were, at GET /api/zkmap/blocks/{height}/art.svg. The picture is not inscribed and is not part of the claim; the inscription’s bytes remain exactly <height>.zkmap and are one click away from every picture. Nothing about ownership, price or rarity can be read out of a drawing.

Two things are versioned separately. The layout decides where each transaction goes; the artwork decides what is drawn there. The claim ruleset zkmap-v1 is a third thing again, and no artwork version touches it. Every edition keeps its own addresses and its own bytes for ever: a new drawing is published at a new URL rather than swapped in at an old one.

Fully determined by public chain data:

  1. The canvas is the square from (0, 0) to (1024, 1024), with an 80-unit label band below it that never overlaps the geometry.
  2. The parcels are the block’s transactions in block order, the coinbase included, each weighted by its serialized byte length. A shielded transaction contributes only its byte size, which is public. No owner, price, time or randomness enters the geometry.
  3. The rectangle is split recursively: the ordered list is divided at the boundary whose cumulative weight is nearest half the total (the earlier boundary on a tie), and the rectangle is cut across its longest axis (x on a tie) in proportion to the two weights, clamped to at least one unit each side. Recursion stops at a single transaction, or when the longest axis is below 2 units, in which case the remaining transactions become one aggregate parcel that records their count.
  4. A one-unit gutter is taken from the right and bottom edge of every parcel that can spare it.

A block whose only transaction is the coinbase is one parcel, and stays one parcel: transactions are never invented to make a picture busier. Two blocks with equal or proportional transaction sizes share this geometry, and that is correct: they really do have the same shape. Changing any rule above is a new layout version, never a silent change to zkmap-treemap-v1.

What distinguishes two districts of the same shape is the artwork, and it is derived from the whole block identity:

  1. A seed is taken over the network, the genesis hash, the decimal height and the full block hash. It chooses one of eight frozen palettes.
  2. Every parcel has its own hash, over that seed, the parcel’s position, its inclusive transaction bounds and the first and last transaction id it covers. That hash picks its fill from the palette’s five shades and draws its engraved contours. Two blocks with identical transaction sizes still differ here, because their transaction ids differ.
  3. The full 256-bit block hash is drawn once around the frame, most significant bit first, as 256 small cells running clockwise from the top-left, outside a uniform inset. This is the district’s signature.

The perimeter signature is a signature and the interior contours are texture. Neither is a transaction, a parcel or a claimable piece of a district. The coinbase parcel is marked with a thin outline and otherwise takes the ordinary colour its own hash chose.

The current picture is not an SVG and is not drawn from transaction sizes. It draws one yellow square per transaction, sized by the public transparent value that transaction paid out, packed in the block’s own order on a transparent ground:

GET /api/zkmap/blocks/{height}/art.png
?art=zkmap-bitmap-v1&network=testnet&size=256&hash=<block hash>
PropertyValue
Artworkzkmap-bitmap-v1
Layoutbitmap-mondrian-v1
Native image576 x 576, 8 bit RGBA PNG
Colour#FACC15 opaque, on fully transparent
Sizes256, 512, 576 and 1024

A transaction’s square has side max(1, ceil(log10(zatoshis)) - 5): one unit per order of magnitude above 0.01 ZEC, and the smallest square for everything at or below it. Squares are placed in transaction order, never sorted, into the first free slot scanning rows upward and left to right.

What the size means, and what it does not. It is public transparent output value, counted in exact zatoshis. Shielded value is private and stays private: a transaction that moved its whole payment shielded has a public transparent sum of zero and draws the smallest square, and nothing infers a hidden amount from a value balance or anything else. The picture is therefore not a picture of a block’s total economic activity, and two blocks that moved the same public amounts really do look alike. Fees, subsidies and byte sizes are not used as stand-ins for a value anywhere.

There is no label. The block’s name, its transaction count and its date are text on the page beside the picture, where a screen reader and a text search can reach them.

network is required and must be the network the block was read on, as for every edition after v1. The response names what it drew in x-zkmap-art-version, x-zkmap-network, x-zkmap-block-hash, x-zkmap-input-digest and x-zkmap-content-sha256.

The immutable address of a picture’s bytes

Section titled “The immutable address of a picture’s bytes”
GET /api/zkmap/media/{sha256}

A height is an alias that follows the chain, so art.png is always revalidated. This route names exact bytes and nothing else, so it may be kept for a year. It makes no claim about which block is current and none about who owns the district: it may serve a picture of a block that has since been replaced, which is what a historical reference is for. It answers only for published district artwork.

zkmap-art-v1 is kept, and its promise is corrected

Section titled “zkmap-art-v1 is kept, and its promise is corrected”

The first artwork chose its palette from the first byte of the block hash and painted every coinbase parcel one fixed colour. The earlier version of this page said that two blocks with the same transaction shape still differ by the block they name. That was not true of zkmap-art-v1: proof-of-work makes leading hash bytes anything but uniform, and with the coinbase always the same colour, a block whose only transaction is the coinbase drew the same picture as any other such block. zkmap-art-v1 is still served, byte for byte, for clients built against it; zkmap-art-v2 is what makes the promise true.

GET /api/zkmap/blocks/{height}/art.svg
?art=zkmap-art-v2&network=testnet&size=256&hash=<block hash>

art omitted, or art=zkmap-art-v1, returns the legacy picture unchanged. art=zkmap-art-v2 needs network, and it must be the network the block was read on: a missing network is an error, not an assumed mainnet, and a network this service does not serve is refused rather than drawn from another chain. size is 256, 512 or 1024, and every size shows the same complete picture and signature. The response names what it drew in x-zkmap-art-version and x-zkmap-network.

The SVG contains only svg, rect, g, path and text elements, escaped numeric and hex labels, and fill and stroke attributes: no script, no external reference, no foreignObject, no event handler, no animation.

A cached picture is history, not a live answer

Section titled “A cached picture is history, not a live answer”

A hash-pinned request (?hash=<block hash>) may be kept by a browser for a year. Such a copy is a picture of one block as it was, and it cannot notice a reorg by itself: a browser holding a fresh immutable copy does not ask again. That is why the artwork version is part of the address: a new drawing is published at a new URL rather than swapped in at the old one. Only a fresh request that pins a hash which no longer names the block at that height answers 409. Which block a height names now is decided by reading the block or the claim receipt again, never by looking at an image.

https://zordinals.run/zkmap/<height> is one district, and it opens with the district: the picture, and beside it the shortest true answer about it.

The summary. The claim status in its own words, the current owner as a link to their portfolio with a copy control beside it, the date the block was mined, how many transactions it holds, and one action if there is one to offer. Where the service says a height cannot be claimed at all, the reason it gave is shown rather than the bare words “Not claimable”. Claim status and sale status are never fused into a single badge: a district can be claimed and not for sale, and a listing is an offer held by this service, not a chain fact.

The action. Mint, when the district is free and its observation is still current. Send, when the connected wallet is the confirmed holder and the carrying output can be spent. View inscription, whenever a winner exists. Try to mint, for any other block: the mint review states the risk. When the block cannot be read right now, the page shows its last known status and when it was checked, or says it has not been checked yet. Nothing invents a Buy, a price or a rarity score. An observation that has expired says the availability is being checked rather than continuing to offer a mint, because availability is an observation and not a reservation.

The market. One rail per district, beside the picture. It says which of five things it is doing rather than guessing: checking, unavailable with a retry, verified not listed, an active listing at its exact price, or a last answer that could not be re-checked. An offer marked as possibly unbacked is not an ordinary safe purchase, and a sale waiting to confirm is not a sale. An offer that ended without a sale says how it ended: cancelled, with the published limit of what cancelling actually revokes; expired, with the block height the signature committed to; no longer valid, with the service’s own reason; or overtaken by a chain reorganisation, with whether the settlement it recorded still stands. A completed sale is reported instead of any of these, because two answers to one question is worse than one.

The evidence. Under the summary, at most four trait highlights chosen from what the service actually answered, then the whole catalogue behind All traits, searchable by plain name, original id or description, and filterable by whether the answer is known, unknown, or a key that has no Zcash meaning. Nothing is dropped to make the page short: every returned trait is there, and false, 0, unknown and not-applicable stay four different answers.

The record. Transactions lists every transaction of the block, paged, with its byte size and its coinbase and shielded marks, and it is the keyboard equivalent of pointing at a square in the picture. Record details holds the full block hash, the winning inscription, the claiming block and transaction, the owner address, the carrying output and the checkpoint the record was read at, whole and selectable, with links into the explorer and the portfolio. How ZkMaps work is the short version of this page. All three are closed until you open one, and a link that names one opens it.

When a read fails. The picture, the transactions, the traits and the market are four separate reads, and each says so on its own with a retry that asks only for itself. A failed trait read never removes the owner or the market record. The transactions and the traits are read against the exact block, network, genesis, height and hash together, so a reorg that replaces the block at a height asks for the replacement rather than leaving the sections blank.

Selling and cancelling. A published listing shows its cancellation value once, and this browser keeps a copy bound to that network, listing, asset and seller so the cancel page can find it again. “Listing published” and “Recovery saved” are two separate statements: a browser that refuses to keep the value says so while it is still on screen and offers it as a copy or a file. Pasting the value by hand always works, on any device. A request whose answer never arrived is settled by asking the service about the order that was signed, never by signing a second time.

Paying. An invoice shows the exact ZIP-321 request as a QR. A request too long for the small in-house encoder is drawn by the larger one; a request longer than any QR can hold says so and points at the copy and open-in-wallet controls, which carry the identical request. The address, the exact amount and the instructions never change with the symbol.

The market at /market/zkmap is built from the winning districts, not from listings: every district is shown whether or not it was ever listed, and a listing is attached to the district it sells. The market’s copy of the districts is refreshed from the indexer continuously and is only published once it is complete, so a half-read market is never shown as the whole one. The copy is for browsing; a purchase still reads the claim receipt and the live output of the winning inscription when it happens.

Offers on “any zkMap district” are ordinary market orders over the reserved collection zkmap-v1:all: a district belongs to it exactly when its inscription is the current winner of its block and is held at the output the seller names. This is an application rule of the market, not a new on-chain protocol, and it does not change who wins a block.

All operations are under the zkmap tag of the public HTTP API. Heights travel as exact decimal strings.

OperationPurpose
GET /api/zkmap/blocks?start=&limit=A window of statuses, occupancy proof, block hashes, winners and owners (limit up to 1024)
GET /api/zkmap/blocks?start=&limit=&view=draftThe map for picking blocks while the reading is incomplete (zkmap-blocks-draft-v1): the node tip, the projection checkpoint or null, a strict flag, and one status per height up to the node tip. Unknown is never available
GET /api/zkmap/blocks?start=&limit=&view=displayThe map as shown (zkmap-display-v1): currentRead (ok, degraded or unavailable), and per height the current read, the lastKnown status with its own chain identity and first-seen time, and the display status with its source (current, retained or none) and whether it is stale. Tip and chain identity are null when nothing current could establish them
GET /api/zkmap/blocks/{height}One block’s status, occupancy proof, winner and owner
GET /api/zkmap/blocks/{height}?view=displayOne block as shown (zkmap-block-display-v1): the strict record or null, the display status, lastKnown and the winners recorded for the height (history, each active or reorged)
GET /api/zkmap/blocks/{height}/geometryThe SVG editions’ input: ordered transaction byte sizes and their digest
GET /api/zkmap/blocks/{height}/art.svg?art=&network=&size=&hash=The SVG district picture at 256, 512 or 1024; every edition after v1 needs the network it was observed on
GET /api/zkmap/blocks/{height}/art.png?art=zkmap-bitmap-v1&network=&size=&hash=The bitmap district picture at 256, 512, 576 or 1024
GET /api/zkmap/media/{sha256}Exact published artwork bytes, immutable; no claim about the current chain or about ownership
GET /api/zkmap/districts?owner=&cursor=&limit=&order=Claimed districts, optionally held by one address
GET /api/zkmap/claims/{inscriptionId}The claim receipt and verdict of one inscription
POST /api/zkmap/availabilityPreflight of up to 24 heights with historical and current occupancy evidence; an observation, not a reservation. source says what answered (strict, draft or node); the checkpoint and genesisHash are null when only the node answered. Each height carries its lastKnown status, and admissionPolicy names the terms new orders are created under
POST /api/zkmap/prepare, POST /api/zkmap/batch/prepareConnected-wallet mint of one, or up to 24, block numbers. Send admissionPolicy: "attempt-any-v1" to accept the attempt terms; without it the earlier terms apply
POST /api/zkmap/invoices, POST /api/zkmap/invoices/batchPay-from-any-wallet mint of one, or up to 24, block numbers, with the same admissionPolicy acknowledgment
GET /api/zkmap/orders/{orderId}/claimThe claim outcome of a connected-wallet mint order
GET /api/zkmap/payment-orders/{orderId}/claimsThe claim outcomes of an invoice mint
GET /api/zkmap/marketEvery winning district, listed first, with filters (status, q, price, block range, owner, traits) applied to the whole market; unlisted districts have no ask and no price
GET /api/zkmap/market/facetsPer-trait counts over the selected districts, each trait counted without its own selection
GET /api/zkmap/market/holdersCurrent holders of the selected districts
GET /api/zkmap/market/history?window=Confirmed district sales only: count, exact volume, last, high, low and the sale points
GET /api/zkmap/market/activity?kind=District sales, listings and delistings, newest first
GET /api/zkmap/market/floor-historyThe lowest open ask and the listed count over the whole market history (zkmap-floor-history-v1), one point per change; floorZatoshis is null where nothing was listed. Past 20,000 events it answers complete: false with reason: "over-bound" and no points

Every response is bound to the indexer checkpoint (height and hash) it was read at, or says it has none. A mint order’s claim outcome (pending, accepted, conflict, invalid, reorged, unknown) is tracked separately from the order state: only accepted beside a complete order is a won district. A complete order whose claim lost is a conflict, and the product says so.

  1. It does not resolve names to addresses and is not part of any name registry. See Names and Dual-Registry Architecture.
  2. It does not reserve a block for anyone before a claim completes on chain.
  3. It does not refund a claim that lost on chain; the inscription was made and is the loser’s to keep. (Under the earlier product terms only, the invoice path refunds a payment whose name was already known to be taken before the payment was spent. That is a product rule, not a protocol rule, and the attempt terms do not include it.)
  4. It does not re-open a block whose winner was burned or shielded.