permbook_demo

curl -sS 'https://pearl.testnets.gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/permbook_demo$download&file=permbook_demo.gno' | shasum -a 256

Overview

Package permbook_demo is the reference consumer for the permbook permission primitive. It exists to make permbook's central claim falsifiable on a live chain.

That claim is: a permission revoked in transaction N is refused in transaction N+1. A pure package cannot demonstrate this — a vm/qeval is a single ephemeral evaluation and nothing it writes survives it. Only a realm, called across several transactions, can show a grant taking effect and then a revoke taking it away. So this realm is not a decoration on the primitive; it is the experiment.

What it does

Two permission-gated actions, deliberately trivial so that the only interesting thing about them is the gate:

• bump — increments a counter and records who did it
• notice — replaces a short public notice

Neither action is reachable without the corresponding permission. The deployer is the book's admin and is the only account that may grant or revoke. Holding "bump" confers no authority over the book itself: a holder cannot grant, cannot revoke, and cannot nominate. That separation is the property being demonstrated.

How it wires permbook correctly

This realm is also the worked example of permbook's consumer contract:

• every permbook mutator is called from a CROSSING entrypoint, passing that entrypoint's own cur, so the principal permbook resolves is this realm's immediate caller (contract 1);
• the *Book is an unexported package-level var and is never returned across a realm boundary (contract 2);
• Has is asked about an address this realm derived itself from cur.Previous().Address(), never about a parameter (contract 3);
• the limits are chosen once, at init, and documented below (contract 4).

This realm holds no coins and imports no banker. Every crossing entrypoint rejects attached coins; the read views are non-crossing, which MsgCall will not dispatch to, so no transaction can attach coins to one.

Imports

• chain
• chain/runtime
• chain/runtime/unsafe
• gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/permbook
• gno.land/p/nt/markdown/sanitize/v0
• strconv

Constants and variables

The permission names this realm gates on. They are constants rather than caller-supplied strings for the gated actions, so a typo cannot silently create an unenforced gate.

const (
	PermBump   = "bump"
	PermNotice = "notice"
)

const (
	// The book's limits. Deliberately far below permbook's ceilings: this
	// realm needs two permissions and a handful of holders, and a bound
	// should describe what the application actually does rather than the
	// most the library would tolerate. A few spare slots are left so the
	// permission limit can be exercised on-chain without wedging the demo.
	MaxPermissions = 8
	MaxHolders     = 32
	MaxNameLen     = 24

	// MaxNoticeLen bounds the public notice. A BYTE length, not a rune
	// count, because its job is to bound storage.
	MaxNoticeLen = 200

	// MaxListed caps how many rows any single query or view returns, so no
	// read is unbounded regardless of how full the book is.
	MaxListed = 50
)

Functions

AcceptAdmin

func AcceptAdmin(cur realm) string

Crossing function. Callable from a transaction via MsgCall, and from another realm as AcceptAdmin(cross(cur), ...).

AcceptAdmin completes a pending handoff. Only the nominee may call it.

Admin

func Admin() string

Admin returns the book's current admin.

Bump

func Bump(cur realm) string

Crossing function. Callable from a transaction via MsgCall, and from another realm as Bump(cross(cur), ...).

Bump increments the counter. Requires the "bump" permission.

This is the experiment: call it with the permission and it succeeds; have the admin revoke, call it again in a later transaction, and it aborts.

Bumps

func Bumps() int64

Bumps returns how many times Bump has succeeded.

CanBump

func CanBump(addr address) bool

CanBump reports whether addr would be allowed to call Bump right now.

CancelNomination

func CancelNomination(cur realm) string

Crossing function. Callable from a transaction via MsgCall, and from another realm as CancelNomination(cross(cur), ...).

CancelNomination withdraws a pending nomination. Admin only.

DropPermission

func DropPermission(cur realm, perm string) string

Crossing function. Callable from a transaction via MsgCall, and from another realm as DropPermission(cross(cur), ...).

DropPermission removes a permission and every grant of it. Admin only.

Grant

func Grant(cur realm, perm string, addr address) string

Crossing function. Callable from a transaction via MsgCall, and from another realm as Grant(cross(cur), ...).

Grant gives addr a permission. Admin only.

Has

func Has(perm string, addr address) bool

Has reports whether addr holds perm. This is the primitive's core query, exposed verbatim so it can be checked from off-chain.

Height

func Height() int64

Height returns the chain height this realm is reading as "now".

HolderCount

func HolderCount(perm string) int

HolderCount returns how many addresses hold perm, or 0 if it does not exist.

Holders

func Holders(perm string) string

Holders returns up to MaxListed holders of perm, comma-separated in sorted order.

LastBump

func LastBump() string

LastBump describes the most recent successful Bump, or "none".

Limits

func Limits() string

Limits reports the book's fixed limits.

NominateAdmin

func NominateAdmin(cur realm, nominee address) string

Crossing function. Callable from a transaction via MsgCall, and from another realm as NominateAdmin(cross(cur), ...).

NominateAdmin records a nominee for the admin role. Admin only. The handoff does not take effect until the nominee calls AcceptAdmin.

Notice

func Notice() string

Notice returns the current public notice, or "".

PendingAdmin

func PendingAdmin() string

PendingAdmin returns the nominated-but-not-yet-accepted admin, or "".

PermissionCount

func PermissionCount() int

PermissionCount returns how many distinct permissions currently exist.

Permissions

func Permissions() string

Permissions returns up to MaxListed permission names, comma-separated in lexicographic order.

PermissionsOf

func PermissionsOf(addr address) string

PermissionsOf returns the permissions addr holds, comma-separated in lexicographic order, or "" for none. Names are restricted by permbook to lowercase alphanumerics and underscore, so a comma can never appear in one and this encoding is unambiguous.

Ready

func Ready() bool

Ready reports whether init captured a deploy-time admin and constructed the book. False means the realm is inert; see the note in init.

Render

func Render(path string) string

Render serves three views, selected by path.

(empty) summary, the permission table, and the gated state holders every permission with its holders, up to MaxListed each about what this realm is and why it exists

An inert realm (see init) reports that instead of rendering. Every view reads the book, so without this the gnoweb page would abort on a nil dereference — which is exactly the moment an operator needs it to say what is wrong. The typed read functions still abort when inert; Ready is the probe that answers the question without panicking.

Revoke

func Revoke(cur realm, perm string, addr address) string

Crossing function. Callable from a transaction via MsgCall, and from another realm as Revoke(cross(cur), ...).

Revoke removes a permission from addr. Admin only.

The revoke is committed by this transaction. Any later transaction that reaches a gate on that permission is refused — that is the claim.

RevokeAll

func RevokeAll(cur realm, addr address) string

Crossing function. Callable from a transaction via MsgCall, and from another realm as RevokeAll(cross(cur), ...).

RevokeAll removes every permission addr holds and reports how many. Admin only.

SetNotice

func SetNotice(cur realm, text string) string

Crossing function. Callable from a transaction via MsgCall, and from another realm as SetNotice(cross(cur), ...).

SetNotice replaces the public notice. Requires the "notice" permission.

It exists so the demo shows two INDEPENDENT permissions on one book: holding "bump" does not let an address set the notice, and revoking one leaves the other intact.

---

Doc text is reproduced as vm/qdoc returns it. The node markdown-escapes doc comments, so a bracket or angle bracket may carry a backslash the committed source does not have. The source itself is at source and in this repository.