Skip to content

MrGheek/ROMx

BranchesTags

Repository files navigation

ROSMx

Blockchain-verified event recording and swarm coordination for ROS 2 robots using Minima

ROSMx runs an embedded Minima blockchain node on your robot's onboard computer. It captures sensor events from ROS 2 topics, hashes them with SHA-256, batches up to 253 events per transaction with Merkle tree verification, and records them immutably on-chain. It also coordinates multi-robot swarms via SwarMx -- encrypted peer-to-peer messaging over Minima's Maxima layer for role-based task handoffs, progress tracking, emergency alerts, and coordinator kill-switch authority. No cloud. No central server. Just the robots, the swarm, and the chain.

What It Does

ROS 2 Sensors ──▶ EventBridge ──▶ SHA-256 Hasher ──▶ Batch (Merkle tree) ──▶ Minima On-Chain
  /scan                              │
  /imu/data                          ▼
  /gps/fix                    Web Dashboard ◀── SwarMx Coordination
  /cmd_vel                    (port 5000)        │
  /camera/detections                              ▼
  ...                                      Maxima P2P Messaging
                                           (encrypted swarm comms)
  • Captures events from 10+ ROS 2 topics (LiDAR, IMU, GPS, cameras, motors, navigation, battery, arm, diagnostics)
  • Hashes each event with SHA-256 and assigns it to a batch
  • Batches up to 253 events into a single on-chain transaction with a Merkle root for cryptographic verification
  • Records batches on the Minima blockchain with full state variable encoding
  • Coordinates multi-robot swarms via SwarMx -- encrypted Maxima P2P messaging with role-based task handoffs and coordinator kill switch
  • Displays real-time status on a web dashboard showing subsystems, chain status, hash log, swarm peers, task board, and coordination log

Why

Autonomous robots need provable records. Insurance claims, regulatory compliance, safety audits, incident investigation -- all require tamper-proof evidence of what the robot sensed, decided, and did. ROSMx provides that evidence layer without trusting any third party.

Quick Start

Simulation Mode (No Robot Required)

git clone <repo-url>
cd rosmx
npm install
npm start

Open http://localhost:5000 to see the dashboard. The simulator generates realistic ROS 2 sensor data (LaserScan, IMU, GPS, Twist, BatteryState, JointState, etc.) with proper message structures, headers, and covariance matrices.

ROS 2 Mode (Real Robot)

# Terminal 1: Start rosbridge
ros2 launch rosbridge_server rosbridge_websocket_launch.xml

# Terminal 2: Start ROSMx
ROSMX_MODE=ros2 ROSBRIDGE_URL=ws://localhost:9090 npm start

Using the ROS 2 Launch File

# Copy to your colcon workspace
cp -r ros2_package ~/ros2_ws/src/rosmx
cd ~/ros2_ws && colcon build --packages-select rosmx

source install/setup.bash
ros2 launch rosmx rosmx.launch.py mode:=ros2

Architecture

