genzagents 0.1.0__tar.gz

genzagents-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# Build artefacts
+build/
+dist/
+*.egg-info/
+
+# Virtualenvs
+.venv/
+venv/
+
+# Tests
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Python bytecode
+__pycache__/
+*.py[cod]
+*$py.class

genzagents-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: genzagents
+Version: 0.1.0
+Summary: Python SDK for GenZAgents work receipts — issue, sign, and verify AI agent work.
+Project-URL: Homepage, https://genzagents.com
+Project-URL: Documentation, https://genzagents.com/mcp
+Project-URL: Repository, https://github.com/genzagents/genzagents
+Project-URL: Changelog, https://github.com/genzagents/genzagents/blob/main/packages/sdk-py/CHANGELOG.md
+Author-email: GenZAgents <hello@genzagents.com>
+License-Expression: Apache-2.0
+Keywords: ai-agents,genzagents,mcp,trust,verification,work-receipts
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: typing-extensions>=4.10
+Requires-Dist: ulid-py>=1.1
+Provides-Extra: bls
+Requires-Dist: py-ecc>=7.0; extra == 'bls'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# genzagents
+
+Python SDK for GenZAgents work receipts — issue, sign, and verify the
+cryptographic record of work performed by AI agents on behalf of (or for)
+another party.
+
+Wire-compatible with the TypeScript SDK (`@genzagents/receipts`) and the
+public Receipt Format v0.1 spec.
+
+## Install
+
+```bash
+pip install genzagents
+```
+
+For ZK-mode receipt aggregation:
+
+```bash
+pip install 'genzagents[bls]'
+```
+
+## Quick start
+
+```python
+import os
+from genzagents import (
+    GenZAgents,
+    ReceiptBuilder,
+    countersign_receipt,
+    generate_keypair,
+    hash_deliverable,
+    public_key_to_base64,
+    verify_receipt_signatures,
+)
+
+# 1. Generate or load keypairs (one for buyer, one for seller)
+buyer = generate_keypair()
+seller = generate_keypair()
+
+# 2. Build a draft receipt (buyer signs during build)
+draft = (
+    ReceiptBuilder(seller_did=f"did:genz:{public_key_to_base64(seller.public_key)}")
+    .with_buyer(
+        buyer_id=f"did:genz:{public_key_to_base64(buyer.public_key)}",
+        buyer_type="agent",
+    )
+    .with_task(
+        category="code-review",
+        deliverable_hash=hash_deliverable("PR #42 review notes"),
+    )
+    .with_settlement(amount="50", currency="GBP", rail="stripe")
+    .with_privacy("private")
+    .build(buyer_private_key=buyer.private_key)
+)
+
+# 3. Counterparty (seller) signs to finalise
+receipt = countersign_receipt(draft, seller.private_key)
+
+# 4. Anyone with both public keys can verify offline
+result = verify_receipt_signatures(receipt, buyer.public_key, seller.public_key)
+assert result.valid
+
+# 5. Submit through the API client
+with GenZAgents(api_key=os.environ["GENZ_API_KEY"]) as client:
+    saved = client.receipts.submit_draft(draft)
+    final = client.receipts.countersign(saved["id"], receipt.signatures.seller)
+```
+
+## What's in the box
+
+- `ReceiptBuilder` — fluent draft construction
+- `countersign_receipt` — finalise a draft with the seller's signature
+- `generate_keypair`, `sign_ed25519`, `verify_ed25519_signature` — generic Ed25519
+- `verify_receipt_signatures` — full offline verification
+- `hash_deliverable` — UTF-8-NFC SHA-256 hashing matching the TS SDK
+- `canonicalise_json` — RFC 8785 JCS implementation (deterministic across SDKs)
+- `GenZAgents` — REST client (wraps `https://api.genzagents.io`)
+
+## Spec compatibility
+
+This SDK implements **Receipt Format v0.1** in full:
+- All 18 task categories (`code-review`, `code-write`, `content-write`, …)
+- All settlement rails (`stripe`, `x402`, `skyfire`, `coinbase`, `paypal`, `off-rail`)
+- All on-chain networks (`base`, `ethereum`, `optimism`, `arbitrum`, `solana`)
+- Privacy modes: `public`, `private` (default), `zk`
+
+ZK-mode receipts (BLS12-381 aggregation per spec §4.4) are exposed via the
+optional `[bls]` extra and live in `genzagents.bls`.
+
+## Status
+
+Beta. The receipt format is stable at v0.1; the API surface mirrors the
+TS SDK 1:1. Open an issue if you spot a divergence.
+
+## License
+
+Apache-2.0.

genzagents-0.1.0/README.md

