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

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'
}

Map QoS in server/ros2/qos-profiles.js:

'/your/sensor': QOS_PRESETS.RELIABLE_SENSOR

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

Name		Name	Last commit message	Last commit date
Latest commit History 52 Commits
attached_assets		attached_assets
integration/node		integration/node
minima		minima
public		public
ros2_package		ros2_package
server		server
.gitignore		.gitignore
.replit		.replit
KISSVM Scripting Language.pdf		KISSVM Scripting Language.pdf
README.md		README.md
ROMx_SPEC.md		ROMx_SPEC.md
package-lock.json		package-lock.json
package.json		package.json
replit.md		replit.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

ROSMx

What It Does

Why

Quick Start

Simulation Mode (No Robot Required)

ROS 2 Mode (Real Robot)

Using the ROS 2 Launch File

Architecture

Supported ROS 2 Topics

On-Chain Batch Format

Adding Your Own Topics

API Reference

Robot

Blockchain

Hashing

UTXO Management

ROS 2

SwarMx Swarm Coordination

System

Configuration

Prerequisites

Project Structure

Roadmap

Technical Notes

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

ROSMx

What It Does

Why

Quick Start

Simulation Mode (No Robot Required)

ROS 2 Mode (Real Robot)

Using the ROS 2 Launch File

Architecture

Supported ROS 2 Topics

On-Chain Batch Format

Adding Your Own Topics

API Reference

Robot

Blockchain

Hashing

UTXO Management

ROS 2

SwarMx Swarm Coordination

System

Configuration

Prerequisites

Project Structure

Roadmap

Technical Notes

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages