railhead 0.4.0__py3-none-any.whl

railhead/__init__.py

@@ -0,0 +1,41 @@
+"""
+Railhead Python SDK
+===================
+The agentic marketplace — discover, contract, and pay for AI capabilities on-chain.
+
+Quick start (buyer — x402, live on Base Sepolia)::
+
+    from railhead import Railhead
+    rh = Railhead()                                     # api.railhead.network · wallet + policy in ~/.railhead
+    rh.recommend("compute")                             # ranked providers, proven track records first
+    receipt = rh.hire("compute", {"a": 40, "b": 2, "op": "add"})   # pays over x402 within your spend policy
+    print(receipt["result"], receipt["explorer"])
+
+Quick start (legacy escrow-v1 client)::
+
+    from railhead import RailheadClient
+
+    client = RailheadClient.from_api("https://api.railhead.network", private_key="0x...")
+    result = client.post_job("price_signal", payment_usdc=5).wait()
+    print(result.note)
+
+Quick start (agent)::
+
+    from railhead import RailheadAgent
+
+    agent = RailheadAgent.from_api("https://api.railhead.network", private_key="0x...")
+
+    @agent.on("my_capability")
+    def handle(job):
+        return {"answer": 42}
+
+    agent.run()
+"""
+
+from .client import RailheadClient
+from .agent  import RailheadAgent
+from .types  import Capability, Agent, Job, Result
+from .buyer  import Railhead, PolicyRefused
+
+__version__ = "0.4.0"
+__all__     = ["Railhead", "PolicyRefused", "RailheadClient", "RailheadAgent", "Capability", "Agent", "Job", "Result"]

railhead/_abis.py

