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.

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
from rcan.qos import QoSLevel
from rcan.consent import ConsentRequest

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

# 2. Gate on AI confidence before acting
gate = ConfidenceGate(threshold=0.8)
confidence = 0.91

if gate.allows(confidence):
    msg = RCANMessage(
        cmd="move_forward",
        target=uri,
        params={"distance_m": 1.0},
        confidence=confidence,
        model_identity="gemini-2.5-flash",
    )

# 3. Replay attack prevention — deduplicate incoming messages
cache = ReplayCache(window_seconds=300)
if cache.is_replay(msg.msg_id):
    raise ValueError("Replay attack detected")
cache.record(msg.msg_id)

# 4. Tamper-evident audit chain — every action sealed and linked
chain = AuditChain(secret="your-hmac-secret")
chain.append(CommitmentRecord(
    action="move_forward",
    robot_uri=str(uri),
    confidence=confidence,
    model_identity="gemini-2.5-flash",
    safety_approved=True,
))
chain.verify_all()  # raises if chain is tampered

# 5. Request human consent before a sensitive action
req = ConsentRequest(
    action="open_gripper",
    robot_uri=str(uri),
    requester="operator-alice",
    scope="control",
)
print(req.to_json())

What's in v0.6.0

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.offline import OfflineMode
from rcan.safety import SafetyInvariant

mode = OfflineMode()
mode.assert_estop_reachable()   # raises if ESTOP path is blocked

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 — 587 tests, 0 skipped. 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. The appendix is proposed in rcan-spec#221 and has not been merged.

import json
from rcan.assurance import verify_chain, audit_authority, replay_against_envelope

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),
]
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.
• Physical assurance levels A1 to A3 are a separate axis from RCAN protocol conformance levels L1 to L4. An L3 robot can be A1, and neither level implies the other. An A-level is self-declared unless third-party evidence accompanies it.

Conformance is not certification.

Ecosystem

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.