recensus-sdk 1.0.0__py3-none-any.whl

recensus_sdk/__init__.py

@@ -0,0 +1,45 @@
+"""
+recensus-sdk — label your agent's transactions on Robinhood Chain.
+
+The Python mirror of ``@recensus/sdk``: the same 24-byte label, the same safety
+rules, the same promise that the label never breaks a transaction.
+
+    from recensus_sdk import Recensus, derive_agent_id
+
+    recensus = Recensus(agent_id=derive_agent_id(operator, "price-watcher"),
+                  autonomous=True, w3=w3)
+    account = recensus.wrap(account)
+    account.send_transaction({"to": recipient, "value": 1_000_000})
+"""
+
+from .label import (
+    MAGIC, LABEL_BYTES, VERSION, FLAG_AUTONOMOUS, FLAG_TEST,
+    Label, LabelFlags, RecensusLabelError,
+    append_label, build_label, byte_to_flags, derive_agent_id, flags_to_byte,
+    has_label, normalize_agent_id, parse_label, short_agent_id, strip_label,
+)
+from .safety import (
+    NEVER_TAG_SELECTORS, CallShape, SafetyDecision, check_safety, selector_of,
+)
+from .frameworks import (
+    FRAMEWORK_UNKNOWN, FRAMEWORK_MCP, FRAMEWORK_SDK_TS, FRAMEWORK_SDK_PY,
+    framework_code_to_hex, framework_color_index,
+)
+from .recensus import Recensus, TagResult
+from .sign import SIGNING_PREFIX, body_hash, canonical_string, random_nonce, sign_request
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "MAGIC", "LABEL_BYTES", "VERSION", "FLAG_AUTONOMOUS", "FLAG_TEST",
+    "Label", "LabelFlags", "RecensusLabelError",
+    "append_label", "build_label", "byte_to_flags", "derive_agent_id",
+    "flags_to_byte", "has_label", "normalize_agent_id", "parse_label",
+    "short_agent_id", "strip_label",
+    "NEVER_TAG_SELECTORS", "CallShape", "SafetyDecision", "check_safety", "selector_of",
+    "FRAMEWORK_UNKNOWN", "FRAMEWORK_MCP", "FRAMEWORK_SDK_TS", "FRAMEWORK_SDK_PY",
+    "framework_code_to_hex", "framework_color_index",
+    "Recensus", "TagResult",
+    "SIGNING_PREFIX", "body_hash", "canonical_string", "random_nonce", "sign_request",
+    "__version__",
+]

recensus_sdk/frameworks.py

@@ -0,0 +1,20 @@
+"""Framework registry helpers (RECENSUS-1 §2)."""
+
+FRAMEWORK_UNKNOWN = 0x0000
+FRAMEWORK_MCP = 0x0001
+FRAMEWORK_SDK_TS = 0x0002
+FRAMEWORK_SDK_PY = 0x0003
+
+
+def framework_code_to_hex(code: int) -> str:
+    return f"0x{code:04x}"
+
+
+def framework_color_index(code: int) -> int:
+    """
+    A stable colour index per framework code, matching the TypeScript side so a
+    framework keeps its colour wherever it is rendered.
+    """
+    if code == FRAMEWORK_UNKNOWN:
+        return 7
+    return ((code * 2654435761) & 0xFFFFFFFF) % 7

recensus_sdk/label.py

