qed-proof 0.1.1__py3-none-any.whl

qed_proof/__init__.py

@@ -0,0 +1,42 @@
+"""qed-proof: the Python SDK for QED Proof.
+
+    from qed_proof import QedProof, actions, verify_receipt
+
+    qp = QedProof(api_key="qed_sk_...")
+    claim = qp.submit_claim(actions.github_commit_push(target="owner/repo", sha="...", branch="main"),
+                            agent_id="my-agent")
+    result = qp.wait_for_verdict(claim.claim_id)
+    receipt = qp.get_receipt(result.receipt_id)
+    report = verify_receipt(receipt, keys=qp.get_keys())
+"""
+from __future__ import annotations
+
+from . import actions
+from .actions import Action
+from .client import (
+    AsyncQedProof,
+    ClaimPage,
+    ClaimResult,
+    QedProof,
+    QedProofError,
+    QedProofRateLimited,
+    QedProofTimeout,
+)
+from .verify import VerifyReport, verify_receipt
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "Action",
+    "actions",
+    "AsyncQedProof",
+    "ClaimPage",
+    "ClaimResult",
+    "QedProof",
+    "QedProofError",
+    "QedProofRateLimited",
+    "QedProofTimeout",
+    "VerifyReport",
+    "verify_receipt",
+    "__version__",
+]

qed_proof/_anchor.py

@@ -0,0 +1,75 @@
+"""Ported, not imported: SPEC §8.4's on-chain anchor check (``oss/spec/tools/anchor_check.py``).
+
+Checks a receipt's ``proof.anchor`` (scheme ``eas``) against a public JSON-RPC endpoint. It needs no
+issuer API, only the chain: EAS.getAttestation(uid) must be a live, unrevoked attestation made by an
+address the issuer publishes, under a schema the issuer publishes, whose data decodes to this proof's
+(log_id, tree_size, root_hash).
+
+Requires the ``qed-proof[anchor]`` extra (``eth-abi``, ``eth-hash``). Importing this module without it
+installed raises an ``ImportError`` with a clear message, from ``verify_receipt``'s call site.
+"""
+from __future__ import annotations
+
+import json
+import urllib.request
+
+try:
+    from eth_abi import decode as abi_decode
+    from eth_hash.auto import keccak
+except ImportError as exc:  # pragma: no cover - exercised via verify.py's guard
+    raise ImportError(
+        "the 'anchor' extra is required to check an on-chain anchor: pip install 'qed-proof[anchor]'"
+    ) from exc
+
+EAS = "0x4200000000000000000000000000000000000021"  # the OP-stack predeploy (Base mainnet + Base Sepolia)
+_GET = keccak(b"getAttestation(bytes32)")[:4]
+_ATT = "(bytes32,bytes32,uint64,uint64,uint64,bytes32,address,address,bool,bytes)"
+_DATA = ["bytes32", "uint64", "bytes32", "uint64", "bytes32", "string"]
+
+
+def _rpc(url: str, method: str, *params):
+    req = urllib.request.Request(
+        url,
+        json.dumps({"jsonrpc": "2.0", "id": 1, "method": method, "params": list(params)}).encode(),
+        {"content-type": "application/json", "user-agent": "qed-proof-py/0.1"},
+    )
+    with urllib.request.urlopen(req, timeout=20) as r:  # noqa: S310 - RPC URL is caller-supplied by design
+        body = json.loads(r.read())
+    if "error" in body:
+        raise RuntimeError(f"{method}: {body['error'].get('message')}")
+    return body["result"]
+
+
+def check_anchor(proof: dict, keyset: dict, rpc_url: str, b64u_decode) -> dict:
+    """Return {"ok": bool, "reason": str, "proven_by": unix seconds | None}. Any doubt -> ok False, never a pass."""
+    a = proof["anchor"]
+    try:
+        if a.get("scheme") != "eas":
+            return {"ok": False, "reason": "unknown_scheme", "proven_by": None}
+        if int(_rpc(rpc_url, "eth_chainId"), 16) != int(str(a["chain"]).split(":")[1]):
+            return {"ok": False, "reason": "rpc_chain_mismatch", "proven_by": None}
+        uid = bytes.fromhex(a["uid"][2:])
+        out = _rpc(rpc_url, "eth_call", {"to": EAS, "data": "0x" + (_GET + uid).hex()}, "latest")
+        (att,) = abi_decode([_ATT], bytes.fromhex(out[2:]))
+        uid_, schema, time_, _exp, revoked_at, _ref, _recipient, attester, _revocable, data = att
+    except Exception as exc:  # network, decode or shape errors: the anchor is unproven, not proven
+        return {"ok": False, "reason": f"unreadable:{type(exc).__name__}", "proven_by": None}
+    if uid_ != uid or time_ == 0:
+        return {"ok": False, "reason": "attestation_not_found", "proven_by": None}
+    if revoked_at:
+        return {"ok": False, "reason": "attestation_revoked", "proven_by": None}
+    if attester.lower() not in {x.lower() for x in keyset.get("anchor_addresses", [])}:
+        return {"ok": False, "reason": "attester_not_published", "proven_by": None}
+    if "0x" + schema.hex() not in {x.lower() for x in keyset.get("anchor_schemas", [])}:
+        return {"ok": False, "reason": "schema_not_published", "proven_by": None}
+    try:
+        log_id, size, root, _prev_size, _prev_root, _spec = abi_decode(_DATA, data)
+    except Exception:
+        return {"ok": False, "reason": "data_undecodable", "proven_by": None}
+    if log_id != b64u_decode(proof["log_id"]) or size != a["tree_size"]:
+        return {"ok": False, "reason": "log_or_size_mismatch", "proven_by": None}
+    if a["tree_size"] != proof["tree_size"]:
+        return {"ok": False, "reason": "consistency_proof_required", "proven_by": None}  # this issuer proves at the anchored size
+    if root != b64u_decode(proof["root_hash"]):
+        return {"ok": False, "reason": "root_mismatch", "proven_by": None}
+    return {"ok": True, "reason": "anchored", "proven_by": time_}  # EAS sets time = block.timestamp

