ENG-653: Flash-native payment splits for incoming payments (API, phase 1)

[islandbitcoin]

Problem

ENG-653: a merchant or user wants an incoming payment split automatically, for example 10% to a partner wallet. Flash had no rules for this. Splits must go through the normal send path so ENG-573 limits, KYC level, ENG-530 idempotency, notifications and history all apply.

The two input plans assumed Fygaro top-ups, referral payouts and split payouts never reach the invoice webhook. They do. intraledgerPaymentSendWalletId mints the recipient invoice with Ibex.addInvoice, and addInvoice always binds onReceive.invoice. Without a marker, every system credit would trigger splits, and a split payout would trigger the next split in a loop.

Change

Everything sits behind paymentSplits.enabled, which defaults to false.

• Config: paymentSplits { enabled, maxAttempts (5), minShareCents (1), loopIntervalMs (60s), executorTimeBudgetMs (45s), reconcileIntervalMs (15 min), cronIntervalMs (24h) }.
• Marker (payment-critical code): Flash-to-Flash payments never trigger splits (decision 1). send-intraledger writes an InternalTransferInvoice row (origin: "intraledger") for the recipient invoice's payment hash between addInvoice and payInvoice. The cash-wallet cutover does the same with origin: "cutover". If the write fails, the send returns InternalTransferMarkerError and nothing is paid. That error is not cached, so the same idempotency key can retry. The hash is decoded from the bolt11 being paid, with IBEX's invoice.hash as fallback. The marker has a 30-day TTL. Bolt11 pays (lnInvoicePaymentSend, lnNoAmountUsdInvoicePaymentSend) mark the invoice hash (origin: "ln-send") before paying, fail-closed, because the payee may be a Flash wallet; an undecodable bolt11 is paid unmarked since every IBEX-minted invoice decodes. lnurlPaymentSend cannot know the hash before IBEX pays, so it marks the hash IBEX returns (origin: "lnurl-send"), and the executor re-checks the marker before every payout (skipped_internal).
• Data: new PaymentSplitRule, PaymentSplitExecution (unique (triggerKey, walletId, destinationWalletId) index, one payout per receive per target, so a webhook replay after the rules were re-saved (new rule ids, same destinations) is still a duplicate) and InternalTransferInvoice collections. Their repos return typed RepositoryErrors, and a duplicate insert is a typed no-op.
• Domain: validateSplitSet accepts an empty set (clears all splits) and otherwise checks that the sum is in (0, 100], percents are integers from 1 to 100, there are at most 10 rules, no wallet splits to itself, destinations are unique, and every destination uses the source wallet's currency. Source wallets must be USD or USDT. computeShare floors in minor units (USD cents, USDT micros) and then to whole cents. A share below minShareCents is recorded as skipped_min.
• Webhook: a recordPaymentSplits middleware runs on the invoice and lnurl routes only. It records rows and never sends. On any error it logs and moves on, so the response is still 200; the split reconcile (below) records what it missed. Receives with a marker record nothing, and replays hit the unique (triggerKey, walletId, destinationWalletId) index and do nothing, including a replay after a rule re-save. The webhook passes the receive's receivedAt, so a rule never fires on a receive that settled before the rule was created. A re-save keeps createdAt for every destination that survives it, so it never hides an earlier unrecorded receive from the reconcile.
• Split loop (startPaymentSplitsLoop, runs inside the long-running ibex-webhook workload every loopIntervalMs). The galoy cron is a daily k8s Job (chart 0 2 * * *), too slow to pay or retry splits, so no chart change is needed or relied on:
  • Reconcile, once per reconcileIntervalMs across replicas (Redis NX lease, fail-open): reads IBEX type-1 receives on wallets with rules, paging newest-settled first until a page passes the lookback. The lookback is derived from the cadence (cadence plus a margin: 25 min here) and uses the same payment-hash key as the webhook. Type 9, ETH USDT crypto receives, is ignored per decision 2.
  • Executor: claims rows with an atomic pending → sending update until none are due or executorTimeBudgetMs is spent (no fixed batch cap), then pays through intraledgerPaymentSendWalletIdForUsdWallet with authorizeSend (kind intraledger) and idempotencyKey: split:<executionId>. Results map as follows:
    • Success becomes sent and pushes the owner.
    • Pending becomes ibex_pending and is never re-paid.
    • Limit, KYC, insufficient-balance and inactive-account errors become failed on the first attempt and push the owner.
    • Rate-limit, guard-unavailable, marker and IBEX 429 errors, and a lock that was never acquired (ResourceAttemptsLockServiceError before the send guard passed), retry after 1, 2, 4 and 8 minutes, then become failed at the 5-attempt budget.
    • Any other lock error, or any lock error after the send guard passed (redlock can report one after IBEX paid, when the routine throws or the release fails), becomes unknown with an ops alert and is never resent.
  • Stale sweep: moves a row stuck in sending for more than 10 minutes to unknown and sends an ops alert. It never resends.
