doc.gno

 1// Package subscription provides recurring and lifetime subscription
 2// primitives. Payment is pulled through a caller-supplied
 3// *allowancesender.AllowanceSender (a cap-token whose construction is
 4// gated on banker.IsCanonical, so the lib can rely on Send actually
 5// moving real coins). Subscriber identity is decoupled from cap-token
 6// authority; the lib does not inspect call-chain shape.
 7//
 8// Each subscription instance locks its payment destination at
 9// construction time (payeeAddr) and pulls a fixed per-period amount
10// from the cap on each Subscribe call. A leaked struct pointer cannot
11// redirect payment.
12//
13// Recurring Subscription:
14//
15//	// In the consumer realm, at deployment:
16//	var recSub = recurring.NewRecurringSubscription(
17//	    time.Hour*24*30,                    // 30-day periods
18//	    100,                                // 100 ugnot per period
19//	    runtime.CurrentRealm().Address(),   // payee = this realm
20//	)
21//
22//	// Wrapper exposed to users. The wrapper builds an AllowanceSender
23//	// from a real banker, defers Close, and forwards the call. Subscribe
24//	// pulls 100 ugnot from the consumer realm (whose -send envelope
25//	// the wrapper validated) and records `subscriber` as active until
26//	// time.Now() + 30 days.
27//	func Subscribe(_ realm, subscriber address) {
28//	    if !runtime.PreviousRealm().IsUserCall() { panic("EOA only") }
29//	    src := banker.NewBanker(banker.BankerTypeRealmSend)
30//	    al := allowancesender.New(src, runtime.CurrentRealm().Address(),
31//	        chain.NewCoins(chain.NewCoin("ugnot", recSub.GetAmount())))
32//	    defer al.Close()
33//	    if err := recSub.Subscribe(al, subscriber); err != nil {
34//	        panic(err)
35//	    }
36//	}
37//
38// Lifetime Subscription:
39//
40//	var lifeSub = lifetime.NewLifetimeSubscription(
41//	    500,                                // 500 ugnot one-time
42//	    runtime.CurrentRealm().Address(),
43//	)
44//
45//	// Same wrapper shape as recurring.
46//
47// Both libraries trust whatever address the consumer's wrapper passes
48// as `subscriber` — the wrapper's policy decides who's allowed to
49// register, who can be gifted, etc. Self-Subscribe and gift collapse
50// into the same call with different `subscriber` arguments.
51package subscription