subscriptions state

Denom

Denom is the only asset this realm accepts.

MaxFeeBps

MaxFeeBps is the hard protocol-fee cap: 1000 bps = 10%.

PlanActive

Plan status values.

PlanRetired

Plan status values.

SubActive

Subscription status values. Cancelled and Expired are terminal.

SubCancelled

Subscription status values. Cancelled and Expired are terminal.

SubExpired

Subscription status values. Cancelled and Expired are terminal.

MaxTitleLen

Input bounds.

MaxDescLen

Input bounds.

MinPrice

Input bounds.

MinPeriodBlocks

Input bounds.

MaxPeriodBlocks

Input bounds.

MaxPlansPerProvider

Input bounds.

MaxSubsPerSubscriber

Input bounds.

RenderLimit

Input bounds.

plan

sub

admin

// may set fee, fee recipient, stage successor

pendingAdmin

// staged by TransferAdmin, completes via AcceptAdmin

feeRecipient

// may withdraw fees and sweep surplus

feeBps

// fee snapshotted into NEW plans

self

// this realm's address, captured at deploy

nextPlan

nextSub

plans

// padID(id) -> \*plan

subs

// padID(id) -> \*sub

activeByKey

// padID(planID)|subscriber -> int64 sub id, while Active

latestByKey

// padID(planID)|subscriber -> most recent sub id, never removed

providerNum

// address -> \*int64, live plans per provider

subNum

// address -> \*int64, Active subs per subscriber

ledger

init.31

CreatePlan

CreatePlan publishes a subscription plan and returns its id. No coins are accepted; the storage deposit the caller pays is the anti-spam. The current protocol fee is snapshotted into the plan and must not exceed maxFeeBps, the ceiling the provider signed for — pass MaxFeeBps to accept any legal fee. Plans are immutable once created: price and period changes are a new plan, so nothing a subscriber agreed to can move underneath them.

RetirePlan

RetirePlan takes a plan off the market: no new subscriptions and no renewals. Provider only. Existing entitlements run to their paidThrough untouched; refusing renewals is subscriber protection — nobody keeps paying for a service whose provider announced its end. The provider's plan-quota slot frees.

Subscribe

Subscribe pays for the first billing period of a plan and returns the new subscription id. The transaction must attach EXACTLY the plan's price in ugnot — over- and underpayment are both refused, so a mistaken double-attach cannot silently become a donation. One subscriber holds at most one live subscription per plan: if an Active one exists the call is refused (the renewal path is Renew, never a second Subscribe — that is the duplicate-payment guard at the identity level); an incumbent past its grace window is collapsed to Expired in place, so a fresh start never waits on housekeeping. The payment settles immediately: price minus the plan's snapshotted fee to the provider's claimable balance, fee to the protocol pot. Entitlement runs from this block: paidThrough = height + periodBlocks.

Renew

Renew pays for the next billing period of the caller's own subscription. The transaction must attach exactly the subscription's price. The renewal window is deterministic and stated in the header: accepted iff paidThrough - height \<= periodBlocks (at most one full unstarted period prepaid — the duplicate-payment bound) and height \< paidThrough + periodBlocks (the grace bound, exclusive — a renewal always buys at least one block). Extension is always FROM paidThrough, so period boundaries never drift, and a renewal inside grace covers the lapsed span — that is the price of keeping the original schedule, and it is the documented, deterministic choice.

Cancel

Cancel ends the caller's own subscription. Terminal: it can never be renewed afterwards, by anyone. No refund and no funds move — every payment settled when it was made, and the entitlement already bought (height \< paidThrough) remains until it runs out. The plan slot and the subscriber's quota slot free immediately.

Expire

Expire marks a lapsed subscription Expired once its grace window is over: height >= paidThrough + periodBlocks. Permissionless by design — like the sibling realms' valves, no slot's liveness may depend on either party showing up. No funds move.

Claim

Claim sends amount ugnot of the caller's claimable balance back to the caller. Providers earn into this balance at every payment.

ClaimAll

ClaimAll sends the caller's entire claimable balance back to the caller. Fails if there is nothing to claim.

WithdrawFees

WithdrawFees sends the accrued fee pot to the fee recipient. Only the fee recipient may call it, and only the pot moves.

SweepDenom

SweepDenom recovers out-of-band coins (sent by raw bank transfer, outside any entrypoint) to the fee recipient. For the ledger denom the reserve is Liabilities() — user balances and the fee pot are structurally unreachable. Fee recipient only.

SetFeeBps

SetFeeBps sets the protocol fee snapshotted into FUTURE plans. Bounded by MaxFeeBps; existing plans and subscriptions are untouched — their fee was fixed the moment the provider consented to it.

SetFeeRecipient

SetFeeRecipient points future fee withdrawals and sweeps at a new address. Admin only. The zero address is refused — it would strand the pot.

TransferAdmin

TransferAdmin stages a two-step admin handover. The successor holds nothing until AcceptAdmin.

AcceptAdmin

AcceptAdmin completes the handover; only the staged successor may.

Entitled

Entitled reports whether the subscription's paid entitlement covers the current block: height \< paidThrough. Status deliberately does not enter into it — a cancelled subscriber keeps what they paid for, and an expirable-but-unexpired one has already lapsed here.

EntitledFor

EntitledFor reports whether subscriber currently holds paid entitlement to planID, through their MOST RECENT subscription to it. This is the one-call integration surface for other realms and services, and it honors the entitlement contract across status: a cancelled subscription keeps answering true until its paidThrough — what was bought stays bought (audit finding Y1). One self-inflicted edge is fail-closed: cancelling a prepaid subscription and re-subscribing at once points this surface at the NEW, earlier paidThrough; the old subscription's remaining span stays queryable per-id via Entitled.

ActiveSubID

ActiveSubID returns the caller-facing id of subscriber's live subscription to planID, or (0, false) if none is Active.

PlanInfo

SubInfo

PaidThrough

PaidThrough returns the absolute height a subscription is paid to.

RenewableFrom

RenewableFrom returns the earliest height at which Renew will accept a payment for this subscription, and the last height at which it still will (inclusive) — the deterministic window, precomputed for integrators. From until+1 the subscription is expirable instead; the two sets partition exactly.

Admin

PendingAdmin

FeeRecipient

FeeBps

NumPlans

NumSubs

UsersTotal

FeesAccrued

Liabilities

BalanceOf

Address

Held

Render

renderHome

expireInPlace

expireInPlace flips an Active subscription to Expired and frees its slots. Callers have already established expirability.

releaseSlots

releaseSlots removes the plan|subscriber activity index entry and decrements the subscriber's quota counter. Exactly once per terminal transition, which both terminal paths guarantee by requiring SubActive first.

assertNoSend

assertAdmin

mustGetPlan

mustGetSub

counter

counter returns the persistent per-address counter in tree, allocating a zero on first use.

padID

itoa