v5 state

saleFeeRecipient

// gnotchi-opponent, v4's choice

saleFeeRateBps

// 5% of the declared price

saleFeeFloorUgnot

// 1 GNOT flat minimum per sale

collectionName

collectionSymbol

adminAddress

numEyes

numNoses

hourSeconds

daySeconds

numPlots

// acorns.plots

plantCost

// acorns.plantCost

feedCost

// acorns.feedCost

acornsStart

meterMax

patCheer

hungryAtOrBelow

growHours

patCooldownHours

tinkerCost

levelBase

levelStep

sulkyPenaltyPct

harvestPerPlot

feedBelly

bellyDropEveryHours

cheerDropEveryHours

dailyCareCap

acornReserve

happyBonusPct

happyWindowHours

sulkyAfterHours

maxLevel

typeAtLevel

xpPat

xpFeed

xpHarvestPerPlot

xpTinkerTask

maxActionsPerCall

maxBackfillHours

caredWindowDays

maxGnomesPageSize

maxListingsPageSize

ugnotDenom

maxPriceUgnot

maxFeeRateBps

maxListingDays

moodHungry

moodSulky

moodHappy

moodContent

actionPat

actionFeed

actionPlant

actionHarvest

actionTinker

typeGardener

typeExplorer

typeTinkerer

batchCap

numNamedEditions

lockCaredDays

pinOffsetSeconds

pinOffsetRounds

pinOffsetRounds is a const expression over an imported const (beacon.PeriodSeconds), which Gno permits across package boundaries exactly as it would within one; TestPinOffsetIsTwentyRounds pins the arithmetic rather than trusting the comment above.

hatOptions

