feat(python): MPP sessions (client + server + playground)

[EfeDurmaz16]

What this adds

The MPP session intent for the Python SDK, now both halves plus the example app, bringing Python to parity with the Go port (#160). Rebased onto main (which carries #160), so the diff is the Python session surface only.

• Wire types protocols/mpp/intents/session.py — SessionRequest, the SessionAction tagged union (open / voucher / commit / topUp / close), signed vouchers, metering types.
• Client protocols/mpp/client/session.py + session_consumer.py — ActiveSession (voucher signing, monotonic watermark, action builders) and SessionConsumer (metered ack/commit).
• Server protocols/mpp/server/session_*.py — the full server method ported from go/protocols/mpp/server against the Rust spine (rust/crates/mpp/src/server/session.rs) as wire truth: session_store (channel store with per-channel-locked read-modify-write and Go-faithful nil-slice serialization), session_voucher (offline voucher verifier), session_lifecycle, session_onchain (open/top-up verification with an optional RPC liveness seam, submit-open server-broadcast, and settle-at-close), session_method (new_session + open/voucher/commit/topUp/close handlers, re-drivable close, pull-mode guard, atomic settle-in-progress guard), session_stream (metered SSE), session_routes + session (HTTP routes with strict typed decode, public SessionServer).
• Generated client protocols/programs/paymentchannels/ — codama-py output (Go uses @codama/renderers-go); regenerate with just payment-channels-generate-py.
• Playground examples/playground_api/ — FastAPI port of go/examples/playground-api: charges (stocks/marketplace/weather with fee splits), the metered session stream/compute/receipt, x402, faucet, docs, health/config catalog.

Reviewing it

Suggested read order (the generated client and the playground example can be skimmed):

1. protocols/mpp/intents/session.py (wire types)
2. protocols/mpp/client/session.py, session_consumer.py
3. protocols/mpp/server/session_store.py, session_voucher.py, session_method.py (the fund-safety surface)
4. protocols/mpp/server/session_routes.py (HTTP + strict decode)
5. protocols/mpp/server/session_onchain.py (server-broadcast open + settle-at-close + polling confirmation)
6. examples/playground_api/ (runnable example)

On-chain broadcast and settlement

The Python SDK now ships the server-side on-chain paths the Go/TS servers have:

• Server-broadcast open (openTxSubmitter=server): the server completes the fee-payer signature on a client-built open transaction, broadcasts it, and waits for confirmation before persisting channel state. Mirrors the TS submitOpenTx helper. A replayed open does NOT re-broadcast: a store existence pre-check short-circuits to the idempotent process_open path before the broadcast, since re-sending an already-landed open would break idempotent-replay semantics.
• Settle at close (settle_and_finalize_channel): a close with a signer and RPC configured builds the settle_and_finalize instruction (preceded by the Ed25519 precompile when a voucher was recorded) plus a distribute instruction, signs, broadcasts, and confirms, then records the settlement signature and finalizes. The close is re-drivable when no settlement signature was recorded so a transient settlement failure cannot strand the channel.
• Polling confirmation (confirm_transaction_signature): a freshly broadcast signature commonly returns None from getSignatureStatuses for hundreds of ms to seconds. The helper now polls (mirroring the TS waitForSignatureConfirmation) until the signature reaches at least confirmed, fails on-chain, or times out (default 30s). This replaces the old single-shot check, which raised spuriously on just-broadcast transactions. The already-landed open/top-up verify path (verify_open_tx) keeps the single-shot liveness check, since the signature there was supplied by the client and is expected to be known.
• Atomic settle-in-progress guard (settling): the settle path claims a settling flag under the per-channel store lock before broadcasting, so a concurrent close retry or idle-watchdog fire cannot both pass the finalize check and broadcast duplicate settle transactions. The guard is released by the finalize mutator (which sets finalized), or by a failed broadcast path so a retry can claim again.

The RPC client remains optional: with no RPC the open/top-up signatures and deposit amounts are trusted as provided (offline core), and close is a pure state-flip with settledSignature=null. Mirrors how the Go port treats the RPC client as optional; the playground uses the client submitter with rpc=None accordingly.

Verification

ruff check, ruff format, pyright (0 errors), pytest --cov=pay_kit --cov-fail-under=90 (cov 93.6%). The server modules mirror Go's test behaviors test-first. Manual check: the playground responds with real 402 Payment challenges on the session stream, charge, and x402 routes; the app boots with all routes registered. The server-broadcast open path reaches the RPC (fails on blockhash-not-found without a live validator, not the old verify_open_tx hard-reject). Pull-mode opens with no transaction skip the server-broadcast path and trust the channel id/deposit, mirroring the TS else open branch. The 48-byte voucher preimage and single-byte discriminators (open=1, topUp=3) match the Rust/Go frozen vectors.

---

Reviewer note (sakana-reviewer, fugu-ultra)

Independent verification against branch tip 81dde1d3. All three fixes (polling confirm, replay-safe open broadcast, atomic settle guard) hold against the current tree.

• B1 sound: confirm_transaction_signature (session_onchain.py:354-417) now polls getSignatureStatuses on a 30s/1s deadline, exits on err (transaction-failed), treats confirmationStatus of None/confirmed/finalized as success, and cleanly distinguishes transaction-not-found (no status ever seen) from transaction-not-confirmed (saw a status, timed out). Wired into the settle broadcast (:493), so just-broadcast settles no longer reject spuriously.
• S1 preserves idempotency: the pre-broadcast get_channel check (session_method.py:551-580) only short-circuits the re-broadcast; process_open (session.py:341-353) remains the atomic check-and-insert source of truth, returning existing state unchanged with the voucher watermark intact. Sequential replay is broadcast-safe; truly concurrent first-opens stay bounded by the atomic mutator.
• S2 race-safe: _settle_channel (session_method.py:768-833) claims settling under the per-channel store lock, losers return None/the finalized signature without broadcasting, the guard is released on broadcast/confirm failure, and finalize clears it. Confirm-before-finalize + on-chain idempotency contain the restart window (settling is intentionally transient/unserialized).
• No fund-safety regressions: no path double-credits, leaks, or bypasses the deposit; deposit is never re-credited, settle is single-broadcast, and finalize keeps the winner's signature. Approve.

[greptile-apps]

Greptile Summary

This PR ports the full MPP session intent to the Python SDK, including wire types, client (ActiveSession, SessionConsumer), server (store, voucher verifier, lifecycle, on-chain open/settle paths, metered SSE, HTTP routes), a codama-generated payment-channels client, and a FastAPI playground — bringing Python to parity with the Go/TS session surface.

• Wire types & client (intents/session.py, client/session.py, session_consumer.py): cumulative-watermark voucher signing, monotonic watermark guard, action builders, and a SessionConsumer wrapping the Kafka-style metered-delivery ack loop.
• Server (server/session_*.py): full per-channel locked store, Ed25519 voucher verifier, on-chain open/top-up verification with polling confirmation, atomic settle-in-progress guard, re-drivable close, idle-close watchdog, and server-broadcast open (all previous fund-safety issues — missing confirmation, payer/deposit propagation, duplicate finalize, idle-close state-flip — are fixed at this HEAD).
• Playground (examples/playground_api/): FastAPI port of the Go playground with metered stream, charge, x402, and faucet routes.

Confidence Score: 5/5

Safe to merge. All fund-safety paths (payer/deposit propagation, settlement confirmation, atomic settle guard, idle-close state-flip, duplicate-finalize protection) are correctly implemented at this HEAD.

The fund-safety surface reviewed exhaustively: payer and deposit are propagated from verify_open_tx before process_open persists them; settle_and_finalize_channel polls for confirmation before returning; the finalize mutator is idempotent; the settling flag is claimed and released atomically. All previously flagged issues resolved. Two remaining comments are minor style/robustness nits.

No files require special attention. The release mutator type-ignore in session_method.py is only reachable by a custom ChannelStore that calls delete_channel on an actively-settling channel, which is not possible with the built-in MemoryChannelStore.

Important Files Changed

Filename	Overview
python/src/pay_kit/protocols/mpp/server/session_method.py	Core session method handler: open/voucher/commit/topUp/close dispatch with on-chain verify, atomic settle guard, re-drivable close, and idle-close watchdog. All previously flagged fund-safety issues fixed. One suppressed type-ignore in the release mutator is a minor robustness gap for custom store implementors.
python/src/pay_kit/protocols/mpp/server/session_onchain.py	On-chain open verification, server-broadcast cosign, polling confirmation (30s deadline), and settle_and_finalize_channel with confirm-before-return. All previous issues resolved.
python/src/pay_kit/protocols/mpp/server/session_store.py	Per-channel locked MemoryChannelStore with correct lock-then-_mu ordering in delete_channel. Go-faithful nil-slice serialization preserved.
python/src/pay_kit/protocols/mpp/server/session_routes.py	Metered side-channel routes with strict typed decode. All previously flagged 400-boundary gaps fixed.
python/src/pay_kit/protocols/mpp/intents/session.py	Wire types for all five session actions. CommitReceipt.from_dict raises on unknown/absent status. Base-unit parsing routes through _parse_base_units throughout.
python/src/pay_kit/protocols/mpp/client/session_consumer.py	Kafka-style consumer with prepare/record split for safe commit retries. Replayed receipt path correctly clamps watermark advance.
python/examples/playground_api/sessions.py	FastAPI playground session route with pull mode + clientVoucher and idle-close watchdog. Accesses session._touch as a private method — minor style issue.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant C as Client
    participant S as Session (HTTP layer)
    participant Store as ChannelStore
    participant RPC as Solana RPC

    C->>S: GET /api/v1/stream (no Auth)
    S-->>C: 402 WWW-Authenticate (SessionRequest challenge)
    C->>S: POST open action (Authorization: Bearer ...)
    S->>S: HMAC verify challenge
    alt has_transaction and server submitter
        S->>S: verify_open_tx (structural)
        S->>RPC: cosign + send_raw_transaction
        S->>RPC: confirm_transaction_signature (poll 30s)
        RPC-->>S: confirmed
    else has_transaction and client submitter
        S->>RPC: confirm_transaction_signature (optional)
    end
    S->>Store: process_open (atomic insert)
    S-->>C: 200 X-Payment-Receipt
    loop Metered deliveries
        C->>S: POST /__402/session/deliveries
        S->>Store: begin_delivery
        S-->>C: 200 MeteringDirective
        C->>S: POST /__402/session/commit (signed voucher)
        S->>Store: process_commit (atomic watermark advance)
        S-->>C: 200 CommitReceipt
    end
    C->>S: POST close action (final voucher)
    S->>Store: update_channel (flip close_requested_at)
    S->>Store: "update_channel (claim settling=True)"
    S->>RPC: settle_and_finalize_channel
    S->>RPC: confirm_transaction_signature
    RPC-->>S: confirmed
    S->>Store: "update_channel (finalized=True, settled_signature)"
    S-->>C: 200 X-Payment-Receipt (settled signature)

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant C as Client
    participant S as Session (HTTP layer)
    participant Store as ChannelStore
    participant RPC as Solana RPC

    C->>S: GET /api/v1/stream (no Auth)
    S-->>C: 402 WWW-Authenticate (SessionRequest challenge)
    C->>S: POST open action (Authorization: Bearer ...)
    S->>S: HMAC verify challenge
    alt has_transaction and server submitter
        S->>S: verify_open_tx (structural)
        S->>RPC: cosign + send_raw_transaction
        S->>RPC: confirm_transaction_signature (poll 30s)
        RPC-->>S: confirmed
    else has_transaction and client submitter
        S->>RPC: confirm_transaction_signature (optional)
    end
    S->>Store: process_open (atomic insert)
    S-->>C: 200 X-Payment-Receipt
    loop Metered deliveries
        C->>S: POST /__402/session/deliveries
        S->>Store: begin_delivery
        S-->>C: 200 MeteringDirective
        C->>S: POST /__402/session/commit (signed voucher)
        S->>Store: process_commit (atomic watermark advance)
        S-->>C: 200 CommitReceipt
    end
    C->>S: POST close action (final voucher)
    S->>Store: update_channel (flip close_requested_at)
    S->>Store: "update_channel (claim settling=True)"
    S->>RPC: settle_and_finalize_channel
    S->>RPC: confirm_transaction_signature
    RPC-->>S: confirmed
    S->>Store: "update_channel (finalized=True, settled_signature)"
    S-->>C: 200 X-Payment-Receipt (settled signature)

Loading

_{Reviews (35): Last reviewed commit: "test(python/mpp): add session harness co..." | Re-trigger Greptile}