aotrust-protocol 2.2.0__py3-none-any.whl

agent_notary/__init__.py

@@ -0,0 +1,24 @@
+"""A&O Trust Layer — Agent Notary SDK (asyncio-native)."""
+
+from .client import NotaryClient
+from .models import NotarizeRequest, NotarizeResult, PdrResult, StatusResult
+from .exceptions import (
+    NotaryError,
+    NotaryAuthError,
+    NotaryNotFoundError,
+    NotaryPaymentError,
+    NotaryServerError,
+)
+
+__all__ = [
+    "NotaryClient",
+    "NotarizeRequest",
+    "NotarizeResult",
+    "PdrResult",
+    "StatusResult",
+    "NotaryError",
+    "NotaryAuthError",
+    "NotaryNotFoundError",
+    "NotaryPaymentError",
+    "NotaryServerError",
+]

agent_notary/client.py

@@ -0,0 +1,128 @@
+"""Asyncio-native NotaryClient for A&O Trust Layer."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Optional
+
+import aiohttp
+
+from .models import NotarizeRequest, NotarizeResult, StatusResult, PdrResult
+from .exceptions import (
+    NotaryError,
+    NotaryAuthError,
+    NotaryNotFoundError,
+    NotaryPaymentError,
+    NotaryServerError,
+)
+
+DEFAULT_TIMEOUT = 30
+DEFAULT_POLL_INTERVAL = 2.0
+DEFAULT_POLL_TIMEOUT = 120.0
+MAX_RETRIES = 3
+RETRY_DELAYS = (1.0, 2.0, 4.0)
+
+
+class NotaryClient:
+    """Async client for the A&O Trust Layer Notary API."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        notary_pubkey: Optional[str] = None,
+    ):
+        self.api_key = api_key or os.environ.get("NOTARY_API_KEY", "")
+        self.base_url = (base_url or os.environ.get("NOTARY_API_URL", "https://api.aotrust.link/v1")).rstrip("/")
+        self.notary_pubkey = notary_pubkey or os.environ.get("NOTARY_PUBKEY", "9c7d64bbabe90ead8f18982497a47acbd95677cef0d9285caec95377e4ccf6b0")
+
+    def _headers(self) -> dict:
+        h = {"Content-Type": "application/json"}
+        if self.api_key:
+            h["X-API-Key"] = self.api_key
+        return h
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        json_data: Optional[dict] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> tuple[int, dict]:
+        url = f"{self.base_url}{path}"
+        last_exc = None
+        for attempt in range(MAX_RETRIES):
+            try:
+                async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=timeout)) as session:
+                    async with session.request(method, url, headers=self._headers(), json=json_data) as resp:
+                        body = await resp.json(content_type=None) if resp.content_type and "json" in resp.content_type else {}
+                        if resp.status in (502, 503) and attempt < MAX_RETRIES - 1:
+                            await asyncio.sleep(RETRY_DELAYS[attempt])
+                            continue
+                        return resp.status, body
+            except aiohttp.ClientError as exc:
+                last_exc = exc
+                if attempt < MAX_RETRIES - 1:
+                    await asyncio.sleep(RETRY_DELAYS[attempt])
+        raise NotaryServerError(f"Request failed after {MAX_RETRIES} retries: {last_exc}")
+
+    def _check_status(self, status: int, body: dict) -> None:
+        if status == 401:
+            raise NotaryAuthError(body.get("error", "Unauthorized"))
+        if status == 403:
+            detail = body.get("detail", body.get("error", "Forbidden"))
+            raise NotaryPaymentError(detail)
+        if status == 404:
+            raise NotaryNotFoundError(body.get("error", "Not found"))
+        if status >= 500:
+            raise NotaryServerError(body.get("error", f"Server error {status}"), status_code=status)
+
+    async def notarize(self, request: NotarizeRequest) -> NotarizeResult:
+        status, body = await self._request("POST", "/notarize", json_data=request.to_api_payload())
+        self._check_status(status, body)
+        if status not in (200, 202):
+            raise NotaryError(f"Unexpected status {status}: {body}")
+        return NotarizeResult(job_id=body.get("job_id", ""))
+
+    async def get_status(self, job_id: str) -> StatusResult:
+        status, body = await self._request("GET", f"/status/{job_id}")
+        self._check_status(status, body)
+        result = body.get("result", {})
+        return StatusResult(
+            status=body.get("status", "unknown"),
+            pdr_b64=result.get("pdr_b64"),
+            payment_hash=result.get("near_tx_hash") or result.get("payment_hash"),
+        )
+
+    async def get_pdr(self, job_id: str) -> PdrResult:
+        status, body = await self._request("GET", f"/pdr/{job_id}")
+        self._check_status(status, body)
+        verify_url = f"{self.base_url}/verify/{job_id}" if "verify_url" not in body else body.get("verify_url")
+        return PdrResult(
+            pdr_b64=body.get("pdr", body.get("pdr_b64", "")),
+            payment_hash=body.get("near_tx_hash") or body.get("payment_hash"),
+            verify_url=verify_url,
+        )
+
+    async def wait_for_pdr(
+        self,
+        job_id: str,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        timeout: float = DEFAULT_POLL_TIMEOUT,
+    ) -> StatusResult:
+        elapsed = 0.0
+        while elapsed < timeout:
+            result = await self.get_status(job_id)
+            if result.is_anchored:
+                return result
+            if result.status.lower() in ("rejected", "error", "failed"):
+                raise NotaryPaymentError(f"Notarization {result.status}")
+            await asyncio.sleep(poll_interval)
+            elapsed += poll_interval
+        raise NotaryServerError(f"Timed out waiting for PDR ({timeout}s)")
+
+    async def quote(self) -> dict:
+        status, body = await self._request("POST", "/notarize/quote")
+        self._check_status(status, body)
+        return body

