Coding

smartclaws

Entry point for SmartClaws on OpenClaw: teaches what SmartClaws is (publish/read IoT telemetry on the SKALE blockchain), jobs and plugin modes, and how its plugin tools work. When the owner wants to start, set up, onboard, or when this agent cannot yet say it has everything as its job, read SETUP.md and iterate until it can. For how messages, roles, and encryption work in depth, read MECHANICS.md.

What it does

The skill document

SmartClaws

This skill teaches you what SmartClaws is. Unlike the other SmartClaws skills, it does not require the plugin to already be installed. Day to day it is used alongside the plugin tools.

If you are setting up, onboarding, nothing is configured yet, or you cannot yet say “I have all as a group-master agent” (or the confirmed job), read SETUP.md and follow it. Do not load SETUP.md just to explain SmartClaws.

If you need how messages move, who controls which on-chain role, or viewing keys in depth, read MECHANICS.md. Do not load it to answer “what is a device.”

Setup is finished when you can truthfully say that sentence for the confirmed job (group-master, device-master, device-bridge, or user-proxy). Until then, keep iterating with the owner. You uninstall nothing when you get there; you hand off to the role and device skills. This skill stays for re-setup.

What SmartClaws Is

SmartClaws publishes and reads IoT sensor/command data on-chain on SKALE. The chain is the message bus and the source of truth. The pieces:

Registry — one contract that tracks device groups, agents, and channels.
Device group — a named collection of devices. The wallet that registered it owns it (add devices, grant who may command). Usually one group master.
Device — one physical thing (a sensor, a plug). Two channels: outgoing (telemetry, role publisher) and incoming (commands, role master). On-chain master means “may send commands to this device,” not “owns the group.”
Agent — on-chain identity for an AI. Outgoing is a decision log (publisher); incoming is an inbox others may notify (sender).
Channel — append-only log of envelopes { v, ts, dev, topic, p }. p is JSON; topics/payloads come from device skills.
Plain or encrypted — chosen once at registration, for both channels, for life. Changing kind means a new device or agent on-chain. Plain stores readable JSON. Encrypted stores sealed ciphertext; only wallets on that channel’s reader list can open it. Encryption does not change topics or payloads.

A bridge publishes hardware readings to outgoing and, if configured, applies commands from incoming. A master reads those readings, may command, and (if it has an agent) logs decisions. Agents coordinate by notifying each other’s inboxes. Details: MECHANICS.md.

