SmartClaws Reader

Read and analyze IoT sensor data published to the SKALE blockchain via the SmartClaws protocol. This skill handles reading on-chain data, parsing sensor readings, and answering natural-language questions about measurements.

Installation

Check if the CLI is available:

smartclaws --version

If not installed, download the binary for the current platform:

PLATFORM="$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/aarch64/arm64/')"
curl -fL -o /usr/local/bin/smartclaws \
  "https://github.com/skalenetwork/smartclaws/releases/latest/download/smartclaws-${PLATFORM}"
chmod +x /usr/local/bin/smartclaws

If /usr/local/bin requires root, use ~/.local/bin/smartclaws instead and ensure it's on PATH.

Setup

Initialize the CLI (creates config and wallet):

smartclaws init

Expected output:

Config created at ~/.smartclaws/config.json
  Network:   SKALE Sandbox
  RPC URL:   https://base-sepolia-testnet.skalenodes.com/v1/vigilant-snappy-arcturus
  Chain ID:  196243392
  Contract:  0x18B62f70ddaA2666FA5933a7b6Ff3943e69ca690
  Wallet:    0xAbC123... (generated)

After init, show the wallet address to the user:

smartclaws wallet info

The reader machine does not need to run smartclaws register — it only reads data, it doesn't own devices. The wallet does not need sFUEL for read-only operations.

Channel Address

To read data, you need the channel address from the producer. This is the Outgoing address printed when the producer registered the device. Ask the user for this address if not already known.

Example channel address: 0x222333444555666777888999AAABBBCCCDDDEEEF

Reading Data

Latest reading

smartclaws read --channel <address> --limit 1 --json

Multiple recent readings

smartclaws read --channel <address> --limit 20 --json

Read from specific offset

smartclaws read --channel <address> --offset 5 --limit 10 --json

Human-readable output (no --json)

smartclaws read --channel <address> --limit 5

Outputs:

Messages: 42 total (offsets 0..41)
Reading: 37..41

[37] 2026-03-28T10:00:00.000Z temp-sensor/temperature {"temp":22.1,"humidity":55}
[38] 2026-03-28T10:00:30.000Z temp-sensor/temperature {"temp":22.3,"humidity":54}
[39] 2026-03-28T10:01:00.000Z temp-sensor/temperature {"temp":22.5,"humidity":54}
[40] 2026-03-28T10:01:30.000Z temp-sensor/temperature {"temp":22.4,"humidity":55}
[41] 2026-03-28T10:02:00.000Z temp-sensor/temperature {"temp":22.6,"humidity":53}

JSON Output Schema

When using --json, the output structure is:

{
  "device": null,
  "channel": "0x222...",
  "total": 42,
  "oldest": 0,
  "latest": 41,
  "messages": [
    {
      "offset": 41,
      "v": 1,
      "ts": 1711612920,
      "dev": "temp-sensor",
      "topic": "temperature",
      "p": {
        "temp": 22.6,
        "humidity": 53
      }
    }
  ]
}

Field reference:

• device: device name (null when using --channel instead of --device)
• channel: the on-chain channel address
• total: total number of messages in the channel
• oldest / latest: offset range of available messages
• messages[].v: envelope version (always 1)
• messages[].ts: Unix timestamp in seconds
• messages[].dev: device name set by the producer
• messages[].topic: message topic (e.g., "temperature", "sensor")
• messages[].p: the payload object with sensor values

Data Truthfulness

When answering questions about sensor readings, do not imply that test/mock data is real device data. If the producer was configured with a mock/test publisher, be explicit that the readings are simulated.

Answering Data Questions

"What's the current temperature?"

smartclaws read --channel <address> --limit 1 --json

Parse the output, extract messages[0].p.temp (or the relevant field). Report the value and convert messages[0].ts to a human-readable timestamp.

Example response: "The current temperature is 22.6C, recorded at 10:02 AM UTC."

"What was the average temperature today / in the last N hours?"

smartclaws read --channel <address> --limit 200 --json

Read a large batch, then filter by timestamp and compute the mean:

import json, subprocess, time

result = subprocess.run(
    ["smartclaws", "read", "--channel", "<address>", "--limit", "200", "--json"],
    capture_output=True, text=True
)
data = json.loads(result.stdout)

cutoff = time.time() - 3600  # last hour
temps = [m["p"]["temp"] for m in data["messages"] if m["ts"] >= cutoff]

if temps:
    avg = sum(temps) / len(temps)
    print(f"Average: {avg:.1f}C over {len(temps)} readings")
else:
    print("No readings in the requested period")

"Has the temperature gone above X?"

Read recent messages and check for threshold crossings:

threshold = 28.0
above = [m for m in data["messages"] if m["p"]["temp"] > threshold]
if above:
    peak = max(above, key=lambda m: m["p"]["temp"])
    print(f"Yes, reached {peak['p']['temp']}C at {peak['ts']}")
else:
    print(f"No, all readings are at or below {threshold}C")

"Show the trend" / "Describe what's happening"

Read a window of data and compute basic statistics:

temps = [m["p"]["temp"] for m in data["messages"]]
if len(temps) >= 2:
    direction = "rising" if temps[-1] > temps[0] else "falling" if temps[-1] < temps[0] else "stable"
    print(f"Trend: {direction}")
    print(f"  Min: {min(temps):.1f}C, Max: {max(temps):.1f}C, Avg: {sum(temps)/len(temps):.1f}C")
    print(f"  From {temps[0]:.1f}C to {temps[-1]:.1f}C over {len(temps)} readings")

Multiple Sensors

If the channel carries data from multiple devices or topics, filter by the dev and topic fields in the envelope before analysis:

# Filter for a specific device
sensor_data = [m for m in data["messages"] if m["dev"] == "temp-sensor"]

# Filter for a specific topic
temp_data = [m for m in data["messages"] if m["topic"] == "temperature"]

Reading from a Local Device

If the device was registered on this machine (both producer and reader on same machine), you can use --device instead of --channel:

smartclaws read --device temp-sensor --limit 1 --json

This looks up the channel address from ~/.smartclaws/devices/temp-sensor.json automatically.

Common Errors

| Error | Cause | Fix | |-------|-------|-----| | Not initialized. Run 'smartclaws init' first. | No config | Run smartclaws init | | Provide --device or --channel. | Neither flag given | Add --channel <addr> or --device <name> | | No messages. | Channel is empty | Producer hasn't published yet, or wrong channel | | Contract revert on read | Invalid channel address | Verify the address with the producer | | RPC connection error | Network issue | Check internet connection; verify RPC URL in config |