v1 state

bookOne

maxBook

numChaptersBookOne

numEmberSeedChapters

bookOneClaim

bookOneClaim is one address's claimed progress through Book One. Named claim, not progress or record, on purpose: every field here is what an address SAID, timestamped by the chain when it said it, never something this package checked against the actual game. See the package doc above.

claims

totalClaimants

claimKey

claimKey is the tree key for one (address, book) pair's claim.

ClearChapter

ClearChapter records that the calling address CLAIMS to have cleared this chapter of this book. See the package doc above for what this is and is not: a timestamped, public, permanent claim, never a verified outcome. Accepts no coins (this package handles no money at all; see NOTES.md for why chapter purchase is out of scope entirely, not half-built). Chapters must clear in strict order, starting from 1, and each chapter may be claimed at most once per address -- both enforced by the single comparison below against highestChapterClaimed, the same way garden/v2 favours one invariant that closes several hostile cases over several separate ad hoc checks (see that file's SaveDay comment). Ember Seeds are never a parameter here or anywhere in this package: see emberSeedsFor for how they are derived instead. ATOMICITY: every check below runs to completion before anything is written. work is a plain value copy of this address's existing claim (or the zero value, if this is its first), taken after every validation has already passed; the only thing that happens to it is the two-field update at the bottom, so a panic anywhere above that point leaves the persisted claim -- if any -- completely untouched. This mirrors garden/v2's SaveDay pattern deliberately: a plain value copy, not a recover()-and-rollback. See the package doc for why recover() is never the right tool here either.

emberSeedsFor

emberSeedsFor derives the number of Ember Seeds this claim implies: one per chapter 1-3 claimed cleared (chapter 4 is the finale that brings the three home, not a fourth seed -- see numEmberSeedChapters's own comment). This is the ONLY place Ember Seeds are computed anywhere in this package. There is no exported function, field, or parameter anywhere in this file that lets a caller set, add, or otherwise assert an Ember Seed count directly -- it is always read off highestChapterClaimed, never written. A client cannot claim seeds it did not (claim to have) earned, because there is no spelling of a call into this package that takes a seed count as input at all. Reads highestChapterClaimed, never claimedAt: ClearChapter only ever advances both fields together (see its own comment), so the two cannot disagree today -- but highestChapterClaimed is the simpler source of truth. claimedAt uses 0 as its own "not yet claimed" sentinel while also being written from real block time, a dual representation of the same fact with a sentinel to keep straight; highestChapterClaimed needs neither. Capped at numEmberSeedChapters so chapter 4 (the finale, not a fourth seed-winning chapter) never adds a 4th.

BookOneClaim

BookOneClaim is the progress read for one address: what it has claimed in Book One, and the Ember Seed count derived from those claims. found is false if this address has never had a ClearChapter call accepted for Book One at all.

TotalClaimants

TotalClaimants returns the number of addresses with at least one accepted chapter claim in Book One. Everything claims holds is already public via Render (there is no privacy cost to exposing it), but before this function the only way to reach this exact number was BookOneClaim(someKnownAddress) for one address at a time, or string-parsing the overview page Render("") returns. Neither lets another realm -- a future Book Two, a shop, a leaderboard -- enumerate or even count claimants, which is a real limitation for a ledger whose entire stated purpose is being publicly readable. See ClaimantsPage below for the enumerator this same gap needed.

maxClaimantsPageSize

maxClaimantsPageSize bounds a single ClaimantsPage call's own limit, so that call stays gas-bounded no matter how large claims grows over this realm's lifetime -- a caller cannot make one call's own cost scale with the whole ledger's size just by asking for a bigger page. Picked well above anything a real paging UI needs per page (a leaderboard or an admin view rendering a few dozen rows at a time) and far below a size that would make one call's own tree traversal unbounded.

ClaimantsPage

ClaimantsPage is the paginated enumerator claims needed to be genuinely publicly readable, not just publicly readable one known address at a time. It returns up to limit claim keys (each claimKey(address, book), i.e. "\<address>:\<book>") in the claims tree's own stable order, starting at offset -- the same (key, value) order claims.IterateByOffset itself walks, which never changes for a fixed tree. limit is CLAMPED to maxClaimantsPageSize rather than rejected outright, so a caller that asks for too much still gets a gas-bounded page back instead of an aborted call; offset and limit are otherwise rejected if non-positive/negative, since those are caller mistakes with no sane page to return. Paging with offset 0, then offset+len(returned page), ... until a page shorter than its own requested limit comes back, covers every claimant exactly once, in this stable order, with no duplicates and no gaps, for any snapshot where claims does not grow between calls -- see hollowmere\_test.gno's own paging test, which proves this directly rather than assuming it from the underlying avl.Tree's own doc comment.

Render

Render gives each player a public page on gno.land. Path validated with address(path).IsValid() before anything derived from it is echoed back -- the same guard garden/v2's own Render uses, and for the same reason: an invalid path must get a generic refusal, never a page built out of attacker-controlled text.

chapterLine