Name & Visual Layer

Your parcel is more than a shape on the map — it is a canvas. Name it, describe it, draw on it, upload artwork. You control the visual layer of your territory: what visitors see, read, and remember when they look at your land.

In merca.earth, ideas compete for space. The visual layer is how you make your idea visible — how you stake your claim not just economically, but culturally.

When you save, the app uploads your content to Walrus by default and records a walrus:// URI on the Sui blockchain. The protocol stores only that URI string — so metadata from external tools using ipfs:// or https:// URIs is equally valid. Your content is censorship-resistant, verifiable, and permanently tied to your ownership.

info

Walrus is a decentralized storage network — your visual layer content is censorship-resistant and remains available even if any single node goes offline.

What You Can Attach

Under the hood, the visual layer is a structured JSON document conforming to the Metadata Schema → Schema Definition. Only the schema version is required; everything else is optional, so you can enrich your parcel incrementally.

Schema structure

Opening the Editor

Select a parcel you own on the map and click Edit in the detail panel. A full-screen editor overlay opens with your parcel on a dedicated map view, a sidebar form for name and description, and a bottom toolbar for visual editing.

Close the editor with Escape or Cancel. No changes are saved until you explicitly confirm.

Starting from paint

If anyone painted on the public canvas under your parcel before you registered, those pixels carry over. The editor opens with the cropped paint already loaded as your visual layer — your starting point.

You can keep it, edit on top, or replace it entirely. Click Clear to wipe and start blank, or upload a new image. The choice is yours; the public canvas no longer holds those pixels regardless. See Paint → From paint to ownership for the full mechanic.

Nothing carries over for parcels registered on virgin canvas. The editor opens empty.

Setting a Name

The Name field at the top of the sidebar is the label that appears on the map, in search results, and in your holdings list.

Names can be up to 256 characters. Keep them concise — think of what a visitor scanning the map would find useful. A neighborhood might be "Riverside Quarter"; a city-level parcel could carry its official name. Setting a name is optional; block-level parcels are often identified by their on-chain ID alone.

tip

Names are plain text — no formatting or markup.

Adding a Description

Below the name is a rich-text editor powered by Markdown. Tell the story of your parcel — its history, purpose, whatever you want the world to know.

The toolbar offers bold, italic, underline, headings (levels 2 and 3), bulleted and numbered lists, links, and horizontal dividers. A diff-source switcher lets you toggle between rich-text and raw Markdown.

Descriptions support CommonMark Markdown, up to 10,000 characters. No raw HTML. Think of it as a small wiki page for your territory: notable features, zoning details, or practical information for visitors.

Adding Visuals

Draw

Drawing a Sketch

The editor includes a freehand sketch canvas directly on top of your parcel's shape.

Click Draw in the bottom toolbar. A transparent canvas appears, clipped to your polygon boundary. Draw freehand strokes in blue ink with mouse or stylus. Every stroke is captured as SVG vector data, staying sharp at any zoom level.

Click Clear to erase and start over. The sketch exports as SVG on save and uploads to Walrus.

Sketches have no prescribed purpose. Mark building footprints, trace pathways, highlight features, or sign your name.

Upload Image

Uploading an Image

Click Upload Image in the toolbar. Accepted formats: SVG, PNG, JPEG, and WebP, up to 1 MB.

The image appears inside the polygon boundary. Drag to reposition, scale to resize, rotate to adjust angle — the editor provides interactive handles for all three. The visible portion (clipped to the polygon) exports as PNG and uploads to Walrus.

Useful for logos, aerial photographs, custom illustrations, or any visual overlay for your parcel.

Saving Changes

Click Save at the bottom of the sidebar. The editor will:

• Validate your content (character limits, coordinate ranges, required fields).
• Upload visual content and the structured document to Walrus.
• Build a Sui transaction calling set_metadata.
• Prompt your wallet to sign and execute.

If validation fails, a warning describes the issue. If the transaction succeeds, the editor closes and your visual layer is live — visible to anyone viewing your parcel.

tip

You can update your visual layer any time. Each save creates a new on-chain record pointing to the latest Walrus version. Previous versions remain on the storage network but are no longer blockchain-referenced.

---

See also: Key Concepts → Visual Layer · Metadata Schema → Schema Definition · Register Land → Step 1 · Hierarchy → Six Hierarchy Levels

How storage works under the hood

The following diagram shows how your content flows from the editor to the blockchain:

When you save, two things happen:

1. Visual upload — If you drew a sketch or uploaded an image, the visual data (SVG or PNG) uploads to Walrus first. Walrus returns a blob ID, which becomes a walrus:// URI.

2. Metadata JSON upload — The editor assembles a JSON document (schema version 1.0.0), embeds the visual URI if present, and uploads to Walrus. The resulting blob ID is the final content identifier.

The on-chain metadata::set_metadata function records this URI against your parcel in the cadastre index. The blockchain stores only the lightweight URI string; all rich content lives on Walrus.

Walrus also supports ipfs:// and https:// URIs, so metadata from external tools using those storage networks is equally valid.