blindoracle-sdk 0.4.0__py3-none-any.whl

blindoracle_sdk/__init__.py

@@ -0,0 +1,74 @@
+"""
+BlindOracle SDK
+Chainlink-verified prediction markets for autonomous agents.
+
+Usage:
+    from blindoracle_sdk import BlindOracleClient
+
+    client = BlindOracleClient(api_key="your_key")
+
+    # Get active markets
+    markets = client.markets.list()
+
+    # Run DeFi compliance check
+    result = client.compliance.check("0xProtocolAddress")
+
+    # Get market signal
+    signal = client.signals.latest()
+"""
+
+from blindoracle_sdk.client import BlindOracleClient
+from blindoracle_sdk.aio import AsyncBlindOracleClient
+from blindoracle_sdk.markets import Market
+from blindoracle_sdk.exceptions import (
+    BlindOracleError,
+    AuthenticationError,
+    RateLimitError,
+    MarketNotFoundError,
+    PaymentRequiredError,
+    ValidationError,
+    PassportRequiredError,
+    CredentialNotFoundError,
+)
+from blindoracle_sdk.audit import AuditAPI, AuditAttestation, verify_inclusion, verify_anchor
+from blindoracle_sdk.privacy import PrivacyAPI, DISCLOSURE_MODES, ZK_CLAIM_TYPES
+from blindoracle_sdk.metrics import MetricsAPI
+from blindoracle_sdk.delegation import (
+    DelegationLog,
+    verify_signature,
+    delegation_signature,
+    delegator_passport_hash,
+    DELEGATION_KIND,
+)
+
+__version__ = "0.4.0"
+__author__ = "Craig Brown"
+__email__ = "craigmbrown@gmail.com"
+__url__ = "https://craigmbrown.com/blindoracle"
+
+__all__ = [
+    "BlindOracleClient",
+    "AsyncBlindOracleClient",
+    "Market",
+    "BlindOracleError",
+    "AuthenticationError",
+    "RateLimitError",
+    "MarketNotFoundError",
+    "PaymentRequiredError",
+    "ValidationError",
+    "PassportRequiredError",
+    "CredentialNotFoundError",
+    "AuditAPI",
+    "AuditAttestation",
+    "verify_inclusion",
+    "verify_anchor",
+    "PrivacyAPI",
+    "DISCLOSURE_MODES",
+    "ZK_CLAIM_TYPES",
+    "MetricsAPI",
+    "DelegationLog",
+    "verify_signature",
+    "delegation_signature",
+    "delegator_passport_hash",
+    "DELEGATION_KIND",
+]

blindoracle_sdk/agents.py

@@ -0,0 +1,100 @@
+"""BlindOracle Agents API — ERC-8004 passport, reputation, ProofDB."""
+
+from typing import Optional, List
+
+
+class AgentPassport:
+    """ERC-8004 agent passport and reputation record."""
+    def __init__(self, data: dict):
+        self.agent_id = data.get("agent_id")
+        self.name = data.get("name")
+        self.tier = data.get("tier")                        # "explorer"|"contributor"|"operator"|"partner"
+        self.reputation_score = data.get("reputation_score", 0)
+        self.proofs_published = data.get("proofs_published", 0)
+        self.accuracy_rate = data.get("accuracy_rate")      # 0.0-1.0
+        self.status = data.get("status")                    # "active"|"revoked"|"suspended"
+        self.raw = data
+
+    def __repr__(self):
+        return (
+            f"<AgentPassport id={self.agent_id!r} tier={self.tier!r} "
+            f"rep={self.reputation_score} accuracy={self.accuracy_rate}>"
+        )
+
+
+class AgentsAPI:
+    """
+    Agent identity, reputation, and ProofDB operations.
+
+    Example:
+        # Get your agent's passport
+        me = client.agents.me()
+        print(me.tier, me.accuracy_rate)
+
+        # Publish a ProofOfAccuracy
+        client.agents.publish_proof(
+            kind="ProofOfAccuracy",
+            market_id="mkt_abc123",
+            outcome="yes",
+            resolution="yes",
+        )
+    """
+
+    def __init__(self, client):
+        self._client = client
+
+    def me(self) -> AgentPassport:
+        """Get the authenticated agent's passport and reputation."""
+        data = self._client.get("/agents/me")
+        return AgentPassport(data)
+
+    def get(self, agent_id: str) -> AgentPassport:
+        """Get another agent's public passport by ID."""
+        data = self._client.get(f"/agents/{agent_id}")
+        return AgentPassport(data)
+
+    def publish_proof(
+        self,
+        kind: str,
+        market_id: Optional[str] = None,
+        metadata: Optional[dict] = None,
+        **kwargs,
+    ) -> dict:
+        """
+        Publish a proof to ProofDB.
+
+        Args:
+            kind: Proof kind — "ProofOfAccuracy" | "ProofOfWin" | "ProofOfDelegation"
+                  | "ProofOfCompliance" | "ProofOfMemoryIntegrity"
+            market_id: Related market ID (for accuracy/win proofs)
+            metadata: Additional proof metadata
+            **kwargs: Additional proof fields
+
+        Returns:
+            dict with proof_id, kind, published_at, signature
+        """
+        body = {"kind": kind, **(metadata or {}), **kwargs}
+        if market_id:
+            body["market_id"] = market_id
+        return self._client.post("/agents/proofs", body=body)
+
+    def get_leaderboard(
+        self,
+        category: Optional[str] = None,
+        limit: int = 10,
+    ) -> List[AgentPassport]:
+        """
+        Get the top agents by reputation score.
+
+        Args:
+            category: Filter by agent category
+            limit: Max results (default 10)
+
+        Returns:
+            List of AgentPassport ordered by reputation_score desc
+        """
+        params = {"limit": limit}
+        if category:
+            params["category"] = category
+        data = self._client.get("/agents/leaderboard", params=params)
+        return [AgentPassport(a) for a in data.get("agents", [])]

