v2 state

TokenURI

TokenURI is the skin's image, as a data URI, for a token that exists.

TokenMetadata

TokenMetadata is the skin's metadata as a camelCase JSON string: name, description, externalUrl and attributes of {traitType, value}. No image in it; that is TokenURI.

skinOfTID

externalURL

externalURL is the skin's own page: tokenURIBase plus the token id, on the chain's gnoweb when the base is a path. "#" would start a URL fragment, so it is escaped.

spriteSVG

spriteSVG draws the sprite format DefineSkin validates ("A#rrggbb,..|row|row") as one rect per horizontal run, on a dark matte. It re-checks every rule assertValidArt applies rather than trusting that it ran, and refuses the whole sprite on any fault — a picture with holes in it is worse than an honest placeholder. Colours are emitted only after they are checked to be exactly # and six hex digits, so nothing from the definition reaches the SVG unvalidated.

isHex6

placeholderImage

dataURI

escapeXML

escapeJSON

nameKey

bindingIsLive

bindingIsLive reports whether a token's binding still points at the registration it was made against. Same test ArtForName and Claim already apply; named once so the four copies cannot drift.

grcID

grcID saves every call site from importing grc721 just to cast.

Attach

Attach binds a skin to a name and puts the token into this realm's custody. See the long note in types.gno for why custody rather than a lock in place: it is what makes a marketplace's escrow of the NAME irrelevant to the skin. ONE SKIN, ONE NAME, both ways. A token may be attached to one name, and a name may wear one skin. Letting one copy dress every name a person owns would make the second copy pointless, and the object stops meaning anything.

wear

wear is Attach's body, shared with Buy so that buying and wearing settle in one transaction. Splitting them would let a buyer stop halfway and end up holding a skin they paid for and did not put on.

Refresh

