aotrust-protocol 2.3.6__tar.gz → 2.4.0__tar.gz

aotrust_protocol-2.4.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: aotrust-protocol
+Version: 2.4.0
+Summary: Asyncio-native SDK for A&O Trust Layer — Agent Notary Service
+Author: A&O Trust Layer
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pynacl>=1.5
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: aioresponses>=0.7; extra == "dev"
+Dynamic: license-file
+
+# aotrust-protocol SDK
+
+<!-- mcp-name: link.aotrust/notary -->
+
+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
+pip install aotrust-protocol
+```
+
+## Quickstart
+
+### Free tier — no API key, no wallet (fastest way to try)
+
+```python
+import asyncio, hashlib
+from agent_notary import NotaryClient
+
+async def main():
+    # IMPORTANT: no /v1 suffix — the SDK appends API paths itself.
+    client = NotaryClient(base_url="https://api.aotrust.link")
+
+    work_hash = hashlib.sha256(b"my artifact text").hexdigest()
+    result = await client.shield_free(work_hash)
+    job_id = result["job_id"]          # keep this UUID — it is the handle
+    print("job_id:", job_id)
+
+    # Check status BY job_id (not by the artifact text!)
+    status = await client.get_status(job_id)
+    print("status:", status.status)    # PENDING → anchored (anchor batches)
+
+    # Fetch + verify the PDR
+    pdr = await client.get_pdr(job_id)
+    print("verify in browser:", pdr.verify_url)
+    assert (await client.verify_pdr(pdr.pdr_b64))["valid"]
+
+asyncio.run(main())
+```
+
+Free tier: 5 PDR / 24h per IP. Examples: [`examples/04_free_tier.py`](examples/04_free_tier.py).
+
+### Witness mode (pre-paid tx_hash)
+
+```python
+import asyncio
+from agent_notary import NotaryClient, NotarizeRequest
+
+async def main():
+    client = NotaryClient(
+        api_key="your-api-key",
+        base_url="https://api.aotrust.link"  # no /v1 suffix!
+    )
+
+    # Submit notarization
+    req = NotarizeRequest(
+        tx_hash="EzrfDW5b...",
+        work_hash="599d6999...",
+        agent_sig="base64_sig_A...",
+        agent_pubkey="aff91a18...",
+    )
+    result = await client.notarize(req)
+    print(f"Job: {result.job_id}")
+
+    # Poll for PDR — status/pdr calls always take the job_id returned above
+    status = await client.wait_for_pdr(result.job_id, timeout=60)
+    if status.is_anchored:
+        pdr = await client.get_pdr(result.job_id)
+        assert pdr.verify(client.notary_pubkey)
+        print("PDR Valid: YES")
+
+asyncio.run(main())
+```
+
+> **Why no `/v1`?** `base_url` must be `https://api.aotrust.link`. The SDK
+> already builds `/v1/...` request paths; adding `/v1` yourself produces
+> `/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).
+
+## Configuration
+
+| Env Var | Constructor Arg | Description |
+|---------|-----------------|-------------|
+| `NOTARY_API_KEY` | `api_key` | API key for auth |
+| `NOTARY_API_URL` | `base_url` | API base URL |
+| `NOTARY_PUBKEY` | `notary_pubkey` | Notary Ed25519 public key (hex) |
+
+## Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/v1/notarize` | Submit notarization |
+| GET | `/v1/status/{job_id}` | Poll job status |
+| GET | `/v1/pdr/{job_id}` | Get PDR |
+| POST | `/v1/notarize/quote` | Get price quote |
+| GET | `/.well-known/agent.json` | MCP Server Card |
+| GET | `/openapi.json` | OpenAPI 3.0 spec |
+
+## PDR Verification
+
+```python
+pdr = await client.get_pdr(job_id)
+is_valid = pdr.verify(notary_pubkey_hex="9c7d64bb...")
+```
+
+Uses NEP-413 raw-buffer verification. No SHA256 pre-hash.
+
+## Error Handling
+
+```python
+from agent_notary.exceptions import (
+    NotaryAuthError,        # 401 (authenticated CI surfaces; anonymous x402 gives 402 instead)
+    NotaryPaymentError,     # 402 x402-challenge / 403
+    NotaryNotFoundError,    # 404
+    NotaryValidationError,  # 400/422 — invalid params, INVALID_AGENT_SIGNATURE
+    NotaryConflictError,    # 409 — tx_hash/job_id already used (idempotency)
+    NotaryServerError,      # 5xx, carries status_code
+    NotaryError,            # base — safety net
+)
+
+try:
+    result = await client.notarize(req)
+except NotaryAuthError:
+    print("Invalid API key")
+except NotaryPaymentError as e:
+    print(f"Payment/sig failed: {e}")
+except NotaryValidationError as e:
+    print(f"Bad request or invalid signature: {e}")
+except NotaryConflictError:
+    print("This tx_hash/job_id was already used — generate a new one")
+except NotaryError as e:
+    print(f"Other SDK error: {e}")
+```
+
+## Development
+
+```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.4.0/README.md

@@ -0,0 +1,172 @@
+# aotrust-protocol SDK
+
+<!-- mcp-name: link.aotrust/notary -->
+
+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
+pip install aotrust-protocol
+```
+
+## Quickstart
+
+### Free tier — no API key, no wallet (fastest way to try)
+
+```python
+import asyncio, hashlib
+from agent_notary import NotaryClient
+
+async def main():
+    # IMPORTANT: no /v1 suffix — the SDK appends API paths itself.
+    client = NotaryClient(base_url="https://api.aotrust.link")
+
+    work_hash = hashlib.sha256(b"my artifact text").hexdigest()
+    result = await client.shield_free(work_hash)
+    job_id = result["job_id"]          # keep this UUID — it is the handle
+    print("job_id:", job_id)
+
+    # Check status BY job_id (not by the artifact text!)
+    status = await client.get_status(job_id)
+    print("status:", status.status)    # PENDING → anchored (anchor batches)
+
+    # Fetch + verify the PDR
+    pdr = await client.get_pdr(job_id)
+    print("verify in browser:", pdr.verify_url)
+    assert (await client.verify_pdr(pdr.pdr_b64))["valid"]
+
+asyncio.run(main())
+```
+
+Free tier: 5 PDR / 24h per IP. Examples: [`examples/04_free_tier.py`](examples/04_free_tier.py).
+
+### Witness mode (pre-paid tx_hash)
+
+```python
+import asyncio
+from agent_notary import NotaryClient, NotarizeRequest
+
+async def main():
+    client = NotaryClient(
+        api_key="your-api-key",
+        base_url="https://api.aotrust.link"  # no /v1 suffix!
+    )
+
+    # Submit notarization
+    req = NotarizeRequest(
+        tx_hash="EzrfDW5b...",
+        work_hash="599d6999...",
+        agent_sig="base64_sig_A...",
+        agent_pubkey="aff91a18...",
+    )
+    result = await client.notarize(req)
+    print(f"Job: {result.job_id}")
+
+    # Poll for PDR — status/pdr calls always take the job_id returned above
+    status = await client.wait_for_pdr(result.job_id, timeout=60)
+    if status.is_anchored:
+        pdr = await client.get_pdr(result.job_id)
+        assert pdr.verify(client.notary_pubkey)
+        print("PDR Valid: YES")
+
+asyncio.run(main())
+```
+
+> **Why no `/v1`?** `base_url` must be `https://api.aotrust.link`. The SDK
+> already builds `/v1/...` request paths; adding `/v1` yourself produces
+> `/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).
+
+## Configuration
+
+| Env Var | Constructor Arg | Description |
+|---------|-----------------|-------------|
+| `NOTARY_API_KEY` | `api_key` | API key for auth |
+| `NOTARY_API_URL` | `base_url` | API base URL |
+| `NOTARY_PUBKEY` | `notary_pubkey` | Notary Ed25519 public key (hex) |
+
+## Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/v1/notarize` | Submit notarization |
+| GET | `/v1/status/{job_id}` | Poll job status |
+| GET | `/v1/pdr/{job_id}` | Get PDR |
+| POST | `/v1/notarize/quote` | Get price quote |
+| GET | `/.well-known/agent.json` | MCP Server Card |
+| GET | `/openapi.json` | OpenAPI 3.0 spec |
+
+## PDR Verification
+
+```python
+pdr = await client.get_pdr(job_id)
+is_valid = pdr.verify(notary_pubkey_hex="9c7d64bb...")
+```
+
+Uses NEP-413 raw-buffer verification. No SHA256 pre-hash.
+
+## Error Handling
+
+```python
+from agent_notary.exceptions import (
+    NotaryAuthError,        # 401 (authenticated CI surfaces; anonymous x402 gives 402 instead)
+    NotaryPaymentError,     # 402 x402-challenge / 403
+    NotaryNotFoundError,    # 404
+    NotaryValidationError,  # 400/422 — invalid params, INVALID_AGENT_SIGNATURE
+    NotaryConflictError,    # 409 — tx_hash/job_id already used (idempotency)
+    NotaryServerError,      # 5xx, carries status_code
+    NotaryError,            # base — safety net
+)
+
+try:
+    result = await client.notarize(req)
+except NotaryAuthError:
+    print("Invalid API key")
+except NotaryPaymentError as e:
+    print(f"Payment/sig failed: {e}")
+except NotaryValidationError as e:
+    print(f"Bad request or invalid signature: {e}")
+except NotaryConflictError:
+    print("This tx_hash/job_id was already used — generate a new one")
+except NotaryError as e:
+    print(f"Other SDK error: {e}")
+```
+
+## Development
+
+```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.6 → aotrust_protocol-2.4.0}/agent_notary/__init__.py

@@ -1,6 +1,6 @@
 """A&O Trust Layer — Agent Notary SDK (asyncio-native)."""
 
-__version__ = "2.3.6"
+__version__ = "2.3.7"
 
 from .client import NotaryClient
 from .models import NotarizeRequest, NotarizeResult, PdrResult, StatusResult

{aotrust_protocol-2.3.6 → aotrust_protocol-2.4.0}/agent_notary/client.py

@@ -9,12 +9,48 @@ 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,
     NotaryServerError,
+    NotaryValidationError,
+    NotaryConflictError,
 )
 
 DEFAULT_TIMEOUT = 30
@@ -119,22 +155,50 @@ class NotaryClient:
             raise NotaryNotFoundError(body.get("error", "Not found"))
         if status == 429:
             raise NotaryError(body.get("error", body.get("message", "Rate limit reached")))
+        if status == 409:
+            raise NotaryConflictError(body.get("error", body.get("message", "Conflict")))
+        if status in (400, 422):
+            detail = body.get("message") or body.get("detail") or body.get("error") or f"Invalid request ({status})"
+            raise NotaryValidationError(f"{detail} (HTTP {status})")
         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):

{aotrust_protocol-2.3.6 → aotrust_protocol-2.4.0}/agent_notary/exceptions.py

@@ -22,4 +22,12 @@ class NotaryServerError(NotaryError):
 
     def __init__(self, message: str, status_code: int = 0):
         super().__init__(message)
-        self.status_code = status_code
+        self.status_code = status_code
+
+
+class NotaryValidationError(NotaryError):
+    """400/422 — request payload rejected: invalid params or signature/content mismatch."""
+
+
+class NotaryConflictError(NotaryError):
+    """409 — idempotency conflict: this tx_hash/job_id was already used."""

{aotrust_protocol-2.3.6 → aotrust_protocol-2.4.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.4.0/aotrust_protocol.egg-info/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: aotrust-protocol
+Version: 2.4.0
+Summary: Asyncio-native SDK for A&O Trust Layer — Agent Notary Service
+Author: A&O Trust Layer
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pynacl>=1.5
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: aioresponses>=0.7; extra == "dev"
+Dynamic: license-file
+
+# aotrust-protocol SDK
+
+<!-- mcp-name: link.aotrust/notary -->
+
+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
+pip install aotrust-protocol
+```
+
+## Quickstart
+
+### Free tier — no API key, no wallet (fastest way to try)
+
+```python
+import asyncio, hashlib
+from agent_notary import NotaryClient
+
+async def main():
+    # IMPORTANT: no /v1 suffix — the SDK appends API paths itself.
+    client = NotaryClient(base_url="https://api.aotrust.link")
+
+    work_hash = hashlib.sha256(b"my artifact text").hexdigest()
+    result = await client.shield_free(work_hash)
+    job_id = result["job_id"]          # keep this UUID — it is the handle
+    print("job_id:", job_id)
+
+    # Check status BY job_id (not by the artifact text!)
+    status = await client.get_status(job_id)
+    print("status:", status.status)    # PENDING → anchored (anchor batches)
+
+    # Fetch + verify the PDR
+    pdr = await client.get_pdr(job_id)
+    print("verify in browser:", pdr.verify_url)
+    assert (await client.verify_pdr(pdr.pdr_b64))["valid"]
+
+asyncio.run(main())
+```
+
+Free tier: 5 PDR / 24h per IP. Examples: [`examples/04_free_tier.py`](examples/04_free_tier.py).
+
+### Witness mode (pre-paid tx_hash)
+
+```python
+import asyncio
+from agent_notary import NotaryClient, NotarizeRequest
+
+async def main():
+    client = NotaryClient(
+        api_key="your-api-key",
+        base_url="https://api.aotrust.link"  # no /v1 suffix!
+    )
+
+    # Submit notarization
+    req = NotarizeRequest(
+        tx_hash="EzrfDW5b...",
+        work_hash="599d6999...",
+        agent_sig="base64_sig_A...",
+        agent_pubkey="aff91a18...",
+    )
+    result = await client.notarize(req)
+    print(f"Job: {result.job_id}")
+
+    # Poll for PDR — status/pdr calls always take the job_id returned above
+    status = await client.wait_for_pdr(result.job_id, timeout=60)
+    if status.is_anchored:
+        pdr = await client.get_pdr(result.job_id)
+        assert pdr.verify(client.notary_pubkey)
+        print("PDR Valid: YES")
+
+asyncio.run(main())
+```
+
+> **Why no `/v1`?** `base_url` must be `https://api.aotrust.link`. The SDK
+> already builds `/v1/...` request paths; adding `/v1` yourself produces
+> `/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).
+
+## Configuration
+
+| Env Var | Constructor Arg | Description |
+|---------|-----------------|-------------|
+| `NOTARY_API_KEY` | `api_key` | API key for auth |
+| `NOTARY_API_URL` | `base_url` | API base URL |
+| `NOTARY_PUBKEY` | `notary_pubkey` | Notary Ed25519 public key (hex) |
+
+## Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/v1/notarize` | Submit notarization |
+| GET | `/v1/status/{job_id}` | Poll job status |
+| GET | `/v1/pdr/{job_id}` | Get PDR |
+| POST | `/v1/notarize/quote` | Get price quote |
+| GET | `/.well-known/agent.json` | MCP Server Card |
+| GET | `/openapi.json` | OpenAPI 3.0 spec |
+
+## PDR Verification
+
+```python
+pdr = await client.get_pdr(job_id)
+is_valid = pdr.verify(notary_pubkey_hex="9c7d64bb...")
+```
+
+Uses NEP-413 raw-buffer verification. No SHA256 pre-hash.
+
+## Error Handling
+
+```python
+from agent_notary.exceptions import (
+    NotaryAuthError,        # 401 (authenticated CI surfaces; anonymous x402 gives 402 instead)
+    NotaryPaymentError,     # 402 x402-challenge / 403
+    NotaryNotFoundError,    # 404
+    NotaryValidationError,  # 400/422 — invalid params, INVALID_AGENT_SIGNATURE
+    NotaryConflictError,    # 409 — tx_hash/job_id already used (idempotency)
+    NotaryServerError,      # 5xx, carries status_code
+    NotaryError,            # base — safety net
+)
+
+try:
+    result = await client.notarize(req)
+except NotaryAuthError:
+    print("Invalid API key")
+except NotaryPaymentError as e:
+    print(f"Payment/sig failed: {e}")
+except NotaryValidationError as e:
+    print(f"Bad request or invalid signature: {e}")
+except NotaryConflictError:
+    print("This tx_hash/job_id was already used — generate a new one")
+except NotaryError as e:
+    print(f"Other SDK error: {e}")
+```
+
+## Development
+
+```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.6 → aotrust_protocol-2.4.0}/pyproject.toml

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

aotrust_protocol-2.3.6/PKG-INFO

@@ -1,118 +0,0 @@
-Metadata-Version: 2.4
-Name: aotrust-protocol
-Version: 2.3.6
-Summary: Asyncio-native SDK for A&O Trust Layer — Agent Notary Service
-Author: A&O Trust Layer
-License: MIT
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Framework :: AsyncIO
-Classifier: Topic :: Security :: Cryptography
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: aiohttp>=3.9
-Requires-Dist: pydantic>=2.0
-Requires-Dist: pynacl>=1.5
-Provides-Extra: dev
-Requires-Dist: pytest>=7.0; extra == "dev"
-Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
-Requires-Dist: pytest-cov>=4.0; extra == "dev"
-Requires-Dist: aioresponses>=0.7; extra == "dev"
-Dynamic: license-file
-
-# aotrust-protocol SDK
-
-<!-- mcp-name: link.aotrust/notary -->
-
-Asyncio-native Python SDK for the AOTrust Notary API — cryptographic proof-of-existence for AI agent outputs.
-
-## Install
-
-```bash
-pip install aotrust-protocol
-```
-
-## Quickstart
-
-```python
-import asyncio
-from agent_notary import NotaryClient, NotarizeRequest
-
-async def main():
-    client = NotaryClient(
-        api_key="your-api-key",
-        base_url="https://api.aotrust.link/v1"
-    )
-
-    # Submit notarization
-    req = NotarizeRequest(
-        tx_hash="EzrfDW5b...",
-        work_hash="599d6999...",
-        agent_sig="base64_sig_A...",
-        agent_pubkey="aff91a18...",
-    )
-    result = await client.notarize(req)
-    print(f"Job: {result.job_id}")
-
-    # Poll for PDR
-    status = await client.wait_for_pdr(result.job_id, timeout=60)
-    if status.is_anchored:
-        pdr = await client.get_pdr(result.job_id)
-        assert pdr.verify(client.notary_pubkey)
-        print("PDR Valid: YES")
-
-asyncio.run(main())
-```
-
-## Configuration
-
-| Env Var | Constructor Arg | Description |
-|---------|-----------------|-------------|
-| `NOTARY_API_KEY` | `api_key` | API key for auth |
-| `NOTARY_API_URL` | `base_url` | API base URL |
-| `NOTARY_PUBKEY` | `notary_pubkey` | Notary Ed25519 public key (hex) |
-
-## Endpoints
-
-| Method | Path | Description |
-|--------|------|-------------|
-| POST | `/v1/notarize` | Submit notarization |
-| GET | `/v1/status/{job_id}` | Poll job status |
-| GET | `/v1/pdr/{job_id}` | Get PDR |
-| POST | `/v1/notarize/quote` | Get price quote |
-| GET | `/.well-known/agent.json` | MCP Server Card |
-| GET | `/openapi.json` | OpenAPI 3.0 spec |
-
-## PDR Verification
-
-```python
-pdr = await client.get_pdr(job_id)
-is_valid = pdr.verify(notary_pubkey_hex="9c7d64bb...")
-```
-
-Uses NEP-413 raw-buffer verification. No SHA256 pre-hash.
-
-## Error Handling
-
-```python
-from agent_notary.exceptions import NotaryAuthError, NotaryPaymentError, NotaryNotFoundError
-
-try:
-    result = await client.notarize(req)
-except NotaryAuthError:
-    print("Invalid API key")
-except NotaryPaymentError as e:
-    print(f"Payment/sig failed: {e}")
-```
-
-## Development
-
-```bash
-pip install -e ".[dev]"
-pytest tests/ -v
-```

aotrust_protocol-2.3.6/README.md

@@ -1,91 +0,0 @@
-# aotrust-protocol SDK
-
-<!-- mcp-name: link.aotrust/notary -->
-
-Asyncio-native Python SDK for the AOTrust Notary API — cryptographic proof-of-existence for AI agent outputs.
-
-## Install
-
-```bash
-pip install aotrust-protocol
-```
-
-## Quickstart
-
-```python
-import asyncio
-from agent_notary import NotaryClient, NotarizeRequest
-
-async def main():
-    client = NotaryClient(
-        api_key="your-api-key",
-        base_url="https://api.aotrust.link/v1"
-    )
-
-    # Submit notarization
-    req = NotarizeRequest(
-        tx_hash="EzrfDW5b...",
-        work_hash="599d6999...",
-        agent_sig="base64_sig_A...",
-        agent_pubkey="aff91a18...",
-    )
-    result = await client.notarize(req)
-    print(f"Job: {result.job_id}")
-
-    # Poll for PDR
-    status = await client.wait_for_pdr(result.job_id, timeout=60)
-    if status.is_anchored:
-        pdr = await client.get_pdr(result.job_id)
-        assert pdr.verify(client.notary_pubkey)
-        print("PDR Valid: YES")
-
-asyncio.run(main())
-```
-
-## Configuration
-
-| Env Var | Constructor Arg | Description |
-|---------|-----------------|-------------|
-| `NOTARY_API_KEY` | `api_key` | API key for auth |
-| `NOTARY_API_URL` | `base_url` | API base URL |
-| `NOTARY_PUBKEY` | `notary_pubkey` | Notary Ed25519 public key (hex) |
-
-## Endpoints
-
-| Method | Path | Description |
-|--------|------|-------------|
-| POST | `/v1/notarize` | Submit notarization |
-| GET | `/v1/status/{job_id}` | Poll job status |
-| GET | `/v1/pdr/{job_id}` | Get PDR |
-| POST | `/v1/notarize/quote` | Get price quote |
-| GET | `/.well-known/agent.json` | MCP Server Card |
-| GET | `/openapi.json` | OpenAPI 3.0 spec |
-
-## PDR Verification
-
-```python
-pdr = await client.get_pdr(job_id)
-is_valid = pdr.verify(notary_pubkey_hex="9c7d64bb...")
-```
-
-Uses NEP-413 raw-buffer verification. No SHA256 pre-hash.
-
-## Error Handling
-
-```python
-from agent_notary.exceptions import NotaryAuthError, NotaryPaymentError, NotaryNotFoundError
-
-try:
-    result = await client.notarize(req)
-except NotaryAuthError:
-    print("Invalid API key")
-except NotaryPaymentError as e:
-    print(f"Payment/sig failed: {e}")
-```
-
-## Development
-
-```bash
-pip install -e ".[dev]"
-pytest tests/ -v
-```

aotrust_protocol-2.3.6/aotrust_protocol.egg-info/PKG-INFO

@@ -1,118 +0,0 @@
-Metadata-Version: 2.4
-Name: aotrust-protocol
-Version: 2.3.6
-Summary: Asyncio-native SDK for A&O Trust Layer — Agent Notary Service
-Author: A&O Trust Layer
-License: MIT
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Framework :: AsyncIO
-Classifier: Topic :: Security :: Cryptography
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: aiohttp>=3.9
-Requires-Dist: pydantic>=2.0
-Requires-Dist: pynacl>=1.5
-Provides-Extra: dev
-Requires-Dist: pytest>=7.0; extra == "dev"
-Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
-Requires-Dist: pytest-cov>=4.0; extra == "dev"
-Requires-Dist: aioresponses>=0.7; extra == "dev"
-Dynamic: license-file
-
-# aotrust-protocol SDK
-
-<!-- mcp-name: link.aotrust/notary -->
-
-Asyncio-native Python SDK for the AOTrust Notary API — cryptographic proof-of-existence for AI agent outputs.
-
-## Install
-
-```bash
-pip install aotrust-protocol
-```
-
-## Quickstart
-
-```python
-import asyncio
-from agent_notary import NotaryClient, NotarizeRequest
-
-async def main():
-    client = NotaryClient(
-        api_key="your-api-key",
-        base_url="https://api.aotrust.link/v1"
-    )
-
-    # Submit notarization
-    req = NotarizeRequest(
-        tx_hash="EzrfDW5b...",
-        work_hash="599d6999...",
-        agent_sig="base64_sig_A...",
-        agent_pubkey="aff91a18...",
-    )
-    result = await client.notarize(req)
-    print(f"Job: {result.job_id}")
-
-    # Poll for PDR
-    status = await client.wait_for_pdr(result.job_id, timeout=60)
-    if status.is_anchored:
-        pdr = await client.get_pdr(result.job_id)
-        assert pdr.verify(client.notary_pubkey)
-        print("PDR Valid: YES")
-
-asyncio.run(main())
-```
-
-## Configuration
-
-| Env Var | Constructor Arg | Description |
-|---------|-----------------|-------------|
-| `NOTARY_API_KEY` | `api_key` | API key for auth |
-| `NOTARY_API_URL` | `base_url` | API base URL |
-| `NOTARY_PUBKEY` | `notary_pubkey` | Notary Ed25519 public key (hex) |
-
-## Endpoints
-
-| Method | Path | Description |
-|--------|------|-------------|
-| POST | `/v1/notarize` | Submit notarization |
-| GET | `/v1/status/{job_id}` | Poll job status |
-| GET | `/v1/pdr/{job_id}` | Get PDR |
-| POST | `/v1/notarize/quote` | Get price quote |
-| GET | `/.well-known/agent.json` | MCP Server Card |
-| GET | `/openapi.json` | OpenAPI 3.0 spec |
-
-## PDR Verification
-
-```python
-pdr = await client.get_pdr(job_id)
-is_valid = pdr.verify(notary_pubkey_hex="9c7d64bb...")
-```
-
-Uses NEP-413 raw-buffer verification. No SHA256 pre-hash.
-
-## Error Handling
-
-```python
-from agent_notary.exceptions import NotaryAuthError, NotaryPaymentError, NotaryNotFoundError
-
-try:
-    result = await client.notarize(req)
-except NotaryAuthError:
-    print("Invalid API key")
-except NotaryPaymentError as e:
-    print(f"Payment/sig failed: {e}")
-```
-
-## Development
-
-```bash
-pip install -e ".[dev]"
-pytest tests/ -v
-```