meters

gnokey query vm/qeval \
  --data 'gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/meters.FeeBps()' \
  --remote https://rpc.onyx.testnets.gno.land:443

import "gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/meters"

curl -sS 'https://onyx.testnets.gno.land/r/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/meters$download&file=meters.gno' | shasum -a 256

Overview

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':

base = units × unitPrice (checked int64 multiplication) due = 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.

Imports

• chain
• chain/runtime
• chain/runtime/unsafe
• gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/coinio
• gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/feeledger
• gno.land/p/g1ut6uspuh73e02yauxpmyt8g3wwddaq8utagvm3/tiers
• gno.land/p/nt/avl/v0
• gno.land/p/nt/markdown/sanitize/v0
• strconv

Constants and variables

Meter status values.

const (
	MeterActive  = "active"
	MeterRetired = "retired"
)

Enrollment status values. Exited is terminal.

const (
	EnrollActive = "active"
	EnrollExited = "exited"
)

Input bounds.

const (
	MaxTitleLen = 80
	MaxUnitLen  = 24

	// MinUnitPrice keeps a meter from being free-by-rounding; a provider
	// who wants a free tier declares a 0-rate first tier instead, which
	// keeps the arithmetic visible in the schedule rather than implicit
	// in a zero price.
	MinUnitPrice = int64(1)
	// MaxUnitPrice keeps base = units × unitPrice far from int64
	// overflow for any usage a deposit could plausibly cover; the
	// checked multiplication is still there and still refuses.
	MaxUnitPrice = int64(1_000_000_000) // 1000 GNOT per unit

	// MinPeriodBlocks/MaxPeriodBlocks bound a meter's billing period —
	// the same bounds and reasoning as r/subscriptions: the floor keeps
	// settlement from becoming a per-block treadmill, the ceiling keeps
	// period arithmetic far from overflow.
	MinPeriodBlocks = int64(10)
	MaxPeriodBlocks = int64(7500000)

	// MaxMetersPerProvider bounds catalog monopolization by a single
	// address — the finding that was RED in permission_registry and
	// service_registry, carried from the start here.
	MaxMetersPerProvider = 20

	// MaxEnrollmentsPerConsumer bounds one account's open-enrollment
	// state. Exited enrollments free their slot.
	MaxEnrollmentsPerConsumer = 100

	// RenderLimit bounds every rendered list — an unbounded Render was
	// YELLOW in three prior audits.
	RenderLimit = 20
)

Denom is the only asset this realm accepts.

const Denom = "ugnot"

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

const MaxFeeBps = int64(1000)

Functions

AcceptAdmin

func AcceptAdmin(cur realm)

Crossing function. Callable from a transaction via MsgCall, and from another realm as AcceptAdmin(cross(cur), ...).

AcceptAdmin completes a staged admin transfer. Pending admin only.

ActiveEnrollID

func ActiveEnrollID(meterID int64, consumer address) (int64, bool)

ActiveEnrollID resolves the caller-free (meter, consumer) index.

BalanceOf

func BalanceOf(enrollID int64) int64

BalanceOf is an enrollment's deposited balance as the LEDGER holds it — including a not-yet-settled elapsed period's charge; net view: subtract PendingChargeOf.

ChargeHeadroomOf

func ChargeHeadroomOf(enrollID int64) int64

ChargeHeadroomOf is how much MORE charge the current period could absorb before Record's deposit bound refuses: balance − pending charge.

Claim

func Claim(cur realm, amount int64)

Crossing function. Callable from a transaction via MsgCall, and from another realm as Claim(cross(cur), ...).

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

ClaimAll

func ClaimAll(cur realm)

Crossing function. Callable from a transaction via MsgCall, and from another realm as ClaimAll(cross(cur), ...).

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

ClaimableOf

func ClaimableOf(a address) int64

CreateMeter

func CreateMeter(cur realm, title, unit string, unitPrice, periodBlocks int64, edges, rates string, maxFeeBps int64) int64

