const MeterActive, MeterRetired
Meter status values.
meters source realm
Realm meters is usage-based billing with graduated marginal pricing: a provider publishes a METER (a unit of service,...
Realm meters is usage-based billing with graduated marginal pricing: a provider publishes a METER (a unit of service, a list price per unit, a billing period, and a tiers.Schedule of marginal volume discounts), a consumer ENROLLS and prepays a deposit, the provider RECORDS usage as it is served, and each period's accumulated usage settles from the consumer's deposit into the provider's claimable balance.
It is the usage-based complement to r/subscriptions' flat recurring plans — the one billing shape this portfolio lacked (its discovery gate's whole finding). The pricing identity is p/tiers':
Example
1base = units × unitPrice (checked int64 multiplication)
2due = Schedule.Charge(base) (≤ base — marginal discount off list)
tiers validates every rate into [0, RateScale], so Charge(base) ≤ base is an arithmetic fact: a schedule can DISCOUNT list price and can never surcharge it. A flat price is the one-rate schedule (no edges, rates "10000") — the degenerate case, not a second code path.
The three trust statements, in order of who bears what
- USAGE IS PROVIDER-ASSERTED, and that declaration is the trust boundary — the same boundary r/books draws at owner-posted entries and r/cashflow at Policy.Cash. The realm cannot verify off-chain consumption; what it does is make the assertion attributable (only the meter's provider may Record, and only against an enrollment to that meter), bounded (next statement), and auditable (every unit is an event and a readable row).
- LIABILITY IS BOUNDED BY DEPOSIT, fail-closed. Record refuses any posting whose end-of-period charge would exceed the enrollment's deposited balance, and a withdrawal leaves the pending charge covered. Charge is monotone in units (tiers' documented monotonicity), so the refusal predicate is well-defined. No arrears exist anywhere in this design: the realm never holds a claim against funds a consumer has not deposited.
- SETTLEMENT IS LAZY AND EXACT. Usage accumulates against the period it was recorded in; the first touch after a period boundary settles that period's charge. A period nobody recorded usage in owes zero, so lazy settlement loses nothing — there is no keeper, no upkeep dependency, and a Settle valve is permissionless so neither party's absence can wedge the other's funds.
Funds move on pull paths only: providers Claim, consumers WithdrawDeposit or Exit, the fee recipient WithdrawFees. Periods are fixed-length block windows anchored at Enroll height — runtime.ChainHeight() throughout, never a caller-supplied time (r/books' obligation, inherited verbatim).
REALM-CALLER CAVEAT, inherited from the siblings verbatim: coinio's receipt guard admits only EOA payers, so enrolling consumers are EOAs; assertNoSend reads the ORIGIN envelope, so every non-payable function refuses any transaction that attached coins anywhere. Providers may be EOAs or realms, but a realm provider must expose its own crossing path to Claim, or what it earns is stranded.
5
const EnrollActive, EnrollExited
Enrollment status values. Exited is terminal.
const MaxTitleLen, MaxUnitLen, MinUnitPrice, MaxUnitPrice, MinPeriodBlocks, MaxPeriodBlocks, MaxMetersPerProvider, MaxEnrollmentsPerConsumer, RenderLimit
1const (
2 MaxTitleLen = 80
3 MaxUnitLen = 24
4
5 // MinUnitPrice keeps a meter from being free-by-rounding; a provider
6 // who wants a free tier declares a 0-rate first tier instead, which
7 // keeps the arithmetic visible in the schedule rather than implicit
8 // in a zero price.
9 MinUnitPrice = int64(1)
10 // MaxUnitPrice keeps base = units × unitPrice far from int64
11 // overflow for any usage a deposit could plausibly cover; the
12 // checked multiplication is still there and still refuses.
13 MaxUnitPrice = int64(1_000_000_000) // 1000 GNOT per unit
14
15 // MinPeriodBlocks/MaxPeriodBlocks bound a meter's billing period —
16 // the same bounds and reasoning as r/subscriptions: the floor keeps
17 // settlement from becoming a per-block treadmill, the ceiling keeps
18 // period arithmetic far from overflow.
19 MinPeriodBlocks = int64(10)
20 MaxPeriodBlocks = int64(7500000)
21
22 // MaxMetersPerProvider bounds catalog monopolization by a single
23 // address — the finding that was RED in permission_registry and
24 // service_registry, carried from the start here.
25 MaxMetersPerProvider = 20
26
27 // MaxEnrollmentsPerConsumer bounds one account's open-enrollment
28 // state. Exited enrollments free their slot.
29 MaxEnrollmentsPerConsumer = 100
30
31 // RenderLimit bounds every rendered list — an unbounded Render was
32 // YELLOW in three prior audits.
33 RenderLimit = 20
34)Input bounds.
const Denom
Denom is the only asset this realm accepts.
const MaxFeeBps
MaxFeeBps is the hard protocol-fee cap: 1000 bps = 10%.
33
func AcceptAdmin
crossing ActionAcceptAdmin completes a staged admin transfer. Pending admin only.
func ActiveEnrollID
ActionActiveEnrollID resolves the caller-free (meter, consumer) index.
func BalanceOf
ActionBalanceOf is an enrollment's deposited balance as the LEDGER holds it — including a not-yet-settled elapsed period's charge; net view: subtract PendingChargeOf.
func ChargeHeadroomOf
ActionChargeHeadroomOf is how much MORE charge the current period could absorb before Record's deposit bound refuses: balance − pending charge.
func Claim
crossing ActionClaim sends amount ugnot of the caller's claimable balance back to the caller. Providers earn into this balance at every settlement.
func ClaimAll
crossing ActionClaimAll sends the caller's entire claimable balance back to the caller. Fails if there is nothing to claim.
func ClaimableOf
Actionfunc CreateMeter
crossing Action1func CreateMeter(cur realm, title, unit string, unitPrice, periodBlocks int64, edges, rates string, maxFeeBps int64) int64CreateMeter publishes a meter and returns its id. No coins are accepted; the storage deposit the caller pays is the anti-spam. edges and rates are comma-separated int64 lists building the tiers.Schedule over the ugnot BASE (units × unitPrice): len(rates) == len(edges)+1, each rate in [0, 10000] ten-thousandths of list price. "" edges with rates "10000" is a flat meter. The current protocol fee is snapshotted in and must not exceed maxFeeBps, the ceiling the provider signed for — pass MaxFeeBps to accept any legal fee. Meters are immutable once created: price, period or schedule changes are a new meter, so nothing a consumer agreed to can move underneath them.
func CurrentPeriodOf
ActionCurrentPeriodOf is the period index now open for an enrollment.
func Deposit
crossing ActionDeposit adds the attached coins to the caller's own enrollment deposit. Elapsed usage settles first, so a top-up lands on a current balance.
func Enroll
crossing ActionEnroll opens an enrollment on a meter for the caller, with any attached coins credited as the initial deposit. One active enrollment per (meter, consumer); Exit frees the slot. Terms (price, schedule, period, fee) are copied in at this moment and never re-read.
func Exit
crossing ActionExit closes the caller's own enrollment: elapsed periods settle, the CURRENT period's recorded usage settles immediately (the provider served it; exiting is not an escape from it), the remaining deposit refunds in full, and the slot frees. Terminal.
func FeeBps
Actionfunc FeesAccrued
Actionfunc Height
Actionfunc Held
Actionfunc Liabilities
Actionfunc NumEnrollments
Actionfunc NumMeters
Actionfunc PendingChargeOf
ActionPendingChargeOf is the charge the enrollment's current recorded usage would settle at — what WithdrawDeposit holds back.
func PriceOf
ActionPriceOf prices units of meter meterID at its schedule: the charge a period closing at exactly that usage would settle. The quote every consumer can take before enrolling and every provider can show beside an invoice.
func Record
crossing ActionRecord asserts that the enrollment's consumer used units more units of the meter's service in the CURRENT period. Provider only. Fail-closed on the deposit bound: if charging the period's new total at the enrollment's schedule would exceed the deposited balance, the whole posting is refused — never clipped, because a clipped assertion is a wrong assertion with the same signature as a right one. Any elapsed period settles first, so the bound is always measured against the balance that will actually back this period.
func Render
Render shows the catalog at "", a meter at "meter/<id>", an enrollment at "enroll/<id>". Every user string is sanitized; every list is bounded by RenderLimit with the bound stated.
func RetireMeter
crossing ActionRetireMeter stops NEW enrollments and NEW usage on the caller's own meter. Existing enrollments keep their funds paths whole: pending usage still settles, deposits stay withdrawable, Exit still refunds. The provider's meter slot frees. Terminal.
func ScheduleOf
ActionScheduleOf returns a meter's schedule as its edge and rate slices.
func SetFeeBps
crossing ActionSetFeeBps sets the protocol fee snapshotted into NEW meters. Admin only. No existing meter or enrollment moves.
func SetFeeRecipient
crossing ActionSetFeeRecipient points fee withdrawal and sweeps at recipient. Admin only.
func Settle
crossing ActionSettle settles any fully-elapsed period of an enrollment. Permissionless by design — like the sibling realms' valves, no settlement's liveness may depend on either party showing up. No coins may ride on it, and calling it on an enrollment with nothing elapsed is a refused no-op so the event stream never carries empty settlements.
func SweepDenom
crossing ActionSweepDenom 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.
func TransferAdmin
crossing ActionTransferAdmin stages successor as the next admin; AcceptAdmin completes it. Two-step with consent — a one-step transfer bricked resources in two prior audits (service_registry Y4, permission_registry Y4).
func UsersTotal
Actionfunc WithdrawDeposit
crossing ActionWithdrawDeposit returns amount of the caller's own enrollment deposit. The current period's pending charge stays covered: withdrawable is balance − Charge(current usage), so a provider's already-recorded usage can never be defunded. Elapsed usage settles first.
func WithdrawFees
crossing ActionWithdrawFees sends the accrued fee pot to the fee recipient. Only the fee recipient may call it, and only the pot moves.
