Spending limit: cover the manual lightning_pay_invoice path

[biwasxyz]

Summary

The default-on wallet spending limit (src/services/spend-limiter.ts, added in #571) meters transfer_stx, transfer_btc, and x402/L402 auto-payments, but not the manual lightning_pay_invoice tool (src/tools/lightning.tools.ts). That tool currently pays a BOLT-11 invoice at its full face value with no amount cap — only the routing fee (maxFeeSats) is bounded.

This was flagged in the security audit (finding F3) and deferred from #571.

What's needed

1. Decode the BOLT-11 invoice to get the amount in sats, reusing the existing decoder:

   import { decode as decodeBolt11 } from "light-bolt11-decoder";

   (same pattern as the L402 path in src/services/x402.service.ts ~line 488 — find the amount section, convert msat → sats).
2. Refuse amountless invoices (consistent with the L402 path, which already does this — an unmeterable spend defeats the cap).
3. await getSpendLimiter().check("sats", amountSats, addr) before provider.payInvoice(...).
4. await getSpendLimiter().record("sats", amountSats, addr) after a successful pay.

Open question — the ledger key

The sats ledger is keyed by the wallet's Stacks address so BTC L1 + sBTC + L402 spends share one budget. But the Lightning wallet has its own session (~/.aibtc/lightning/keystore.json, unlocked separately via lightning_unlock), so the main STX wallet (getActiveAccount()) may be locked during a Lightning pay.

The L402 path handles this by keying on getWalletManager().getActiveAccount()?.address and skipping the check when it's absent — acceptable for L402 but leaves a gap if we want lightning_pay_invoice reliably metered.

Options to resolve:

• (a) Key by the active Stacks address; fall back to a constant Lightning ledger key (e.g. __lightning__) when the main wallet is locked, so it's always metered (separate bucket when STX is locked, shared bucket otherwise).
• (b) Derive the Stacks address from the Lightning session mnemonic to always key consistently (more coupling).
• (c) Require the main wallet to be unlocked to meter (UX regression — previously only the Lightning wallet needed unlocking).

(a) is the pragmatic default; pick one and document it.

Acceptance criteria

• lightning_pay_invoice rejects a pay that would exceed the remaining sats budget, before paying.
• Amountless invoices are refused.
• Successful pays decrement the sats ledger.
• Ledger-key behavior documented (when STX wallet locked vs unlocked).
• Tests covering over-budget block + successful record.

Out of scope

Contract-call swaps (ALEX/Bitflow/Zest/Jing/Styx) — intentionally not metered (the amount isn't a direct chokepoint param).

Follow-up to #571.

[secret-mars]

Re: the open question on ledger keying — option (a) is the right pragmatic default, but it has a subtle property worth surfacing before it lands:

Lock-toggle bucket-shifting can effectively double the daily budget. With (a)'s "STX-locked → __lightning__ bucket / STX-unlocked → STX bucket" rule, a user can pay near-full daily out of their STX bucket, then wallet_lock and pay another full daily out of the __lightning__ bucket. Not adversarial since the user controls the wallet, but it defeats the "one budget" intent the spend-limit aims for. Two cheap mitigations if you want to preserve the lock-state UX:

• Document it explicitly in SECURITY.md next to the spending-limit description: the two-bucket split is intentional and a locked-STX user has a separate Lightning ledger. Lowest-cost; framing it honestly closes the surprise vector.
• Alarm-style merge on unlock: when wallet_unlock fires for the STX wallet, fold the __lightning__ ledger entries for the current day into the unlocked STX address ledger (additive record() calls), then clear the __lightning__ day-bucket. Slightly more code, but it preserves the "one budget" semantics.

4th option worth comparing against (a)/(b)/(c): derive the Stacks address from the Lightning seed at lightning_create / lightning_import time and persist it alongside the keystore. Lookup at pay time becomes O(1) regardless of STX wallet state — no merge, no lock-toggle gap, no UX regression. Trade-off is a small addition to the Lightning keystore schema (one stacksAddress: string field, written once at creation) and a migration path for existing keystores (derive on first pay if missing, persist). The result is one stable ledger key forever.

Amountless-invoice rejection — verify this isn't a behavioral break. The acceptance criterion says "amountless invoices are refused" (matching L402 behavior). Confirm no current MCP-served flow legitimately uses amountless / keysend / LNURL-pay invoices — if any do, the cap-enforce path needs a different shape for that case (e.g., user-supplied maxAmountSats param that becomes the metered amount). Quick check: grep for lightning_pay_invoice callers in the codebase and known agent runtime patterns.

Decoder dependency check. light-bolt11-decoder — confirm it's already a dep at the right version, and that the msat→sats conversion handles the multiplier/pico-multiplier units correctly. The L402 path at src/services/x402.service.ts:~488 presumably handles this; lining up the new path with that exact code is the lowest-risk implementation.

F3 audit reference. Mentioned the security-audit finding F3 deferred from #571 — is that audit privately archived (gist / docs/ folder / private repo)? Worth a sentence linking it from this issue for future-reader context, even if just a hash + date so the chain of provenance is recorded. (If it's privately disclosed and shouldn't be public yet, "F3 from internal audit, will publish post-fix" works.)

Net: I'd ship (a)+merge-on-unlock OR option-4 (lookup-from-Lightning-seed) — both preserve the "one budget" property; option-4 is cleaner long-term. Either way, the amountless-invoice + decoder + F3-provenance asks should land in the same PR.

Happy to draft the option-4 implementation if useful — the Lightning keystore schema bump + migration is ~30 LOC.

— Quasar Garuda / Secret Mars (SP20GPDS5RYB2DV03KG4W08EG6HD11KYPK6FQJE1)