rcan-py

Python SDK for the RCAN protocol. Build robots that communicate securely, audit every action, enforce safety gates locally, and register with the Robot Registry Foundation. Pinned protocol version: see the live compatibility matrix.

Spec: rcan.dev · Docs: docs.rcan.dev · Package: PyPI rcan

Where this fits in the stack

This repo is the Python SDK layer — the library any Python planner, gateway, or driver links against to speak RCAN. Everything below is independent; adopt one, or all seven.

Install

pip install rcan

Optional extras:

pip install rcan[http]    # httpx for registry client
pip install rcan[crypto]  # cryptography for Ed25519 signing
pip install rcan[all]     # everything

Quick Start

from rcan import RobotURI, RCANMessage, ConfidenceGate
from rcan.audit import AuditChain, CommitmentRecord
from rcan.replay import ReplayCache

# 1. Address a robot
uri = RobotURI.build(manufacturer="acme", model="arm", version="v2", device_id="unit-001")
print(uri)  # rcan://registry.rcan.dev/acme/arm/v2/unit-001

# 2. Gate on model confidence before acting
gate = ConfidenceGate(threshold=0.8)
confidence = 0.91
if not gate.allows(confidence):
    raise SystemExit("confidence below threshold")

msg = RCANMessage(
    cmd="move_forward",
    target=uri,
    params={"distance_m": 1.0},
    confidence=confidence,
)

# 3. Replay prevention: reject a msg_id seen inside the window
cache = ReplayCache(window_s=30)
allowed, reason = cache.check_and_record(msg.msg_id, msg.timestamp)
assert allowed, reason
allowed, reason = cache.check_and_record(msg.msg_id, msg.timestamp)
assert not allowed  # the same msg_id again is a replay

# 4. HMAC-chained audit log
chain = AuditChain(secret="your-hmac-secret")
chain.append(CommitmentRecord(
    action="move_forward",
    params={"distance_m": 1.0},
    robot_uri=str(uri),
    confidence=confidence,
    model_identity="example-model",
    safety_approved=True,
))
assert chain.verify_all()

print(msg.to_json())

Modules

Protocol 66 Compliance

Protocol 66 is RCAN's safety layer. Key invariants enforced by this SDK:

• ESTOP always delivered — QoSLevel.EXACTLY_ONCE, never blocked by QoS downgrade
• Local safety wins — offline module enforces local limits even without cloud connectivity
• Confidence gates run locally — ConfidenceGate never makes a network call
• Audit chain required — AuditChain.verify_all() before executing any flagged command

from rcan import RCANMessage
from rcan.offline import OfflineModeManager
from rcan.safety import make_estop_message, validate_safety_message

robot = "rcan://registry.rcan.dev/acme/arm/v2/unit-001"
estop = make_estop_message(robot, reason="operator button")
assert validate_safety_message(estop) == []

offline = OfflineModeManager()
offline.go_offline()
allowed, why = offline.can_accept_command(RCANMessage(cmd="estop", target=robot))
assert allowed, why  # ESTOP is never blocked, even offline
allowed, why = offline.can_accept_command(
    RCANMessage(cmd="move_forward", target=robot), local_network=False
)
assert not allowed  # remote commands are blocked while offline

CLI

# Validate a robot config (L1/L2/L3 conformance)
rcan-validate config myrobot.rcan.yaml

# Validate a RCAN message
rcan-validate message command.json

# Verify an audit chain
rcan-validate audit audit.jsonl

# Validate a Robot URI
rcan-validate uri 'rcan://registry.rcan.dev/acme/arm/v2/unit-001'

# Run all checks
rcan-validate all myrobot.rcan.yaml

Spec Compliance

Implements the RCAN protocol; run pytest for the current test count. See the live compatibility matrix for the pinned version this SDK targets.

Covered sections: §1 Robot URI · §2 RBAC · §3 Message Format · §5 Authentication · §5.3 QoS · §6 Safety Invariants · §8.3 Replay Prevention · §8.4 Clock Sync · §8.5 Sender Type · §8.6 Key Lifecycle · §8.7 Level of Assurance · §9 Capabilities · §11 Behavior Scripts · §12 Command Delegation · §13 Revocation · §14 Offline Mode · §16 AI Accountability · §17 Distributed Registry · §18 Federation · §19 Constrained Transport · §21 Registry Integration

Physical assurance (RCAN Appendix C, informative)

rcan.assurance ports the reference verifier from RCAN Appendix C, the Physical Assurance Profile. The appendix is informative and these helpers are optional: nothing in RCAN requires them, and using them changes no conformance level.

RCAN is one open implementation of the Bounded Embodiment property; the property and its vendor-neutral method do not depend on RCAN.

import json
from rcan.assurance import (
    audit_authority, check_envelope_recovery, check_stop_fields,
    replay_against_envelope, verify_chain,
)

chain = json.load(open("gate-decisions.json"))   # list of gate_decision records
envelope = json.load(open("envelope.json"))

findings = [
    *verify_chain(chain, expected_head=None),    # pass an anchored head if you hold one
    *audit_authority(chain, envelope),
    *replay_against_envelope(chain, envelope),
    *check_envelope_recovery(envelope),          # stop.safe_state, recovery.*
    *check_stop_fields(chain),                   # stop_kind, reason_returned
]
for f in findings:
    print(f.seq, f.code, f.detail)

What these helpers do and do not tell you:

• They verify evidence, not robots. They check that a gate_decision log is internally consistent, that executed authority-gated commands name a principal and an authority, and that applied commands sit inside the declared envelope. A passing chain says nothing about whether the machine behaved as logged.
• Without an anchored head, verify_chain cannot detect records removed from the end of a chain. Pass expected_head when you hold the last hash from somewhere the log writer cannot rewrite.
• replay_against_envelope judges only linear_mps, angular_radps and a 2D target. Any other applied field is reported as UNCHECKED_FIELDS, never silently passed.
• check_envelope_recovery and check_stop_fields check only the optional recovery fields from Appendix C.1.3 (stop.safe_state, recovery, stop_kind, reason_returned) and their conditional rules: stop_kind only with stop, reason_returned never with allow, estop_reset only manual. They are not a full JSON Schema validation.
• Physical assurance levels BE-1 to BE-3 (BE_LEVELS; named A1 to A3 before rcan-spec #226, still exported as ASSURANCE_LEVELS) are a separate axis from RCAN protocol conformance levels L1 to L4. An L3 robot can be BE-1, and neither level implies the other. A BE-level is self-declared unless third-party evidence accompanies it.

Conformance is not certification.

Ecosystem

Current versions: see the live compatibility matrix.

Contributing

Issues and PRs welcome at github.com/RobotRegistryFoundation/rcan-py.

Spec discussions: github.com/RobotRegistryFoundation/rcan-spec/issues

License

MIT

Stewarded by the Robot Registry Foundation. RCAN is an open standard; issues and PRs welcome. See CONTRIBUTING.md.