Crossing function. Callable from a transaction via MsgCall, and from another realm as CreateMeter(cross(cur), ...).

CreateMeter 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.

CurrentPeriodOf

func CurrentPeriodOf(enrollID int64) int64

CurrentPeriodOf is the period index now open for an enrollment.

Deposit

func Deposit(cur realm, enrollID int64)

Crossing function. Callable from a transaction via MsgCall, and from another realm as Deposit(cross(cur), ...).

Deposit adds the attached coins to the caller's own enrollment deposit. Elapsed usage settles first, so a top-up lands on a current balance.

Enroll

func Enroll(cur realm, meterID int64) int64

Crossing function. Callable from a transaction via MsgCall, and from another realm as Enroll(cross(cur), ...).

Enroll 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.

Exit

func Exit(cur realm, enrollID int64)

Crossing function. Callable from a transaction via MsgCall, and from another realm as Exit(cross(cur), ...).

Exit 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.

FeeBps

func FeeBps() int64

FeesAccrued

func FeesAccrued() int64

Height

func Height() int64

Held

func Held() int64

Liabilities

func Liabilities() int64

NumEnrollments

func NumEnrollments() int64

NumMeters

func NumMeters() int64

PendingChargeOf

func PendingChargeOf(enrollID int64) int64

PendingChargeOf is the charge the enrollment's current recorded usage would settle at — what WithdrawDeposit holds back.

PriceOf

func PriceOf(meterID, units int64) int64

PriceOf 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.

Record

func Record(cur realm, enrollID, units int64)

Crossing function. Callable from a transaction via MsgCall, and from another realm as Record(cross(cur), ...).

Record 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.

Render

func Render(path string) string

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.

RetireMeter

func RetireMeter(cur realm, meterID int64)

Crossing function. Callable from a transaction via MsgCall, and from another realm as RetireMeter(cross(cur), ...).

RetireMeter 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.

ScheduleOf

func ScheduleOf(meterID int64) (edges, rates []int64)

ScheduleOf returns a meter's schedule as its edge and rate slices.

SetFeeBps

func SetFeeBps(cur realm, bps int64)

Crossing function. Callable from a transaction via MsgCall, and from another realm as SetFeeBps(cross(cur), ...).

SetFeeBps sets the protocol fee snapshotted into NEW meters. Admin only. No existing meter or enrollment moves.

SetFeeRecipient

func SetFeeRecipient(cur realm, recipient address)

Crossing function. Callable from a transaction via MsgCall, and from another realm as SetFeeRecipient(cross(cur), ...).

SetFeeRecipient points fee withdrawal and sweeps at recipient. Admin only.

Settle

func Settle(cur realm, enrollID int64)

Crossing function. Callable from a transaction via MsgCall, and from another realm as Settle(cross(cur), ...).

Settle 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.

SweepDenom

func SweepDenom(cur realm, denom string)

Crossing function. Callable from a transaction via MsgCall, and from another realm as SweepDenom(cross(cur), ...).

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.

TransferAdmin

func TransferAdmin(cur realm, successor address)

Crossing function. Callable from a transaction via MsgCall, and from another realm as TransferAdmin(cross(cur), ...).

TransferAdmin 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).

UsersTotal

func UsersTotal() int64

WithdrawDeposit

func WithdrawDeposit(cur realm, enrollID, amount int64)

Crossing function. Callable from a transaction via MsgCall, and from another realm as WithdrawDeposit(cross(cur), ...).

WithdrawDeposit 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.

WithdrawFees

func WithdrawFees(cur realm)

Crossing function. Callable from a transaction via MsgCall, and from another realm as WithdrawFees(cross(cur), ...).

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

---

Doc text is reproduced as vm/qdoc returns it. The node markdown-escapes doc comments, so a bracket or angle bracket may carry a backslash the committed source does not have. The source itself is at source and in this repository.