Skip to content Search Apps Documentation Source Content Run Reset Eval Playground File Folder Download Copy Actions State String Boolean Number Struct Map Slice Pointer Function Closure Reference Nil Package Type Interface Unknown

Community realm. Read the code first. Community realm, deployed by its author. Read the code before you interact or send coins.

core source realm

Package core is the platform's immutable ledger (design §2.5.2): every collection, its official grc721 token and roya...

Overview

Package core is the platform's immutable ledger (design §2.5.2): every collection, its official grc721 token and royalty, its provenance (commit–reveal v2), the engine registry, fees and the admin timelock.

What core guarantees, whoever holds the admin key:

  • I-1 admin cannot move, approve or burn a token, and holds no funds; the op list is a closed set of parameters (admin.gno).
  • I-2 pause only gates create, mint and trade. Transfer, burn, finalize, distribute and every cancel stay open. A pause expires by itself, cannot be renewed while it runs, and each scope has a budget of MaxPauseBlocks per PauseWindowBlocks (SA-L2).
  • I-5 supply only grows through the collection's bound minter, never past maxSupply, and a token id is never minted twice.
  • I-6 after Launch the engine, params, supply, payees, sale window, commitments, randomness source and fee snapshots are frozen.
  • I-9 MintedBy(addr) is exact while a collection is not Final: grc721 balance minus the reserves sent to addr. It needs I-11 (no token moves or burns before Final); if that lock is ever relaxed the counter must be stored again (TestRegress_P2_*).
  • I-10/11 a collection becomes Final at most once, only with both reveals or after revealDeadline, and that deadline is bounded, so the pre-reveal transfer lock always ends. With a randomness provider Finalize may wait for the bound round, at most ProviderWaitBlocks after the deadline or the binding (a Finalize after the deadline binds), so anyone can end the lock by revealDeadline + 1 + ProviderWaitBlocks + 1.
  • I-12 engine code never runs on a state-changing path, except the creator's own CreateCollection (ValidateParams) and the engine's own RegisterEngine (one sample render). Every exported non-crossing function is read-only, so an engine cannot call back into a mutator. An admin-approved randomness provider (randomness.gno) runs only in RevealCreatorSecret, RequestRandomness, FulfillRandomness and Finalize of collections launched with it.
  • I-13 every stored string passed safe.AssertText.

core imports no mutable realm: minters and engines are known only by package path and interface value.

Constants 4

const OpFeeCreate, OpFeePrimary, OpFeeSecondary, OpFeeEngine, OpTreasury, OpBeacon, OpMinterAdd, OpMinterDeprecate, OpEngineReview, OpAdminTransfer, OpRandomnessAdd, OpRandomnessDepr, OpListingDeposit

 1const (
 2	OpFeeCreate       = "fee.create"           // ugnot, <= CreateFeeCap
 3	OpFeePrimary      = "fee.primary"          // bps, <= ProtocolFeeCapBps
 4	OpFeeSecondary    = "fee.secondary"        // bps, <= ProtocolFeeCapBps
 5	OpFeeEngine       = "fee.engine"           // bps, <= EngineFeeCapBps: platform cap on engine-author fees
 6	OpTreasury        = "treasury"             // address
 7	OpBeacon          = "beacon"               // address, or "" to disable new beacon launches
 8	OpMinterAdd       = "minter.add"           // realm pkgpath
 9	OpMinterDeprecate = "minter.deprecate"     // realm pkgpath: no new collections
10	OpEngineReview    = "engine.review"        // engine id: reviewed badge (UI only)
11	OpAdminTransfer   = "admin.transfer"       // address; the new admin must AcceptAdmin
12	OpRandomnessAdd   = "randomness.add"       // registered provider path: creators may launch with it
13	OpRandomnessDepr  = "randomness.deprecate" // provider path: no new launches; running ones finish
14	OpListingDeposit  = "listing.deposit"      // ugnot, <= ListingDepositCap: market deposit return for new listings
15)
source