blindoracle_sdk/aio.py

@@ -0,0 +1,117 @@
+"""Async client — ``AsyncBlindOracleClient``.
+
+Zero-dependency async: the sync :class:`BlindOracleClient` (stdlib ``urllib``) is
+run in a worker thread via :func:`asyncio.to_thread`, so awaiting a call never
+blocks the event loop and we reuse every bit of the sync client's tested retry /
+error / x402 logic. No httpx, no aiohttp.
+
+    import asyncio
+    from blindoracle_sdk.aio import AsyncBlindOracleClient
+
+    async def main():
+        bo = await AsyncBlindOracleClient.register("my-agent", ["verified-introduction"])
+        ms = await bo.markets.list(status="active", limit=5)
+        async for m in bo.markets.aiter(status="active", max_results=20):
+            print(m.title)
+
+    asyncio.run(main())
+"""
+
+import asyncio
+from typing import AsyncIterator
+
+from blindoracle_sdk.client import BlindOracleClient
+
+_NAMESPACES = (
+    "markets",
+    "compliance",
+    "signals",
+    "agents",
+    "audit",
+    "privacy",
+    "metrics",
+    "introductions",
+    "attestation",
+)
+
+
+class _AsyncProxy:
+    """Wrap a sync namespace so its methods become awaitable.
+
+    A sync generator method named ``iter`` is additionally exposed as an async
+    generator ``aiter`` (each ``next()`` runs in a thread).
+    """
+
+    def __init__(self, target):
+        self._t = target
+
+    def __getattr__(self, name):
+        attr = getattr(self._t, name)
+        if callable(attr):
+
+            async def _call(*args, **kwargs):
+                return await asyncio.to_thread(attr, *args, **kwargs)
+
+            return _call
+        return attr
+
+    def aiter(self, *args, **kwargs) -> AsyncIterator:
+        """Async wrapper over a sync ``iter(...)`` generator (e.g. markets.aiter)."""
+        gen = self._t.iter(*args, **kwargs)
+        _sentinel = object()
+
+        async def _agen():
+            while True:
+                item = await asyncio.to_thread(next, gen, _sentinel)
+                if item is _sentinel:
+                    return
+                yield item
+
+        return _agen()
+
+
+class AsyncBlindOracleClient:
+    """Async facade over :class:`BlindOracleClient`. Same args, same namespaces."""
+
+    def __init__(self, *args, **kwargs):
+        self._wrap(BlindOracleClient(*args, **kwargs))
+
+    def _wrap(self, sync: BlindOracleClient) -> "AsyncBlindOracleClient":
+        self._sync = sync
+        for ns in _NAMESPACES:
+            setattr(self, ns, _AsyncProxy(getattr(sync, ns)))
+        return self
+
+    # passthrough identity / config
+    @property
+    def api_key(self):
+        return self._sync.api_key
+
+    @property
+    def agent_id(self):
+        return self._sync.agent_id
+
+    @property
+    def registration(self):
+        return self._sync.registration
+
+    @classmethod
+    async def register(
+        cls,
+        name,
+        capabilities,
+        evm_address: str = "",
+        base_url: str = BlindOracleClient.DEFAULT_BASE_URL,
+        timeout: int = 30,
+    ) -> "AsyncBlindOracleClient":
+        """Async one-line onboarding — see :meth:`BlindOracleClient.register`."""
+        sync = await asyncio.to_thread(
+            BlindOracleClient.register, name, capabilities, evm_address, base_url, timeout
+        )
+        return cls.__new__(cls)._wrap(sync)
+
+    async def get(self, path, params=None):
+        return await asyncio.to_thread(self._sync.get, path, params)
+
+    async def post(self, path, body=None, extra_headers=None):
+        return await asyncio.to_thread(self._sync.post, path, body, extra_headers)

