feat(python): add unified pay_kit surface with x402 exact

.github/workflows/ci.yml

@@ -123,9 +123,9 @@ jobs:
       - name: Verify committed gen files are up to date
         working-directory: .
         run: |
-          if ! git diff --quiet -- rust/src/server/html/ go/protocols/mpp/server/html/ lua/mpp/server/html_assets/ python/src/solana_mpp/server/html/; then
+          if ! git diff --quiet -- rust/src/server/html/ go/protocols/mpp/server/html/ lua/mpp/server/html_assets/ python/src/pay_kit/protocols/mpp/server/html/; then
             echo "::error::Generated files are out of date. Run 'just html-build' and commit the results."
-            git diff --stat -- rust/src/server/html/ go/protocols/mpp/server/html/ lua/mpp/server/html_assets/ python/src/solana_mpp/server/html/
+            git diff --stat -- rust/src/server/html/ go/protocols/mpp/server/html/ lua/mpp/server/html_assets/ python/src/pay_kit/protocols/mpp/server/html/
             exit 1
           fi
       - name: Upload HTML build artifacts
@@ -137,7 +137,7 @@ jobs:
             rust/src/server/html/
             go/protocols/mpp/server/html/
             lua/mpp/server/html_assets/
-            python/src/solana_mpp/server/html/
+            python/src/pay_kit/protocols/mpp/server/html/
             typescript/packages/mpp/src/server/html-assets.gen.ts
 
   test-rust:

.github/workflows/python.yml

@@ -18,21 +18,28 @@ jobs:
           cache: pip
       - name: Install Python SDK
         working-directory: python
+        # Framework extras bring fastapi/flask/django so the pay_kit shim tests
+        # import and pyright can resolve them; dev brings ruff, pyright, pytest.
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev]"
+          pip install -e ".[dev,fastapi,flask,django]"
       - name: Lint with ruff
         working-directory: python
         run: ruff check src tests
       - name: Type check with pyright
         working-directory: python
-        run: pyright
+        # Point pyright at the interpreter the extras were installed into; it
+        # does not reliably auto-detect the active env on the runner.
+        run: pyright --pythonpath "$(python -c 'import sys; print(sys.executable)')"
       - name: Run tests with coverage
         working-directory: python
-        # Coverage gate: line coverage at 90%. Branch coverage gate is follow-up work, tracked in #108.
+        # Coverage gate: line coverage at 90% over pay_kit (the MPP wire layer
+        # now lives under pay_kit/protocols/mpp). preflight.py is omitted in
+        # pyproject (live-RPC paths). Branch coverage gate is follow-up work,
+        # tracked in #108.
         run: |
           pytest \
-            --cov=solana_mpp \
+            --cov=pay_kit \
             --cov-report=term-missing \
             --cov-report=json:coverage.json \
             --cov-fail-under=90 \
@@ -93,7 +100,9 @@ jobs:
         run: pnpm --filter @solana/mpp build
       - name: Build Rust interop adapters
         working-directory: rust
-        run: cargo build -p solana-mpp --bin interop_client --bin interop_server
+        run: |
+          cargo build -p solana-mpp --bin interop_client --bin interop_server
+          cargo build -p solana-x402 --bin interop_client --bin interop_server
       - name: Install interop harness
         working-directory: harness
         run: pnpm install --frozen-lockfile
@@ -109,3 +118,24 @@ jobs:
           MPP_INTEROP_CLIENTS: rust
           MPP_INTEROP_SERVERS: python
         run: pnpm exec vitest run test/e2e.test.ts
+      # x402 exact: drive the Python pay_kit x402 client (a real signed v0
+      # VersionedTransaction) against the full-settling rust and python x402
+      # servers. test/e2e.test.ts self-hosts surfnet and threads the funded
+      # client keypair into X402_INTEROP_CLIENT_SECRET_KEY. The matrix pairs
+      # every active client x active server, so the MPP_INTEROP_* selectors are
+      # also set to keep the default charge-enabled adapters (typescript, php,
+      # go) out of this x402 run. ts-x402 is excluded: its stub server expects a
+      # payload.challengeId and never broadcasts a real transaction, so it
+      # cannot settle a genuine signed tx (same reason rust-x402 skips it). The
+      # x402 client adapter imports pay_kit from python/src on sys.path (no
+      # extra install beyond the editable SDK above).
+      - name: Focused python-x402 -> rust/python x402 servers
+        working-directory: harness
+        env:
+          MPP_INTEROP_INTENTS: x402-exact
+          MPP_INTEROP_SCENARIOS: x402-exact-basic
+          MPP_INTEROP_CLIENTS: python-x402
+          MPP_INTEROP_SERVERS: rust-x402,python
+          X402_INTEROP_CLIENTS: python-x402
+          X402_INTEROP_SERVERS: rust-x402,python
+        run: pnpm exec vitest run test/e2e.test.ts --testTimeout 180000

README.md

@@ -79,7 +79,7 @@ cargo add solana-mpp
 go get github.com/solana-foundation/pay-kit/go
 
 # Python
-pip install solana-mpp
+pip install solana-pay-kit
 
 # Ruby
 cd ruby && bundle install
