Skip to content

demechtech/DeMech

BranchesTags

Repository files navigation

DeMech Pro v3.2

Website: https://www.demech.net

DeMech connects physical robots to a crypto-native coordination & payments layer on Solana. Robots receive tasks, produce verifiable telemetry (Merkle roots), get oracle attestations (ed25519), and are paid in SPL tokens from per-task escrow vaults.

Why DeMech?

  1. Trust — Verify robot outcomes without watching every second.
    → Hash all telemetry into Merkle trees and sample proofs; on-chain attestations bind evidence to payouts.

  2. Payments — Programmatic, auditable, instant payouts.
    → Rewards are escrowed in SPL token vaults and released to robot ATAs when attested.

  3. Interoperability — Heterogenous fleets, minimal glue code.
    → Edge Agent ships a ROS2 bridge (Twist subscriber, Odometry publisher) and stable HTTP APIs.

Architecture

+----------------+       HTTP        +------------------+      Tx + Ix (ed25519)     +--------------------+
|  Edge Agent    |  <--------------> |   Coordinator    |  -----------------------> |  Solana Program    |
|  (Robot side)  |                   |  (FastAPI)       |                           |  (Anchor, Rust)    |
|                |   submit root     |  store leaves    |   oracle signs msg        |  SPL escrow vault  |
| Telemetry ---> |   (Merkle)      ->|  serve proofs  ->|   add ed25519 verify ix ->|  pay to robot ATA  |
| ROS2 bridge    |                   |                  |                           |  state machine     |
+----------------+                   +------------------+                           +--------------------+

Signed message:
msg = task_pubkey (32) || telemetry_root (32) || spec_hash (32) → 96 bytes.
On-chain, we parse the ed25519 verify instruction from the instructions sysvar and check pubkey + message. Replay protection via attest_nonce and last_msg_hash.

Tech stack

Repository layout

onchain/                      # Anchor workspace (Rust program)
  programs/demech/            # Program code (PDAs, escrow, attestation, ATA creation)
  tests/                      # TypeScript smoke/E2E scaffolding
coordinator/                  # FastAPI service (task mgmt, proof endpoint)
edge_agent/
  app/                        # Agent runtime (telemetry, merkle, ROS2 bridge, runner)
  config/agent.toml           # Agent config (uplink, ROS2 params)
tools/                        # Signer helpers (python+ts)
cli/                          # Minimal CLI to poke the coordinator
docker/                       # Dockerfiles + compose
.github/workflows/            # CI (default python-only + manual onchain)

Installation guide

1) All-in-one (Docker)

docker compose -f docker/compose.local.yml up --build
# Services:
# - solana-localnet (8899)
# - coordinator (7000)
# - edge-simulator (2 robots)
# - web-dashboard (8080)

2) Install components separately

Coordinator (FastAPI)

cd coordinator
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python -m app.main  # http://localhost:7000

Edge Agent

cd edge_agent
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp config/agent.toml config/agent.local.toml
$EDITOR config/agent.local.toml
DEMECH_AGENT_CONFIG=config/agent.local.toml python -m app.main
  • ROS2 support activates automatically when rclpy is importable and the config enables it.

On-chain (Anchor) — local

# install Solana + Anchor via official docs
solana --version
anchor --version

cd onchain
npm install
anchor build
anchor test

Workspace safety (required by Anchor):

# onchain/Cargo.toml (workspace root)
[workspace]
members = ["programs/demech"]
resolver = "2"

[profile.release]
overflow-checks = true

CLI

python -m cli.demech task create --reward 10 --deadline 900 --spec specs/inspection_area.json
python -m cli.demech task proof --task <TASK_ID> --index 0

CI set-up

  • /.github/workflows/ci.yml runs always on push/PR and only checks Python-side bits → green and fast.
  • /.github/workflows/onchain-manual.yml runs on-demand in an Anchor container: build & test the program when needed.

If the container tag is not available, pin a different version inside onchain-manual.yml.

Program details

  • Accounts (PDAs)

    • Config: oracle pubkey, token mint, fee bps
    • Robot: owner, stake, reputation, status
    • Task: creator, optional robot, reward, deadline, spec_hash, telemetry_root, leaf_count, vault bump, replay guards

  • Escrow & payout

    • Vault = PDA ATA seeded by ["vault", task_pubkey].
    • complete_task creates robot ATA via Associated Token Program CPI if missing, then transfers reward.

  • Attestation

    • Oracle must sign the tx and include an ed25519 verify instruction for the 96-byte message.
    • Program parses the instruction and validates it; then moves task to attested.