@@ -0,0 +1,225 @@
+"""
+RECENSUS-1 label: build, parse, validate.  See packages/spec/RECENSUS-1.md.
+
+Layout, appended to the end of calldata:
+
+    | agentId (16) | framework (2) | flags (1) | version (1) | magic (4) |
+
+This module mirrors ``packages/spec/src/label.ts`` byte for byte, and the test
+suite checks the two against the same vectors.  It has no dependencies on
+purpose: a label reader should be copy-pasteable into anything.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Union
+
+MAGIC = "50554c53"  # "PULS"
+MAGIC_BYTES = 4
+LABEL_BYTES = 24
+VERSION = 1
+
+FLAG_AUTONOMOUS = 0b0000_0001
+FLAG_TEST = 0b0000_0010
+#: Bits 2-7 are reserved and must be zero (RECENSUS-1 §1.2).
+FLAG_RESERVED_MASK = 0b1111_1100
+
+HexLike = Union[str, bytes, bytearray]
+
+
+class RecensusLabelError(ValueError):
+    """Raised when something that must be a label is not one."""
+
+
+@dataclass(frozen=True)
+class LabelFlags:
+    autonomous: bool = False
+    test: bool = False
+
+
+@dataclass(frozen=True)
+class Label:
+    #: 16-byte hex, lowercase, 0x-prefixed.
+    agent_id: str
+    #: Framework code, 0-65535.
+    framework: int
+    flags: LabelFlags
+    #: The raw flags byte, as sent.
+    flags_byte: int
+    version: int
+
+
+# --------------------------------------------------------------------- hex
+
+
+def _to_hex_body(value: HexLike) -> str:
+    """The hex characters of a value, with no 0x and no case."""
+    if isinstance(value, (bytes, bytearray)):
+        return value.hex()
+    if not isinstance(value, str):
+        raise RecensusLabelError(f"expected hex or bytes, got {type(value).__name__}")
+    body = value[2:] if value.lower().startswith("0x") else value
+    if body and not all(c in "0123456789abcdefABCDEF" for c in body):
+        raise RecensusLabelError(f"{value!r} is not hex")
+    return body.lower()
+
+
+def normalize_agent_id(agent_id: HexLike) -> str:
+    """Any accepted agent-id form as 0x + 32 lowercase hex characters."""
+    body = _to_hex_body(agent_id)
+    if len(body) != 32:
+        raise RecensusLabelError(
+            f"agentId must be exactly 16 bytes (32 hex characters), got {len(body) // 2} bytes"
+        )
+    return f"0x{body}"
+
+
+# ------------------------------------------------------------------- build
+
+
+def flags_to_byte(flags: Union[LabelFlags, int, None]) -> int:
+    if isinstance(flags, int):
+        if not 0 <= flags <= 0xFF:
+            raise RecensusLabelError(f"flags byte must be 0-255, got {flags}")
+        if flags & FLAG_RESERVED_MASK:
+            raise RecensusLabelError(
+                f"flags bits 2-7 are reserved and must be zero (RECENSUS-1 §1.2), got 0x{flags:02x}"
+            )
+        return flags
+    if flags is None:
+        return 0
+    byte = 0
+    if flags.autonomous:
+        byte |= FLAG_AUTONOMOUS
+    if flags.test:
+        byte |= FLAG_TEST
+    return byte
+
+
+def byte_to_flags(byte: int) -> LabelFlags:
+    return LabelFlags(
+        autonomous=bool(byte & FLAG_AUTONOMOUS),
+        test=bool(byte & FLAG_TEST),
+    )
+
+
+def build_label(
+    agent_id: HexLike,
+    framework: int = 0,
+    flags: Union[LabelFlags, int, None] = None,
+    version: int = VERSION,
+) -> str:
+    """The 24-byte label as 0x-prefixed hex."""
+    body = normalize_agent_id(agent_id)[2:]
+
+    if not isinstance(framework, int) or isinstance(framework, bool) or not 0 <= framework <= 0xFFFF:
+        raise RecensusLabelError(f"framework must be an integer 0-65535, got {framework!r}")
+    if not isinstance(version, int) or not 0 <= version <= 0xFF:
+        raise RecensusLabelError(f"version must be an integer 0-255, got {version!r}")
+
+    flags_byte = flags_to_byte(flags)
+    return f"0x{body}{framework:04x}{flags_byte:02x}{version:02x}{MAGIC}"
+
+
+# ------------------------------------------------------------------- parse
+
+
+def parse_label(calldata: Union[HexLike, None]) -> Union[Label, None]:
+    """
+    Read the RECENSUS-1 label off the end of calldata.
+
+    Returns ``None`` — never raises — for anything that is not a well-formed
+    label of a version we know.  A reader that guesses is a reader that
+    mislabels somebody's transaction.
+    """
+    if calldata is None:
+        return None
+
+    try:
+        body = _to_hex_body(calldata)
+    except RecensusLabelError:
+        return None
+
+    if len(body) % 2 != 0:
+        return None
+    if len(body) < LABEL_BYTES * 2:
+        return None
+    if not body.endswith(MAGIC):
+        return None
+
+    tail = body[-LABEL_BYTES * 2:]
+    version = int(tail[38:40], 16)
+    if version != VERSION:
+        return None  # unknown version: ignore, do not guess
+
+    flags_byte = int(tail[36:38], 16)
+    if flags_byte & FLAG_RESERVED_MASK:
+        return None  # reserved bits set: malformed
+
+    return Label(
+        agent_id=f"0x{tail[0:32]}",
+        framework=int(tail[32:36], 16),
+        flags=byte_to_flags(flags_byte),
+        flags_byte=flags_byte,
+        version=version,
+    )
+
+
+def has_label(calldata: Union[HexLike, None]) -> bool:
+    """True when calldata already carries a well-formed RECENSUS-1 label."""
+    return parse_label(calldata) is not None
+
+
+def strip_label(calldata: HexLike) -> str:
+    """Calldata with its label removed, or unchanged when it has none."""
+    body = _to_hex_body(calldata)
+    if not has_label(calldata):
+        return f"0x{body}"
+    return f"0x{body[:-LABEL_BYTES * 2]}"
+
+
+def append_label(calldata: Union[HexLike, None], label: str) -> str:
+    """
+    Append a label to calldata.  Never stacks: calldata that is already
+    labelled comes back unchanged (RECENSUS-1 §4.2 rule 3).
+    """
+    body = "" if calldata is None else _to_hex_body(calldata)
+    if has_label(f"0x{body}"):
+        return f"0x{body}"
+    return f"0x{body}{_to_hex_body(label)}"
+
+
+# --------------------------------------------------------- agent identity
+
+
+def derive_agent_id(
+    operator: str,
+    agent_name: str,
+    keccak: Union[Callable[[bytes], bytes], None] = None,
+) -> str:
+    """
+    The recommended derivation (RECENSUS-1 §1.1)::
+
+        keccak256(operatorAddress ‖ agentName)[0:16]
+
+    ``keccak`` is injected so this module can be used without web3; when it is
+    omitted, ``eth_utils.keccak`` is imported lazily.
+    """
+    address = _to_hex_body(operator)
+    if len(address) != 40:
+        raise RecensusLabelError(f"operator must be a 20-byte address, got {len(address) // 2} bytes")
+
+    if keccak is None:
+        from eth_utils import keccak as _keccak  # imported here so the label module stays dependency-free
+
+        keccak = _keccak
+
+    digest = keccak(bytes.fromhex(address) + agent_name.encode("utf-8"))
+    return f"0x{digest.hex()[:32]}"
+
+
+def short_agent_id(agent_id: HexLike) -> str:
+    """Short display form: 0x9f2a0c1e…d7b4a5c3"""
+    full = normalize_agent_id(agent_id)
+    return f"{full[:10]}…{full[-8:]}"

recensus_sdk/recensus.py

@@ -0,0 +1,240 @@
+"""
+recensus-sdk — the Python mirror of ``@recensus/sdk``.
+
+The one rule this file exists to keep: **the label never breaks a
+transaction** (RECENSUS-1 §4).  Three layers enforce it.
+
+  1. ``check_safety`` refuses call shapes where trailing calldata is not inert.
+  2. Before sending, the labelled call is simulated.  If it would revert and
+     the unlabelled call would not, the unlabelled call is sent.
+  3. Any unexpected failure while deciding falls through to unlabelled.
+
+Losing a row on a scoreboard is cheap.  Losing a transaction is not.
+"""
+
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Iterable, Optional
+
+from .frameworks import FRAMEWORK_SDK_PY
+from .label import (
+    HexLike,
+    LabelFlags,
+    append_label,
+    build_label,
+    derive_agent_id,
+    has_label,
+    normalize_agent_id,
+    parse_label,
+)
+from .safety import CallShape, check_safety, load_tag_safe_contracts
+from .sign import sign_request
+
+
+@dataclass(frozen=True)
+class TagResult:
+    data: str
+    labelled: bool
+    reason: Optional[str] = None
+    detail: Optional[str] = None
+
+
+class Recensus:
+    """
+    Label an agent's transactions.
+
+        recensus = Recensus(agent_id=..., autonomous=True, w3=w3)
+        account = recensus.wrap(account)
+        account.send_transaction({"to": recipient, "value": 1_000_000})
+    """
+
+    def __init__(
+        self,
+        agent_id: HexLike,
+        framework: int = FRAMEWORK_SDK_PY,
+        autonomous: bool = False,
+        test: bool = False,
+        w3: Any = None,
+        simulate_before_send: bool = True,
+        denylist: Optional[Iterable[str]] = None,
+        deny_selectors: Optional[Iterable[str]] = None,
+        on_unlabelled: Optional[Callable[[Dict[str, Any]], None]] = None,
+        logger: Optional[Callable[[str], None]] = None,
+    ) -> None:
+        self.agent_id = normalize_agent_id(agent_id)
+        self.framework = framework
+        self.flags = LabelFlags(autonomous=autonomous, test=test)
+        self.label = build_label(self.agent_id, framework, self.flags)
+        self.w3 = w3
+        #: RECENSUS-1 §4.3 forbids shipping this off by default.
+        self.simulate_before_send = simulate_before_send
+
+        self._denylist = list(denylist or [])
+        self._deny_selectors = list(deny_selectors or [])
+        self._on_unlabelled = on_unlabelled
+        self._log = logger if logger is not None else (lambda message: warnings.warn(message, stacklevel=2))
+        self._contracts = load_tag_safe_contracts()
+        self._code_cache: Dict[str, bool] = {}
+
+    # ---------------------------------------------------------- manual
+
+    def tag(self, calldata: Optional[HexLike]) -> str:
+        """Append the label.  No safety check, no simulation: you asked."""
+        return append_label(calldata, self.label)
+
+    @staticmethod
+    def parse(calldata: Optional[HexLike]):
+        """Read a label back off any calldata."""
+        return parse_label(calldata)
+
+    # ---------------------------------------------------------- decide
+
+    def _has_code(self, address: str) -> Optional[bool]:
+        if self.w3 is None:
+            return None
+        key = address.lower()
+        if key in self._code_cache:
+            return self._code_cache[key]
+        try:
+            code = self.w3.eth.get_code(self.w3.to_checksum_address(address))
+            result = len(code) > 0
+        except Exception:
+            return None  # unknown: let the shape rules and the simulation decide
+        self._code_cache[key] = result
+        return result
+
+    def decide(self, to: Optional[str], data: Optional[str] = "0x") -> TagResult:
+        """Whether this call may carry the label, from its shape."""
+        data = data or "0x"
+        to_has_code = self._has_code(to) if to else None
+
+        decision = check_safety(
+            CallShape(to=to, data=data, to_has_code=to_has_code),
+            contracts=self._contracts,
+            denylist=self._denylist,
+            deny_selectors=self._deny_selectors,
+        )
+        if not decision.safe:
+            return TagResult(data, False, decision.reason, decision.detail)
+        return TagResult(self.tag(data), True)
+
+    def simulate(self, to: str, tagged: str, untagged: str, value: int = 0, sender: Optional[str] = None) -> TagResult:
+        """
+        The backstop (RECENSUS-1 §4.3).  If the labelled call reverts where the
+        unlabelled one succeeds, drop the label.  If both revert, keep the
+        caller's own call so the error they see is their own.
+        """
+        if self.w3 is None:
+            return TagResult(tagged, True)
+
+        def call(data: str) -> None:
+            tx: Dict[str, Any] = {"to": self.w3.to_checksum_address(to), "data": data}
+            if value:
+                tx["value"] = value
+            if sender:
+                tx["from"] = self.w3.to_checksum_address(sender)
+            self.w3.eth.call(tx)
+
+        try:
+            call(tagged)
+            return TagResult(tagged, True)
+        except Exception as labelled_error:
+            try:
+                call(untagged)
+            except Exception:
+                return TagResult(tagged, True, "SIMULATION_REVERTED_BOTH")
+            return TagResult(untagged, False, "SIMULATION_REVERTED", str(labelled_error).split("\n")[0])
+
+    def prepare(self, to: Optional[str], data: Optional[str] = "0x", value: int = 0, sender: Optional[str] = None) -> TagResult:
+        """The full decide → simulate → fall back pipeline for one call."""
+        data = data or "0x"
+        try:
+            result = self.decide(to, data)
+        except Exception as error:  # nothing about deciding may cost a transaction
+            self._warn(to, "DECIDE_FAILED", str(error))
+            return TagResult(data, False, "DECIDE_FAILED")
+
+        if not result.labelled:
+            self._warn(to, result.reason or "UNSAFE", result.detail)
+            return result
+
+        if self.simulate_before_send and self.w3 is not None and to is not None:
+            try:
+                simulated = self.simulate(to, result.data, data, value, sender)
+            except Exception as error:
+                # The simulation itself failed.  That is not evidence the label
+                # is unsafe, but it is not evidence it is safe either.
+                self._warn(to, "SIMULATION_UNAVAILABLE", str(error))
+                return TagResult(data, False, "SIMULATION_UNAVAILABLE")
+            if not simulated.labelled:
+                self._warn(to, simulated.reason or "SIMULATION_REVERTED", simulated.detail)
+            return simulated
+
+        return result
+
+    # ------------------------------------------------------------ wrap
+
+    def wrap(self, account: Any) -> Any:
+        """
+        Wrap an ``eth_account`` LocalAccount so every ``send_transaction``
+        carries the label.  Everything else passes through untouched.
+        """
+        recensus = self
+        w3 = self.w3
+        if w3 is None:
+            raise ValueError("Recensus(w3=...) is required before wrapping an account: sending needs a provider.")
+
+        class _WrappedAccount:
+            def __init__(self, inner: Any) -> None:
+                self._inner = inner
+
+            def __getattr__(self, name: str) -> Any:
+                return getattr(self._inner, name)
+
+            @property
+            def recensus(self) -> "Recensus":
+                return recensus
+
+            def send_transaction(self, tx: Dict[str, Any]) -> bytes:
+                prepared = recensus.prepare(
+                    tx.get("to"),
+                    tx.get("data", "0x"),
+                    int(tx.get("value", 0) or 0),
+                    self._inner.address,
+                )
+                outgoing = dict(tx)
+                outgoing["data"] = prepared.data
+                outgoing.setdefault("from", self._inner.address)
+                outgoing.setdefault("nonce", w3.eth.get_transaction_count(self._inner.address))
+                outgoing.setdefault("chainId", w3.eth.chain_id)
+                if "gas" not in outgoing:
+                    outgoing["gas"] = w3.eth.estimate_gas(outgoing)
+                if "gasPrice" not in outgoing and "maxFeePerGas" not in outgoing:
+                    outgoing["gasPrice"] = w3.eth.gas_price
+
+                signed = self._inner.sign_transaction(outgoing)
+                raw = getattr(signed, "raw_transaction", None) or getattr(signed, "rawTransaction")
+                return w3.eth.send_raw_transaction(raw)
+
+        return _WrappedAccount(account)
+
+    # ------------------------------------------------------ agent lane
+
+    def sign_request(self, method: str, url: str, account: Any, body: Any = None, **kwargs: Any) -> Dict[str, str]:
+        """Sign an HTTP request so an app can verify it came from this agent (SPEC §8)."""
+        return sign_request(self.agent_id, method, url, account, body, **kwargs)
+
+    # --------------------------------------------------------- private
+
+    def _warn(self, to: Optional[str], reason: str, detail: Optional[str] = None) -> None:
+        if self._on_unlabelled is not None:
+            self._on_unlabelled({"to": to, "reason": reason, "detail": detail})
+        self._log(
+            f"[recensus] sending unlabelled to {to or 'contract deployment'} — {reason}"
+            + (f": {detail}" if detail else "")
+        )
+
+
+__all__ = ["Recensus", "TagResult", "derive_agent_id", "has_label"]

recensus_sdk/safety.py

@@ -0,0 +1,122 @@
+"""
+RECENSUS-1 §4 — when it is safe to append the label.
+
+Mirrors ``packages/spec/src/safety.ts``.  The rule the whole standard rests on
+is that the label must never break a transaction; this module answers "may I
+append here?" from the call shape alone, and the SDK simulates as a backstop.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, Optional, Set
+
+from .label import has_label
+
+#: Selectors that must never carry a trailing label, whatever the target: the
+#: label belongs on the inner call, not on the wrapper.
+NEVER_TAG_SELECTORS = (
+    "0x765e827f",  # EntryPoint.handleOps            (v0.7 / v0.8)
+    "0x1fad948c",  # EntryPoint.handleOps            (v0.6)
+    "0xdbed18e0",  # EntryPoint.handleAggregatedOps  (v0.6)
+    "0x4b1d7cf5",  # EntryPoint.handleAggregatedOps  (v0.7 / v0.8)
+)
+
+
+@dataclass(frozen=True)
+class CallShape:
+    #: Target address; None for a contract deployment.
+    to: Optional[str] = None
+    #: Calldata as it would be sent, before the label.
+    data: str = "0x"
+    #: Whether `to` has code.  None when the caller could not check.
+    to_has_code: Optional[bool] = None
+
+
+@dataclass(frozen=True)
+class SafetyDecision:
+    safe: bool
+    reason: Optional[str] = None
+    detail: Optional[str] = None
+
+
+def selector_of(data: Optional[str]) -> Optional[str]:
+    if not data or len(data) < 10:
+        return None
+    return data[:10].lower()
+
+
+def load_tag_safe_contracts(config_dir: Optional[Path] = None) -> dict:
+    """
+    ``config/labels.json``, when this package is used from inside the repo.
+
+    Published to PyPI there is no config directory, and that is fine: the call
+    shape rules plus the simulation are the real guard, and a missing config
+    file is never a reason to fail a send.
+    """
+    if config_dir is None:
+        here = Path(__file__).resolve()
+        for parent in here.parents:
+            candidate = parent / "config" / "labels.json"
+            if candidate.exists():
+                config_dir = candidate.parent
+                break
+    if config_dir is None:
+        return {}
+    try:
+        return json.loads((config_dir / "labels.json").read_text()).get("contracts", {})
+    except Exception:
+        return {}
+
+
+def check_safety(
+    call: CallShape,
+    contracts: Optional[dict] = None,
+    denylist: Optional[Iterable[str]] = None,
+    deny_selectors: Optional[Iterable[str]] = None,
+) -> SafetyDecision:
+    contracts = contracts if contracts is not None else {}
+    deny: Set[str] = {a.lower() for a in (denylist or [])}
+    deny_sel: Set[str] = {s.lower() for s in (deny_selectors or [])}
+    data = call.data or "0x"
+
+    if has_label(data):
+        return SafetyDecision(False, "ALREADY_LABELLED", "calldata already carries a RECENSUS-1 label")
+
+    if call.to is None:
+        return SafetyDecision(
+            False,
+            "CONTRACT_DEPLOYMENT",
+            "a contract deployment is its own init code; a trailing label would become part of it",
+        )
+
+    to = call.to.lower()
+
+    if to in deny:
+        return SafetyDecision(False, "DENYLISTED", f"{to} is on the operator denylist")
+
+    known = contracts.get(to)
+    if known is not None and known.get("tagSafe") is False:
+        return SafetyDecision(False, "DENYLISTED", f"{known.get('name', to)} is marked tagSafe: false")
+
+    selector = selector_of(data)
+    if selector:
+        if selector in NEVER_TAG_SELECTORS:
+            return SafetyDecision(
+                False, "DENIED_SELECTOR", f"{selector} wraps other calls; label the inner call instead"
+            )
+        if selector in deny_sel:
+            return SafetyDecision(False, "DENIED_SELECTOR", f"{selector} is on the operator selector denylist")
+
+    # RECENSUS-1 §4.2 rule 1: sending real data to an address with no code means
+    # the data IS the message.  A label would corrupt it.
+    if call.to_has_code is False and data not in ("0x", "", None) and len(data) > 2:
+        return SafetyDecision(
+            False,
+            "DATA_TO_EOA",
+            "target has no code and the call carries data; the label would be indistinguishable from that payload",
+        )
+
+    return SafetyDecision(True)

