Package subscriptions is a multi-provider subscription hub: providers publish plans priced per billing period; subscribers pay per period, with deterministic renewal, grace, expiration and cancellation rules; other realms and off-chain services gate access on Entitled / EntitledFor, which is the integration surface this realm exists to provide.
THE BILLING MODEL, COMPLETELY:
Example
1Subscribe (payable, exact price) : creates the subscription, pays
2 period 1. paidThrough = height
3 + periodBlocks.
4Renew (payable, exact price) : extends paidThrough by exactly
5 one periodBlocks, FROM
6 paidThrough — never from the
7 current height — so period
8 boundaries are fixed at
9 Subscribe time and never drift.
10Entitlement : height < paidThrough. Nothing
11 else. Status does not enter
12 into it: a cancelled
13 subscription stays entitled to
14 what it already paid for.
15Renewal window : a renewal is accepted iff BOTH
16 paidThrough - height <= periodBlocks (early bound)
17 height < paidThrough + periodBlocks (late bound)
18 The early bound caps prepayment
19 at one full unstarted period —
20 a second Renew straight after a
21 first is refused, which is what
22 makes an accidental duplicate
23 payment structurally impossible
24 rather than merely unlikely.
25 The late bound is the grace
26 window: renewing after lapse
27 extends from paidThrough, so it
28 back-pays the lapsed span to
29 keep the original schedule and
30 buys paidThrough + periodBlocks
31 - height further blocks — always
32 at least one, because the bound
33 is exclusive (audit finding Y2).
34 A lapsed subscriber who prefers
35 a fresh full period may Cancel
36 and Subscribe again at the same
37 total price; Subscribe's refusal
38 message states both options.
39Expire (permissionless valve) : once height >= paidThrough +
40 periodBlocks, anyone may mark
41 the subscription Expired. No
42 funds move — every payment
43 settled when it was made. The
44 valve exists so the
45 plan|subscriber slot frees
46 without depending on either
47 party, and Subscribe itself
48 collapses an expired incumbent,
49 so a fresh start never depends
50 on housekeeping having run. The
51 renewable and expirable height
52 sets partition exactly: no
53 height is in both or neither.
54Cancel (subscriber only) : Active -> Cancelled. Terminal.
55 No refund — payments settle to
56 the provider at payment time,
57 and what was bought (entitlement
58 through paidThrough) stays
59 bought. What cancellation ends
60 is the OBLIGATION: a Cancelled
61 subscription can never be
62 renewed, by the subscriber or
63 anyone else.
64RetirePlan (provider only) : no new Subscribes, no renewals.
65 Existing entitlements run to
66 paidThrough untouched. Refusing
67 renewals on a retired plan is
68 subscriber protection: nobody
69 can keep paying for a service
70 whose provider announced its
71 end.
The obligation is therefore explicit on chain at every moment: a subscription owes nothing (there is no pull payment and no debt — a lapse simply ends entitlement), and the realm owes the subscriber exactly `paidThrough - height` blocks of entitlement, queryable by anyone via PaidThrough / Entitled / EntitledFor.
WHO PAYS WHOM. Payments settle immediately: price - fee is credited to the provider's claimable balance, fee to the protocol pot, both inside the same feeledger the sibling realms use. There is no escrow: H == U + F at all times (plus out-of-band surplus, recoverable by SweepDenom above the Liabilities reserve). The renewal caller must be the subscriber — a third party cannot extend someone else's subscription, which closes both a consent problem (an unwanted gift re-arms a lapsing obligation) and a griefing edge (spending pennies to keep a victim's slot occupied).
FEES follow the house pattern exactly: a compile-time MaxFeeBps ceiling, the current fee snapshotted into the PLAN at CreatePlan (provider consents via its own maxFeeBps argument), copied into the subscription at Subscribe, and charged at every payment from the PROVIDER's side. A later SetFeeBps touches only plans created afterwards; no existing plan or subscription can have its fee moved by anyone.
REALM-CALLER CAVEAT, inherited from the siblings verbatim: coinio's receipt guard admits only EOA payers, so subscribers 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 (see RegisterService's caveat in service_market — the same three obligations apply).
