core state

admin

Admin (design §2.5.2, §7.5). The admin can only change the parameters listed in validateOp, each inside a hard cap, after a public timelock; it can pause new activity for a bounded time. It can never move, approve or burn a token, touch a collection's configuration, or receive funds (I-1). With no collection yet there is nothing to protect, so ops execute without delay — that is how the platform is configured after deploy. TODO(mainnet): the initial admin and treasury must be the 2/3 multisig. SA-I6: CreateFee starts at 0 here so tests and bootstrap stay simple; scripts/deploy-onyx.sh sets a non-zero fee.create during bootstrap.

pendingAdmin

Admin (design §2.5.2, §7.5). The admin can only change the parameters listed in validateOp, each inside a hard cap, after a public timelock; it can pause new activity for a bounded time. It can never move, approve or burn a token, touch a collection's configuration, or receive funds (I-1). With no collection yet there is nothing to protect, so ops execute without delay — that is how the platform is configured after deploy. TODO(mainnet): the initial admin and treasury must be the 2/3 multisig. SA-I6: CreateFee starts at 0 here so tests and bootstrap stay simple; scripts/deploy-onyx.sh sets a non-zero fee.create during bootstrap.

fees

Admin (design §2.5.2, §7.5). The admin can only change the parameters listed in validateOp, each inside a hard cap, after a public timelock; it can pause new activity for a bounded time. It can never move, approve or burn a token, touch a collection's configuration, or receive funds (I-1). With no collection yet there is nothing to protect, so ops execute without delay — that is how the platform is configured after deploy. TODO(mainnet): the initial admin and treasury must be the 2/3 multisig. SA-I6: CreateFee starts at 0 here so tests and bootstrap stay simple; scripts/deploy-onyx.sh sets a non-zero fee.create during bootstrap.

beacon

Admin (design §2.5.2, §7.5). The admin can only change the parameters listed in validateOp, each inside a hard cap, after a public timelock; it can pause new activity for a bounded time. It can never move, approve or burn a token, touch a collection's configuration, or receive funds (I-1). With no collection yet there is nothing to protect, so ops execute without delay — that is how the platform is configured after deploy. TODO(mainnet): the initial admin and treasury must be the 2/3 multisig. SA-I6: CreateFee starts at 0 here so tests and bootstrap stay simple; scripts/deploy-onyx.sh sets a non-zero fee.create during bootstrap.

minters

// minter pkgpath -> \*minterRecord

ops

// safe.PadInt(op id) -> \*pendingOp

opCount

Admin (design §2.5.2, §7.5). The admin can only change the parameters listed in validateOp, each inside a hard cap, after a public timelock; it can pause new activity for a bounded time. It can never move, approve or burn a token, touch a collection's configuration, or receive funds (I-1). With no collection yet there is nothing to protect, so ops execute without delay — that is how the platform is configured after deploy. TODO(mainnet): the initial admin and treasury must be the 2/3 multisig. SA-I6: CreateFee starts at 0 here so tests and bootstrap stay simple; scripts/deploy-onyx.sh sets a non-zero fee.create during bootstrap.

pauses

// scope -> \*pauseRecord

pauseRecord

pauseRecord is one scope's pause and its budget (SA-L2): within a window of PauseWindowBlocks a scope can be paused for at most MaxPauseBlocks in total; a pause cannot be renewed while it runs. Worst case two budgets meet at a window boundary (\<= 2 x MaxPauseBlocks in a row), never more.

minterRecord

pendingOp

OpFeeCreate

// ugnot, \<= CreateFeeCap

OpFeePrimary

// bps, \<= ProtocolFeeCapBps

OpFeeSecondary

// bps, \<= ProtocolFeeCapBps

OpTreasury

// address

OpBeacon

// address, or "" to disable new beacon launches

OpMinterAdd

// realm pkgpath

OpMinterDeprecate

// realm pkgpath: no new collections

OpEngineReview

// engine id: reviewed badge (UI only)

OpAdminTransfer

// address; the new admin must AcceptAdmin

pauseScopes

ProposeOp

ExecuteOp

ExecuteOp applies a proposed op once its timelock has passed. The delay is judged at execution, so an op proposed during bootstrap still waits the full timelock if a collection appeared in the meantime.

CancelOp

AcceptAdmin

Pause

Pause stops new activity in one scope for the rest of its budget (at most MaxPauseBlocks per PauseWindowBlocks). It never blocks exits (I-2) and cannot be renewed while it runs (SA-L2).

Unpause

Unpause ends a pause early and gives the unused blocks back to the budget.

pauseOf

Paused

Paused reports whether scope ("create", "mint", "trade") is paused now.

