Glossary
Quick reference for terms used across the merca.earth documentation. Entries are alphabetized. Each links to the article where the concept is explained in full.
Acquire — A territory operation that captures a slice of a neighboring parcel owned by someone else. You pay based on the captured area at the donor's current premium. See Territory Operations.
Activity dot — A colored circle on the map at coarser zooms showing where painting is happening right now. Size scales with the past week of painting activity at that index; color encodes recency — red within the last hour, orange around a day old, gray near the end of the week. See Paint → Activity Dots.
Broadphase — The first pass of spatial collision detection. The protocol checks only the quadtree cells that a new parcel's bounding box touches, rather than comparing against every registered parcel. This makes overlap detection fast regardless of how many parcels exist. See How It Works → Three-Phase Collision.
Bump Price — An owner-triggered operation that raises a parcel's price by one step on the resale ladder. The fee is 15% of the current buyout price (7% to the protocol treasury, 8% to the hierarchy pool). The effect is identical to a self-buy but requires only one wallet. See Pricing → Owner Price Controls and Buyout & Premium → Bump Price and Drop Price.
Buyout — The forced purchase of a parcel at its current on-chain price. Any user can execute a buyout at any time; the owner cannot refuse. Payment splits 85% to the seller, 7% to the protocol treasury, and 8% to the hierarchy pool. See Buying a Parcel → How Buyout Works.
Cell (quadtree) — A single node in the quadtree spatial index. The world is recursively divided into four quadrants at each level; each resulting region is a cell. Every parcel is stored in exactly one cell — the shallowest cell whose bounds fully contain the parcel. See Key Concepts → Spatial Hierarchy.
collect_tax — The on-chain function that collects tax revenue from child parcels into a parent parcel, called via the market::collect_tax wrapper. Permissionless — any sender can call it, but the tax always transfers to the parcel owner. Collects and withdraws atomically in a single call: the owner's share is transferred immediately, no separate withdrawal step needed. Processes up to 20 child tax buckets per transaction, keeps the parent's share per the cascade formula, and forwards the remainder up the hierarchy. See Tax → What Owners Need to Do.
Compactness — A shape quality check enforced at registration. Extremely thin or elongated shapes fail this check. The protocol rejects shapes that would be difficult to decompose into valid convex parts or that represent degenerate geometry. See Geometry Rules → Compactness floor.
Convex decomposition — The process of splitting an arbitrary shape into a union of convex parts. The protocol stores parcels as convex parts rather than arbitrary shapes, enabling efficient SAT-based overlap detection. The app decomposes your drawn shape automatically; up to 10 parts are allowed. See Register Land → Validation Rules.
depth_prefix — The portion of a Morton code that encodes a cell's position in the quadtree hierarchy. Cells at the same depth share a common prefix length. The protocol uses depth prefixes to navigate the tree and find spatially related cells quickly. See Hierarchy → depth_prefix.
Detail panel — The sidebar panel that appears when you click a parcel on the map. It shows the parcel's price, area, owner, and available actions (buy, expand, collect tax, edit visual layer). For owned parcels, it also shows Bump Price and Drop Price controls. See Buying a Parcel → Finding a Parcel to Buy.
Drop Price — An owner-triggered operation that lowers a parcel's price by one step on the resale ladder. The fee is 8% of the current buyout price (hierarchy pool only — no treasury cut). The price can drop all the way back to the registration base (1.0× premium). See Pricing → Owner Price Controls and Buyout & Premium → Bump Price and Drop Price.
Enoki — Mysten Labs' authentication service that powers social sign-in on merca.earth. Enoki handles the OAuth flow and generates the zkLogin proof that derives your Sui wallet address from your social identity. See Wallet Setup → Social Sign-In with zkLogin.
Expand — A territory operation that grows a parcel into adjacent unclaimed space. You pay only for the added area at the base rate; your parcel's premium multiplier stays unchanged. See Territory Operations.
Forced sale — Another name for a buyout. The term emphasizes that the owner has no veto — the protocol transfers ownership automatically when a buyer pays the current price. See Buyout & Premium → Every Parcel Is Always for Sale.
Hierarchy pool — The 8% share of every transaction payment that flows into the cascading tax system. It distributes upward through parent parcels in the spatial hierarchy, rewarding owners of larger territorial claims. See Tax → Where the 8% Goes.
Index — The shared on-chain data structure that holds all registered parcels for a given deployment level. It maps Morton-coded cell keys to parcel IDs and stores each parcel's full geometry. The Index enforces spatial uniqueness: no two parcels at the same level may overlap. See Key Concepts → Index.
Ink — The per-session paint budget. Each level — continent, country, region, city, district, block — gets its own allocation: more ink at finer levels, less at coarser levels, calibrated so one full session covers a comparable share of your viewport at any zoom. When ink runs out, you wait out a cooldown of about twenty minutes before the next session opens. See Paint → Ink and Cooldown.
Merge — A geometry operation that combines two parcels you own into one. The surviving parcel adopts the area-weighted average of both premiums and the maximum of both sale counts. See Buyout & Premium → merge_owned.
MIN fee — The non-refundable tip paid to the parcel owner when submitting a POI proposal. Transferred immediately at proposal time, regardless of outcome. Default: 1000 MIST.
min_offer — A per-parcel threshold set by the owner that proposers must meet. If the owner sets a min_offer of 5000 MIST, any proposal with an offer below that amount is rejected on-chain. See POI Proposals → For Owners.
Morton code — A space-filling curve encoding that interleaves X and Y coordinates into a single integer. The protocol uses Morton codes to address quadtree cells, making spatial lookups fast: nearby cells have similar Morton codes, so range queries touch only relevant cells. See Hierarchy → Morton Codes (Z-Order).
Natural depth — The shallowest quadtree level at which a parcel's bounding box fits entirely inside a single cell. A small parcel sits deep in the tree; a large parcel sits near the root. The protocol assigns each parcel to its natural depth automatically at registration. See Hierarchy → Natural Depth.
Occupied mask — The rule that prevents painting over registered parcels. Pixels covered by an existing parcel are not drawn on the canvas. See Paint → Painting around parcels.
Paint — A pixel-grid raster layer over the world map that anyone can write to without a wallet. Each level — continent through block — has its own canvas. Free, anonymous, off-chain. When someone registers land, the paint under the new parcel becomes the parcel's visual layer; the public canvas loses those pixels. See Paint.
Paint session — A time-bounded slot in which you can paint anonymously. Holds a fixed ink budget, expires after twenty minutes. See Paint → Starting a session.
Parcel — The fundamental unit of land on merca.earth. A parcel is a shape you draw on the world map, registered on-chain as a Sui object. It has an owner, a shape (stored as convex parts), and a creation epoch. Parcels cannot overlap and are always for sale. See Key Concepts → Parcel.
Premium — The price multiplier applied on top of a parcel's base area price. Registration is charged at 1.0×, but the stored buyout premium immediately advances to the first resale rung (2.95×). Each buyout then advances the premium one step further up the resale ladder, making the parcel progressively more expensive to purchase. See Buyout & Premium → How premium_ppm Works.
POI (Point of Interest) — A named location proposed by any user on a block-level parcel. POIs carry a name, coordinates, optional icon, and an optional IPFS details link. The parcel owner decides which proposals to accept. See Proposing a POI.
premium_ppm — The on-chain representation of a parcel's premium multiplier, stored as parts per million. A value of 1,000,000 means 1.0× and is used for the registration quote; 2,950,000 means 2.95× and is the first stored rung after register. The protocol uses integer arithmetic throughout to avoid floating-point rounding. See Buyout & Premium → How premium_ppm Works.
Proposal — A pending request to add a POI to a parcel. Proposals carry an escrow payment that splits 85/7/8 on acceptance or refunds in full on rejection.
ProposalBoard — The shared on-chain object that stores all pending proposals. Created once by the admin, it holds the escrow pool and rate-limit counters.
Quadtree — The spatial data structure that organizes all parcels on merca.earth. The world is recursively divided into four quadrants at each level, up to 20 levels deep. Each parcel lives in exactly one cell — the shallowest cell that fully contains it. See Key Concepts → Spatial Hierarchy and Hierarchy → Quadtree Cells.
Rebalance — A territory operation that moves area from one of your parcels to an adjacent parcel you also own. No land cost — you already own both. After rebalancing, both parcels adopt the area-weighted average of the two premiums. See Territory Operations.
Registration — The act of claiming a new parcel on-chain. You submit a shape, the protocol validates it and checks for overlaps, and if everything passes you become the owner. Registration is atomic: it either fully succeeds or fully reverts. See Register Land → Step 1.
Resale ladder — The fixed sequence of per-sale premium multipliers applied by the protocol. Registration seeds the first rung at 2.95× for the next buyer, the next buyout applies 2.18× on top of that, and later steps taper toward a floor of 1.15× per sale after position 64. See Buyout & Premium → The Resale Ladder.
SAT (Separating Axis Theorem) — The collision detection algorithm the protocol uses to check whether two convex shapes overlap. For each pair of candidate parcels, the protocol tests whether a separating axis exists between their convex parts. If no axis separates them, the shapes overlap and registration fails. See How It Works → Three-Phase Collision and Geometry Rules → SAT Guarantee.
self_claimable — Deprecated. Previously accumulated tax balance held on-chain until withdrawal. Now collect_tax transfers the owner's share directly in the same call. The on-chain field exists for Sui upgrade compatibility but is always 0. See Tax → What Owners Need to Do.
Sui — The Layer 1 blockchain that merca.earth runs on. Sui uses an object-centric model where parcels are first-class on-chain objects. Transactions confirm in seconds and gas fees are typically a fraction of a SUI token. See Wallet Setup → Connection Methods.
Sui Snap — A MetaMask plugin that adds Sui support inside MetaMask. It lets you use your existing MetaMask wallet to sign Sui transactions without installing a separate extension. Desktop only. See Wallet Setup → MetaMask (Sui Snap).
sweep_expired — A permissionless on-chain function, called via the market::sweep_expired wrapper, that anyone can call on an expired tax bucket. It moves the uncollected funds permanently to the protocol treasury. Once swept, the revenue cannot be recovered by the original parent parcel owner. See Tax → Sweep Expired Buckets.
Tax bucket — An on-chain escrow record that holds the 8% hierarchy pool share from a transaction. Buckets are keyed by six fields: (polygon_id, version, bucket_id, origin_level_rank, ancestor_distance, accrual_epoch). Anyone can collect them via collect_tax before they expire — the tax always goes to the parcel owner. See Tax → What a Tax Bucket Is.
TransferCap — A capability object held by the Market contract that authorizes it to call index::force_transfer and reassign parcel ownership. This separation keeps the spatial Index simple and auditable while economic logic lives in the Market layer. See Architecture → TransferCap.
Version (parcel) — A counter that increments whenever a parcel's geometry changes through expansion, rebalance, merge, or slice acquisition. Tax buckets are keyed by version, so old buckets from a previous geometry remain collectible until they expire even after the shape changes. See Tax → What a Tax Bucket Is.
Visual layer — The name, description, and artwork that appear on the map for a parcel. Only the current owner can set or update it. Updating costs only gas. The visual layer is stored as a JSON document on Walrus; the blockchain holds only a lightweight URI. When you register a new parcel, paint under your shape becomes the starting visual layer for the parcel. See Name & Visual Layer and Paint → From paint to ownership.
zkLogin — Sui's zero-knowledge proof system for deriving a blockchain wallet address from a social identity (Google, Facebook, Twitch). Your social credentials never touch the chain — the proof confirms you control the account without revealing private data. See Wallet Setup → Social Sign-In with zkLogin.
See also: Key Concepts · FAQ · How It Works · API Reference