examples: add runnable BRC-105 server + client demo

Author: kryp2

examples/README.md

@@ -0,0 +1,82 @@
+# Examples
+
+Runnable examples for `bsv-brc`. Each one is self-contained and small enough
+to read in a single sitting.
+
+## ⚠️ Demo only — read this first
+
+**These examples use fake stubs** for the parts that require a real BSV
+wallet. They demonstrate the *protocol flow*, not real cryptographic
+verification. Specifically:
+
+- `verify_payment` always accepts — production code must call your wallet's
+  `internalizeAction()` (or equivalent) and return the real result.
+- `build_payment` returns a hardcoded fake transaction — production code
+  must call your wallet's `createAction()` to build a real signed payment.
+- `get_identity_key` bypasses BRC-103 authentication for local testing —
+  production code must use real BRC-103/104 mutual auth (coming in a future
+  release of `bsv-brc`).
+
+**Do not deploy these examples as-is.** They will accept any payment (or
+none at all) and they will not protect you from anything. They exist so
+you can see the shape of the API in 30 seconds without needing a wallet
+running on your machine.
+
+## brc105 — HTTP 402 micropayments
+
+The `BRC-105` examples show the server and client sides of the 402 Payment
+Required flow. The two scripts talk to each other over HTTP on
+`127.0.0.1:8000`.
+
+### Run
+
+In one terminal:
+
+```bash
+pip install "bsv-brc[starlette]" uvicorn httpx
+python examples/brc105_minimal_server.py
+```
+
+In another terminal:
+
+```bash
+python examples/brc105_client.py
+```
+
+### What you should see
+
+Server side:
+```
+INFO:     Uvicorn running on http://127.0.0.1:8000
+INFO:     127.0.0.1:xxxxx - "GET /data HTTP/1.1" 402 Payment Required
+INFO:     127.0.0.1:xxxxx - "GET /data HTTP/1.1" 200 OK
+```
+
+Client side:
+```
+→ GET /data (no payment)
+  ← 402
+  challenge: 100 satoshis required
+→ GET /data (with payment)
+  ← 200
+  body: {'data': 'hello, paying customer', 'satoshis_paid': 100}
+  satoshis_paid header: 100
+```
+
+### What just happened
+
+1. Client requested a paid endpoint without including a payment header.
+2. Server's `PaymentMiddleware` saw no payment, generated a derivation
+   prefix nonce, and returned `402 Payment Required` with the challenge
+   in the response headers.
+3. Client parsed the challenge, built a payment (fake, in this example),
+   and retried the request with the `x-bsv-payment` header.
+4. Server's middleware verified the nonce, called `verify_payment` (which
+   in this demo always accepts), and let the request through to the
+   handler.
+5. Handler returned the response, and the middleware added an
+   `x-bsv-payment-satoshis-paid` header to confirm the amount.
+
+In a real deployment, steps 2 and 3 would involve actual BSV wallet
+operations and the payment would be a signed transaction the server can
+broadcast and verify on-chain.

examples/brc105_client.py