Ops and their argument formats.

const ProtocolFeeCapBps, RoyaltyCapBps, CreateFeeCap, MaxPayees, MaxSupplyCap, MaxMintPerTx, MaxReserveBps, MaxSaleBlocks, RevealWindowMin, RevealWindowMax, BeaconGraceBlocks, TimelockBlocks, MaxPauseBlocks, PauseWindowBlocks, EngineFeeCapBps, ProviderWaitBlocks, ListingDepositCap, MaxNameLen, MaxDescriptionLen, MaxParamsLen, MinSecretLen, MaxSecretLen, MaxPageSize

 1const (
 2	ProtocolFeeCapBps  = 500           // 5% of any sale
 3	RoyaltyCapBps      = 1000          // 10% (RA M-3)
 4	CreateFeeCap       = 1_000_000_000 // 1,000 GNOT in ugnot
 5	MaxPayees          = 4
 6	MaxSupplyCap       = 10_000
 7	MaxMintPerTx       = 10               // hypothesis: measure n=10 gas/deposit on Onyx
 8	MaxReserveBps      = 1000             // creator reserve <= 10% of supply
 9	MaxSaleBlocks      = 732_000          // ~30 days
10	RevealWindowMin    = 1_017            // ~1 hour
11	RevealWindowMax    = 170_000          // ~7 days
12	BeaconGraceBlocks  = 254              // beacon may reveal first in the window's last ~15 min (< RevealWindowMin, so the creator always gets to go first)
13	TimelockBlocks     = 48_800           // ~48 hours
14	MaxPauseBlocks     = 195_000          // ~8 days: pause budget per scope and window
15	PauseWindowBlocks  = 732_000          // ~30 days (SA-L2)
16	EngineFeeCapBps    = engine.MaxFeeBps // 5%: hard cap of an engine author's fee (platform cap <= this)
17	ProviderWaitBlocks = 24_400           // ~24 h: Finalize waits this long after the deadline (or the round's binding) for a provider's round before falling back (CV-M1)
18	ListingDepositCap  = 5_000_000        // 5 GNOT: hard cap of the market's listing deposit return (op listing.deposit, CV-L2)
19
20	MaxNameLen        = 64
21	MaxDescriptionLen = 1024
22	MaxParamsLen      = 1024
23	MinSecretLen      = 32
24	MaxSecretLen      = 256
25	MaxPageSize       = 50
26)
source

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).

Functions 71

func AbortLaunch

crossing Action
1func AbortLaunch(cur realm, cid string)
source

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).

func ApprovalNonces

Action
1func ApprovalNonces(cid, tid string, owner, operator address) (tokenNonce, operatorNonce int64)
source

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.

func Approve

crossing Action
1func Approve(cur realm, cid, tid string, to address)
source

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).

func BeaconCommit

crossing Action
1func BeaconCommit(cur realm, cid, commitHex string)
source

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

func Burn

crossing Action
1func Burn(cur realm, cid, tid string)
source

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

func ClaimEngine

crossing Action
1func ClaimEngine(cur realm, id string)
source

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

func CloseMint

crossing Action
1func CloseMint(cur realm, cid string)
source

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

func CreateCollection

crossing Action
1func CreateCollection(cur realm, creator address, spec types.CollectionSpec) string
source

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).

func DeprecateEngine

crossing Action
1func DeprecateEngine(cur realm, id string)
source

DeprecateEngine stops new collections; existing ones keep rendering.

func DistributeRoyalties

crossing Action
1func DistributeRoyalties(cur realm, cid string) int64
source

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.

func EngineFee

Action
1func EngineFee(cid string) (author address, bps int64)
source

EngineFee is the engine-author share of cid's sales: the author and the bps a sale pays now (0 when the creator is the author). mint/v1 and market/v1 pay safe.BpsOf(amount, bps) to author.

func EngineManifest

Action
1func EngineManifest(id string) engine.Manifest
source

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

func EngineStatus

Action
1func EngineStatus(id string) string
source

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

