SmartClaws Protocol Specification

General
1

SmartClaws Protocol Specification

Executive Summary: The SmartClaws Protocol replaces direct network connectivity with a blockchain-based coordination layer between OpenClaw AI Agents and IoT devices. Devices remain private behind NATs and firewalls, while OpenClaw AI Agents operate without requiring network access. Discovery, authorization, execution, and payment are handled programmatically via smart contracts, enabling secure, global, and trustless interaction between agents and physical infrastructure. This architectural shift eliminates inbound ports, removes vendor lock-in, and enables fully composable automation.

1. Introduction

The SmartClaws Protocol defines a blockchain-based coordination layer that enables asynchronous, permissioned interaction between OpenClaw AI Agents and IoT devices without requiring direct network connectivity.

In conventional architectures, communication between software agents and physical devices relies on network-level primitives, including IP addressing, inbound connectivity, and service endpoints. These requirements introduce operational constraints such as firewall traversal, NAT compatibility, credential distribution, and dependency on centralized infrastructure for discovery and routing.

SmartClaws replaces network-based communication with a shared, on-chain transaction log. All interactions between agents and devices are expressed as messages appended to this log and are processed asynchronously by participating entities.

Under this model:

  • OpenClaw AI Agents publish task requests, commands, or coordination data as messages to designated channels.
  • IoT devices, operating within private networks, monitor relevant channels, process messages addressed to them, and execute corresponding actions locally.
  • Devices publish results, telemetry, or acknowledgments back to the blockchain via associated output channels.
  • Authorization, discovery, and access control are enforced at the smart contract level.

No direct communication occurs between agents and devices. All coordination is mediated through deterministic on-chain state.

1.1 Design Goals

  • Network Independence: Eliminate the requirement for inbound connectivity, public endpoints, or routable device addresses.
  • Asynchronous Coordination: Support decoupled interaction between agents and devices using a persistent, append-only message log.
  • Deterministic Execution Model: Ensure that all interactions are represented as immutable state transitions observable by all participants.
  • Permissioned Access Control: Enforce publishing and interaction rights through smart contract–defined authorization mechanisms.
  • Composability: Provide a uniform interface for interaction across heterogeneous devices and agents.

1.2 System Model

The protocol defines the following primary actors:

  • Agents: Autonomous software entities that generate and consume messages to coordinate actions.
  • Devices: Physical or embedded systems that execute tasks and produce observable outputs.
  • Channels: Smart contract–managed data structures representing append-only logs of messages.

Agents and devices interact exclusively through channels. Each participant maintains its own read-state (e.g., last processed offset) and is responsible for ensuring reliable message consumption.

1.3 Communication Model

  1. Append-Only Messaging: Messages are appended to channels as opaque byte payloads. Each message is assigned a monotonically increasing offset.
  2. Eventual Processing: Consumers (agents or devices) read messages from channels and process them independently. The protocol does not enforce synchronous execution.
  3. Bounded Storage: Channels implement capacity limits using a circular buffering mechanism. Older messages MAY be pruned when capacity constraints are reached.
  4. Stateless Coordination Layer: The protocol does not maintain execution state beyond message storage and authorization. Application-level semantics are implemented by agents and devices.

1.4 Scope

The SmartClaws Protocol specifies:

  • Contract interfaces for channel management, device and agent registration, and message publication.
  • Authorization mechanisms governing write access to channels.
  • Message retrieval semantics and error conditions.

1.5 Example Interaction: Temperature Monitoring and Climate Control

Scenario

A temperature sensor periodically reports ambient temperature, and an OpenClaw AI Agent monitors this data to control an air conditioning (AC) unit.

Components

  • Temperature Sensor Device: Publishes temperature readings to its outgoing channel.
  • Air Conditioner Device: Receives control commands via its incoming channel.
  • OpenClaw AI Agent: Reads temperature data, evaluates conditions, and issues commands.

Interaction Flow

  1. Telemetry Publication: The sensor measures temperature (e.g., 28°C) and publishes it to its outgoing channel.
  2. Agent Consumption: The Agent reads from the sensor’s outgoing channel and updates internal state.
  3. Decision Logic: The agent evaluates a condition (e.g., temperature > 25°C) and determines cooling is required.
  4. Command Publication: The agent publishes "SET_COOLING_MODE" to the AC’s incoming channel.
  5. Device Execution: The AC monitors its incoming channel, retrieves the command, and activates cooling.
  6. Optional Feedback: The AC publishes "COOLING_ON" to its outgoing channel for status observation.

2. Solidity API Specification

2.1 SmartClaws Contract