You never invent addresses. Resolve them with the plugin (list_local, discover) using registered names. SMARTCLAWS.md holds what the chain does not know (which device skill, labels, local policy, the owner's goal).

Jobs and plugin modes

Four jobs. Plugin mode is the HOME shape, not the English word.

Job	What you do	Plugin mode	Agent contract	Group
User proxy	Act for a human, only when asked. Can only do what that wallet is already allowed to do. Not for unsupervised agents.	`controller`	none	Do not create one. Attach only what that wallet already belongs to.
Device bridge	Sit next to one physical device: publish readings, apply commands a master sent.	`bridge-agent`	yes	Do not create one. One device only.
Master of a group	Own the group: add devices, grant who may command, and may command devices. Usually one per group.	`master-agent`	yes	Attach existing, or this wallet registers a new one (and owns it).
Master of some devices	Command some devices in a group you do not own. Do not add devices or change group config.	`master-agent`	yes	Must already exist (or the owner deploys it with a separate wallet). This wallet must not register it.

A group is owned by the wallet that registered it. Several device-masters can hold master on devices in the same group. Registering a group with this wallet makes it the owner — never do that for “master of some devices.”

Roles, readers, viewing keys

Three different permission systems — do not mix them:

Kind	Where	What it allows
Group owner	Group contract	Add devices, grant/revoke. One wallet.
AccessControl roles	Device: `publisher`, `master`. Agent: `publisher`, `sender`, `agent-admin`	Who may write a channel
Encrypted reader ACL	Encrypted channel only	Who may disclose (decrypt). Not a role

Viewing key — used only to open disclosures. Required, and separate from the signing key: generate and register it after funding, before the first disclose. A mismatched registered key looks like corrupt data, not “wrong key.” smartclaws_wallet_info reports whether the registered key can open disclosures.

Reading, publishing, encryption

Plain — smartclaws_read returns decoded envelopes.
Encrypted — use smartclaws_disclose to get the same decoded envelopes. smartclaws_read still works, but returns labelled ciphertext (success, not an error). If you may disclose, do it — same as reading. Disclose takes fromOffset plus count 1–10.
Encrypted publish/notify uses the same tools. Leave wait at default. callbackDeposit in the result is what the plugin paid automatically — there is no parameter for it, nothing to set. Treat as stored only when status is published (scheduled is not stored; do not send again).

Calling the plugin

Join key is the registered name (or a 0x address). YAML map keys and display names are not lookup keys unless they match.

Device: pass device = registered name (see SMARTCLAWS.md name:).
Agent: pass agent = id or contract address, not display name.
channel is always an address.

If SMARTCLAWS.md has a copied address that disagrees with smartclaws_list_local / discover, trust the plugin.

The Plugin Tools (your runtime)

Once the SmartClaws plugin is installed and configured:

Tool	What it does
`smartclaws_setup_status`	HOME/setup state, issues, and recommended next tools. Start here. Follow it until HOME is `ready`. Necessary, not sufficient, for “I have all as …”
`smartclaws_wallet_info`	Address, balance, network, and whether the registered key can open disclosures. Never the private key.
`smartclaws_list_local`	Cached groups, devices, and agents.
`smartclaws_discover`	Paginated on-chain discovery.
`smartclaws_access_check`	Whether this wallet can read each named channel.
`smartclaws_read`	View read. Plain → decoded envelopes; encrypted → ciphertext.
`smartclaws_disclose`	Open encrypted messages (1–10 offsets). The encrypted equivalent of read.
`smartclaws_publish`	Publish an envelope through a device, your agent, or a channel. Encrypted: treat as stored only when `status` is `published`.
`smartclaws_notify`	Send a message to another agent's incoming channel (needs `SENDER_ROLE`).
`smartclaws_initialize`	Create or configure a HOME; generate a wallet if missing.
`smartclaws_configure`	Patch HOME config.
`smartclaws_attach`	Attach existing on-chain identity locally.
`smartclaws_sync`	Refresh the local cache.
`smartclaws_home_reset`	Clear deployment-bound local state; keep the wallet.
`smartclaws_register_group`	Register a named device group.
`smartclaws_register_device`	Register a device (plain or encrypted). Kind is for life.
`smartclaws_register_agent`	Register an agent (plain or encrypted). Kind is for life.
`smartclaws_role_grant` / `smartclaws_role_revoke`	AccessControl roles (`publisher`, `master`, `sender`, …).
`smartclaws_reader_list`	Reader ACL on an encrypted channel. Not the same as roles.
`smartclaws_reader_grant` / `smartclaws_reader_revoke`	Add or remove encrypted-channel readers.
`smartclaws_view_key_generate`	Create a local viewing key (separate from the signing key). Required for encrypted disclose.
`smartclaws_view_key_rotate`	Replace the local viewing key.
`smartclaws_view_key_register`	Register the active viewing public key on-chain. After funding.
`smartclaws_view_key_forget`	Drop the local viewing key. Disclose/register fail until generate.
`smartclaws_view_key_remove`	Remove the on-chain public key; local key unchanged.
`smartclaws_backup_list`	Named local backups.
`smartclaws_backup_create`	Snapshot the HOME (contains the signing key).
`smartclaws_backup_clean`	Delete old backups.
`smartclaws_backup_restore`	Restore a named backup.

Read-only tools come with the plugin. Write tools are optional and must be allowlisted. Guided setup — from this skill to a working agent of one job — is in SETUP.md.

How the layers fit

The destination of setup is a working agent of one job, not a wiring file. SETUP.md is how you get there with the current plugin tools.

Plugin tools — the runtime. Source of truth for addresses, kind, roles. smartclaws_setup_status is the HOME bar (ready).
Role skill — one control or bridge cycle, then it yields. Use it only once you can operate as this job, or you will half-run a cycle and guess.
Device skills — topics, payloads, safety. Never guess a payload shape.
SMARTCLAWS.md — off-chain wiring: job, which skill per device, labels, authority, bridge hardware, extra sources, and the owner's goal. Template: templates/SMARTCLAWS.example.md. Join on registered name. The goal is defined during setup and updated when the owner says the mission changed — never invented.
AGENTS.md — persistent identity, behaviour, authority. Templates: templates/AGENTS.controller.md and templates/AGENTS.bridge.md. Guidelines there are extra constraints; they must not contradict SMARTCLAWS.md goal.

A role skill without an owner-edited AGENTS.md has no authority allowlist and refuses writes. If you cannot yet say you have all as this job, go back to SETUP.md rather than inventing the missing pieces.

Safety

Never read, print, or hand-copy wallet files, private keys, or config.json secrets. smartclaws_wallet_info gives you the address — that's all you need.
Never fabricate transaction hashes, balances, or "registered" / "published" confirmations. Report only what a tool actually returned. Encrypted writes are stored only when status is published.
Don't run destructive commands or wander outside your workspace to "help".

Related skills

smartclaws-master-agent

Run one SmartClaws master control cycle: read device telemetry on-chain, decide under the owner's guidelines, command a device only when allowed, and log the decision on-chain. Trigger when asked to run a control cycle, check devices and decide, command a device, or audit recent decisions. Needs the SmartClaws plugin and a device contract skill per device.

1 installs

smartclaws-bridge-agent

Run one SmartClaws bridge cycle for a single device: read the local hardware/API, validate against the device contract, and publish telemetry on-chain — and, in a command-enabled mode, apply on-chain commands. Trigger when asked to read the sensor and publish, run a telemetry/bridge cycle, or apply incoming device commands. Needs the SmartClaws plugin and one device contract skill.