recensus-sdk 1.0.0__tar.gz

recensus_sdk-1.0.0/.gitignore

@@ -0,0 +1,44 @@
+node_modules/
+dist/
+build/
+.next/
+out/
+coverage/
+.turbo/
+*.tsbuildinfo
+.env
+.env.local
+.env.*.local
+!.env.example
+.DS_Store
+.data/
+*.log
+.vercel/
+# Generated from config/chains.json at build time (scripts/gen-manifest.mjs).
+# Unanchored on purpose: a leading path would be anchored to the repo root and
+# would miss apps/web/public/, which is where they are actually written.
+**/llms.txt
+**/llms-full.txt
+__pycache__/
+*.egg-info/
+.venv/
+.pytest_cache/
+cache/
+broadcast/
+.venv/
+lh*.json
+
+# Foundry
+contracts/out/
+contracts/cache/
+contracts/lib/
+# Run receipts, including local anvil runs. The deployed addresses that
+# matter go in config/site.json, not here.
+contracts/broadcast/
+
+# Vercel CLI: the project link and the OIDC token it pulls.
+#
+# The CLI also appends a blanket `.env*` here, which would take `.env.example`
+# with it — and CLAUDE.md rule 4 requires that one committed. The env rules at
+# the top of this file already cover the real ones, so it is removed on sight.
+.vercel/