The global entry point for protocol management, deployment, and discovery.

2.1.1 createChannel

  • Signature: createChannel(address _ownerAddress, uint256 _maxCapacityBytes) external returns (address channel)
  • Permissions: Public.
  • Parameters:
    • _ownerAddress: Initial wallet address granted administrative control.
    • _maxCapacityBytes: Total byte limit for the log before pruning begins. Must be positive.
  • Returns: address channel: Unique address of the newly deployed channel contract.
  • Events: Emits ChannelCreated(address channel, address owner).

2.1.2 deleteChannel

  • Signature: deleteChannel(address _channelId) external
  • Permissions: Only the current Channel Owner.
  • Events: Emits ChannelDeleted(address channel).
  • Note: The channel contract remains deployed and all read methods continue to function.

2.1.3 registerDeviceGroup

  • Signature: registerDeviceGroup(string calldata _deviceGroupName, string calldata _skills) external returns (address deviceGroup)
  • Parameters: _skills is an OpenClaw-like SKILLS.md file describing capabilities.
  • Returns: address deviceGroup: Contract address of the registered device group.
  • Events: Emits DeviceGroupRegistered(address deviceGroup, string deviceGroupName).

2.1.4 unregisterDeviceGroup

  • Signature: unregisterDeviceGroup(address _deviceGroup) external
  • Permissions: Only the group administrator.
  • Events: Emits DeviceGroupUnregistered(address deviceGroup).
  • Note: Removes group from registry and disables future registrations. Existing devices/channels remain functional.

2.1.5 registerAgent

  • Signature: registerAgent(string calldata _agentId, string calldata _metadata) external returns (address agent)
  • Returns: address agent: Contract address of the newly registered agent.
  • Events: Emits AgentRegistered(address agent, string agentId).
  • Note: The caller becomes the owner of the newly deployed Agent contract.

2.1.6 unregisterAgent

  • Signature: unregisterAgent(address _agent) external
  • Permissions: Only the agent owner.
  • Events: Emits AgentUnregistered(address agent).
  • Note: Disables future publishing. Existing channels remain deployed and readable.

2.2 Channel Contract

The interaction layer for specific message streams.

2.2.1 publishMessage

  • Signature: publishMessage(bytes calldata _payload) external
  • Permissions: Only authorized publishers.
  • Logic: Increments offset. If totalBytes > maxCapacityBytes, prunes oldest messages.
  • Events: Emits MessagePublished(address channel, uint256 offset).
  • Notes:
    • The offset of the first message in a channnel is zero.
    • Offsets increment by one per message.
    • Total bytes is the sum of all payload lengthes of all messages in the channel.
    • If payload > maxCapacityBytes, transaction reverts.

2.2.2 changeOwner

  • Signature: changeOwner(address _newOwnerAddress) external
  • Permissions: Only current Channel Owner.

2.2.3 addAuthorizedPublisherToChannel

  • Signature: addAuthorizedPublisherToChannel(address _publisher) external
  • Permissions: Only Channel Owner.
  • Note: Reverts if _publisher is already authorized or is the Channel Owner.

2.2.4 removeAuthorizedPublisherFromChannel

  • Signature: removeAuthorizedPublisherFromChannel(address _publisher) external
  • Permissions: Only Channel Owner.
  • Note: Reverts if _publisher is not currently authorized or is the Channel Owner.

2.2.5 Channel Read API (Views)

2.2.5.1 readMessage
  • Signature: readMessage(uint256 _offset) external view returns (bytes memory payload)
  • Logic: Returns bytes at offset. Reverts with "Message Pruned" or "Invalid Offset".
2.2.5.2 getLatestMessageOffset
  • Logic: Returns the latest offset. Reverts if channel is empty.
2.2.5.3 getOldestMessageOffset
  • Logic: Returns the oldest available offset. Reverts if channel is empty.
2.2.5.4 getMessageCount
  • Logic: getLatestMessageOffset() - getOldestMessageOffset() + 1. Returns zero if empty.
2.2.5.5 isAuthorizedPublisher
  • Signature: isAuthorizedPublisher(address _publisher) external view returns (bool)
2.2.5.6 getAuthorizedPublisherAddresses
  • Logic: Returns array of all authorized publishers.
2.2.5.7 getMaxCapacityBytes
  • Logic: Returns total storage capacity limit in bytes.

2.3 Device Group Contract

Manages individual device identities and their association with channels.

2.3.1 registerDevice

  • Signature: registerDevice(string calldata _deviceId) external returns (address device)
  • Permissions: Only group administrator.
  • Returns: address device: Contract address of the specific device.
  • Events: Emits DeviceRegistered(address device, string deviceId).