@@ -0,0 +1,89 @@
+# Minimal ABIs — only the functions the SDK calls.
+# Keeping these inline means the SDK has no dependency on forge build output.
+#
+# 2026-07-12 (Phase-A): resynced to the frozen optimistic-acceptance contracts.
+#   • JobMarket.jobs now has 16 fields — submittedAt/disputedAt/disputedPreResult were
+#     added, so `status` is index 13 (was 10). New enum: Open,Accepted,Submitted,Complete,
+#     Disputed,Cancelled,Expired.
+#   • AgentRegistry.getAgent tuple regenerated (completedJobs/disputedJobs precede status;
+#     unstakeRequestedAt/unstakeUnlocksAt/metadataHash added).
+#   • Added approveResult / claimPayout / disputeJob (optimistic finality + client dispute).
+#   • The token is USDC (6-decimal) — this ERC20 ABI is unchanged, only the amounts' decimals.
+# Regenerated from `forge inspect <Contract> abi`; verify against a fresh build after any edit.
+
+USDC_ABI = [
+    {"inputs":[{"name":"account","type":"address"}],"name":"balanceOf","outputs":[{"name":"","type":"uint256"}],"stateMutability":"view","type":"function"},
+    {"inputs":[{"name":"spender","type":"address"},{"name":"amount","type":"uint256"}],"name":"approve","outputs":[{"name":"","type":"bool"}],"stateMutability":"nonpayable","type":"function"},
+    {"inputs":[{"name":"to","type":"address"},{"name":"amount","type":"uint256"}],"name":"transfer","outputs":[{"name":"","type":"bool"}],"stateMutability":"nonpayable","type":"function"},
+]
+# Back-compat alias — the token handle used to be named RAIL; it is USDC now.
+RAIL_ABI = USDC_ABI
+
+REGISTRY_ABI = [
+    {"inputs":[{"name":"capabilities","type":"string[]"},{"name":"pricePerCall","type":"uint256"},{"name":"stake","type":"uint256"},{"name":"endpoint","type":"string"},{"name":"metadataHash","type":"bytes32"}],"name":"register","outputs":[],"stateMutability":"nonpayable","type":"function"},
+    {"inputs":[{"name":"addr","type":"address"}],"name":"getAgent","outputs":[{"name":"","type":"tuple","components":[
+        {"name":"addr","type":"address"},
+        {"name":"capabilities","type":"string[]"},
+        {"name":"pricePerCall","type":"uint256"},
+        {"name":"stake","type":"uint256"},
+        {"name":"completedJobs","type":"uint256"},
+        {"name":"disputedJobs","type":"uint256"},
+        {"name":"status","type":"uint8"},
+        {"name":"registeredAt","type":"uint256"},
+        {"name":"unstakeRequestedAt","type":"uint256"},
+        {"name":"unstakeUnlocksAt","type":"uint256"},
+        {"name":"endpoint","type":"string"},
+        {"name":"metadataHash","type":"bytes32"}
+    ]}],"stateMutability":"view","type":"function"},
+    {"inputs":[],"name":"getActiveAgents","outputs":[{"name":"","type":"address[]"}],"stateMutability":"view","type":"function"},
+    {"inputs":[],"name":"minStake","outputs":[{"name":"","type":"uint256"}],"stateMutability":"view","type":"function"},
+    {"inputs":[{"name":"addr","type":"address"},{"name":"authorized","type":"bool"}],"name":"setAgentWhitelist","outputs":[],"stateMutability":"nonpayable","type":"function"},
+]
+
+JOB_MARKET_ABI = [
+    {"inputs":[{"name":"agent","type":"address"},{"name":"capability","type":"string"},{"name":"inputHash","type":"bytes32"},{"name":"payment","type":"uint256"},{"name":"deadline","type":"uint256"}],"name":"createJob","outputs":[{"name":"","type":"uint256"}],"stateMutability":"nonpayable","type":"function"},
+    {"inputs":[{"name":"jobId","type":"uint256"}],"name":"acceptJob","outputs":[],"stateMutability":"nonpayable","type":"function"},
+    # Optimistic-finality settlement paths (mediator-free):
+    {"inputs":[{"name":"jobId","type":"uint256"}],"name":"approveResult","outputs":[],"stateMutability":"nonpayable","type":"function"},
+    {"inputs":[{"name":"jobId","type":"uint256"}],"name":"claimPayout","outputs":[],"stateMutability":"nonpayable","type":"function"},
+    # Client dispute (must land within CHALLENGE_WINDOW of submission):
+    {"inputs":[{"name":"jobId","type":"uint256"},{"name":"note","type":"string"}],"name":"disputeJob","outputs":[],"stateMutability":"nonpayable","type":"function"},
+    {"inputs":[{"name":"","type":"uint256"}],"name":"jobs","outputs":[
+        {"name":"id","type":"uint256"},
+        {"name":"client","type":"address"},
+        {"name":"agent","type":"address"},
+        {"name":"capability","type":"string"},
+        {"name":"inputHash","type":"bytes32"},
+        {"name":"payment","type":"uint256"},
+        {"name":"fee","type":"uint256"},
+        {"name":"createdAt","type":"uint256"},
+        {"name":"acceptedAt","type":"uint256"},
+        {"name":"deadline","type":"uint256"},
+        {"name":"submittedAt","type":"uint256"},
+        {"name":"disputedAt","type":"uint256"},
+        {"name":"disputedPreResult","type":"bool"},
+        {"name":"status","type":"uint8"},
+        {"name":"resultHash","type":"bytes32"},
+        {"name":"disputeNote","type":"string"}
+    ],"stateMutability":"view","type":"function"},
+    {"inputs":[],"name":"CHALLENGE_WINDOW","outputs":[{"name":"","type":"uint256"}],"stateMutability":"view","type":"function"},
+    {"anonymous":False,"inputs":[{"indexed":True,"name":"jobId","type":"uint256"},{"indexed":True,"name":"client","type":"address"},{"indexed":True,"name":"agent","type":"address"},{"indexed":False,"name":"capability","type":"string"},{"indexed":False,"name":"payment","type":"uint256"}],"name":"JobCreated","type":"event"},
+]
+
+RESULT_STORE_ABI = [
+    {"inputs":[{"name":"jobId","type":"uint256"},{"name":"resultHash","type":"bytes32"},{"name":"schemaHash","type":"bytes32"}],"name":"submitResult","outputs":[],"stateMutability":"nonpayable","type":"function"},
+    {"inputs":[{"name":"jobId","type":"uint256"},{"name":"note","type":"string"}],"name":"validate","outputs":[],"stateMutability":"nonpayable","type":"function"},
+    {"inputs":[{"name":"jobId","type":"uint256"},{"name":"evidenceHash","type":"bytes32"},{"name":"note","type":"string"}],"name":"dispute","outputs":[],"stateMutability":"nonpayable","type":"function"},
+    {"inputs":[{"name":"","type":"uint256"}],"name":"results","outputs":[
+        {"name":"jobId","type":"uint256"},
+        {"name":"agent","type":"address"},
+        {"name":"resultHash","type":"bytes32"},
+        {"name":"schemaHash","type":"bytes32"},
+        {"name":"evidenceHash","type":"bytes32"},
+        {"name":"submittedAt","type":"uint256"},
+        {"name":"validatedAt","type":"uint256"},
+        {"name":"status","type":"uint8"},
+        {"name":"mediator","type":"address"},
+        {"name":"note","type":"string"}
+    ],"stateMutability":"view","type":"function"},
+]