recensus_sdk-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,87 @@
+# 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/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "recensus-sdk"
+version = "1.0.0"
+description = "Label your agent's transactions on Robinhood Chain so they show up on Recensus."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+keywords = ["robinhood-chain", "ai-agents", "recensus", "web3", "evm"]
+# eth-hash needs an explicit backend: eth-utils declares the interface but not
+# an implementation, and derive_agent_id works without web3, so it cannot be
+# left to web3 to pull one in.
+dependencies = [
+  "web3>=6.20,<8",
+  "eth-account>=0.11",
+  "eth-utils>=4.0",
+  "eth-hash[pycryptodome]>=0.7",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.urls]
+Homepage = "https://recensus.xyz"
+Documentation = "https://recensus.xyz/docs/get-counted"
+Specification = "https://recensus.xyz/spec"
+
+[tool.hatch.build.targets.wheel]
+packages = ["recensus_sdk"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

recensus_sdk-1.0.0/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-1.0.0/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-1.0.0/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-1.0.0/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-1.0.0/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-1.0.0/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/tests/test_label.py

@@ -0,0 +1,177 @@
+"""
+The Python label implementation, checked against the same expectations as the
+TypeScript one.
+
+``test_parity.py`` runs the TypeScript implementation over the same vectors, so
+the two cannot drift apart silently.
+"""
+
+import pytest
+
+from recensus_sdk import (
+    FLAG_AUTONOMOUS,
+    FLAG_TEST,
+    LABEL_BYTES,
+    MAGIC,
+    VERSION,
+    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,
+)
+
+ID = "0x9f2a0c1e7b5d4a8f36c20e91d7b4a5c3"
+
+
+class TestBuildLabel:
+    def test_produces_exactly_24_bytes_ending_in_the_magic(self):
+        label = build_label(ID, 0x0002, LabelFlags(autonomous=True))
+        assert len(label) == 2 + LABEL_BYTES * 2
+        assert label.endswith(MAGIC)
+        assert label == "0x9f2a0c1e7b5d4a8f36c20e91d7b4a5c30002010150554c53"
+
+    def test_defaults(self):
+        assert build_label(ID) == "0x9f2a0c1e7b5d4a8f36c20e91d7b4a5c30000000150554c53"
+
+    def test_accepts_bytes(self):
+        assert build_label(b"\xab" * 16) == f"0x{'ab' * 16}0000000150554c53"
+
+    def test_rejects_an_agent_id_that_is_not_16_bytes(self):
+        with pytest.raises(RecensusLabelError, match="exactly 16 bytes"):
+            build_label("0xdead")
+        with pytest.raises(RecensusLabelError):
+            build_label("0x" + "aa" * 17)
+
+    def test_rejects_an_out_of_range_framework(self):
+        with pytest.raises(RecensusLabelError, match="0-65535"):
+            build_label(ID, 0x1_0000)
+        with pytest.raises(RecensusLabelError, match="0-65535"):
+            build_label(ID, -1)
+
+    def test_rejects_reserved_flag_bits(self):
+        with pytest.raises(RecensusLabelError, match="reserved"):
+            build_label(ID, 0, 0b0000_0100)
+        with pytest.raises(RecensusLabelError, match="reserved"):
+            build_label(ID, 0, 0xFF)
+
+    @pytest.mark.parametrize(
+        "flags",
+        [LabelFlags(), LabelFlags(autonomous=True), LabelFlags(test=True), LabelFlags(True, True)],
+    )
+    def test_round_trips_every_legal_flag_combination(self, flags):
+        parsed = parse_label(build_label(ID, 0, flags))
+        assert parsed.flags == flags
+
+
+class TestParseLabel:
+    label = build_label(ID, 0x0010, LabelFlags(autonomous=True, test=True))
+
+    def test_parses_a_bare_label(self):
+        parsed = parse_label(self.label)
+        assert parsed.agent_id == ID
+        assert parsed.framework == 0x0010
+        assert parsed.flags == LabelFlags(autonomous=True, test=True)
+        assert parsed.flags_byte == FLAG_AUTONOMOUS | FLAG_TEST
+        assert parsed.version == VERSION
+
+    def test_parses_a_label_on_real_calldata(self):
+        transfer = "0xa9059cbb" + "0" * 24 + "ca" * 20 + "0" * 58 + "4c4b40"
+        assert parse_label(transfer + self.label[2:]).agent_id == ID
+
+    @pytest.mark.parametrize(
+        "value",
+        [None, "", "0x", "not hex", "0xzz", "0xa9059cbb", "0x50554c53", "0x" + "00" * 19 + "50554c53"],
+    )
+    def test_returns_none_never_raises_for_anything_that_is_not_a_label(self, value):
+        assert parse_label(value) is None
+
+    def test_returns_none_for_an_unknown_version_rather_than_guessing(self):
+        assert parse_label(build_label(ID, 0, None, version=0x02)) is None
+
+    def test_returns_none_when_a_reserved_flag_bit_is_set(self):
+        assert parse_label(f"0x{ID[2:]}0000fc0150554c53") is None
+
+    def test_is_case_insensitive(self):
+        assert parse_label(self.label.upper().replace("0X", "0x")) is not None
+
+    def test_ignores_odd_length_hex(self):
+        assert parse_label("0xabc") is None
+
+    def test_accepts_bytes(self):
+        assert parse_label(bytes.fromhex(self.label[2:])).agent_id == ID
+
+
+class TestAppendAndStrip:
+    label = build_label(ID)
+
+    def test_appends_to_empty_calldata(self):
+        assert append_label("0x", self.label) == self.label
+        assert append_label(None, self.label) == self.label
+
+    def test_never_stacks_two_labels(self):
+        once = append_label("0xa9059cbb", self.label)
+        assert append_label(once, self.label) == once
+
+    def test_strips_back_to_the_original(self):
+        base = "0xa9059cbb" + "0" * 63 + "1"
+        assert strip_label(append_label(base, self.label)) == base
+
+    def test_leaves_unlabelled_calldata_alone(self):
+        assert strip_label("0xa9059cbb") == "0xa9059cbb"
+
+    def test_has_label_agrees_with_parse_label(self):
+        assert has_label(self.label) is True
+        assert has_label("0xa9059cbb") is False
+
+
+class TestDeriveAgentId:
+    def test_matches_keccak_of_operator_and_name(self):
+        from eth_utils import keccak
+
+        operator = "0x1111111111111111111111111111111111111111"
+        expected = "0x" + keccak(bytes.fromhex(operator[2:]) + b"price-watcher").hex()[:32]
+        assert derive_agent_id(operator, "price-watcher") == expected
+
+    def test_is_stable_and_distinct(self):
+        op = "0x2222222222222222222222222222222222222222"
+        a = derive_agent_id(op, "alpha")
+        b = derive_agent_id(op, "beta")
+        c = derive_agent_id("0x3333333333333333333333333333333333333333", "alpha")
+        assert len({a, b, c}) == 3
+        assert derive_agent_id(op, "alpha") == a
+
+    def test_rejects_a_non_address_operator(self):
+        with pytest.raises(RecensusLabelError, match="20-byte address"):
+            derive_agent_id("0xdead", "x")
+
+
+class TestHelpers:
+    def test_flags_round_trip(self):
+        assert flags_to_byte(LabelFlags(True, True)) == 3
+        assert byte_to_flags(3) == LabelFlags(True, True)
+        assert flags_to_byte(None) == 0
+
+    def test_short_agent_id(self):
+        assert short_agent_id(ID) == "0x9f2a0c1e…d7b4a5c3"
+
+    def test_normalize_accepts_bytes_and_bare_hex(self):
+        assert normalize_agent_id(bytes.fromhex(ID[2:])) == ID
+        assert normalize_agent_id(ID[2:]) == ID
+
+
+class TestCollisionBehaviour:
+    def test_does_not_claim_calldata_too_short_to_be_a_label(self):
+        assert parse_label("0x50554c5350554c53") is None
+
+    def test_does_claim_24_bytes_ending_in_the_magic(self):
+        # RECENSUS-1 §5.1: a label is a claim, never proof. Attribution is what
+        # keeps this honest, not the parser.
+        assert parse_label("0x" + "11" * 19 + "000150554c53") is not None

recensus_sdk-1.0.0/tests/test_parity.py

@@ -0,0 +1,141 @@
+"""
+The two SDKs must produce the same bytes.
+
+This runs the TypeScript implementation over a set of vectors and checks the
+Python one agrees, so a change to either side that breaks the other fails here
+rather than on someone's chain.
+
+Skipped when Node is not available, because a Python-only environment should
+still be able to run the rest of the suite.
+"""
+
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from recensus_sdk import LabelFlags, build_label, derive_agent_id, parse_label
+
+REPO = Path(__file__).resolve().parents[3]
+SPEC_DIST = REPO / "packages" / "spec" / "dist" / "index.js"
+
+VECTORS = [
+    {"agentId": "0x9f2a0c1e7b5d4a8f36c20e91d7b4a5c3", "framework": 0x0002, "autonomous": True, "test": False},
+    {"agentId": "0x00000000000000000000000000000000", "framework": 0x0000, "autonomous": False, "test": False},
+    {"agentId": "0xffffffffffffffffffffffffffffffff", "framework": 0xFFFF, "autonomous": True, "test": True},
+    {"agentId": "0x1122334455667788990011223344556f", "framework": 0x0010, "autonomous": False, "test": True},
+    {"agentId": "0xabcdef0123456789abcdef0123456789", "framework": 0x0003, "autonomous": False, "test": False},
+]
+
+CALLDATA = [
+    "0x",
+    "0xa9059cbb",
+    "0x095ea7b3" + "0" * 128,
+    "0x" + "de" * 200,
+]
+
+
+def node_available() -> bool:
+    return shutil.which("node") is not None and SPEC_DIST.exists()
+
+
+pytestmark = pytest.mark.skipif(
+    not node_available(),
+    reason="needs node and a built packages/spec (pnpm --filter @recensus/spec build)",
+)
+
+
+def run_typescript(script: str) -> dict:
+    result = subprocess.run(
+        ["node", "--input-type=module", "-e", script],
+        capture_output=True,
+        text=True,
+        cwd=REPO,
+        env={**os.environ, "NODE_NO_WARNINGS": "1"},
+        timeout=60,
+    )
+    if result.returncode != 0:
+        pytest.fail(f"the TypeScript side failed:\n{result.stderr}")
+    return json.loads(result.stdout)
+
+
+def test_build_label_matches_typescript():
+    script = f"""
+import {{ buildLabel }} from '{SPEC_DIST.as_posix()}';
+const vectors = {json.dumps(VECTORS)};
+console.log(JSON.stringify(vectors.map((v) =>
+  buildLabel({{ agentId: v.agentId, framework: v.framework, flags: {{ autonomous: v.autonomous, test: v.test }} }})
+)));
+"""
+    from_ts = run_typescript(script)
+    from_py = [
+        build_label(v["agentId"], v["framework"], LabelFlags(autonomous=v["autonomous"], test=v["test"]))
+        for v in VECTORS
+    ]
+    assert from_py == from_ts
+
+
+def test_parse_label_matches_typescript():
+    labels = [
+        build_label(v["agentId"], v["framework"], LabelFlags(v["autonomous"], v["test"]))
+        for v in VECTORS
+    ]
+    cases = [data + label[2:] for label in labels for data in CALLDATA] + CALLDATA
+
+    script = f"""
+import {{ parseLabel }} from '{SPEC_DIST.as_posix()}';
+const cases = {json.dumps(cases)};
+console.log(JSON.stringify(cases.map((c) => {{
+  const p = parseLabel(c);
+  return p === null ? null : {{ agentId: p.agentId, framework: p.framework, flagsByte: p.flagsByte, version: p.version }};
+}})));
+"""
+    from_ts = run_typescript(script)
+
+    from_py = []
+    for case in cases:
+        parsed = parse_label(case)
+        from_py.append(
+            None
+            if parsed is None
+            else {
+                "agentId": parsed.agent_id,
+                "framework": parsed.framework,
+                "flagsByte": parsed.flags_byte,
+                "version": parsed.version,
+            }
+        )
+
+    assert from_py == from_ts
+
+
+def test_derive_agent_id_matches_typescript():
+    pairs = [
+        ("0x1111111111111111111111111111111111111111", "price-watcher"),
+        ("0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266", "claude"),
+        ("0x0000000000000000000000000000000000000000", ""),
+        ("0xabcdefabcdefabcdefabcdefabcdefabcdefabcd", "an agent with spaces and é"),
+    ]
+
+    script = f"""
+import {{ deriveAgentId }} from '{SPEC_DIST.as_posix()}';
+import {{ keccak256 }} from '{(REPO / "node_modules" / "viem" / "_esm" / "index.js").as_posix()}';
+const pairs = {json.dumps(pairs)};
+console.log(JSON.stringify(pairs.map(([op, name]) => deriveAgentId(op, name, (b) => keccak256(b)))));
+"""
+    from_ts = run_typescript(script)
+    from_py = [derive_agent_id(op, name) for op, name in pairs]
+    assert from_py == from_ts
+
+
+def test_reserved_flag_bits_are_rejected_on_both_sides():
+    script = f"""
+import {{ parseLabel }} from '{SPEC_DIST.as_posix()}';
+const malformed = '0x' + '11'.repeat(16) + '0000' + 'fc' + '01' + '50554c53';
+console.log(JSON.stringify(parseLabel(malformed)));
+"""
+    assert run_typescript(script) is None
+    assert parse_label("0x" + "11" * 16 + "0000" + "fc" + "01" + "50554c53") is None