func EngineTraits

Action
1func EngineTraits(id, params, seed string) []engine.Trait
source

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

func ExecuteOp

crossing Action
1func ExecuteOp(cur realm, opID string)
source

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.

func FairLaunch

Action
1func FairLaunch(cid string) bool
source

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.

func FeeConfig

Action
1func FeeConfig() types.Fees
source

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

func Fees

Action
1func Fees() string
source

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

func Finalize

crossing Action
1func Finalize(cur realm, cid string)
source

Finalize is permissionless and never paused (I-2): immediately once every expected secret is revealed, otherwise after revealDeadline (fallback). For a provider collection it first binds or consumes the provider's round (settleProvider) and falls back only when the provider failed to deliver.

func FulfillRandomness

crossing Action
1func FulfillRandomness(cur realm, cid string)
source

FulfillRandomness takes the bound round's value from the provider as the beacon secret and finalizes (2/2 after the creator, beacon-only when it stayed silent). Permissionless and never paused (I-2); works before and after the deadline while the collection is Closed.

func Info

Action
1func Info(cid string) types.CollectionInfo
source

Info is the typed collection view for other realms.

func Launch

crossing Action
1func Launch(cur realm, cid string, l types.LaunchSpec)
source

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.

func ListingDeposit

Action
1func ListingDeposit() int64
source

ListingDeposit is the deposit return (ugnot) market/v1 pins into a new listing (CV-L2); 0..ListingDepositCap, admin op listing.deposit.

func MintTo

crossing Action
1func MintTo(cur realm, cid string, to address, n int64) (first, last int64)
source

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 and the beacon commitment (I-5). The lifetime counter of I-9 is the grc721 balance itself (mintedBy).

func MintedBy

Action
1func MintedBy(cid string, addr address) int64
source

MintedBy is addr's lifetime count of sale mints in cid (OA B3, I-9), reserves excluded. Exact until the collection is Final, -1 afterwards (derived from the locked grc721 balance; see mintedBy).

func MintedTotal

Action
1func MintedTotal(cid string) int64
source

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

func Pause

crossing Action
1func Pause(cur realm, scope string)
source

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).

func PauseBudget

Action
1func PauseBudget(scope string) string
source

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

func Paused

Action
1func Paused(scope string) bool
source

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

func PrimaryFeeBps

Action
1func PrimaryFeeBps(cid string) int64
source

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).

func PrimaryPayees

Action
1func PrimaryPayees(cid string) []types.Payee
source

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

func Provenance

Action
1func Provenance(cid string) string
source

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

func RandomnessProviders

Action
1func RandomnessProviders(offset, limit int64) string
source

RandomnessProviders lists registered providers (by path) as JSON: [{id, name, active, registeredHeight}]. Registration is open, so only "active" ones (admin-approved) can be chosen at Launch.

func RegisterEngine

crossing Action
1func RegisterEngine(cur realm, e engine.Engine) string
source

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.

func RegisterRandomnessProvider

crossing Action
1func RegisterRandomnessProvider(cur realm, p RandomnessProvider) string
source

RegisterRandomnessProvider stores the calling realm's provider. It is inert until the admin approves it (randomness.add, timelocked).

func Render

1func Render(path string) string
source

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

func RenderWith

Action
1func RenderWith(id, params, seed string) string
source

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

func RequestRandomness

crossing Action
1func RequestRandomness(cur realm, cid string) int64
source

RequestRandomness binds a provider-backed collection whose creator stayed silent to the provider's next unknowable round (a creator's reveal binds it itself). Permissionless and never paused (I-2); after the deadline the first Finalize binds instead.

func ReserveTo

crossing Action
1func ReserveTo(cur realm, cid string, to address, n int64) (first, last int64)
source

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.

func Royalty

Action
1func Royalty(cid string) *royalty.Royalty
source

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

func SetPayees

crossing Action
1func SetPayees(cur realm, cid, payees string)
source

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).

func Token

Action
1func Token(cid string) *grc721.Token
source

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.