@@ -0,0 +1,87 @@
+"""
+BRC-105 minimal client example.
+
+Walks through the full 402 Payment Required flow against the example server:
+
+    1. Hit /data without payment           → 402 with payment challenge
+    2. Build a BSVPayment from the challenge → POST again with x-bsv-payment
+    3. Server accepts                       → 200 with the response
+
+Run the server first:
+    python examples/brc105_minimal_server.py
+
+Then in another terminal:
+    python examples/brc105_client.py
+
+⚠️  DEMO ONLY — DO NOT DEPLOY ⚠️
+The `build_payment` function in this example produces a fake payment with
+hardcoded values. In production you must call your BSV wallet's
+`createAction()` to build a real signed transaction that pays the server's
+derived output script.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+import httpx
+
+from bsv_brc.brc105 import BSVPayment, PaymentChallenge, parse_challenge_headers
+
+
+SERVER_URL = "http://127.0.0.1:8000"
+
+
+async def fake_build_payment(challenge: PaymentChallenge) -> BSVPayment:
+    """
+    DEMO ONLY. Returns a hardcoded fake payment.
+    In production, call wallet.createAction() with the challenge to build
+    a real signed BSV transaction paying the requested amount.
+    """
+    return BSVPayment(
+        derivation_prefix=challenge.derivation_prefix,
+        derivation_suffix="demo-suffix",
+        transaction="BASE64_FAKE_PAYMENT_TX_NOT_REAL",  # not a real AtomicBEEF
+    )
+
+
+async def main() -> None:
+    async with httpx.AsyncClient() as client:
+        # Step 1: hit /data with no payment
+        print("→ GET /data (no payment)")
+        r1 = await client.get(
+            f"{SERVER_URL}/data",
+            headers={"x-bsv-auth-identity-key": "demo-client-identity-key"},
+        )
+        print(f"  ← {r1.status_code}")
+
+        if r1.status_code != 402:
+            print(f"  unexpected response: {r1.text}")
+            return
+
+        # Step 2: parse the challenge from headers and build a fake payment
+        challenge = parse_challenge_headers(dict(r1.headers))
+        if challenge is None:
+            print("  challenge headers missing or malformed")
+            return
+        print(f"  challenge: {challenge.satoshis_required} satoshis required")
+
+        payment = await fake_build_payment(challenge)
+
+        # Step 3: retry with the payment header
+        print("→ GET /data (with payment)")
+        r2 = await client.get(
+            f"{SERVER_URL}/data",
+            headers={
+                "x-bsv-auth-identity-key": "demo-client-identity-key",
+                "x-bsv-payment": json.dumps(payment.to_dict()),
+            },
+        )
+        print(f"  ← {r2.status_code}")
+        print(f"  body: {r2.json()}")
+        print(f"  satoshis_paid header: {r2.headers.get('x-bsv-payment-satoshis-paid')}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/brc105_minimal_server.py

@@ -0,0 +1,91 @@
+"""
+BRC-105 minimal server example.
+
+A Starlette app with one paid endpoint (`/data`) that costs 100 satoshis,
+and one free endpoint (`/health`).
+
+Run:
+    pip install "bsv-brc[starlette]" uvicorn
+    python examples/brc105_minimal_server.py
+
+Then in another terminal:
+    python examples/brc105_client.py
+
+⚠️  DEMO ONLY — DO NOT DEPLOY ⚠️
+This example uses a fake `verify_payment` stub that accepts every payment
+without actually verifying anything on-chain. In production you must wire
+this up to a real BSV wallet via `wallet.internalizeAction()` (or equivalent).
+The `get_identity_key` override here also bypasses BRC-103 authentication
+for local testing — production code must NOT do this.
+"""
+
+from __future__ import annotations
+
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+from bsv_brc.brc105 import (
+    BSVPayment,
+    NonceManager,
+    PaymentMiddleware,
+    PaymentResult,
+    StaticPricing,
+)
+
+
+# --- handlers ---
+
+async def health(_: Request) -> JSONResponse:
+    return JSONResponse({"status": "ok"})
+
+
+async def data(request: Request) -> JSONResponse:
+    # PaymentMiddleware attaches the result to request.state on success.
+    paid = request.state.payment.satoshis_paid
+    return JSONResponse({"data": "hello, paying customer", "satoshis_paid": paid})
+
+
+# --- payment plumbing (DEMO STUBS — replace in production) ---
+
+async def fake_verify_payment(payment: BSVPayment, identity_key: str) -> PaymentResult:
+    """
+    DEMO ONLY. Always accepts. In production, call your BSV wallet's
+    internalizeAction() with the payment's transaction and return the
+    real result from the wallet.
+    """
+    return PaymentResult(satoshis_paid=100, accepted=True)
+
+
+def fake_get_identity_key(_: Request) -> str:
+    """
+    DEMO ONLY. Bypasses BRC-103 auth for local testing.
+    Production code must read a real identity key set by BRC-104 middleware.
+    """
+    return "demo-identity-key-not-for-production"
+
+
+# --- app ---
+
+app = Starlette(
+    routes=[
+        Route("/health", health),
+        Route("/data", data),
+    ],
+)
+
+app.add_middleware(
+    PaymentMiddleware,
+    nonce_manager=NonceManager(secret=b"demo-server-secret-change-me"),
+    pricing=StaticPricing(100),  # 100 satoshis per request
+    verify_payment=fake_verify_payment,
+    get_identity_key=fake_get_identity_key,
+    excluded_paths={"/health"},
+)
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="127.0.0.1", port=8000)