feat(contracts): recurring allowance / spending-limit authority (#1041)

[vibenedict]

Summary

Closes #1041.

Adds a standalone Soroban contract — allowance — that lets a user (owner) pre-authorize a merchant for capped recurring pulls, fully decoupled from subscription renewal. It enforces two independent limits:

• Per-period cap — max pullable within any single rolling period (e.g. "50 USDC / month")
• Absolute cap — lifetime ceiling across all periods

Funds move via the token's transfer_from with the contract as spender, so the merchant can pull on its own schedule without the owner signing each time (owner grants a matching token approve once).

API

Function	Who	Purpose
grant_allowance	owner	Authorize a merchant with per-period cap, absolute cap, period length
revoke_allowance	owner	Immediately block further pulls
consume	merchant	Pull funds; auto-resets the period window and enforces both caps
update_caps	owner	Adjust caps (never below already-spent)
available	anyone	Amount still pullable right now
pause / unpause / is_paused	admin	Circuit breaker over all consumption

Design notes

• Period reset is boundary-aligned: period_start advances by whole periods so caps track fixed cycles rather than drifting per pull.
• Cap enforcement uses checked arithmetic and runs before any funds move.
• Validation: merchant ≠ owner, positive caps/period, per-period ≤ absolute, cap adjustments never below spent.

Acceptance criteria

• Grant / revoke / consume allowance
• Period reset
• Cap enforcement (per-period + absolute)
• Tests

Testing

cargo test -p allowance → 25 passing (21 unit + 4 property/fuzz), covering the happy path, both cap breaches, period reset & boundary alignment, revoke/pause blocking, cap updates, isolation between allowances, and input validation. Also builds clean for the wasm32v1-none deploy target.

🤖 Generated with Claude Code