recensus_sdk/sign.py

@@ -0,0 +1,74 @@
+"""
+Agent-lane request signing (SPEC §8), the mirror of ``sdk-ts/src/sign.ts``.
+
+The signed string is canonical and versioned so a server can reconstruct it
+byte for byte::
+
+    recensus-v1\\n<METHOD>\\n<URL>\\n<timestamp>\\n<nonce>\\n<sha256(body) as hex>
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import secrets
+import time
+from typing import Any, Dict, Optional, Union
+
+SIGNING_PREFIX = "recensus-v1"
+
+BodyLike = Union[str, bytes, bytearray, Dict[str, Any], None]
+
+
+def canonical_body(body: BodyLike) -> bytes:
+    if body is None:
+        return b""
+    if isinstance(body, (bytes, bytearray)):
+        return bytes(body)
+    if isinstance(body, str):
+        return body.encode("utf-8")
+    # Separators without spaces, to match JSON.stringify.
+    return json.dumps(body, separators=(",", ":")).encode("utf-8")
+
+
+def body_hash(body: BodyLike) -> str:
+    return "0x" + hashlib.sha256(canonical_body(body)).hexdigest()
+
+
+def canonical_string(method: str, url: str, timestamp: int, nonce: str, body_sha256: str) -> str:
+    return "\n".join([SIGNING_PREFIX, method.upper(), url, str(timestamp), nonce, body_sha256])
+
+
+def random_nonce() -> str:
+    return secrets.token_hex(16)
+
+
+def sign_request(
+    agent_id: str,
+    method: str,
+    url: str,
+    account: Any,
+    body: BodyLike = None,
+    timestamp: Optional[int] = None,
+    nonce: Optional[str] = None,
+) -> Dict[str, str]:
+    """
+    Five headers an app can verify.  ``account`` is an ``eth_account``
+    LocalAccount, or anything with ``address`` and ``sign_message``.
+    """
+    from eth_account.messages import encode_defunct
+
+    ts = timestamp if timestamp is not None else int(time.time())
+    n = nonce if nonce is not None else random_nonce()
+    message = canonical_string(method, url, ts, n, body_hash(body))
+    signed = account.sign_message(encode_defunct(text=message))
+
+    return {
+        "Recensus-Agent": agent_id,
+        "Recensus-Key": account.address,
+        "Recensus-Timestamp": str(ts),
+        "Recensus-Nonce": n,
+        "Recensus-Signature": signed.signature.hex()
+        if signed.signature.hex().startswith("0x")
+        else "0x" + signed.signature.hex(),
+    }

recensus_sdk-1.0.0.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.5
+Name: recensus-sdk
+Version: 1.0.0
+Summary: Label your agent's transactions on Robinhood Chain so they show up on Recensus.
+Project-URL: Homepage, https://recensus.xyz
+Project-URL: Documentation, https://recensus.xyz/docs/get-counted
+Project-URL: Specification, https://recensus.xyz/spec
+License: MIT
+Keywords: ai-agents,evm,recensus,robinhood-chain,web3
+Requires-Python: >=3.11
+Requires-Dist: eth-account>=0.11
+Requires-Dist: eth-hash[pycryptodome]>=0.7
+Requires-Dist: eth-utils>=4.0
+Requires-Dist: web3<8,>=6.20
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# recensus-sdk
+
+Label your agent's transactions on Robinhood Chain so they show up on
+[Recensus](https://recensus.xyz). The Python mirror of `recensus-sdk` on npm —
+same name, same surface, different registry.
+
+```bash
+pip install recensus-sdk
+```
+
+```python
+from recensus_sdk import Recensus, derive_agent_id
+from web3 import Web3
+
+w3 = Web3(Web3.HTTPProvider("https://rpc.mainnet.chain.robinhood.com"))
+
+recensus = Recensus(
+    agent_id=derive_agent_id(operator_address, "price-watcher"),
+    autonomous=True,   # no human approves each send
+    # test=True        # in staging: excluded from every public number
+    w3=w3,
+)
+
+account = recensus.wrap(account)
+account.send_transaction({"to": recipient, "value": 1_000_000})
+```
+
+That is the whole integration. Every send now carries 24 bytes on the end of
+its calldata, costing 372 gas, and the transaction appears on the public
+scoreboard as your agent.
+
+## The label never breaks a transaction
+
+Three layers, in order:
+
+1. **Call shape.** The label goes only where trailing calldata is inert.
+   Contract deployments, EntryPoint `handleOps`, data sent to an address with
+   no code, and anything marked `tagSafe: false` are refused outright.
+2. **Simulation.** Before sending, the labelled call is simulated. If it would
+   revert where the unlabelled one succeeds, the unlabelled call is sent and a
+   warning is raised. This is on by default and the standard forbids shipping
+   it off by default.
+3. **A catch-all.** Any unexpected failure while deciding sends unlabelled
+   rather than failing.
+
+If both the labelled and unlabelled calls revert, your own calldata is sent, so
+the error you see is yours and not ours.
+
+## Without web3
+
+The label itself has no dependencies, so a reader or writer can live anywhere:
+
+```python
+from recensus_sdk import build_label, parse_label
+
+label = build_label("0x9f2a0c1e7b5d4a8f36c20e91d7b4a5c3", framework=0x0003)
+data  = existing_calldata + label[2:]
+
+parse_label(data).agent_id   # '0x9f2a0c1e7b5d4a8f36c20e91d7b4a5c3'
+```
+
+`parse_label` returns `None` rather than raising for anything that is not a
+well-formed label of a version it knows. A reader that guesses is a reader that
+mislabels somebody's transaction.
+
+## The agent lane
+
+```python
+headers = recensus.sign_request("POST", "https://api.example.com/v1/thing",
+                             account, body={"hello": "world"})
+requests.post(url, json=body, headers=headers)
+```
+
+Five headers an app can verify with `requireRecensus` from `recensus-sdk` on
+npm, so a
+labelled agent can be given its own rate limits instead of being throttled like
+a spam bot.
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+pytest
+```
+
+The test suite checks this implementation against the same vectors as the
+TypeScript one, so the two cannot drift.

recensus_sdk-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+recensus_sdk/__init__.py,sha256=nLdhK3B6Xv_ZZoLxwm4_pNcgisupBNIGSfBjTkdhs30,1873
+recensus_sdk/frameworks.py,sha256=t8TFq3DGYmXAcXw7Yho6YBUYwhWJ-lsqJcYw6e3RHGs,528
+recensus_sdk/label.py,sha256=Ydw0LPj3MNWU4t_aglaZX1BqFujB8ayjCwWOuv1I02o,6823
+recensus_sdk/recensus.py,sha256=c9Ur8XpS2a1bzSXe3HWzjInZpZ2Ct4SOZOzLaWBJyCs,9464
+recensus_sdk/safety.py,sha256=jWGXeahrGL4WBwTjp37zYoQBBEaxYw17gjF2TJuklU0,4236
+recensus_sdk/sign.py,sha256=zdeaGG8-htGYp4Ay35mjYHa6XujffLWxopkHERBv8r0,2190
+recensus_sdk-1.0.0.dist-info/METADATA,sha256=VWhBjXN1z5mg20owuIkunTSNIHZUXRzCIA4TQYbiDfg,3430
+recensus_sdk-1.0.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+recensus_sdk-1.0.0.dist-info/RECORD,,

recensus_sdk-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.3
+Root-Is-Purelib: true
+Tag: py3-none-any