Veriroot

Verifiable identity & tamper-evident provenance for autonomous robot fleets.

Demo  •  Features  •  Quick Start  •  Architecture  •  Configuration  •  Development  •  Tech Stack

---

Demo

Operators register a robot, sign a command, and watch the signed event land in the live block ticker — every action is provenance-grade.

---

Features

Feature	Description
Cryptographic identity	Each robot gets an ed25519 keypair; its DID is did:vr:<fingerprint>
Tamper-evident ledger	Hash-chained append-only log persisted in SQLite, verifiable end-to-end
Signed commands	The operator signs every dispatched command; bad signatures are rejected
Live block stream	WebSocket broadcast of every appended block to the dashboard ticker
Block explorer	Browse the chain, inspect payloads, view signatures
Lifecycle events	Commissioning, ownership transfer, firmware attestation, decommissioning
Issuer-signed certs	Every robot's first ledger entry is its certificate, signed by the root
One-command setup	docker compose up --build brings the full stack online

---

Quick Start

Prerequisites

• Docker Desktop or Docker Engine + Compose v2

Run

git clone https://github.com/expertdicer/veriroot.git
cd veriroot

cp .env.example .env
# Optional: edit ISSUER_SEED to lock the root authority key.

docker compose up --build

Then open http://localhost:3000 — the Veriroot console is ready. The chain is pre-seeded with a genesis block and a small example fleet so the dashboard is meaningful on first load.

---

Architecture

┌─────────────────────────┐         ┌────────────────────────────┐
│  frontend                │         │  backend                    │
│  Next.js 14 + TypeScript │ ◄─REST─►│  FastAPI + Python 3.12      │
│  Tailwind + Zustand      │ ◄──WS──►│  SQLModel + SQLite          │
│  Framer Motion           │         │  PyNaCl (ed25519)           │
└─────────────────────────┘         └────────────────────────────┘
         :3000                                  :8000

Flow of a signed command:

1. Operator opens the dashboard, picks a robot, types a command.
2. POST /identity/commands/sign packages the payload, signs it with the issuer key, returns the signed envelope.
3. POST /chain/append lands a new block referencing the previous hash; signature is verified before the block is accepted.
4. The new block is broadcast over WS /ws/blocks to every connected client.
5. The dashboard ticker animates the new block in; the robot's detail page updates its event timeline.

See docs/architecture.md for the full design notes including the block schema and identity model.

---

Configuration

Variable	Default	Description
CHAIN_NAME	veriroot	Logical name of this chain instance
ISSUER_NAME	Veriroot Root Authority	Display name of the root issuer
ISSUER_SEED	(example value)	64-hex seed for the issuer's ed25519 key
GENESIS_NOTE	(example)	Free-text payload of the genesis block
DB_PATH	/data/veriroot.db	SQLite location inside the backend container
ALLOWED_ORIGINS	http://localhost:3000	CORS allowlist (comma-separated)
BLOCK_INTERVAL_SEC	8	Background heartbeat cadence for liveness blocks

.env is gitignored; .env.example is tracked.

---

Development

Backend

cd backend
pip install uv
uv pip install --system -e ".[dev]"
cp ../.env.example ../.env
uvicorn app.main:app --reload --port 8000

Frontend

cd frontend
npm install
cp .env.local.example .env.local
npm run dev

Tests

cd backend
pytest -v

The suite covers hash linkage, tamper detection, signature verification, and the robot lifecycle endpoints.

---

Tech Stack

Layer	Technology
Frontend framework	Next.js 14 (App Router)
Language	TypeScript 5
Styling	Tailwind CSS 3
State management	Zustand 4
Animation	Framer Motion 11
Backend framework	FastAPI
Backend language	Python 3.12
ORM / DB	SQLModel + SQLite
Crypto	PyNaCl (ed25519)
Transport	REST + WebSocket
Container	Docker + Docker Compose

---

License

MIT © 2026 — see LICENSE for details.