PauseBudget

PauseBudget is the scope's pause record as JSON: {until, used, windowStart, windowEnd, left}.

assertNotPaused

assertScope

assertAdmin

bootstrapping

earliestExecution

mustOp

validateOp

validateOp is the closed list of admin powers (I-1).

applyOp

assertActiveMinter

parseAmount

CreateCollection

CreateCollection stores a Draft collection and returns its id. Nobody can mint a Draft, so a creator can configure phases across several messages without a race (OA B2).

Launch

Launch freezes the configuration (I-6): sale window, reveal window and the creator's commitment. The sale must start in the future so a beacon can commit before the first mint.

AbortLaunch

AbortLaunch returns a launched collection to Draft while nothing has been minted — the way out when a beacon never commits. A commitment whose secret was revealed is burned for this collection; unrevealed ones (the beacon's deterministic one included) may be committed again (SA-L1).

ReserveTo

ReserveTo mints the creator's reserve before the sale starts. Reserve mints feed the entropy like any mint, appear in Provenance, and do not count toward wallet caps.

MintTo

MintTo mints n tokens during the sale. The minter has already checked phase, price, allowlist and wallet cap; core re-checks only what it owns: state, supply, beacon commitment, and the lifetime counter (I-5, I-9).

assertMintCount

mintBatchTo

mintBatchTo is the only place tokens come into existence.

mintedBy

CloseMint

CloseMint materializes Closed once the sale window has passed. Anyone may call it; reveals and Finalize work without it.

TransferCreator

TransferCreator starts a two-step handover (RA M-11).

AcceptCreator

SetPayees

SetPayees changes the royalty split after Final. The primary-sale split is frozen with the sale (I-6); the royalty receiver stays the collection's sub-treasury, so third-party markets are unaffected. Royalties earned so far are first paid to the current payees (SA-I4).

assertPayees

assertPayees refuses payees that can never spend what they receive (SA-L5): the platform's own realms and sub-addresses. cid is the collection being configured, engineID its engine adapter.

assertSpendable

assertSpendable panics for core, core's sub-addresses of collection cid (token identity c/\<cid>, royalty treasury roy/\<cid>), every minter ever approved, the engine adapter, and the platform realms next to core (market, reader, gallery, the genesis adapter). None of them has a path that spends an incoming payment, so the coins would be stranded (I-3).

platformRealms

platformRealms are the realm paths next to core (README package map).

assertCreator

assertBoundMinter

boolStr

ProtocolFeeCapBps

// 5% of any sale

RoyaltyCapBps

// 10% (RA M-3)

CreateFeeCap

// 1,000 GNOT in ugnot

MaxPayees

Hard limits. They are constants on purpose: nobody, admin included, can raise them after deploy (block counts assume ~3.54 s blocks, RA M-1).

MaxSupplyCap

Hard limits. They are constants on purpose: nobody, admin included, can raise them after deploy (block counts assume ~3.54 s blocks, RA M-1).

MaxMintPerTx

// hypothesis: measure n=10 gas/deposit on Onyx

MaxReserveBps

// creator reserve \<= 10% of supply

MaxSaleBlocks

// ~30 days

RevealWindowMin

// ~1 hour

RevealWindowMax

// ~7 days

BeaconGraceBlocks

// beacon may reveal first in the window's last ~15 min (\< RevealWindowMin, so the creator always gets to go first)

TimelockBlocks

// ~48 hours

MaxPauseBlocks

// ~8 days: pause budget per scope and window

PauseWindowBlocks

// ~30 days (SA-L2)

MaxNameLen

Hard limits. They are constants on purpose: nobody, admin included, can raise them after deploy (block counts assume ~3.54 s blocks, RA M-1).

MaxDescriptionLen

Hard limits. They are constants on purpose: nobody, admin included, can raise them after deploy (block counts assume ~3.54 s blocks, RA M-1).

MaxParamsLen

Hard limits. They are constants on purpose: nobody, admin included, can raise them after deploy (block counts assume ~3.54 s blocks, RA M-1).

MinSecretLen

Hard limits. They are constants on purpose: nobody, admin included, can raise them after deploy (block counts assume ~3.54 s blocks, RA M-1).

MaxSecretLen

Hard limits. They are constants on purpose: nobody, admin included, can raise them after deploy (block counts assume ~3.54 s blocks, RA M-1).

MaxPageSize

Hard limits. They are constants on purpose: nobody, admin included, can raise them after deploy (block counts assume ~3.54 s blocks, RA M-1).

BadgeBoth

Provenance badges (design §4.3).

BadgeCreatorOnly

Provenance badges (design §4.3).

BadgeBeaconOnly

Provenance badges (design §4.3).

BadgeFallback

Provenance badges (design §4.3).

collection

selfPath

collections

// safe.PadInt(cid) -> \*collection

byCreator

// creator + ":" + padded cid -> cid

collCount

init.87

cidWidth

collKey

mustCollection

stateAt

stateAt is the effective state at height h; the stored state lags until the next write materializes it (refresh).

refresh

revealDeadline

revealDeadline is when anyone may finalize without the missing secrets. It is at most endHeight + RevealWindowMax, which bounds the transfer lock (I-11).

caller

assertNoDeposit

assertNoDeposit refuses coins on functions that take none, so nothing can get stuck in core (RA L-1). The origin-send envelope belongs to the first realm of the call; it is only ours to judge when a wallet called us.

itoa

height

engineRecord

Engine registry ("art as code", design §5). An engine registers itself from its own /r/ adapter realm; its id is that realm's package path, so nobody can register in someone else's name. The stored interface value's methods are declared in the adapter, so every call runs with the adapter's authority, not core's (interrealm v2 borrow rule #1): engine code cannot write core state. It also cannot call back into a core mutator: all of core's state-changing functions are crossing and need a live cur the engine never has. Honest limits, surfaced to users rather than hidden: - an adapter realm with state could change its art later; the sample fingerprint (VerifyEngine) detects a change of the sample, and review means reading the adapter for statelessness; - a private (re-deployable) adapter cannot register: the VM aborts the registration when core's state would retain the private realm's type (spike A9, observed in gno v1.7.0 test mode; confirm on Onyx).

engines

// engine id -> \*engineRecord

engineOrder

// safe.PadInt(seq) -> engine id

engineCount

RegisterEngine

RegisterEngine stores the calling realm's engine (I-12 exception: one sample render in the engine's own registration transaction). The record is immutable afterwards except for the claim/deprecate/review flags.

