feat(payments): ENG-573 Phase 0 send guard — attempt budget, amount sanity, daily-limit cap

[forge0x]

Linear: ENG-573 — Phase 0.

TL;DR for whoever deploys this

This ships observing, not enforcing. sendGuard.mode defaults to log-only: all three checks run, every would-be rejection posts a transfer / would-reject ops event, and the send goes through. Nothing is refused until someone sets the flag.

sendGuard:
  mode: log-only # default — measure first
  # mode: enforce  # rejections become real
  # mode: off      # returns before Redis / price / decode — see "what `off` misses" below

Rollback is the same flag: back to log-only, or off if the guard itself is the outage. It is not live-reloaded — yamlConfig is read once from --configPath at process start, so a rollback is helm upgrade plus a pod roll (kubectl rollout restart deploy/<api>), not an instant flip. Budget for a roll, not for a switch. Anything unrecognised degrades to log-only — the failure mode of this switch must be "does not block", never "every send is refused". Read docs/send-guard.md before flipping it: it has the rollout procedure, what to count in the ops feed, and the config that goes with it.

Why

Flash has no internal ledger, so Galoy's AccountLimitsChecker reads zero volume for every account and never rejects. The live send resolvers call IBEX with nothing on the Flash side checking the amount. On 2026-09-03 a $999,999,999.99 intraledger request reached IBEX untouched (TEST cluster, demo_account → rewards); prod runs the same path.

What

Payments.authorizeSend (src/app/payments/authorize-send.ts), reached by every user-initiated send mutation:

1. Attempt budget — two Redis buckets keyed on the account: 10/min burst, 200/day. Consumed first, so a rejected attempt still costs a point and probing the amount space is bounded by the caller's own budget.
2. Amount sanity — positive and finite. USD/USDT cents may be fractional (USDT settles in micros); sats must be whole.
3. Daily limit as the per-transaction cap — amount <= dailyLimit(level), per the ENG-573 decision. Intraledger sends use the intraLedger limit; lightning / LNURL / on-chain use the withdrawal limit. Phase 1 replaces this with the remaining allowance.

Wired into all eight live send mutations: intraLedgerPaymentSend, intraLedgerUsdPaymentSend, lnInvoicePaymentSend, lnNoAmountInvoicePaymentSend, lnNoAmountUsdInvoicePaymentSend, lnurlPaymentSend, onChainUsdPaymentSend, onChainPaymentSendAll.

It runs inside the idempotency wrapper, not ahead of it

On the six rails that accept an idempotencyKey, the guard is handed to withPaymentIdempotency as its authorize hook — inside the lock, after the in-lock cache re-check, immediately before the send. Only the path that is about to pay is judged.

That ordering is load-bearing, not tidiness. Ahead of the wrapper, a client whose $50 send timed out and retried spent a burst point on every retry before ever reaching the replay: past 10/min it got {status:"failed"} + "Too many payment attempts" for a payment that had already settled — and a client that reads "failed" as "retry with a fresh key" then double-pays, which is precisely the ENG-530 class the wrapper exists to prevent. The two sats rails additionally re-priced on each retry, so a settled send near the cap could come back as "Cannot transfer more than $X" after a mid-price tick. A replay must cost nothing and must not be re-judged.

off covers every check the guard runs — and one thing it does not

lnInvoicePaymentSend had to start decoding the bolt11, because the guard needs the amount and the amount is inside the invoice. decodeInvoice refuses anything invoices.parsePaymentRequest can't parse and any invoice with no payment secret — a rejection class that rail never had, since it used to hand the raw bolt11 straight to IBEX. That gate therefore lives inside the same authorize hook and answers to the same switch: on off the resolver doesn't decode at all. If the gate ever refuses an invoice IBEX would have paid, the flag is the remedy, not a deploy.

But off is not a full revert of ENG-573. Reading an account with no level field as level 0 lives in effectiveAccountLevel, applied inside getAccountLimits at the config layer — deliberately, so the guard, Account.limits and remainingLimit cannot disagree about those ~300 accounts. Galoy's own AccountLimitsChecker reads the same function, so it caps an unleveled account at the level-0 limits in every mode, off included, with no ops event and no sendGuard.* span attribute to explain it. It bites only the BTC no-amount lightning pair, the sole user-facing rails still routed through @app/payments; the USD and amount-bearing resolvers pay IBEX directly and never reach the checker, so on those off really is pre-ENG-573. Read What off does not cover before concluding the flag has undone everything.

Fail-closed is bounded

No limit configured for the level, no BTC→USD price for a sats amount, or a rate-limit store fault all reject the send with SendLimitsUnavailableError when enforcing — infrastructure faults, not user error. They are recorded as span exceptions on every occurrence (Critical when enforcing, Warn in log-only): that is the signal to alert on.

