System Architecture

TaτsuOS is composed of three codebases, each of which can be deployed and operated independently.

1. tatsuos-burn — Smart Contracts and Burn Portal

A Solidity contract suite (TatsuBurn.sol, plus interfaces) deployed to Ethereum-compatible chains. It accepts a TATSU burn for a registered featureId against a specified deviceId, and emits a FeatureUnlocked(user, featureId, deviceId, amount, nonce) event. A nonce registry prevents replay.

A React + Vite portal provides the end-user interface: connect wallet, select feature, enter device ID, approve, burn. After confirmation, the portal pulls the signed receipt from the cloud API and pushes it to the device over Web Bluetooth.

2. tatsuos-cloud — Listener, Signer, and Dashboard

A Next.js application that hosts:

• FeatureUnlocked chain listener subscribing to events over a JSON-RPC websocket.
• A receipt signer that constructs a canonical receipt payload and signs it with an ECDSA private key held in a KMS / HSM in production.
• A TimescaleDB instance (Postgres-compatible) for telemetry and unlock history.
• An MQTT subscriber (EMQX broker) for device-originated heartbeat and telemetry.
• A web dashboard for fleet operators to monitor devices, online status, and unlock history.
• A public, unauthenticated /api/receipt?deviceId=… endpoint that returns signed receipts. Because every receipt is self-authenticating, this endpoint requires no access control.

3. tatsuos-firmware — Zephyr RTOS Image

A Zephyr-based firmware image targeting the ESP32 family in the initial release, with a board-abstraction layer designed to extend to nRF52, STM32, and RP2040 platforms. The image includes:

• WiFi station and provisioning.
• MQTT client for telemetry and heartbeat publishing.
• BLE GATT server exposing a ReceiptCharacteristic for receipt delivery.
• ECDSA verification using the device's hardware crypto engine where available, with a software fallback (tinycrypt or mbedTLS).
• A persistent, append-only feature_unlocks partition in flash.
• A small in-process ML hook (the ml/ module) reserved for on-device inference workloads that may themselves be feature-gated.

4. Architectural Diagram

┌─────────────┐    burn TATSU          ┌──────────────┐
│  User /     │──────────────────────► │  TatsuBurn   │
│  Portal     │                        │  Contract    │
└──────┬──────┘                        └──────┬───────┘
       │                                      │
       │ HTTPS                                │ FeatureUnlocked event
       ▼                                      ▼
┌─────────────┐    signed receipt      ┌──────────────┐
│ /api/       │◄───────────────────────│  Listener    │
│ receipt     │                        │  + Signer    │
└──────┬──────┘                        └──────────────┘
       │
       │ HTTPS → phone → BLE GATT
       ▼
┌─────────────┐    ECDSA verify        ┌──────────────┐
│  Firmware   │──────────────────────► │  Hardcoded   │
│  (Zephyr)   │                        │  Public Key  │
└─────────────┘                        └──────────────┘