agent_notary/exceptions.py

@@ -0,0 +1,25 @@
+"""Custom exceptions for NotaryClient."""
+
+
+class NotaryError(Exception):
+    """Base exception for all NotaryClient errors."""
+
+
+class NotaryAuthError(NotaryError):
+    """401 Unauthorized — invalid or missing API key."""
+
+
+class NotaryPaymentError(NotaryError):
+    """403 Forbidden — payment verification or agent signature failed."""
+
+
+class NotaryNotFoundError(NotaryError):
+    """404 Not Found — job_id or PDR not found."""
+
+
+class NotaryServerError(NotaryError):
+    """5xx server error with retry context."""
+
+    def __init__(self, message: str, status_code: int = 0):
+        super().__init__(message)
+        self.status_code = status_code

agent_notary/models.py

@@ -0,0 +1,148 @@
+"""Pydantic models for NotaryClient request/response schemas."""
+
+from __future__ import annotations
+
+import base64
+import struct
+from enum import IntEnum
+from typing import Optional
+from pydantic import BaseModel, Field, validator
+
+NEP413_TAG = 2147484061
+EXTERNAL_PDR_SIZE = 239
+EXTERNAL_PAYLOAD_SIZE = 175
+
+
+class PaymentAnchorType(IntEnum):
+    UNPAID              = 0x00
+    NEAR_DIRECT         = 0x01
+    AGENT_MARKET_SUBMIT = 0x02
+    AGENT_MARKET_RELEASE= 0x03
+    NEAR_ESCROW_LOCK    = 0x04
+    X402_BASE           = 0x05
+    X402_POLYGON        = 0x06
+    X402_NEAR           = 0x07
+    CHAIN_SIG_PAYMENT   = 0x08
+    NEAR_ESCROW_SETTLED = 0x09
+    UNKNOWN             = 0xFF
+
+
+class NotarizeRequest(BaseModel):
+    tx_hash: str = Field(..., min_length=32, max_length=128, description="tx hash (NEAR Base58 or EVM hex)")
+    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")
+
+    def to_api_payload(self) -> dict:
+        payload: dict = {"tx_hash": self.tx_hash}
+        if self.work_hash:
+            payload["payload"] = {"work_hash": self.work_hash}
+        if self.agent_sig:
+            payload["agent_sig"] = self.agent_sig
+        if self.agent_pubkey:
+            payload["agent_pubkey"] = self.agent_pubkey
+        return payload
+
+
+class NotarizeResult(BaseModel):
+    job_id: str
+
+
+class StatusResult(BaseModel):
+    status: str
+    pdr_b64: Optional[str] = None
+    payment_hash: Optional[str] = None
+
+    @property
+    def is_anchored(self) -> bool:
+        return self.status.lower() == "anchored"
+
+
+class PdrResult(BaseModel):
+    pdr_b64: str
+    payment_hash: Optional[str] = None
+    payment_anchor_type: Optional[int] = None
+    format: str = "nep413-dualsig-v1"
+    verify_url: Optional[str] = None
+
+    @property
+    def pdr_bytes(self) -> bytes:
+        return base64.b64decode(self.pdr_b64)
+
+    def _resolve_payment_anchor_type(self) -> None:
+        if self.payment_anchor_type is not None:
+            return
+        raw = self.pdr_bytes
+        version = raw[0]
+        if version == 0x02:
+            self.payment_anchor_type = PaymentAnchorType.NEAR_DIRECT
+        elif version in (0x03, 0x04):
+            pat_byte = raw[2]
+            try:
+                self.payment_anchor_type = PaymentAnchorType(pat_byte)
+            except ValueError:
+                self.payment_anchor_type = PaymentAnchorType.UNKNOWN
+        else:
+            self.payment_anchor_type = PaymentAnchorType.UNKNOWN
+
+    @property
+    def payload_bytes(self) -> bytes:
+        raw = self.pdr_bytes
+        version = raw[0]
+        if version == 0x02:
+            expected = EXTERNAL_PDR_SIZE + 1  # v2.2 was 238 (one byte less than v2.3's 239)
+            payload_size = EXTERNAL_PAYLOAD_SIZE + 1  # v2.2 was 174 (one byte less than v2.3's 175)
+        elif version in (0x03, 0x04):
+            expected = EXTERNAL_PDR_SIZE
+            payload_size = EXTERNAL_PAYLOAD_SIZE
+        else:
+            raise ValueError(f"Unknown PDR version: {version:#04x}")
+        if len(raw) != expected:
+            raise ValueError(f"Invalid PDR size: {len(raw)}, expected {expected}")
+        return raw[:payload_size]
+
+    @property
+    def signature_bytes(self) -> bytes:
+        raw = self.pdr_bytes
+        version = raw[0]
+        if version == 0x02:
+            payload_size = EXTERNAL_PAYLOAD_SIZE + 1  # v2.2 was 174
+        elif version in (0x03, 0x04):
+            payload_size = EXTERNAL_PAYLOAD_SIZE
+        else:
+            payload_size = EXTERNAL_PAYLOAD_SIZE
+        return raw[payload_size:]
+
+    def verify(self, notary_pubkey_hex: str) -> bool:
+        from nacl.signing import VerifyKey
+        from nacl.exceptions import BadSignatureError
+
+        raw = self.pdr_bytes
+        version = raw[0]
+        if version == 0x02:
+            expected = EXTERNAL_PDR_SIZE + 1  # v2.2 was 238
+            payload_size = EXTERNAL_PAYLOAD_SIZE + 1  # v2.2 was 174
+        elif version in (0x03, 0x04):
+            expected = EXTERNAL_PDR_SIZE
+            payload_size = EXTERNAL_PAYLOAD_SIZE
+        else:
+            return False
+        if len(raw) != expected:
+            return False
+
+        self._resolve_payment_anchor_type()
+
+        payload = raw[:payload_size]
+        signature = raw[payload_size:]
+        verify_key = VerifyKey(bytes.fromhex(notary_pubkey_hex))
+        nep413_buffer = struct.pack("<II", NEP413_TAG, len(payload)) + payload
+        try:
+            verify_key.verify(nep413_buffer, signature)
+        except BadSignatureError:
+            return False
+
+        if self.payment_anchor_type not in (None, PaymentAnchorType.UNPAID):
+            if self.payment_hash is not None and len(self.payment_hash) < 4:
+                return False
+
+        return True