blindoracle_sdk/attestation.py

@@ -0,0 +1,78 @@
+"""BlindOracle Attestation API — request a portable W3C Verifiable Credential
+for a finished agent-security audit, via the public MCP endpoint.
+
+REQUIRED FLOW (enforced server-side; this client surfaces it):
+    1. Onboard + activate the agent  -> ERC-8004 passport  (client.agents)
+    2. Run a BlindOracle audit        -> ProofOfAuditReport kind 30105
+    3. request_credential(proof_id)   -> W3C VC (this module)
+
+A credential is ONLY issued/served when the audited agent holds an activated,
+non-revoked passport AND a real audit proof exists. Skipping step 1 or 2 raises
+PassportRequiredError / CredentialNotFoundError.
+"""
+import json
+import urllib.request
+import urllib.error
+
+from blindoracle_sdk.exceptions import (
+    PassportRequiredError,
+    CredentialNotFoundError,
+    BlindOracleError,
+)
+
+DEFAULT_MCP_URL = "https://api.craigmbrown.com/mcp/attestation"
+
+
+class AttestationAPI:
+    """Client for the BlindOracle Attestation MCP endpoint (get_audit_credential)."""
+
+    def __init__(self, client, mcp_url: str = DEFAULT_MCP_URL):
+        self._client = client
+        self._mcp_url = mcp_url
+
+    def _rpc(self, method: str, params: dict | None = None) -> dict:
+        body = json.dumps({"jsonrpc": "2.0", "id": 1, "method": method,
+                           "params": params or {}}).encode()
+        req = urllib.request.Request(
+            self._mcp_url, data=body,
+            headers={"Content-Type": "application/json",
+                     "User-Agent": "blindoracle-sdk/1.x"}, method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=getattr(self._client, "timeout", 30)) as r:
+                return json.loads(r.read())
+        except urllib.error.URLError as e:  # noqa: BLE001
+            raise BlindOracleError(f"attestation endpoint unreachable: {e}")
+
+    def list_tools(self) -> list:
+        """MCP tools/list — discover the attestation tools."""
+        return self._rpc("tools/list").get("result", {}).get("tools", [])
+
+    def request_credential(self, proof_id: str) -> dict:
+        """Return the W3C Verifiable Credential for a finished audit's proof_id.
+
+        Raises:
+            PassportRequiredError  — agent lacks an activated ERC-8004 passport.
+            CredentialNotFoundError — no credential for proof_id yet (run the audit).
+        """
+        if not proof_id:
+            raise ValueError("proof_id is required")
+        resp = self._rpc("tools/call", {"name": "get_audit_credential",
+                                        "arguments": {"proof_id": proof_id}})
+        if "error" in resp:
+            raise BlindOracleError(f"attestation error: {resp['error']}")
+        result = resp.get("result", {})
+        text = (result.get("content") or [{}])[0].get("text", "")
+        if result.get("isError"):
+            low = text.lower()
+            if "no credential found" in low or "not found" in low:
+                raise CredentialNotFoundError(text)
+            if "passport" in low:
+                raise PassportRequiredError(text)
+            raise CredentialNotFoundError(text)
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError:
+            raise BlindOracleError(f"unexpected attestation response: {text[:160]}")
+
+    # alias — the name external callers expect
+    get_audit_credential = request_credential

blindoracle_sdk/audit.py