qed_proof/_primitives.py

@@ -0,0 +1,97 @@
+"""Ported, not imported: the poaw/0.1 receipt primitives (SPEC.md sections 3, 5 and 8).
+
+This is a line-for-line port of ``oss/core-python/src/poaw_core/__init__.py`` from the QED Proof
+monorepo, trimmed to what a *verifier* needs (no tree-building or consistency-proof helpers, since
+the SDK only checks receipts it is handed). Keep this in sync with the reference by hand: the
+conformance suite in ``tests/test_conformance.py`` is what actually proves it matches.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+from typing import Any
+
+import rfc8785
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+SPEC_VERSION = "poaw/0.1"
+SIG_DOMAIN = b"POAW-RECEIPT-V0\n"
+
+
+# --- encoding (SPEC §3) ------------------------------------------------------------------------
+def b64u(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def b64u_decode(text: str) -> bytes:
+    return base64.urlsafe_b64decode(text + "=" * (-len(text) % 4))
+
+
+def jcs(obj: Any) -> bytes:
+    return rfc8785.dumps(obj)
+
+
+def sha256(data: bytes) -> bytes:
+    return hashlib.sha256(data).digest()
+
+
+def has_float(obj: Any) -> bool:
+    """SPEC §3: receipts carry integers only."""
+    if isinstance(obj, bool):
+        return False
+    if isinstance(obj, float):
+        return True
+    if isinstance(obj, dict):
+        return any(has_float(v) for v in obj.values())
+    if isinstance(obj, list):
+        return any(has_float(v) for v in obj)
+    return False
+
+
+# --- keys + signatures (SPEC §5) ---------------------------------------------------------------
+def key_id(pk_raw: bytes) -> str:
+    return "ed25519:" + b64u(sha256(pk_raw))
+
+
+def verify_signature(pk_raw: bytes, body: dict, sig_value: str) -> bool:
+    try:
+        Ed25519PublicKey.from_public_bytes(pk_raw).verify(b64u_decode(sig_value), SIG_DOMAIN + jcs(body))
+        return True
+    except (InvalidSignature, ValueError):
+        return False
+
+
+def claim_digest(claim: dict) -> str:
+    stripped = {k: v for k, v in claim.items() if k != "claim_digest"}
+    return b64u(sha256(jcs(stripped)))
+
+
+# --- Merkle log, RFC 6962 (SPEC §8) -------------------------------------------------------------
+def leaf_hash(receipt: dict) -> bytes:
+    return sha256(b"\x00" + jcs({"body": receipt["body"], "signature": receipt["signature"]}))
+
+
+def _node(left: bytes, right: bytes) -> bytes:
+    return sha256(b"\x01" + left + right)
+
+
+def root_from_inclusion(index: int, size: int, leaf: bytes, path: list[bytes]) -> bytes | None:
+    """RFC 9162 §2.1.3.2 audit-path verification. Returns the computed root, or None if the path is malformed."""
+    if index >= size:
+        return None
+    fn, sn, r = index, size - 1, leaf
+    for p in path:
+        if sn == 0:
+            return None
+        if fn & 1 or fn == sn:
+            r = _node(p, r)
+            if not fn & 1:
+                while fn and not fn & 1:
+                    fn >>= 1
+                    sn >>= 1
+        else:
+            r = _node(r, p)
+        fn >>= 1
+        sn >>= 1
+    return r if sn == 0 else None

qed_proof/actions.py

@@ -0,0 +1,99 @@
+"""Typed helpers that build an :class:`Action` for the five live verifier profiles plus
+``http.url.status``. Param names, types and target formats follow ``oss/spec/profiles/*.md`` and the
+node's verifier ``Params`` models (``oss/node/src/poaw_node/verifiers/{github,x,slack,http}.py``).
+
+Each helper validates cheaply-checkable shape locally (regexes for a commit SHA, a fingerprint hex
+digest, a Slack target, ...) and raises ``ValueError`` with a clear message on a bad value. It cannot
+catch everything the node will reject (e.g. an unreadable repo) — that still comes back as a 422 from
+``submit_claim``.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+_REPO = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$")
+_SHA40 = re.compile(r"^[0-9a-f]{40}$")
+_HEX64 = re.compile(r"^[0-9a-f]{64}$")
+_HANDLE = re.compile(r"^@[A-Za-z0-9_]{1,15}$")
+_SLACK_TARGET = re.compile(r"^slack://(T[A-Z0-9]{2,20})/([CG][A-Z0-9]{2,20})$")
+_SLACK_TS = re.compile(r"^[0-9]{10}\.[0-9]{6}$")
+
+
+@dataclass(frozen=True)
+class Action:
+    """An action + target + params ready to hand to ``QedProof.submit_claim``."""
+
+    action: str
+    target: str
+    params: dict[str, Any]
+
+
+def _require(cond: bool, msg: str) -> None:
+    if not cond:
+        raise ValueError(msg)
+
+
+def github_commit_push(target: str, sha: str, branch: str) -> Action:
+    """`github.commit.push` v1: `branch` contains `sha` on the remote."""
+    _require(bool(_REPO.match(target)), "target must look like 'owner/repo'")
+    _require(bool(_SHA40.match(sha)), "sha must be 40 lowercase hex characters")
+    _require(isinstance(branch, str) and bool(branch), "branch must be a non-empty string")
+    return Action("github.commit.push", target, {"sha": sha, "branch": branch})
+
+
+def github_pr_open(target: str, number: int, base: str | None = None, head_sha: str | None = None) -> Action:
+    """`github.pr.open` v1: the PR exists (and, if given, matches `base` / `head_sha`)."""
+    _require(bool(_REPO.match(target)), "target must look like 'owner/repo'")
+    _require(isinstance(number, int) and number > 0, "number must be a positive integer")
+    if head_sha is not None:
+        _require(bool(_SHA40.match(head_sha)), "head_sha must be 40 lowercase hex characters")
+    params: dict[str, Any] = {"number": number}
+    if base is not None:
+        params["base"] = base
+    if head_sha is not None:
+        params["head_sha"] = head_sha
+    return Action("github.pr.open", target, params)
+
+
+def github_checks_pass(target: str, sha: str) -> Action:
+    """`github.checks.pass` v1: every check run for `sha` concluded successfully."""
+    _require(bool(_REPO.match(target)), "target must look like 'owner/repo'")
+    _require(bool(_SHA40.match(sha)), "sha must be 40 lowercase hex characters")
+    return Action("github.checks.pass", target, {"sha": sha})
+
+
+def x_post_publish(target: str, post_id: str, text_sha256: str | None = None) -> Action:
+    """`x.post.publish` v1: the post exists, written by the account `target` (an `@handle`) is bound to."""
+    _require(bool(_HANDLE.match(target)), "target must be an '@handle' (1-15 of A-Za-z0-9_)")
+    _require(isinstance(post_id, str) and post_id.isdigit() and 1 <= len(post_id) <= 20,
+              "post_id must be a string of 1-20 digits")
+    if text_sha256 is not None:
+        _require(bool(_HEX64.match(text_sha256)), "text_sha256 must be 64 lowercase hex characters")
+    params: dict[str, Any] = {"post_id": post_id}
+    if text_sha256 is not None:
+        params["text_sha256"] = text_sha256
+    return Action("x.post.publish", target, params)
+
+
+def slack_message_post(target: str, ts: str, text_sha256: str | None = None) -> Action:
+    """`slack.message.post` v1: the message exists at `slack://<team>/<channel>` timestamp `ts`."""
+    _require(bool(_SLACK_TARGET.match(target)), "target must look like 'slack://<team_id>/<channel_id>'")
+    _require(bool(_SLACK_TS.match(ts)), "ts must look like '1234567890.123456'")
+    if text_sha256 is not None:
+        _require(bool(_HEX64.match(text_sha256)), "text_sha256 must be 64 lowercase hex characters")
+    params: dict[str, Any] = {"ts": ts}
+    if text_sha256 is not None:
+        params["text_sha256"] = text_sha256
+    return Action("slack.message.post", target, params)
+
+
+def http_url_status(target: str, status: int = 200, content_fingerprint: str | None = None) -> Action:
+    """`http.url.status` v1: an HTTPS URL returns `status` (and, if given, a matching content fingerprint)."""
+    _require(isinstance(target, str) and target.startswith("https://"), "target must be an https:// URL")
+    _require(isinstance(status, int) and 100 <= status <= 599, "status must be a valid HTTP status code")
+    params: dict[str, Any] = {"status": status}
+    if content_fingerprint is not None:
+        params["content_fingerprint"] = content_fingerprint
+    return Action("http.url.status", target, params)

qed_proof/client.py

@@ -0,0 +1,350 @@
+"""HTTP client for QED Proof: submit claims, poll for a verdict, fetch a receipt and the public keys.
+
+Endpoint shapes follow ``oss/node/src/poaw_node/app.py`` (``ClaimIn`` in ``models.py``, and
+``Store.claim_status`` / ``Store.receipt_with_proof`` in ``store.py``).
+"""
+from __future__ import annotations
+
+import os
+import time
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+import httpx
+
+from .actions import Action
+from .verify import VerifyReport, verify_receipt
+
+__all__ = [
+    "QedProof", "AsyncQedProof", "ClaimResult", "ClaimPage",
+    "QedProofError", "QedProofRateLimited", "QedProofTimeout",
+]
+
+DEFAULT_BASE_URL = "https://api.qedproof.site"
+DEFAULT_TIMEOUT = 30
+_ENV_KEY = "QED_PROOF_API_KEY"
+LIST_CLAIMS_DEFAULT_LIMIT = 50
+LIST_CLAIMS_MIN_LIMIT = 1
+LIST_CLAIMS_MAX_LIMIT = 200
+
+
+class QedProofError(Exception):
+    """An error response from the QED Proof API (a FastAPI ``{"detail": ...}`` body).
+
+    The API key is never included in this exception's message, repr or args — only the status code
+    and the server's own detail text.
+    """
+
+    def __init__(self, status_code: int, detail: Any):
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"QED Proof API error {status_code}: {detail!r}")
+
+
+class QedProofRateLimited(QedProofError):
+    """A 429 response. ``retry_after`` is the ``Retry-After`` header in whole seconds, if present."""
+
+    def __init__(self, status_code: int, detail: Any, retry_after: int | None):
+        self.retry_after = retry_after
+        super().__init__(status_code, detail)
+
+
+class QedProofTimeout(Exception):
+    """``wait_for_verdict`` did not observe a decided claim within ``timeout`` seconds."""
+
+    def __init__(self, claim_id: str, timeout: float):
+        self.claim_id = claim_id
+        self.timeout = timeout
+        super().__init__(f"claim {claim_id} was not decided within {timeout}s")
+
+
+@dataclass(frozen=True)
+class ClaimResult:
+    """A claim as the API reports it (``Store.claim_status`` / the ``POST /v1/claims`` response)."""
+
+    claim_id: str
+    state: str  # "queued" | "decided"
+    attempts: int
+    receipt_id: str | None
+    verdict: str | None
+    created: bool | None = None  # only set on the response to submit_claim
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def decided(self) -> bool:
+        return self.state == "decided"
+
+    @classmethod
+    def _from_dict(cls, d: dict[str, Any]) -> "ClaimResult":
+        return cls(
+            claim_id=d["claim_id"], state=d["state"], attempts=d.get("attempts", 0),
+            receipt_id=d.get("receipt_id"), verdict=d.get("verdict"), created=d.get("created"), raw=d,
+        )
+
+
+@dataclass(frozen=True)
+class ClaimPage:
+    """One page of ``GET /v1/claims`` (newest first, keyset-paginated)."""
+
+    claims: list[ClaimResult]
+    next_cursor: str | None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+def _list_claims_params(*, limit: int, cursor: str | None, agent_id: str | None, action: str | None,
+                        verdict: str | None, state: str | None) -> dict[str, Any]:
+    if not (LIST_CLAIMS_MIN_LIMIT <= limit <= LIST_CLAIMS_MAX_LIMIT):
+        raise ValueError(f"limit must be between {LIST_CLAIMS_MIN_LIMIT} and {LIST_CLAIMS_MAX_LIMIT}, got {limit}")
+    params: dict[str, Any] = {"limit": limit}
+    if cursor is not None:
+        params["cursor"] = cursor
+    if agent_id is not None:
+        params["agent_id"] = agent_id
+    if action is not None:
+        params["action"] = action
+    if verdict is not None:
+        params["verdict"] = verdict
+    if state is not None:
+        params["state"] = state
+    return params
+
+
+def _claim_page_from_dict(d: dict[str, Any]) -> ClaimPage:
+    return ClaimPage(claims=[ClaimResult._from_dict(c) for c in d.get("claims", [])],
+                     next_cursor=d.get("next_cursor"), raw=d)
+
+
+def _now_iso() -> str:
+    now = datetime.now(timezone.utc)
+    return now.strftime("%Y-%m-%dT%H:%M:%S.") + f"{now.microsecond // 1000:03d}Z"
+
+
+def _claim_body(action: Action | str, *, target: str | None, params: dict[str, Any] | None,
+                agent_id: str, client_claim_id: str | None, claimed_at: str | None) -> dict[str, Any]:
+    if isinstance(action, Action):
+        action_name, resolved_target, resolved_params = action.action, action.target, dict(action.params)
+    else:
+        action_name, resolved_target, resolved_params = action, target, dict(params or {})
+    if resolved_target is None:
+        raise ValueError("target is required when action is a plain string")
+    return {
+        "client_claim_id": client_claim_id or str(uuid.uuid4()),
+        "agent_id": agent_id,
+        "action": action_name,
+        "target": resolved_target,
+        "params": resolved_params,
+        "claimed_at": claimed_at or _now_iso(),
+    }
+
+
+def _raise_for_status(resp: httpx.Response) -> None:
+    if resp.status_code < 400:
+        return
+    try:
+        detail = resp.json().get("detail", resp.text)
+    except ValueError:
+        detail = resp.text
+    if resp.status_code == 429:
+        retry_after = resp.headers.get("Retry-After")
+        raise QedProofRateLimited(429, detail, int(retry_after) if retry_after and retry_after.isdigit() else None)
+    raise QedProofError(resp.status_code, detail)
+
+
+class QedProof:
+    """Synchronous client. ``api_key`` falls back to the ``QED_PROOF_API_KEY`` environment variable."""
+
+    def __init__(self, api_key: str | None = None, base_url: str = DEFAULT_BASE_URL, timeout: float = DEFAULT_TIMEOUT,
+                http_client: httpx.Client | None = None):
+        self._api_key = api_key or os.environ.get(_ENV_KEY)
+        self._base_url = base_url.rstrip("/")
+        self._client = http_client or httpx.Client(timeout=timeout)
+        self._owns_client = http_client is None
+
+    def __repr__(self) -> str:  # never leak the key
+        return f"QedProof(base_url={self._base_url!r})"
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "QedProof":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _auth_headers(self) -> dict[str, str]:
+        if not self._api_key:
+            raise QedProofError(401, "no API key set (pass api_key= or set QED_PROOF_API_KEY)")
+        return {"Authorization": f"Bearer {self._api_key}"}
+
+    def submit_claim(self, action: Action | str, *, target: str | None = None, params: dict[str, Any] | None = None,
+                     agent_id: str, client_claim_id: str | None = None, claimed_at: str | None = None) -> ClaimResult:
+        body = _claim_body(action, target=target, params=params, agent_id=agent_id,
+                           client_claim_id=client_claim_id, claimed_at=claimed_at)
+        resp = self._client.post(f"{self._base_url}/v1/claims", json=body, headers=self._auth_headers())
+        _raise_for_status(resp)
+        return ClaimResult._from_dict(resp.json())
+
+    def get_claim(self, claim_id: str) -> ClaimResult:
+        resp = self._client.get(f"{self._base_url}/v1/claims/{claim_id}", headers=self._auth_headers())
+        _raise_for_status(resp)
+        return ClaimResult._from_dict(resp.json())
+
+    def wait_for_verdict(self, claim_id: str, timeout: float = 120, poll_interval: float = 2) -> ClaimResult:
+        deadline = time.monotonic() + timeout
+        interval = poll_interval
+        while True:
+            try:
+                claim = self.get_claim(claim_id)
+            except QedProofRateLimited as exc:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise QedProofTimeout(claim_id, timeout) from exc
+                time.sleep(min(exc.retry_after or interval, remaining))
+                continue
+            if claim.decided:
+                return claim
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise QedProofTimeout(claim_id, timeout)
+            time.sleep(min(interval, remaining))
+            interval = min(interval * 2, 30)
+
+    def list_claims(self, *, limit: int = LIST_CLAIMS_DEFAULT_LIMIT, cursor: str | None = None,
+                    agent_id: str | None = None, action: str | None = None, verdict: str | None = None,
+                    state: str | None = None) -> ClaimPage:
+        """``GET /v1/claims``, newest first. Raises :class:`ValueError` locally if ``limit`` is out of range."""
+        params = _list_claims_params(limit=limit, cursor=cursor, agent_id=agent_id, action=action,
+                                     verdict=verdict, state=state)
+        resp = self._client.get(f"{self._base_url}/v1/claims", params=params, headers=self._auth_headers())
+        _raise_for_status(resp)
+        return _claim_page_from_dict(resp.json())
+
+    def iter_claims(self, *, page_size: int = LIST_CLAIMS_DEFAULT_LIMIT, agent_id: str | None = None,
+                    action: str | None = None, verdict: str | None = None, state: str | None = None):
+        """Yield every :class:`ClaimResult` matching the filters, following ``next_cursor`` until exhausted."""
+        cursor: str | None = None
+        while True:
+            page = self.list_claims(limit=page_size, cursor=cursor, agent_id=agent_id, action=action,
+                                    verdict=verdict, state=state)
+            yield from page.claims
+            if page.next_cursor is None:
+                return
+            cursor = page.next_cursor
+
+    def get_receipt(self, receipt_id: str) -> dict[str, Any]:
+        resp = self._client.get(f"{self._base_url}/v1/receipts/{receipt_id}")  # no auth: receipts are public
+        _raise_for_status(resp)
+        return resp.json()
+
+    def get_keys(self) -> dict[str, Any]:
+        resp = self._client.get(f"{self._base_url}/.well-known/poaw-keys.json")
+        _raise_for_status(resp)
+        return resp.json()
+
+    def verify(self, receipt: dict[str, Any], rpc_url: str | None = None) -> VerifyReport:
+        keys = self.get_keys()
+        return verify_receipt(receipt, keys, rpc_url=rpc_url)
+
+
+class AsyncQedProof:
+    """Asynchronous client with the same surface as :class:`QedProof`, over ``httpx.AsyncClient``."""
+
+    def __init__(self, api_key: str | None = None, base_url: str = DEFAULT_BASE_URL, timeout: float = DEFAULT_TIMEOUT,
+                http_client: httpx.AsyncClient | None = None):
+        self._api_key = api_key or os.environ.get(_ENV_KEY)
+        self._base_url = base_url.rstrip("/")
+        self._client = http_client or httpx.AsyncClient(timeout=timeout)
+        self._owns_client = http_client is None
+
+    def __repr__(self) -> str:
+        return f"AsyncQedProof(base_url={self._base_url!r})"
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncQedProof":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    def _auth_headers(self) -> dict[str, str]:
+        if not self._api_key:
+            raise QedProofError(401, "no API key set (pass api_key= or set QED_PROOF_API_KEY)")
+        return {"Authorization": f"Bearer {self._api_key}"}
+
+    async def submit_claim(self, action: Action | str, *, target: str | None = None, params: dict[str, Any] | None = None,
+                          agent_id: str, client_claim_id: str | None = None, claimed_at: str | None = None) -> ClaimResult:
+        body = _claim_body(action, target=target, params=params, agent_id=agent_id,
+                           client_claim_id=client_claim_id, claimed_at=claimed_at)
+        resp = await self._client.post(f"{self._base_url}/v1/claims", json=body, headers=self._auth_headers())
+        _raise_for_status(resp)
+        return ClaimResult._from_dict(resp.json())
+
+    async def get_claim(self, claim_id: str) -> ClaimResult:
+        resp = await self._client.get(f"{self._base_url}/v1/claims/{claim_id}", headers=self._auth_headers())
+        _raise_for_status(resp)
+        return ClaimResult._from_dict(resp.json())
+
+    async def wait_for_verdict(self, claim_id: str, timeout: float = 120, poll_interval: float = 2) -> ClaimResult:
+        import asyncio
+        deadline = time.monotonic() + timeout
+        interval = poll_interval
+        while True:
+            try:
+                claim = await self.get_claim(claim_id)
+            except QedProofRateLimited as exc:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise QedProofTimeout(claim_id, timeout) from exc
+                await asyncio.sleep(min(exc.retry_after or interval, remaining))
+                continue
+            if claim.decided:
+                return claim
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise QedProofTimeout(claim_id, timeout)
+            await asyncio.sleep(min(interval, remaining))
+            interval = min(interval * 2, 30)
+
+    async def list_claims(self, *, limit: int = LIST_CLAIMS_DEFAULT_LIMIT, cursor: str | None = None,
+                          agent_id: str | None = None, action: str | None = None, verdict: str | None = None,
+                          state: str | None = None) -> ClaimPage:
+        """``GET /v1/claims``, newest first. Raises :class:`ValueError` locally if ``limit`` is out of range."""
+        params = _list_claims_params(limit=limit, cursor=cursor, agent_id=agent_id, action=action,
+                                     verdict=verdict, state=state)
+        resp = await self._client.get(f"{self._base_url}/v1/claims", params=params, headers=self._auth_headers())
+        _raise_for_status(resp)
+        return _claim_page_from_dict(resp.json())
+
+    async def iter_claims(self, *, page_size: int = LIST_CLAIMS_DEFAULT_LIMIT, agent_id: str | None = None,
+                          action: str | None = None, verdict: str | None = None, state: str | None = None):
+        """Async-yield every :class:`ClaimResult` matching the filters, following ``next_cursor`` until exhausted."""
+        cursor: str | None = None
+        while True:
+            page = await self.list_claims(limit=page_size, cursor=cursor, agent_id=agent_id, action=action,
+                                          verdict=verdict, state=state)
+            for c in page.claims:
+                yield c
+            if page.next_cursor is None:
+                return
+            cursor = page.next_cursor
+
+    async def get_receipt(self, receipt_id: str) -> dict[str, Any]:
+        resp = await self._client.get(f"{self._base_url}/v1/receipts/{receipt_id}")
+        _raise_for_status(resp)
+        return resp.json()
+
+    async def get_keys(self) -> dict[str, Any]:
+        resp = await self._client.get(f"{self._base_url}/.well-known/poaw-keys.json")
+        _raise_for_status(resp)
+        return resp.json()
+
+    async def verify(self, receipt: dict[str, Any], rpc_url: str | None = None) -> VerifyReport:
+        keys = await self.get_keys()
+        return verify_receipt(receipt, keys, rpc_url=rpc_url)