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.