Telemetry & Merkle proofs

  • Edge Agent serializes telemetry frames deterministically, hashes leaves (sha256), builds a full Merkle tree, and submits:
    • root (hex) + leaf_hashes (array of hex) to the coordinator.
  • Coordinator exposes /proof?task=...&index=n returning { leaf, siblings[], root } to verify off-chain.

Security considerations

  • Use hardware-backed keys for the robot and the oracle in production.
  • Rate limits in the coordinator protect against flooding.
  • Replay protection enforced on-chain via attest_nonce and last_msg_hash (keccak).

Example scenario: one robot, one task, full loop

To make the structure less abstract, imagine a single inspection robot in a small warehouse:

  1. An operator (or another program) creates a task that encodes a simple "patrol this aisle" job and funds it with SPL tokens on chain.
  2. The coordinator sees the new on chain task and records it in its SQLite database.
  3. The edge agent running on the robot polls /api/tasks/next, claims the task and starts moving. The ROS2 bridge converts the high level velocity commands into /cmd_vel and synthesizes /odom readings.
  4. The telemetry collector turns sensor snapshots into a sequence of frames. The Merkle builder hashes them into a root and the agent submits it back to the coordinator with /api/tasks/report.
  5. The coordinator stores the root and leaf hashes and can later serve Merkle proofs over /api/tasks/proof so an on chain attestation or an external auditor can verify that a specific frame was part of the committed telemetry set.
  6. Once the on chain program is satisfied, the escrow vault releases the SPL rewards to the robot owner account.

The same pattern scales from a single robot to a heterogeneous fleet without changing the core components.

Developer quickstart

Running the coordinator locally

From the repository root:

cd coordinator
python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
export COORDINATOR_DB_PATH="$(pwd)/coordinator.db"
uvicorn app.main:app --reload --host 0.0.0.0 --port 8080

You now have a local API on http://localhost:8080 with:

  • GET /health for a basic liveness check
  • POST /api/tasks/create to create a task
  • GET /api/tasks/all to list tasks
  • GET /api/tasks/next?pk=<robot_pubkey> to claim the next task
  • POST /api/tasks/report and GET /api/tasks/proof to work with Merkle telemetry sets

Running the edge agent in simulation

In a second terminal:

cd edge_agent
python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
python -m app.main

The agent will:

  • Generate synthetic telemetry frames
  • Request tasks from the coordinator
  • Build Merkle trees from telemetry
  • Submit roots and request proofs
  • Mark tasks as completed

This gives you a repeatable way to verify the full loop before wiring in your own robot platform and ROS2 setup.

Troubleshooting

  • CI red? The default pipeline is Python-only and should be green. Use the manual on-chain workflow for Anchor builds.
  • Anchor build fails locally: verify toolchain compatibility (Solana/Anchor versions), and ensure [profile.release].overflow-checks = true is present in the workspace Cargo.toml.

MIT © 2025 DeMech

Version 3.2 highlights

v2.6 is the release that turns DeMech from a set of scripts into a stack you can actually operate and observe:

  • coordinator backed by SQLite with tasks, robots, API keys and a small metrics endpoint
  • background expiry and reconciliation workers so stale or over-retried tasks do not clog the queue
  • edge agent with ed25519 signing, ROS2 bridge, telemetry logging and safety
  • CLI and web dashboard for operators
  • Docker Compose setup to run the whole loop with a single command

Running the full stack via Docker

From the repository root:

docker compose up --build

This will start:

The coordinator stores its SQLite database inside the demech-data Docker volume so restarts do not wipe state.

Using the web dashboard

Open http://localhost:7080 in your browser.

You get:

  • a live robot table with labels, reputation and last heartbeat
  • a task queue view showing state, robot assignment, reward and deadlines
  • a small event stream that logs task creation and connection events

The dashboard talks directly to the coordinator HTTP API at port 7000 and will also subscribe to the /ws/tasks and /ws/robots WebSocket feeds when available.

Public API highlights

  • /api/meta/version for quick coordinator and API introspection
  • /api/tasks/detail/{id} and /api/tasks/search for task-centric dashboards
  • /api/robots/detail/{pk}, /api/robots/stats and /api/robots/leaderboard for fleet overviews

These endpoints are deliberately small, read-focused and stable so you can safely integrate them into monitoring, bots or external services without fighting breaking changes every week.

About

No description, website, or topics provided.

Resources

Readme

License

View license
Activity

Stars

4 stars

Watchers

1 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

No packages published

Languages