v0 source pure

Adopt installs a kind as live without a vote.

The consuming realm's, and nobody else's — reaching it needs the *Governor, which a realm keeps unexported. That is the same authority the realm already has by holding the engine at all, so this grants nothing new; what it does is make the un-voted path explicit and greppable rather than something a realm improvises by reaching into a tree.

For a realm's OWN powers, and for arming a governor in a test. Anything a stranger publishes goes through Offer and an adoption vote, which is the distinction the whole design turns on: publishing code and letting that code hold the governor's authority are different decisions taken by different actors.

A realm that exposes this through a crossing function has given governance away. So would exposing Propose without its rules, or Execute without its timelock; the engine cannot stop a consumer publishing the wrong thing, and says so here because this is the one most obviously worth not publishing.

Cancel withdraws a proposal. Only the proposer, only while it is still open.

Describe is what the vote is about, rendered by the kind from the payload alone — the same string Do will be handed.

Digest is the key a question occupies in the open index, derived from the kind and payload that define it. Exported because it is a pure function of two public strings, and because what it is FOR is worth knowing: a proposer chooses their payload and so chooses their key, which is why the slot sweep rotates rather than always starting at the low end.

EpochOf is the sealed epoch a proposal's weight was read at. Fixed when the question was asked, and the reason buying in afterwards buys nothing.

HasRoll reports whether a proposal is still holding its voter roll, or has given it back through ReleaseRoll.

HasVoted reports whether an address has already voted on a proposal.

OpenZeppelin has hasVoted; without it the only way to find out is to send a vote and be refused, spending a transaction to learn what the realm knows. A wallet needs it before deciding whether to offer the buttons.

Keeps answering after a proposal closes, because the roll survives until somebody calls ReleaseRoll. Once it has been released this answers false, so it is "is their vote still on record here", not "did they ever" — the permanent record of who voted is the Voted events.

InstallBuiltin adopts a kind under the reserved prefix, which Offer refuses.

For the consuming realm only, and it is unexported state that makes that true: reaching this needs the *Governor, which the realm keeps to itself. A realm uses it for a power that is its own rather than the engine's — the mint being the example.

KindRules is the terms a kind was adopted on. A copy: Rules is a plain struct of numbers, so handing one back gives away nothing to write through.

KindStatus is whether a name has been offered here, and whether the holders have adopted it. Both false for a name nobody has published.

Offer shelves a kind. It takes effect on nothing.

Ungated, because an offered kind can do nothing. What it buys is a name pointing at published, immutable code the holders are later asked to approve.

The two-step exists because MsgCall.Args is []string: an account cannot hand over a Kind, only a realm can construct one. If adopting required passing the value, only realms could grow the governor — and that decision has to belong to the holders. Offer is the realm's half; the vote is theirs.

OpenSlots is how many proposals are holding a slot, decided-and-unrun included. The number the front page prints beside MaxLive.

Preview renders what a payload would say, before anybody proposes it — so an interface can show somebody their proposal, and Check refuses a malformed one without spending a transaction.

It also pins the thing the extension point rests on: govern calling INTO a kind in another realm. A stored interface value is re-resolved from the store on every call, so the method that runs is the offering realm's code.

Reads whether or not the kind is adopted. What a payload would say is not a power, and refusing to preview an unadopted one makes the adoption vote harder to judge rather than safer.

Proposals is how many questions have ever been asked here.

Propose opens a question. One maketx call, two strings — which is the whole design and the reason the payload is not a struct.

The quorum is the rules' QuorumBps fraction of the engaged weight. A consumer that computes its own absolute bar — a court sizing quorum to a claim's open interest — uses ProposeWithQuorum instead.