@@ -121,13 +121,16 @@ return result.withReceipt(Response.json({ data: '...' }))
 <summary>Python</summary>
 
 ```python
-from solana_mpp.server import Mpp, Config
+from pay_kit import MemoryStore
+from pay_kit.protocols.mpp.server import Config, Mpp
 
 mpp = Mpp(Config(
     recipient="RecipientPubkey...",
     currency="EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
     decimals=6,
     html=True,
+    secret_key="...",       # or set MPP_SECRET_KEY in the environment
+    store=MemoryStore(),    # required; use FileReplayStore(path) for durable replay
 ))
 
 challenge = mpp.charge("1.00")  # 1 USDC

docs/security/compute-budget-caps.md

@@ -51,7 +51,7 @@ this monorepo.
 | Lua (#103)  | `lua/mpp/methods/solana/instructions.lua:31`               | `MAX_COMPUTE_UNIT_LIMIT` (pending PR #103 merge)              |
 | Lua (#103)  | `lua/mpp/methods/solana/instructions.lua:32`               | `MAX_COMPUTE_UNIT_PRICE_MICROLAMPORTS` (pending PR #103 merge) |
 | Go (#101)   | `go/protocols/mpp/server/server.go` (`maxComputeUnitLimit`)              | pending PR #101 merge                     |
-| Python (#106) | `python/src/solana_mpp/server/mpp.py`                    | pending PR #106 merge                     |
+| Python (#106) | `python/src/pay_kit/protocols/mpp/server/charge.py`      | pending PR #106 merge                     |
 
 `harness/test/compute-budget-caps.test.ts` parses each file above
 and asserts byte-identical literals against the canonical pair. Go and

docs/security/fee-payer-drain.md

@@ -28,7 +28,7 @@ Client crafts a transaction where the fee-payer is placed at a non-canonical sig
 
 ### 4. Tampered-Details Attack (Client-Supplied `methodDetails.feePayerKey`)
 
-The MPP charge request carries `methodDetails.feePayerKey` (string, base58 pubkey; this is the canonical wire field across all SDKs, see [`typescript/packages/mpp/src/Methods.ts`](../../typescript/packages/mpp/src/Methods.ts) L62, [`go/paycore/solana.go`](../../go/paycore/solana.go) L115, [`python/src/solana_mpp/protocol/solana.py`](../../python/src/solana_mpp/protocol/solana.py) L120, [`rust/crates/mpp/src/protocol/solana.rs`](../../rust/crates/mpp/src/protocol/solana.rs) L394, [`php/src/Server/SolanaChargeTransactionVerifier.php`](../../php/src/Server/SolanaChargeTransactionVerifier.php) L304, [`ruby/lib/mpp/methods/solana/verifier.rb`](../../ruby/lib/mpp/methods/solana/verifier.rb), [`lua/mpp/server/init.lua`](../../lua/mpp/server/init.lua) L85). A malicious client supplies `methodDetails.feePayerKey = ATTACKER_PUBKEY` while the server's actual signing key is `SERVER_PUBKEY`. If the verifier trusts the client-supplied details field as the source of truth for "who is the fee-payer", it will validate guards (source != fee-payer, slot, etc.) against `ATTACKER_PUBKEY`. The real `SERVER_PUBKEY` then signs a transaction that drains itself.
+The MPP charge request carries `methodDetails.feePayerKey` (string, base58 pubkey; this is the canonical wire field across all SDKs, see [`typescript/packages/mpp/src/Methods.ts`](../../typescript/packages/mpp/src/Methods.ts) L62, [`go/paycore/solana.go`](../../go/paycore/solana.go) L115, [`python/src/pay_kit/_paycore/solana.py`](../../python/src/pay_kit/_paycore/solana.py) L120, [`rust/crates/mpp/src/protocol/solana.rs`](../../rust/crates/mpp/src/protocol/solana.rs) L394, [`php/src/Server/SolanaChargeTransactionVerifier.php`](../../php/src/Server/SolanaChargeTransactionVerifier.php) L304, [`ruby/lib/mpp/methods/solana/verifier.rb`](../../ruby/lib/mpp/methods/solana/verifier.rb), [`lua/mpp/server/init.lua`](../../lua/mpp/server/init.lua) L85). A malicious client supplies `methodDetails.feePayerKey = ATTACKER_PUBKEY` while the server's actual signing key is `SERVER_PUBKEY`. If the verifier trusts the client-supplied details field as the source of truth for "who is the fee-payer", it will validate guards (source != fee-payer, slot, etc.) against `ATTACKER_PUBKEY`. The real `SERVER_PUBKEY` then signs a transaction that drains itself.
 
 Source of truth MUST be the server-context fee-payer pubkey (the public key of the server's signer keypair), never a client-controlled field.
 
@@ -67,7 +67,7 @@ A passing fee-payer co-sign path is the conjunction of all four. Missing any one
 | PHP      | [`php/src/Server/SolanaChargeTransactionVerifier.php`](../../php/src/Server/SolanaChargeTransactionVerifier.php): `validateInstructionAllowlist` (L454), invoked from both push (L169) and pull (L216) paths in the same file |
 | Ruby     | [`ruby/lib/mpp/methods/solana/verifier.rb`](../../ruby/lib/mpp/methods/solana/verifier.rb): `validate_allowlist` (L191), `expected_fee_payer` (L100), source-vs-fee-payer guards at L128, L156, L158 |
 | Lua      | [`lua/mpp/server/solana_verify.lua`](../../lua/mpp/server/solana_verify.lua): `verify_instruction_allowlist` (L330), invoked from the main verify path at L140 |
-| Python   | `python/src/solana_mpp/server/mpp.py`: `_validate_instruction_allowlist` (lands with [#106](https://github.com/solana-foundation/mpp-sdk/pull/106)) |
+| Python   | `python/src/pay_kit/protocols/mpp/server/charge.py`: `_validate_instruction_allowlist` (lands with [#106](https://github.com/solana-foundation/mpp-sdk/pull/106)) |
 | Go       | `go/protocols/mpp/server/server.go`: allowlist branch inside `verifyTransaction` (lands with [#101](https://github.com/solana-foundation/mpp-sdk/pull/101)) |
 
 The Rust path is the spine. PHP, Ruby, Lua, Python, and Go port the same four invariants with language-idiomatic surfaces.