hatOptions / coatOptions: v4's validHats/validCoats catalogue, as an ORDERED array rather than a set, because Settle needs to draw a POSITION, not merely validate one. Order is frozen the moment this realm deploys, exactly as v4's own numEyes/numNoses ordering is frozen -- a part may be redrawn; it may never be reordered, removed or renumbered (v4's own comment on this).

coatOptions

eyesWeights

eyesWeights: ECONOMY.md section 3, verbatim -- "eyes across 4 colours at 15%, 3 at 9%, 2 at 5%, 1 at 3%" -- 4+3+2+1 = 10 entries = numEyes, and 4\*15+3\*9+2\*5+1\*3 = 100. TestWeightTablesSumToOneHundred pins the sum rather than trusting the arithmetic in this comment; drawWeighted's own fallback additionally makes a drift here fail safe, not silently.

noseWeights

noseWeights: ECONOMY.md section 3 says only "nose similar across 8 shapes" and gives no exact percentages -- BATCH-ONE.md section 4a names this directly as real work nobody has done yet. This is a SHAPE-FAITHFUL INTERPRETATION, not a transcription: four tiers of two shapes each, 20/20/15/15/10/10/5/5, the same big-gap-then-smaller-gaps shape eyesWeights has, scaled to 8 entries and summing to 100. Flagged here, not quietly presented as sourced, so the owner or a future author can replace it with real numbers the moment ECONOMY.md section 3 gets them.

namedEditionOrder

namedEditionOrder: BATCH-ONE.md section 7's three names, in the fixed order Settle's namedPick indexes into. The order carries no meaning -- it is not a ranking -- it only has to be fixed, which it is, forever, the moment this realm deploys.

genesisGnomeName

genesisGnomeName: DECISIONS.md 2026-10-15 settles the MECHANISM (minted to this realm's own address, non-transferable, never listable, separate from the batch) but never settles a NAME anywhere in this project's documents. Placeholder, named as one; change it freely before deploying, it is read by nothing else in this file.

plot

plot: unchanged from v4. plantedAt == 0 is the empty state; readyAt is stored, not computed, so a future change to growHours (there is none possible in this file, but the shape is kept for the day a v6 adds tuning back) could never reach backwards into an already-planted plot.

gnome

gnome is the whole persisted pet. EVERY FIELD HERE HAS AN EXPORTED READER -- v4's own rule, carried over verbatim: a realm cannot grow a second chance at this after deploy. NOT HERE, DELIBERATELY: a name (see the package doc's "out of scope" section) and a hat/coat the OWNER chose (nothing is chosen any more; hat/coat are ROLLED exactly as eyes/nose are, and are exactly as permanent as eyes/nose always were in v4 -- there has never been a function anywhere in this family of realms that changes a gnome's hat or coat after mint). character is "" for every ordinary gnome and one of namedEditionOrder's three strings for a named one-of-one. eyes/nose/hat/coat are the sentinel -1/-1/""/"" for a named edition: its look is NOT a point in the ordinary 1,280-look space, it is BATCH-ONE.md section 6's own new art (Hob's crown and gold coat, Thistle's helmet and axe, Wick's lantern), which this contract does not need to know the pixels of -- only that Character(tokenID) names it, so the app can render the right thing. A named edition's parts are therefore never counted in eyesCounts/noseCounts/hatCounts/coatCounts: it is already as rare as a thing can be, at cap one, counted instead through characterOwner.

listing

listing: unchanged in shape from v4, now simply one of possibly SEVERAL a single owner may have standing at once (mint one, hold many) -- listings is still keyed by tokenID, which was always the right key for this and needed no change.

feeConfig

feeConfig: unchanged from v4.

pendingClaim

pendingClaim is the record Claim writes and Settle consumes: the permanent, irrevocable fact that this address spent its one roll, and the future drand round it is waiting on.

token

ledger

nextID

gnomes

// tokenID -> \*gnome

ownerTokens

activeToken

lastWakeDay

lastCaredDayForOwner

balances

// owner address -> int64 acorns, per PLAYER, exactly as v4

listings

// tokenID -> \*listing

allowlist

hasRolled

pendingClaims

eyesCounts

noseCounts

hatCounts

coatCounts

characterOwner

mintedCount

// reservations made by Claim, gates batchCap; never decremented

settledCount

// completions made by Settle; informational only, see BatchStatus

genesisTokenID

// set exactly once, in init()

rulesFrozen

// always true: there are no rules to freeze or unfreeze in v5. See AdminState.

fee

transferGate

init.99

assertFeeConfig

assertFeeConfig: unchanged from v4's own gate.

saleGateExtension

saleGateExtension: v4's shape, plus the genesis refusal. Panics on every transfer except the one Buy is performing right now, and ALWAYS panics for genesisTokenID regardless of transferGate -- there is no path, including a future bug in Buy, by which the genesis gnome should ever be transferable, so this checks it first and unconditionally.

AdminAllow

AdminAllow adds addr to the allowlist, so it may call Claim. Adding an address a second time is a harmless no-op. Adding an address that has already rolled changes nothing -- hasRolled is checked independently and is permanent regardless of allowlist state.

AdminDisallow

AdminDisallow removes addr from the allowlist. It does NOT, and cannot, undo a roll already spent: hasRolled is a separate, permanent record, and this function never touches it. Removing an address that was never allowed, or that has already claimed, is a harmless no-op.

Claim

Claim spends the caller's one-and-only roll on this realm and pins a drand round that does not exist yet. It mints NOTHING -- Settle does that, once the pinned round is actually published -- because the whole point of this split is that the result must not be computable, by anyone, including this transaction's own caller, at the moment the roll becomes irrevocable (MINT.md section 10.2: gno.land has no on-chain entropy at all, so anything decidable inside one transaction is decidable by the caller before broadcasting it). WALLET-ONLY, the same reasoning as v4's Adopt: a gnome minted to a realm's address could never be recovered, so a batching, sponsor or multicall realm must never be able to spend a roll on anyone's behalf. The \`gnokey maketx run\` shape is refused by the identical gate, for the identical reason (IsUserCall is false for both).

pendingClaimFor

pendingClaimFor looks up claimant's pending roll, shared by both Settle and SettleWithSignature so the "no pending claim" message and lookup logic exist exactly once.

Settle

Settle computes and permanently mints the result of claimant's pending roll, once the round Claim pinned has actually been published to the beacon by SOMEBODY -- another claimant's own SettleWithSignature, a relay, anyone. It does not publish anything itself; call SettleWithSignature instead if the round is not published yet and the caller has its signature to offer. ANYONE may call this -- the claimant themself, the project's own relayer, a stranger -- because by the time it can succeed at all, nothing is left to decide: the drand signature for the pinned round either exists publicly or it does not, and the parts this mints are a pure function of (that signature, the claimant's own address), fixed the instant the round is published, not the instant Settle happens to be called. Simulating this call before calling it for real previews a fact, not a choice -- exactly the property MINT.md section 10.5 names as the whole fix: "reading the result afterward is a free query, same as any other realm read." Refuses coins for the same reason every other non-paying function here does: there is no banker to return them, and this is a free, permissionless computation, never a payment.

