aotrust-protocol 2.3.7__tar.gz → 2.5.0__tar.gz

{aotrust_protocol-2.3.7 → aotrust_protocol-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aotrust-protocol
-Version: 2.3.7
+Version: 2.5.0
 Summary: Asyncio-native SDK for A&O Trust Layer — Agent Notary Service
 Author: A&O Trust Layer
 License: MIT
@@ -31,6 +31,9 @@ Dynamic: license-file
 
 Asyncio-native Python SDK for the AOTrust Notary API — cryptographic proof-of-existence for AI agent outputs.
 
+> **Why protocol-level proofs?** An ERC-8004 empirical study (2026) measured that **>98% of agent feedback records carry no proof of an underlying interaction** (no payment proof, no task linkage); 59–91% of reviewers on three chains participated in coordinated Sybil campaigns, and manipulating a reputation score past a trust threshold costs as little as **$0.0027**. The agentic economy is moving from *statements* to *verifiable claims*: a PDR (239 bytes, Ed25519-signed, hash-chained, NEAR-anchored) turns any output or payment into independent evidence — verifiable by anyone, without trusting the provider's database.
+> *(Refs: arXiv:2610.12948 [cs.CR], 2026; ERC-8004 Sybil measurements, Xiong et al. 2026.)*
+
 ## Install
 
 ```bash
@@ -105,6 +108,43 @@ asyncio.run(main())
 > `/v1/v1/...` → HTTP 404 on every call. This bit a real user (2026-09-29:
 > quickstart copy-paste + status lookups by artifact text instead of job_id).
 
+## Paid read products (2.5.0)
+
+The SDK never signs or settles payments itself: a paid call first raises
+`NotaryPaymentError`, whose message carries the server's x402 challenge. Pay
+with any x402-capable client and retry with `X-PAYMENT` (HTTP) or
+`x402/payment` (MCP); the SDK then parses the 200 response.
+
+```python
+from agent_notary import NotaryClient
+from agent_notary.exceptions import NotaryPaymentError, NotaryPendingError
+
+client = NotaryClient()
+
+# Evidence pack — $0.02. Default = earliest issuance; seq selects one.
+pack = await client.bundle(work_hash)                 # dict: picked/issuances/anchor/verify
+pack_at_158 = await client.bundle(work_hash, seq=158)
+
+# Signed time attestation — $0.002.
+attest = await client.time_attest(payload_hash)       # id/ts/sig_b64/leaf/log_index/anchor
+
+# Idempotent lookup by payment tx — free. A 404 is a normal answer.
+found = await client.pdr_by_tx("0x" + "ab" * 32)      # {"found": False} when unknown
+
+# Anchor API — free.
+status = await client.anchor_status()                 # mode/latest/log_size
+proof = await client.anchor_proof(186)                # RFC 9162 §2.1.3 path
+logproof = await client.anchor_logproof(381)          # Phase B, kind 0/1
+cons = await client.anchor_consistency(62, 64)        # RFC 9162 §2.1.4
+
+try:
+    pack = await client.bundle(work_hash)
+except NotaryPaymentError as e:
+    print("Pay via x402, then retry with X-PAYMENT / x402/payment:", e)
+except NotaryPendingError as e:
+    print(f"Anchor not committed yet; retry in {e.eta_seconds}s at {e.recheck_url}")
+```
+
 ## Configuration
 
 | Env Var | Constructor Arg | Description |
@@ -122,6 +162,15 @@ asyncio.run(main())
 | GET | `/v1/pdr/{job_id}` | Get PDR |
 | POST | `/v1/notarize/quote` | Get price quote |
 | GET | `/.well-known/agent.json` | MCP Server Card |
+| POST | `/notarize` | Anonymous x402 paid PDR ($0.01) |
+| POST | `/v1/attestation/bundle` | Evidence pack ($0.02) |
+| POST | `/v1/attest/time` | Signed time attestation ($0.002) |
+| GET | `/v1/pdr/verify/{pdr_b64}` | Verify a PDR |
+| GET | `/v1/pdr/by-tx/{tx}` | PDR by payment tx |
+| GET | `/v1/anchor/status` | Cumulative anchor status |
+| GET | `/v1/anchor/proof/{seq}` | Inclusion proof by ledger seq |
+| GET | `/v1/anchor/logproof/{log_index}` | Inclusion proof by log index (Phase B) |
+| GET | `/v1/anchor/consistency?from=&to=` | Consistency proof |
 | GET | `/openapi.json` | OpenAPI 3.0 spec |
 
 ## PDR Verification
@@ -140,6 +189,7 @@ from agent_notary.exceptions import (
     NotaryAuthError,        # 401 (authenticated CI surfaces; anonymous x402 gives 402 instead)
     NotaryPaymentError,     # 402 x402-challenge / 403
     NotaryNotFoundError,    # 404
+    NotaryPendingError,     # 404 NOT_YET_ANCHORED — retry after eta_seconds
     NotaryValidationError,  # 400/422 — invalid params, INVALID_AGENT_SIGNATURE
     NotaryConflictError,    # 409 — tx_hash/job_id already used (idempotency)
     NotaryServerError,      # 5xx, carries status_code
@@ -166,3 +216,31 @@ except NotaryError as e:
 pip install -e ".[dev]"
 pytest tests/ -v
 ```
+
+## Payment binding (NEAR rail)
+
+NEAR payments must be provably linked to the account that sent them. Pass
+`payer_account` (the NEAR account that paid) together with `bind_sig` — a
+base64 Ed25519 **NEP-413 raw-buffer** signature (no SHA-256 pre-hash) over:
+
+```
+AOTrust AITP-BIND v1
+work_hash:<64 hex>
+tx_hash:<tx hash exactly as submitted>
+```
+
+The server resolves the account's public key via RPC and checks
+`transaction.signer_id == payer_account`; a mismatch is rejected with
+`403 PAYMENT_BIND_SIGNER_MISMATCH`, a bad signature with
+`403 PAYMENT_BIND_INVALID`.
+
+If `NEAR_PRIVATE_KEY` is set in the environment (or `near_private_key=` is
+passed), the SDK signs the canonical message itself and fills `bind_sig`:
+
+```python
+req = NotarizeRequest(tx_hash=tx, work_hash=wh)
+await client.notarize(req, payer_account="alice.near")
+```
+
+Server mode `AITP_BIND_MODE=warn` (default) accepts unbound requests with a
+`PAYMENT_UNBOUND` log line; `enforce` requires the fields.

{aotrust_protocol-2.3.7 → aotrust_protocol-2.5.0}/README.md

@@ -4,6 +4,9 @@
 
 Asyncio-native Python SDK for the AOTrust Notary API — cryptographic proof-of-existence for AI agent outputs.
 
+> **Why protocol-level proofs?** An ERC-8004 empirical study (2026) measured that **>98% of agent feedback records carry no proof of an underlying interaction** (no payment proof, no task linkage); 59–91% of reviewers on three chains participated in coordinated Sybil campaigns, and manipulating a reputation score past a trust threshold costs as little as **$0.0027**. The agentic economy is moving from *statements* to *verifiable claims*: a PDR (239 bytes, Ed25519-signed, hash-chained, NEAR-anchored) turns any output or payment into independent evidence — verifiable by anyone, without trusting the provider's database.
+> *(Refs: arXiv:2610.12948 [cs.CR], 2026; ERC-8004 Sybil measurements, Xiong et al. 2026.)*
+
 ## Install
 
 ```bash
@@ -78,6 +81,43 @@ asyncio.run(main())
 > `/v1/v1/...` → HTTP 404 on every call. This bit a real user (2026-09-29:
 > quickstart copy-paste + status lookups by artifact text instead of job_id).
 
+## Paid read products (2.5.0)
+
+The SDK never signs or settles payments itself: a paid call first raises
+`NotaryPaymentError`, whose message carries the server's x402 challenge. Pay
+with any x402-capable client and retry with `X-PAYMENT` (HTTP) or
+`x402/payment` (MCP); the SDK then parses the 200 response.
+
+```python
+from agent_notary import NotaryClient
+from agent_notary.exceptions import NotaryPaymentError, NotaryPendingError
+
+client = NotaryClient()
+
+# Evidence pack — $0.02. Default = earliest issuance; seq selects one.
+pack = await client.bundle(work_hash)                 # dict: picked/issuances/anchor/verify
+pack_at_158 = await client.bundle(work_hash, seq=158)
+
+# Signed time attestation — $0.002.
+attest = await client.time_attest(payload_hash)       # id/ts/sig_b64/leaf/log_index/anchor
+
+# Idempotent lookup by payment tx — free. A 404 is a normal answer.
+found = await client.pdr_by_tx("0x" + "ab" * 32)      # {"found": False} when unknown
+
+# Anchor API — free.
+status = await client.anchor_status()                 # mode/latest/log_size
+proof = await client.anchor_proof(186)                # RFC 9162 §2.1.3 path
+logproof = await client.anchor_logproof(381)          # Phase B, kind 0/1
+cons = await client.anchor_consistency(62, 64)        # RFC 9162 §2.1.4
+
+try:
+    pack = await client.bundle(work_hash)
+except NotaryPaymentError as e:
+    print("Pay via x402, then retry with X-PAYMENT / x402/payment:", e)
+except NotaryPendingError as e:
+    print(f"Anchor not committed yet; retry in {e.eta_seconds}s at {e.recheck_url}")
+```
+
 ## Configuration
 
 | Env Var | Constructor Arg | Description |
@@ -95,6 +135,15 @@ asyncio.run(main())
 | GET | `/v1/pdr/{job_id}` | Get PDR |
 | POST | `/v1/notarize/quote` | Get price quote |
 | GET | `/.well-known/agent.json` | MCP Server Card |
+| POST | `/notarize` | Anonymous x402 paid PDR ($0.01) |
+| POST | `/v1/attestation/bundle` | Evidence pack ($0.02) |
+| POST | `/v1/attest/time` | Signed time attestation ($0.002) |
+| GET | `/v1/pdr/verify/{pdr_b64}` | Verify a PDR |
+| GET | `/v1/pdr/by-tx/{tx}` | PDR by payment tx |
+| GET | `/v1/anchor/status` | Cumulative anchor status |
+| GET | `/v1/anchor/proof/{seq}` | Inclusion proof by ledger seq |
+| GET | `/v1/anchor/logproof/{log_index}` | Inclusion proof by log index (Phase B) |
+| GET | `/v1/anchor/consistency?from=&to=` | Consistency proof |
 | GET | `/openapi.json` | OpenAPI 3.0 spec |
 
 ## PDR Verification
@@ -113,6 +162,7 @@ from agent_notary.exceptions import (
     NotaryAuthError,        # 401 (authenticated CI surfaces; anonymous x402 gives 402 instead)
     NotaryPaymentError,     # 402 x402-challenge / 403
     NotaryNotFoundError,    # 404
+    NotaryPendingError,     # 404 NOT_YET_ANCHORED — retry after eta_seconds
     NotaryValidationError,  # 400/422 — invalid params, INVALID_AGENT_SIGNATURE
     NotaryConflictError,    # 409 — tx_hash/job_id already used (idempotency)
     NotaryServerError,      # 5xx, carries status_code
@@ -138,4 +188,32 @@ except NotaryError as e:
 ```bash
 pip install -e ".[dev]"
 pytest tests/ -v
-```
+```
+
+## Payment binding (NEAR rail)
+
+NEAR payments must be provably linked to the account that sent them. Pass
+`payer_account` (the NEAR account that paid) together with `bind_sig` — a
+base64 Ed25519 **NEP-413 raw-buffer** signature (no SHA-256 pre-hash) over:
+
+```
+AOTrust AITP-BIND v1
+work_hash:<64 hex>
+tx_hash:<tx hash exactly as submitted>
+```
+
+The server resolves the account's public key via RPC and checks
+`transaction.signer_id == payer_account`; a mismatch is rejected with
+`403 PAYMENT_BIND_SIGNER_MISMATCH`, a bad signature with
+`403 PAYMENT_BIND_INVALID`.
+
+If `NEAR_PRIVATE_KEY` is set in the environment (or `near_private_key=` is
+passed), the SDK signs the canonical message itself and fills `bind_sig`:
+
+```python
+req = NotarizeRequest(tx_hash=tx, work_hash=wh)
+await client.notarize(req, payer_account="alice.near")
+```
+
+Server mode `AITP_BIND_MODE=warn` (default) accepts unbound requests with a
+`PAYMENT_UNBOUND` log line; `enforce` requires the fields.

{aotrust_protocol-2.3.7 → aotrust_protocol-2.5.0}/agent_notary/__init__.py

@@ -1,6 +1,6 @@
 """A&O Trust Layer — Agent Notary SDK (asyncio-native)."""
 
-__version__ = "2.3.7"
+__version__ = "2.5.0"
 
 from .client import NotaryClient
 from .models import NotarizeRequest, NotarizeResult, PdrResult, StatusResult
@@ -9,7 +9,10 @@ from .exceptions import (
     NotaryAuthError,
     NotaryNotFoundError,
     NotaryPaymentError,
+    NotaryPendingError,
     NotaryServerError,
+    NotaryValidationError,
+    NotaryConflictError,
 )
 from .tools import AOTrustTool
 
@@ -23,6 +26,9 @@ __all__ = [
     "NotaryAuthError",
     "NotaryNotFoundError",
     "NotaryPaymentError",
+    "NotaryPendingError",
     "NotaryServerError",
+    "NotaryValidationError",
+    "NotaryConflictError",
     "AOTrustTool",
 ]

{aotrust_protocol-2.3.7 → aotrust_protocol-2.5.0}/agent_notary/client.py

@@ -9,11 +9,46 @@ from typing import Optional
 import aiohttp
 
 from .models import NotarizeRequest, NotarizeResult, StatusResult, PdrResult
+NEP413_TAG = 2147484061
+
+
+def canonical_bind_message(work_hash: str, tx_hash: str) -> bytes:
+    """Canonical AOTrust AITP-BIND v1 message — identical to the server module."""
+    return f"AOTrust AITP-BIND v1\nwork_hash:{work_hash}\ntx_hash:{tx_hash}".encode("utf-8")
+
+
+def _decode_ed25519_key(raw: str) -> bytes:
+    """Accepts hex, base58, or NEAR's 'ed25519:<base58>' key format."""
+    import base58
+    key = raw.strip()
+    if key.startswith("ed25519:"):
+        key = key.split(":", 1)[1]
+    try:
+        if len(key) == 64 and all(c in "0123456789abcdefABCDEF" for c in key):
+            return bytes.fromhex(key)
+    except Exception:
+        pass
+    return base58.b58decode(key)
+
+
+def _sign_bind_message(private_key: str, work_hash: str, tx_hash: str) -> str:
+    """NEP-413 RAW buffer signature (no SHA-256 pre-hash) over the bind message."""
+    import base64
+    import struct
+    from nacl.signing import SigningKey
+
+    msg = canonical_bind_message(work_hash, tx_hash)
+    buf = struct.pack("<II", NEP413_TAG, len(msg)) + msg
+    sk = SigningKey(_decode_ed25519_key(private_key))
+    return base64.b64encode(sk.sign(buf).signature).decode()
+
+
 from .exceptions import (
     NotaryError,
     NotaryAuthError,
     NotaryNotFoundError,
     NotaryPaymentError,
+    NotaryPendingError,
     NotaryServerError,
     NotaryValidationError,
     NotaryConflictError,
@@ -108,6 +143,10 @@ class NotaryClient:
                     await asyncio.sleep(RETRY_DELAYS[attempt])
         raise NotaryServerError(f"Request failed after {MAX_RETRIES} retries: {last_exc}")
 
+    async def _get_json(self, path: str) -> tuple[int, dict]:
+        """GET helper — same retry policy as _request (502/503 backoff)."""
+        return await self._request("GET", path)
+
     def _check_status(self, status: int, body: dict) -> None:
         if status == 401:
             raise NotaryAuthError(body.get("error", "Unauthorized"))
@@ -129,19 +168,42 @@ class NotaryClient:
         if status >= 500:
             raise NotaryServerError(body.get("error", f"Server error {status}"), status_code=status)
 
-    async def notarize(self, request: NotarizeRequest) -> NotarizeResult:
+    async def notarize(
+        self,
+        request: NotarizeRequest,
+        payer_account: Optional[str] = None,
+        bind_sig: Optional[str] = None,
+        near_private_key: Optional[str] = None,
+    ) -> NotarizeResult:
         """POST /notarize — anonymous x402 path.
 
         Without payment the server answers 402 with the x402 challenge
         (x402Version/accepts[0].resource=...); NotaryPaymentError carries it.
         Payload built for the live x402 contract: work_hash at top level
         (the CI-channel envelope with tx_hash/payload.work_hash is NOT used here).
+
+        Payment binding (V5-A', NEAR rail): pass payer_account + bind_sig, or
+        let the SDK build them. If `near_private_key` (or env NEAR_PRIVATE_KEY)
+        is set and payer_account is provided, the SDK signs the canonical
+        AOTrust AITP-BIND v1 message with the NEP-413 raw buffer and fills
+        bind_sig. Without a key, fields are simply not added (server warn mode
+        passes unbound requests).
         """
+        payer = payer_account or request.payer_account
+        sig = bind_sig or request.bind_sig
+        key = near_private_key or os.environ.get("NEAR_PRIVATE_KEY")
+        if not sig and key and payer and request.work_hash and request.tx_hash:
+            sig = _sign_bind_message(key, request.work_hash, request.tx_hash)
+
         payload: dict = {"work_hash": request.work_hash or ""}
         if request.agent_sig:
             payload["agent_sig"] = request.agent_sig
         if request.agent_pubkey:
             payload["agent_pubkey"] = request.agent_pubkey
+        if payer:
+            payload["payer_account"] = payer
+        if sig:
+            payload["bind_sig"] = sig
         status, body = await self._request("POST", "/notarize", json_data=payload)
         self._check_status(status, body)
         if status not in (200, 202):
@@ -234,4 +296,84 @@ class NotaryClient:
             payload["agent_pubkey"] = agent_pubkey
         status, body = await self._request("POST", "/v1/shield/free", json_data=payload)
         self._check_status(status, body)
-        return body
+        return body
+
+    # ── 2.5.0: paid read products + anchor API ─────────────────────────────
+
+    async def bundle(self, work_hash: str, seq: int | None = None) -> dict:
+        """POST /v1/attestation/bundle — read-only evidence pack ($0.02).
+
+        Returns the earliest issuance unless `seq` selects a concrete one.
+        Without payment the server answers 402 → NotaryPaymentError carrying
+        the x402 challenge (`x402/payment` meta on retry).
+        """
+        payload: dict = {"work_hash": work_hash}
+        if seq is not None:
+            payload["seq"] = seq
+        status, body = await self._request("POST", "/v1/attestation/bundle", json_data=payload)
+        self._check_status(status, body)
+        return body
+
+    async def time_attest(self, payload_hash: str, nonce: str | None = None) -> dict:
+        """POST /v1/attest/time — signed time attestation ($0.002).
+
+        Returns id/ts/ts_iso/payload_hash/nonce/kid/alg/sig_b64/leaf/log_index/
+        anchor/verify. 402 → NotaryPaymentError.
+        """
+        payload: dict = {"payload_hash": payload_hash}
+        if nonce is not None:
+            payload["nonce"] = nonce
+        status, body = await self._request("POST", "/v1/attest/time", json_data=payload)
+        self._check_status(status, body)
+        return body
+
+    async def pdr_by_tx(self, tx: str) -> dict:
+        """GET /v1/pdr/by-tx/{tx} — idempotent lookup by payment transaction.
+
+        A 404 is a normal answer ({"found": False}); a malformed tx is a
+        400 → NotaryValidationError.
+        """
+        from urllib.parse import quote as _urlquote
+        status, body = await self._get_json(f"/v1/pdr/by-tx/{_urlquote(tx, safe='')}")
+        if status == 404:
+            return {"found": False}
+        self._check_status(status, body)
+        return body
+
+    async def anchor_status(self) -> dict:
+        """GET /v1/anchor/status — cumulative Merkle log status."""
+        status, body = await self._get_json("/v1/anchor/status")
+        self._check_status(status, body)
+        return body
+
+    async def anchor_proof(self, seq: int) -> dict:
+        """GET /v1/anchor/proof/{seq} — RFC 9162 inclusion proof.
+
+        The server answers 409 NOT_YET_ANCHORED (409 = state conflict: the leaf
+        exists in the log, the committed slice does not include it yet) — and
+        historically 404 with the same code — both raise
+        NotaryPendingError(eta_seconds, recheck_url). A 404 NOT_FOUND means the
+        seq was never issued; 404 NOT_A_LEAF is a server-side invariant signal.
+        """
+        status, body = await self._get_json(f"/v1/anchor/proof/{int(seq)}")
+        if status in (404, 409) and (body or {}).get("error") == "NOT_YET_ANCHORED":
+            raise NotaryPendingError(
+                eta_seconds=body.get("eta_seconds"),
+                recheck_url=body.get("recheck_url"),
+                message="Anchor not published yet; retry after eta_seconds",
+            )
+        self._check_status(status, body)
+        return body
+
+    async def anchor_logproof(self, log_index: int) -> dict:
+        """GET /v1/anchor/logproof/{log_index} — Phase B proof by opaque log_index."""
+        status, body = await self._get_json(f"/v1/anchor/logproof/{int(log_index)}")
+        self._check_status(status, body)
+        return body
+
+    async def anchor_consistency(self, from_seq: int, to_seq: int) -> dict:
+        """GET /v1/anchor/consistency?from=&to= — RFC 9162 consistency proof."""
+        status, body = await self._get_json(
+            f"/v1/anchor/consistency?from={int(from_seq)}&to={int(to_seq)}")
+        self._check_status(status, body)
+        return body

{aotrust_protocol-2.3.7 → aotrust_protocol-2.5.0}/agent_notary/exceptions.py

@@ -30,4 +30,16 @@ class NotaryValidationError(NotaryError):
 
 
 class NotaryConflictError(NotaryError):
-    """409 — idempotency conflict: this tx_hash/job_id was already used."""
+    """409 — idempotency conflict: this tx_hash/job_id was already used."""
+
+
+class NotaryPendingError(NotaryError):
+    """409/404 NOT_YET_ANCHORED — the leaf/anchor is not committed yet.
+
+    Retry after `eta_seconds`; `recheck_url` points at the same endpoint.
+    """
+
+    def __init__(self, eta_seconds=None, recheck_url=None, message=None):
+        super().__init__(message or "Not anchored yet")
+        self.eta_seconds = eta_seconds
+        self.recheck_url = recheck_url

{aotrust_protocol-2.3.7 → aotrust_protocol-2.5.0}/agent_notary/models.py

@@ -33,6 +33,13 @@ class NotarizeRequest(BaseModel):
     work_hash: Optional[str] = Field(None, description="SHA-256 hex digest (64 chars)")
     agent_sig: Optional[str] = Field(None, description="Base64 Ed25519 signature (sig_A)")
     agent_pubkey: Optional[str] = Field(None, description="Hex Ed25519 public key")
+    payer_account: Optional[str] = Field(
+        None, description="NEAR account that paid/signed the tx (payment binding)"
+    )
+    bind_sig: Optional[str] = Field(
+        None,
+        description="Base64 Ed25519 NEP-413 signature over the AOTrust AITP-BIND v1 message",
+    )
 
     def to_api_payload(self) -> dict:
         payload: dict = {"tx_hash": self.tx_hash}
@@ -42,6 +49,10 @@ class NotarizeRequest(BaseModel):
             payload["agent_sig"] = self.agent_sig
         if self.agent_pubkey:
             payload["agent_pubkey"] = self.agent_pubkey
+        if self.payer_account:
+            payload["payer_account"] = self.payer_account
+        if self.bind_sig:
+            payload["bind_sig"] = self.bind_sig
         return payload
 
 

{aotrust_protocol-2.3.7 → aotrust_protocol-2.5.0}/aotrust_protocol.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aotrust-protocol
-Version: 2.3.7
+Version: 2.5.0
 Summary: Asyncio-native SDK for A&O Trust Layer — Agent Notary Service
 Author: A&O Trust Layer
 License: MIT
@@ -31,6 +31,9 @@ Dynamic: license-file
 
 Asyncio-native Python SDK for the AOTrust Notary API — cryptographic proof-of-existence for AI agent outputs.
 
+> **Why protocol-level proofs?** An ERC-8004 empirical study (2026) measured that **>98% of agent feedback records carry no proof of an underlying interaction** (no payment proof, no task linkage); 59–91% of reviewers on three chains participated in coordinated Sybil campaigns, and manipulating a reputation score past a trust threshold costs as little as **$0.0027**. The agentic economy is moving from *statements* to *verifiable claims*: a PDR (239 bytes, Ed25519-signed, hash-chained, NEAR-anchored) turns any output or payment into independent evidence — verifiable by anyone, without trusting the provider's database.
+> *(Refs: arXiv:2610.12948 [cs.CR], 2026; ERC-8004 Sybil measurements, Xiong et al. 2026.)*
+
 ## Install
 
 ```bash
@@ -105,6 +108,43 @@ asyncio.run(main())
 > `/v1/v1/...` → HTTP 404 on every call. This bit a real user (2026-09-29:
 > quickstart copy-paste + status lookups by artifact text instead of job_id).
 
+## Paid read products (2.5.0)
+
+The SDK never signs or settles payments itself: a paid call first raises
+`NotaryPaymentError`, whose message carries the server's x402 challenge. Pay
+with any x402-capable client and retry with `X-PAYMENT` (HTTP) or
+`x402/payment` (MCP); the SDK then parses the 200 response.
+
+```python
+from agent_notary import NotaryClient
+from agent_notary.exceptions import NotaryPaymentError, NotaryPendingError
+
+client = NotaryClient()
+
+# Evidence pack — $0.02. Default = earliest issuance; seq selects one.
+pack = await client.bundle(work_hash)                 # dict: picked/issuances/anchor/verify
+pack_at_158 = await client.bundle(work_hash, seq=158)
+
+# Signed time attestation — $0.002.
+attest = await client.time_attest(payload_hash)       # id/ts/sig_b64/leaf/log_index/anchor
+
+# Idempotent lookup by payment tx — free. A 404 is a normal answer.
+found = await client.pdr_by_tx("0x" + "ab" * 32)      # {"found": False} when unknown
+
+# Anchor API — free.
+status = await client.anchor_status()                 # mode/latest/log_size
+proof = await client.anchor_proof(186)                # RFC 9162 §2.1.3 path
+logproof = await client.anchor_logproof(381)          # Phase B, kind 0/1
+cons = await client.anchor_consistency(62, 64)        # RFC 9162 §2.1.4
+
+try:
+    pack = await client.bundle(work_hash)
+except NotaryPaymentError as e:
+    print("Pay via x402, then retry with X-PAYMENT / x402/payment:", e)
+except NotaryPendingError as e:
+    print(f"Anchor not committed yet; retry in {e.eta_seconds}s at {e.recheck_url}")
+```
+
 ## Configuration
 
 | Env Var | Constructor Arg | Description |
@@ -122,6 +162,15 @@ asyncio.run(main())
 | GET | `/v1/pdr/{job_id}` | Get PDR |
 | POST | `/v1/notarize/quote` | Get price quote |
 | GET | `/.well-known/agent.json` | MCP Server Card |
+| POST | `/notarize` | Anonymous x402 paid PDR ($0.01) |
+| POST | `/v1/attestation/bundle` | Evidence pack ($0.02) |
+| POST | `/v1/attest/time` | Signed time attestation ($0.002) |
+| GET | `/v1/pdr/verify/{pdr_b64}` | Verify a PDR |
+| GET | `/v1/pdr/by-tx/{tx}` | PDR by payment tx |
+| GET | `/v1/anchor/status` | Cumulative anchor status |
+| GET | `/v1/anchor/proof/{seq}` | Inclusion proof by ledger seq |
+| GET | `/v1/anchor/logproof/{log_index}` | Inclusion proof by log index (Phase B) |
+| GET | `/v1/anchor/consistency?from=&to=` | Consistency proof |
 | GET | `/openapi.json` | OpenAPI 3.0 spec |
 
 ## PDR Verification
@@ -140,6 +189,7 @@ from agent_notary.exceptions import (
     NotaryAuthError,        # 401 (authenticated CI surfaces; anonymous x402 gives 402 instead)
     NotaryPaymentError,     # 402 x402-challenge / 403
     NotaryNotFoundError,    # 404
+    NotaryPendingError,     # 404 NOT_YET_ANCHORED — retry after eta_seconds
     NotaryValidationError,  # 400/422 — invalid params, INVALID_AGENT_SIGNATURE
     NotaryConflictError,    # 409 — tx_hash/job_id already used (idempotency)
     NotaryServerError,      # 5xx, carries status_code
@@ -166,3 +216,31 @@ except NotaryError as e:
 pip install -e ".[dev]"
 pytest tests/ -v
 ```
+
+## Payment binding (NEAR rail)
+
+NEAR payments must be provably linked to the account that sent them. Pass
+`payer_account` (the NEAR account that paid) together with `bind_sig` — a
+base64 Ed25519 **NEP-413 raw-buffer** signature (no SHA-256 pre-hash) over:
+
+```
+AOTrust AITP-BIND v1
+work_hash:<64 hex>
+tx_hash:<tx hash exactly as submitted>
+```
+
+The server resolves the account's public key via RPC and checks
+`transaction.signer_id == payer_account`; a mismatch is rejected with
+`403 PAYMENT_BIND_SIGNER_MISMATCH`, a bad signature with
+`403 PAYMENT_BIND_INVALID`.
+
+If `NEAR_PRIVATE_KEY` is set in the environment (or `near_private_key=` is
+passed), the SDK signs the canonical message itself and fills `bind_sig`:
+
+```python
+req = NotarizeRequest(tx_hash=tx, work_hash=wh)
+await client.notarize(req, payer_account="alice.near")
+```
+
+Server mode `AITP_BIND_MODE=warn` (default) accepts unbound requests with a
+`PAYMENT_UNBOUND` log line; `enforce` requires the fields.

{aotrust_protocol-2.3.7 → aotrust_protocol-2.5.0}/aotrust_protocol.egg-info/SOURCES.txt

@@ -12,4 +12,5 @@ aotrust_protocol.egg-info/dependency_links.txt
 aotrust_protocol.egg-info/requires.txt
 aotrust_protocol.egg-info/top_level.txt
 tests/test_client.py
-tests/test_live_smoke.py
+tests/test_live_smoke.py
+tests/test_v250_methods.py

{aotrust_protocol-2.3.7 → aotrust_protocol-2.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aotrust-protocol"
-version = "2.3.7"
+version = "2.5.0"
 description = "Asyncio-native SDK for A&O Trust Layer — Agent Notary Service"
 readme = "README.md"
 requires-python = ">=3.10"

{aotrust_protocol-2.3.7 → aotrust_protocol-2.5.0}/tests/test_live_smoke.py

@@ -76,8 +76,12 @@ def test_live_get_status_404_on_unknown_job():
     assert msg is not None, "get_status() на несуществующем job должен дать 404"
 
 
-def test_live_pubkey_lazy_fetch():
+def test_live_pubkey_lazy_fetch(monkeypatch):
     _live_guard()
+    # Isolation: root tests do os.environ.setdefault("NOTARY_PUBKEY", ...), and in a
+    # combined run that makes NotaryClient take the "provided key" path (no fetch),
+    # so _pubkey_fetched stays None. This test is specifically about lazy fetch.
+    monkeypatch.delenv("NOTARY_PUBKEY", raising=False)
     from agent_notary import NotaryClient
 
     client = NotaryClient()

aotrust_protocol-2.5.0/tests/test_v250_methods.py

@@ -0,0 +1,225 @@
+"""aotrust-protocol 2.5.0 — paid read products and anchor API.
+
+Mock transport only (aioresponses): bundle/time_attest, pdr_by_tx, and the
+anchor status/proof/logproof/consistency methods, including the 402 path and
+NOT_YET_ANCHORED → NotaryPendingError mapping.
+"""
+import pytest
+import aioresponses.core as _arc
+from aioresponses import aioresponses
+from aiohttp import ClientResponse as _AiohttpClientResponse
+
+
+class _CompatClientResponse(_AiohttpClientResponse):
+    """aiohttp 3.14 requires stream_writer; aioresponses 0.7.9 predates it."""
+
+    class _Writer:
+        output_size = 0
+
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault("stream_writer", self._Writer())
+        super().__init__(*args, **kwargs)
+
+
+# _build_response() resolves this module-level name at call time.
+_arc.ClientResponse = _CompatClientResponse
+
+from agent_notary import NotaryClient
+from agent_notary.exceptions import (
+    NotaryNotFoundError,
+    NotaryPaymentError,
+    NotaryPendingError,
+    NotaryValidationError,
+)
+
+BASE = "https://api.aotrust.test"
+WORK_HASH = "9" * 64
+PAYLOAD_HASH = "a" * 64
+
+
+@pytest.fixture
+def client():
+    return NotaryClient(base_url=BASE)
+
+
+@pytest.mark.asyncio
+async def test_bundle_200_and_optional_seq(client):
+    with aioresponses() as m:
+        m.post(f"{BASE}/v1/attestation/bundle", status=200, payload={
+            "work_hash": WORK_HASH,
+            "seq": 80,
+            "picked": "earliest",
+            "issuance_count": 2,
+            "issuances": [{"seq": 80}, {"seq": 158}],
+            "pdr_b64": "AAA=",
+            "anchor": {"mode": "cumulative", "size": 191},
+        })
+        out = await client.bundle(WORK_HASH)
+        assert out["seq"] == 80
+        assert out["picked"] == "earliest"
+        assert isinstance(out["issuances"], list)
+        key = next(k for k in m.requests if k[0].upper() == "POST")
+        calls = m.requests[key]
+        assert calls[0].kwargs["json"] == {"work_hash": WORK_HASH}
+
+    with aioresponses() as m:
+        m.post(f"{BASE}/v1/attestation/bundle", status=200, payload={
+            "work_hash": WORK_HASH, "seq": 158, "picked": "requested"})
+        out = await client.bundle(WORK_HASH, seq=158)
+        assert out["seq"] == 158
+        key = next(k for k in m.requests if k[0].upper() == "POST")
+        calls = m.requests[key]
+        assert calls[0].kwargs["json"] == {"work_hash": WORK_HASH, "seq": 158}
+
+
+@pytest.mark.asyncio
+async def test_bundle_402_is_payment_error(client):
+    with aioresponses() as m:
+        m.post(f"{BASE}/v1/attestation/bundle", status=402, payload={
+            "x402Version": 1,
+            "accepts": [{"scheme": "exact", "amount": "20000"}],
+            "error": "Payment required",
+        })
+        with pytest.raises(NotaryPaymentError) as exc:
+            await client.bundle(WORK_HASH)
+        assert "Payment required" in str(exc.value)
+
+
+@pytest.mark.asyncio
+async def test_time_attest_200_omits_nonce(client):
+    with aioresponses() as m:
+        m.post(f"{BASE}/v1/attest/time", status=200, payload={
+            "id": 7, "ts": 1760000000000000000, "payload_hash": PAYLOAD_HASH,
+            "sig_b64": "c2ln", "leaf": "bGVhZg==", "log_index": 381,
+            "anchor": {"mode": "cumulative", "log_index": 381},
+        })
+        out = await client.time_attest(PAYLOAD_HASH)
+        assert out["id"] == 7
+        assert out["log_index"] == 381
+        assert out["anchor"]["mode"] == "cumulative"
+        key = next(k for k in m.requests if k[0].upper() == "POST")
+        calls = m.requests[key]
+        assert calls[0].kwargs["json"] == {"payload_hash": PAYLOAD_HASH}
+
+
+@pytest.mark.asyncio
+async def test_time_attest_402_is_payment_error(client):
+    with aioresponses() as m:
+        m.post(f"{BASE}/v1/attest/time", status=402, payload={"error": "Payment required"})
+        with pytest.raises(NotaryPaymentError) as exc:
+            await client.time_attest(PAYLOAD_HASH)
+        assert "Payment required" in str(exc.value)
+
+
+@pytest.mark.asyncio
+async def test_pdr_by_tx_200(client):
+    tx = "0x" + "ab" * 32
+    with aioresponses() as m:
+        m.get(f"{BASE}/v1/pdr/by-tx/{tx}", status=200, payload={
+            "found": True, "seq": 186, "payment_hash": tx[2:],
+            "payment_anchor_type": 5, "work_hash": WORK_HASH, "pdr_b64": "AAA="})
+        out = await client.pdr_by_tx(tx)
+        assert out["found"] is True
+        assert out["seq"] == 186
+        assert out["payment_hash"] == tx[2:]
+
+
+@pytest.mark.asyncio
+async def test_pdr_by_tx_404_is_found_false(client):
+    with aioresponses() as m:
+        m.get(f"{BASE}/v1/pdr/by-tx/0xunknown", status=404, payload={"found": False})
+        assert await client.pdr_by_tx("0xunknown") == {"found": False}
+
+
+@pytest.mark.asyncio
+async def test_pdr_by_tx_400_is_validation_error(client):
+    with aioresponses() as m:
+        m.get(f"{BASE}/v1/pdr/by-tx/garbage", status=400, payload={"error": "INVALID_TX"})
+        with pytest.raises(NotaryValidationError):
+            await client.pdr_by_tx("garbage")
+
+
+@pytest.mark.asyncio
+async def test_anchor_status_200(client):
+    with aioresponses() as m:
+        m.get(f"{BASE}/v1/anchor/status", status=200, payload={
+            "mode": "cumulative",
+            "latest": {"anchor_seq": 64, "size": 191, "root": "ff" * 32,
+                       "near_tx": "tx", "ts": 1},
+            "log_size": 191,
+        })
+        out = await client.anchor_status()
+        assert out["mode"] == "cumulative"
+        assert out["latest"]["size"] == 191
+        assert out["log_size"] == 191
+
+
+@pytest.mark.asyncio
+async def test_anchor_proof_200(client):
+    with aioresponses() as m:
+        m.get(f"{BASE}/v1/anchor/proof/190", status=200, payload={
+            "mode": "cumulative", "seq": 190, "anchor_seq": 64, "size": 191,
+            "index": 189, "path": ["ab" * 32], "root": "ff" * 32,
+        })
+        out = await client.anchor_proof(190)
+        assert out["seq"] == 190
+        assert out["index"] == 189
+        assert isinstance(out["path"], list)
+
+
+@pytest.mark.asyncio
+async def test_anchor_proof_not_yet_anchored_is_pending(client):
+    # Real server semantics: 409 (state conflict) with error=NOT_YET_ANCHORED.
+    with aioresponses() as m:
+        m.get(f"{BASE}/v1/anchor/proof/999", status=409, payload={
+            "error": "NOT_YET_ANCHORED", "eta_seconds": 3600,
+            "recheck_url": "/v1/anchor/proof/999"})
+        with pytest.raises(NotaryPendingError) as exc:
+            await client.anchor_proof(999)
+        assert exc.value.eta_seconds == 3600
+        assert exc.value.recheck_url == "/v1/anchor/proof/999"
+
+
+@pytest.mark.asyncio
+async def test_anchor_proof_pending_404_compat(client):
+    # Older deployments answered 404 with the same code — keep the mapping.
+    with aioresponses() as m:
+        m.get(f"{BASE}/v1/anchor/proof/998", status=404, payload={
+            "error": "NOT_YET_ANCHORED", "eta_seconds": 60,
+            "recheck_url": "/v1/anchor/proof/998"})
+        with pytest.raises(NotaryPendingError):
+            await client.anchor_proof(998)
+
+
+@pytest.mark.asyncio
+async def test_anchor_proof_not_found_is_notary_not_found(client):
+    # A seq that was never issued must NOT look like "pending".
+    with aioresponses() as m:
+        m.get(f"{BASE}/v1/anchor/proof/7777", status=404, payload={"error": "NOT_FOUND"})
+        with pytest.raises(NotaryNotFoundError):
+            await client.anchor_proof(7777)
+
+
+@pytest.mark.asyncio
+async def test_anchor_logproof_path_and_200(client):
+    with aioresponses() as m:
+        m.get(f"{BASE}/v1/anchor/logproof/381", status=200, payload={
+            "log_index": 381, "kind": 1, "ref_id": 7, "anchor_seq": 64,
+            "size": 191, "path": [], "root": "ff" * 32})
+        out = await client.anchor_logproof(381)
+        assert out["log_index"] == 381
+        assert out["kind"] == 1
+
+
+@pytest.mark.asyncio
+async def test_anchor_consistency_query(client):
+    with aioresponses() as m:
+        m.get(f"{BASE}/v1/anchor/consistency?from=62&to=64", status=200, payload={
+            "from": {"anchor_seq": 62, "size": 189, "root": "aa" * 32},
+            "to": {"anchor_seq": 64, "size": 191, "root": "ff" * 32},
+            "proof": ["cd" * 32], "how_to_verify": "RFC 9162 §2.1.4",
+        })
+        out = await client.anchor_consistency(62, 64)
+        assert out["from"]["size"] == 189
+        assert out["to"]["anchor_seq"] == 64
+        assert isinstance(out["proof"], list)