ClaimEngine

ClaimEngine proves the manifest author controls that address. Unclaimed engines cannot back a collection.

DeprecateEngine

DeprecateEngine stops new collections; existing ones keep rendering.

mustEngine

copyManifest

copyManifest gives core its own copy: the engine's slice was allocated in the engine realm.

RenderWith

RenderWith renders any registered engine for arbitrary params and seed as a data URI — Studio previews and the Verify button.

EngineTraits

EngineTraits returns a core-owned copy of the engine's traits for seed.

TraitsWith

VerifyEngine

VerifyEngine re-renders the sample and compares it with the fingerprint stored at registration.

EngineManifest

EngineManifest is the typed read for other realms (gallery).

EngineStatus

EngineStatus is "unclaimed", "unverified", "reviewed" or "deprecated".

engineStatus

Engine

Engine is the record as JSON.

Engines

writeEngine

studioInput

provenance

Commit–reveal v2 (design §4.2–4.3, closes RA H-3, M-5, M-6). The map is fixed by three inputs: the creator's secret sc, the beacon's secret sb and the public mint-entropy accumulator acc. Neither committer knows the other's secret while minting is open, so neither can time the last mint for a good map. Order of reveals: 1. nothing is accepted before Closed (an early reveal informs the other side); 2. the creator may reveal until revealDeadline - BeaconGraceBlocks; the beacon follows at any time before the deadline; 3. inside the last BeaconGraceBlocks only the beacon may reveal. If the creator stayed silent, the beacon's reveal finalizes at once ("beacon-only"), so the creator never sees sb while it can still choose (SA-M1; this also closes the mempool race of a creator front-running the beacon's grace reveal); 4. after revealDeadline anyone finalizes with whatever was revealed. What stays open, by design: the beacon, as last revealer after the creator, can still choose between revealing and not (one bit). It runs public code and the badge shows the outcome. The transfer lock (tokens.gno) keeps anyone from trading on early knowledge until Final. A collection launched without the beacon (only possible while no beacon is configured, SA-M2) gives the creator the whole choice of the map; it can have no creator reserve and is never reported as a fair launch (FairLaunch, Provenance "fair").

roleCreator

roleBeacon

BeaconCommit

BeaconCommit is the beacon's commitment, before any token exists.

RevealCreatorSecret

RevealBeaconSecret

Finalize

Finalize is permissionless and never paused (I-2): immediately once every expected secret is revealed, otherwise after revealDeadline (fallback).

assertRevealOpen

assertSecret

revealsComplete

finalize

finalize runs at most once per collection (I-10): every caller checks state Closed, and this sets Final.

VerifyProvenance

VerifyProvenance recomputes every commitment and the salt from public data. True only for a Final collection whose record is consistent.

FairLaunch

FairLaunch is true only for a Final, consistent collection whose map no single party could choose: launched with the beacon and finalized with both secrets or with the beacon's alone (after the creator stayed silent). Creator-only collections (no beacon: the creator alone knew the only secret and could steer the last mint, SA-M2) and fallbacks are not fair launches, even when VerifyProvenance is true.

isBurned

Provenance

Provenance is the whole record as JSON; secrets and salt stay "" until revealed / final.

SelfAddress

CollectionCount

MintedTotal

MintedTotal counts every token ever minted, burned ones included (OA B4).

MintedBy

MintedBy is the lifetime mint counter of addr in cid (OA B3, I-9).

Info

Info is the typed collection view for other realms.

PrimaryPayees

PrimaryPayees returns a copy of the frozen primary-sale split.

FeeConfig

FeeConfig is the typed fee view minters and markets settle with.

PrimaryFeeBps

PrimaryFeeBps is the protocol fee on cid's primary sale: the fee at Launch, or the current one if the admin lowered it since (SA-I5: a fee cannot rise during a sale).

Beacon

Admin

IsMinter

Collection

Collection is the collection record as JSON.

Collections

CollectionsByCreator

Fees

Fees is the fee configuration and its hard caps as JSON.

PendingOps

PendingOps is the timelock queue as JSON.

writeCollection

clampLimit

Render

Render stays minimal in the immutable realm; the browsable gallery is the private, re-deployable gallery realm (design §2.5.7).

royaltyAddress

RoyaltyAddress

DistributeRoyalties

DistributeRoyalties pushes the whole sub-treasury balance to the royalty payees. Permissionless and never paused (I-2); market/v1 calls it after every sale. Returns the amount distributed. The sub-realm banker spend is verified by spike/subtoken, core and market tests on gno v1.7.0.

distribute

tidWidth

tokenState

tokenState is the per-collection data the transfer hook needs. It is shared by the collection and its lockExt, so neither points at the other.

mintBatch

mintBatch records one mint call; mint height is derived per token from it, so a 10-token mint writes one record, not ten.

moveRecord

lockExt

lockExt is the grc721 Extension behind two invariants: - I-11: before Final no token moves or burns (the reveal lock that closes RA H-3's information-advantage branch). The veto is a panic, which aborts the whole transaction — the documented Extension semantics of p/nt/grc721/v0. - H-2: every transfer bumps the token's move counter, so a market listing taken at moves=N is dead after any transfer, even if the token later comes back to the seller. It is declared in this realm, so the hooks write core state with core's authority even when another realm moves the token via RealmTeller.

lockKind

Approve

Every Approve of a token and every SetApprovalForAll of an (owner, operator) pair bumps a nonce. A market pins the nonces at listing time, so revoking an approval kills a listing for good: approving again later starts a new nonce and never revives the old listing (SA-L3).

SetApprovalForAll

ApprovalNonces

ApprovalNonces returns the token's approval nonce and the (owner, operator) approval-for-all nonce. Approvals made directly through Token(cid).RealmTeller by a realm acting for itself do not bump them.

bumpNonce

nonceOf

TransferFrom

Burn

Burn is owner-only. The supply gate uses nextTID, so a burn never reopens a slot (I-5).

Token

Token publishes the collection's official \*grc721.Token. Its exported methods are reads or teller factories that need the caller's live realm; the ledger itself is never published.

Royalty

Royalty publishes the read-only royalty view (EIP-2981 RoyaltyInfo).

OwnerOf

BalanceOf

TokenMoves

TokenMoves is the transfer counter market/v1 pins in a listing (H-2).

TokenSeed

TokenSeed is "" until the collection is Final: no read path can leak the rarity map early.

TokenState

TokenState is {mintHeight, lastMoveHeight, moves} as JSON.

TokenURI

TokenURI is a base64 SVG data URI. Before Final every token shows core's neutral placeholder, never engine output (design §4.2).

TokenTraits

TokenTraits is \[{"trait\_type":…,"value":…}] JSON.

TokenTraitList

TokenTraitList is the typed form of TokenTraits for other realms (a copy).

TokenMetadata

TokenMetadata is OpenSea-style metadata JSON.

exists

tokenInput

renderToken

renderToken runs the collection's engine on a read path. A bad output degrades to a placeholder; a panicking engine only fails reads of its own collections (interrealm v2 §9: cross-realm panics abort the query).

tokenTraits

writeTraits

placeholderSVG

placeholderSVG is core's own neutral art: identical for every token of a collection, so it carries no rarity signal.

dataURI

emitBatch

emitBatch announces one MintTo ("MintBatch") or ReserveTo ("Reserved") call; each token also gets its own "Minted" event from lockExt.