spendbook/v2 package

Package spendbook is a pure allowance primitive for realms that need to let one party spend another party's funds, up to a bounded amount, over many transactions. It is to *delegated spending* what duebook is to *time*: it holds no coins, performs no effects, imports no chain APIs, and owns no package-level state. The importing realm owns a *Book, supplies the clock, and performs its own effects.

Why v2 exists

v1 of this package is deployed and immutable. Its API is unchanged here; ONE method body differs, and it is a correctness fix:

1v1:  func (a Allowance) IsExpired(now int64) bool {
2         return a.Terms.ExpiresAt != 0 && now >= a.Terms.ExpiresAt
3     }

a.Terms is the LAST-WRITTEN record, not the terms in force. Every other live question in this package is routed through at(), which resolves a pending amendment at the window boundary it is due at; IsExpired was the one exported predicate that read the stored field instead. Because an amendment that moves ExpiresAt in the LOOSER direction can only ever be QUEUED -- tighterOrEqualTo refuses both "push the expiry out" and "remove the expiry" as immediate -- queueing is the only path such an amendment has, so the stale read was on that path every time.

The consequence is not one bug but two, pointing opposite ways, and the second is the dangerous one:

• UNDER-authorization. An owner extends the expiry. The amendment is accepted and queued, the boundary arrives, at() puts the new expiry in force -- and IsExpired still answers from the old one. At the OLD expiry: Remaining reports 0, Spend returns ErrExpired, and Reap, which is PERMISSIONLESS, lets any third party delete an allowance the owner had just extended. The owner's accepted amendment is silently discarded, which the v1 doc calls "the failure mode this package is least able to explain after the fact" -- about a different case, in Amend, four lines from the guard that does not cover this one.

• OVER-authorization. An amendment may be looser in PerPeriod and TIGHTER in ExpiresAt; tighterOrEqualTo is weakly-tighter in EVERY dimension, so that mix queues as a whole. Past the boundary, at() hands Spend the new PerPeriod while IsExpired reports the allowance alive on the OLD, later expiry. The spender draws -- at the raised cap -- past an expiry the owner themselves set. No bound in this package stops it, because the bound was moved and the gate was not told.

Both are repaired by resolving the expiry through at(). Neither could be repaired in v1: a /p/ is immutable after addpkg, and v1's two live consumers are themselves immutable realms with v1's bytes compiled into every path they run. v1 therefore stays live and keeps the defect; it is not retired by this package existing, and nothing here migrates it.

The v1 workaround, for a consumer stuck on it: restating the SAME amendment inside [next boundary, old expiry) applies it immediately -- Amend rolls the window first, promoting the pending terms into a.Terms, and the restatement is then equal-to rather than looser. It is owner-only, moves no funds, and needs no spend. It must be done BEFORE the old expiry; afterwards v1's Amend refuses with ErrExpired, and Revoke plus a fresh Open is the only route left.

Why this package exists

The ecosystem's existing allowance primitive, gno.land/p/jaekwon/allowancesender/v0, is scoped to a single call and says so in its own documentation:

1"Allowance survives across N txs but not N+1 txs." Use a session
2counter pattern in the granter realm; this package's Close is
3binary, not deadline-based.

It then declines block-height expiry on the grounds that it "would require runtime cooperation". That is true only for a package that reads the clock itself. spendbook does not: every operation takes `now` as an argument, which makes the window arithmetic a pure function and the whole package unit-testable without a chain. Three application realms in the searched sources each hand-rolled this mechanism internally rather than importing one; see DISCOVERY.md.

The one idea

An allowance is not a balance. It is a *permission with a ceiling that refills*. The owner says "this spender may draw at most PerPeriod per window, at most Total ever, until ExpiresAt, and I can revoke it now":

1if err := book.Spend(id, spenderKey, now, amount); err != nil {
2	panic(err) // revoked, expired, over the window cap, over the total
3}
4// ... the realm moves the coins here, under its own authority

