Metadata & Naming
Metadata is how you give your parcel an identity. Add a name, a description, a hand-drawn sketch, or an uploaded image to transform an anonymous polygon into a recognizable place that visitors can discover and remember.
Everything you attach is stored off-chain on the Walrus decentralized storage network and referenced by a URI on the Sui blockchain. Your metadata is censorship-resistant, verifiable, and permanently linked to your ownership record without bloating on-chain storage.
Metadata Schema at a Glance
The metadata JSON follows schema version 1.0.0. Only schema_version is required; every other field is optional, letting you enrich a parcel incrementally.
Opening the Metadata Editor
Select a parcel you own on the map and click Edit Metadata in the detail panel. A full-screen editor overlay opens with your parcel on a dedicated map view, a sidebar metadata form, and a bottom toolbar for visual editing.
Close the editor with Escape or Cancel. No changes are saved until you explicitly confirm.
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.
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.
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, uploads to Walrus, and is referenced in your metadata's svg field.
Sketches have no prescribed purpose. Mark building footprints, trace pathways, highlight features, or sign your name.
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.
Label Coordinate
For city-level parcels (rank 2), the editor exposes a Label Coordinate field. Pick a specific point on the map where the parcel's name label should appear.
Click Pick on Map, then click the desired location. The latitude and longitude are stored in the label metadata field. Helpful for large or irregular parcels where the geometric center is not the ideal label spot. Clear the coordinate to fall back to automatic placement.
Points of Interest
The metadata schema supports Points of Interest (POIs) — named, geolocated markers within or near your parcel. Each POI has an identifier, display name, coordinate, and optional icon type and description.
POIs live in the pois metadata field, up to 50 entries per parcel. They are useful at city, district, and block levels to mark entrances, landmarks, transit stops, or other features. Descriptions are capped at 512 characters each.
The current editor UI focuses on name, description, and visual overlays. POIs can be added by editing the metadata JSON directly or through future editor updates.
Storage
The following diagram shows the full upload pipeline from visual content to on-chain record:
When you save, two things happen:
-
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. -
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.
Saving Changes
Click Save at the bottom of the sidebar. The editor will:
- Validate metadata against the schema (character limits, coordinate ranges, required fields).
- Upload visual content and metadata JSON 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 metadata is live — visible to anyone viewing your parcel.
You can update metadata 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.