aotrust_protocol-2.2.0.dist-info/METADATA

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: aotrust-protocol
+Version: 2.2.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
+
+# agent-notary SDK
+
+Asyncio-native Python SDK for the A&O Trust Layer Notary API.
+
+## Install
+
+```bash
+pip install agent-notary
+```
+
+## 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.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+agent_notary/__init__.py,sha256=XFlyetoH5WTncJ2SrDyJzVFt2z6jWlTTD1UxdAwFc1Q,546
+agent_notary/client.py,sha256=0gEDKRMaqgl22bqAnk-7FhF3age_vx0ahXC9_zm-lCI,5077
+agent_notary/exceptions.py,sha256=YE_sKmK7BHnxTWB4wCUeWIyBgu54DknDoIAQgbW6h5Y,657
+agent_notary/models.py,sha256=w522Co863dflEpTlWQVE9Gs6SGLgNMFTiqVr2OStLu0,4908
+aotrust_protocol-2.2.0.dist-info/licenses/LICENSE,sha256=rbAuFQIJDAkZOMMLJ02qyksduBpI2mg2Y4PD26zgsq4,1071
+aotrust_protocol-2.2.0.dist-info/METADATA,sha256=ihm0fG3COkZD1DtXyHYB4vjOUvrB4Y-g5mrQ8VQt5uM,3036
+aotrust_protocol-2.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+aotrust_protocol-2.2.0.dist-info/top_level.txt,sha256=bKhWjMrwnDELWzmK7yRXR5W-Wjtl55EdgH_ZimS6l7o,13
+aotrust_protocol-2.2.0.dist-info/RECORD,,

aotrust_protocol-2.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

aotrust_protocol-2.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 A&O Trust Layer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aotrust_protocol-2.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agent_notary