v0 source pure

Package allowancesender provides a bounded, granter-revocable spending capability that wraps a banker.Banker source.

Use case

Realm A wants to grant realm B the ability to spend up to some bounded amount from A's address (or A's tx envelope) within a single call, without giving B unbounded access. After A's call to B returns, A revokes the capability via Close(); B cannot use it across tx boundaries even if it persisted the reference.

Canonical pattern

1src := banker.NewBanker(banker.BankerTypeRealmSend, cur)
2al  := allowancesender.New(src, granterAddr,
3           chain.NewCoins(chain.NewCoin("ugnot", 1_000_000)))
4defer al.Close()
5bRealm.DoSomething(cross, al)  // B can call al.Send up to cap

On return (success or panic), `defer al.Close()` flips the closed flag. If B persisted al, B's stored reference is now dead — any later al.Send() panics with "closed".

Naming note

Despite the underlying type wrapping a banker.Banker, *AllowanceSender does NOT satisfy the banker.Banker interface. The other Banker methods (GetCoins, TotalCoin, IssueCoin, RemoveCoin) have no meaningful behavior on an allowance abstraction:

• GetCoins would either leak the granter realm's full balance (misleading) or return Remaining() (lying about the addr arg).
• TotalCoin/IssueCoin/RemoveCoin are out of scope.

Send is the only meaningful operation; hence the "Sender" name. If you need to plug into a banker.Banker-shaped API, write an adapter in your own package.

Security model

• Pointer-based API. All callees that hold a *AllowanceSender share the same underlying state. Close() flips a bool that every reader observes synchronously.
• Inner banker is an unexported field. Callees cannot extract it to bypass the wrapper. Language-enforced.
• Cap is enforced per-denom via chain.Coins.AmountOf. Any denom in amt that is missing from cap implicitly has capAmt=0; positive spend on such a denom panics with "cap exceeded".
• Persistence is the kill switch's friend, not its enemy. The closed flag persists with the struct, so a callee that stored the reference for cross-tx use sees a closed allowance.
• Defer-close survives panic. If B's call panics, the tx reverts entirely (so the close is irrelevant — state reverts anyway). On success, defer fires before granter's function returns, committing closed=true with the rest of the tx state.
• Cap/Spent return defensive copies. Mutating the returned chain.Coins does not affect internal state.
• Inner banker panic on SendCoins (e.g. bank-keeper "insufficient funds") rolls back the spent counter — caller's accounting stays accurate even if a defer-recover swallows the panic. (Without recovery, the entire tx reverts and the rollback is moot.)
• Arithmetic uses math/overflow.Add64. Overflow on (spent+amount) panics rather than silently wrapping (which could bypass the cap check). Negative amounts are explicitly rejected.

Design choices

• Pointer type, not value: forces shared state across references. Value-copy AllowanceSender would have separate closed flags and defeat the kill switch.
• One-shot Close, not graduated: simpler invariant. If you need "resume later," create a fresh allowance.
• No destination allowlist: out of scope. If the granter wants to restrict where funds go, wrap this further.
• No time-based expiry: rely on Close. Block-height stamping or deadline checks would require runtime cooperation; this package is pure Gno.
• Cap is multi-denom (chain.Coins, not int64): supports heterogeneous payment policies. Most callers use single-denom.
• Idempotent Close: safe to defer-Close even if Close was called manually earlier in the function.
• Does NOT satisfy banker.Banker: see "Naming note" above.

Limitations

• Granter retains direct access to the underlying source banker. The AllowanceSender only constrains the wrapped capability, not the granter's ability to spend its own funds via other means.
• No cross-realm enforcement of granter identity. The source banker's own pkgAddr check (banker.gno) rejects mismatched froms. This package relies on banker's own protection there.
• Re-entrancy: nested allowances work (each is independent), but do NOT re-use the same AllowanceSender pointer across grants — always create a fresh one. Re-using would mix spent counters.
• Cap with duplicate denoms (constructed by hand, not via chain.NewCoins) will trigger chain.Coins.AmountOf to panic on read. Use chain.NewCoins(...) to construct cap; it deduplicates.
• Persistence: granter is responsible for clearing references to closed AllowanceSender pointers from its own state if it wants them garbage-collected; otherwise they linger as dead structs.

What this package does NOT solve

• "Allowance survives across N txs but not N+1 txs." Use a session counter pattern in the granter realm; this package's Close is binary, not deadline-based.
• "Fungible-token (grc20) allowances." Use the grc20 package's own Approve/Allowance/TransferFrom triple. AllowanceSender is for native (chain-coin) sends only.

Events

AllowanceSender emits chain events at two points so off-chain observers can track allowance lifecycles. Events are emitted from the calling realm's package path (whichever realm holds the AllowanceSender pointer when the method is called).

• "AllowanceSenderSend": on each successful Send, with attributes "payer", "to", "amount", "spent_total", "remaining".
• "AllowanceSenderClose": on Close (only the first call; idempotent re-Closes do not re-emit).

The underlying inner banker also emits its own bank-keeper events for the actual coin movement; AllowanceSender's events sit on top of those for allowance-level audit trails.