Mdk

Building on MDK

MDK is a P2P mining device management platform layered as: Consumers → Gateway → Kernel (a.k.a. ORK) → Workers → Devices.

The Kernel (backend/core/kernel) discovers workers over the Hyperswarm DHT, pulls telemetry, dispatches commands, and monitors health. Workers (backend/workers/) are device-protocol adapters: a Worker Plugin, either a directory-loaded package (mdk-contract.json + src/ handlers, hosted on WorkerRuntimeV2 — the shape mdk create worker scaffolds) or the older { contract, dir, connect } + handler-module shape hosted on the generic WorkerRuntime (backend/core/mdk-worker; both shapes are documented in ../mdk-worker-plugin/references/worker-base-api.md). All Kernel ↔ Worker communication is MDK Protocol envelopes over @hyperswarm/rpc — never direct method calls.

Load references/architecture.md when you need the module-level picture, and references/protocol.md before touching anything that sends or receives envelopes. references/package-index.md maps every package name to its actual folder. references/glossary.md decodes the terminology.

Route to the right skill

Skills are installed as flat siblings — each row names a skill directory next to this one. Read this table first on every MDK task; many user prompts need more than one skill in order.

Single-skill tasks

Composite prompts (use multiple skills, in order)

Prompts like "create a UI to show <metric> for a <device>" are not UI-only. Follow this chain:

Skip step 2–3 when the route already exists and returns the right JSON. Skip step 1's device work — if the worker/channel is missing, insert mdk-worker-plugin before step 2.

User: "show / UI / dashboard for <metric> on <device family>"
        │
        ▼
  Contract exists? ──no──► mdk-worker-plugin ──┐
        │ yes                                  │
        ▼                                      ▼
  /api route exists? ──no──► mdk-gateway-plugin ──► mdk-deployment
        │ yes                                  │
        ▼                                      ▼
  mdk-ui-component  ◄──────────────────────────┘
        │
        ▼
  mdk-deployment (smoke: curl + UI)

Quick examples

Non-negotiable invariants

• Workers never call the Kernel. The protocol is unidirectional: the Kernel pulls (telemetry.pull, state.pull, health.ping) and pushes commands (command.request). A worker only ever answers handleRequest.
• mdk-contract.json is the single source of truth for a worker's telemetry, commands, health states and error codes. Validate it against references/mdk-contract.schema.json (the Kernel terminates workers whose capability payload is malformed, and rejects commands not declared in it).
• Never add transport-level envelope fields. The envelope is exactly { id, version, type, action, sender, target, deviceId, timestamp, payload } — extend payload instead.
• Use canonical @tetherto/mdk-* names only — the full list lives in references/package-index.md.
• Never invent UI prop names or telemetry fields — registry + contracts only (mdk-ui-component / mdk-gateway-plugin).