closedhumanPR #116Payments
stripe-engineer: Production-grade streaming payments with idempotency, conservation invariants, and adversarial property tests
This PR hardens the streaming payments plugin against the failure modes that naive debit-credit ledgers silently accept. Every stream mutation is now idempotency-keyed, and the plugin enforces three invariants at the balance level that…
Author
@stanleyoz
github profile →- Status
- Closed without merging
- Opened on
- Jul 9
- Branch
- hackathon/stripe-engineer-streaming-payments
Description
The pitch.
## What This PR hardens the streaming payments plugin against the failure modes that naive debit-credit ledgers silently accept. Every stream mutation is now idempotency-keyed, and the plugin enforces three invariants at the balance level that `prepaid_credits` cannot: **conservation** (total wealth constant across all operations), **rate enforcement** (no tick drains more than `rate_per_tick`), and **stop-on-close** (zero balance change after `close_stream`). ## Why (Persona: stripe-engineer) Stripe's API design principles — idempotency keys, conservation-first ledgers, typed error surfaces, audit trails — map directly to the streaming payments problem. A Stripe payments engineer ships a plugin where: - **Retrying a close that already succeeded returns the original receipt**, not a `ValueError` - **Repeating a tick with the same logical timestamp does not double-bill**, because the audit trail's last entry tick is checked - **Refunding a stream returns the full debited amount to the payer** with roles swapped in the receipt - **Every debit is traceable** via `StreamEntry` records with tick, amount, and kind ## What Changed **Plugin** (`streaming.py`, +313 lines): `StreamError` typed exception, `refund_stream()` lifecycle, `locked_funds()` / `active_streams()` / `stream()` inspection API, `StreamEntry` audit trail dataclass, and idempotency-key semantics on `open_stream`, `close_stream`, `tick_stream`, and `pay`. **Validators** (4 new, 7 total): - `validate_streaming_rate_enforcement` — groups debits by (ref, tick), fails if per-tick sum > `rate_per_tick` - `validate_streaming_no_double_open` — detects any ref opened more than once - `validate_streaming_conservation_per_tick` — running balance check at every tick boundary - `validate_streaming_audit_trail_complete` — every open has a matching close **Tests** (45 total, 18 Hypothesis property-based): Hypothesis generates arbitrary sequences of open/tick/close/refund and verifies conservation, rate enforcement, idempotency, stop-on-close, max-total enforcement, determinism, and adversarial attacks (reopen-closed, refund-open, double-bill-same-tick). **Scenario built-in** (`streaming_payments.py`): Buyer-seller tick-drain loop with configurable early-close, emitting all 7 validator trace events. ## Verification ```bash # Run the streaming property suite uv run pytest packages/nest-plugins-reference/tests/test_streaming_properties.py -v # Run the full streaming test suite uv run pytest packages/nest-plugins-reference/tests/test_streaming*.py -v # Full CI make ci-local # ruff check, ruff format --check, pyright, pytest -v (972 passed) ``` ## Tradeoffs - **Idempotency storage**: `_closed_receipts` dict grows linearly with closed streams. Fine for 10K streams (~1 MB); beyond that, expiry-eviction would be needed - **Stream refund only after close**: matches Stripe's refund-after-capture semantics - **No multi-payee streams**: bilateral only, per the problem scope - **In-memory only**: no persistence; the audit trail loses state across process restarts (matches `prepaid_credits`)
Try it
Open PR on GitHubView diffCheckout locally
git fetch origin pull/116/head:pr-116
git checkout pr-116