railhead/_chain.py

@@ -0,0 +1,196 @@
+"""Internal: web3 connection, contract instances, tx helpers."""
+from __future__ import annotations
+import json, time
+from typing import Any
+
+import requests
+from web3 import Web3
+from eth_account import Account
+from eth_account.messages import encode_defunct
+
+from ._abis import RAIL_ABI, REGISTRY_ABI, JOB_MARKET_ABI, RESULT_STORE_ABI
+
+# USDC is 6-decimal (NOT 18 like the old RAIL token). Use these for every TOKEN amount.
+# ETH/gas amounts stay on w3.to_wei/from_wei(…, "ether") — those are real 18-decimal ETH.
+USDC_DEC = 6
+
+
+def to_usdc(x: float) -> int:
+    """Human USDC → base units (6dp). e.g. 25 → 25_000_000."""
+    return int(round(x * 10 ** USDC_DEC))
+
+
+def from_usdc(x: int) -> float:
+    """Base units (6dp) → human USDC. e.g. 25_000_000 → 25.0."""
+    return x / 10 ** USDC_DEC
+
+
+def relay_auth(private_key: str, job_id: int, valid_secs: int = 120) -> str:
+    """Sign a short-lived, job-scoped relay-access token ``'<validBefore>.<sig>'``. The signer must be
+    the job's client (reading results / posting inputs) or agent (reading inputs / posting results) for
+    the discovery API to serve the payload — so a stranger can't enumerate and vacuum everyone's data."""
+    valid_before = int(time.time()) + valid_secs
+    sig = Account.sign_message(
+        encode_defunct(text=f"railhead-relay|{job_id}|{valid_before}"), private_key).signature
+    return f"{valid_before}.{Web3.to_hex(sig)}"
+
+
+def _relay_post(url: str, payload: dict, *, retry_on=(404, 409), attempts: int = 6,
+                delay: float = 2.0, label: str = "relay", log=None, auth: str = None) -> bool:
+    """POST to a data-plane relay endpoint that validates the payload against on-chain state.
+
+    Public / load-balanced RPCs lag between a write tx and the API's confirming read, so a
+    just-created job (404 "job not found") or a just-submitted result (409 "not submitted
+    yet") can be invisible to the API for a few seconds. Retry with backoff until the chain
+    state propagates. A non-lag error (e.g. 400 hash-mismatch) is terminal — stop early.
+    ``auth`` is the job-scoped X-Relay-Auth token from ``relay_auth``. Returns True on a 2xx."""
+    headers = {"X-Relay-Auth": auth} if auth else None
+    last = None
+    for i in range(attempts):
+        try:
+            resp = requests.post(url, json=payload, timeout=10, headers=headers)
+            if resp.ok:
+                return True
+            last = f"HTTP {resp.status_code}: {resp.text[:160]}"
+            if resp.status_code not in retry_on:
+                break
+        except Exception as e:
+            last = str(e)
+        if i < attempts - 1:
+            time.sleep(delay)
+    if log is not None:
+        log.warning("%s relay failed after %d attempts: %s", label, attempts, last)
+    return False
+
+
+def _relay_get_json(url: str, key: str, *, attempts: int = 6, delay: float = 2.0, auth: str = None) -> dict:
+    """GET a data-plane payload that may not be relayed yet (404 until the counterparty's POST
+    lands / its on-chain write propagates). Retry on 404; return the ``key`` field of the JSON,
+    or {} if it never became available. ``auth`` is the X-Relay-Auth token from ``relay_auth``."""
+    headers = {"X-Relay-Auth": auth} if auth else None
+    for i in range(attempts):
+        try:
+            r = requests.get(url, timeout=8, headers=headers)
+            if r.ok:
+                return r.json().get(key, {}) or {}
+            if r.status_code != 404:
+                break
+        except Exception:
+            pass
+        if i < attempts - 1:
+            time.sleep(delay)
+    return {}
+
+
+def _fetch_abis(api_url: str) -> dict:
+    """Fetch compiled ABIs from the Railhead discovery API. Falls back to minimal ABIs."""
+    try:
+        r = requests.get(f"{api_url.rstrip('/')}/abis", timeout=8)
+        if r.ok:
+            return r.json()
+    except Exception:
+        pass
+    return {}
+
+
+class Chain:
+    """Thin wrapper around a web3 connection + all four Railhead contracts."""
+
+    def __init__(self, rpc: str, private_key: str,
+                 rail: str, registry: str, job_market: str, result_store: str):
+        self.w3 = Web3(Web3.HTTPProvider(rpc))
+        if not self.w3.is_connected():
+            raise ConnectionError(f"Cannot connect to RPC: {rpc}")
+
+        self.account = self.w3.eth.account.from_key(private_key)
+        self._key    = private_key
+        cs = self.w3.to_checksum_address
+
+        self.rail         = self.w3.eth.contract(address=cs(rail),         abi=RAIL_ABI)
+        self.registry     = self.w3.eth.contract(address=cs(registry),     abi=REGISTRY_ABI)
+        self.job_market   = self.w3.eth.contract(address=cs(job_market),   abi=JOB_MARKET_ABI)
+        self.result_store = self.w3.eth.contract(address=cs(result_store), abi=RESULT_STORE_ABI)
+
+    @classmethod
+    def from_api(cls, api_url: str, private_key: str) -> "Chain":
+        """Auto-discover contract addresses and ABIs from the Railhead discovery API."""
+        url = api_url.rstrip("/") + "/health"
+        try:
+            r = requests.get(url, timeout=8)
+            r.raise_for_status()
+        except Exception as e:
+            raise ConnectionError(f"Cannot reach Railhead API at {url}: {e}")
+        data = r.json()
+        contracts = data.get("contracts", {})
+        rpc = data.get("rpc", "")
+        if not rpc:
+            from urllib.parse import urlparse
+            parsed = urlparse(api_url)
+            rpc = f"http://{parsed.hostname}:8545"
+
+        inst = cls.__new__(cls)
+        inst.w3      = Web3(Web3.HTTPProvider(rpc))
+        inst.account = inst.w3.eth.account.from_key(private_key)
+        inst._key    = private_key
+        cs = inst.w3.to_checksum_address
+
+        # Prefer full ABIs from API; fall back to minimal bundled ABIs
+        abis = _fetch_abis(api_url)
+        inst.rail         = inst.w3.eth.contract(address=cs(contracts["rail_token"]),      abi=abis.get("Rail",          RAIL_ABI))
+        inst.registry     = inst.w3.eth.contract(address=cs(contracts["agent_registry"]),  abi=abis.get("AgentRegistry", REGISTRY_ABI))
+        inst.job_market   = inst.w3.eth.contract(address=cs(contracts["job_market"]),      abi=abis.get("JobMarket",     JOB_MARKET_ABI))
+        inst.result_store = inst.w3.eth.contract(address=cs(contracts["result_store"]),    abi=abis.get("ResultStore",   RESULT_STORE_ABI))
+        return inst
+
+    def send(self, fn, gas: int = 1_200_000) -> Any:
+        """Sign and broadcast a contract function call. Returns the receipt.
+
+        If the on-chain receipt comes back with ``status == 0`` (revert), a
+        warning is logged with the tx hash and gas-used so callers can see
+        that the call cheerily succeeded at the RPC level but failed at the
+        contract level — the EVM-silent-success trap.
+        """
+        import logging
+        _log = logging.getLogger("railhead.chain")
+        # Local nonce tracking — public/load-balanced RPCs lag on get_transaction_count between
+        # back-to-back txs ("replacement transaction underpriced"). Track locally; resync on failure.
+        if getattr(self, "_nonce", None) is None:
+            self._nonce = self.w3.eth.get_transaction_count(self.account.address, "pending")
+        tx = fn.build_transaction({
+            "from":     self.account.address,
+            "nonce":    self._nonce,
+            "gas":      gas,
+            "gasPrice": self.w3.eth.gas_price,
+        })
+        signed  = self.w3.eth.account.sign_transaction(tx, self._key)
+        try:
+            tx_hash = self.w3.eth.send_raw_transaction(signed.raw_transaction)
+        except Exception:
+            self._nonce = None   # resync from chain on the next send
+            raise
+        self._nonce += 1
+        receipt = self.w3.eth.wait_for_transaction_receipt(tx_hash)
+        if receipt.status == 0:
+            _log.warning(
+                "Transaction REVERTED on-chain: tx=%s  gasUsed=%d/%d  (likely out of gas — bump the gas argument)",
+                receipt.transactionHash.hex(), receipt.gasUsed, gas,
+            )
+        return receipt
+
+    def usdc_balance(self, address: str | None = None) -> float:
+        """USDC balance (6-decimal) of the wallet. NOTE: `self.rail` is the USDC token handle."""
+        addr = self.w3.to_checksum_address(address or self.account.address)
+        return from_usdc(self.rail.functions.balanceOf(addr).call())
+
+    # Back-compat alias — callers used to say rail_balance(); it returns USDC now.
+    def rail_balance(self, address: str | None = None) -> float:
+        return self.usdc_balance(address)
+
+    def result_hash(self, output: dict) -> bytes:
+        """Compute keccak256 of the JSON-encoded output dict (canonical form)."""
+        payload = json.dumps(output, sort_keys=True, separators=(",", ":")).encode()
+        return self.w3.keccak(payload)
+
+    def input_hash(self, input_data: dict) -> bytes:
+        payload = json.dumps(input_data, sort_keys=True, separators=(",", ":")).encode()
+        return self.w3.keccak(payload)

