v1 state

KeyBlockTop

The notice blocks: two strings a realm drops at the top and the bottom of its Render, empty by default, so moul can put a warning, a changelog line or a bit of news on every realm at once or on one of them. func Render(path string) string { return config.TopBlock() + body + config.BottomBlock() } Both are set with the ordinary Set, which is what keeps this realm's surface from growing a function per idea: Set block.top "> Chain migration on Tuesday." # every realm Set block.top@r/moul/gns "> v2 shipped, see the changelog" # this one only

KeyBlockBottom

The notice blocks: two strings a realm drops at the top and the bottom of its Render, empty by default, so moul can put a warning, a changelog line or a bit of news on every realm at once or on one of them. func Render(path string) string { return config.TopBlock() + body + config.BottomBlock() } Both are set with the ordinary Set, which is what keeps this realm's surface from growing a function per idea: Set block.top "> Chain migration on Tuesday." # every realm Set block.top@r/moul/gns "> v2 shipped, see the changelog" # this one only

TopBlock

TopBlock returns the notice for the realm calling in, ready to concatenate in front of its content. Empty when there is nothing to say, which is the default and the usual case. Three things can appear, in this order, separated by blank lines: 1. the pause banner, when this realm or every realm is paused 2. the global block.top 3. this realm's own block.top The pause banner comes first because it is the one a reader has to see, and it is included here rather than left to the realm so that guarding writes with AssertWritable is enough to also explain the refusal on the page. Global and scoped are BOTH shown rather than one overriding the other: a chain-wide warning and a per-realm changelog are different messages, and dropping either because the other exists is the surprising behaviour.

TopBlockFor

TopBlockFor is TopBlock for a named realm. Use it from a crossing function, where the caller cannot be read off the stack, or to render another realm's notice.

BottomBlock

BottomBlock returns the notice for the realm calling in, ready to concatenate after its content. No pause banner here: one is enough, and the top is where it is read.

BottomBlockFor

BottomBlockFor is BottomBlock for a named realm.

joinBlocks

joinBlocks assembles the non-empty parts into one markdown fragment. Each part is separated by a blank line, because two markdown blocks with only a newline between them are one paragraph, and a blockquote followed directly by text swallows the text into the quote. The result ends with a blank line when there is anything at all, so a realm can write config.TopBlock() + body without a separator of its own and get the same output whether or not a notice is set. Nothing to say means the empty string, and the page is byte-for-byte what it was before.

Authorizer

init.8

AddManager

AddManager adds a new address to the list of authorized managers. This only works if the current authority is a MemberAuthority. The caller must be authorized by the current authority.

RemoveManager

RemoveManager removes an address from the list of authorized managers. This only works if the current authority is a MemberAuthority. The caller must be authorized by the current authority.

TransferManagement

TransferManagement transfers the authority to manage keys to a new authority. The caller must be authorized by the current authority.

ListManagers

HasManager

ScopeSep

The key grammar. A key is a NAME, optionally followed by "@" and a SCOPE: pause applies to every realm that asks pause@r/moul/home applies to that realm only The scope is a package path with the chain domain stripped, because the domain is the same for every realm reading this one and repeating it in a few dozen keys buys nothing but storage. Two settings therefore answer every scoped question, and each reader decides how they combine: pause takes the stricter of the two (pausable.Strictest), while the notice blocks show both. That choice belongs to the reader and not here, because "stricter wins" and "show both" are both right, for different settings.

maxNameLen

The key grammar. A key is a NAME, optionally followed by "@" and a SCOPE: pause applies to every realm that asks pause@r/moul/home applies to that realm only The scope is a package path with the chain domain stripped, because the domain is the same for every realm reading this one and repeating it in a few dozen keys buys nothing but storage. Two settings therefore answer every scoped question, and each reader decides how they combine: pause takes the stricter of the two (pausable.Strictest), while the notice blocks show both. That choice belongs to the reader and not here, because "stricter wins" and "show both" are both right, for different settings.

maxScopeLen

The key grammar. A key is a NAME, optionally followed by "@" and a SCOPE: pause applies to every realm that asks pause@r/moul/home applies to that realm only The scope is a package path with the chain domain stripped, because the domain is the same for every realm reading this one and repeating it in a few dozen keys buys nothing but storage. Two settings therefore answer every scoped question, and each reader decides how they combine: pause takes the stricter of the two (pausable.Strictest), while the notice blocks show both. That choice belongs to the reader and not here, because "stricter wins" and "show both" are both right, for different settings.

realmPath

realmPath is this realm's own path, including its version. Stated once so the page can link to itself and the proxy check can recognise a sibling version without either restating the string.

validName

validName reports whether name is a legal setting name: 1..maxNameLen bytes of \[a-z0-9.\_-]. The dot is the namespace separator ("block.top"), lowercase only so a setting has exactly one name, and no whitespace so a name round-trips through Manifest's tab-separated lines.

validScope

