MDK

Status

⚠️ Work in Progress

MDK is under active development and is not yet considered stable.

Current release v0.5.0.

Table of Contents

• Overview
• Architecture
• Releases
• Get Started
• Build and develop
• Documentation
• Support
• Contributing
• License
• Acknowledgments

Overview

This repository is the monorepo for the Mining Development Kit MDK. MDK is a Node.js SDK for operating bitcoin mining hardware, providing a modular and extensible foundation for:

• Monitoring mining infrastructure
• Controlling devices and containers
• Collecting telemetry and operational data
• Building custom mining applications and integrations

The monorepo is organized into three development domains:

• core — Kernel, Gateway, MDK SDK, MDK client, mock control service
• Workers — protocol translators for data sources, e.g., miners, pools, power meters, sensors, containers
• UI toolkit — headless state and API contracts, React bindings, mining-domain components, and application scaffolding

You drive MDK via the Gateway. The Gateway is where your business logic is defined and MDK can be extended. It's your Node.js server that connects to the Kernel to receive data from, and send instructions to, Workers.

Architecture

MDK uses device credentials to collect telemetry continuously, dispatch commands, and expose device state through the Kernel to agents,applications, dashboards, and automation services. At Layer 1, Workers translate vendor protocols for miners, power meters, sensors, facility platforms, and pool APIs into the MDK Protocol.

Through the Gateway, AI agents, dashboards, and custom solutions monitor device state and issue authorized control commands through a consistent API.

That means that you can connect any physical hardware (e.g., miners, power meters, temperature sensors), facility management platforms (e.g., Antspace, Bitdeer), or pool APIs (e.g., OceanPool, F2Pool) by defining their Workers (at Layer 1), translating each source into the common MDK protocol. Furthermore, you have full control over configuring your deployments as single-process, local multi-process, or distributed deployments.

Layer 4 — Browser UI          (Optional dashboard/app layer)
        │  HTTP / WebSocket
        ▼
Layer 3 — Gateway            (Your Node.js server)
        │  HRPC (@hyperswarm/rpc)
        ▼
Layer 2 — Kernel              (Orchestration Kernel)
        │  MDK Protocol over HRPC
        ▼
Layer 1 — Workers             (Protocol translators)
        │  HTTP + vendor auth
        ▼
Layer 0 — Data sources        (Hardware, external APIs, facility platforms)

UI application layer

MDK can run without a UI, but the UI toolkit is a first-class development surface for operator applications. It connects dashboards and control interfaces to the Gateway without requiring applications to implement the MDK Protocol or hardware integrations directly.

• @tetherto/mdk-ui-foundation provides framework-independent state, API contracts, and query helpers
• @tetherto/mdk-react-adapter connects React applications to Gateway data and actions
• @tetherto/mdk-react-devkit provides reusable UI primitives and mining-domain components
• mdk-ui scaffolds applications, pages, and features

Use the packages together for a complete operator dashboard. You may develop your dashboards via the CLI reference: mdk-ui, the agent-oriented workflow, or directly compose the runtime packages in your own application structure.

Releases

The latest development code is available on the main branch. MDK follows Semantic Versioning 2.0.0: 0.y.z versions are initial development (public API not stable until 1.0.0); 1.0.0 and above denote a stable public API.

Releases have notes docs/reference/release-notes/](docs/reference/release-notes/) and the full version history is available as a [CHANGELOG.md`.

Get started

Note

Try the demo: run the full MDK stack: multiple configured Workers across a range of device families, their mock device servers, a Gateway HTTP API, and a React dashboard, all with one command

MDK ships a backend SDK and an optional dashboarding layer. Find your lane:

• I'm a hardware provider: where do I start? Build a Worker and author its mdk-contract.json
• I'm a site operator: how do I connect my Workers to a Gateway? Run an MDK site as a single process, or choose another deployment shape
• I'm an app developer building a React UI: scaffold or add MDK to an existing app with the UI toolkit and CLI
• I'm an app developer building backend services or Gateway plugins: run the backend stack locally or start with the Gateway API surfaces
• I'm an app developer building a dashboard end to end: follow Build a dashboard
• I'm building with AI: how do I point an agent at MDK? Read the agent entry points

Agents

If you are an LLM being pointed at this repo? Read these three first:

• ui/AGENTS.md: contract overview and a quick recipe
• ui/docs/AGENT_FIRST.md: manifests, blueprints, registry
• examples/backend/README.md: runnable shapes of the backend

Build and develop

The repo is federated: each domain keeps its own package manager, lock file, and install scripts, and a thin root package.json forwards commands to them. The root has no shared dependency graph, workspaces, or Turbo configuration.

Domain	Location	Tooling
UI	ui/	npm workspace (apps/* + packages/*) driven by Turbo
Core (backend)	backend/core/	independent per-process installs via install-packages.sh
Workers (backend)	backend/workers/	independent per-process installs via install-packages.sh

Run any task once from the repo root and it fans out to all three domains:

npm run setup       # install every domain (UI workspace + backend per-process installs)
npm run build       # build all domains (no-op where a domain has no build step)
npm run test        # test all domains
npm run lint        # lint all domains
npm run typecheck   # typecheck all domains (no-op where a domain has no typecheck step)

Each task also has per-domain variants when you only need one: :ui, :core, :workers (e.g. npm run test:ui, npm run lint:core). Use npm run ci instead of npm run setup for clean, lockfile-faithful installs in CI, and npm run clean to tear down build artifacts and installed dependencies.

To run the supported Worker fleet with mock devices as separate PM2 or Docker processes, use examples/site-backend/.

Note: setup/ci is the one-command installer; there is no root install script, so a plain npm install at the root installs nothing (the root has no dependencies of its own).

Documentation

Browse this repo's documentation or the published end-user documentation docs.mdk.tether.io which consumes pages from this repo.

Request updates to docs via docs-needed issue. Update documentation in this repository directly via the contribution flow.

Support

For support, raise a GitHub Issue or chat to the community on Discord.

Contributing

Contributions are welcome. Follow the contribution guide for setup, branch conventions, testing, and pull-request requirements.

For security vulnerability reporting, see the Security policy.

License

MDK is released under Apache License Version 2.0.

Acknowledgments

Built with contributions from the mining operations team.