func TokenMoves

Action
1func TokenMoves(cid, tid string) int64
source

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

func TokenSeed

Action
1func TokenSeed(cid, tid string) string
source

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

func TokenState

Action
1func TokenState(cid, tid string) string
source

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

func TokenTraitList

Action
1func TokenTraitList(cid, tid string) []engine.Trait
source

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

func TokenTraits

Action
1func TokenTraits(cid, tid string) string
source

TokenTraits is [{"trait_type":…,"value":…}] JSON.

func TokenURI

Action
1func TokenURI(cid, tid string) (string, error)
source

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

func TransferCreator

crossing Action
1func TransferCreator(cur realm, cid string, to address)
source

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

func Unpause

crossing Action
1func Unpause(cur realm, scope string)
source

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

func VerifyEngine

Action
1func VerifyEngine(id string) bool
source

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

func VerifyProvenance

Action
1func VerifyProvenance(cid string) bool
source

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

Types 1

type RandomnessProvider

interface
 1type RandomnessProvider interface {
 2	// Name is a short label for UIs, e.g. "drand quicknet".
 3	Name() string
 4	// Target is the round a request made in the current block is bound
 5	// to. Its value must be unknowable to anyone at this block (a round
 6	// published strictly in the future). Read-only.
 7	Target() int64
 8	// Randomness is round's verified value as 64 lowercase hex characters
 9	// (32 bytes), or "" while it is not available. Read-only.
10	Randomness(round int64) string
11}
source

Pluggable randomness sources (beacon v2).

A collection launched with useBeacon picks its second entropy source at Launch (LaunchSpec.BeaconSource, frozen by I-6):

  • types.BeaconCommitted: the platform beacon's commit-reveal (provenance.gno; BeaconCommit before the first mint, RevealBeaconSecret after the creator).
  • the package path of a randomness provider realm: a public random value nobody can know in advance, e.g. a drand round relayed and BLS-verified on chain (gnolang/gno#6268 p/drand + r/drand). Nothing is committed before the sale; the round is fixed by the creator's reveal (same transaction) or, for a silent creator, in the grace period / at the deadline, and its value is then consumed by whoever calls first (FulfillRandomness or Finalize): no caller can skip it.

Before any provider is approved (randomness.add) a keeper must run that requests in the grace period for silent creators and fulfills bound rounds as soon as they are published (README "Randomness keeper").

A provider realm registers itself (its id is its package path, as for engines) and is usable only after the admin approves it through the timelocked op randomness.add; randomness.deprecate stops new launches, running collections finish with it. So a drand provider plugs in without a core redeploy. Its methods are declared in its own realm, so core calling them runs the provider with the provider's authority (interrealm v2 borrow rule #1): it cannot write core state, and with no cur it cannot call a core mutator.

Order with a provider (same guarantees as the committed beacon, SA-M1; CV-M1: the outcome never depends on who calls, or when):

  1. the creator reveals until revealDeadline - BeaconGraceBlocks; the reveal itself binds the collection to provider.Target() in the same transaction, a round nobody knows yet (its secret is public now, so nobody holding a choice learns anything new later);
  2. a silent creator: RequestRandomness (anyone, a keeper) inside the grace period, or the first Finalize after revealDeadline, binds the round instead — the creator's window is closed by then;
  3. once the provider has the bound round (and not in the binding block, CV-I6), FulfillRandomness or Finalize (anyone, before or after the deadline) takes its value as the beacon secret and the collection is Final (2/2 after the creator, beacon-only otherwise). After the deadline Finalize refuses to fall back while the bound round may still arrive;
  4. fallback (creator-only / fallback badge, never a FairLaunch) only once the provider failed to deliver for ProviderWaitBlocks after the deadline or the binding, whichever is later.

A provider that panics aborts the calling transaction (a realm-boundary panic cannot be recovered); if an approved provider breaks, the admin deprecates it and, after the wait, Finalize stops calling it.

Dependencies

Source Files 10