access state

owner

priceUsdCents

periodSec

creditsPerUsdCent

maxTopUpUgnot

quoteUgnot

// ugnot for one period

quotedAt

// when it was posted

prevUgnot

prevUntil

quoteTtlSec

quoteGraceSec

quoteGraceBand

pendingOwner

operator

subs

// addr -> expiry (unix)

credits

// addr -> credit balance

settled

Subscribe

Subscribe buys pro time for the caller at the live quote. Each whole quote sent buys one period; anything left over becomes units at the same rate a top-up gets, rather than being kept, so the payer keeps the value of every ugnot they sent. Every call is priced at the quote in force when it executes, so a renewal costs what a period costs today. Pinning a renewal to the price paid at first purchase is a known trap: Unlock Protocol does it and a renewal simply reverts once the price has moved.

subscribe

subscribe holds the money math, separate from the origin/caller plumbing above so it can be exercised directly (AssertOriginCall cannot be satisfied from a test frame).

Login

Login does nothing. Sign-In-With-Gno signs (never broadcasts) a call to it so the wallet shows a "Login" to GnoPulse rather than a token transfer; the challenge nonce rides in the tx memo.

TopUp

TopUp buys prepaid credits for the caller.

topUp

topUp converts the payment to units at the SAME quote the subscription uses, so a credit is worth the same in dollars whatever GNOT is doing. Paying in GNOT, priced in USD.

unitsFor

unitsFor converts a ugnot payment into API units at a given quote. The payment is worth paid/price of a period, a period costs priceUsdCents, and one cent buys creditsPerUsdCent units. One helper so a top-up and the change from a subscription can never diverge.

HasAccess

TierOf

CreditsOf

ExpiresAt

SettledOf

Owner

Config

Consume

Consume charges an address for metered API usage, up to a cumulative cost-unit total. The owner passes the caller's running lifetime usage, not a delta: the realm keeps the watermark itself and charges only the part it has not charged before. That makes the call idempotent (a replay is rejected, not re-billed) and means a restored or rolled-back off-chain database cannot double-charge anyone. A caller with too few credits is charged what they have and the watermark still advances; the event records both what was owed and what was actually taken, so a shortfall is visible rather than silently forgiven.

consume

Forgive

Forgive advances the billing watermark without charging: usage already covered by an active time-based subscription. Separate from Consume so that "we decided not to bill this" is its own auditable on-chain act rather than an invisible gap in the watermark.

forgive

SetQuote

SetQuote posts the price of one period in ugnot. Called on a short schedule by the job that already tracks the GNOT price, which converts priceUsdCents off chain and publishes only the result. The previous quote stays payable for quoteGraceSec so payments already in flight are not repriced.

setQuote

Quote

Quote is what the payment page reads: the amount to send for one period, and the moment it stops being honoured. Reading it from here rather than from a price feed is what makes the figure on screen and the figure charged the same number.

currentPrice

currentPrice is what Subscribe charges. While a superseded quote is still inside its grace window both are live, and the payer is charged the lower of the two: we cannot tell which one they were shown, and charging the lower one guarantees it is never more than they saw.

SetConfig

setConfig

Withdraw

TransferOwnership

TransferOwnership OFFERS the realm to newOwner. It does not hand it over: the offer stands until that address claims it with AcceptOwnership. A mistyped address therefore costs nothing, where a single-step transfer would have locked every admin function and the revenue behind an address nobody holds, permanently, because the realm cannot be redeployed.

transferOwnership

transferOwnership holds the offer itself, split from the owner gate above for the same reason subscribe is split from Subscribe: assertOwner cannot be satisfied from a test frame.

CancelOwnershipTransfer

CancelOwnershipTransfer withdraws a standing offer.

AcceptOwnership

AcceptOwnership completes the handover. Only the offered address can call it, which proves the key exists and can sign before anything irreversible happens.

acceptOwnership

PendingOwner

SetOperator

SetOperator appoints, rotates or (with an empty address) revokes the hot role. One step, unlike TransferOwnership, and the asymmetry is deliberate: a mistyped owner is permanent and locks the revenue, while a mistyped operator only means quotes stop until the owner sets it again. Making revocation a two-step handshake would be worse than useless, since the address being revoked is the one you no longer trust to act.

setOperator

Operator

assertOwner

assertOwner requires a DIRECT call from the owner. cur.Previous() is the immediate caller, so a relaying realm (owner -> X -> here) would fail this, no separate origin assert needed.

isOperator

isOperator is the routine-work gate as a pure predicate, so it is unit-testable: assertOperator below cannot be satisfied from a test frame, exactly as assertOwner cannot. The owner always passes. A fresh deploy has no operator yet, so the owner must be able to post the first quote or the realm is unusable until one is appointed, and the owner must be able to take over the moment an operator is revoked.

assertOperator

assertOperator gates the two jobs that run on a schedule. Everything that moves money or changes the terms stays behind assertOwner, including Forgive, which is the repair for an operator that over-charges and therefore must never be reachable by one.

Render

usd

usd renders cents as dollars, keeping the two decimal places (2500 -> "25.00", 2505 -> "25.05").