Refresh points a binding's \`binder\` at the name's CURRENT owner. WHY THIS EXISTS, and it is the fix for a real hole. \`binder\` decides who gets the skin back once the name record is gone. Set once at Attach and never updated, it names whoever ATTACHED the skin — so: Alice attaches, sells the name to Bob, the skin travels with it as intended, Bob lets the name lapse, and the skin goes back to ALICE. Bob paid for it. That is not a limitation, it is taking something from the person who bought it. nsdata cannot tell us a name changed hands — it is permanent, it has no hook, and it never will. So \`binder\` cannot be maintained; it can only be CAUGHT UP. This is that, and it is deliberately open to anyone: it only ever writes the name's real current owner, so calling it can never move the skin anywhere it should not go, and there is nothing to gain by calling it on somebody else's binding which means the site can call it on a purchase, a keeper can call it on a schedule, the buyer can call it themselves, or nobody calls it at all and the next Attach or Claim does it — all with the same result and none of them needing to be trusted Nothing on chain is automatic here. gno has no scheduler and nsdata has no callback, so every version of "the skin follows the sale" is one extra call by someone. Making that call safe for ANYONE to make is as close to automatic as this can get, and it is close enough.

refresh

refresh is Refresh without the realm ceremony, for the callers below.

claimEntitled

claimEntitled is Claim's rule on its own, with the record handed in (exists false and zeros when the record is gone), so it can be tested without a registry under it. A live, FROZEN registration is refused outright: the admin freezes a stolen or disputed name so nothing moves while it is sorted out, and its skin used to be claimable and sellable all the same (re-audit 2026-10-16, L-5). The record's frozen bit, not the ledger's holds, so a free-tier name's skin still travels.

Claim

Claim takes a skin out of custody and into the caller's wallet. WHO MAY, and this is the whole travels-with-the-name rule: the CURRENT OWNER of the name, while the name record still exists. Buy the name, claim the skin — including a name bought from someone else, which is the point. the LAST KNOWN NAME OWNER, once the record is gone entirely. That is the "it comes back to your wallet when the name expires" case — and "last known" rather than "whoever attached it", because after a sale those are different people and only one of them paid for it. See Refresh above for how that is kept current without a hook nsdata does not have. The binding is pinned to one REGISTRATION. If a name lapsed and somebody else registered it, its timestamp has changed, so the new registrant is not the owner of anything here and cannot claim.

SkinOnName

SkinOnName returns the token currently worn by a name, or "".

BindingOf

ugnot

Buy

BUYING ONE, AND WEARING IT, IN A SINGLE TRANSACTION. Splitting these would mean a buyer signs twice and can stop between — leaving a skin they paid for sitting unworn in a wallet, which is the state nobody wants and the one a two-step flow produces most often. So the name is an argument: pass it and the skin is minted and attached together; pass "" and it is minted loose, which is what somebody buying ahead of registering a name needs. NOTHING IS EVER HELD. Payment, treasury and refund all settle inside the buyer's own transaction, exactly as nslogic does it — and for the same reason, which is worth restating because it is a legal position rather than a style: a realm you can have a BALANCE in is a different kind of thing to operate, subject to different rules, run by people with licences. Every ugnot that arrives leaves again in the same call. THE 70/30 SPLIT IS NOT HERE, and that is deliberate rather than forgotten. Every skin in this collection is ours, so the artist and the treasury are the same address and a split would move money from a pocket to itself while costing gas to do it. The artist is recorded on every definition so the day it stops being us, this is where the split goes — see SKINS.md.

SetPrice

SetPrice sets the BASE price, in ugnot — what a design costs when the rule has not made it free and no admin has priced it by hand. ugnot because that is what the chain moves: what it is worth in anything else is a question for the page that quotes it, and pinning a dollar figure into a contract that cannot see an exchange rate would be a lie with a number in it.

GetPrice

assertNoSend

Free calls must not be able to strand coins here. This realm has no withdrawal path, so anything attached to one would sit in its address permanently.

init.26

freeShare

The threshold, out of a hundred, under which a hashed id is free. THIRTY-FIVE, NOT THIRTY, AND THE FOUR-POINT GAP IS THE HONEST PART. The rule is a statement about ids, not a quota, so any particular collection lands near the threshold rather than on it — sixty ids at a threshold of thirty came out at thirteen, which is twenty-one per cent and not the third that was asked for. Thirty-five puts the launch batch at eighteen, which is thirty per cent exactly. So the constant was chosen to fit the collection that exists. That is worth saying plainly rather than dressing up: what it buys is that every FUTURE id still gets an answer nobody can lobby for, which is the property that mattered, while the batch on sale today is the share that was promised. A constant rather than a stored value, because changing it would silently reprice every skin nobody has overridden — including ones people have already been shown a price for. That should cost a deploy.

priceOverride

// definition id -> int64 ugnot

freeByRule

freeByRule is FNV-1a over the id, taken modulo one hundred. freeShare of every hundred ids fall under the threshold, so the share lands NEAR it rather than on it for any particular collection — see the note on the constant. The launch batch of sixty comes out at eighteen, and ListFreeSkins says so rather than asking anyone to trust the arithmetic. The same hash is in nsview.faceForArt, deliberately not shared: one runs over a sprite and one over an id, they answer different questions, and a helper spanning both realms would be a dependency between them for four lines of arithmetic.

IsFreeByRule

IsFreeByRule reports what the rule alone says, ignoring any override. Exposed so an admin panel can show what it would revert to.

HasPriceOverride

HasPriceOverride reports whether this id has been priced by hand. A panel needs it to tell "set to zero" from "free by the rule", which look identical in the price alone and are different decisions.

PriceOf

PriceOf is what this design costs right now, in ugnot. It does NOT check that the id exists: a price for a definition that is not there is meaningless rather than wrong, and Buy is the thing that must refuse an unknown id — which it already does, by name, before it ever asks what the price is.

SetSkinPrice

SetSkinPrice prices one design by hand, overriding the rule. Zero is a legitimate value and is NOT the same as removing the override: it says "this one is free because I said so", which survives a change to the base price and to the rule. ClearSkinPrice is how you go back to being unopinionated.

setSkinPrice

setSkinPrice is SetSkinPrice without the realm ceremony. Split for the same reason attach.gno splits refresh from Refresh: the rules are worth testing on their own, and the gate above them is the same assertIsAdmin every other write in this realm goes through.

ClearSkinPrice

ClearSkinPrice drops an override, putting the design back under the rule and the base price.

clearSkinPrice

SetSkinPrices

SetSkinPrices prices many designs in one call. A panel that lets somebody retune a collection produces a batch of changes, and sixty separate transactions is sixty flat fees for what is one decision. Same encoding as AllSkins reads back — tab between the id and the price, newline between records — so the two halves of the panel speak one format. An empty price field CLEARS the override rather than setting zero. The panel shows an empty box for "no opinion" and a 0 for "free on purpose", and those must not collapse into each other on the way here.

setSkinPrices

parseU64

parseU64 is strconv.ParseInt without the import, and without accepting a sign — every price here is a non-negative amount of ugnot, and "-0" or "+5" arriving from a form should be refused rather than guessed at.

ListFreeSkins

ListFreeSkins names every definition that costs nothing right now, counting overrides — so it answers "what can I have for free", which is the question, rather than "what does the rule say", which is trivia.

AllPrices

AllPrices is every id and its price, for a shop that wants the lot in one read. AllSkins carries the price too; this exists for a panel that wants prices without the rest and for checking the two agree.

ArtForName

ArtForName is the one question the renderer asks, and it is answered here so the rule lives with the data it depends on. It returns the sprite a name should be drawn with, or "" for the ordinary card. Everything the renderer would otherwise have to remember to check is inside it, because a renderer that has to remember three things before drawing is one that eventually forgets one. The checks, and what each of them makes self-cleaning: the name wears a token at all that token's definition has not been WITHDRAWN — so a takedown reverts every name wearing it, everywhere, at once, with no migration and no per-name cleanup the binding is FRESH, pinned to this registration — so a name that lapsed and was taken by somebody else inherits nothing the LOCK still matches — belt and braces, since Attach checks it too Note what is NOT checked: who holds the token in their wallet. Nobody does. It is in this realm's custody for as long as it is attached, which is what makes the skin travel with the name instead of with a wallet.

SkinInfo

SkinExists

ListSkins

ListSkins returns every definition id, in tree order. Small by construction — this is a curated shop, not a submission firehose — and if that ever stops being true it wants paging rather than a bigger answer.

AllSkins

AllSkins packs the whole catalogue into ONE read. A shop page needs every definition's name, lock and availability, and asking for them one at a time is sixty round trips before anything appears on screen. The ART is deliberately NOT here: it is the bulk of the data, it is committed in the repo as the canonical source, and a page that already has it does not need to fetch it again. Six fields: id, name, lock, withdrawn, minted, price in ugnot. Tab-separated fields, newline-separated records — not JSON, because building JSON by string concatenation in a realm is how quoting bugs get shipped, and a shop is not worth that risk. No field can contain a tab or a newline: ids and locks are \[a-z0-9-] by rule, and a name is checked here rather than assumed.

skinOfToken

SkinOfToken

SkinOfToken is skinOfToken for callers outside the realm.

GetAdmin

GetTokenURIBase

IsTrustedShop

Name

Symbol

GetName

GetSymbol

TokenCount

TotalSupply

ID

ID is the collection id wallets and indexers key on: "\<this realm's path>.MNSKIN.0000000".

BalanceOf

OwnerOf

GetApproved

IsApprovedForAll

skin

binding

A live attachment. \`registered\` pins it to one REGISTRATION of the name, not to the label: if the name lapses and somebody else takes it, the timestamp changes and this binding is stale, so the new registrant inherits nothing.

token

ledger

skins

// definition id -> \*skin

tokenSkin

bound

// token id -> \*binding

nameBound

// "domain\*label" -> token id

tokenURIBase

admin

trustedShop

price

maxSkinName

maxSkinArt

// a 32x32 sprite is about 1,100 bytes

maxSkinID

// appears in every token id and every binding

assertIsAdmin

assertIsAdminOrShop

DefineSkin

DefineSkin registers a design. It does not mint anything. Definitions and copies are separate calls on purpose: defining is the expensive, careful, one-off act that puts an artist's work and a sprite on chain, while minting is the cheap repeated one. Rolling them together would mean re-sending the artwork with every sale. A definition may be REDEFINED only while nothing has been minted from it. After the first copy exists, the art is what its holders bought and it stops being ours to edit — the only lever left is withdrawal, which is honest about what it is doing.

Mint

Mint issues one copy of a definition to somebody. The serial is the definition's own running count, so token ids read as "ember#1", "ember#2". Never reused: the counter only goes up, even across burns, because a reissued id would let a new token inherit whatever an old one was pointed at.

Withdraw

Withdraw is the takedown control, and SKINS.md §6 makes it non-negotiable: it has to exist before a single outside submission is accepted, which means it has to exist now, while there is nothing to take down and it is cheap to build. Somebody will submit a character somebody else owns, or a bank's logo, or something vile, and it will render inside other people's wallets with our name beside it. When that happens the fix has to be one call, not a migration. It does NOT burn anything. The holder keeps the token; it simply stops rendering, and every name pointing at it falls back to the ordinary card at once. Burning somebody's property to solve our problem is a different act with different consequences, and it is not this one.

SetTokenURIBase

SetAdmin

TrustShop

TransferFrom

Approve

SetApprovalForAll

mustSkin

assertValidID

An id goes into every token id and into the pointer a name stores, so it has to survive being split on "#" and compared byte for byte.

assertValidLabel

assertValidArt

assertValidArt mirrors the sprite checks nsview makes, and it is here for one reason: nsview REJECTS THE WHOLE SPRITE SILENTLY. A malformed skin does not draw a broken picture, it draws nothing at all, with no error anywhere a person would see it. Storing one would mean selling somebody a blank card and finding out weeks later. So the shape is checked at the point of storage, where the failure is a panic in a transaction nobody has paid for yet. Deliberately checks the SHAPE and not the rendering. This realm does not know how a card is composed and should not learn — that is the whole reason the renderer is swappable.