Merge pull request #3 from naory/feat/pypi-ready-and-rpc-helper

PyPI readiness, CI, and fetch_transaction_jsonrpc helper

Author: naory

.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Checkout x402-xrpl (shared vectors)
+        uses: actions/checkout@v4
+        with:
+          repository: naory/x402-xrpl
+          path: x402-xrpl
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        env:
+          X402_TEST_VECTORS_PATH: ${{ github.workspace }}/x402-xrpl/conformance/test_vectors.json
+        run: PYTHONPATH=src python -m pytest
+
+      - name: Ruff check
+        run: ruff check src tests

README.md

@@ -4,10 +4,6 @@ Strict **server-side settlement verifier** for **x402 v2 payments on XRPL**.
 
 This package validates presigned XRPL `Payment` transactions and turns them into deterministic, replay-safe x402 settlement receipts for HTTP 402 flows.
 
-This repository is the Python port of the TypeScript XRPL adapter in
-[`naory/x402-xrpl`](https://github.com/naory/x402-xrpl). Both implementations
-share the same canonical conformance test vectors.
-
 Designed for backend services that require strong guarantees around:
 
 - On-ledger settlement verification
@@ -54,9 +50,10 @@ Minimal by design:
 - `InMemoryReplayStore`
 - `SettlementVerificationError`
 
-Optional helper:
+Optional helpers (stdlib-only; core stays dependency-free):
 
-- `x402_xrpl_adapter.rpc.XrplJsonRpcClient`
+- `fetch_transaction_jsonrpc(network_url, tx_hash)` — minimal RPC fetch
+- `x402_xrpl_adapter.rpc.XrplJsonRpcClient` — wrapper for `verify_settlement` callback
 
 ---
 
@@ -141,7 +138,18 @@ Second call with the same `paymentId` + `txHash` returns idempotent success.
 
 ## Optional XRPL JSON-RPC Helper
 
-You can use the bundled minimal helper and pass it directly as the callback:
+Minimal stdlib-only helpers. Core verifier stays dependency-free.
+
+**Function** — `fetch_transaction_jsonrpc(network_url, tx_hash)`:
+
+```python
+from x402_xrpl_adapter import fetch_transaction_jsonrpc
+
+tx = fetch_transaction_jsonrpc("https://s.altnet.rippletest.net:51234", "ABCDEF123...")
+# returns dict or None
+```
+
+**Class** — `XrplJsonRpcClient` for use as `verify_settlement` callback:
 
 ```python
 from x402_xrpl_adapter.rpc import XrplJsonRpcClient

pyproject.toml

@@ -5,13 +5,53 @@ build-backend = "hatchling.build"
 [project]
 name = "x402-xrpl-settlement-adapter-py"
 version = "0.1.0"
-description = "Strict x402 v2 settlement verifier for XRPL (Python port)"
+description = "Server-side settlement verifier for x402 v2 on XRPL (XRP & issued tokens like RLUSD): strict Payment validation, memo binding, replay protection, no paths/partials."
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 license = { text = "MIT" }
 authors = [{ name = "Naor Yuval" }]
+keywords = [
+  "x402",
+  "x402-v2",
+  "payment-protocol",
+  "http-402",
+  "payment-required",
+  "xrpl",
+  "xrp",
+  "rlusd",
+  "stablecoin",
+  "iou",
+  "issued-currency",
+  "settlement",
+  "settlement-verification",
+  "verifier",
+  "server",
+  "backend",
+  "middleware",
+  "receipt",
+  "replay-protection",
+  "xaman",
+  "xumm",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Office/Business :: Financial",
+  "Intended Audience :: Developers",
+]
 dependencies = []
 
+[project.urls]
+Homepage = "https://github.com/naory/x402-xrpl-python#readme"
+Repository = "https://github.com/naory/x402-xrpl-python"
+Documentation = "https://github.com/naory/x402-xrpl-python#readme"
+"Bug Tracker" = "https://github.com/naory/x402-xrpl-python/issues"
+
 [project.optional-dependencies]
 dev = [
   "pytest>=8.2.0",
@@ -27,7 +67,7 @@ addopts = "-q"
 
 [tool.ruff]
 line-length = 100
-target-version = "py39"
+target-version = "py310"
 
 [tool.ruff.lint]
 select = ["E", "F", "I"]

src/x402_xrpl_adapter/__init__.py

@@ -4,10 +4,12 @@
     create_challenge,
     verify_settlement,
 )
+from .rpc import fetch_transaction_jsonrpc
 
 __all__ = [
     "create_challenge",
     "verify_settlement",
     "SettlementVerificationError",
     "InMemoryReplayStore",
+    "fetch_transaction_jsonrpc",
 ]

src/x402_xrpl_adapter/rpc.py

@@ -1,8 +1,46 @@
+"""Optional XRPL JSON-RPC helpers. Stdlib-only; core verifier stays dependency-free."""
+
 import json
 from typing import Any, Dict, Optional
 from urllib.request import Request, urlopen
 
 
+def fetch_transaction_jsonrpc(network_url: str, tx_hash: str) -> Optional[Dict[str, Any]]:
+    """
+    Fetch a transaction from an XRPL node via JSON-RPC.
+
+    Args:
+        network_url: XRPL node URL (e.g. https://s.altnet.rippletest.net:51234).
+        tx_hash: Transaction hash (hex).
+
+    Returns:
+        Transaction result dict, or None if not found or on error.
+    """
+    payload = {
+        "method": "tx",
+        "params": [{"transaction": tx_hash, "binary": False}],
+    }
+    body = json.dumps(payload).encode("utf-8")
+    request = Request(
+        network_url,
+        data=body,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urlopen(request, timeout=10) as response:
+            raw = response.read().decode("utf-8")
+            parsed = json.loads(raw)
+    except Exception:
+        return None
+    result = parsed.get("result")
+    if not isinstance(result, dict):
+        return None
+    if result.get("error") is not None:
+        return None
+    return result
+
+
 class XrplJsonRpcClient:
     """Tiny optional helper for XRPL JSON-RPC tx lookup."""