railhead/agent.py

@@ -0,0 +1,328 @@
+"""RailheadAgent — register a capability and handle incoming jobs."""
+from __future__ import annotations
+import json, logging, time
+from typing import Callable, Any
+
+import requests
+
+from ._chain import Chain, to_usdc, from_usdc, _relay_post, _relay_get_json, relay_auth
+from .types  import Job, Result
+
+log = logging.getLogger("railhead.agent")
+
+
+class RailheadAgent:
+    """
+    Register an agent on Railhead and handle incoming jobs.
+
+    Quick start::
+
+        agent = RailheadAgent.from_api("https://api.railheads.ai", private_key="0x...")
+
+        agent.register(
+            capabilities=["price_signal"],
+            price_usdc=1,
+            stake_usdc=25,
+            endpoint="https://myagent.example.com",
+        )
+
+        @agent.on("price_signal")
+        def handle(job):
+            return {"signal": "buy", "confidence": 0.85}
+
+        agent.run()
+    """
+
+    def __init__(self, rpc: str, private_key: str,
+                 rail: str, registry: str, job_market: str, result_store: str):
+        self._chain    = Chain(rpc, private_key, rail, registry, job_market, result_store)
+        self._handlers: dict[str, Callable] = {}
+        self._last_block: int = 0
+        self._api_url: str = ""
+
+    @classmethod
+    def from_api(cls, api_url: str, private_key: str) -> "RailheadAgent":
+        """
+        Recommended constructor. Auto-discovers contract addresses from the API.
+
+        :param api_url:     Railhead discovery API, e.g. "https://api.railheads.ai"
+        :param private_key: 0x-prefixed hex private key
+        """
+        chain = Chain.from_api(api_url, private_key)
+        inst = cls.__new__(cls)
+        inst._chain    = chain
+        inst._handlers = {}
+        inst._last_block = 0
+        inst._api_url  = api_url.rstrip("/")
+        return inst
+
+    @classmethod
+    def from_credentials(cls, config_path: str | None = None) -> "RailheadAgent":
+        """
+        Construct from credentials saved by `railhead init` at ~/.railhead/config.json.
+
+        Reads private_key + api_url from disk. The config file should be chmod 600.
+        """
+        import json
+        from pathlib import Path
+        path = Path(config_path) if config_path else Path.home() / ".railhead" / "config.json"
+        if not path.exists():
+            raise FileNotFoundError(
+                f"No Railhead credentials at {path}. "
+                "Run `railhead init --invite-code XXX` to set up."
+            )
+        cfg = json.loads(path.read_text())
+        return cls.from_api(cfg["api_url"], private_key=cfg["private_key"])
+
+    # ── Registration ──────────────────────────────────────────────────────────
+
+    def register(
+        self,
+        capabilities: list[str],
+        price_usdc:   float  = 1.0,
+        stake_usdc:   float  = 25.0,   # min is 10 USDC on-chain; 25 is a sane default
+        endpoint:     str    = "",
+    ) -> str:
+        """
+        Register this agent on-chain. Stakes USDC (6-decimal) as reputation collateral.
+
+        The connected wallet must hold enough USDC to cover the stake (min 10 USDC).
+        On Base Sepolia, fund the wallet from Circle's test-USDC faucet.
+
+        :returns: Transaction hash of the registration.
+        """
+        c = self._chain
+        w3 = c.w3
+
+        # Check if already registered
+        existing = c.registry.functions.getAgent(c.account.address).call()
+        if existing[0] != "0x0000000000000000000000000000000000000000":
+            log.info("Agent already registered — capabilities: %s", existing[1])
+            return ""
+
+        stake_units = to_usdc(stake_usdc)   # 6-decimal base units
+        price_units = to_usdc(price_usdc)
+
+        # Check USDC balance
+        bal = c.usdc_balance()
+        if bal < stake_usdc:
+            raise ValueError(
+                f"Insufficient USDC: have {bal:.2f}, need {stake_usdc:.2f}. "
+                "Fund your wallet with Base Sepolia test-USDC (Circle faucet)."
+            )
+
+        # Approve registry to pull stake
+        c.send(c.rail.functions.approve(c.registry.address, stake_units))
+        log.info("USDC approved ✓")
+
+        # Register. Gas grows linearly with the number of capabilities; pass an
+        # explicit roomy budget so multi-capability registrations don't silently
+        # revert when the default isn't enough (the bug that bit Agent #5).
+        gas_budget = 400_000 + 250_000 * max(1, len(capabilities))
+        receipt = c.send(c.registry.functions.register(
+            capabilities, price_units, stake_units, endpoint, b'\x00' * 32
+        ), gas=gas_budget)
+
+        if receipt.status != 1:
+            raise RuntimeError(
+                f"Registration reverted on-chain (tx {receipt.transactionHash.hex()}, "
+                f"gasUsed {receipt.gasUsed}/{gas_budget}). "
+                "Check whitelist status + USDC allowance + stake balance."
+            )
+
+        tx = receipt.transactionHash.hex()
+        log.info("Registered on Railhead ✓  capabilities=%s  tx=%s  gasUsed=%d", capabilities, tx[:20], receipt.gasUsed)
+        return tx
+
+    @property
+    def address(self) -> str:
+        return self._chain.account.address
+
+    @property
+    def balance(self) -> float:
+        return self._chain.usdc_balance()
+
+    def claim_payout(self, job_id: int) -> str:
+        """
+        Release escrow for one of your delivered jobs after its challenge window closes.
+
+        Under the optimistic-acceptance model, a Submitted result that the client neither
+        approved nor disputed within CHALLENGE_WINDOW can be settled by ANYONE — no mediator
+        needed. Call this on your own jobs once the window has passed to get paid.
+
+        Reverts on-chain (surfaced as a warning) if the window is still open or the job isn't
+        in the Submitted state.
+        """
+        c = self._chain
+        receipt = c.send(c.job_market.functions.claimPayout(job_id))
+        if receipt.status != 1:
+            log.warning("  claimPayout #%d reverted — window still open, or job not Submitted.", job_id)
+        else:
+            log.info("  claimPayout #%d ✓  escrow released (mediator-free)", job_id)
+        return receipt.transactionHash.hex()
+
+    # ── Capability handler registry ───────────────────────────────────────────
+
+    def on(self, capability: str) -> Callable:
+        """
+        Decorator — register a handler for a capability.
+
+        The handler receives a Job and must return a dict (the result payload).
+        The SDK handles hashing, submitting, and validating on-chain automatically.
+
+        Example::
+
+            @agent.on("price_signal")
+            def handle(job):
+                return {"signal": "buy", "asset": "ETH", "confidence": 0.9}
+        """
+        def decorator(fn: Callable) -> Callable:
+            self._handlers[capability] = fn
+            log.info("Handler registered for '%s'", capability)
+            return fn
+        return decorator
+
+    # ── Job loop ──────────────────────────────────────────────────────────────
+
+    def run(self, poll_secs: float = 5.0) -> None:
+        """
+        Start polling for jobs. Blocks forever (Ctrl+C to stop).
+
+        For each incoming job assigned to this agent:
+        1. Calls the registered handler
+        2. Submits the result hash on-chain
+        3. Self-validates (Phase 1 — agent is its own mediator)
+        4. Escrow releases automatically
+        """
+        log.info("Agent %s watching for jobs  (poll every %.0fs)", self.address[:10], poll_secs)
+        log.info("Handling capabilities: %s", list(self._handlers.keys()))
+        self._last_block = self._chain.w3.eth.block_number
+        try:
+            while True:
+                try:
+                    self._poll()
+                except KeyboardInterrupt:
+                    raise
+                except Exception as e:
+                    # A transient RPC/DNS/network failure must NOT kill the daemon — there is no process
+                    # supervisor (review ops finding). Log and retry on the next cycle instead of dying.
+                    log.warning("poll error (transient?) — retrying next cycle: %s", e)
+                time.sleep(poll_secs)
+        except KeyboardInterrupt:
+            log.info("Stopped.")
+
+    def _poll(self) -> None:
+        c = self._chain
+        current_block = c.w3.eth.block_number
+        if current_block <= self._last_block:
+            return
+
+        # Scan for JobCreated events assigned to this agent
+        try:
+            jc_sig = c.w3.keccak(text="JobCreated(uint256,address,address,string,uint256)")
+            logs = c.w3.eth.get_logs({
+                "fromBlock": self._last_block + 1,
+                "toBlock":   current_block,
+                "address":   c.job_market.address,
+                "topics":    [jc_sig],
+            })
+        except Exception as e:
+            log.warning("Log fetch error: %s", e)
+            self._last_block = current_block
+            return
+
+        self._last_block = current_block
+
+        for entry in logs:
+            try:
+                job_id = int(entry["topics"][1].hex(), 16)
+                raw    = c.job_market.functions.jobs(job_id).call()
+                agent  = raw[2]
+                status = raw[13]   # status index in the 16-field jobs() tuple
+                cap    = raw[3]
+
+                if agent.lower() != c.account.address.lower():
+                    continue
+                if status != 0:  # only Open jobs
+                    continue
+
+                log.info("Job #%d received  capability=%s  payment=%.2f USDC",
+                         job_id, cap, from_usdc(raw[5]))
+                self._handle(job_id, cap, raw)
+
+            except Exception as e:
+                log.error("Error processing job: %s", e, exc_info=True)
+
+    def _fetch_input(self, job_id: int) -> dict:
+        """
+        Retrieve the off-chain input payload from the discovery API's relay.
+        Returns {} if no API is configured, none is stored, or the fetch fails —
+        so a missing relay degrades to the old empty-input behavior rather than erroring.
+        """
+        if not self._api_url:
+            return {}
+        # The client's input POST may still be in flight (or its on-chain visibility lagging),
+        # so retry on 404 for a few seconds before degrading to empty input.
+        return _relay_get_json(f"{self._api_url}/job-inputs/{job_id}", "input",
+                               auth=relay_auth(self._chain._key, job_id))  # only the assigned agent may read
+
+    def _handle(self, job_id: int, capability: str, raw: tuple) -> None:
+        c = self._chain
+
+        handler = self._handlers.get(capability)
+        if not handler:
+            log.warning("No handler for capability '%s' — skipping job #%d", capability, job_id)
+            return
+
+        # Input is hashed on-chain and stored off-chain; retrieve the real payload
+        # from the discovery API relay (falls back to {} if unavailable).
+        job = Job(
+            id=job_id,
+            capability=capability,
+            client=raw[1],
+            agent=raw[2],
+            payment_usdc=from_usdc(raw[5]),
+            status="Open",
+            input=self._fetch_input(job_id),
+            _chain=c,
+        )
+
+        # Accept the job
+        c.send(c.job_market.functions.acceptJob(job_id))
+        log.info("  acceptJob #%d ✓", job_id)
+
+        # Run the handler
+        try:
+            output = handler(job)
+            if not isinstance(output, dict):
+                output = {"result": str(output)}
+        except Exception as e:
+            log.error("  Handler error on job #%d: %s", job_id, e)
+            output = {"error": str(e)}
+
+        # Submit result hash
+        result_hash = c.result_hash(output)
+        c.send(c.result_store.functions.submitResult(
+            job_id, result_hash, b'\x00' * 32
+        ))
+        log.info("  submitResult #%d ✓  hash=%s", job_id, result_hash.hex()[:16])
+
+        # Relay the result text off-chain so clients can read it (not just the hash).
+        # Best-effort — the on-chain submit already happened, so a relay failure
+        # just means clients see the hash but can't fetch the body. The relay
+        # endpoint verifies our keccak matches the on-chain resultHash.
+        if self._api_url:
+            # The API validates our payload against the on-chain resultHash; its RPC may not see
+            # our just-landed submitResult yet (409), so retry until the write propagates.
+            _relay_post(f"{self._api_url}/job-results/{job_id}", output,
+                        retry_on=(404, 409), label=f"result #{job_id}", log=log,
+                        auth=relay_auth(c._key, job_id))   # only the assigned agent may post
+
+        # Self-validate (Phase 1 — agent wallet must be whitelisted as mediator)
+        note = output.get("_summary", f"{capability} completed")
+        try:
+            c.send(c.result_store.functions.validate(job_id, note))
+            log.info("  validate #%d ✓  escrow released  note=%r", job_id, note)
+        except Exception as e:
+            log.warning("  validate #%d failed — wallet not whitelisted as mediator. "
+                        "Contact the Railhead team to enable auto-settlement. error=%s", job_id, e)