ProposeWithQuorum is Propose with an ABSOLUTE turnout the question needs, replacing the rules' QuorumBps fraction for this one proposal. The figure is the consumer's to compute (a court's max(5% supply, min(1×X̄, ⅓ votable))) and is snapshotted here, so the bar cannot move under an open vote. A non-positive floor is refused — a caller wanting the bps formula calls Propose.

Additive: Propose is unchanged and passes zero, which every existing user does.

QuorumFloor is the absolute turnout a proposal needs when it was opened with ProposeWithQuorum, or 0 when the quorum is the rules' QuorumBps fraction of the engaged weight. A court renders a floored proposal's bar from this; the engine already uses it in the tally and on its own page. Snapshotted at Propose, so it is the bar the voters actually face.

Reason is why a proposal ended, or the empty string while it is still open. The page prints it; this is the same string.

ReleaseRoll drops a finished proposal's voter roll and refunds its deposit to whoever calls.

The roll does not go when a proposal settles, because a kind that pays out to the people who voted has to ask after the fact, and pull-based claiming means the last claim can be a long way after execution. So it is reclaimed on request instead: nobody is obliged to, and whoever does is paid for it — the same bargain Settle makes for the slot.

Refused twice over. While a proposal is open, because Vote reads the roll to refuse a second vote and dropping it early would let everybody vote twice. And while it has SUCCEEDED but not yet run, because that is exactly the window in which the kind has not read it yet — Execute is where a kind that pays its voters looks, so a stranger could otherwise empty the roll in the block before execution and leave the kind with nobody to pay. Waiting for the execution to land costs the reclaimer nothing; there is no deadline on this.

Render is the front page, or one proposal's page when path names an id.

notes are extra lines the consuming realm puts under the token and above the governance — who may mint, most of all, which is the realm's fact rather than the engine's and cannot be inferred from silence.

Passed in rather than stored. A stored note is a WRITE, and this is a read: a realm calling SetNotes from its own Render turned reading a page into something that costs storage, which is the defect check-storage exists to catch and did.

RollSize is how many addresses are on a proposal's voter roll.

Zero can mean two things and HasRoll separates them: nobody has voted yet, or the roll was reclaimed after the proposal finished.

SetElectorate changes where voting weight comes from, keeping everything else — the adopted kinds, every proposal, the slot cursor.

The consuming realm's, like Adopt, and for a narrow purpose: a realm that wraps its ledger to drop idle weight out of the quorum denominator swaps the wrapper in here rather than rebuilding the governor and losing its registry.

Only sensible before anything is open. A proposal snapshots the epoch it is weighed at but reads the electorate live, so changing it under an open vote moves the bar the voters were shown — which is the thing per-proposal rules exist to prevent, arrived at from the other side.

Settle advances a proposal's state and frees its slot if it is finished.

Needed because a read cannot persist: State and Render will tell you a proposal is defeated and tell you again tomorrow, since the transition they computed died with the query. Without a way to record it, the open list is a resource anybody can exhaust — fill every slot with proposals that will lose and nothing ever reclaims them.

Permissionless, because it decides nothing: it writes down a conclusion the rules already reached.

Snapshot is a proposal's engaged weight and the sealed epoch both it and the votes were read at — snapshotted at Propose and reachable no other way (EpochOf gives the epoch alone). Engaged is the turnout DENOMINATOR the pool is shown against; for a proposal opened with an absolute quorum floor the bar is that floor, not a fraction of engaged — read it with QuorumFloor. Scalars, so nothing is handed out to write through.

State advances the clock before answering, so a reader never sees a proposal that is active only because nobody has poked it.

StoredState is the state that has been WRITTEN DOWN, which is not always the state a reader is shown.

State computes the outcome from the rules and the clock, because a proposal whose deadline passed is decided whether or not anybody has poked it. Only a transaction records that, so between the deadline and the next Settle the two differ — and the difference is the whole reason reading is free: a read works out the answer and stores nothing.

A caller wanting to know whether the slot has actually been given back, or whether there is anything left for Settle to do, wants this one.

Sweep reclaims the slots of proposals that have finished but were never written down.

Propose already calls it when the board is full, which is the path that matters. This is the same thing on request, for a caller who would rather free a slot than be refused one — permissionless, like Settle, and for the same reason: it decides nothing, it only writes down what the rules already decided.

Tally is the vote so far: yes, no, abstain, and the supply they are weighed against.

The fourth number is the one worth having. Every bar here is a fraction — quorum of the snapshot supply, threshold of what was cast — so three counts without their denominator cannot be checked against anything. It is the supply at the proposal's snapshot epoch, not the supply now.

Timings is a proposal's clock: when it opened, when voting closes, when it becomes executable, and when that chance lapses. The companion to Tally — without it, anything showing a countdown parsed the page, which is prose written for people.

Two of these are zero rather than absent, and both zeroes mean something:

1ready == 0    the outcome is not recorded yet, so the timelock has not
2              started. Settle starts it, and anybody may call it.
3expires == 0  it never expires, which is what a grace period of zero means
4              everywhere else in this realm.

TimingsAt is Timings' wall-clock half: when the proposal opened and when voting closes, as unix seconds, or 0 for a proposal opened before the stamps.

A SIBLING RATHER THAN A WIDER Timings, because Timings is consumed by more than one realm and arity is the kind of change that should arrive with its readers rather than ahead of them. Its first reader lands in the same commit as this method — kourtv2's ClaimTimeline — which is the rule the clock plan applies to constants and which holds just as well for a read.

The heights stay on Timings and are still the reference; this is the number the gate actually compares against, so a page built from it cannot promise a close the governor will not honour.

Vote records a choice, weighed at the proposal's snapshot.

VoteOf is how an address voted, for a kind that has to pay them.

One address at a time, on purpose. A list of every voter is an unbounded return, and handing back the tree itself would be a live mutator holding this realm's authority — so payouts are pull-based: each claimant asks about themselves.

Answers only while the roll survives. It is dropped by ReleaseRoll, so a kind that pays out should either do it inside Do, where the roll is certainly intact, or tell its claimants that the window closes when somebody reclaims the deposit.

VoteWithCap is Vote where the consumer supplies a CEILING on the weight, and the engine still derives the weight itself and takes the lesser.

A CEILING, NEVER A WEIGHT, and the distinction is the whole reason this method is shaped like this. An earlier attempt added VoteWithWeight, which took the figure to tally. That was a permissionless verdict flip.

A supplied weight is not drawn from p.total, so `cast` could exceed it and `rest := p.total - cast` went NEGATIVE. Written out, the two early arms are

1early-succeed  yes*bps                    >= (total - abstain)*T
2early-defeat   (total - no - abstain)*bps  < (total - abstain)*T

because turnout is yes+no+abstain, so yes+no+rest is identically total-abstain. The damage was therefore an inflated NUMERATOR against a snapshotted denominator: `yes` could exceed anything the electorate held while (total - abstain) stayed put, passing on support that did not exist. And a negative rest shrinks (yes+rest), so the defeat arm could fire on a question still open.

AN EARLIER VERSION OF THIS COMMENT SAID the arm "reduced to yes*bps >= (total - abstain)*T, dropping `no` out of the test entirely". The identity above shows that reduction is not a symptom of anything: it holds always, and `no` is not in the early-succeed comparison and never was. The description was repeated in four files before the algebra was checked, which is what TestTheEarlyArmsIgnoreNoAndACapOnlyDelays now pins. Here the consumer can only LOWER what this package read for itself, so

1Σ w  ≤  Σ PastVotes(·, p.epoch)  ≤  PastTotal(p.epoch)  =  p.total

holds as an inequality rather than as a promise a caller has to keep. A hostile consumer cannot raise `cast`, and the contract electorate.gno says this engine "cannot check and cannot recover from" stays enforced where it lives.

NO SENTINEL. `cap <= 0` is refused, and Vote is the uncapped path. Treating zero as "uncapped" was tried in the plan for this change and reopened the exploit verbatim: a renter who has sold everything HAS a floor of zero, so zero is not an edge case, it is the attack's terminal state.

Why a consumer would want this: kourtv2 caps at the voter's live balance, so weight that has been sold back cannot vote. See VOTEFLOOR.md.

VoteWithReason is Vote with a note the voter wants on the record — the same pair OpenZeppelin has. Two entrypoints rather than one optional argument because MsgCall carries a fixed list of strings and gno has no optional parameters.

The reason is emitted and never stored: it rides the Voted event, so the voter pays gas for the bytes and the ledger carries none of them. Storing it would be a new key per vote, on the path this design keeps cheapest.

Bounded by maxReason. Not filtered through TextOnly, unlike a title: the realm never renders this on a page, so a consumer that displays it is responsible for its own escaping, as with any event field.