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 defined by vertices with exact integer coordinates.

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.

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.

The hierarchy also plays an economic role. Parent parcels (those at shallower depths that spatially contain smaller parcels) collect a share of tax revenue from their children. This incentivizes large landowners to steward the regions they encompass — more on that in the Tax section below.

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, meaning any user can read from it and, through the market contract, write to it.

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. Because each parcel is stored in exactly one cell (not duplicated across every grid square it touches), storage cost is O(1) per parcel regardless of size.

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.

Buyout and Harberger-Style Pricing

In merca.earth, every parcel is always for sale. There is no way to take land off the market. This follows Harberger tax theory: you own something, you declare its price, and anyone can buy it from you at that price.

Here is how it works:

1. Base price. Each Index level has a configured price per square kilometer (in SUI). A parcel's base price is its area multiplied by that rate.

2. Premium. Each parcel carries a premium multiplier $M$ that starts at 1x when first registered. Every time the parcel changes hands, $M$ escalates according to a resale ladder — the first resale carries a 2.95x multiplier, the second around 2.18x on top, and so on, tapering toward a floor of about 1.15x per subsequent sale.

3. Forced buyout. Any user can pay the current buyout price and immediately become the new owner. The seller has no veto.

The buyout price at any moment:

$$P_{\text{buyout}} = A \times R \times M$$

where $A$ is area, $R$ is the level's base rate per km², and $M$ is the current premium. The payment splits: 85% to the seller, 7% to the protocol treasury, 8% to the hierarchy tax pool (cascading to parent parcels).

This prevents land hoarding: price too high, you pay more in tax; too low, someone buys you out. The market finds equilibrium.

Tax

A portion of every payment (registration, buyout, expansion, slice acquisition) is routed into a tax fund. This fund does not go to a central authority. Instead, it cascades upward through the spatial hierarchy:

• Tax revenue from a parcel flows into buckets claimable by parent parcels at each level above.
• When a parent collects, it keeps a configured share and forwards the remainder further up the tree.
• If nobody collects within an expiry window, anyone can sweep the expired bucket and return the funds to the treasury.

Owners withdraw accumulated tax revenue at any time via withdraw_tax. The system uses versioned buckets so that when geometry changes (splits, merges, expansions), accounting stays consistent — old buckets close and new ones open automatically.

The cascading tax creates a virtuous loop: large territorial owners are rewarded for economic activity inside their boundaries, giving them incentive to attract smaller registrations rather than sitting on empty land.

Registration

Claiming land is a single transaction called register:

1. You submit the polygon geometry — vertex coordinate arrays for each convex Part.
2. The protocol validates the shape: minimum three vertices per part, positive area, minimum edge length, convexity, proper multipart connectivity, and a compactness threshold.
3. The Index computes the bounding box, finds the natural quadtree depth, and checks overlapping cells for collisions using the Separating Axis Theorem (SAT).
4. If all checks pass, the parcel is inserted into the Index, a Registered event is emitted, and you become the owner.
5. You pay the base registration price $P = A \times R$ (with the initial $M = 1$). The payment splits into treasury and hierarchy-pool shares just like a buyout.

Registration is atomic — if any step fails, the entire transaction reverts. You either get a fully valid, non-overlapping parcel or nothing.

Metadata

Once you own a parcel, you can attach metadata to it. Metadata is stored as a Sui dynamic field on the Index, keyed by the parcel's ID. The on-chain record holds only a content URI and the epoch when it was last updated.

The URI points to an off-chain JSON document on Walrus (a decentralized storage layer) that can contain anything — a name, description, images, links, or structured data. This keeps on-chain storage costs low while letting owners publish rich information about their parcels.

Key rules:

• Only the current owner can set or update metadata.
• Setting metadata costs only gas — no additional payment beyond transaction fees.
• Calling set_metadata again overwrites the previous URI.
• When a parcel is removed or destroyed (for example, during a split), metadata is automatically cleaned up.

---

With these six concepts — parcels, the quadtree hierarchy, the spatial index, Harberger-style buyouts, registration, and metadata — you have a working understanding of the protocol. Head to the Getting Started guide and claim your first parcel.