Their ops embeds are coalesced to one per minute, carrying muted: N so the feed stays countable. A Redis fault isn't one noisy caller — it makes every send in flight report at the same instant, into a shared 50-deep FIFO that drains sequentially and drops its oldest entries. Unbounded, it would bury the verification / cashout / deposit feed during exactly the incident this switch exists to survive. rate-limited and undecodable-invoice are coalesced the same way and for the same reason — both are unbounded by anything but the caller's own retry loop, and a check with no observable output cannot be read during a log-only rollout at all. over-daily-limit and invalid-amount are never coalesced — they are the per-account facts the log-only rollout exists to read, and each caller's attempt budget already bounds them.

Decisions baked in

These decide what log-only will report, and what enforce would refuse. The point of shipping in log-only is that the second column stops being an assumption before anything is blocked.

Decision	Value	Why
Accounts with no level field	treated as level 0 ($125/tx)	~300 prod accounts lack the field (174 with usernames); mongoose has no default. "An unleveled account is an unverified one" is an assumption — this is the sharpest thing to check in the log-only sample before enforcing.
Level-3 (Business) daily limits	same as level 2 ($50k intraledger / $50k withdrawal)	25 prod accounts are L3. Placeholder until the ladder is decided (ENG-573 open question).
Levels 0–2	Galoy schema defaults, except level 1 (L0 $125, L1 $1k, L2 $50k)	Started on the schema defaults. Galoy ships L1 split — $1k withdrawal against $2k intraledger — and that split was the only place the guard's rail-vs-destination approximation could change an outcome. Settled 2026-09-08 to a single $1,000, i.e. downward, rather than by raising the external cap to $2k. Every level now carries equal withdrawal and intraLedger limits.
Attempt budget	10/min, 200/day	rateLimits.paymentSendAttempt / paymentSendDailyAttempt. blockDuration must be ≥ duration — rate-limiter-flexible rewrites the key TTL to blockDuration on the first breach, so a shorter block hands back a fresh budget early.

Deploy notes

• No chart/values change required, and none needed to stay safe — the default is log-only.
• The new rateLimits keys are property-level defaults, not required keys, because prod overrides the whole rateLimits block in deployments/tf-modules/flash/flash-values.tmpl.yaml; a required key there would fail config validation at boot. A unit test pins this.
• accountLimits levels 0–3 are all required. A values file that overrides accountLimits partially now fails at boot instead of resolving a missing level to NaN and silently blocking that level's sends.
• Expect 🔁 Transfer — Would Reject embeds in #flash-activity after rollout. In log-only that is the guard measuring, not blocking. Count them by step before flipping — the procedure is in docs/send-guard.md.

Tests

• authorize-send.spec.ts — all three modes; budget order; store fault reported as an infra fault, not as a rate limit; invalid amounts (0, negative, NaN, ∞, fractional sats, bad strings); exact-limit boundary per kind; the wall-of-nines regression at every level; missing level → 0; sats→USD via mid price incl. price-unavailable; 50 consecutive store faults produce one ops embed and 50 span exceptions, and the muted count lands on the next embed that posts.
• idempotency.spec.ts — authorize is skipped on a replay, on a lock-busy return and on a fingerprint mismatch; runs before execute on the paying path; a rejection leaves the key retryable.
• send-intraledger.spec.ts — end to end through the real wrapper: a replayed key runs the guard once, not twice (the burst-budget regression); a rejection sends nothing and the key still works afterwards.
• send-lightning-ops-events.spec.ts — a rejection on the no-amount BTC rail validates nothing, sends nothing, posts no ops event.
• Resolver specs for all eight mutations — the guard's args, that it is handed down to the send function rather than run ahead of it, and that a rejection returns a failed payload.
• ln-invoice-payment-send.spec.ts — off still pays an undecodable invoice and a no-amount invoice and never decodes at all; plus a real mainnet bolt11 through the real decodeInvoice, proving the new gate passes an ordinary amount-bearing invoice to IBEX with its true sats amount.
• send-limits.spec.ts — a behavioural RateLimiterMemory case proving the daily counter survives a breach for the whole window; partial accountLimits override without level 3 fails Ajv validation; sendGuard defaults and enum.
• error-map.spec.ts — the three new mappings, and that SendLimitsUnavailableError keeps its generic wording instead of leaking internal limit detail.

Full unit suite: 255 suites, 2906 tests (2903 passed, 3 pre-existing skips). yarn tsc-check, yarn tsc-check-noimplicitany, yarn eslint-check, yarn build, yarn check-yaml and yarn madge-check all clean.

Follow-ups (tracked in ENG-573)

• Flip to enforce once a week of would-reject data is in — a separate, values-only change.
• Phase 0b: ops-event env label distinguishes clusters; TEST events to their own channel.
• Phase 1: Redis rolling-24h allowance with reservations; cap becomes amount <= remaining.
• Phase 2: truthful Account.limits.remainingLimit; IBEX reconciliation job.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NEoz7nBtdtsHyuYG5wNPQV

[linear]

ENG-573