spendbook.gno
24.44 Kb · 687 lines
1// Package spendbook is a pure allowance primitive for realms that need to
2// let one party spend another party's funds, up to a bounded amount, over
3// many transactions. It is to *delegated spending* what duebook is to
4// *time*: it holds no coins, performs no effects, imports no chain APIs,
5// and owns no package-level state. The importing realm owns a *Book,
6// supplies the clock, and performs its own effects.
7//
8// # Why this package exists
9//
10// The ecosystem's existing allowance primitive,
11// gno.land/p/jaekwon/allowancesender/v0, is scoped to a single call and
12// says so in its own documentation:
13//
14// "Allowance survives across N txs but not N+1 txs." Use a session
15// counter pattern in the granter realm; this package's Close is
16// binary, not deadline-based.
17//
18// It then declines block-height expiry on the grounds that it "would
19// require runtime cooperation". That is true only for a package that reads
20// the clock itself. spendbook does not: every operation takes `now` as an
21// argument, which makes the window arithmetic a pure function and the
22// whole package unit-testable without a chain. Three application realms in
23// the searched sources each hand-rolled this mechanism internally rather
24// than importing one; see DISCOVERY.md.
25//
26// # The one idea
27//
28// An allowance is not a balance. It is a *permission with a ceiling that
29// refills*. The owner says "this spender may draw at most PerPeriod per
30// window, at most Total ever, until ExpiresAt, and I can revoke it now":
31//
32// if err := book.Spend(id, spenderKey, now, amount); err != nil {
33// panic(err) // revoked, expired, over the window cap, over the total
34// }
35// // ... the realm moves the coins here, under its own authority
36//
37// Spend checks every bound and CONSUMES the allowance in the same call,
38// before returning. The realm then acts. Because the realm performs the
39// effect itself, no closure, callback, or capability ever crosses a realm
40// boundary. spendbook cannot be handed code to run, so it cannot be
41// tricked into running the wrong code.
42//
43// # Windows are anchored, not sliding
44//
45// A window is derived from a fixed origin — the Anchor set at Open — by
46// integer division:
47//
48// index(now) = (now - Anchor) / PeriodLength
49//
50// so the boundaries are the same for everyone and a spender cannot reset a
51// window by choosing when to call. A sliding "PerPeriod per trailing N
52// blocks" window would let a spender draw the full cap at the end of one
53// trailing span and again at the start of the next; anchoring removes the
54// choice. The refill is a RESET, not a carry: an unused allowance does not
55// accumulate into the next window, because the point of the cap is to bound
56// worst-case loss per window, and a carry would unbound it.
57//
58// PeriodLength == 0 means one window that never rolls: a pure lifetime
59// allowance, where PerPeriod is the only cap that matters.
60//
61// # Amendments cannot enlarge the live window
62//
63// An owner who could raise PerPeriod mid-window would be able to undo the
64// bound a spender is relying on, and — worse in the other direction — an
65// owner who drains a relationship and then lowers terms retroactively
66// could strand a spender mid-settlement. The rule here is one-sided and
67// enforced in Amend:
68//
69// - TIGHTER-OR-EQUAL terms apply IMMEDIATELY. Lowering a ceiling can
70// never authorize a draw that was not already authorized, so there is
71// no reason to delay it, and delaying it would make the owner's only
72// fast remedy Revoke.
73// - LOOSER terms are PENDING and take effect at the next window
74// boundary, never inside the current one.
75//
76// This is the same adversarial problem that r/samcrew/agent_registry_v2
77// solves by locking its price while any credit entry exists; the shape
78// here is a deferral rather than a lock, so terms can still move.
79//
80// With PeriodLength == 0 there is no next boundary, so a loosening
81// amendment is refused with ErrNoBoundary rather than silently queued
82// forever. PeriodLength itself is IMMUTABLE: changing it would move every
83// future boundary, which is an enlargement vector wearing a different hat.
84//
85// # State growth
86//
87// Revoked allowances are removed, not archived. IDs are allocated
88// monotonically and never reused, so a revoked ID can never be resurrected
89// and there is nothing to keep. Live allowances are capped per Book at
90// construction, so storage is bounded by maxLive regardless of how many
91// allowances have ever existed. Audit history belongs in the consuming
92// realm's events.
93//
94// An EXPIRED allowance is not self-removing, and bounded storage is not the
95// same as a usable Book: Spend refuses it forever while it still holds a
96// slot. Reap exists for exactly that and is permissionless, because an
97// expired allowance can authorize nothing and so removing it takes nothing
98// from anyone.
99//
100// What this package does NOT bound is how many of a Book's slots ONE owner
101// may hold — maxLive is a single global figure, so any owner permitted to
102// Open can exhaust it and lock out the rest. That is a policy question with
103// no answer a primitive can pick (per-owner quota? first-come? owner
104// whitelist?), so it is left where the authentication already lives: the
105// consuming realm decides who may Open, and a Book shared across mutually
106// untrusting owners needs its own per-owner cap on top of this one. Named
107// here rather than implied, because "bounded" reads like "safe to share".
108//
109// # Consumer contract (the parts the package cannot enforce)
110//
111// 1. SUPPLY A REAL CLOCK. spendbook cannot verify that `now` came from
112// runtime.ChainHeight() or time.Now().Unix(). A realm that lets a
113// caller choose `now` has handed the spender the power to roll the
114// window at will, which defeats every cap in this package. Pass the
115// chain's own clock, and use the same units for the life of the Book.
116//
117// 2. AUTHENTICATE THE SPENDER KEY. spendbook compares the key string it
118// is given against the one recorded at Open. It cannot tell whether
119// that string is the real caller. Derive it from
120// cur.Previous().Address(), never from an argument the caller supplies.
121//
122// 3. SPEND BEFORE SENDING. Spend consumes the allowance and returns; the
123// realm then moves coins. Doing it in the other order means a failed
124// send leaves the allowance consumed, or a successful send leaves it
125// unconsumed — both are real losses. State first, effect second.
126//
127// 4. AN ALLOWANCE IS NOT CUSTODY. spendbook authorizing 100 does not mean
128// 100 exists. The realm must check its own held balance separately;
129// this package bounds permission, not solvency.
130package spendbook
131
132import (
133 "errors"
134 "strconv"
135
136 "gno.land/p/nt/avl/v0"
137)
138
139// MaxLiveLimit is the largest maxLive a Book may be constructed with. It
140// bounds the worst-case cost of Iterate, which scans the live set.
141const MaxLiveLimit = 10000
142
143// MaxKeyLen bounds an owner or spender key. A bech32 gno address is 40
144// characters; the headroom exists so a realm may namespace its keys.
145const MaxKeyLen = 128
146
147// maxInt64 is the overflow boundary for every accumulation here.
148const maxInt64 = int64(1<<63 - 1)
149
150// Errors returned by Book operations.
151var (
152 ErrInvalidConfig = errors.New("spendbook: invalid book configuration")
153 ErrEmptyOwner = errors.New("spendbook: empty owner key")
154 ErrEmptySpender = errors.New("spendbook: empty spender key")
155 ErrKeyTooLong = errors.New("spendbook: key exceeds MaxKeyLen")
156 ErrInvalidNow = errors.New("spendbook: now must be non-negative")
157 ErrInvalidTerms = errors.New("spendbook: invalid terms")
158 ErrInvalidAmount = errors.New("spendbook: amount must be positive")
159 ErrBookFull = errors.New("spendbook: live allowance cap reached")
160 ErrNotFound = errors.New("spendbook: no such live allowance")
161 ErrNotExpired = errors.New("spendbook: allowance has not expired")
162 ErrNotOwner = errors.New("spendbook: caller does not own this allowance")
163 ErrNotSpender = errors.New("spendbook: caller is not this allowance's spender")
164 ErrExpired = errors.New("spendbook: allowance has expired")
165 ErrNotStarted = errors.New("spendbook: allowance has not started")
166 ErrPeriodExceeded = errors.New("spendbook: amount exceeds the window cap")
167 ErrTotalExceeded = errors.New("spendbook: amount exceeds the lifetime cap")
168 ErrNoBoundary = errors.New("spendbook: no reachable next window boundary")
169 ErrOverflow = errors.New("spendbook: int64 overflow")
170 ErrIDExhausted = errors.New("spendbook: identifier space exhausted")
171)
172
173// Terms are the ceilings on an allowance. Zero has a distinct meaning in
174// three of the four fields and it is never "zero allowed":
175//
176// PerPeriod > 0 required. The cap per window.
177// PeriodLength 0 means ONE window that never rolls (lifetime).
178// Total 0 means no lifetime cap.
179// ExpiresAt 0 means no expiry.
180type Terms struct {
181 PerPeriod int64
182 PeriodLength int64
183 Total int64
184 ExpiresAt int64
185}
186
187// valid reports whether the terms are self-consistent, given the anchor the
188// allowance is (or would be) opened at.
189func (t Terms) valid(anchor int64) bool {
190 if t.PerPeriod <= 0 || t.PeriodLength < 0 || t.Total < 0 {
191 return false
192 }
193 if t.ExpiresAt < 0 {
194 return false
195 }
196 // An allowance that has already expired at its own anchor can never
197 // authorize anything, so accepting it would only create a live entry
198 // that every Spend refuses.
199 if t.ExpiresAt != 0 && t.ExpiresAt <= anchor {
200 return false
201 }
202 // A Total below PerPeriod is not an error -- it is a narrower lifetime
203 // cap, which Spend enforces. A Total of exactly 0 is "unlimited".
204 return true
205}
206
207// tighterOrEqualTo reports whether t is weakly tighter than u in every
208// dimension, i.e. whether t can authorize nothing u would not have. This is
209// the predicate that decides whether an amendment applies immediately.
210//
211// The zero-means-unlimited fields invert the comparison, which is the whole
212// subtlety: Total 0 is LOOSER than any positive Total, and ExpiresAt 0 is
213// LOOSER than any positive ExpiresAt. Reading those two as "smaller is
214// tighter" would let an owner remove a lifetime cap and an expiry
215// mid-window and call it a tightening.
216func (t Terms) tighterOrEqualTo(u Terms) bool {
217 if t.PeriodLength != u.PeriodLength {
218 return false // immutable; see the package doc
219 }
220 if t.PerPeriod > u.PerPeriod {
221 return false
222 }
223 switch {
224 case u.Total == 0:
225 // u was unlimited; anything is tighter or equal.
226 case t.Total == 0 || t.Total > u.Total:
227 return false
228 }
229 switch {
230 case u.ExpiresAt == 0:
231 // u never expired; any expiry is tighter or equal.
232 case t.ExpiresAt == 0 || t.ExpiresAt > u.ExpiresAt:
233 return false
234 }
235 return true
236}
237
238// Allowance is one owner's grant to one spender. It is returned BY VALUE:
239// holders cannot reach into a Book through it.
240type Allowance struct {
241 ID uint64
242 Owner string
243 Spender string
244 Terms Terms
245 Anchor int64 // window origin; also the earliest spendable instant
246 CreatedAt int64
247
248 SpentTotal int64 // over the allowance's whole life
249 SpentWindow int64 // within WindowIndex
250 WindowIndex int64
251
252 // Pending terms, applied at the next window boundary. Meaningful only
253 // when HasPending is true.
254 Pending Terms
255 HasPending bool
256}
257
258// IsExpired reports whether the allowance is past its expiry at now. An
259// allowance with no expiry is never expired.
260func (a Allowance) IsExpired(now int64) bool {
261 return a.Terms.ExpiresAt != 0 && now >= a.Terms.ExpiresAt
262}
263
264// windowIndex returns the anchored window number containing now. A lifetime
265// allowance (PeriodLength == 0) is always in window 0.
266//
267// now < Anchor cannot reach here: every caller rejects it first with
268// ErrNotStarted, which keeps this division away from negative numerators
269// where Go's truncation-toward-zero would fold two windows into one.
270func (a Allowance) windowIndex(now int64) int64 {
271 if a.Terms.PeriodLength == 0 {
272 return 0
273 }
274 return (now - a.Anchor) / a.Terms.PeriodLength
275}
276
277// nextBoundary returns the instant window idx+1 begins, and whether that
278// instant is reachable at all.
279//
280// Unreachable has three causes and they collapse to the same answer, which is
281// why this returns a bool rather than an error: a lifetime allowance has no
282// boundary by construction, and an arithmetically unrepresentable boundary
283// (PeriodLength so large, or the clock so far along, that Anchor + steps *
284// PeriodLength overflows int64) is one no clock will ever reach. Computing it
285// unguarded would wrap to a small number and report a boundary in the PAST,
286// which is the dangerous direction: Amend would queue a loosening as though
287// it were about to take effect.
288func (a Allowance) nextBoundary(idx int64) (int64, bool) {
289 pl := a.Terms.PeriodLength
290 if pl == 0 || idx < 0 || idx == maxInt64 {
291 return 0, false
292 }
293 steps := idx + 1
294 if steps > maxInt64/pl {
295 return 0, false
296 }
297 off := steps * pl
298 if off > maxInt64-a.Anchor {
299 return 0, false
300 }
301 return a.Anchor + off, true
302}
303
304// at computes the allowance's effective state at now WITHOUT mutating it:
305// the terms in force, the window it falls in, and how much has been spent
306// within that window.
307//
308// Spend and Remaining BOTH go through this one function. That is deliberate
309// -- a read that answered "how much is left" with its own copy of the
310// rollover and amendment logic would be a second implementation of the
311// rule, free to disagree with the one that enforces it, and the
312// disagreement would surface as an allowance that reports more than it
313// honors (or honors more than it reports).
314func (a Allowance) at(now int64) (Terms, int64, int64) {
315 idx := a.windowIndex(now)
316 if idx == a.WindowIndex {
317 return a.Terms, idx, a.SpentWindow
318 }
319 // The window has rolled. A pending amendment takes effect exactly here,
320 // and the in-window spend resets -- it does not carry.
321 terms := a.Terms
322 if a.HasPending {
323 terms = a.Pending
324 }
325 return terms, idx, 0
326}
327
328// Remaining reports how much the spender may draw right now: the lesser of
329// what the current window leaves and what the lifetime cap leaves. It is 0
330// for an allowance that is expired, not yet started, or fully drawn.
331//
332// It is a projection, not a reservation. Nothing is held, and the figure can
333// change in the same block if someone else's call advances the clock past a
334// boundary.
335func (a Allowance) Remaining(now int64) int64 {
336 if now < a.Anchor || a.IsExpired(now) {
337 return 0
338 }
339 terms, _, spentWindow := a.at(now)
340 left := terms.PerPeriod - spentWindow
341 if left < 0 {
342 // Reachable: a tightening amendment can drop PerPeriod below what
343 // the window already spent. The allowance is drawn, not negative.
344 left = 0
345 }
346 if terms.Total != 0 {
347 lifeLeft := terms.Total - a.SpentTotal
348 if lifeLeft < 0 {
349 lifeLeft = 0
350 }
351 if lifeLeft < left {
352 left = lifeLeft
353 }
354 }
355 return left
356}
357
358// Book holds the live allowances of one consuming realm. The zero value is
359// not usable; construct with New.
360type Book struct {
361 maxLive int
362 nextID uint64 // never decreases; IDs are never reused
363 live *avl.Tree // padded id -> Allowance
364}
365
366// New returns an empty Book. maxLive caps simultaneously live allowances
367// and must be in [1, MaxLiveLimit].
368func New(maxLive int) (*Book, error) {
369 if maxLive < 1 || maxLive > MaxLiveLimit {
370 return nil, ErrInvalidConfig
371 }
372 return &Book{maxLive: maxLive, nextID: 1, live: avl.NewTree()}, nil
373}
374
375// MustNew is New but panics on error.
376func MustNew(maxLive int) *Book {
377 b, err := New(maxLive)
378 if err != nil {
379 panic(err)
380 }
381 return b
382}
383
384// MaxLive returns the Book's cap on simultaneously live allowances.
385func (b *Book) MaxLive() int { return b.maxLive }
386
387// Count returns the number of live allowances.
388func (b *Book) Count() int { return b.live.Size() }
389
390// key pads an id to a fixed width so avl's lexical order matches numeric
391// order. 20 digits covers the whole uint64 range.
392func key(id uint64) string {
393 s := strconv.FormatUint(id, 10)
394 for len(s) < 20 {
395 s = "0" + s
396 }
397 return s
398}
399
400func checkKeys(owner, spender string) error {
401 if owner == "" {
402 return ErrEmptyOwner
403 }
404 if spender == "" {
405 return ErrEmptySpender
406 }
407 if len(owner) > MaxKeyLen || len(spender) > MaxKeyLen {
408 return ErrKeyTooLong
409 }
410 return nil
411}
412
413// Open records a new allowance and returns its id. now becomes the window
414// anchor and the earliest instant the spender may draw.
415//
416// An owner may open several allowances for the same spender; they are
417// independent, and the ids are what tell them apart. spendbook does not
418// merge or deduplicate them, because "one allowance per pair" is a policy
419// some consuming realms want and others do not, and a primitive that
420// decided it here could not be talked out of it.
421func (b *Book) Open(owner, spender string, now int64, terms Terms) (uint64, error) {
422 if err := checkKeys(owner, spender); err != nil {
423 return 0, err
424 }
425 if now < 0 {
426 return 0, ErrInvalidNow
427 }
428 if !terms.valid(now) {
429 return 0, ErrInvalidTerms
430 }
431 if b.live.Size() >= b.maxLive {
432 return 0, ErrBookFull
433 }
434 if b.nextID == 0 {
435 return 0, ErrIDExhausted
436 }
437 id := b.nextID
438 b.nextID++
439 b.live.Set(key(id), Allowance{
440 ID: id,
441 Owner: owner,
442 Spender: spender,
443 Terms: terms,
444 Anchor: now,
445 CreatedAt: now,
446 })
447 return id, nil
448}
449
450// get fetches a live allowance by id.
451//
452// avl's Get returns a bare `any` with no found flag, so absence is a nil
453// value. That is sound here only because nothing nil is ever stored: Set is
454// called in exactly three places and all three pass an Allowance value.
455func (b *Book) get(id uint64) (Allowance, bool) {
456 v := b.live.Get(key(id))
457 if v == nil {
458 return Allowance{}, false
459 }
460 a, ok := v.(Allowance)
461 if !ok {
462 return Allowance{}, false
463 }
464 return a, true
465}
466
467// Get returns a copy of a live allowance.
468func (b *Book) Get(id uint64) (Allowance, error) {
469 a, ok := b.get(id)
470 if !ok {
471 return Allowance{}, ErrNotFound
472 }
473 return a, nil
474}
475
476// Remaining reports what the spender of id may draw at now, or 0 if there
477// is no such live allowance. A caller that must distinguish "nothing left"
478// from "no such allowance" should use Get.
479func (b *Book) Remaining(id uint64, now int64) int64 {
480 a, ok := b.get(id)
481 if !ok {
482 return 0
483 }
484 return a.Remaining(now)
485}
486
487// Spend consumes amount from allowance id on behalf of spender and returns
488// nil if every bound permits it. The caller then performs its own effect.
489//
490// On any error NOTHING is consumed. The write happens once, after the last
491// check, so a refused Spend leaves the book exactly as it was.
492func (b *Book) Spend(id uint64, spender string, now int64, amount int64) error {
493 if now < 0 {
494 return ErrInvalidNow
495 }
496 if amount <= 0 {
497 return ErrInvalidAmount
498 }
499 a, ok := b.get(id)
500 if !ok {
501 return ErrNotFound
502 }
503 if a.Spender != spender {
504 return ErrNotSpender
505 }
506 if now < a.Anchor {
507 return ErrNotStarted
508 }
509 if a.IsExpired(now) {
510 return ErrExpired
511 }
512
513 terms, idx, spentWindow := a.at(now)
514
515 // Window cap. Checked as a subtraction so the sum cannot overflow:
516 // spentWindow and PerPeriod are both >= 0 and PerPeriod > 0.
517 if amount > terms.PerPeriod-spentWindow {
518 return ErrPeriodExceeded
519 }
520 // Lifetime cap.
521 if terms.Total != 0 && amount > terms.Total-a.SpentTotal {
522 return ErrTotalExceeded
523 }
524 // SpentTotal is unbounded when Total == 0, so it is the one
525 // accumulation that can genuinely reach the int64 ceiling.
526 if a.SpentTotal > maxInt64-amount {
527 return ErrOverflow
528 }
529
530 a.Terms = terms
531 if idx != a.WindowIndex {
532 a.HasPending = false
533 a.Pending = Terms{}
534 }
535 a.WindowIndex = idx
536 a.SpentWindow = spentWindow + amount
537 a.SpentTotal += amount
538 b.live.Set(key(id), a)
539 return nil
540}
541
542// Revoke removes an allowance. Only its owner may revoke, and it takes
543// effect immediately -- there is no window to wait for, because revocation
544// is the owner's remedy and a delayed remedy is not one.
545//
546// The id is not reused, so a revoked allowance cannot be resurrected: a
547// later Spend on it returns ErrNotFound forever.
548func (b *Book) Revoke(id uint64, owner string) error {
549 a, ok := b.get(id)
550 if !ok {
551 return ErrNotFound
552 }
553 if a.Owner != owner {
554 return ErrNotOwner
555 }
556 b.live.Remove(key(id))
557 return nil
558}
559
560// Amend changes an allowance's terms. Only its owner may amend.
561//
562// PeriodLength is immutable and must be passed unchanged. Terms that are
563// weakly tighter in every dimension apply immediately; anything looser
564// becomes pending and takes effect at the next window boundary. A lifetime
565// allowance has no next boundary, so a loosening amendment on one is
566// refused with ErrNoBoundary.
567//
568// The returned bool reports whether the amendment applied immediately
569// (true) or was queued (false). A caller that ignores it cannot tell
570// whether the new ceiling is in force, which is exactly the thing worth
571// knowing.
572func (b *Book) Amend(id uint64, owner string, now int64, terms Terms) (bool, error) {
573 if now < 0 {
574 return false, ErrInvalidNow
575 }
576 a, ok := b.get(id)
577 if !ok {
578 return false, ErrNotFound
579 }
580 if a.Owner != owner {
581 return false, ErrNotOwner
582 }
583 if now < a.Anchor {
584 return false, ErrNotStarted
585 }
586 if a.IsExpired(now) {
587 return false, ErrExpired
588 }
589 // Validated against the ANCHOR rather than now, which is the LOOSER of
590 // the two and is deliberate. valid() only needs ExpiresAt to be after the
591 // window origin; an owner naming an expiry between the anchor and now is
592 // tightening the allowance until it is dead, which is their prerogative.
593 // Revoke is the cleaner way to say that, and Reap then reclaims the slot.
594 if !terms.valid(a.Anchor) {
595 return false, ErrInvalidTerms
596 }
597 if terms.PeriodLength != a.Terms.PeriodLength {
598 return false, ErrInvalidTerms
599 }
600
601 // Roll the window first if the clock has moved past a boundary, so an
602 // amendment made after a quiet stretch is judged against the terms
603 // actually in force rather than the ones a stale record still holds.
604 cur, idx, spentWindow := a.at(now)
605 if idx != a.WindowIndex {
606 a.Terms = cur
607 a.WindowIndex = idx
608 a.SpentWindow = spentWindow
609 a.HasPending = false
610 a.Pending = Terms{}
611 }
612
613 if terms.tighterOrEqualTo(a.Terms) {
614 a.Terms = terms
615 // A tightening supersedes a queued loosening. Leaving it queued
616 // would mean the owner's tightening silently expires at the next
617 // boundary and the looser terms they just replaced come back.
618 a.HasPending = false
619 a.Pending = Terms{}
620 b.live.Set(key(id), a)
621 return true, nil
622 }
623
624 // A loosening is only queueable if the boundary it waits for will arrive
625 // while the allowance is still alive. Queueing one that cannot be reached
626 // would report "accepted, pending" for terms that never take effect --
627 // the owner's amendment silently discarded, which is the failure mode
628 // this package is least able to explain after the fact.
629 //
630 // Two ways it is unreachable. The allowance has no boundary at all
631 // (PeriodLength == 0, or an unrepresentable one), or the current terms
632 // expire at or before the next boundary. The second is reachable in
633 // ordinary use: a tightening of ExpiresAt applies IMMEDIATELY, so an
634 // owner can tighten the expiry below the next boundary and then loosen
635 // PerPeriod, and without this check the second call would be accepted
636 // against a window that never opens.
637 nb, ok := a.nextBoundary(a.WindowIndex)
638 if !ok {
639 return false, ErrNoBoundary
640 }
641 if a.Terms.ExpiresAt != 0 && nb >= a.Terms.ExpiresAt {
642 return false, ErrNoBoundary
643 }
644 a.Pending = terms
645 a.HasPending = true
646 b.live.Set(key(id), a)
647 return false, nil
648}
649
650// Reap removes an allowance that has expired at now, and may be called by
651// anyone. It returns ErrNotFound for an unknown id and ErrNotExpired for one
652// that is still alive.
653//
654// Permissionless on purpose, and the reasoning is the whole justification:
655// an expired allowance can never authorize another draw, so removing it takes
656// nothing from the owner and grants nothing to the caller. Without it an
657// expiry is a slow leak against maxLive -- Spend refuses the dead allowance
658// forever while it holds a slot, so a Book shared between owners could fill
659// with corpses and refuse new Opens, and the only remedy would be the owner
660// of each corpse noticing and calling Revoke.
661//
662// This relies on `now` exactly as much as Spend does. A realm that lets a
663// caller choose `now` has already broken consumer contract item 1, and such a
664// realm would let a caller reap a LIVE allowance by naming a future instant.
665func (b *Book) Reap(id uint64, now int64) error {
666 if now < 0 {
667 return ErrInvalidNow
668 }
669 a, ok := b.get(id)
670 if !ok {
671 return ErrNotFound
672 }
673 if !a.IsExpired(now) {
674 return ErrNotExpired
675 }
676 b.live.Remove(key(id))
677 return nil
678}
679
680// Iterate calls fn for every live allowance in id order, stopping early if
681// fn returns true. The allowance is passed by value, so fn cannot mutate
682// the book through it.
683func (b *Book) Iterate(fn func(Allowance) bool) {
684 b.live.Iterate("", "", func(_ string, v any) bool {
685 return fn(v.(Allowance))
686 })
687}