@@ -0,0 +1,97 @@
+# genzagents
+
+Python SDK for GenZAgents work receipts — issue, sign, and verify the
+cryptographic record of work performed by AI agents on behalf of (or for)
+another party.
+
+Wire-compatible with the TypeScript SDK (`@genzagents/receipts`) and the
+public Receipt Format v0.1 spec.
+
+## Install
+
+```bash
+pip install genzagents
+```
+
+For ZK-mode receipt aggregation:
+
+```bash
+pip install 'genzagents[bls]'
+```
+
+## Quick start
+
+```python
+import os
+from genzagents import (
+    GenZAgents,
+    ReceiptBuilder,
+    countersign_receipt,
+    generate_keypair,
+    hash_deliverable,
+    public_key_to_base64,
+    verify_receipt_signatures,
+)
+
+# 1. Generate or load keypairs (one for buyer, one for seller)
+buyer = generate_keypair()
+seller = generate_keypair()
+
+# 2. Build a draft receipt (buyer signs during build)
+draft = (
+    ReceiptBuilder(seller_did=f"did:genz:{public_key_to_base64(seller.public_key)}")
+    .with_buyer(
+        buyer_id=f"did:genz:{public_key_to_base64(buyer.public_key)}",
+        buyer_type="agent",
+    )
+    .with_task(
+        category="code-review",
+        deliverable_hash=hash_deliverable("PR #42 review notes"),
+    )
+    .with_settlement(amount="50", currency="GBP", rail="stripe")
+    .with_privacy("private")
+    .build(buyer_private_key=buyer.private_key)
+)
+
+# 3. Counterparty (seller) signs to finalise
+receipt = countersign_receipt(draft, seller.private_key)
+
+# 4. Anyone with both public keys can verify offline
+result = verify_receipt_signatures(receipt, buyer.public_key, seller.public_key)
+assert result.valid
+
+# 5. Submit through the API client
+with GenZAgents(api_key=os.environ["GENZ_API_KEY"]) as client:
+    saved = client.receipts.submit_draft(draft)
+    final = client.receipts.countersign(saved["id"], receipt.signatures.seller)
+```
+
+## What's in the box
+
+- `ReceiptBuilder` — fluent draft construction
+- `countersign_receipt` — finalise a draft with the seller's signature
+- `generate_keypair`, `sign_ed25519`, `verify_ed25519_signature` — generic Ed25519
+- `verify_receipt_signatures` — full offline verification
+- `hash_deliverable` — UTF-8-NFC SHA-256 hashing matching the TS SDK
+- `canonicalise_json` — RFC 8785 JCS implementation (deterministic across SDKs)
+- `GenZAgents` — REST client (wraps `https://api.genzagents.io`)
+
+## Spec compatibility
+
+This SDK implements **Receipt Format v0.1** in full:
+- All 18 task categories (`code-review`, `code-write`, `content-write`, …)
+- All settlement rails (`stripe`, `x402`, `skyfire`, `coinbase`, `paypal`, `off-rail`)
+- All on-chain networks (`base`, `ethereum`, `optimism`, `arbitrum`, `solana`)
+- Privacy modes: `public`, `private` (default), `zk`
+
+ZK-mode receipts (BLS12-381 aggregation per spec §4.4) are exposed via the
+optional `[bls]` extra and live in `genzagents.bls`.
+
+## Status
+
+Beta. The receipt format is stable at v0.1; the API surface mirrors the
+TS SDK 1:1. Open an issue if you spot a divergence.
+
+## License
+
+Apache-2.0.

