python.yml

name: Python

on:
  push:
    branches: [main]
  pull_request:
  workflow_call:

jobs:
  test-python:
    name: Python tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
          cache: pip
      - name: Install Python SDK
        working-directory: python
        # Framework extras bring fastapi/flask/django so the solana_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,fastapi,flask,django]"
      - name: Lint with ruff
        working-directory: python
        run: ruff check src tests
      - name: Type check with pyright
        working-directory: python
        # 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% over solana_pay_kit (the MPP wire layer
        # now lives under solana_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_pay_kit \
            --cov-report=term-missing \
            --cov-report=json:coverage.json \
            --cov-fail-under=90 \
            --ignore=tests/test_server_html.py
      - name: Upload Python coverage
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: python-coverage
          path: python/coverage.json

  harness-python:
    name: Python harness matrix
    runs-on: ubuntu-latest
    needs: test-python
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
          cache: pip
      - uses: astral-sh/setup-uv@v5
      - name: Install Python SDK
        working-directory: python
        run: |
          python -m pip install --upgrade pip
          pip install -e ".[dev]"
      - uses: ./.github/actions/setup-harness
        with:
          cargo-bins: "paykit-harness-bins:mpp_harness_client,mpp_harness_server,x402_harness_client,x402_harness_server,x402_harness_upto_client,x402_harness_upto_server"
          cargo-cache-key: python
      # x402 upto settles on the canonical payment-channels program; the upto
      # e2e deploys this localnet SBF artifact onto the embedded surfnet. Mirrors
      # the harness-go job in .github/workflows/go.yml.
      - name: Checkout payment channels program
        uses: actions/checkout@v5
        with:
          repository: Moonsong-Labs/solana-payment-channels
          ref: 0c07d5751c8972abf6a219570a3f39a72f46f879
          path: _payment-channels
          fetch-depth: 1
      - name: Install Anza CLI
        run: |
          sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"
          echo "$HOME/.local/share/solana/install/active_release/bin" >> "$GITHUB_PATH"
      - name: Patch payment channels treasury owner
        working-directory: _payment-channels
        run: |
          program_id="CHNLxYvVA28MJP9PrFuDXccuoGXAx7jBacfLEkahyGsX"
          lib_file="program/payment_channels/src/lib.rs"
          sentinel_file="program/payment_channels/src/constants.rs"
          sentinel_prefix="    0xb0, 0x41, 0xd9, 0xd3, 0x37, 0xb7, 0x21, 0xbe, 0x57, 0x89, 0x4e, 0xb6, 0x9c, 0x3b, 0x68, 0x09,"
          sentinel_suffix="    0xa5, 0x3a, 0x0e, 0x2b, 0x6a, 0x23, 0x99, 0xfc, 0x7d, 0x5b, 0x7e, 0xda, 0x8c, 0xac, 0x89, 0xaa,"
          # The pinned upstream ref already declares our canonical program id, so
          # only the localnet treasury-owner sentinel needs patching. Guard the id
          # assumption so a future ref bump that changes it fails loudly here.
          if ! grep -Fq "declare_id!(\"$program_id\")" "$lib_file"; then
            echo "::error::payment-channels no longer declares $program_id; revisit this patch"
            exit 1
          fi
          perl -0pi -e 's/const TREASURY_OWNER_SENTINEL: \[u8; 32\] = \[\n.*?\n\];/const TREASURY_OWNER_SENTINEL: [u8; 32] = [\n    0xb0, 0x41, 0xd9, 0xd3, 0x37, 0xb7, 0x21, 0xbe, 0x57, 0x89, 0x4e, 0xb6, 0x9c, 0x3b, 0x68, 0x09,\n    0xa5, 0x3a, 0x0e, 0x2b, 0x6a, 0x23, 0x99, 0xfc, 0x7d, 0x5b, 0x7e, 0xda, 0x8c, 0xac, 0x89, 0xaa,\n];/s' "$sentinel_file"
          if ! grep -Fq "$sentinel_prefix" "$sentinel_file" || ! grep -Fq "$sentinel_suffix" "$sentinel_file"; then
            echo "::error::payment-channels treasury sentinel patch did not apply"
            exit 1
          fi
      - name: Build payment channels program
        working-directory: _payment-channels/program/payment_channels
        run: cargo build-sbf --tools-version v1.52 --arch v1
      # Sync the uv environment the conformance runner (runners/python.json:
      # ``uv run python conformance_runner.py``) executes in, so the cross-SDK
      # vectors - including the frozen 48-byte session voucher preimage - run
      # without a per-vector cold install.
      - name: Sync Python uv environment
        working-directory: python
        run: uv sync --extra dev
      # Cross-SDK conformance vectors for Python: charge, x402-exact, and the
      # session voucher-preimage byte-vector (runners/python.json declares the
      # session intent). Pins the Python session wire bytes against the frozen
      # cross-SDK vector rather than only the charge path.
      - name: Run Python cross-SDK conformance vectors
        working-directory: harness
        env:
          MPP_CONFORMANCE_LANGUAGES: python
        run: pnpm exec vitest run test/conformance.test.ts
      - name: Focused Python session harness
        working-directory: harness
        env:
          MPP_HARNESS_INTENTS: session
          MPP_HARNESS_SCENARIOS: session-basic
          MPP_HARNESS_CLIENTS: python-session
          MPP_HARNESS_SERVERS: python
        run: pnpm exec vitest run test/e2e.test.ts
      - name: Focused TS-to-Python harness
        working-directory: harness
        env:
          MPP_HARNESS_CLIENTS: typescript
          MPP_HARNESS_SERVERS: python
        run: pnpm exec vitest run test/e2e.test.ts
      - name: Focused Rust-to-Python harness
        working-directory: harness
        env:
          MPP_HARNESS_CLIENTS: rust
          MPP_HARNESS_SERVERS: python
        run: pnpm exec vitest run test/e2e.test.ts
      # x402 exact: drive the Python solana_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_HARNESS_CLIENT_SECRET_KEY. The matrix pairs
      # every active client x active server, so the MPP_HARNESS_* 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 solana_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_HARNESS_INTENTS: x402-exact
          MPP_HARNESS_SCENARIOS: x402-exact-basic
          MPP_HARNESS_CLIENTS: python-x402
          MPP_HARNESS_SERVERS: rust-x402,python
          X402_HARNESS_CLIENTS: python-x402
          X402_HARNESS_SERVERS: rust-x402,python
        run: pnpm exec vitest run test/e2e.test.ts --testTimeout 180000
      # x402 upto: drive the Python solana_pay_kit upto client + PayKit upto server
      # (channel open + voucher settle on the embedded surfnet) against the Rust
      # upto reference. x402-upto-basic runs every active client x server; the
      # zero-actual scenario is pinned to rust-x402-upto (serverIds in
      # intents/x402-upto.ts), so the fail-closed PayKit python/go servers are
      # excluded from it. Requires the payment-channels .so built above.
      - name: Focused python-x402-upto -> rust/python upto servers
        working-directory: harness
        env:
          MPP_HARNESS_INTENTS: x402-upto
          MPP_HARNESS_SCENARIOS: x402-upto-basic,x402-upto-zero-actual
          MPP_HARNESS_CLIENTS: python-x402-upto,rust-x402-upto
          MPP_HARNESS_SERVERS: python-x402-upto,rust-x402-upto
          X402_HARNESS_CLIENTS: python-x402-upto,rust-x402-upto
          X402_HARNESS_SERVERS: python-x402-upto,rust-x402-upto
          PAYMENT_CHANNELS_PROGRAM_SO: ../_payment-channels/target/deploy/payment_channels.so
          PAYMENT_CHANNELS_PROGRAM_ID: CHNLxYvVA28MJP9PrFuDXccuoGXAx7jBacfLEkahyGsX
          SURFPOOL_DATASOURCE_RPC_URL: ${{ secrets.SURFPOOL_DATASOURCE_RPC_URL }}
        run: pnpm exec vitest run test/e2e.test.ts --testTimeout 180000