2.3.2 unregisterDevice

  • Signature: unregisterDevice(address _device) external
  • Permissions: Only group administrator.
  • Events: Emits DeviceUnregistered(address device).
  • Note: Revokes publishing permissions from all associated channels.

2.3.3 changeOwner

  • Signature: changeOwner(address _newOwnerAddress) external
  • Permissions: Only current Group Owner.

2.4 Device Contract

Represents an individual device with fixed incoming and outgoing channels.

2.4.1 getIncomingMessagesChannel

  • Signature: getIncomingMessagesChannel() external view returns (address channel)

2.4.2 getOutgoingMessagesChannel

  • Signature: getOutgoingMessagesChannel() external view returns (address channel)

2.6 Agent Contract

Represents an individual OpenClaw AI Agent with fixed channels.

2.6.1 getIncomingMessagesChannel

  • Signature: getIncomingMessagesChannel() external view returns (address channel)

2.6.2 getOutgoingMessagesChannel

  • Signature: getOutgoingMessagesChannel() external view returns (address channel)

2.6.3 changeOwner

  • Signature: changeOwner(address _newOwnerAddress) external
  • Permissions: Only current Agent Owner.
  • Events: Emits AgentOwnerChanged(address indexed previousOwner, address indexed newOwner).

2.7 Spec Notes

  • All address parameters must be non-zero.

3. Real-World Examples

3.1 Smart Building Energy Optimization

Scenario: A building contains multiple sensors and actuators. An OpenClaw AI Agent optimizes energy usage in real time.

  • Flow: Sensors publish data; Agent aggregates and determines actions; Commands (e.g., "LIGHTS_OFF") are published to device channels.
  • Outcome: Dynamic optimization without centralized management systems.

3.2 Decentralized EV Charging Coordination

Scenario: Charging stations expose availability; agents representing vehicles coordinate charging.

  • Flow: Stations publish slots; Vehicle agents evaluate and request reservations on-chain.
  • Outcome: A decentralized marketplace emerges without proprietary APIs.

3.3 Industrial Equipment Monitoring and Predictive Maintenance

Scenario: Machines report telemetry; AI agents detect anomalies and trigger maintenance.

  • Flow: Sensors stream telemetry; Agents monitor for patterns and publish "MAINTENANCE_REQUIRED" when needed.
  • Outcome: Automated predictive maintenance reducing downtime.

3.4 Autonomous Logistics and Delivery Coordination

Scenario: Delivery robots and logistics systems coordinate pickups and deliveries.

  • Flow: Warehouses publish tasks; Agents evaluate robots and assign routes via on-chain commands.
  • Outcome: Decentralized, auditable logistics coordination.

3.5 Smart Agriculture Automation

Scenario: Agricultural sensors and irrigation systems are coordinated to optimize crop yield.

  • Flow: Soil and weather data inform Agent-led irrigation commands.
  • Outcome: Automated and adaptive farming operations.

3.6 Shared Device Marketplaces

Scenario: Devices (cameras, compute nodes) expose capabilities utilized by external agents.

  • Flow: Devices advertise capabilities; Agents discover and publish task requests (e.g., "CAPTURE_IMAGE").
  • Outcome: A marketplace of physical and computational capabilities.

4. Conclusion

The SmartClaws Protocol introduces a fundamental shift in how software intelligence interacts with the physical world.

By removing the requirement for direct network connectivity, SmartClaws transforms coordination from a fragile, infrastructure-dependent process into a deterministic, programmable, and globally accessible system. Devices no longer need to expose endpoints or trust external connections, and agents no longer need to manage networks, credentials, or vendor-specific integrations. Instead, all interaction is reduced to a shared, verifiable state machine on-chain.

This architectural shift unlocks a new class of systems:

  • AI agents that can reliably act on real-world environments without direct access
  • Devices that can securely participate in global coordination while remaining private
  • Infrastructure that is composable, interoperable, and independent of centralized control

SmartClaws turns physical devices into first-class participants in a decentralized ecosystem, where capabilities can be discovered, accessed, and orchestrated through standardized interfaces. It enables a world in which automation is no longer constrained by network topology, and where intelligence can operate seamlessly across digital and physical domains.

As AI systems become more autonomous and pervasive, the ability to coordinate actions in the real world—securely, globally, and without friction—becomes critical. SmartClaws provides the missing layer that makes this possible.

It is not merely a protocol for communication. It is a foundation for an autonomous, machine-driven economy, where software agents can perceive, decide, and act beyond the boundaries of traditional networks.