Key Concepts
Parcel
A parcel is the fundamental unit of land in merca.earth. On the map it appears as a polygon — a closed shape you draw on the world.
- For Users
- Technical Details
A parcel is a piece of the map that you own. Draw a shape, register it, and it is yours. Parcels can be simple rectangles or complex multi-part shapes (like an L-shaped lot). Every parcel has an owner, a shape, and a creation date.
The protocol enforces strict rules: shapes cannot overlap, must have real area, and must pass quality checks. If anything is wrong, the registration fails — no invalid land can ever exist on the map.
Every corner snaps to a precise grid point, and the protocol uses fixed-point arithmetic (no floating-point rounding) so that independent nodes always agree on whether a shape is valid.
A single parcel can be a multi-part polygon — a union of up to 10 convex pieces that share edges. This lets you represent L-shaped lots or land with cutouts. Each convex piece is called a Part; the protocol verifies that they connect properly and never overlap internally.
Every parcel carries a few essential fields on-chain:
- Owner address — the Sui account that controls the parcel.
- Geometry — vertex coordinates of each Part, plus a precomputed bounding box (AABB).
- Created epoch — the Sui epoch when the parcel was first registered.
The protocol enforces strict spatial rules at the transaction level: parcels must have positive area, edges must meet a minimum length, shapes must pass a compactness check, and no two parcels may overlap. If any rule is violated, the transaction fails — invalid geometry can never be recorded on-chain.
Spatial Hierarchy and the Quadtree
Imagine the entire world map divided into four quadrants. Each quadrant divides into four smaller quadrants, recursively — like repeatedly folding a piece of paper. This recursive subdivision is a quadtree, and it is how merca.earth organizes all parcels spatially.
Every parcel lives at a natural depth: the shallowest level where its bounding box fits entirely inside a single cell. A small city lot sits deep in the tree (a tiny cell), while a large territorial claim sits near the top (a broad cell). The protocol supports up to 20 levels of depth, covering everything from continental regions down to individual building footprints.
The hierarchy also plays an economic role. Parent parcels (those at shallower depths that spatially contain smaller parcels) collect a share of tax flow from their children. More on that in the Tax section below. For a technical deep-dive on cell addressing, Morton codes, and tax routing, see Hierarchy → Quadtree Cells.
How does spatial addressing work? (Morton codes)
Cell addresses use Morton codes (Z-order curves) — interleaving X and Y coordinates into a single integer. This makes spatial lookups fast: to find overlapping parcels, the protocol only checks the cells an area touches, rather than scanning every parcel.
Each parcel sits at the shallowest depth where its bounding box fits inside a single cell. Up to 20 levels of subdivision are supported.
Index
The Index is the shared on-chain data structure holding all parcels. There is one Index per deployment level (for example, one for country-scale parcels and another for city-scale parcels). It is a Sui shared object: any user can read from it, and the market contract writes to it.
When you register a new parcel, the Index places it in the correct spatial cell and checks for overlaps. Because each parcel is stored in exactly one cell, storage cost is O(1) per parcel regardless of size.
What does the Index store internally?
Under the hood, the Index contains two key tables:
- cells — maps each Morton-coded cell key to a list of parcel IDs at that cell.
- polygons — maps each parcel ID to its full Polygon object (geometry, owner, epoch).
When you register a new parcel, the Index computes the natural depth, places it in the correct cell, and runs overlap checks against neighboring cells.
The Index also issues capabilities — cryptographic tokens that authorize the market contract to transfer ownership or register new parcels. This separation keeps the spatial core simple and auditable, while economic logic lives in a separate market layer. See Architecture → Shared Object Layout for the full module breakdown.
Buyout and Harberger-Style Pricing
In merca.earth, every parcel is always for sale. There is no way to take land off the market.
Any user can pay the current buyout price and immediately become the new owner. The seller has no veto. Payment splits 85% to the seller, 7% to the protocol treasury, and 8% to the hierarchy tax pool.
For the full pricing model, premium ladder, and per-operation behavior, see Pricing → Buyout Price and Buyout & Premium → The Payment Split.
Tax
A portion of every payment (registration, buyout, expansion, acquisition) flows into a cascading tax fund. This fund distributes upward through the spatial hierarchy, so parent parcels can collect from activity within their boundaries.
Collect your tax balances regularly. Uncollected buckets expire and return to the treasury permanently.
For the full collection workflow and expiry mechanics, see Tax → What a Tax Bucket Is and Cash Flows → Tax Collection.
Registration
Claiming land is a single transaction called register: you submit geometry, the protocol validates it, checks for overlaps, and if everything passes you become the owner. You pay the base registration price (area multiplied by the level's rate). Registration is atomic — you either get a fully valid, non-overlapping parcel or nothing. After success, the parcel's stored buyout premium immediately advances to the first resale rung, so the next buyer sees a higher price than the registration quote.
For the step-by-step walkthrough, see Register Land → Step 1: Enter Drawing Mode.
Visual Layer
Once you own a parcel, you control its visual layer — the name, description, and artwork that other people see on the map. This is how you make your idea visible: not just by holding territory, but by shaping what it communicates.
For naming, drawing, and uploading images, see Name & Visual Layer → Setting a Name.
Paint
Anyone can paint pixels on the world map without a wallet. Each level — continent, country, region, city, district, block — has its own public canvas. Paint costs nothing, requires no signing, and appears on every viewer's map within thirty seconds.
Paint coexists with parcels: you cannot paint over registered land. The map enforces this for you — pixels covered by an existing parcel are dropped before they reach the canvas.
When you register a new parcel, the paint under your shape moves with you. It becomes the starting visual layer of the new parcel. The public canvas loses those pixels; you keep them, edit them, replace them.
For sessions, ink budget, painting tools, and how registration absorbs paint, see Paint.
With these seven concepts — parcels, the quadtree hierarchy, the spatial index, Harberger-style buyouts, registration, the visual layer, and paint — you have a working understanding of the protocol. Head to the Getting Started guide and claim your first parcel.
See also: How It Works → Two Layers · Hierarchy → Six Hierarchy Levels · Architecture → Module Dependency Graph · Glossary · FAQ