validScope reports whether scope is shaped like a package path with the domain stripped: 1..maxScopeLen bytes of [a-z0-9.\_/-](/a-z0-9._/-), no empty segment.

validKey

validKey reports whether key is a legal name, or a legal name and scope joined by ScopeSep.

SplitKey

SplitKey takes a key apart. An unscoped key returns an empty scope, and so does a malformed one: callers pair this with validKey rather than trusting the split.

Scope

Scope turns a package path into the scope half of a key, stripping the chain domain: "gno.land/r/moul/home" and "r/moul/home" both give "r/moul/home". A path that is not shaped like one comes back empty, and every caller here treats that as "no scope", falling back to the global setting rather than inventing a key nobody can type. The chain domain is tried first and the literal "gno.land/" second, so a key written on one chain still resolves on another whose domain differs. Twin of mygnoscan.TrimDomain, which answers the same question for a URL and is stricter about the characters, because its output lands inside a link.

KeyFor

KeyFor builds the scoped key for a setting on one realm, and returns the bare name when pkgPath names no realm this can scope to. This is what a realm should render when it wants to tell a manager which setting to change, so the command in the page is the command that works.

caller

caller is the package path of the realm that called into this one. Every exported function here that uses it is a plain read with no \`cur realm\` parameter, so it can only ever be BORROWED: gno runs it without opening a realm frame, and unsafe.CurrentRealm() therefore reports the borrower. That is what makes the zero-argument helpers (TopBlock, IsPaused, …) able to name their caller at all. Measured in the test harness on 2026-09-22: a call from a code realm at gno.land/r/test/caller reports CurrentRealm=gno.land/r/test/caller and PreviousRealm=gno.land/r/moul/config/v1. The moment one of these grows a \`cur realm\` parameter this stops being true and starts reporting this realm instead. Do not add one. Anything that needs a realm frame takes the path explicitly, which is what the …For variants are.

scopedPair

scopedPair reads both halves of a scoped setting: the global one and the one for pkgPath, either of which may be empty.

KeyPause

The pause switch: one setting that stops every realm reading this one, and one per realm that stops just that one. Set pause "paused: incident, back in an hour" Set pause@r/moul/gns "readonly" Unset pause # running again A realm guards its writes and leaves its reads alone, which is what makes "readonly" the level worth having: the page keeps rendering and explains itself through TopBlock, and nothing new lands. func Post(cur realm, body string) { config.AssertWritable() … } The levels, the fail-closed parse and the stricter-of-two rule all live in gno.land/p/moul/pausable; this file is only the wiring to storage.

Pause

Pause returns the pause state of the realm calling in: the stricter of the global setting and that realm's own.

PauseFor

PauseFor is Pause for a named realm. A stale per-realm entry can never re-open a realm during a global pause, because the two combine with pausable.Strictest rather than one overriding the other. The cost is that exempting one realm from a global pause is not expressible: clear the global and set the others.

IsPaused

IsPaused reports whether the realm calling in is held back at all, ReadOnly as well as fully paused.

IsPausedFor

IsPausedFor is IsPaused for a named realm.

AssertWritable

AssertWritable aborts unless the realm calling in may still change state. This is the one line a mutating function needs.

AssertWritableFor

AssertWritableFor is AssertWritable for a named realm, for a crossing function that cannot be read off the stack.

AssertReadable

AssertReadable aborts unless the realm calling in may still be read. Most realms should NOT put this in Render. A page that aborts tells a reader nothing; TopBlock tells them what happened and when to come back. Reach for this only where serving stale data is itself the harm.

AssertReadableFor

AssertReadableFor is AssertReadable for a named realm.

proxies

// pkgPath -> address

AllowProxy

AllowProxy registers a newer version of this realm as a relay. Manager only. It takes a package path rather than an address because a path is what a manager can check by eye; the address is derived here with the same function the chain uses, so the two cannot drift.

RevokeProxy

RevokeProxy withdraws a relay. Manager only. Revoking one that was never registered aborts rather than passing quietly: at this point in an incident, "done" and "you misspelled it" must not look the same.

IsProxy

IsProxy reports whether addr is a registered relay.

ListProxies

ListProxies returns the registered relay paths, in sorted order.

SetAs

SetAs is Set, performed by a registered proxy on behalf of principal. Two checks, and both have to hold: the caller is a registered relay, and the principal it names is authorized. Neither is redundant. Dropping the first would let any realm claim any principal; dropping the second would make a registered proxy an unconditional bypass of the member list.

UnsetAs

UnsetAs is Unset, performed by a registered proxy on behalf of principal.

assertRelay

assertRelay aborts unless the immediate caller is a registered proxy.

assertPrincipal

assertPrincipal puts an address through the Authorizer without it being the caller, which is what a relay needs and what DoByPrevious cannot express. With the default MemberAuthority this is a membership test. With an authority that inspects the caller instead (a ContractAuthority), the relayed path asks that authority about the principal, so check what it does before transferring management while a proxy is registered.

assertProxyPath

assertProxyPath refuses anything that is not a realm path under this namespace. A proxy is by definition a later version of this realm, so nothing else should ever be registered, and the narrow check turns a fat-fingered AllowProxy into an abort rather than a standing grant to an unrelated realm.

isDigits

KeyMygnoscanURL

The keys this realm answers for by name. A key is just a string and any key can be set, but one the rest of the repo reads gets a constant here so the reader and the writer cannot drift apart on a typo.

KeyMygnoscanNetwork

The keys this realm answers for by name. A key is just a string and any key can be set, but one the rest of the repo reads gets a constant here so the reader and the writer cannot drift apart on a typo.

maxValueLen

maxValueLen bounds one write. Storage is paid for and never refunded, so this realm holds settings, not content: a URL, a flag, a short list. A notice block is the one that pushes against it, and 1024 bytes is several paragraphs of markdown. A realm that needs more than that is asking this one to be a CMS, which is what its own slots are for.

setting

settings

// key -> \*setting

settingsRev

Set

Set creates or replaces a setting. Only an address the Authorizer accepts may call it. It panics rather than returning an error, which is the opposite of the manager functions in config.gno, and deliberately so: a returned error from a realm call leaves the transaction SUCCESSFUL. A rejected config write that reports success is the one outcome worth ruling out here, because the caller then walks away believing the new value is live and every realm reading this key keeps serving the old one. The manager functions predate that reasoning and are frozen on chain at v0; new surface does not inherit the mistake.

Unset

Unset removes a setting, so readers fall back to their built-in default. Removing a key that is not set is an error, not a no-op: it almost always means the key was misspelled here or in the realm that reads it.

writeSetting

writeSetting is the only place a setting is stored, shared by the direct and the relayed path so a new caller cannot forget the revision or the event.

removeSetting

removeSetting is writeSetting's twin.

assertWritableKey

assertValue

assertValue rejects a value the reader could not make sense of. Only pause has a grammar today, and it is exactly the setting where a silently unreadable value matters: pausable.MustParse fails CLOSED, so a typo stored here would take every realm offline at the next render. Catching it on the way in costs one comparison and turns that into a failed transaction the writer sees immediately.

assertAuthorized

assertAuthorized runs the write through the Authorizer, so whoever holds authority today decides: the member list at first, a DAO or a contract after a TransferManagement. The action closure is what authz authorizes; the write itself happens after, because a nil error is the only thing that reaches it.

Get

Get returns a setting's value, or "" when it is not set. Reads are open: a realm importing this one calls Get on every render and pays nothing beyond the cross-realm call.

GetOr

GetOr returns a setting's value, or fallback when it is unset or empty. This is the shape every consumer wants: a realm should still render on a chain where this one was never deployed with that key.

Has

Has reports whether key is set, including to the empty string, which GetOr cannot distinguish from unset.

Keys

Keys returns every set key, in sorted order.

Size

Size returns how many settings are set.

SettingsRevision

SettingsRevision counts every settings write this realm has accepted. A client that caches config polls this one int to learn that nothing moved.

Manifest

Manifest returns one tab-separated line per setting: <key>\t<rev>\t<height>\t<value> It is the whole config in one vm/qeval read, for a tool that wants to diff the chain against a local file without a call per key. The value is last because it is the only field that can contain a tab.

MygnoscanURL

MygnoscanURL returns the explorer base moul's realms should link to, falling back to the package default when nothing is set here.

Scanner

Scanner returns a link builder pointed at the configured explorer, on whichever network answers for the running chain (or at the KeyMygnoscanNetwork override, when one is set). This is the function other realms are meant to call: config.Scanner().Realm("gno.land/r/moul/home") config.Scanner().Address(someAddr) Changing where every one of them points is then one transaction against this realm, not a redeploy of each.

Mygnoscan

Mygnoscan is the explorer page of the realm calling in.

MygnoscanFor

MygnoscanFor is Mygnoscan for a named realm.

MygnoscanFooter

MygnoscanFooter is the render-ready form: the markdown line the realm calling in appends under its output.

MygnoscanFooterFor

MygnoscanFooterFor is MygnoscanFooter for a named realm.

Render

Render shows the whole configuration: the settings, who may change them, and where this realm itself can be inspected.

renderPause

renderPause reports the global pause only. A per-realm one is a setting like any other and is already in the table above; repeating them here would be a second list to keep in step, and the one a reader of THIS page wants is the switch that covers everything.

renderProxies

renderProxies lists the later versions allowed to relay writes here. The section is omitted entirely while there are none, which is the state this realm ships in and stays in until a v2 exists.

renderValue

renderValue puts a value in a code span and neutralises the two characters that would otherwise break out of the table cell it sits in. Only a manager can write a value, so this is about a stray pipe in a URL and not about an attacker, but a config page that silently loses a column is its own bug.