Spend checks every bound and CONSUMES the allowance in the same call, before returning. The realm then acts. Because the realm performs the effect itself, no closure, callback, or capability ever crosses a realm boundary. spendbook cannot be handed code to run, so it cannot be tricked into running the wrong code.

Windows are anchored, not sliding

A window is derived from a fixed origin — the Anchor set at Open — by integer division:

1index(now) = (now - Anchor) / PeriodLength

so the boundaries are the same for everyone and a spender cannot reset a window by choosing when to call. A sliding "PerPeriod per trailing N blocks" window would let a spender draw the full cap at the end of one trailing span and again at the start of the next; anchoring removes the choice. The refill is a RESET, not a carry: an unused allowance does not accumulate into the next window, because the point of the cap is to bound worst-case loss per window, and a carry would unbound it.

PeriodLength == 0 means one window that never rolls: a pure lifetime allowance, where PerPeriod is the only cap that matters.

Amendments cannot enlarge the live window

An owner who could raise PerPeriod mid-window would be able to undo the bound a spender is relying on, and — worse in the other direction — an owner who drains a relationship and then lowers terms retroactively could strand a spender mid-settlement. The rule here is one-sided and enforced in Amend:

• TIGHTER-OR-EQUAL terms apply IMMEDIATELY. Lowering a ceiling can never authorize a draw that was not already authorized, so there is no reason to delay it, and delaying it would make the owner's only fast remedy Revoke.
• LOOSER terms are PENDING and take effect at the next window boundary, never inside the current one.

This is the same adversarial problem that r/samcrew/agent_registry_v2 solves by locking its price while any credit entry exists; the shape here is a deferral rather than a lock, so terms can still move.

With PeriodLength == 0 there is no next boundary, so a loosening amendment is refused with ErrNoBoundary rather than silently queued forever. PeriodLength itself is IMMUTABLE: changing it would move every future boundary, which is an enlargement vector wearing a different hat.

State growth

Revoked allowances are removed, not archived. IDs are allocated monotonically and never reused, so a revoked ID can never be resurrected and there is nothing to keep. Live allowances are capped per Book at construction, so storage is bounded by maxLive regardless of how many allowances have ever existed. Audit history belongs in the consuming realm's events.

An EXPIRED allowance is not self-removing, and bounded storage is not the same as a usable Book: Spend refuses it forever while it still holds a slot. Reap exists for exactly that and is permissionless, because an expired allowance can authorize nothing and so removing it takes nothing from anyone.

What this package does NOT bound is how many of a Book's slots ONE owner may hold — maxLive is a single global figure, so any owner permitted to Open can exhaust it and lock out the rest. That is a policy question with no answer a primitive can pick (per-owner quota? first-come? owner whitelist?), so it is left where the authentication already lives: the consuming realm decides who may Open, and a Book shared across mutually untrusting owners needs its own per-owner cap on top of this one. Named here rather than implied, because "bounded" reads like "safe to share".

Consumer contract (the parts the package cannot enforce)

1. SUPPLY A REAL CLOCK. spendbook cannot verify that `now` came from runtime.ChainHeight() or time.Now().Unix(). A realm that lets a caller choose `now` has handed the spender the power to roll the window at will, which defeats every cap in this package. Pass the chain's own clock, and use the same units for the life of the Book.

2. AUTHENTICATE THE SPENDER KEY. spendbook compares the key string it is given against the one recorded at Open. It cannot tell whether that string is the real caller. Derive it from cur.Previous().Address(), never from an argument the caller supplies.

3. SPEND BEFORE SENDING. Spend consumes the allowance and returns; the realm then moves coins. Doing it in the other order means a failed send leaves the allowance consumed, or a successful send leaves it unconsumed — both are real losses. State first, effect second.

4. AN ALLOWANCE IS NOT CUSTODY. spendbook authorizing 100 does not mean 100 exists. The realm must check its own held balance separately; this package bounds permission, not solvency.