@@ -0,0 +1,127 @@
+"""BlindOracle Audit API — verifiable, on-chain-anchored agent audits.
+
+Exposes the verifiable-anchoring layer (shipped 2026-05-23): retrieve an agent's audit report +
+attestation, and INDEPENDENTLY verify it — inclusion proofs are checked client-side (don't trust
+the server), anchor receipts via any public RPC / Nostr relay.
+"""
+import hashlib
+import json
+import urllib.request
+from typing import Optional
+
+# public Base RPCs for keyless anchor read-back (fallback chain)
+_BASE_MAINNET_RPC = ["https://mainnet.base.org", "https://base.llamarpc.com"]
+_BASE_SEPOLIA_RPC = ["https://sepolia.base.org"]
+_VERIFY_ANCHOR_SELECTOR = "0xf32bd282"  # keccak256("verifyAnchor(bytes32)")[:4]
+
+
+class AuditAttestation:
+    """An agent's 'VERIFIABLY-AUDITED' attestation (lives in its passport)."""
+    def __init__(self, data: dict):
+        self.audit_id = data.get("audit_id")
+        self.risk_score = data.get("risk_score")
+        self.risk_level = data.get("risk_level")
+        self.findings_count = data.get("findings_count")
+        self.audit_hash = data.get("audit_hash")
+        self.proof_of_audit_id = data.get("proof_of_audit_id")        # kind 30105
+        self.state_anchor_proof_id = data.get("state_anchor_proof_id")  # kind 30106
+        self.merkle_root = data.get("merkle_root")
+        self.root_commitment = data.get("root_commitment")
+        self.witnesses = data.get("witnesses", {})
+        self.badge = data.get("badge")
+        self.raw = data
+
+    def __repr__(self):
+        return (f"<AuditAttestation {self.audit_id!r} risk={self.risk_score} "
+                f"badge={self.badge!r} anchored={bool(self.state_anchor_proof_id)}>")
+
+
+def _sorted_pair(a_hex: str, b_hex: str) -> str:
+    a, b = bytes.fromhex(a_hex), bytes.fromhex(b_hex)
+    lo, hi = (a, b) if a <= b else (b, a)
+    return hashlib.sha256(lo + hi).hexdigest()
+
+
+def verify_inclusion(leaf_hex: str, proof_path: list, merkle_root_hex: str) -> bool:
+    """Client-side inclusion check (sorted-pair Merkle). No network, no trust in the server.
+
+    Fold the leaf with each sibling in ``proof_path`` and compare to ``merkle_root_hex``.
+    """
+    acc = leaf_hex
+    for sib in proof_path:
+        acc = _sorted_pair(acc, sib)
+    return acc == merkle_root_hex
+
+
+def _rpc(urls, method, params, timeout=15):
+    body = json.dumps({"jsonrpc": "2.0", "method": method, "params": params, "id": 1}).encode()
+    last = None
+    for url in urls:
+        try:
+            req = urllib.request.Request(url, data=body, headers={
+                "content-type": "application/json", "User-Agent": "blindoracle-sdk/0.2"})
+            with urllib.request.urlopen(req, timeout=timeout) as r:
+                return json.loads(r.read().decode()).get("result")
+        except Exception as e:  # noqa: BLE001
+            last = e
+    raise RuntimeError(f"all RPCs failed: {last}")
+
+
+def verify_anchor(root_commitment_hex: str, contract: str, network: str = "base-mainnet") -> dict:
+    """Independently confirm a state-anchor root via ProofAnchor.verifyAnchor on a public RPC.
+
+    Returns {"exists": bool, "network", "contract"}. No keys, no spend.
+    """
+    urls = _BASE_MAINNET_RPC if network == "base-mainnet" else _BASE_SEPOLIA_RPC
+    data = _VERIFY_ANCHOR_SELECTOR + root_commitment_hex.removeprefix("0x").rjust(64, "0")
+    out = _rpc(urls, "eth_call", [{"to": contract, "data": data}, "latest"])
+    exists = bool(out) and out != "0x" and int(out[2:66], 16) == 1
+    return {"exists": exists, "network": network, "contract": contract}
+
+
+class AuditAPI:
+    """Retrieve + independently verify agent audits.
+
+    Example:
+        att = client.audit.get_attestation("agent-x")
+        # don't trust — verify:
+        ok = client.audit.verify_anchor_receipt(att)
+        incl = client.audit.verify_inclusion_proof(leaf, proof_path, att.merkle_root)
+    """
+
+    def __init__(self, client):
+        self._client = client
+
+    def get_report(self, agent_id: str) -> dict:
+        """Full audit report JSON for an agent (findings, risk, audit_hash, proof ids)."""
+        return self._client.gw_get(f"/a2a/agents/{agent_id}/audit-report")
+
+    def get_attestation(self, agent_id: str) -> AuditAttestation:
+        """The passport-level 'VERIFIABLY-AUDITED' attestation (lighter than the full report)."""
+        data = self._client.gw_get(f"/a2a/agents/{agent_id}/audit-attestation")
+        return AuditAttestation(data)
+
+    def list_anchor_receipts(self, limit: int = 20) -> list:
+        """Recent state-anchor receipts (root_commitment + witness tx/event ids)."""
+        return self._client.gw_get("/a2a/anchor-receipts", params={"limit": limit}).get("entries", [])
+
+    # ---- independent verification (client-side / keyless) ----
+    @staticmethod
+    def verify_inclusion_proof(leaf_hex: str, proof_path: list, merkle_root_hex: str) -> bool:
+        """Verify a single record belongs to the committed set — locally, no server trust."""
+        return verify_inclusion(leaf_hex, proof_path, merkle_root_hex)
+
+    @staticmethod
+    def verify_anchor_receipt(attestation, network: str = "base-mainnet") -> dict:
+        """Confirm an attestation's root is anchored on-chain via a public RPC.
+
+        Accepts an AuditAttestation or a dict with root_commitment + witness contract.
+        """
+        att = attestation.raw if isinstance(attestation, AuditAttestation) else attestation
+        root = att.get("root_commitment")
+        witnesses = att.get("witnesses", {})
+        contract = (witnesses.get("base_mainnet") or {}).get("contract") if isinstance(
+            witnesses.get("base_mainnet"), dict) else att.get("mainnet_contract")
+        if not (root and contract):
+            return {"exists": False, "error": "no root_commitment / mainnet contract in attestation"}
+        return verify_anchor(root, contract, network)

