a2a-protocol-core 0.2.1__tar.gz → 0.3.0__tar.gz

{a2a_protocol_core-0.2.1 → a2a_protocol_core-0.3.0}/CHANGELOG.md

@@ -3,6 +3,44 @@
 All notable changes to `a2a-protocol-core` are documented here. This project
 adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.3.0] — 2026-07-20
+
+The version where the SDK can buy and verify the product end to end: pay DNS of
+Money's own USDC-priced endpoints, screen a counterparty before paying it, and
+cryptographically verify the attestation you paid for.
+
+### Added
+- `pay_alias_usdc_algorand(...)` — pay a `pay:` alias in USDC on Algorand from
+  the caller's own wallet. Signs the USDC transfer leg locally via the OFFICIAL
+  x402 client mechanisms (new `[algorand]` extra → `x402-avm[avm]`); the
+  facilitator co-signs the fee leg and submits. Omit the amount to pay the
+  alias's declared (enforced) price.
+- `pay_alias(...)` — rail-dispatching front door: `currency="XRP"` → XRPL,
+  `"USDC"` → Algorand. Deterministic table lookup, no scoring.
+- `screen(...)` / `screen_with_payment_header(...)` / `ScreenResult` — client
+  for the paid counterparty screen (`GET /x402/screen/{target}`): pay the
+  server-priced fee, receive the OFAC + resolution attestation about a
+  caller-named `pay:` alias or raw address. "Screen before you pay," one call.
+- `verify_attestation(...)` — client-side verification of the signed
+  attestation's `eddsa-jcs-2022` Data Integrity proof: resolves the issuer's
+  `did:web` document, enforces `assertionMethod` authorization, verifies the
+  Ed25519 signature (new `[verify]` extra → `cryptography`). JCS
+  canonicalization, base58btc, and did:web resolution are pure Python; an
+  unsigned attestation FAILS verification by design.
+- `fetch_requirement_header(...)` — raw `PAYMENT-REQUIRED` header fetch (any
+  currency, amount optional) for callers driving official x402 clients.
+- Bounded retry with exponential backoff on every idempotent HTTP leg
+  (challenge fetch, settle, capabilities, DID-document fetch): connection
+  errors and 502/503/504 only, fixed attempt count, no jitter. Settle legs are
+  retry-safe because the server checks idempotency before verification. The
+  payment-hook POST is never auto-retried — re-send with the same
+  `job_id` + `semantic_hash` (the server's idempotency key) instead.
+
+### Changed
+- `A2APaymentHookClient` now raises `A2AClientError` (with `status_code` and a
+  `body` snippet) instead of a bare `requests.HTTPError`, so agents can branch
+  on the failure. `capabilities()` retries transient failures.
+
 ## [0.2.1] — 2026-07-20
 
 Conformance fix for the XRPL exact scheme's field placement. Required before

{a2a_protocol_core-0.2.1 → a2a_protocol_core-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: a2a-protocol-core
-Version: 0.2.1
+Version: 0.3.0
 Summary: Open, deterministic protocol core for the DNS of Money A2A payment surface (FAS-1 pay: addressing, canonical hashing, payment-hook client).
 Project-URL: Homepage, https://dnsofmoney.com
 Project-URL: Specification, https://github.com/dnsofmoney/dns-of-money
@@ -17,9 +17,14 @@ Classifier: Topic :: Office/Business :: Financial
 Requires-Python: >=3.10
 Requires-Dist: pydantic>=2.10.0
 Requires-Dist: requests>=2.31.0
+Provides-Extra: algorand
+Requires-Dist: x402-avm[avm]>=2.0.2; extra == 'algorand'
 Provides-Extra: dev
+Requires-Dist: cryptography>=42.0.0; extra == 'dev'
 Requires-Dist: pytest>=8.3.0; extra == 'dev'
 Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Provides-Extra: verify
+Requires-Dist: cryptography>=42.0.0; extra == 'verify'
 Provides-Extra: xrpl
 Requires-Dist: xrpl-py>=2.5.0; extra == 'xrpl'
 Description-Content-Type: text/markdown
@@ -53,6 +58,9 @@ Runtime deps are intentionally minimal: `pydantic` and `requests`.
 | `canonical_hash` | A2A-008 | metadata- & vocabulary-stable payment-intent hash |
 | `schemas` | A2A-041 | payment-hook request/response wire models |
 | `client` | A2A-041 | `A2APaymentHookClient` over `/v1/a2a/*` |
+| `x402_pay` | x402 | one-call pay: XRP on XRPL (`[xrpl]`) / USDC on Algorand (`[algorand]`) |
+| `screen` | x402 | paid counterparty screen — "screen before you pay" |
+| `attestation_verify` | did:web | verify the attestation's Ed25519 proof (`[verify]`) |
 
 ## Quick start
 
@@ -124,6 +132,69 @@ result = attest_settled_payment(
 DNS of Money **verifies an already-settled transaction and returns metadata** — it
 never holds your keys or your funds.
 
+## Pay in USDC on Algorand (the priced endpoints)
+
+DNS of Money's own paid endpoints declare their price in USDC on Algorand.
+`pay_alias_usdc_algorand` (or the rail-dispatching `pay_alias`) signs the USDC
+transfer leg locally via the **official x402 client mechanisms** — omit the
+amount and the server quotes its declared, enforced price:
+
+```bash
+pip install "a2a-protocol-core[algorand]"
+```
+
+```python
+from a2a_protocol_core import pay_alias_usdc_algorand
+
+result = pay_alias_usdc_algorand(
+    base_url="https://api.dnsofmoney.com",
+    alias="pay:dnsofmoney",
+    api_key="fas_live_...",
+    mnemonic="...your 25-word Algorand mnemonic...",  # signs locally, never sent
+)
+print(result.tx_hash, result.summary.verdict)
+```
+
+## Screen before you pay
+
+Pay the screening fee, get an OFAC + resolution attestation about a
+**caller-named** target — a `pay:` alias or a raw any-chain address — before you
+send it money:
+
+```python
+from a2a_protocol_core import screen
+
+result = screen(
+    base_url="https://api.dnsofmoney.com",
+    target="pay:vendor.alpha",
+    api_key="fas_live_...",
+    algorand_mnemonic="...",   # fee is USDC on Algorand (server-priced)
+    verify=True,               # also check the attestation signature
+)
+if result.verdict == "CLEAR":
+    ...  # proceed to pay the vendor
+```
+
+## Verify the attestation yourself
+
+Attestations are W3C Verifiable Credentials signed `eddsa-jcs-2022` by a
+`did:web` issuer. `verify_attestation` resolves the issuer's DID document,
+enforces `assertionMethod` authorization, and checks the Ed25519 signature —
+so the proof chain ends at *your* process, not at TLS:
+
+```bash
+pip install "a2a-protocol-core[verify]"
+```
+
+```python
+from a2a_protocol_core import verify_attestation
+
+v = verify_attestation(result.attestation, expected_issuer="did:web:dnsofmoney.com")
+assert v.verified
+```
+
+An unsigned attestation **fails** verification by design.
+
 ## Why canonical hashing?
 
 Two agents describing the same payment with different words ("send" vs

{a2a_protocol_core-0.2.1 → a2a_protocol_core-0.3.0}/README.md

@@ -27,6 +27,9 @@ Runtime deps are intentionally minimal: `pydantic` and `requests`.
 | `canonical_hash` | A2A-008 | metadata- & vocabulary-stable payment-intent hash |
 | `schemas` | A2A-041 | payment-hook request/response wire models |
 | `client` | A2A-041 | `A2APaymentHookClient` over `/v1/a2a/*` |
+| `x402_pay` | x402 | one-call pay: XRP on XRPL (`[xrpl]`) / USDC on Algorand (`[algorand]`) |
+| `screen` | x402 | paid counterparty screen — "screen before you pay" |
+| `attestation_verify` | did:web | verify the attestation's Ed25519 proof (`[verify]`) |
 
 ## Quick start
 
@@ -98,6 +101,69 @@ result = attest_settled_payment(
 DNS of Money **verifies an already-settled transaction and returns metadata** — it
 never holds your keys or your funds.
 
+## Pay in USDC on Algorand (the priced endpoints)
+
+DNS of Money's own paid endpoints declare their price in USDC on Algorand.
+`pay_alias_usdc_algorand` (or the rail-dispatching `pay_alias`) signs the USDC
+transfer leg locally via the **official x402 client mechanisms** — omit the
+amount and the server quotes its declared, enforced price:
+
+```bash
+pip install "a2a-protocol-core[algorand]"
+```
+
+```python
+from a2a_protocol_core import pay_alias_usdc_algorand
+
+result = pay_alias_usdc_algorand(
+    base_url="https://api.dnsofmoney.com",
+    alias="pay:dnsofmoney",
+    api_key="fas_live_...",
+    mnemonic="...your 25-word Algorand mnemonic...",  # signs locally, never sent
+)
+print(result.tx_hash, result.summary.verdict)
+```
+
+## Screen before you pay
+
+Pay the screening fee, get an OFAC + resolution attestation about a
+**caller-named** target — a `pay:` alias or a raw any-chain address — before you
+send it money:
+
+```python
+from a2a_protocol_core import screen
+
+result = screen(
+    base_url="https://api.dnsofmoney.com",
+    target="pay:vendor.alpha",
+    api_key="fas_live_...",
+    algorand_mnemonic="...",   # fee is USDC on Algorand (server-priced)
+    verify=True,               # also check the attestation signature
+)
+if result.verdict == "CLEAR":
+    ...  # proceed to pay the vendor
+```
+
+## Verify the attestation yourself
+
+Attestations are W3C Verifiable Credentials signed `eddsa-jcs-2022` by a
+`did:web` issuer. `verify_attestation` resolves the issuer's DID document,
+enforces `assertionMethod` authorization, and checks the Ed25519 signature —
+so the proof chain ends at *your* process, not at TLS:
+
+```bash
+pip install "a2a-protocol-core[verify]"
+```
+
+```python
+from a2a_protocol_core import verify_attestation
+
+v = verify_attestation(result.attestation, expected_issuer="did:web:dnsofmoney.com")
+assert v.verified
+```
+
+An unsigned attestation **fails** verification by design.
+
 ## Why canonical hashing?
 
 Two agents describing the same payment with different words ("send" vs

a2a_protocol_core-0.3.0/examples/attest_byo_tx.py

@@ -0,0 +1,56 @@
+"""
+Bring-your-own-wallet attestation — no signing extras needed.
+
+For agents that already settled the payment through their own wallet stack
+(their own xrpl-py flow, a Coinbase Agentic Wallet, anything that produced a
+validated XRPL tx hash): skip the SDK's signing path entirely and just buy the
+read-only verify + signed attestation for the tx you already made. Base
+install only — no [xrpl], no [algorand].
+
+    pip install a2a-protocol-core          # + [verify] to check the signature
+
+Env:
+  FAS_API_KEY    tenant API key
+  SETTLED_TX     the already-validated XRPL payment hash
+  PAY_ALIAS      alias that was paid (default pay:vendor.alpha)
+  AMOUNT_XRP     the amount that tx paid (default 0.10)
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from a2a_protocol_core import attest_settled_payment, verify_attestation
+from a2a_protocol_core.attestation_verify import AttestationVerificationError
+
+
+def main() -> int:
+    api_key = os.getenv("FAS_API_KEY", "").strip()
+    tx_hash = os.getenv("SETTLED_TX", "").strip()
+    if not api_key or not tx_hash:
+        print("set FAS_API_KEY and SETTLED_TX")
+        return 2
+
+    result = attest_settled_payment(
+        base_url=os.getenv("FAS_BASE_URL", "https://api.dnsofmoney.com"),
+        alias=os.getenv("PAY_ALIAS", "pay:vendor.alpha"),
+        amount_xrp=os.getenv("AMOUNT_XRP", "0.10"),
+        tx_hash=tx_hash,
+        api_key=api_key,
+    )
+    print(f"settled    : {result.settled} (idempotent={result.idempotent})")
+    print(f"verdict    : {result.summary.verdict}")
+    print(f"signed     : {result.summary.signed}")
+
+    try:
+        v = verify_attestation(result.attestation, expected_issuer="did:web:dnsofmoney.com")
+        print(f"verified   : {v.verified} by {v.issuer}")
+    except AttestationVerificationError as exc:
+        print(f"verify     : FAILED — {exc}")
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

a2a_protocol_core-0.3.0/examples/screen_and_verify.py

@@ -0,0 +1,52 @@
+"""
+Screen a counterparty before paying it — and verify the attestation yourself.
+
+The end-to-end 0.3.0 flow: pay the screening fee in USDC on Algorand from your
+own wallet (server-priced; you never name the amount), receive the OFAC +
+resolution attestation about the TARGET you named, and check the issuer's
+Ed25519 signature against its did:web document locally.
+
+    pip install "a2a-protocol-core[algorand,verify]"
+
+Env:
+  FAS_API_KEY            tenant API key (the settle leg requires X-API-Key)
+  ALGORAND_MNEMONIC      your 25-word payer mnemonic — signs locally, never sent
+  SCREEN_TARGET          pay: alias or raw address to screen (default below)
+  FAS_BASE_URL           default https://api.dnsofmoney.com
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from a2a_protocol_core import screen
+
+
+def main() -> int:
+    api_key = os.getenv("FAS_API_KEY", "").strip()
+    mnemonic = os.getenv("ALGORAND_MNEMONIC", "").strip()
+    if not api_key or not mnemonic:
+        print("set FAS_API_KEY and ALGORAND_MNEMONIC")
+        return 2
+
+    result = screen(
+        base_url=os.getenv("FAS_BASE_URL", "https://api.dnsofmoney.com"),
+        target=os.getenv("SCREEN_TARGET", "pay:vendor.alpha"),
+        api_key=api_key,
+        algorand_mnemonic=mnemonic,
+        verify=True,  # don't just trust TLS — check the issuer's signature
+        expected_issuer="did:web:dnsofmoney.com",
+    )
+
+    print(f"target   : {result.target}")
+    print(f"verdict  : {result.verdict}")
+    print(f"fee txid : {result.proof.get('transaction')}")
+    print(f"signed   : {result.summary.signed}")
+    if result.verification:
+        print(f"verified : {result.verification.verified} by {result.verification.issuer}")
+    return 0 if result.verdict == "CLEAR" else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{a2a_protocol_core-0.2.1 → a2a_protocol_core-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "a2a-protocol-core"
-version = "0.2.1"
+version = "0.3.0"
 description = "Open, deterministic protocol core for the DNS of Money A2A payment surface (FAS-1 pay: addressing, canonical hashing, payment-hook client)."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -36,9 +36,22 @@ Source = "https://github.com/dnsofmoney/a2a-protocol-core"
 xrpl = [
     "xrpl-py>=2.5.0",
 ]
+# USDC-on-Algorand pay path (pay_alias_usdc_algorand / screen fee): drives the
+# OFFICIAL x402 client mechanisms to build the atomic group — never hand-rolled.
+# x402-avm is GoPlausible's distribution of the x402 client WITH the AVM
+# mechanisms registered (it provides the `x402` import namespace).
+algorand = [
+    "x402-avm[avm]>=2.0.2",
+]
+# Attestation signature verification (verify_attestation): Ed25519 only — JCS,
+# base58btc, and did:web resolution are pure Python.
+verify = [
+    "cryptography>=42.0.0",
+]
 dev = [
     "pytest>=8.3.0",
     "ruff>=0.8.0",
+    "cryptography>=42.0.0",
 ]
 
 [tool.hatch.build.targets.wheel]

{a2a_protocol_core-0.2.1 → a2a_protocol_core-0.3.0}/src/a2a_protocol_core/__init__.py

@@ -19,7 +19,7 @@ from a2a_protocol_core.addressing import (
     is_valid_pay_uri,
 )
 from a2a_protocol_core.canonical_hash import compute_canonical_hash
-from a2a_protocol_core.client import A2APaymentHookClient
+from a2a_protocol_core.client import A2AClientError, A2APaymentHookClient
 from a2a_protocol_core.schemas import (
     A2ACapabilities,
     A2APaymentHookRequest,
@@ -34,19 +34,36 @@ from a2a_protocol_core.semantic_normalizer import (
     normalize_action,
     normalize_message,
 )
+from a2a_protocol_core.attestation_verify import (
+    AttestationVerification,
+    AttestationVerificationError,
+    did_web_document_url,
+    fetch_did_document,
+    verify_attestation,
+)
+from a2a_protocol_core.screen import (
+    ScreenResult,
+    fetch_screen_requirement_header,
+    screen,
+    screen_with_payment_header,
+)
 from a2a_protocol_core.x402_pay import (
     AttestationSummary,
     X402PaymentResult,
     X402PayError,
     attest_settled_payment,
+    build_avm_payment_header,
     build_x_payment_header,
     decode_payment_required,
     fetch_requirement,
+    fetch_requirement_header,
+    pay_alias,
+    pay_alias_usdc_algorand,
     pay_alias_xrp,
     summarize_attestation,
 )
 
-__version__ = "0.2.1"
+__version__ = "0.3.0"
 
 __all__ = [
     "__version__",
@@ -70,14 +87,30 @@ __all__ = [
     "A2ACapabilities",
     # client
     "A2APaymentHookClient",
-    # x402 pay-path (one-call; signing needs the [xrpl] extra)
+    "A2AClientError",
+    # x402 pay-path (one-call; XRP signing needs [xrpl], USDC needs [algorand])
+    "pay_alias",
     "pay_alias_xrp",
+    "pay_alias_usdc_algorand",
     "attest_settled_payment",
     "fetch_requirement",
+    "fetch_requirement_header",
     "decode_payment_required",
     "build_x_payment_header",
+    "build_avm_payment_header",
     "summarize_attestation",
     "AttestationSummary",
     "X402PaymentResult",
     "X402PayError",
+    # paid counterparty screen ("screen before you pay")
+    "screen",
+    "screen_with_payment_header",
+    "fetch_screen_requirement_header",
+    "ScreenResult",
+    # attestation verification (signature checking needs the [verify] extra)
+    "verify_attestation",
+    "fetch_did_document",
+    "did_web_document_url",
+    "AttestationVerification",
+    "AttestationVerificationError",
 ]

a2a_protocol_core-0.3.0/src/a2a_protocol_core/_retry.py

@@ -0,0 +1,55 @@
+"""
+Bounded, deterministic retry for idempotent HTTP legs.
+
+Agent runtimes call these endpoints over flaky networks; a transient connection
+reset or a 502 from a proxy should not fail a whole pay/screen flow. Retries
+are DELIBERATELY narrow:
+
+- GET only, and only legs that are idempotent by contract. The x402 settle leg
+  qualifies: the server checks idempotency BEFORE verification, so re-sending
+  the same settled tx proof returns the recorded outcome rather than
+  double-settling.
+- Connection errors / timeouts and 502/503/504 only. A 4xx or a 500 is a real
+  answer and is returned/raised immediately — retrying it would just repeat it.
+- Fixed attempt count, exponential backoff, no jitter — deterministic, like
+  everything else in this package.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Optional
+
+import requests
+
+RETRYABLE_STATUS = frozenset({502, 503, 504})
+DEFAULT_RETRIES = 2  # total attempts = retries + 1
+DEFAULT_BACKOFF = 0.5  # seconds; doubles per attempt
+
+
+def get_with_retries(
+    session: requests.Session,
+    url: str,
+    *,
+    params: Optional[dict] = None,
+    headers: Optional[dict] = None,
+    timeout: int,
+    retries: int = DEFAULT_RETRIES,
+    backoff: float = DEFAULT_BACKOFF,
+) -> requests.Response:
+    """GET with bounded retries on transient failures (see module docstring)."""
+    attempt = 0
+    while True:
+        try:
+            resp = session.get(url, params=params, headers=headers, timeout=timeout)
+        except (requests.ConnectionError, requests.Timeout):
+            if attempt >= retries:
+                raise
+            time.sleep(backoff * (2**attempt))
+            attempt += 1
+            continue
+        if resp.status_code in RETRYABLE_STATUS and attempt < retries:
+            time.sleep(backoff * (2**attempt))
+            attempt += 1
+            continue
+        return resp