SettleWithSignature

SettleWithSignature is Settle, plus: if claimant's pinned round has not been published yet, this function publishes it ITSELF first, in this same transaction, using sigHex -- the round's drand signature, which the caller's own app fetches read-only from drand's public API ([https://api.drand.sh/](https://api.drand.sh/)\<chain>/public/\<round> or any mirror) and passes straight through unmodified. This is the function a player's app should call once it has fetched a signature; Settle (above) remains for a caller with no signature to offer, or that already knows (or does not care) that somebody else has published the round. SAFE EITHER WAY THE ROUND TURNS OUT TO BE, which is the one property this function exists to guarantee and the live chain fact its shape is built around (see the package doc): beacon/v2's own Publish PANICS, not no-ops, when the round is already published, so this function checks beacon.Published first and only calls Publish if that check says no. If the round was published by someone else (another claimant's own SettleWithSignature, a relay, anyone) between the moment the caller fetched sigHex and the moment this transaction lands, sigHex is simply never used -- this function still succeeds, exactly as Settle would have. A bad sigHex, by contrast, is a real failure: beacon.Publish rejects it with its own "beacon: invalid signature" panic, which aborts this whole call (and the claim stays pending, to be retried with a correct signature or left for Settle once someone else relays it). Refuses coins for the same reason Settle does and every non-paying function here does: there is no banker to return them, and this is a free, permissionless computation -- the only payment anywhere in this call is the ordinary GNOT gas the caller's own transaction spends, to the network, never to this project (MINT.md section 14).

settleCore

settleCore is Settle's and SettleWithSignature's shared tail: the draw, the mint, and every write that follows, once the caller above has already confirmed the pinned round is published. Takes no \`cur realm\` because it makes no cross-realm call of its own -- beacon.Randomness and beacon.Published below are plain reads, not crossing functions, exactly as they always were before this change.

fnv64a

fnv64a is a plain, non-cryptographic 64-bit FNV-1a hash. IT IS NOT THE SOURCE OF UNPREDICTABILITY HERE -- drand's signature for a not-yet-existent round is, exactly as MINT.md section 10.5 designs. This exists only to DECORRELATE independent draws (two different claimants sharing a pinned round, or one claimant's own eyes-draw from their own nose-draw) from a single public drand value, the same category of use math/rand's PCG(0,0) would be fine for once combined with a secure external seed -- see MINT.md section 10.5's own list of unsafe constructions for why math/rand ALONE is not used, and note this is never alone: every call site below mixes in beacon.Randomness(pc.round), which is the only thing doing real work.

seedFor

seedFor derives one independent-looking 64-bit value from the published drand randomness, the claimant's own address, and a purpose string -- so a single drand round can safely drive several unrelated draws (which named edition, which eyes, which nose, which hat/coat) for several different simultaneous claimants without any of them correlating with each other.

drawWeighted

drawWeighted picks an index into weights (which TestWeightTablesSumToOneHundred pins as summing to totalWeight) using seed as the source of randomness -- a plain cumulative-sum bucket walk, MINT.md section 10.5's own recommendation for what Settle should do ("a simple, bounded index... easy to audit"), applied to a weight table instead of a published array, which is the same shape of arithmetic.

Wake

Wake makes tokenID the caller's awake gnome. Free, and limited to once per UTC day -- the same day-boundary discipline SaveDay's own dailyCareDay already uses, chosen over a GNOT fee for the reason MINT.md section 2a gives: "a cost that cannot be bought, only lived".

saveAction

SaveDay

ChooseType

List

List offers tokenID, which the caller must own, for sale. The lock: a named one-of-one (character != "") cannot be listed until it has lockCaredDays cared days; an ordinary gnome has no such restriction, trading from the moment it is minted (MINT.md section 12/13).

Cancel

Cancel withdraws the caller's own listing on tokenID. Only the seller who created it may.

Buy

Buy purchases the listed gnome tokenID. v4's validate-then-commit shape, unchanged, MINUS the one-gnome-per-address refusal: MINT.md section 2a removes the hold cap from Buy specifically, and only from Buy -- Claim's hasRolled gate is the cap that still matters, and this function never touches it.

Listing

TotalListings

ListingsPage

QuoteFee

FeeRules

Provenance

GnomeByToken

GnomeByToken: the basic facts for one token -- hat, coat, eyes, nose, character (empty for an ordinary gnome), level, calling and the moment it was minted.

ActiveGnome

ActiveGnome returns the tokenID that is awake for addr right now, or found=false if nothing is (never claimed or bought a gnome, or sold the only one and has not Woken another since).

OwnerTokens

OwnerTokens returns every tokenID addr currently holds, in no particular order. Unbounded and unpaginated deliberately: batchCap is 24 and the genesis gnome is permanently unreachable to any wallet, so no address can ever hold more than batchCap tokens, which is a small, fixed upper bound this call is always safely within.

TokensPage

TokensPage: the global token enumerator, hollowmere/v1's own pattern (TotalClaimants/ ClaimantsPage) applied here, because v4's own missing-enumerator lesson (DECISIONS.md:780-791, arena/v1 shipping with no challenge inbox and no way to ever add one) is unavailable to fix after deploy and twenty lines now is cheaper than "unavailable forever" later.

GardenState

CareState

MeterState

Progress

CaredDays

Mood

IsLocked

IsLocked reports whether tokenID is currently refused by List's lockCaredDays check -- true only for a named one-of-one with fewer than lockCaredDays cared days; false for every ordinary gnome, always, and false for a named one-of-one once it has enough cared days.

CollectionInfo

TotalSupply

BalanceOf

OwnerOfToken

TotalGnomes

Acorns

EyesCount

NoseCount

HatCount

CoatCount

CharacterOwner

CharacterOwner resolves one of the three named one-of-ones, or the genesis gnome under its own name "genesis", to its tokenID, once minted. (Second-audit-pass nitpick: an earlier version of this comment said only "one of the three named one-of-ones", which stopped being true the moment init() registered "genesis" here too -- see init()'s own comment for why that registration is safe and never touches the three editions' cap.)

IsAllowlisted

HasRolled

PendingClaim

BatchStatus

BatchStatus: mintedCount is reservations made by Claim (gates batchCap); settledCount is completions made by Settle (always \<= mintedCount, the gap being pending, unsettled claims); namedMinted is how many of the three named one-of-ones have actually been minted so far -- read live off characterOwner rather than a separate counter, so there is only ever one source of truth for "has this edition been taken".

GenesisTokenID

AdminState

LastWakeDay

Render

gnomeByTokenID

activeGnomeForAddr

activeGnomeForAddr resolves addr's AWAKE gnome, if any. This is the one and only lookup SaveDay and ChooseType use -- there is deliberately no "the gnome for this address" any more.

ownerOfToken

addOwnerToken

addOwnerToken / removeOwnerToken: the hold-many index. ownerTokens stores a \*\[]string per owner so repeated appends mutate one allocation rather than replacing the tree entry every time; removal does a linear scan, which is fine at this realm's permanent, tiny upper bound (batchCap = 24 tokens that will ever exist, minus the one permanently unreachable genesis gnome, so no owner's slice is ever longer than 24 entries for the whole life of this realm).

removeOwnerToken

balanceOf

setBalance

grantStartingPurseIfNew

feeFor

exactUgnot

coinsString

listingFor

lowerASCII

lowerASCII: v4's own helper, unchanged -- ASCII-only on purpose (see v4's own comment on why not strings.ToLower).

anyPlotPlanted

eyesCount

noseCount

hatCount

coatCount

parseActions

quoteAction

parseUnixField

parsePlotField

dayNumber

recordCaredDay

recordCaredDay reports, via banked, whether it actually incremented g.caredDayCount -- false on the no-op branch (day == g.lastCaredDay already, e.g. a second SaveDay call the same UTC day, or a token bought mid-day that the SELLER had already banked that exact day for before the sale). SaveDay's own caller-scoped gate (lastCaredDayForOwner) depends on this: it must only spend the owner's one-bank-per-day allowance on a call that actually banked something, never on a no-op -- a gno-auditor re-audit found that an unconditional advance let a buyer's SaveDay on a token the seller had already banked that day silently consume the buyer's own allowance for the rest of that day, denying an otherwise fully legitimate cared day on a DIFFERENT, genuinely active token later the same day. See the call site in SaveDay.

caredDaysCsv

meterNow

clampMeter

canPat

moodNow

xpToNext

totalXpForLevel

levelFromXp