• Cron: keeps only a backstop reconcile for the loop being down, with a lookback of cronIntervalMs plus a margin (26h).
• GraphQL:
  • walletSplitsSet and walletSplitDelete are registered under atWalletLevel, so the wallet-id middleware checks ownership. The app layer re-checks ownership too.
  • Wallet.splits is on UsdWallet and UsdtWallet, visible only to the wallet's owner. BTCWallet always returns []. It is not added to PublicWallet.
  • API-key scopes are set: both mutations need write:wallet, and the nested splits field needs read:wallet. The SDL is regenerated.
• Notifications: notification.paymentSplit.sent and notification.paymentSplit.failed, in en and es.

How it was tested

• yarn tsc-check-noimplicitany, yarn tsc-check, yarn eslint-check, yarn build, yarn check:sdl, yarn check-yaml, yarn madge-check and typos --config typos.toml all pass.
• Full unit suite (the command make unit-in-ci runs): 290 suites, 3673 passed, 3 skipped.
• New unit specs:
  • domain validation and share math
  • set and delete splits: username vs walletId resolution, same-currency wallet pick, ownership re-check, lock held
  • record: replay dedupe, marked hash, flag off
  • executor: success, pending, terminal failures, backoff, stable idempotency key, concurrent claim
  • sweep and reconcile
  • webhook routes
  • mutation resolvers and the Wallet.splits resolver
  • send-intraledger and cutover marker ordering and fail-closed behavior
  • a guard test that lists every Ibex.addInvoice call site
• api-key-scope-enforcement.spec.ts now treats splits as a sensitive field.
• New integration spec test/flash/integration/payment-splits: unique (triggerKey, walletId, destinationWalletId) index (a rule-rewrite replay is a no-op, another destination is not; index shape asserted), rule createdAt carried across a re-save and a reconcile that records a receive settled before the re-save, one winner among 5 concurrent claimers, marker TTL index, rule replace semantics. Locally I ran it against a throwaway mongo:6.0.5 container with a minimal mongoose-only setup. CI runs it under the normal integration harness.

Follow-ups

• Trigger on ETH USDT (type 9) deposits that do not match a BridgeDeposits tx hash (decision 2).
• Write an ops runbook for resolving unknown and ibex_pending rows.
• Mobile UI.
• The marker is a denylist. The call-site test fails when a new addInvoice caller appears. CashoutManager is classified as a Flash-owned recipient, but nothing stops someone from adding split rules on a Flash-owned wallet.
• Split sends use the owner's ENG-573 attempt budget and daily limit.
• The executor uses a 5-attempt budget, so the 16-minute step is only reached if maxAttempts is raised to 6.
• cronIntervalMs mirrors the chart's cron schedule; if the chart schedule ever becomes less frequent than daily, raise it.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WxkKbrg2Xohf3mQj7BLrs6

[linear]

ENG-653