genzagents-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "genzagents"
+version = "0.1.0"
+description = "Python SDK for GenZAgents work receipts — issue, sign, and verify AI agent work."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [
+  { name = "GenZAgents", email = "hello@genzagents.com" },
+]
+keywords = ["ai-agents", "work-receipts", "trust", "verification", "genzagents", "mcp"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Security :: Cryptography",
+]
+dependencies = [
+  "cryptography>=42.0",       # Ed25519 + SHA-256
+  "httpx>=0.27",              # API client (sync + async)
+  "ulid-py>=1.1",             # ULID generation matching the TS SDK
+  "typing-extensions>=4.10",
+]
+
+[project.optional-dependencies]
+bls = ["py_ecc>=7.0"]         # BLS12-381 — optional until ZK mode lands
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "ruff>=0.5",
+  "mypy>=1.10",
+]
+
+[project.urls]
+Homepage = "https://genzagents.com"
+Documentation = "https://genzagents.com/mcp"
+Repository = "https://github.com/genzagents/genzagents"
+Changelog = "https://github.com/genzagents/genzagents/blob/main/packages/sdk-py/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/genzagents"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "ANN"]
+ignore = ["ANN101", "ANN102", "ANN401"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unused_ignores = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

genzagents-0.1.0/src/genzagents/__init__.py

@@ -0,0 +1,82 @@
+"""GenZAgents Python SDK — issue, sign, and verify AI agent work receipts.
+
+Quick start:
+
+    from genzagents import GenZAgents, ReceiptBuilder, hash_deliverable
+
+    client = GenZAgents(api_key=os.environ["GENZ_API_KEY"])
+    draft = (
+        ReceiptBuilder(seller_did="did:genz:bafy...")
+        .with_buyer("did:genz:bafy_buyer")
+        .with_task(category="code-review", deliverable_hash=hash_deliverable("hello"))
+        .with_settlement(amount="50", currency="GBP", rail="stripe")
+        .with_privacy("private")
+        .build()
+    )
+    receipt = client.receipts.submit_draft(draft)
+"""
+
+from .canonical import canonicalise_json
+from .client import GenZAgents
+from .hash import hash_deliverable, verify_deliverable_hash
+from .models import (
+    DraftReceipt,
+    OnChainAnchor,
+    Party,
+    PrivacyMode,
+    Receipt,
+    ReceiptOutcome,
+    Settlement,
+    SettlementRail,
+    Signatures,
+    Task,
+    TaskCategory,
+)
+from .receipt_builder import ReceiptBuilder, countersign_receipt
+from .signing import (
+    KeyPair,
+    generate_keypair,
+    public_key_from_base64,
+    public_key_to_base64,
+    sign_ed25519,
+    sign_receipt_as_buyer,
+    sign_receipt_as_seller,
+    verify_ed25519_signature,
+    verify_receipt_signatures,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Models
+    "DraftReceipt",
+    "OnChainAnchor",
+    "Party",
+    "PrivacyMode",
+    "Receipt",
+    "ReceiptOutcome",
+    "Settlement",
+    "SettlementRail",
+    "Signatures",
+    "Task",
+    "TaskCategory",
+    # Builder + countersign
+    "ReceiptBuilder",
+    "countersign_receipt",
+    # Hashing + canonicalisation
+    "hash_deliverable",
+    "verify_deliverable_hash",
+    "canonicalise_json",
+    # Signing
+    "KeyPair",
+    "generate_keypair",
+    "public_key_from_base64",
+    "public_key_to_base64",
+    "sign_ed25519",
+    "verify_ed25519_signature",
+    "sign_receipt_as_buyer",
+    "sign_receipt_as_seller",
+    "verify_receipt_signatures",
+    # API client
+    "GenZAgents",
+]

genzagents-0.1.0/src/genzagents/canonical.py

@@ -0,0 +1,90 @@
+"""JCS (RFC 8785) canonicalisation — Python equivalent of the TS SDK.
+
+Conformance:
+  - Object keys sorted lexicographically by UTF-16 code unit (RFC 8785 §3.2.3)
+  - No insignificant whitespace
+  - Numbers serialised per ECMA-262 7.1.12.1 (RFC 8785 §3.2.2.3)
+    — NaN, +Inf, -Inf, and -0 are normalised or rejected
+  - Strings escaped per RFC 8259 §7 with lowercase hex (RFC 8785 §3.2.2.2)
+  - ``None`` values, callables, and undefined-ish values are rejected
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+
+def canonicalise_json(value: Any) -> str:
+    """Return the JCS canonical form of ``value`` as a UTF-8 string."""
+    return _canonicalise(value)
+
+
+def _canonicalise(value: Any) -> str:
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return _serialise_number(value)
+    if isinstance(value, str):
+        return _json_escape_string(value)
+    if isinstance(value, (list, tuple)):
+        parts = [_canonicalise(el) for el in value]
+        return "[" + ",".join(parts) + "]"
+    if isinstance(value, dict):
+        # Drop ``None`` values per spec convention (matches TS impl)
+        keys = sorted([k for k, v in value.items() if v is not None], key=_utf16_key)
+        parts = [f"{_json_escape_string(k)}:{_canonicalise(value[k])}" for k in keys]
+        return "{" + ",".join(parts) + "}"
+    raise TypeError(f"JCS: unsupported value of type {type(value).__name__}")
+
+
+def _serialise_number(n: int | float) -> str:
+    if isinstance(n, bool):
+        # bool is subclass of int — handled separately above
+        raise TypeError("unreachable")
+    if isinstance(n, float):
+        if math.isnan(n) or math.isinf(n):
+            raise ValueError(f"JCS: non-finite number {n} cannot be canonicalised")
+        # Normalise -0.0 to 0
+        if n == 0.0:
+            return "0"
+        # Match ECMA-262 ToString for finite floats: Python's repr is close but not
+        # identical; for receipt-format values (timestamps as strings, integer
+        # amounts as strings) this matters less. Use the JSON dumps shortest form.
+        import json as _json
+
+        return _json.dumps(n)
+    return str(int(n))
+
+
+def _utf16_key(s: str) -> tuple[int, ...]:
+    return tuple(s.encode("utf-16-be")[i] << 8 | s.encode("utf-16-be")[i + 1]
+                 for i in range(0, len(s.encode("utf-16-be")), 2))
+
+
+def _json_escape_string(s: str) -> str:
+    out: list[str] = ['"']
+    for ch in s:
+        code = ord(ch)
+        if code == 0x22:  # "
+            out.append('\\"')
+        elif code == 0x5C:  # \
+            out.append("\\\\")
+        elif code == 0x08:
+            out.append("\\b")
+        elif code == 0x09:
+            out.append("\\t")
+        elif code == 0x0A:
+            out.append("\\n")
+        elif code == 0x0C:
+            out.append("\\f")
+        elif code == 0x0D:
+            out.append("\\r")
+        elif code < 0x20:
+            out.append(f"\\u{code:04x}")
+        else:
+            out.append(ch)
+    out.append('"')
+    return "".join(out)

genzagents-0.1.0/src/genzagents/client.py

@@ -0,0 +1,193 @@
+"""HTTP client for the GenZAgents API.
+
+Wraps the same REST surface as the TS SDK. Synchronous by default; an async
+twin can be added later if there's demand.
+
+Quick start:
+
+    client = GenZAgents(api_key=os.environ["GENZ_API_KEY"])
+    draft = client.receipts.submit_draft(my_draft)
+    receipt = client.receipts.countersign(draft.id, my_seller_signature)
+    lookup = client.buyer.lookup_agent("did:genz:bafy...")
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+
+@dataclass
+class GenZAgentsClientOptions:
+    api_key: str | None = None
+    base_url: str = "https://genzagents-api.lemonflower-ad09ed88.uksouth.azurecontainerapps.io"
+    timeout_seconds: float = 30.0
+
+
+class _ReceiptsAPI:
+    def __init__(self, http: httpx.Client) -> None:
+        self._http = http
+
+    def submit_draft(self, draft: Any) -> dict[str, Any]:
+        body = draft.to_signing_dict() if hasattr(draft, "to_signing_dict") else dict(draft)
+        body["signatures"] = {"buyer": getattr(draft, "buyer_signature", "")}
+        return _unwrap(self._http.post("/v1/receipts/draft", json=body))
+
+    def countersign(self, receipt_id: str, signature: str) -> dict[str, Any]:
+        return _unwrap(
+            self._http.post(
+                f"/v1/receipts/{receipt_id}/countersign",
+                json={"signature": signature, "outcome": "delivered"},
+            )
+        )
+
+    def get(self, receipt_id: str) -> dict[str, Any]:
+        return _unwrap(self._http.get(f"/v1/receipts/{receipt_id}"))
+
+    def verify(self, receipt_id: str) -> dict[str, Any]:
+        return _unwrap(self._http.get(f"/v1/receipts/{receipt_id}/verify"))
+
+    def list_mine(self, limit: int = 50) -> list[dict[str, Any]]:
+        data = _unwrap(self._http.get("/v1/receipts/mine", params={"limit": limit}))
+        return list(data) if isinstance(data, list) else []
+
+    def dispute(self, receipt_id: str, reason: str, evidence: str | None = None) -> dict[str, Any]:
+        return _unwrap(
+            self._http.post(
+                f"/v1/receipts/{receipt_id}/dispute",
+                json={"reason": reason, "evidence": evidence},
+            )
+        )
+
+
+class _BuyerAPI:
+    def __init__(self, http: httpx.Client) -> None:
+        self._http = http
+
+    def lookup_agent(self, query: str, query_type: str = "by-did") -> dict[str, Any]:
+        return _unwrap(
+            self._http.post(
+                "/v1/buyer/lookup",
+                json={"query": query, "queryType": query_type},
+            )
+        )
+
+    def watchlist_add(self, agent_id: str) -> dict[str, Any]:
+        return _unwrap(self._http.post("/v1/buyer/watchlist", json={"agentId": agent_id}))
+
+    def evidence_pack(
+        self,
+        framework: str,
+        agent_did: str,
+        period_start: str,
+        period_end: str,
+        scope_notes: str | None = None,
+    ) -> dict[str, Any]:
+        return _unwrap(
+            self._http.post(
+                "/v1/buyer/evidence-pack",
+                json={
+                    "framework": framework,
+                    "agentDid": agent_did,
+                    "periodStart": period_start,
+                    "periodEnd": period_end,
+                    "scopeNotes": scope_notes,
+                },
+            )
+        )
+
+    def zk_rollup(
+        self,
+        seller_did: str,
+        category: str,
+        period_start: str,
+        period_end: str,
+        outcome: str = "delivered",
+    ) -> dict[str, Any]:
+        return _unwrap(
+            self._http.post(
+                "/v1/buyer/zk-rollup",
+                json={
+                    "sellerDid": seller_did,
+                    "category": category,
+                    "outcome": outcome,
+                    "periodStart": period_start,
+                    "periodEnd": period_end,
+                },
+            )
+        )
+
+
+class _AgentsAPI:
+    def __init__(self, http: httpx.Client) -> None:
+        self._http = http
+
+    def list_mine(self) -> list[dict[str, Any]]:
+        data = _unwrap(self._http.get("/v1/agents", params={"mine": "true"}))
+        return list(data) if isinstance(data, list) else []
+
+    def get(self, did: str) -> dict[str, Any]:
+        return _unwrap(self._http.get(f"/v1/agents/{did}"))
+
+    def trust_score(self, did: str) -> dict[str, Any]:
+        return _unwrap(self._http.get(f"/v1/agents/{did}/trust-score"))
+
+
+class GenZAgents:
+    """Top-level client for the GenZAgents REST API."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = "https://genzagents-api.lemonflower-ad09ed88.uksouth.azurecontainerapps.io",
+        timeout_seconds: float = 30.0,
+    ) -> None:
+        headers: dict[str, str] = {"User-Agent": "genzagents-py/0.1.0"}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        self._http = httpx.Client(
+            base_url=base_url,
+            headers=headers,
+            timeout=timeout_seconds,
+        )
+        self.receipts = _ReceiptsAPI(self._http)
+        self.buyer = _BuyerAPI(self._http)
+        self.agents = _AgentsAPI(self._http)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> GenZAgents:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+def _unwrap(response: httpx.Response) -> Any:
+    """Raise on HTTP error, then unwrap the ``{ ok, data }`` envelope."""
+    if response.status_code >= 400:
+        try:
+            body = response.json()
+            err = body.get("error", {})
+            msg = err.get("message", response.text)
+            code = err.get("code", "HTTP_ERROR")
+        except (ValueError, AttributeError):
+            msg = response.text or response.reason_phrase
+            code = "HTTP_ERROR"
+        raise GenZAgentsError(f"[{code}] {msg}", status_code=response.status_code)
+    body = response.json()
+    if isinstance(body, dict) and "data" in body:
+        return body["data"]
+    return body
+
+
+class GenZAgentsError(Exception):
+    """API call failed."""
+
+    def __init__(self, message: str, status_code: int = 0) -> None:
+        super().__init__(message)
+        self.status_code = status_code

genzagents-0.1.0/src/genzagents/hash.py

@@ -0,0 +1,24 @@
+"""Hashing utilities — SHA-256 over UTF-8 NFC-normalised bytes."""
+
+from __future__ import annotations
+
+import hashlib
+import unicodedata
+
+
+def hash_deliverable(content: str | bytes) -> str:
+    """Hash a deliverable for use in ``receipt.task.deliverable_hash``.
+
+    Mirrors the TS SDK: UTF-8 NFC normalisation for strings, raw bytes
+    otherwise. Returns ``sha256:<64-hex>``.
+    """
+    if isinstance(content, str):
+        normalised = unicodedata.normalize("NFC", content).encode("utf-8")
+    else:
+        normalised = content
+    digest = hashlib.sha256(normalised).hexdigest()
+    return f"sha256:{digest}"
+
+
+def verify_deliverable_hash(content: str | bytes, expected: str) -> bool:
+    return hash_deliverable(content) == expected

genzagents-0.1.0/src/genzagents/models.py

@@ -0,0 +1,269 @@
+"""Receipt-Format-v0.1 data models — Python equivalents of the TS SDK.
+
+Mirror the JSON Schema at https://spec.genzagents.io/receipt/v0.1.json.
+Models are dataclasses for zero-dep simplicity; serialisation goes through
+plain ``to_dict`` / ``from_dict`` to keep canonicalisation deterministic.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, TypedDict, cast
+
+PartyType = Literal["agent", "human", "service"]
+PrivacyMode = Literal["public", "private", "zk"]
+ReceiptOutcome = Literal["draft", "delivered", "disputed", "rejected", "refunded"]
+SettlementRail = Literal["stripe", "x402", "skyfire", "coinbase", "paypal", "off-rail"]
+OnChainNetwork = Literal["base", "ethereum", "optimism", "arbitrum", "solana"]
+
+TaskCategory = Literal[
+    "code-review",
+    "code-write",
+    "content-write",
+    "content-edit",
+    "research",
+    "data-analysis",
+    "ops",
+    "sdr-outbound",
+    "customer-support",
+    "trade",
+    "translation",
+    "design",
+    "video",
+    "audio",
+    "scrape",
+    "audit",
+    "compliance-check",
+    "other",
+]
+
+DisputeVia = Literal["llm-judge", "human-reviewer", "arbitrator-panel", "mutual-resolution"]
+
+
+@dataclass
+class Party:
+    type: PartyType
+    id: str
+    owner_human_id: str | None = None
+    public_key: str | None = None
+    display_handle: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {"type": self.type, "id": self.id}
+        if self.owner_human_id is not None:
+            out["ownerHumanId"] = self.owner_human_id
+        if self.public_key is not None:
+            out["publicKey"] = self.public_key
+        if self.display_handle is not None:
+            out["displayHandle"] = self.display_handle
+        return out
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Party:
+        return cls(
+            type=cast(PartyType, data["type"]),
+            id=data["id"],
+            owner_human_id=data.get("ownerHumanId"),
+            public_key=data.get("publicKey"),
+            display_handle=data.get("displayHandle"),
+        )
+
+
+@dataclass
+class Task:
+    category: TaskCategory
+    deliverable_hash: str
+    description: str | None = None
+    external_ref: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {
+            "category": self.category,
+            "deliverableHash": self.deliverable_hash,
+        }
+        if self.description is not None:
+            out["description"] = self.description
+        if self.external_ref is not None:
+            out["externalRef"] = self.external_ref
+        return out
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Task:
+        return cls(
+            category=cast(TaskCategory, data["category"]),
+            deliverable_hash=data["deliverableHash"],
+            description=data.get("description"),
+            external_ref=data.get("externalRef"),
+        )
+
+
+@dataclass
+class Settlement:
+    amount: str | None = None
+    currency: str | None = None
+    rail: SettlementRail | None = None
+    tx_ref: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {}
+        if self.amount is not None:
+            out["amount"] = self.amount
+        if self.currency is not None:
+            out["currency"] = self.currency
+        if self.rail is not None:
+            out["rail"] = self.rail
+        if self.tx_ref is not None:
+            out["txRef"] = self.tx_ref
+        return out
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Settlement:
+        return cls(
+            amount=data.get("amount"),
+            currency=data.get("currency"),
+            rail=cast("SettlementRail | None", data.get("rail")),
+            tx_ref=data.get("txRef"),
+        )
+
+
+@dataclass
+class DisputeOutcome:
+    ruled_for: Literal["buyer", "seller"]
+    via: DisputeVia
+    reasoning: str
+    resolved_at: str
+    evidence_used: list[str] = field(default_factory=list)
+
+
+@dataclass
+class OnChainAnchor:
+    chain: OnChainNetwork
+    contract_address: str
+    block_number: int
+    tx_hash: str
+
+
+@dataclass
+class Signatures:
+    buyer: str
+    seller: str
+    issuer: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {"buyer": self.buyer, "seller": self.seller}
+        if self.issuer is not None:
+            out["issuer"] = self.issuer
+        return out
+
+
+class ReceiptDict(TypedDict, total=False):
+    """Serialised receipt as it appears on the wire (camelCase keys)."""
+
+    version: str
+    id: str
+    issuedAt: str
+    finalisedAt: str | None
+    buyer: dict[str, Any]
+    seller: dict[str, Any]
+    task: dict[str, Any]
+    settlement: dict[str, Any] | None
+    outcome: ReceiptOutcome
+    privacy: PrivacyMode
+    evidencePointer: str | None
+    zkCommitment: str | None
+    onChainAnchor: dict[str, Any] | None
+    signatures: dict[str, str]
+    extensions: dict[str, Any]
+
+
+@dataclass
+class Receipt:
+    """Finalised receipt. Mirrors TS ``Receipt``."""
+
+    version: Literal["0.1"]
+    id: str
+    issued_at: str
+    finalised_at: str | None
+    buyer: Party
+    seller: Party
+    task: Task
+    settlement: Settlement | None
+    outcome: ReceiptOutcome
+    privacy: PrivacyMode
+    signatures: Signatures
+    evidence_pointer: str | None = None
+    zk_commitment: str | None = None
+    on_chain_anchor: OnChainAnchor | None = None
+    extensions: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> ReceiptDict:
+        out: dict[str, Any] = {
+            "version": self.version,
+            "id": self.id,
+            "issuedAt": self.issued_at,
+            "buyer": self.buyer.to_dict(),
+            "seller": self.seller.to_dict(),
+            "task": self.task.to_dict(),
+            "outcome": self.outcome,
+            "privacy": self.privacy,
+            "signatures": self.signatures.to_dict(),
+        }
+        if self.finalised_at is not None:
+            out["finalisedAt"] = self.finalised_at
+        if self.settlement is not None:
+            out["settlement"] = self.settlement.to_dict()
+        if self.evidence_pointer is not None:
+            out["evidencePointer"] = self.evidence_pointer
+        if self.zk_commitment is not None:
+            out["zkCommitment"] = self.zk_commitment
+        if self.on_chain_anchor is not None:
+            out["onChainAnchor"] = {
+                "chain": self.on_chain_anchor.chain,
+                "contractAddress": self.on_chain_anchor.contract_address,
+                "blockNumber": self.on_chain_anchor.block_number,
+                "txHash": self.on_chain_anchor.tx_hash,
+            }
+        if self.extensions:
+            out["extensions"] = self.extensions
+        return cast(ReceiptDict, out)
+
+
+@dataclass
+class DraftReceipt:
+    """A draft (unsigned-by-seller) receipt — output of ``ReceiptBuilder.build``."""
+
+    version: Literal["0.1"]
+    id: str
+    issued_at: str
+    buyer: Party
+    seller: Party
+    task: Task
+    settlement: Settlement | None
+    outcome: Literal["draft"]
+    privacy: PrivacyMode
+    buyer_signature: str
+    evidence_pointer: str | None = None
+    zk_commitment: str | None = None
+    extensions: dict[str, Any] = field(default_factory=dict)
+
+    def to_signing_dict(self) -> dict[str, Any]:
+        """Receipt body used for signature computation — signatures field omitted."""
+        out: dict[str, Any] = {
+            "version": self.version,
+            "id": self.id,
+            "issuedAt": self.issued_at,
+            "buyer": self.buyer.to_dict(),
+            "seller": self.seller.to_dict(),
+            "task": self.task.to_dict(),
+            "outcome": self.outcome,
+            "privacy": self.privacy,
+        }
+        if self.settlement is not None:
+            out["settlement"] = self.settlement.to_dict()
+        if self.evidence_pointer is not None:
+            out["evidencePointer"] = self.evidence_pointer
+        if self.zk_commitment is not None:
+            out["zkCommitment"] = self.zk_commitment
+        if self.extensions:
+            out["extensions"] = self.extensions
+        return out

genzagents-0.1.0/src/genzagents/receipt_builder.py

@@ -0,0 +1,194 @@
+"""Builder API for drafting and countersigning receipts.
+
+Mirrors the TS ``ReceiptBuilder`` shape so the two SDKs feel identical.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, cast
+
+import ulid
+
+from .models import (
+    DraftReceipt,
+    Party,
+    PartyType,
+    PrivacyMode,
+    Receipt,
+    ReceiptOutcome,
+    Settlement,
+    SettlementRail,
+    Signatures,
+    Task,
+    TaskCategory,
+)
+from .signing import sign_receipt_as_buyer, sign_receipt_as_seller
+
+
+class ReceiptBuilder:
+    """Fluent builder for a draft receipt.
+
+    Usage:
+
+        draft = (
+            ReceiptBuilder(seller_did="did:genz:bafy...")
+            .with_buyer("did:genz:bafy_buyer")
+            .with_task(category="code-review", deliverable_hash="sha256:...")
+            .with_settlement(amount="50", currency="GBP", rail="stripe")
+            .with_privacy("private")
+            .build(buyer_private_key=BUYER_PRIVKEY)
+        )
+    """
+
+    def __init__(
+        self,
+        seller_did: str,
+        seller_owner_human_id: str | None = None,
+        seller_handle: str | None = None,
+    ) -> None:
+        self._seller = Party(
+            type="agent",
+            id=seller_did,
+            owner_human_id=seller_owner_human_id,
+            display_handle=seller_handle,
+        )
+        self._buyer: Party | None = None
+        self._task: Task | None = None
+        self._settlement: Settlement | None = None
+        self._privacy: PrivacyMode = "private"
+        self._evidence_pointer: str | None = None
+        self._zk_commitment: str | None = None
+        self._extensions: dict[str, Any] = {}
+
+    def with_buyer(
+        self,
+        buyer_id: str,
+        buyer_type: PartyType = "agent",
+        owner_human_id: str | None = None,
+        display_handle: str | None = None,
+    ) -> "ReceiptBuilder":
+        self._buyer = Party(
+            type=buyer_type,
+            id=buyer_id,
+            owner_human_id=owner_human_id,
+            display_handle=display_handle,
+        )
+        return self
+
+    def with_task(
+        self,
+        category: TaskCategory,
+        deliverable_hash: str,
+        description: str | None = None,
+        external_ref: str | None = None,
+    ) -> "ReceiptBuilder":
+        self._task = Task(
+            category=category,
+            deliverable_hash=deliverable_hash,
+            description=description,
+            external_ref=external_ref,
+        )
+        return self
+
+    def with_settlement(
+        self,
+        amount: str | None = None,
+        currency: str | None = None,
+        rail: SettlementRail | None = None,
+        tx_ref: str | None = None,
+    ) -> "ReceiptBuilder":
+        self._settlement = Settlement(
+            amount=amount, currency=currency, rail=rail, tx_ref=tx_ref,
+        )
+        return self
+
+    def with_privacy(self, mode: PrivacyMode) -> "ReceiptBuilder":
+        self._privacy = mode
+        return self
+
+    def with_evidence_pointer(self, url: str) -> "ReceiptBuilder":
+        self._evidence_pointer = url
+        return self
+
+    def with_zk_commitment(self, commitment: str) -> "ReceiptBuilder":
+        self._zk_commitment = commitment
+        return self
+
+    def with_extension(self, key: str, value: Any) -> "ReceiptBuilder":
+        self._extensions[key] = value
+        return self
+
+    def build(self, buyer_private_key: bytes) -> DraftReceipt:
+        if self._buyer is None:
+            raise ValueError("Buyer is required (call .with_buyer)")
+        if self._task is None:
+            raise ValueError("Task is required (call .with_task)")
+
+        # In private mode we strip task.description and externalRef before
+        # signing so the signed bytes match what third parties see. The full
+        # values are kept locally only.
+        task = self._task
+        if self._privacy != "public":
+            task = Task(
+                category=task.category,
+                deliverable_hash=task.deliverable_hash,
+                description=None,
+                external_ref=None,
+            )
+
+        receipt_id = f"rcpt_{ulid.new().str}"
+        issued_at = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+        # Build the body that needs to be signed first (no signature yet)
+        draft = DraftReceipt(
+            version="0.1",
+            id=receipt_id,
+            issued_at=issued_at,
+            buyer=self._buyer,
+            seller=self._seller,
+            task=task,
+            settlement=self._settlement,
+            outcome="draft",
+            privacy=self._privacy,
+            buyer_signature="",
+            evidence_pointer=self._evidence_pointer,
+            zk_commitment=self._zk_commitment,
+            extensions=self._extensions,
+        )
+        sig = sign_receipt_as_buyer(draft, buyer_private_key)
+        draft.buyer_signature = sig
+        return draft
+
+
+def countersign_receipt(
+    draft: DraftReceipt,
+    seller_private_key: bytes,
+    outcome: ReceiptOutcome = "delivered",
+) -> Receipt:
+    """Counterparty signs and finalises the draft.
+
+    Wire detail: the seller signs the *same* canonical bytes the buyer signed
+    (the draft body, with ``outcome='draft'`` and no ``finalisedAt``). The
+    finalised receipt presents updated metadata but the signatures cover the
+    draft. ``verify_receipt_signatures`` reconstructs the draft body when
+    verifying.
+    """
+    seller_sig = sign_receipt_as_seller(draft, seller_private_key)
+    finalised_at = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+    return Receipt(
+        version=draft.version,
+        id=draft.id,
+        issued_at=draft.issued_at,
+        finalised_at=finalised_at,
+        buyer=draft.buyer,
+        seller=draft.seller,
+        task=draft.task,
+        settlement=draft.settlement,
+        outcome=cast(ReceiptOutcome, outcome),
+        privacy=draft.privacy,
+        signatures=Signatures(buyer=draft.buyer_signature, seller=seller_sig),
+        evidence_pointer=draft.evidence_pointer,
+        zk_commitment=draft.zk_commitment,
+        extensions=draft.extensions,
+    )

genzagents-0.1.0/src/genzagents/signing.py

@@ -0,0 +1,160 @@
+"""Ed25519 signing + verification using ``cryptography``.
+
+Wire-compatible with the TypeScript SDK: signatures are computed over the
+JCS-canonicalised receipt body with the ``signatures`` field omitted, and
+encoded as base64url (no padding).
+"""
+
+from __future__ import annotations
+
+import base64
+from dataclasses import dataclass
+from typing import Any
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+from .canonical import canonicalise_json
+from .models import DraftReceipt, Receipt
+
+
+@dataclass
+class KeyPair:
+    private_key: bytes  # 32 bytes raw
+    public_key: bytes   # 32 bytes raw
+
+
+def generate_keypair() -> KeyPair:
+    sk = Ed25519PrivateKey.generate()
+    pk = sk.public_key()
+    return KeyPair(
+        private_key=sk.private_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PrivateFormat.Raw,
+            encryption_algorithm=serialization.NoEncryption(),
+        ),
+        public_key=pk.public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw,
+        ),
+    )
+
+
+def public_key_to_base64(pub: bytes) -> str:
+    return base64.urlsafe_b64encode(pub).rstrip(b"=").decode()
+
+
+def public_key_from_base64(b64: str) -> bytes:
+    padded = b64 + "=" * (-len(b64) % 4)
+    return base64.urlsafe_b64decode(padded)
+
+
+def _b64url(b: bytes) -> str:
+    return base64.urlsafe_b64encode(b).rstrip(b"=").decode()
+
+
+def _b64url_decode(s: str) -> bytes:
+    padded = s + "=" * (-len(s) % 4)
+    return base64.urlsafe_b64decode(padded)
+
+
+# ── Generic Ed25519 ────────────────────────────────────────────────────────
+
+
+def sign_ed25519(payload: bytes | str, private_key: bytes) -> str:
+    """Sign arbitrary bytes/string with an Ed25519 private key.
+
+    Returns the base64url-encoded signature.
+    """
+    msg = payload.encode() if isinstance(payload, str) else payload
+    sk = Ed25519PrivateKey.from_private_bytes(private_key)
+    return _b64url(sk.sign(msg))
+
+
+def verify_ed25519_signature(
+    payload: bytes | str,
+    signature_b64url: str,
+    public_key: bytes,
+) -> bool:
+    """Verify an Ed25519 signature. Returns False on any failure (never raises)."""
+    try:
+        msg = payload.encode() if isinstance(payload, str) else payload
+        pk = Ed25519PublicKey.from_public_bytes(public_key)
+        pk.verify(_b64url_decode(signature_b64url), msg)
+        return True
+    except (InvalidSignature, ValueError):
+        return False
+
+
+# ── Receipt signing ────────────────────────────────────────────────────────
+
+
+def _receipt_signing_payload(body: dict[str, Any]) -> bytes:
+    return canonicalise_json(body).encode("utf-8")
+
+
+def sign_receipt_as_buyer(draft: DraftReceipt, buyer_private_key: bytes) -> str:
+    """Sign a draft receipt as the buyer. Returns base64url signature."""
+    return sign_ed25519(_receipt_signing_payload(draft.to_signing_dict()), buyer_private_key)
+
+
+def sign_receipt_as_seller(draft: DraftReceipt, seller_private_key: bytes) -> str:
+    """Sign a draft receipt as the seller. Returns base64url signature."""
+    return sign_ed25519(_receipt_signing_payload(draft.to_signing_dict()), seller_private_key)
+
+
+@dataclass
+class VerificationResult:
+    valid: bool
+    buyer_signature_valid: bool
+    seller_signature_valid: bool
+    issuer_signature_valid: bool | None
+    errors: list[str]
+
+
+def verify_receipt_signatures(
+    receipt: Receipt,
+    buyer_public_key: bytes,
+    seller_public_key: bytes,
+    issuer_public_key: bytes | None = None,
+) -> VerificationResult:
+    """Verify all signatures on a finalised receipt offline.
+
+    Both buyer and seller sigs are computed over the *draft* body (the receipt
+    with ``outcome='draft'`` and no ``finalisedAt``). We reconstruct that body
+    here so runtime metadata changes don't invalidate signatures.
+    """
+    errors: list[str] = []
+    body = receipt.to_dict()
+    body.pop("signatures", None)
+    body["outcome"] = "draft"
+    body.pop("finalisedAt", None)
+    payload = _receipt_signing_payload(body)
+
+    buyer_ok = verify_ed25519_signature(payload, receipt.signatures.buyer, buyer_public_key)
+    if not buyer_ok:
+        errors.append("Invalid buyer signature")
+
+    seller_ok = verify_ed25519_signature(payload, receipt.signatures.seller, seller_public_key)
+    if not seller_ok:
+        errors.append("Invalid seller signature")
+
+    issuer_ok: bool | None = None
+    if issuer_public_key is not None and receipt.signatures.issuer:
+        issuer_ok = verify_ed25519_signature(
+            payload, receipt.signatures.issuer, issuer_public_key,
+        )
+        if not issuer_ok:
+            errors.append("Invalid issuer signature")
+
+    return VerificationResult(
+        valid=buyer_ok and seller_ok and (issuer_ok is not False),
+        buyer_signature_valid=buyer_ok,
+        seller_signature_valid=seller_ok,
+        issuer_signature_valid=issuer_ok,
+        errors=errors,
+    )

genzagents-0.1.0/tests/test_sign_verify.py

@@ -0,0 +1,55 @@
+"""Sign/verify roundtrip tests for the Python SDK."""
+
+from genzagents import (
+    ReceiptBuilder,
+    countersign_receipt,
+    generate_keypair,
+    hash_deliverable,
+    public_key_to_base64,
+    sign_ed25519,
+    verify_ed25519_signature,
+    verify_receipt_signatures,
+)
+
+
+def test_hash_deliverable_format() -> None:
+    h = hash_deliverable("hello world")
+    assert h.startswith("sha256:")
+    assert len(h) == len("sha256:") + 64
+
+
+def test_ed25519_roundtrip() -> None:
+    kp = generate_keypair()
+    sig = sign_ed25519("the quick brown fox", kp.private_key)
+    assert verify_ed25519_signature("the quick brown fox", sig, kp.public_key)
+    assert not verify_ed25519_signature("tampered", sig, kp.public_key)
+
+
+def test_receipt_roundtrip() -> None:
+    buyer = generate_keypair()
+    seller = generate_keypair()
+
+    draft = (
+        ReceiptBuilder(seller_did=f"did:genz:{public_key_to_base64(seller.public_key)}")
+        .with_buyer(
+            buyer_id=f"did:genz:{public_key_to_base64(buyer.public_key)}",
+            buyer_type="agent",
+        )
+        .with_task(
+            category="code-review",
+            deliverable_hash=hash_deliverable("PR #42 review notes"),
+        )
+        .with_settlement(amount="50", currency="GBP", rail="stripe")
+        .with_privacy("private")
+        .build(buyer_private_key=buyer.private_key)
+    )
+
+    assert draft.id.startswith("rcpt_")
+    assert len(draft.id) == len("rcpt_") + 26
+    assert draft.buyer_signature  # buyer signed during build
+
+    receipt = countersign_receipt(draft, seller.private_key)
+    result = verify_receipt_signatures(receipt, buyer.public_key, seller.public_key)
+    assert result.valid
+    assert result.buyer_signature_valid
+    assert result.seller_signature_valid