┌─────────────────────────────────────────────────────────────┐
│                   ROBOT ONBOARD COMPUTER                    │
│                                                             │
│  ┌────────────┐    ┌──────────────┐    ┌────────────────┐  │
│  │ ROS 2 Nodes│───▶│  rosbridge   │───▶│ RosbridgeClient│  │
│  │ (Sensors)  │    │  (ws://9090) │    │                │  │
│  └────────────┘    └──────────────┘    └───────┬────────┘  │
│                                                 │           │
│  ┌────────────┐                        ┌───────▼────────┐  │
│  │  Simulator │───────────────────────▶│  EventBridge   │  │
│  │ (sim mode) │                        │  (normaliser)  │  │
│  └────────────┘                        └───────┬────────┘  │
│                                                 │           │
│                                        ┌───────▼────────┐  │
│                                        │  EventHasher   │  │
│                                        │  SHA-256 +     │  │
│                                        │  Merkle batch  │  │
│                                        └───────┬────────┘  │
│                                                 │           │
│  ┌────────────┐    ┌──────────────┐    ┌───────▼────────┐  │
│  │   UTXO     │───▶│   Minima     │◀───│ MinimaClient   │  │
│  │ Generator  │    │   Node       │    │ (TCP RPC)      │  │
│  └────────────┘    └──────┬───────┘    └────────────────┘  │
│                           │                                 │
│  ┌──────────────────┐     │     ┌──────────────────────┐  │
│  │ SwarMx Coord.    │     │     │ MDS Receiver         │  │
│  │ SwarmManager     │◀────┼─────│ (MiniDapp long-poll) │  │
│  │ Peers/Tasks/Ctrl │     │     └──────────────────────┘  │
│  └──────────────────┘     │                                 │
│                           │                                 │
│  ┌────────────┐           │        ┌────────────────────┐  │
│  │  Web UI    │◀──────────┼───────▶│  REST API          │  │
│  │ :5000      │           │        │  /api/*            │  │
│  └────────────┘           │        └────────────────────┘  │
│                           │                                 │
└───────────────────────────┼─────────────────────────────────┘
                            │
                 ┌──────────▼──────────┐
                 │  Minima P2P Network │
                 │  (mainnet)          │
                 │  + Maxima P2P Msgs  │
                 └─────────────────────┘

Supported ROS 2 Topics

Message Type Topic Subsystem QoS Profile
sensor_msgs/msg/LaserScan /scan LiDAR SensorData (BEST_EFFORT)
sensor_msgs/msg/Imu /imu/data IMU SensorData
geometry_msgs/msg/Twist /cmd_vel Motors SystemDefault (RELIABLE)
nav_msgs/msg/Odometry /odom Navigation SensorData
sensor_msgs/msg/NavSatFix /gps/fix GPS ReliableSensor
sensor_msgs/msg/BatteryState /battery/state Battery ReliableSensor
sensor_msgs/msg/JointState /arm/joint_states Arm SensorData
vision_msgs/msg/Detection2DArray /camera/detections Camera SensorData
nav2_msgs/msg/NavigateToPose /nav/status Navigation ActionStatus (TRANSIENT_LOCAL)
diagnostic_msgs/msg/DiagnosticArray /diagnostics System SystemDefault

QoS profiles match ROS 2 / Fast DDS (Vulcanexus) defaults for each topic type. See server/ros2/qos-profiles.js for full configuration.

On-Chain Batch Format

Events are batched (up to 253 per transaction) and recorded using Minima's 256 state variable slots:

Slot Content
0 Batch metadata (version, event count, Merkle root, timestamps, batch ID)
1 Batch label (batch/15events)
2-254 Individual event SHA-256 hashes
255 ISO 8601 timestamp

All values are hex-encoded (0x prefix) so Minima stores them as raw bytes.

Batch parameters:

  • Max batch size: 253 events
  • Batch window: 30 seconds
  • Min event interval: 2 seconds
  • Retry attempts: 5 per batch (head-of-line rotation after 3 failures)
  • Pending batch queue: 10 max

Adding Your Own Topics

  1. Define the message type in server/ros2/message-types.js:
'your_msgs/msg/CustomSensor': {
  topic: '/your/sensor',
  fields: { header: { stamp: {}, frame_id: '' }, value: 0 },
  subsystem: 'custom'
}
  1. Map QoS in server/ros2/qos-profiles.js:
'/your/sensor': QOS_PRESETS.RELIABLE_SENSOR
  1. Add to subscriptions in server/ros2/rosbridge-client.js:
{ topic: '/your/sensor', type: 'your_msgs/msg/CustomSensor' }

API Reference

Robot

Method Endpoint Description
GET /api/robot/state Robot state, subsystems, position
GET /api/robot/events Event log
GET /api/robot/topics Active topics

Blockchain

Method Endpoint Description
GET /api/chain/status Node status and block height
GET /api/chain/balance Token balances
GET /api/chain/balance/summary Sendable/confirmed summary
GET /api/chain/block Current block height
GET /api/chain/address Node address
GET /api/chain/mds MDS system status
GET /api/chain/mds/list Installed MiniDapps
POST /api/chain/hash Hash data locally (not on-chain)
POST /api/chain/record Record data on-chain
POST /api/chain/send Send tokens

Hashing

Method Endpoint Description
GET /api/hash/log Hash audit log
GET /api/hash/detail/:eventId Event hash detail
GET /api/hash/stats Hashing statistics
POST /api/hash/pause Pause recording
POST /api/hash/resume Resume recording

UTXO Management

Method Endpoint Description
POST /api/utxo/generate Start UTXO splitting
GET /api/utxo/status Generator status
POST /api/utxo/cancel Cancel generation

ROS 2

Method Endpoint Description
GET /api/ros2/status Bridge mode and stats
GET /api/ros2/topics Topic discovery
GET /api/ros2/qos QoS profiles
GET /api/ros2/message-types Message type mappings

SwarMx Swarm Coordination

Method Endpoint Description
GET /api/swarm/status Swarm status, role, peer count
GET /api/swarm/peers Peer list with roles, battery, tasks
GET /api/swarm/tasks Task board with handoff chains
GET /api/swarm/messages Coordination message log
POST /api/swarm/emergency Broadcast emergency alert
POST /api/swarm/halt HALT ALL robots (coordinator)
POST /api/swarm/resume RESUME ALL robots (coordinator)
POST /api/swarm/halt-robot Halt specific robot by publickey
POST /api/swarm/task/update Post task progress update
POST /api/swarm/task/handoff Initiate task handoff
GET /api/swarm/contacts List Maxima contacts
POST /api/swarm/contact/add Add Maxima contact
POST /api/swarm/contact/remove Remove Maxima contact
POST /api/swarm/contacts/batch Batch import contacts

System

Method Endpoint Description
GET /api/system/overview Complete system overview

Configuration

Environment Variable Default Description
ROSMX_MODE simulation simulation or ros2
ROSBRIDGE_URL ws://localhost:9090 rosbridge WebSocket URL
MDS_PASSWORD Auto-generated Minima MDS password

Prerequisites

Requirement Version
Node.js 18+
Java 11+ (for Minima)
ROS 2 Iron or Humble (for ros2 mode)
rosbridge_suite Matching ROS 2 distro

Project Structure

rosmx/
├── server/
│   ├── index.js                     # Entry point
│   ├── routes/api.js                # REST API
│   ├── services/
│   │   ├── event-bridge.js          # Event normalisation
│   │   ├── event-hasher.js          # SHA-256 + batch + Merkle
│   │   ├── minima-manager.js        # Minima node lifecycle
│   │   ├── robot-simulator.js       # ROS 2 sensor simulation
│   │   └── utxo-generator.js        # UTXO splitting
│   ├── ros2/
│   │   ├── message-types.js         # ROS 2 message definitions
│   │   ├── qos-profiles.js          # DDS QoS presets
│   │   └── rosbridge-client.js      # rosbridge v2 client
│   └── swarm/
│       ├── protocol.js              # SwarMx message types & factories
│       ├── swarm-manager.js         # Peer registry, task board, simulation
│       ├── mds-receiver.js          # MDS long-poll receiver
│       └── minidapp/                # Minimal MiniDapp for MDS
├── integration/node/
│   └── minima-client.js             # Minima RPC (raw TCP) + Maxima
├── public/                          # Web dashboard
├── ros2_package/                    # ROS 2 package for colcon
│   ├── config/rosmx_params.yaml
│   ├── launch/rosmx.launch.py
│   └── package.xml
├── minima/                          # Minima tooling & scripts
│   ├── start.sh, cli.sh
│   ├── get_maxima.sh
│   ├── mxid_*.sh                    # Identity tools
│   └── *.md                         # Documentation
├── ROMx_SPEC.md                     # Full technical specification
└── package.json

Roadmap

  • Robot-to-Robot Payments -- Autonomous micropayments between robots for task delegation, sensor data sharing, and resource access using Minima token transfers
  • Decentralised Task Marketplace -- Robots post tasks, bid on work, verify completion proofs, and settle payments on-chain

See ROMx_SPEC.md for the full technical specification.

Technical Notes

  • Minima's HTTP server uses LF instead of CRLF -- the RPC client uses raw TCP sockets to handle this
  • State values are hex-encoded (0x prefix) so Minima treats them as MiniData, not numbers
  • Event UTXOs are sent to an external address to prevent accidental reuse
  • The hash log preserves on-chain entries and only evicts local entries when the buffer is full
  • Explorer links use block height (?q=<blockHeight>) because the local txpowid differs from the mined transaction ID

License

MIT

About

ROS2 x Minima

github.com/Gheek-Labs/ROMx

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages