Batch failure isolation is per-transaction (chunk); with the default chunk size one bad recipient fails its chunk-mates

[resourcefulmind]

Area: Payments / batch transfers · Type: enhancement (payout safety) / documentation

Recipients are bundled into Solana transactions (default ~20 per tx). The failure unit is the transaction: if one recipient in a chunk makes its transaction fail, all recipients in that chunk fail with it. Per-recipient isolation requires maxRecipientsPerTransaction: 1.

Reproduce

# isolated (tested): maxRecipientsPerTransaction=1, one underfunded recipient -> only that one fails
# bundled (by design): default chunk size, one recipient fails at execution -> its whole chunk fails

Impact: for a payroll run, one bad account can fail up to ~19 innocent colleagues bundled in the same transaction; the safe pattern (chunk size 1) is not the default and is not surfaced.
Suggested fix: document the isolation model; consider defaulting payout batches to per-recipient isolation or surfacing the tradeoff in the API and dashboard.

[resourcefulmind]

Re-verified against main (ef573405) and against the tree as of 8 July. Unchanged, and accurate as filed. #878 refactored the module but carried the default (20 per transaction) and the chunk-wide failure settlement across untouched. maxRecipientsPerTransaction: 1 does give real isolation, though note it's a ceiling rather than an exact count, since transaction size can force smaller chunks anyway.

Re-scoping, and dropping the "change the default" ask. Bundling is defensible: per-recipient isolation multiplies transaction count and fees by up to 20x on a large payroll. The defect is that the tradeoff is invisible.

1. The options OpenAPI description doesn't mention failure isolation at all, and its example sets maxRecipientsPerTransaction: 20, advertising the bundled mode.
2. The payouts guide teaches a workaround for this endpoint instead of documenting it. transfer-batches appears zero times anywhere in apps/sdp-docs/content, and send-payouts.mdx:6 tells readers "SDP does not expose a 'batch' object", then walks them through calling POST /v1/payments/transfers once per recipient and reconciling by memo string-match. So anyone following our own docs to run payroll makes N calls instead of one, and never encounters the chunking behaviour this issue is about. Filing separately, it's bigger than this issue.
3. Every recipient in a failed chunk gets the same chunk-level error string, so an operator can't tell which one caused it and has to resubmit the whole group. Surfacing the culprit would cut blast radius without the fee cost.