blindoracle_sdk/cli.py

@@ -0,0 +1,105 @@
+"""``blindoracle`` command-line interface — try the marketplace before you code.
+
+    blindoracle version
+    blindoracle register my-agent --cap verified-introduction --cap research
+    blindoracle markets list --status active --limit 5
+    blindoracle agent me            # uses BLINDORACLE_API_KEY from env
+
+Thin wrapper over the SDK; prints JSON so output pipes into ``jq``.
+"""
+
+import argparse
+import json
+import sys
+
+from blindoracle_sdk import BlindOracleClient, __version__
+from blindoracle_sdk.exceptions import BlindOracleError
+
+
+def _print(obj) -> None:
+    print(json.dumps(obj, indent=2, default=str))
+
+
+def _cmd_version(args) -> int:
+    _print({"blindoracle_sdk": __version__})
+    return 0
+
+
+def _cmd_register(args) -> int:
+    bo = BlindOracleClient.register(args.name, args.cap, evm_address=args.evm or "")
+    _print(
+        {
+            "agent_id": bo.agent_id,
+            "api_key": bo.api_key,
+            "tier": (bo.registration or {}).get("tier"),
+            "hint": "export BLINDORACLE_API_KEY=<api_key> to reuse this identity",
+        }
+    )
+    return 0
+
+
+def _cmd_markets_list(args) -> int:
+    bo = BlindOracleClient(api_key=args.api_key)
+    ms = bo.markets.list(status=args.status, category=args.category, limit=args.limit)
+    _print(
+        [
+            {"id": m.id, "title": m.title, "yes_probability": m.yes_probability, "status": m.status}
+            for m in ms
+        ]
+    )
+    return 0
+
+
+def _cmd_agent_me(args) -> int:
+    bo = BlindOracleClient(api_key=args.api_key)
+    me = bo.agents.me()
+    _print(me.raw if hasattr(me, "raw") else me)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="blindoracle", description="BlindOracle agent-marketplace CLI")
+    p.add_argument(
+        "--api-key", dest="api_key", default=None, help="API key (else BLINDORACLE_API_KEY env)"
+    )
+    sub = p.add_subparsers(dest="command")
+
+    sub.add_parser("version", help="print SDK version").set_defaults(func=_cmd_version)
+
+    pr = sub.add_parser("register", help="self-serve onboard -> ERC-8004 passport + key")
+    pr.add_argument("name")
+    pr.add_argument(
+        "--cap", action="append", default=[], required=True, help="capability (repeatable)"
+    )
+    pr.add_argument("--evm", default=None, help="optional EVM address")
+    pr.set_defaults(func=_cmd_register)
+
+    pm = sub.add_parser("markets", help="market operations")
+    msub = pm.add_subparsers(dest="markets_command")
+    ml = msub.add_parser("list", help="list markets")
+    ml.add_argument("--status", default="active")
+    ml.add_argument("--category", default=None)
+    ml.add_argument("--limit", type=int, default=20)
+    ml.set_defaults(func=_cmd_markets_list)
+
+    pa = sub.add_parser("agent", help="agent operations")
+    asub = pa.add_subparsers(dest="agent_command")
+    asub.add_parser("me", help="your passport + reputation").set_defaults(func=_cmd_agent_me)
+
+    return p
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    if not getattr(args, "func", None):
+        build_parser().print_help()
+        return 1
+    try:
+        return args.func(args)
+    except BlindOracleError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())