MDK dashboard

` | `capabilities.telemetry` or `capabilities.commands` must be an array | | `ERR_PLUGIN_ENTRY_NAME_MISSING:

` | Give every telemetry/command entry a non-empty string `name` | | `ERR_PLUGIN_HANDLER_MISSING:

.` | Add that entry's relative `handler` path | | `ERR_PLUGIN_HANDLER_NOT_FOUND:

.: : ` | No file resolves at that path relative to the package root | | `ERR_PLUGIN_DUPLICATE_NAME:

.` | Rename or remove the duplicate entry in that section | **Device instantiation**: `runtime.start()` runs this per configured device (see [`worker-runtime-v2.js`](https://github.com/tetherto/mdk/blob/main/backend/core/mdk-worker/lib/worker-runtime-v2.js)), and [`createInstance`](https://github.com/tetherto/mdk/blob/main/backend/core/mdk-worker/index.js) (Step 7) runs the identical check for one device at a time in tests: | Error | Diagnostic and remediation | | ---------------------------------------------------------------------------- | ------------------------------------------------------------------ | | `ERR_INSTANCE_HANDLER_NOT_FOUND: :

.: ` | The path that resolved fine at contract-load time no longer resolves inside this device's module context; check for a typo | | `ERR_INSTANCE_HANDLER_LOAD_FAILED: :

.: ` | The handler file exists but throws while loading; the nested error names the real failure (a missing import, a syntax error) | | `ERR_INSTANCE_HANDLER_NOT_FUNCTION: :

.` | The module must assign a function to `module.exports` | For errors from a live Kernel registration or requests once your Worker is actually hosted, see [Troubleshooting](/guides/workers/test-a-worker) in Test a Worker with MDK. ## Next steps - Test your new [Worker's integration with MDK](/guides/workers/test-a-worker) - Understand the [security boundaries](/concepts/security-boundaries) - See the end-user experience of controlling and monitoring your device via the Worker in [Test a Worker's next steps](/guides/workers/test-a-worker) # Test a new Worker with MDK (/guides/workers/test-a-worker) This guide is for users of third-party worker packages or such partners who have integrated their own hardware, firmware, or data feed with MDK by shipping a [Worker plugin package](/guides/workers/build-a-worker). ## Overview Worker packages are the contract between the hardware and the Kernel, before relying on such a contract you will want to test its integration. To seed devices and register with Kernel, host the package on `WorkerRuntimeV2` in a Node.js host process by pointing it at the Worker plugin package's directory (see [Build a third-party Worker](/guides/workers/build-a-worker)). The host module may live in the Worker plugin package itself; a second npm package is **not required**. A separate host directory is recommended when independent plugin publication and plugin-only tests are useful: ```text your-worker-host/ index.js # host module: WorkerRuntimeV2, devices, lifecycle run-live.js # live Kernel registration and compatibility check ``` This mirrors [`examples/backend/demo-worker-caller/`](https://github.com/tetherto/mdk/blob/main/examples/backend/demo-worker-caller/index.js), which is an example directory containing one host module, not a standalone npm package. ## Prerequisites - Node.js `>=24` (all MDK core packages declare this `engines` constraint) - A completed [Worker plugin package](/guides/workers/build-a-worker), including its bundled mock device - Comfort with plain async JS — no additional MDK framework knowledge is required beyond what building the package already covered ### Install MDK `@tetherto/mdk-worker` (the package that ships `WorkerRuntimeV2`) is **not yet published to the npm registry** — MDK is pre-1.0 and still distributed as this monorepo. Until it is, the working path from an external repo is a git dependency plus a deep `require()` into the checked-out repo, exactly mirroring how every in-repo Worker already resolves it (by relative path, not through `node_modules` package resolution): ```bash npm install github:tetherto/mdk#main ``` This installs the whole monorepo under `node_modules/@tetherto/mdk` (its root `package.json` name). It does **not** auto-install the nested package's own dependencies — this repo's install is a federated set of scripts, not a single root dependency graph — so run its installer once after adding it: ```bash (cd node_modules/@tetherto/mdk/backend/core && ./install-packages.sh) ``` The same deep-path pattern also gets you `getKernel`, `startGateway`, and `waitForDiscovery` from `require('@tetherto/mdk/backend/core/mdk')`, used in Step 3 below. ### Write the host module `host/index.js`, modeled on [`examples/backend/demo-worker-caller/index.js`](https://github.com/tetherto/mdk/blob/main/examples/backend/demo-worker-caller/index.js): ```js "use strict"; const path = require("path"); const { WorkerRuntimeV2 } = require("@tetherto/mdk/backend/core/mdk-worker"); const WORKER_DIR = path.resolve(__dirname, "../your-worker-repo"); async function startVendorWorker({ workerId, kernelTopic, seedDevices }) { const runtime = new WorkerRuntimeV2(WORKER_DIR, { workerId, kernelTopic: kernelTopic || null, devices: (seedDevices || []).map((d) => ({ deviceId: d.id, config: d.opts, })), }); await runtime.start(); return { runtime, stop: () => runtime.stop(), }; } module.exports = { startVendorWorker }; ``` `WorkerRuntimeV2`'s first argument is the Worker plugin package's own directory, the same one that holds its `mdk-contract.json` (see [Build a third-party Worker](/guides/workers/build-a-worker)); there is no plugin module to `require()`. Required options are `workerId` and a non-empty `devices` array. Each device's `config` object here becomes the ambient `opts` its handlers read from `@tetherto/mdk-worker/device`. `kernelTopic` is needed only for DHT discovery. Without a `store`, `WorkerRuntimeV2` generates a new RPC keypair on restart. Pass a process-owned store if deployment requires stable identity. The host process also owns persistence, sampling loops, retries, secrets, and shutdown. See the [demo host module](https://github.com/tetherto/mdk/blob/main/examples/backend/demo-worker-caller/index.js) for a SQLite sampler example. `WorkerRuntimeV2` also exposes two read accessors for the host process: `getPublicKey()` returns the runtime's RPC public key (used to register with Kernel, shown in the next step), and `getDeviceContext(deviceId)` returns a frozen `{ deviceId, config, services }` for a device that is currently `online`, or `null` otherwise. There is no `device` key: a directory-loaded plugin has no per-device client object for the host to reach into, since handler modules bind to their device privately through the ambient context (see Step 4 of Build a third-party Worker). A host process that needs to act on a live device drives it the same way a Gateway request would, through `runtime.handleRequest(...)`, rather than through `getDeviceContext(...).device`. ### Register directly with a live Kernel When Kernel and the Worker host share a process, register the runtime's public key directly. The following host script (save it next to your worker as e.g. `host/run-live.js`) proves that Kernel accepted the Worker, that it reached `READY`, and that telemetry traverses the real client → Kernel → Worker path: ```js "use strict"; const os = require("os"); const path = require("path"); const { getKernel, waitForDiscovery, shutdown, } = require("@tetherto/mdk/backend/core/mdk"); const { createMdkClient } = require("@tetherto/mdk/backend/core/client"); const { startVendorWorker } = require("./index"); const vendorMock = require("../your-worker-repo/mock/server"); const ROOT = path.join(os.tmpdir(), `vendor-worker-${process.pid}`); function onceListening(mock) { if (mock.server.listening) return Promise.resolve(); return new Promise((resolve) => mock.server.once("listening", resolve)); } function withTimeout(promise, timeoutMs, code) { let timer; const timeout = new Promise((_resolve, reject) => { timer = setTimeout(() => reject(new Error(code)), timeoutMs); }); return Promise.race([promise, timeout]).finally(() => clearTimeout(timer)); } async function main() { let mock; let worker; let kernel; let client; try { mock = vendorMock.createServer({ host: "127.0.0.1", port: 9001, hashrateThs: 200, }); await onceListening(mock); kernel = await getKernel({ root: ROOT }); worker = await startVendorWorker({ workerId: "vendor-demo", seedDevices: [ { id: "vendor-0", opts: { host: "127.0.0.1", port: 9001 } }, ], }); await kernel.registerWorker(worker.runtime.getPublicKey()); const workers = await waitForDiscovery(kernel, { minWorkers: 1, timeoutMs: 30000, }); const ready = workers.find( (w) => w.workerId === "vendor-demo" && w.state === "READY", ); if (!ready || !ready.deviceIds.includes("vendor-0")) { throw new Error("ERR_WORKER_NOT_READY"); } client = createMdkClient({ hrpc: { key: kernel.getPublicKey() } }); await client.connect(); const telemetry = await withTimeout( client.pullTelemetry("vendor-0", "metrics"), 8000, "ERR_TELEMETRY_TIMEOUT", ); if (typeof telemetry.metrics?.hashrate_rt !== "number") { throw new Error("ERR_TELEMETRY_INVALID"); } console.log(`READY ${ready.workerId}: ${ready.deviceIds.join(", ")}`); console.log(`hashrate_rt=${telemetry.metrics.hashrate_rt}`); } finally { if (client) await client.close(); if (kernel) await shutdown(kernel); if (worker) await worker.stop(); if (mock) mock.exit(); } } main().catch((err) => { console.error(err); process.exitCode = 1; }); ``` Expected output: ```text READY vendor-demo: vendor-0 hashrate_rt=200 ``` The timeout wrapper bounds the client's wait but cannot cancel the current HRPC request. Always close the client during shutdown. Device-protocol cancellation is separately owned by the device client from Step 2. ### Use DHT discovery across processes or hosts For DHT discovery, generate and securely distribute one 32-byte hex topic, start the Worker first with `kernelTopic`, then start Kernel with the same `topic`. Do **not** also call `registerWorker()`: ```js "use strict"; const crypto = require("crypto"); const os = require("os"); const path = require("path"); const { getKernel, waitForDiscovery, shutdown, } = require("@tetherto/mdk/backend/core/mdk"); const { startVendorWorker } = require("./index"); const ROOT = path.join(os.tmpdir(), `vendor-worker-dht-${process.pid}`); async function main() { const topic = process.env.MDK_TOPIC || crypto.randomBytes(32).toString("hex"); let worker; let kernel; try { worker = await startVendorWorker({ workerId: "vendor-demo", kernelTopic: topic, seedDevices: [ { id: "vendor-0", opts: { host: "10.0.0.20", port: 9001 } }, ], }); kernel = await getKernel({ root: ROOT, topic }); const workers = await waitForDiscovery(kernel, { minWorkers: 1, timeoutMs: 45000, }); const ready = workers.find( (w) => w.workerId === "vendor-demo" && w.state === "READY", ); if (!ready) throw new Error("ERR_WORKER_NOT_READY"); console.log(`READY ${ready.workerId}: ${ready.deviceIds.join(", ")}`); } finally { if (kernel) await shutdown(kernel); if (worker) await worker.stop(); } } main().catch((err) => { console.error(err); process.exitCode = 1; }); ``` For separate production processes, each process must install signal handlers and close every handle it owns. DHT topics enable rendezvous; they are not authentication secrets or command-authorization tokens. See the [discovery model](/concepts/stack/workers) for DHT, Local, and Same-process trade-offs. ## Troubleshooting ### Runtime construction `new WorkerRuntimeV2(dir, opts)` runs two phases synchronously: it loads and validates the Worker plugin package at `dir` first (see [Troubleshooting](/guides/workers/build-a-worker) in Build a third-party Worker for `ERR_WORKER_DIR_REQUIRED` and the contract/handler errors), then validates `opts`: | Error | Diagnostic and remediation | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `ERR_WORKER_ID_REQUIRED` | Pass a non-empty string `workerId` | | `ERR_DEVICES_REQUIRED` | Pass a non-empty `devices` array, unless this is an intentional provisioning-first host using `allowEmptyDevices` | | `ERR_DEVICE_ID_MISSING` | Every device spec needs a non-empty string `deviceId` | | `ERR_DEVICE_ID_DUPLICATE: ` | Device IDs must be unique within one runtime | | `ERR_DEVICE_CONFIG_INVALID: ` | `config`, when supplied, must be a non-null object | `allowEmptyDevices` opts a host into a provisioning-first bootstrap: the runtime constructs with zero devices instead of throwing `ERR_DEVICES_REQUIRED`, then takes `registerThing` writes (a built-in command, see [Worker Runtime legacy services](https://github.com/tetherto/mdk/blob/main/docs/reference/maintainers/worker-runtime-legacy-services.md)) that persist new device configs to the store. Those writes only take effect once the host is stopped and restarted with the provisioned set — there is no hot-add. It is off by default; every shipped miner Worker in this monorepo sets it to `true` in its boot function. ### Startup and discovery | Symptom | Diagnostic and remediation | | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `waitForDiscovery()` returns no `READY` Worker | For direct registration, await `runtime.start()` and `kernel.registerWorker(runtime.getPublicKey())`. For DHT, start the Worker first and verify both processes use the same 32-byte hex topic and can reach the DHT network | | Worker is present but never `READY` | Inspect identity and capability failures. Confirm at least one device ID is reported and the contract has valid `metadata` and `capabilities` | Every device reports `online` as soon as `runtime.start()` returns; a directory-loaded plugin has no boot-time probe, so an unreachable device is never a startup symptom (see [Step 5](/guides/workers/build-a-worker) of Build a third-party Worker). If a device is unreachable, look for it at request time instead, in the table below. ### Request time | Error | Diagnostic and remediation | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ERR_DEVICE_NOT_FOUND: ` | The request targeted an ID not seeded in this runtime; compare it with the Kernel registry's `deviceIds` | | `ERR_DEVICE_ID_REQUIRED: ` | A named telemetry pull or command omitted its target device ID | | `ERR_UNKNOWN_QUERY_TYPE: ` | Use `metrics` or the exact `name` of a telemetry entry; the entry's return `type` is not its channel name | | `ERR_UNKNOWN_COMMAND: ` | Use the exact declared command name and confirm its handler loaded | | `ERR_UNKNOWN_ACTION: ` | Use a public MDK client helper instead of constructing protocol actions manually | | Command returns `status: 'FAILED'` | Read the stable `ERR_*` value, check validation/cooldown/device logs, and do not retry a timed-out physical write until its actual device state is known | An unreachable device does not surface as `ERR_DEVICE_UNAVAILABLE` for a directory-loaded plugin: with no `connect()` probe and no offline state, the failure comes back from inside the handler's own response instead, isolated to the telemetry channel that touched the network (`{ error: '...' }` under that channel's key in `metrics`, or `status: 'FAILED'` for a command); see the [directory-loaded plugin model](/guides/workers/build-a-worker) in Build a third-party Worker. ## Next steps - Understand the [security boundaries](/concepts/security-boundaries) Understand the end-user experience of controlling and monitoring your device via the Worker: - Build a [minimal dashboard](/tutorials/build-a-dashboard) around one Worker - Run the [Starter site example](https://github.com/tetherto/mdk/blob/main/examples/mvp-site/README.md) with a supervised, multi-Worker fleet - Connect [the operator agent](/guides/agent) to query and command your Workers over MCP # Reference (/reference) The Reference section indexes the canonical specs for everything MDK exposes: field semantics, signatures, transition rules, and contracts. Reach for it when you need exact shapes. ## Browse by stack area ### App Toolkit - **UI Devkit**: [components](/reference/ui/components/), [hooks](/reference/ui/hooks/), [types](/reference/ui/types/), and [utilities](/reference/ui/utilities/) for the React UI Devkit ### Kernel - **[Kernel](/reference/kernel/)**: kernel module specs, state machines, transition tables, and recovery behavior ### MDK Protocol - **[Protocol](/reference/protocol/)**: envelope schema, request/response examples, action catalogue, and base command set - *Capability contract*: coming soon ### Hardware - **[Supported hardware](/reference/supported-hardware/)**: miners, containers, power meters, sensors, and mining-pool integrations ### Workers - **[Workers](/reference/worker/)**: device protocol adapters that wrap vendor hardware APIs and expose them through the MDK Protocol ## Next steps - [Architecture](/concepts/architecture) for narrative explanations - [Try the demo](/tutorials/run-a-site) for step-by-step instructions # Glossary (/reference/glossary) This page provides explanations for terms that new users may not be familiar with. - [Stack](#stack-and-hardware-terms) - [HRPC](#hyperswarm-rpc) ## Stack and hardware terms This section explains the terms you need to familiarize yourself with, using an Antminer rack as an example. | Term | What it is | Lives at | | --- | --- | --- | | **Kernel** (Orchestration Kernel) | The pull-only kernel that owns the device registry, routes commands, and aggregates telemetry. | [`backend/core/kernel/index.js`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/index.js) | | **Gateway** | The developer-owned entry point between non-Node clients (UI, AI agents) and Kernel. Mandatory whenever a non-Node consumer reaches the kernel; not used in the in-process Antminer-rack example below. | [`backend/core/gateway/`](https://github.com/tetherto/mdk/blob/main/backend/core/gateway/worker.js) | | **Worker** | A device-family translator. Speaks the MDK Protocol upward to Kernel and the vendor's native API downward to one device family (one miner brand, one container type, one pool API). | [`backend/workers/docs/install-pattern.md`](https://github.com/tetherto/mdk/blob/main/backend/workers/docs/install-pattern.md) | | **Manager class** | The JavaScript class a Worker exports, one per supported device model. Instances drive a single rack of devices. | e.g. `AM_S19XP`, `AM_S21` in [`backend/workers/miners/antminer/index.js`](https://github.com/tetherto/mdk/blob/main/backend/workers/miners/antminer/index.js) | | **Thing** | One registered device instance. Created by calling `manager.registerThing({ info, opts })`. Identified by a generated `deviceId`. | runtime, in `manager.mem.things` | | **MCP** (Model Context Protocol) | The protocol AI agents use to discover and call tools. MDK's server is a standalone package — a separate process from the Gateway, not a Gateway plugin. | [`backend/core/mcp/`](https://github.com/tetherto/mdk/blob/main/backend/core/mcp/README.md) | ### How they compose, for an Antminer rack ```mermaid flowchart TB subgraph clientLayer ["Your code"] Client["your script (e.g., client.js)"] end subgraph kernel ["Kernel"] Kernel["Kernel
device registry · command routing · telemetry pull"] end subgraph workerLayer ["Antminer Worker"] AntminerWorker["e.g., AM_S21PRO"] end subgraph devices ["Antminer devices (real or mock)"] Miners["Antminers (HTTP / digest auth)"] end Client -->|"HRPC"| Kernel Kernel -->|"HRPC"| AntminerWorker AntminerWorker --> Miners ``` The same shape repeats for every other device family (Whatsminer, container vendors, pool APIs). For a multi-Worker view, parallel Workers, and multi-site deployments, see [`architecture.md#scaling`](/concepts/architecture#scaling). ## Hyperswarm RPC MDK uses [`@hyperswarm/rpc`](https://github.com/holepunchto/rpc) as its runtime transport. Hyperswarm RPC (HRPC) is not an HTTP-based RPC system. It is an RPC layer that rides on Hyperswarm peer-to-peer connectivity. The library is a simple RPC over the Hyperswarm DHT, backed by `Protomux`. Think of it as a peer-to-peer remote function call system built on a DHT and an encrypted connection layer. **Mental model** — Hyperswarm finds peers and establishes connections; `Protomux` divides the connection into named channels; RPC defines the conversation — a caller names a method and receives a reply. A useful analogy is a phone call between peers — Hyperswarm helps the phones find each other and connect; `Protomux` splits the line into channels; RPC defines how one side asks for a method and the other side responds. **Practical implications:** - You work with services, methods, requests, and responses — not URLs and routes - The RPC-shaped API is identical across same-process, same-host, and distributed deployments; only the discovery mechanism changes (same-process registration, shared directory, or DHT topic) - Peers discover and communicate without a central HTTP server ### HRPC on the same host MDK uses HRPC as the single transport across all deployment shapes — same-process, same-host, and distributed. Every component is addressed by its public key, not by a socket path or hostname. The Gateway, a standalone Node.js script, and a remote service all connect the same way: ```js createMdkClient({ hrpc: { key } }) ``` The Noise handshake that HRPC performs on every connection authenticates by key, so Kernel's allowlist works identically whether the caller is on the same machine or a remote host. This is consistent with the broader Holepunch ecosystem philosophy — everything is a peer addressed by public key. When the peer is on the same machine it routes locally over the local network interface; the application code sees no difference. ## Next steps - You are ready to run the example in [Run a mining site end to end](/tutorials/run-a-site) - Learn more about: - Multi-process discovery across machines: [Worker discovery](/concepts/stack/workers) - Gateway implementation details, including HTTP routing and plugin registration: [`backend/core/gateway/worker.js`](https://github.com/tetherto/mdk/blob/main/backend/core/gateway/worker.js) - Building your own Worker for a new device family: see [`backend/workers/docs/install-pattern.md`](https://github.com/tetherto/mdk/blob/main/backend/workers/docs/install-pattern.md) - Per-device contract details (telemetry units, command shapes, error codes): those live in each Worker's `mdk-contract.json`, e.g. [`backend/workers/miners/antminer/plugin/mdk-contract.json`](https://github.com/tetherto/mdk/blob/main/backend/workers/miners/antminer/plugin/mdk-contract.json) # Kernel reference (/reference/kernel) `@tetherto/mdk-kernel` is the orchestration kernel of the MDK stack. This subsection holds the canonical specs for its internal modules. For the architectural narrative explaining how these modules fit together, see [Kernel](/concepts/stack/kernel). ## What's documented - **[Modules](/reference/kernel/modules)**: per-module responsibility, interfaces, state machines, transition rules, crash-recovery procedures, and scaling characteristics # Kernel modules (/reference/kernel/modules) ## Overview [Kernel](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/index.js)'s coordination splits across single-purpose modules. Each owns its own state, persistence boundary, and scaling characteristics. It communicates with the others only through its declared interface. The [Kernel's Architecture overview](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#architecture) provides the canonical spec for each module's interfaces, state machine, and recovery behavior. ## Modules - [`WorkerRegistry`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#workerregistry): maps `deviceId` to `workerId` to RPC channel, and drives each Worker through its registration lifecycle - [`CommandDispatcher`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#commanddispatcher): validates an incoming command, resolves the target device or devices, and hands off to the Command State Machine - [`CommandStateMachine`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#commandstatemachine): tracks every command's execution lifecycle in a write-ahead log - [`TelemetryCollector`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#telemetrycollector): a stateless proxy that routes telemetry queries to the Worker that owns the data - [`Scheduler`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#scheduler): the system metronome that fires the recurring telemetry, health, and state jobs - [`HealthMonitor`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#healthmonitor): pings every registered Worker on a cadence and marks dead ones unroutable - [`ActionManager`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#actionmanager): handles the write action approval lifecycle at the Kernel layer - [`ActionCaller`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#actioncaller): resolves an approved action into the per-Worker write calls that carry it out ## Next steps - Review the [Protocol messages](/reference/protocol/messages): the actions these modules route and execute - See the [Kernel architecture](/concepts/stack/kernel): the architectural narrative behind this module split - Understand [approval-gated writes](/concepts/control-plane): the cross-layer flow [`ActionManager`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#actionmanager) and [`ActionCaller`](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#actioncaller) implement # Protocol reference (/reference/protocol) The MDK Protocol is the contract that crosses every layer of the stack: Workers, `@tetherto/mdk-kernel`, and the Gateway all exchange the same envelope. This subsection holds the canonical specs. For the architectural narrative explaining how the protocol fits together, see [Architecture](/concepts/architecture#the-mdk-protocol). ## What's documented - **[Messages](/reference/protocol/messages)**: envelope schema, request/response examples, the full action catalogue, and the base command set. # Protocol messages (/reference/protocol/messages) ## Overview Every MDK Protocol message uses the same envelope regardless of which layers are talking. This page shows the envelope shape and one worked example. ## Envelope ```json { "id": "uuid-v4", "version": "0.2.0", "type": "request | response | event", "action": "", "sender": "", "target": " | null", "deviceId": "string | null", "timestamp": 1711640000000, "payload": {} } ``` External consumers (UI or AI agents) only provide `deviceId`. [Kernel](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/index.js) resolves the target Worker identity internally. A concrete request and response pair, end to end: ```json // request: Gateway asks Kernel to reboot device wm-001 { "id": "8d1c-e3a4", "version": "0.2.0", "type": "request", "action": "command.request", "sender": "gateway", "target": null, "deviceId": "wm-001", "timestamp": 1711640000000, "payload": { "command": "reboot" } } // response: Kernel relays the Worker's terminal result { "id": "1f9b-77c2", "version": "0.2.0", "type": "response", "action": "command.result", "sender": "kernel:kernel:shard-1", "target": "gateway", "deviceId": "wm-001", "timestamp": 1711640002145, "payload": { "status": "SUCCESS", "elapsedMs": 2145 } } ``` ## Next steps - Learn more about actions and command targeting: - The [Kernel README](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#mdk-protocol) holds the full action catalogue (worker discovery, scheduled polling, command dispatch, kernel queries, and the write action lifecycle) and [command targeting rules](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#command-control) (`payload.scope`'s `device`, `worker`, and `rack` values, and the 1024-target cap) - [Approval-gated writes](/concepts/control-plane) details the write action lifecycle's full cross-layer flow, and use [the write-actions how-to](/guides/gateway/write-actions) to submit and approve actions from a Gateway consumer - [How MDK works](/concepts/architecture): for the architectural narrative explaining when each action fires - See the [Kernel MDK Protocol spec](https://github.com/tetherto/mdk/blob/main/backend/core/kernel/README.md#mdk-protocol) for every action, direction, and purpose - [Kernel modules](/reference/kernel/modules): the per-module specs that route and execute these actions - [Build a Worker](/guides/workers/build-a-worker): implement the Worker side of this protocol # Supported hardware (/reference/supported-hardware) ## Overview MDK integrates field hardware through Workers. Each Worker declares what it supports in its `mdk-contract.json`, and that contract is the single source of truth for coverage. Use this page to discover what Workers are supported. ## What MDK supports - **Miners**: For example, Bitmain Antminer, MicroBT Whatsminer - **Containers**: For example, Bitmain Antspace, Bitdeer - **Power meters**: For example, ABB, Satec - **Sensors**: For example, Seneca - **Mining pools**: Protocol integrations such as Ocean, F2Pool For the exact model lists, Worker packages, and per-Worker docs, see the generated catalogue: - [Full supported-hardware catalogue](https://github.com/tetherto/mdk/blob/main/backend/workers/docs/supported-hardware.md) — generated from every `backend/workers/**/mdk-contract.json` ## Next steps - New to the moving parts? Read [terminology](/reference/glossary) (Kernel, Worker, manager, thing, mock) - Decide how to run the Worker service — [Deployment topologies](/concepts/deployment-topologies) - Run a miner Worker — [Run a miner Worker](/guides/miners) # UI Reference (/reference/ui) Complete API reference for the MDK UI packages: `@tetherto/mdk-react-devkit`, `@tetherto/mdk-react-adapter`, and `@tetherto/mdk-ui-foundation`. ## Quick Links | Section | Description | Count | |---------|-------------|-------| | [Components](/reference/ui/components) | React components for building UIs | 286 components | | [Hooks](/reference/ui/hooks) | React hooks for state and data | 106 hooks | | [Query Helpers](/reference/ui/query-helpers) | TanStack Query helpers for data fetching | 43 queryHelpers | | [Stores](/reference/ui/stores) | Zustand stores for state management | 5 stores | | [Types](/reference/ui/types) | TypeScript type definitions | 257 types | | [Utilities](/reference/ui/utilities) | Helper functions and formatters | 149 utilities | ## Package Overview ### `@tetherto/mdk-react-devkit` The main UI component library. Provides: - Production-ready React components - Component-specific hooks - TypeScript types for all components ```tsx ``` ### `@tetherto/mdk-react-adapter` React bindings for the foundation layer. Provides: - Zustand store access hooks - Authentication hooks - Permission hooks - Data fetching hooks ```tsx ``` ### `@tetherto/mdk-ui-foundation` Framework-agnostic foundation layer. Provides: - Zustand stores - TanStack Query helpers - Utility functions - TypeScript types ```tsx ``` ## Getting Started 1. [Install the packages](/guides/ui/install) 2. Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` 3. Browse components by category or search for specific APIs # Components (/reference/ui/components) The `@tetherto/mdk-react-devkit` package provides production-ready React components organized by category. ## Prerequisites - Complete the installation ```bash # Clone the MDK UI monorepo (adjust the URL to your fork if needed) git clone https://github.com/tetherto/mdk.git cd mdk/ui # Install dependencies and build packages (npm workspaces) npm install npm run build ``` - Add the dependency to your app's `package.json` ```json { "dependencies": { "@tetherto/mdk-react-devkit": "*", "@tetherto/mdk-react-adapter": "*", "@tetherto/mdk-ui-foundation": "*" } } ``` > **Coming soon** — npm packages are not yet published. Use the monorepo setup for now. ```bash npm install \ @tetherto/mdk-react-devkit \ @tetherto/mdk-react-adapter \ @tetherto/mdk-ui-foundation ``` Run `npm install` from the `mdk/ui` workspace root after your app is under `apps/` so npm links workspace packages. - Import the core styles in your app's entry point: ```tsx ``` ## Browse by category | Category | Description | |----------|-------------| | [Actions](/reference/ui/components/actions) | Buttons, action triggers, and export controls | | [Auth](/reference/ui/components/auth) | Authentication and sign-in components | | [Branding](/reference/ui/components/branding) | Logos, wordmarks, and brand elements | | [Cards](/reference/ui/components/cards) | Card containers and card-based layouts | | [Charts](/reference/ui/components/charts) | Data visualization and chart components | | [Dashboard](/reference/ui/components/dashboard) | Dashboard layouts and containers | | [Dashboards](/reference/ui/components/dashboards) | Pre-built dashboard compositions | | [Dialogs](/reference/ui/components/dialogs) | Modal dialogs and confirmation prompts | | [Display](/reference/ui/components/display) | Data display and formatting components | | [Features](/reference/ui/components/features) | Feature-specific composite components | | [Feedback](/reference/ui/components/feedback) | Alerts, toasts, and user feedback | | [Filters](/reference/ui/components/filters) | Filter controls and filter bars | | [Forms](/reference/ui/components/forms) | Form inputs, selects, and validation | | [Layout](/reference/ui/components/layout) | Page layouts, grids, and spacing | | [Media](/reference/ui/components/media) | Images, icons, and media display | | [Misc](/reference/ui/components/misc) | Utility and miscellaneous components | | [Monitoring](/reference/ui/components/monitoring) | System monitoring and status displays | | [Navigation](/reference/ui/components/navigation) | Sidebars, tabs, and navigation menus | | [Overlays](/reference/ui/components/overlays) | Popovers, tooltips, and overlay panels | | [Pages](/reference/ui/components/pages) | Full-page layouts and page shells | | [Settings](/reference/ui/components/settings) | Settings panels and preference controls | | [Tables](/reference/ui/components/tables) | Data tables and table utilities | | [Widgets](/reference/ui/components/widgets) | Dashboard widgets and data cards | ## Import pattern Components are imported from the package root: ```tsx ``` ## Styling Components use BEM-style CSS classes (e.g., `.mdk-button`, `.mdk-card__header`) for styling consistency. Every component forwards `className` to its root element. # Action (/reference/ui/components/actions) Components for triggering actions and user interactions. ## Prerequisites - Complete the installation ```bash # Clone the MDK UI monorepo (adjust the URL to your fork if needed) git clone https://github.com/tetherto/mdk.git cd mdk/ui # Install dependencies and build packages (npm workspaces) npm install npm run build ``` - Add the dependency to your app's `package.json` ```json { "dependencies": { "@tetherto/mdk-react-devkit": "*", "@tetherto/mdk-react-adapter": "*", "@tetherto/mdk-ui-foundation": "*" } } ``` > **Coming soon** — npm packages are not yet published. Use the monorepo setup for now. ```bash npm install \ @tetherto/mdk-react-devkit \ @tetherto/mdk-react-adapter \ @tetherto/mdk-ui-foundation ``` Run `npm install` from the `mdk/ui` workspace root after your app is under `apps/` so npm links workspace packages. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit ### Button ```tsx ``` Primary action button with variants, sizes, loading state, icon placement, and full-width layout. Forwards refs and all native ` ) ``` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `ActionButton` [**`ActionButton`**](/reference/ui/components/actions/#actionbutton) component with confirmation popover or dialog `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string \| undefined` | | - | - | | `loading` | `boolean \| undefined` | | - | - | | `disabled` | `boolean \| undefined` | | - | - | | `className` | `string \| undefined` | | - | - | | `variant` | `TActionButtonVariant \| undefined` | | - | - | | `confirmation` | `ActionButtonConfirmation` | ✓ | - | - | | `mode` | `"dialog" \| "popover" \| undefined` | | - | Confirmation mode: popover (inline) or dialog (modal). Default: popover | ### `Button` Primary action button. Supports loading state with spinner, icon placement, variants, sizes, and full-width layout. Forwards refs and all native button attributes. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `loading` | `boolean` | | - | Show a spinner instead of the content and disable the button. | | `fullWidth` | `boolean` | | - | Make the button stretch to fill its container. | | `icon` | `React.ReactNode` | | - | Icon node rendered alongside `children`. | | `variant` | `ButtonVariant` | | - | Visual variant (e.g. `primary`, `secondary`, `ghost`). | | `contentClassName` | `string` | | - | Class names applied to the inner content wrapper. | | `iconPosition` | `ButtonIconPosition` | | - | Icon placement relative to children. | | `size` | `ComponentSize` | | - | Size token (`sm`, `md`, `lg`). | ### `StatsExport` Dropdown button that triggers asynchronous CSV or JSON export. Shows a spinner while the corresponding handler is awaited. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `showLabel` | `boolean \| undefined` | | - | - | | `disabled` | `boolean \| undefined` | | - | - | | `onCsvExport` | `() => Promise` | ✓ | - | - | | `onJsonExport` | `() => Promise` | ✓ | - | - | # Auth (/reference/ui/components/auth) Components for authentication flows and user sign-in. ## Prerequisites - Complete the installation ```bash # Clone the MDK UI monorepo (adjust the URL to your fork if needed) git clone https://github.com/tetherto/mdk.git cd mdk/ui # Install dependencies and build packages (npm workspaces) npm install npm run build ``` - Add the dependency to your app's `package.json` ```json { "dependencies": { "@tetherto/mdk-react-devkit": "*", "@tetherto/mdk-react-adapter": "*", "@tetherto/mdk-ui-foundation": "*" } } ``` > **Coming soon** — npm packages are not yet published. Use the monorepo setup for now. ```bash npm install \ @tetherto/mdk-react-devkit \ @tetherto/mdk-react-adapter \ @tetherto/mdk-ui-foundation ``` Run `npm install` from the `mdk/ui` workspace root after your app is under `apps/` so npm links workspace packages. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `RequireAuth` Route guard that reads the session token from the headless `authStore` (via `useAuth`) and renders the children only when a token is present. Otherwise it renders `fallback` — typically `` from `react-router`. Router-agnostic by design. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `children` | `React.ReactNode` | ✓ | - | Rendered when a token is present. | | `fallback` | `React.ReactNode` | ✓ | - | Rendered when no token is present — typically ``. | | `rememberPath` | `boolean \| undefined` | | - | When true (default), the current location is persisted to sessionStorage before rendering the fallback so the sign-in flow can return there. | ### `SignInGoogleButton` One-click Google OAuth sign-in trigger. Defaults to a full-page redirect to `${oauthBaseUrl}/oauth/google`, mirroring the production MOS flow. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `icon` | `React.ReactNode` | ✓ | - | Icon node rendered alongside `children`. | | `loading` | `boolean \| undefined` | ✓ | - | Show a spinner instead of the content and disable the button. | | `variant` | `ButtonVariant \| undefined` | ✓ | - | Visual variant (e.g. `primary`, `secondary`, `ghost`). | | `size` | `ComponentSize \| undefined` | ✓ | - | Size token (`sm`, `md`, `lg`). | | `fullWidth` | `boolean \| undefined` | ✓ | - | Make the button stretch to fill its container. | | `contentClassName` | `string \| undefined` | ✓ | - | Class names applied to the inner content wrapper. | | `iconPosition` | `ButtonIconPosition \| undefined` | ✓ | - | Icon placement relative to children. | | `oauthBaseUrl` | `string` | ✓ | - | Base URL of the OAuth backend (no trailing slash). Click navigates to `${oauthBaseUrl}/oauth/google`. | | `label` | `string \| undefined` | | - | Override the visible button label. | | `onClick` | `(() => void) \| undefined` | | - | Override the click behaviour entirely. When set, `oauthBaseUrl` is ignored. | # Branding (/reference/ui/components/branding) Components for brand identity and visual consistency. ## Prerequisites - Complete the installation ```bash # Clone the MDK UI monorepo (adjust the URL to your fork if needed) git clone https://github.com/tetherto/mdk.git cd mdk/ui # Install dependencies and build packages (npm workspaces) npm install npm run build ``` - Add the dependency to your app's `package.json` ```json { "dependencies": { "@tetherto/mdk-react-devkit": "*", "@tetherto/mdk-react-adapter": "*", "@tetherto/mdk-ui-foundation": "*" } } ``` > **Coming soon** — npm packages are not yet published. Use the monorepo setup for now. ```bash npm install \ @tetherto/mdk-react-devkit \ @tetherto/mdk-react-adapter \ @tetherto/mdk-ui-foundation ``` Run `npm install` from the `mdk/ui` workspace root after your app is under `apps/` so npm links workspace packages. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `MdkWordmark` MDK wordmark — the canonical brand lockup, rendered as inline SVG so it tints to `currentColor`. Use this in [``](/reference/ui/components/navigation/#appheader) (via the `logo` slot) or anywhere else the brand should appear. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `size` | `MdkWordmarkSize \| undefined` | | - | Visual size of the wordmark. `sm` ≈ 24px tall, `md` ≈ 32px, `lg` ≈ 64px. | | `className` | `string \| undefined` | | - | Optional class hook on the outer `

Chart content

) const [range, setRange] = useState('24h') return (

) } ``` #### Related API - [**`useChartDataCheck`**](/reference/ui/hooks/charts/#usechartdatacheck) @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `ActualEbitdaCard` Stat card summarising the realised EBITDA for the selected reporting window vs the prior period. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `value` | `number` | ✓ | - | - | ### `AreaChart` Presentational Chart.js area chart (Line with fill). Data must be provided via props; this component does no fetching of its own. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `ChartData<"line", (number \| Point \| null)[], unknown>` | ✓ | - | Chart data - required, provided by parent | | `options` | `_DeepPartialObject & ElementChartOptions<"line"> & PluginChartOptions<"line"> & DatasetChartOptions<"line"> & ScaleChartOptions<"line"> & LineControllerChartOptions> \| undefined` | | - | Chart.js options - merged with defaults | | `tooltip` | `ChartTooltipConfig \| undefined` | | - | Custom HTML tooltip configuration. When provided, replaces the default Chart.js tooltip. | | `height` | `number \| undefined` | | - | Chart height in pixels | | `className` | `string \| undefined` | | - | - | ### `AverageDowntimeChart` Stacked bar chart of average downtime (curtailment vs operational issues). Wraps [`ChartContainer`](/reference/ui/components/charts/#chartcontainer) and [`BarChart`](/reference/ui/components/charts/#barchart); pass period labels and rate arrays via `data`. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `title` | `string` | | - | - | | `unit` | `string` | | - | - | | `height` | `number` | | - | - | | `barWidth` | `number` | | - | - | | `className` | `string` | | - | - | | `isLoading` | `boolean` | | - | - | | `emptyMessage` | `string` | | - | - | | `data` | `AverageDowntimeChartData` | | - | - | | `yTicksFormatter` | `(value: number) => string` | | - | Formats Y-axis ticks, tooltips, and bar data labels (values are 0–1 rates). | | `showDataLabels` | `boolean` | | - | - | ### `AvgAllInCostChart` Avg All-in [**`Cost`**](/reference/ui/components/dashboards/#cost) - revenue vs cost ($/MWh) bar chart over time. Renders the OSS `SiteEnergyVsCostChart`. The revenue/cost time-series isn't carried by the cost-summary response, so consumers feed it through as a separate prop (the OSS app sources it from `useAvgAllInPowerCostData`). `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `readonly AvgAllInCostDataPoint[] \| undefined` | | - | - | | `dateRange` | `FinancialDateRange \| null` | ✓ | - | - | | `isLoading` | `boolean \| undefined` | | - | - | ### `BarChart` Presentational Chart.js bar chart. Data must be pre-aggregated; use grouped or stacked categories via `datasets`. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `any` | ✓ | - | Chart data - required, provided by parent. Use `as any` for mixed bar+line datasets. | | `options` | `_DeepPartialObject & ElementChartOptions<"bar"> & PluginChartOptions<"bar"> & DatasetChartOptions<"bar"> & ScaleChartOptions<"bar"> & BarControllerChartOptions> \| undefined` | | - | Chart.js options - merged with defaults | | `isStacked` | `boolean \| undefined` | | - | Stack bars on top of each other | | `isHorizontal` | `boolean \| undefined` | | - | Render bars horizontally (indexAxis: 'y') | | `formatYLabel` | `((value: number) => string) \| undefined` | | - | Format Y-axis tick labels | | `showLegend` | `boolean \| undefined` | | - | Show built-in Chart.js legend (default: true) | | `legendPosition` | `Position \| undefined` | | - | Position of the legend (default: 'top') | | `legendAlign` | `FlexAlign \| undefined` | | - | Alignment of the legend labels within their position (default: 'start') | | `showDataLabels` | `boolean \| undefined` | | - | Show values above each bar | | `formatDataLabel` | `((value: number) => string) \| undefined` | | - | Format data label values (default: round to nearest integer) | | `tooltip` | `ChartTooltipConfig \| undefined` | | - | Custom HTML tooltip configuration. When provided, replaces the default Chart.js tooltip. | | `height` | `number \| undefined` | | - | Chart height in pixels | | `className` | `string \| undefined` | | - | - | ### `BitcoinPriceCard` Stat card showing the BTC reference price used by the reporting view with currency and timestamp. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `value` | `number` | ✓ | - | - | ### `BitcoinProducedCard` Stat card summarising the bitcoin produced during the reporting window with delta to prior period. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `value` | `number` | ✓ | - | - | ### `BitcoinProducedChart` Time-series chart of bitcoin produced per day across the selected reporting window. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `chartData` | `BarChartDataResult` | ✓ | - | - | | `isLoading` | `boolean \| undefined` | | - | - | | `hasAllZeros` | `boolean \| undefined` | | - | - | | `height` | `number \| undefined` | | - | - | ### `BitcoinProductionCostCard` Stat card showing the average cost in USD to produce one bitcoin during the reporting window. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `value` | `number` | ✓ | - | - | ### `ChartContainer` Standard chrome for charts: title, optional highlighted value, legend with toggle, range selector (radio cards), loading / empty states, and a footer for min/max/avg stats. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `title` | `string \| undefined` | | - | - | | `titleExtra` | `React.ReactNode` | | - | Optional node rendered immediately after the title text (e.g. an info tooltip). Only shown when `title` is set and `header` is not. Additive - omit it and the title renders exactly as before. | | `header` | `React.ReactNode` | | - | - | | `headerAction` | `React.ReactNode` | | - | Optional action rendered on the right side of the header row (e.g. an expand/fullscreen toggle). Sits alongside the range selector when both are present. Purely additive - omit it and the header renders exactly as before. | | `legendData` | `LegendItem[] \| undefined` | | - | - | | `highlightedValue` | `HighlightedValueProps \| undefined` | | - | - | | `rangeSelector` | `RangeSelectorProps \| undefined` | | - | - | | `loading` | `boolean \| undefined` | | - | - | | `empty` | `boolean \| undefined` | | - | - | | `emptyMessage` | `string \| undefined` | | - | - | | `minMaxAvg` | `Partial<{ min: string; max: string; avg: string; }> \| undefined` | | - | - | | `timeRange` | `string \| undefined` | | - | - | | `footer` | `React.ReactNode` | | - | - | | `footerClassName` | `string \| undefined` | | - | - | | `className` | `string \| undefined` | | - | - | | `children` | `React.ReactNode` | ✓ | - | - | | `onToggleDataset` | `((index: number) => void) \| undefined` | | - | - | ### `ChartExpandAction` Expand / collapse toggle rendered in a dashboard chart card's header. Swaps between a maximize and a minimize glyph based on `isExpanded`. `advanced` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isExpanded` | `boolean` | ✓ | - | Whether the parent chart is currently expanded to full width. | | `onToggle` | `VoidFunction \| undefined` | | - | Toggles the expanded state. | ### `ChartStatsFooter` [**`ChartStatsFooter`**](/reference/ui/components/charts/#chartstatsfooter) - Displays Min/Max/Avg values and optional stats grid below a chart `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `minMaxAvg` | `Partial<{ min: string; max: string; avg: string; }>` | | - | Min/Max/Avg values row | | `stats` | `ChartStatsFooterItem[]` | | - | Additional stats displayed in a columnar grid | | `statsPerColumn` | `number` | | - | Number of stat items per column (default: 1) | | `secondaryLabel` | `SecondaryLabel` | | - | Secondary label displayed below stats | | `className` | `string` | | - | Custom class name | ### `CostCharts` Convenience wrapper that renders the three cost-page charts in declaration order. Pages that need bespoke layouts (e.g. [`CostContent`](/reference/ui/components/dashboards/#costcontent)'s 2x2 [**`Mosaic`**](/reference/ui/components/layout/#mosaic)) compose the individual chart components directly instead. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `costLog` | `readonly CostTimeSeriesEntry[]` | ✓ | - | - | | `btcPriceLog` | `readonly BtcPriceTimeSeriesEntry[]` | ✓ | - | - | | `totals` | `CostSummaryMonetaryTotals \| null` | ✓ | - | - | | `dateRange` | `FinancialDateRange \| null` | ✓ | - | - | | `avgAllInCostData` | `readonly AvgAllInCostDataPoint[] \| undefined` | | - | - | | `isLoading` | `boolean \| undefined` | | - | - | ### `DetailLegend` [**`DetailLegend`**](/reference/ui/components/charts/#detaillegend) - Enhanced chart legend with current values and percentage change indicators `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `items` | `DetailLegendItem[]` | ✓ | - | Legend items to display | | `onToggle` | `((label: string, index: number) => void) \| undefined` | | - | Callback when a legend item is toggled | | `className` | `string \| undefined` | | - | Custom class name | ### `DoughnutChart` [**`DoughnutChart`**](/reference/ui/components/charts/#doughnutchart) – Presentational Chart.js doughnut chart with custom HTML legend matching the MDK design. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `DoughnutChartDataset[]` | ✓ | - | Array of labelled slices | | `unit` | `string \| undefined` | | - | Unit suffix shown in tooltips | | `options` | `_DeepPartialObject & ElementChartOptions<"doughnut"> & PluginChartOptions<"doughnut"> & DatasetChartOptions<"doughnut"> & ScaleChartOptions<"doughnut"> & DoughnutControllerChartOptions> \| undefined` | | - | Chart.js options – merged with defaults | | `cutout` | `string \| undefined` | | - | Doughnut cutout percentage (default: '75%') | | `borderWidth` | `number \| undefined` | | - | Border width between segments (default: 4) | | `height` | `number \| undefined` | | - | Chart height in pixels | | `legendPosition` | `Position \| undefined` | | - | Where to place the legend relative to the chart (default: 'top') | | `tooltip` | `ChartTooltipConfig \| undefined` | | - | Custom HTML tooltip configuration. When provided, replaces the default doughnut tooltip (which shows label, value with unit, and percentage). Use `valueFormatter` to replicate the percentage display if needed. | | `formatValue` | `((value: number) => string) \| undefined` | | - | Formats slice values in the built-in legend and default tooltip (default: raw number). | | `className` | `string \| undefined` | | - | - | ### `Ebitda` Top-level EBITDA section of the reporting view — pulls together metric cards, charts, and tables. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `metrics` | `EbitdaDisplayMetrics \| null` | ✓ | - | - | | `ebitdaChartInput` | `ToBarChartDataInput \| null` | ✓ | - | - | | `btcProducedChartInput` | `ToBarChartDataInput \| null` | ✓ | - | - | | `hasBtcProducedAllZeros` | `boolean` | ✓ | - | - | | `showEbitdaBarChart` | `boolean` | ✓ | - | - | | `currentBTCPrice` | `number` | ✓ | - | - | | `datePicker` | `React.ReactElement>` | ✓ | - | - | | `isLoading` | `boolean \| undefined` | | - | - | | `errors` | `string[] \| undefined` | | - | - | | `hasDateSelection` | `boolean` | ✓ | - | When false, show the "select a period" hint instead of empty data. | | `setCostHref` | `string \| undefined` | | - | Optional URL for the "Set Monthly [**`Cost`**](/reference/ui/components/dashboards/#cost)" control (hidden when omitted). | ### `EbitdaCharts` Chart panel inside the EBITDA section visualising revenue, cost, and EBITDA over time. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `showEbitdaBarChart` | `boolean` | ✓ | - | - | | `ebitdaChartData` | `BarChartDataResult` | ✓ | - | - | | `btcDisplayData` | `BarChartDataResult` | ✓ | - | - | | `isLoading` | `boolean` | ✓ | - | - | | `hasBtcProducedAllZeros` | `boolean` | ✓ | - | - | ### `EbitdaHodlCard` Stat card projecting EBITDA assuming all produced bitcoin is held instead of sold. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `value` | `number` | ✓ | - | - | | `currentBTCPrice` | `number` | ✓ | - | - | ### `EbitdaMetrics` Row of summary metric cards across the top of the EBITDA section (actual, hodl, selling, cost). `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `metrics` | `EbitdaDisplayMetrics` | ✓ | - | - | | `currentBTCPrice` | `number` | ✓ | - | - | ### `EbitdaSellingCard` Stat card projecting EBITDA assuming all produced bitcoin is sold at the daily reference price. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `value` | `number` | ✓ | - | - | ### `EnergyBalance` Full energy balance view with tabbed revenue and cost sections, charts, and metric cards. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `viewModel` | `EnergyBalanceViewModel` | ✓ | - | - | | `onTabChange` | `(tab: EnergyBalanceTab) => void` | ✓ | - | - | | `onRevenueDisplayModeChange` | `(mode: DisplayMode) => void` | ✓ | - | - | | `onCostDisplayModeChange` | `(mode: DisplayMode) => void` | ✓ | - | - | | `isDemoMode` | `boolean \| undefined` | | - | - | | `timeframeControls` | `React.ReactNode` | | - | Slot for timeframe / date-range controls rendered by the host app. | | `setCostHref` | `string \| undefined` | | - | Optional URL for the "Set Monthly [**`Cost`**](/reference/ui/components/dashboards/#cost)" control (hidden when omitted). | ### `EnergyBalanceCostCharts` Layout container for the energy cost tab charts: revenue-vs-cost bar chart and power line chart. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `costChartData` | `BarChartDataResult` | ✓ | - | - | | `btcUnit` | `string \| null` | ✓ | - | - | | `powerChartInput` | `ThresholdLineChartInput` | ✓ | - | - | | `displayMode` | `DisplayMode` | ✓ | - | - | | `barLabelFormatter` | `(v: number) => string` | ✓ | - | - | | `onDisplayModeChange` | `(mode: DisplayMode) => void` | ✓ | - | - | | `showCostBarChart` | `boolean` | ✓ | - | Show the revenue-vs-cost bar chart only for non-daily periods. | | `periodType` | `PeriodType` | ✓ | - | - | ### `EnergyBalanceCostMetrics` Grid of stat cards summarising energy cost metrics for the selected period. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `metrics` | `EnergyCostMetrics` | ✓ | - | - | ### `EnergyBalancePowerChart` Line chart visualising power consumption against threshold for the energy balance view. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `height` | `number \| undefined` | | - | - | | `fillHeight` | `boolean \| undefined` | | - | - | | `periodType` | `PeriodType` | ✓ | - | - | | `chartInput` | `ThresholdLineChartInput` | ✓ | - | - | ### `EnergyBalanceRevenueCharts` [**`Mosaic`**](/reference/ui/components/layout/#mosaic) layout of revenue, downtime, and power charts for the energy balance revenue tab. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `revenueChartData` | `BarChartDataResult` | ✓ | - | - | | `averageDowntimeData` | `AverageDowntimeChartData` | ✓ | - | - | | `powerChartInput` | `ThresholdLineChartInput` | ✓ | - | - | | `displayMode` | `DisplayMode` | ✓ | - | - | | `barLabelFormatter` | `(v: number) => string` | ✓ | - | - | | `onDisplayModeChange` | `(mode: DisplayMode) => void` | ✓ | - | - | | `periodType` | `PeriodType` | ✓ | - | - | | `revenueMetrics` | `EnergyRevenueMetrics` | ✓ | - | - | ### `EnergyBalanceRevenueMetrics` Grid of stat cards summarising energy revenue metrics for the selected period. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `metrics` | `EnergyRevenueMetrics` | ✓ | - | - | ### `EnergyCostChart` Bar chart comparing site revenue vs cost per MWh, with USD/BTC currency toggle. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `chartData` | `BarChartDataResult` | ✓ | - | - | | `btcUnit` | `string \| null` | ✓ | - | - | | `displayMode` | `DisplayMode` | ✓ | - | - | | `barLabelFormatter` | `(v: number) => string` | ✓ | - | - | | `onDisplayModeChange` | `(mode: DisplayMode) => void` | ✓ | - | - | | `height` | `number \| undefined` | | - | - | ### `EnergyMetricCard` Stat card for a single energy balance metric. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `name` | `string` | ✓ | - | - | | `value` | `number` | ✓ | - | - | | `unit` | `string` | ✓ | - | - | | `fallback` | `string \| undefined` | | - | - | ### `EnergyReportMinerTypeView` Energy report — power consumption grouped by miner model (latest day in range). `advanced` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isLoading` | `boolean \| undefined` | | - | - | | `containers` | `Container[] \| undefined` | | - | - | | `groupedConsumption` | `MetricsConsumptionGroupedResponse \| undefined` | | - | - | | `onTimeFrameChange` | `((start: Date, end: Date) => void) \| undefined` | | - | - | ### `EnergyReportMinerUnitView` Energy report — power consumption grouped by mining unit / container. `advanced` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isLoading` | `boolean \| undefined` | | - | - | | `containers` | `Container[] \| undefined` | | - | - | | `groupedConsumption` | `MetricsConsumptionGroupedResponse \| undefined` | | - | - | | `onTimeFrameChange` | `((start: Date, end: Date) => void) \| undefined` | | - | - | ### `EnergyReportSiteView` Energy report site tab — power trend, power-mode table, and per–mining-unit activity cards. `advanced` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `consumptionError` | `unknown` | | - | - | | `tailLogLoading` | `boolean \| undefined` | | - | - | | `containersLoading` | `boolean \| undefined` | | - | - | | `consumptionLoading` | `boolean \| undefined` | | - | - | | `consumptionFetching` | `boolean \| undefined` | | - | - | | `nominalConfigLoading` | `boolean \| undefined` | | - | - | | `containers` | `EnergyReportContainer[] \| undefined` | | - | - | | `tailLog` | `EnergyReportTailLogItem[][] \| undefined` | | - | - | | `nominalPowerAvailabilityMw` | `number \| null \| undefined` | | - | - | | `consumptionLog` | `MetricsConsumptionLogEntry[] \| undefined` | | - | - | | `snapshotLoading` | `boolean \| undefined` | | - | - | | `onRefetchSnapshot` | `VoidFunction \| undefined` | | - | - | | `dateRange` | `EnergyReportDateRange` | ✓ | - | - | | `onDateRangeChange` | `((range: EnergyReportDateRange) => void) \| undefined` | | - | - | ### `EnergyRevenueChart` Bar chart showing site energy revenue per MWh, with USD/BTC currency toggle. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `chartData` | `BarChartDataResult` | ✓ | - | - | | `displayMode` | `DisplayMode` | ✓ | - | - | | `barLabelFormatter` | `(v: number) => string` | ✓ | - | - | | `onDisplayModeChange` | `(mode: DisplayMode) => void` | ✓ | - | - | | `height` | `number \| undefined` | | - | - | ### `GaugeChart` [**`GaugeChart`**](/reference/ui/components/charts/#gaugechart) - Presentational gauge / speedometer chart. Implementation note: this component used to wrap the `react-gauge-chart` NPM package, but that package is published only as CommonJS with a broken `module` field that points at the same CJS file. That made it crash under ESM bundlers that don't add a `__esModule ? .default : module` interop shim (Webpack 4, raw esbuild, certain SSR setups, etc.) with React's "Element type is invalid" error. We replaced it with a pure-SVG internal implementation (see `./gauge-svg.tsx`) so the component is bundler- and runtime-agnostic and has zero third-party runtime dependencies. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `percent` | `number` | ✓ | - | Value between 0 and 1 (e.g. 0.75 = 75%). Values outside the range are clamped. | | `colors` | `string[] \| undefined` | | - | Arc colours in HEX format. | | `arcWidth` | `number \| undefined` | | - | Arc thickness as a fraction of the gauge radius (0–1). | | `nrOfLevels` | `number \| undefined` | | - | Number of arc segments. Ignored when `arcsLength` is provided. | | `arcsLength` | `number[] \| undefined` | | - | Custom arc-segment proportions (auto-normalised), overriding `nrOfLevels`. e.g. `[0.7, 0.3]` for a progress-style gauge whose first arc is the fill. | | `needleColor` | `string \| undefined` | | - | Needle + hub colour. | | `hideNeedle` | `boolean \| undefined` | | - | Hide the needle + hub (e.g. for a progress-style gauge). | | `formatTextValue` | `((percent: number) => string) \| undefined` | | - | Format the centre label from the clamped fraction (0–1). | | `hideText` | `boolean \| undefined` | | - | Hide the percentage text rendered inside the gauge. | | `id` | `string \| undefined` | | - | Stable id used for the gauge's accessibility labels. | | `height` | `string \| number \| undefined` | | - | Chart height in pixels or any CSS length (e.g. `'200px'` or `'50%'`). | | `maxWidth` | `number \| undefined` | | - | Maximum width in pixels. | | `className` | `string \| undefined` | | - | - | ### `Hashrate` Top-level hashrate reporting section - composes the site / miner-type / mining-unit drilldowns into a tabbed shell. Each tab fetches independently because the three views use different `groupBy` axes; the composite stitches them via per-tab prop bags. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `defaultTab` | `HashrateTabValue \| undefined` | | - | Tab selected on first render. Defaults to the Site View. | | `siteView` | `HashrateSiteViewProps \| undefined` | | - | Props forwarded to the Site View tab. | | `minerTypeView` | `HashrateMinerTypeViewProps \| undefined` | | - | Props forwarded to the Miner Type View tab. | | `miningUnitView` | `HashrateMiningUnitViewProps \| undefined` | | - | Props forwarded to the Mining Unit View tab. | ### `HashrateMinerTypeView` [**`Hashrate`**](/reference/ui/components/charts/#hashrate) drilldown grouped by miner model - bar chart of the latest hashrate per miner type, with an optional multi-select filter. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `log` | `HashrateGroupedLog \| undefined` | | - | [**`Hashrate`**](/reference/ui/components/charts/#hashrate) log grouped by miner type (groupBy=miner). | | `isLoading` | `boolean \| undefined` | | - | - | | `dateRange` | `HashrateDateRange \| undefined` | | - | - | | `onDateRangeChange` | `((range: HashrateDateRange) => void) \| undefined` | | - | - | | `onReset` | `VoidFunction \| undefined` | | - | - | ### `HashrateMiningUnitView` [**`Hashrate`**](/reference/ui/components/charts/#hashrate) drilldown grouped by mining unit / container - bar chart of the latest hashrate per container with an optional multi-select filter. Drops BE-leaked rollup keys (`group-N`, `maintenance`) via the utils layer. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `log` | `HashrateGroupedLog \| undefined` | | - | [**`Hashrate`**](/reference/ui/components/charts/#hashrate) log grouped by container / mining unit (groupBy=container). | | `isLoading` | `boolean \| undefined` | | - | - | | `dateRange` | `HashrateDateRange \| undefined` | | - | - | | `onDateRangeChange` | `((range: HashrateDateRange) => void) \| undefined` | | - | - | | `onReset` | `VoidFunction \| undefined` | | - | - | ### `HashrateSiteView` Site-level hashrate trend - aggregates hashrate across the whole site for the selected date range, with an optional miner-type filter that scopes the sum to a subset. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `log` | `HashrateGroupedLog \| undefined` | | - | [**`Hashrate`**](/reference/ui/components/charts/#hashrate) log grouped by miner type. | | `isLoading` | `boolean \| undefined` | | - | Loading state - drives the chart spinner. | | `dateRange` | `HashrateDateRange \| undefined` | | - | Selected date range used by the host to drive the query. | | `onDateRangeChange` | `((range: HashrateDateRange) => void) \| undefined` | | - | Fires when the user picks a new range from the [**`DateRangePicker`**](/reference/ui/components/forms/#daterangepicker). | | `onReset` | `VoidFunction \| undefined` | | - | Optional reset handler shown as a "Reset" button next to the date picker. | ### `Heatmap` [**`Heatmap`**](/reference/ui/components/charts/#heatmap) — a generic grid of value-coloured cells on a low→high gradient. Presentational and domain-agnostic: pass a row-major matrix of cells and an optional `[min, max]` range (auto-derived otherwise). Use `renderCell` to overlay domain content (socket borders, selection, tooltips) without forking the primitive — the grid still owns each cell's background colour. Pair with [`HeatmapLegend`](/reference/ui/components/charts/#heatmaplegend) for a gradient scale. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `HeatmapCell[][]` | ✓ | - | Rows of cells (row-major). Rows may be ragged. | | `min` | `number \| undefined` | | - | Range floor; auto-derived from the finite values when omitted. | | `max` | `number \| undefined` | | - | Range ceiling; auto-derived from the finite values when omitted. | | `colors` | `readonly string[] \| undefined` | | - | Gradient stops low→high. Defaults to the cold→hot `HEATMAP_GRADIENT`. | | `emptyColor` | `string \| undefined` | | - | Colour used for `null` cells. | | `showValues` | `boolean \| undefined` | | - | Render each cell's value/label as text. | | `renderCell` | `((cell: HeatmapCell, context: HeatmapCellContext) => React.ReactNode) \| undefined` | | - | Override the cell's inner content — e.g. to overlay socket borders, selection, or tooltips for a PDU grid. The primitive still owns the cell's background colour (passed via `context.color`). | | `ariaLabel` | `string \| undefined` | | - | Accessible label for the grid. | | `className` | `string \| undefined` | | - | - | ### `HeatmapLegend` [**`HeatmapLegend`**](/reference/ui/components/charts/#heatmaplegend) — a gradient bar with low/high scale labels, matching the gradient used by [`Heatmap`](/reference/ui/components/charts/#heatmap). `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `min` | `string \| number` | ✓ | - | Value (or pre-formatted label) at the low end of the scale. | | `max` | `string \| number` | ✓ | - | Value (or pre-formatted label) at the high end of the scale. | | `unit` | `string \| undefined` | | - | Unit suffix appended to `min`/`max`. | | `label` | `string \| undefined` | | - | Heading above the gradient bar (e.g. "Temperature"). | | `colors` | `readonly string[] \| undefined` | | - | Gradient stops low→high. Defaults to `HEATMAP_GRADIENT`. | | `className` | `string \| undefined` | | - | - | ### `LineChart` Customisable Chart.js line chart with built-in zoom, tooltip, and legend. Data is passed via props; the component does no fetching. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `chartRef` | `React.MutableRefObject \| undefined` | | - | Mutable ref to hold the LightWeightCharts reference | | `data` | `LineChartData` | ✓ | - | Data of the chart | | `yTicksFormatter` | `((value: number) => string) \| undefined` | | - | Callback to format ticks on y axis. If `priceFormatter` is given. It would be used instead. | | `customLabel` | `string \| undefined` | | - | TODO: Doc | | `priceFormatter` | `((value: number) => string) \| undefined` | | - | Callback to format ticks on y axis. | | `roundPrecision` | `number \| undefined` | | - | The number of decimals to show | | `timeline` | `string \| undefined` | | - | TODO: DOC | | `fixedTimezone` | `string \| undefined` | | - | Applies offset if provided, otherwise timestamps are assumed to already be in local time. Otherwise, use browser's current timezone offset for consistent time display | | `shouldResetZoom` | `boolean \| undefined` | | - | Wether to Reset Zoom | | `skipRound` | `boolean \| undefined` | | - | Prevent rounding of values | | `skipMinWidth` | `boolean \| undefined` | | - | Do not enforce a min width | | `fadedBackground` | `boolean \| undefined` | | - | Use a faded background | | `backgroundColor` | `string \| undefined` | | - | Background color of the chart | | `customDateFormat` | `string \| undefined` | | - | Custom date format | | `verticalLineLabelVisible` | `boolean \| undefined` | | - | Show vertical line at mouse position | | `horizontalLineLabelVisible` | `boolean \| undefined` | | - | Show horizontal line at mouse position | | `showDateInTooltip` | `boolean \| undefined` | | - | Show date line in tooltip | | `disableAutoRange` | `boolean \| undefined` | | - | Disable automatically determining range | | `uniformDistribution` | `boolean \| undefined` | | - | Changes horizontal scale marks generation. With this flag equal to true, marks of the same weight are either all drawn or none are drawn at all. | | `unit` | `string \| undefined` | | - | The unit to display with values | | `beginAtZero` | `boolean \| undefined` | | - | Starts the value axis at 0 | | `showPointMarkers` | `boolean \| undefined` | | - | Show a marker on the line | | `height` | `number \| undefined` | | - | Controls the height of the chart. Default: 240 | ### `LineChartCard` Composable line-chart card with title, timeline range selector, legend (basic or detailed), error boundary, and an optional min/max/avg footer. Accepts either pre-shaped `data` or `rawData` + a `dataAdapter` callback so upstream domain components can keep their data wrangling local. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `LineChartCardData` | | - | Pre-adapted chart data (use this OR rawData+dataAdapter) | | `rawData` | `unknown` | | - | Raw data to be transformed by dataAdapter | | `dataAdapter` | `(data: unknown) => LineChartCardData` | | - | Adapter to transform rawData into LineChartCardData | | `timelineOptions` | `TimelineOption[]` | | - | Timeline range selector options | | `timeline` | `string` | | - | Controlled timeline value | | `defaultTimeline` | `string` | | - | Default timeline when uncontrolled | | `onTimelineChange` | `(timeline: string) => void` | | - | Callback when timeline changes | | `title` | `string` | | - | Chart title | | `detailLegends` | `boolean` | | - | Show detail legends with current values | | `isLoading` | `boolean` | | - | Loading state | | `shouldResetZoom` | `boolean` | | - | Whether to reset zoom on timeline change (default: true) | | `chartProps` | `Partial` | | - | Pass-through props to the core [**`LineChart`**](/reference/ui/components/charts/#linechart) | | `chartRef` | `React.MutableRefObject` | | - | Ref to the lightweight-charts IChartApi | | `minHeight` | `string \| number` | | - | - | | `className` | `string` | | - | Custom class name | | `headerAction` | `React.ReactNode` | | - | Optional action rendered on the right of the card header (e.g. an expand toggle). Passed straight through to [`ChartContainer`](/reference/ui/components/charts/#chartcontainer). Additive - omit it and the card header is unchanged. | | `titleExtra` | `React.ReactNode` | | - | Optional node rendered next to the title (e.g. an info tooltip). Passed straight through to [`ChartContainer`](/reference/ui/components/charts/#chartcontainer). Additive. | ### `MinMaxAvg` Min / Max / Avg summary row with consistent MDK label and value styling. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `min` | `string \| undefined` | ✓ | - | - | | `max` | `string \| undefined` | ✓ | - | - | | `avg` | `string \| undefined` | ✓ | - | - | | `className` | `string \| undefined` | | - | - | ### `MonthlyEbitdaChart` Bar chart comparing EBITDA across the most recent months for trend visualisation. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `chartData` | `BarChartDataResult` | ✓ | - | - | | `height` | `number \| undefined` | | - | - | ### `OperationalHashrateChart` [**`Hashrate`**](/reference/ui/components/charts/#hashrate) trend card for the operational dashboard. Renders the site hashrate over time (TH/s) with an optional nominal reference line, plus an expand toggle. Purely presentational - pass pre-shaped data from [`useOperationsDashboard`](/reference/ui/hooks/misc/#useoperationsdashboard). `advanced` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `LineChartCardData` | | - | - | | `isLoading` | `boolean` | | - | - | | `isExpanded` | `boolean` | | - | - | | `onToggleExpand` | `VoidFunction` | | - | - | ### `OperationalMinersStatusChart` Miners-status card for the operational dashboard. Renders a stacked daily breakdown of miner states (online / error / offline / sleep / maintenance) with an expand toggle. Purely presentational - pass pre-shaped data from [`useOperationsDashboard`](/reference/ui/hooks/misc/#useoperationsdashboard). `advanced` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `MinersStatusChartData` | | - | - | | `isLoading` | `boolean` | | - | - | | `isExpanded` | `boolean` | | - | - | | `onToggleExpand` | `VoidFunction` | | - | - | ### `OperationalPowerConsumptionChart` Power-consumption trend card for the operational dashboard. Renders site power draw over time (MW) with an optional power-availability reference line, plus an expand toggle. Purely presentational - pass pre-shaped data from [`useOperationsDashboard`](/reference/ui/hooks/misc/#useoperationsdashboard). `advanced` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `LineChartCardData` | | - | - | | `isLoading` | `boolean` | | - | - | | `isExpanded` | `boolean` | | - | - | | `onToggleExpand` | `VoidFunction` | | - | - | ### `OperationalSiteEfficiencyChart` Site-efficiency trend card for the operational dashboard. Renders measured site efficiency over time (W/TH/s) with an optional nominal reference line, an info tooltip, and an expand toggle. Purely presentational - pass pre-shaped data from [`useOperationsDashboard`](/reference/ui/hooks/misc/#useoperationsdashboard). `advanced` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `LineChartCardData` | | - | - | | `isLoading` | `boolean` | | - | - | | `isExpanded` | `boolean` | | - | - | | `onToggleExpand` | `VoidFunction` | | - | - | ### `OperationsEnergyChart` Doughnut breakdown of Operations vs Energy cost (in USD totals). Mirrors the OSS [`OperationsEnergyCostChart`](/reference/ui/components/charts/#operationsenergycostchart). Returns the empty-state placeholder when both totals are zero (the OSS chart hides both slices in that case). `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `totals` | `CostSummaryMonetaryTotals \| null` | ✓ | - | - | | `isLoading` | `boolean \| undefined` | | - | - | ### `OperationsEnergyCostChart` Doughnut breakdown of Operations vs Energy cost (USD per MWh). Wraps [`ChartContainer`](/reference/ui/components/charts/#chartcontainer) and [`DoughnutChart`](/reference/ui/components/charts/#doughnutchart); pass `operationalCostsUSD` and `energyCostsUSD` via `data`. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `title` | `string` | | - | - | | `unit` | `string` | | - | - | | `height` | `number` | | - | - | | `className` | `string` | | - | - | | `isLoading` | `boolean` | | - | - | | `emptyMessage` | `string` | | - | - | | `data` | `Partial<{ energyCostsUSD: number; operationalCostsUSD: number; }>` | | - | - | ### `PowerModeTimelineChart` Timeline chart for power-mode state changes over time. Wraps [`TimelineChart`](/reference/ui/components/charts/#timelinechart) with mining-specific data shaping. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `PowerModeTimelineEntry[]` | | - | Initial power-mode entries (each with start/end ts + mode). | | `dataUpdates` | `PowerModeTimelineEntry[]` | | - | Streaming updates appended to the initial data. | | `isLoading` | `boolean` | | - | Show a loading skeleton instead of the chart. | | `timezone` | `string` | | - | IANA timezone string for x-axis tick formatting. | | `title` | `string` | | - | Chart title. | ### `ProductionCostChart` Production cost over time, overlaid with BTC price. Mirrors the OSS `ProductionCostPriceChart` - both series rendered as bars on the same x-axis (bucket labels derived from `dateRange.period`). `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `costLog` | `readonly CostTimeSeriesEntry[]` | ✓ | - | - | | `btcPriceLog` | `readonly BtcPriceTimeSeriesEntry[]` | ✓ | - | - | | `dateRange` | `FinancialDateRange \| null` | ✓ | - | - | | `isLoading` | `boolean \| undefined` | | - | - | ### `RevenueChart` Stacked bar chart displaying monthly revenue per site. Automatically switches between BTC and Sats display based on value scale. Receives pre-fetched data as props — no internal data fetching. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `data` | `RevenueDataItem[]` | | - | - | | `isLoading` | `boolean` | | - | - | | `siteList` | `(string \| SiteItem)[]` | | - | - | | `legendPosition` | `Position` | | - | - | | `legendAlign` | `"center" \| "start" \| "end"` | | - | - | ### `ThresholdLineChart` Line chart with optional horizontal threshold lines. Wraps [`ChartContainer`](/reference/ui/components/charts/#chartcontainer) and [`LineChart`](/reference/ui/components/charts/#linechart); pass `series` and optional `thresholds` via `data`. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `title` | `string` | | - | - | | `unit` | `string` | | - | - | | `height` | `number` | | - | - | | `isTall` | `boolean` | | - | When true, uses a taller default height (360px). | | `className` | `string` | | - | - | | `emptyMessage` | `string` | | - | - | | `isLegendVisible` | `boolean` | | - | - | | `data` | `ThresholdLineChartData` | | - | - | | `yTicksFormatter` | `(value: number) => string` | | - | - | ### `TimelineChart` Discrete-event timeline chart (e.g. miner state over time) with a category legend. Supports streaming updates via `newData`. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `initialData` | `TimelineChartData` | ✓ | - | - | | `newData` | `TimelineChartData \| undefined` | | - | - | | `skipUpdates` | `boolean \| undefined` | | - | - | | `range` | `ChartRange \| undefined` | | - | - | | `axisTitleText` | `AxisTitleText \| undefined` | | - | - | | `isLoading` | `boolean \| undefined` | | - | - | | `title` | `string \| undefined` | | - | - | | `height` | `number \| undefined` | | - | - | # Dashboard (/reference/ui/components/dashboard) Components for building dashboard layouts and containers. ## Prerequisites - Complete the installation ```bash # Clone the MDK UI monorepo (adjust the URL to your fork if needed) git clone https://github.com/tetherto/mdk.git cd mdk/ui # Install dependencies and build packages (npm workspaces) npm install npm run build ``` - Add the dependency to your app's `package.json` ```json { "dependencies": { "@tetherto/mdk-react-devkit": "*", "@tetherto/mdk-react-adapter": "*", "@tetherto/mdk-ui-foundation": "*" } } ``` > **Coming soon** — npm packages are not yet published. Use the monorepo setup for now. ```bash npm install \ @tetherto/mdk-react-devkit \ @tetherto/mdk-react-adapter \ @tetherto/mdk-ui-foundation ``` Run `npm install` from the `mdk/ui` workspace root after your app is under `apps/` so npm links workspace packages. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `AlarmsBellButton` Top-bar bell button with a three-line severity badge (critical / high / medium). Counts are caller-provided so the button stays domain-agnostic; pair with `useActiveIncidents` or `useSiteMinerCounts` to wire them. `onClick` fires for the bell itself; pass `onSeverityClick` to make each count its own button (severity-filtered deep-link). The two are independent — clicking a severity does not also fire `onClick`. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `counts` | `AlarmsBellButtonCounts \| undefined` | | - | Severity-bucketed alarm counts rendered in the stacked badge. | | `onClick` | `((event: React.MouseEvent) => void) \| undefined` | | - | Click handler — typically opens an alerts panel or routes to /alerts. | | `onSeverityClick` | `((severity: AlarmSeverity, event: React.MouseEvent) => void) \| undefined` | | - | Click handler for an individual severity count. When provided, each badge row becomes its own button so an operator can jump straight to the alerts page filtered by that severity (e.g. `/alerts?severity=critical`). When omitted, the counts render as plain (non-interactive) text. | | `label` | `string \| undefined` | | - | Accessible label. Defaults to "Active alarms". | | `className` | `string \| undefined` | | - | - | ### `DashboardDateRangePicker` Dashboard-friendly wrapper around the core [`DateRangePicker`](/reference/ui/components/forms/#daterangepicker) that speaks `{ start, end }` epoch-millisecond timestamps instead of `Date` objects, so it drops straight into `useDashboardDateRange` from `@tetherto/mdk-react-adapter`. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `value` | `DashboardDateRange` | ✓ | - | Current range as `{ start, end }` epoch-millisecond timestamps. | | `onChange` | `(next: DashboardDateRange) => void` | ✓ | - | Fires with the next `{ start, end }` window when the user applies a range. | | `dateFormat` | `string \| undefined` | | - | Display format. Defaults to `dd/MM/yyyy`. | | `disabled` | `boolean \| undefined` | | - | Disable the trigger. | | `className` | `string \| undefined` | | - | Optional class hook. | ### `ExportButton` Split-button trigger for downloading the current dashboard state. The left half labels the action (`↓ Export`); the right half opens a dropdown with the available formats and invokes `onExport(format)` on selection. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `onExport` | `(format: ExportFormat) => void` | ✓ | - | Fires with the chosen format when the user picks an item. | | `formats` | `readonly ExportFormat[] \| undefined` | | - | Formats to offer in the dropdown — defaults to `['csv', 'json']`. | | `label` | `string \| undefined` | | - | [**`Button`**](/reference/ui/components/actions/#button) label — defaults to `'Export'`. | | `disabled` | `boolean \| undefined` | | - | Disable the button. | | `className` | `string \| undefined` | | - | Optional class hook on the wrapper. | ### `HeaderConsumptionBox` Single-row consumption cell for the dashboard's header strip. The `1.663` style numeric is rendered in orange (the warning token) to match the Mining OS visual treatment. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `icon` | `React.ReactNode` | | - | - | | `valueMw` | `number \| undefined` | | - | Current site-level power consumption, in megawatts. | | `unit` | `string \| undefined` | | - | Unit label — defaults to `MW`. | | `className` | `string \| undefined` | | - | - | ### `HeaderEfficiencyBox` Single-row efficiency cell for the dashboard's header strip. Displays the W/TH/s metric derived from `power_w / hashrate_th`. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `icon` | `React.ReactNode` | | - | - | | `valueWthS` | `number \| undefined` | | - | Efficiency in watts per TH/s. | | `unit` | `string \| undefined` | | - | Unit label — defaults to `W/TH/S`. | | `className` | `string \| undefined` | | - | - | ### `HeaderHashrateBox` Two-row hashrate cell for the dashboard's header strip. Shows the app-side and pool-side aggregate hashrate side by side. Values fall back to `—` when undefined. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `icon` | `React.ReactNode` | | - | - | | `appPhs` | `number \| undefined` | | - | App-side aggregate hashrate in PH/s. | | `poolPhs` | `number \| undefined` | | - | Pool-side aggregate hashrate in PH/s. | | `unit` | `string \| undefined` | | - | [**`Hashrate`**](/reference/ui/components/charts/#hashrate) unit label — defaults to `PH/s`. | | `fractionDigits` | `number \| undefined` | | - | Decimal places shown for both values — defaults to `3`. | | `appLabel` | `string \| undefined` | | - | [**`Label`**](/reference/ui/components/forms/#label) for the app-side row — defaults to `APP` (`WEBAPP_SHORT_NAME`). | | `className` | `string \| undefined` | | - | - | ### `HeaderMinersBox` Two-row miner-count cell for the dashboard's header strip. Top row carries the app-side `online / error / offline` breakdown; the bottom row shows the pool-side equivalent. Numbers fall back to `—` when undefined. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `icon` | `React.ReactNode` | | - | Icon shown next to the "Miners" label. Caller-provided so the package stays icon-agnostic. | | `total` | `number \| undefined` | | - | Total miners across the site (denominator of the `158 / 2,188` ratio). | | `online` | `number \| undefined` | | - | Online miners (the `158` numerator). | | `error` | `number \| undefined` | | - | Miners flagged in warning (the small amber count). | | `offline` | `number \| undefined` | | - | Miners offline (the small red count). | | `appTotal` | `number \| undefined` | | - | Optional app-side meta line — total miners reporting to the app. | | `poolTotal` | `number \| undefined` | | - | Optional pool-side meta — total miners as reported by upstream pools. | | `poolOnline` | `number \| undefined` | | - | Optional pool-side online count (green). | | `poolMismatch` | `number \| undefined` | | - | Optional pool-side mismatch count (red). | | `appLabel` | `string \| undefined` | | - | [**`Label`**](/reference/ui/components/forms/#label) for the app-side row — defaults to `APP` (`WEBAPP_SHORT_NAME`). | | `className` | `string \| undefined` | | - | - | ### `HeaderStatsBar` Horizontal flex strip that hosts the dashboard's stat boxes ([**`HeaderMinersBox`**](/reference/ui/components/dashboard/#headerminersbox), [**`HeaderHashrateBox`**](/reference/ui/components/dashboard/#headerhashratebox), [**`HeaderConsumptionBox`**](/reference/ui/components/dashboard/#headerconsumptionbox), [**`HeaderEfficiencyBox`**](/reference/ui/components/dashboard/#headerefficiencybox)). Lives inside [``](/reference/ui/components/navigation/#appheader) as the middle slot. Slot-based: the caller decides which boxes to render and in which order. The bar interleaves an angled chevron divider between adjacent children to match the Mining OS visual treatment. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `children` | `React.ReactNode` | ✓ | - | Stat boxes to render in order, left-to-right. | | `className` | `string \| undefined` | | - | Optional class hook. | ### `ProfileMenu` Top-bar profile dropdown. Wraps the core DropdownMenu primitive with the user-avatar icon as the trigger. Items are caller-provided so the menu surface stays application-driven. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `items` | `ProfileMenuItem[]` | ✓ | - | Items rendered in the dropdown, top-to-bottom. Defaults to a single "Sign out" item. | | `user` | `React.ReactNode` | | - | Optional user label rendered at the top of the dropdown (e.g. an email). | | `icon` | `React.ReactNode` | | - | Override the trigger icon — defaults to the user-avatar icon. | | `label` | `string \| undefined` | | - | Accessible label for the trigger button. | | `className` | `string \| undefined` | | - | - | ### `SiteStatsBar` Site-level summary strip composed from [`WidgetTopRow`](/reference/ui/components/widgets/#widgettoprow) (title + power) and [`GenericDataBox`](/reference/ui/components/widgets/#genericdatabox) (hashrate / miner-count / container-count). Designed to sit at the top of a dashboard page above the chart cards. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `title` | `string` | ✓ | - | Site label rendered in the header row. | | `power` | `number \| undefined` | | - | Current site-level power consumption, in watts (or whatever `powerUnit` says). | | `powerUnit` | `string \| undefined` | | - | Display unit for `power` — defaults to `kW`. | | `totalHashrate` | `number \| undefined` | | - | Aggregate hashrate, in TH/s. | | `hashrateUnit` | `string \| undefined` | | - | [**`Hashrate`**](/reference/ui/components/charts/#hashrate) display unit — defaults to `TH/s`. | | `minerCount` | `number \| undefined` | | - | Total miner count across the site. | | `containerCount` | `number \| undefined` | | - | Total container count across the site. | | `isLoading` | `boolean \| undefined` | | - | Render a skeleton bar while data is loading. | | `className` | `string \| undefined` | | - | Optional class hook. | ### `TimelineSelector` Dropdown for picking the dashboard time range. Wraps `core/Select` and the canonical option list from `getTimelineOptions`. Pair with the `useDashboardTimeRange` hook in `@tetherto/mdk-react-adapter`. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `value` | `string` | ✓ | - | Currently selected timeline value (e.g. `'1m'`, `'5m'`). | | `onChange` | `(next: string) => void` | ✓ | - | Called whenever the user picks a new option. | | `options` | `TimelineOption[] \| undefined` | | - | Available options — defaults to `getTimelineOptions`. Pass a custom list to localise labels or restrict the range. | | `label` | `string \| undefined` | | - | ARIA label / placeholder for the trigger. | | `className` | `string \| undefined` | | - | Tailwind/BEM class hook on the trigger. | # Dashboard compositions (/reference/ui/components/dashboards) Pre-composed dashboard layouts and templates. ## Prerequisites - Complete the installation ```bash # Clone the MDK UI monorepo (adjust the URL to your fork if needed) git clone https://github.com/tetherto/mdk.git cd mdk/ui # Install dependencies and build packages (npm workspaces) npm install npm run build ``` - Add the dependency to your app's `package.json` ```json { "dependencies": { "@tetherto/mdk-react-devkit": "*", "@tetherto/mdk-react-adapter": "*", "@tetherto/mdk-ui-foundation": "*" } } ``` > **Coming soon** — npm packages are not yet published. Use the monorepo setup for now. ```bash npm install \ @tetherto/mdk-react-devkit \ @tetherto/mdk-react-adapter \ @tetherto/mdk-ui-foundation ``` Run `npm install` from the `mdk/ui` workspace root after your app is under `apps/` so npm links workspace packages. - Import styles: `import '@tetherto/mdk-react-devkit/styles.css'` ## Components @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `ActionsSidebar` Full-height side panel for the MiningOS voting/approval workflow. Three sections (only rendered when non-empty): - **Draft** — locally-staged actions not yet sent to the server. - **In review** — actions this user submitted, awaiting votes. - **Requested** — other users' voting actions this user can approve/reject (only shown when the current token has `actions:w`). Open/close state is driven by `actionsStore.sidebarOpen` so the header [`PendingActionsButton`](/reference/ui/components/dashboards/#pendingactionsbutton) and any in-page code can open it without prop-drilling. Mount this once at the app root — it renders nothing when closed. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `className` | `string \| undefined` | | - | Extra class names merged onto the sidebar root element. | ### `Cost` [**`Cost`**](/reference/ui/components/dashboards/#cost) Summary - composite reporting page (single-site). Reads cost-summary view model fields (from [`useCostSummary`](/reference/ui/hooks/utility/#usecostsummary)) and renders: - page header with "[**`Cost`**](/reference/ui/components/dashboards/#cost) Summary" title and an optional action slot (`setCostAction`) pinned to the opposite edge - period selector slot (`controls`) - pass [``](/reference/ui/components/filters/#timeframecontrols) for the OSS-style Year/Month picker or any other date selector element - shared [`CostContent`](/reference/ui/components/dashboards/#costcontent) 2x2 grid (charts + metric tiles) Multi-site is intentionally out of scope for this extraction wave. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `metrics` | `CostSummaryDisplayMetrics \| null` | ✓ | - | - | | `costLog` | `readonly CostTimeSeriesEntry[]` | ✓ | - | - | | `btcPriceLog` | `readonly BtcPriceTimeSeriesEntry[]` | ✓ | - | - | | `totals` | `CostSummaryMonetaryTotals \| null` | ✓ | - | - | | `isLoading` | `boolean \| undefined` | | - | - | | `error` | `unknown` | | - | - | | `dateRange` | `FinancialDateRange \| null` | ✓ | - | - | | `avgAllInCostData` | `readonly AvgAllInCostDataPoint[] \| undefined` | | - | Optional revenue/cost time-series for the Avg All-in [**`Cost`**](/reference/ui/components/dashboards/#cost) panel. | | `controls` | `React.ReactElement>` | ✓ | - | Period selector element. Pass [``](/reference/ui/components/filters/#timeframecontrols) for the OSS-style year/month picker. | | `setCostAction` | `React.ReactElement> \| undefined` | | - | Optional "Set Monthly [**`Cost`**](/reference/ui/components/dashboards/#cost)" header action slot. A `ReactElement` slot (rather than an href string) so consumers can hand in router-aware components like `` or ` setIsOpen(false)} partTypes={PART_TYPES} defaultPartTypeId={activePartType} modelOptions={modelOptions} minerModelOptions={MINER_MODEL_OPTIONS} statusOptions={STATUS_OPTIONS} locationOptions={LOCATION_OPTIONS} isControllerPartTypeSelected={isController} onPartTypeChange={(id) => setActivePartType(id)} onSubmit={async () => { setIsOpen(false); }} /> ); }; ``` #### Related API - [**`SparePartSubTypesModal`**](/reference/ui/components/dialogs/#sparepartsubtypesmodal) @tetherto/mdk-react-devkit ### Manage spare part subtypes ```tsx ``` Modal for viewing and adding spare part subtypes (part models) per part type. Presents a part-type tab strip, a table of existing subtypes for the active type, and an inline add form. #### When to use Use this to manage the list of allowed part models for each part type. It can be opened standalone or embedded from `AddSparePartModal`'s "View Subtypes" button so users can add a missing model without losing their in-progress form. #### Notes - The active part type is controlled by the parent: change `activePartTypeId` and supply the matching `subTypes` in `onPartTypeChange`. - The add form validates a non-empty name and clears on successful add. #### Example ```tsx const PART_TYPES = [ { value: "inventory-miner_part-controller", label: "Controller" }, { value: "inventory-miner_part-psu", label: "PSU" }, { value: "inventory-miner_part-hashboard", label: "Hashboard" }, ]; const INITIAL_SUB_TYPES: Record = { "inventory-miner_part-controller": ["CT-S19", "CT-S19j"], "inventory-miner_part-psu": ["PSU-3000W"], "inventory-miner_part-hashboard": ["HB-S19", "HB-S19j", "HB-S19XP"], }; const [isOpen, setIsOpen] = useState(false); const [activeId, setActiveId] = useState(PART_TYPES[0]?.value ?? ""); const [subTypesMap, setSubTypesMap] = useState(INITIAL_SUB_TYPES); const handleAddSubType = async (name: string): Promise<{ error: string } | void> => { const existing = subTypesMap[activeId] ?? []; if (existing.includes(name)) return { error: "Subtype already exists" }; setSubTypesMap((prev) => ({ ...prev, [activeId]: [...existing, name] })); }; return (

setIsOpen(false)} partTypes={PART_TYPES} activePartTypeId={activeId} onPartTypeChange={setActiveId} subTypes={subTypesMap[activeId] ?? []} onAddSubType={handleAddSubType} />

); }; ``` #### Related API - [**`AddSparePartModal`**](/reference/ui/components/dialogs/#addsparepartmodal) @tetherto/mdk-react-devkit ### Bulk-add spare parts ```tsx ``` Modal for bulk-adding spare parts from a CSV file. Provides a CSV template download, file selection with client-side parsing, and submits the parsed records. CSV parsing and validation helpers (`parseCsvText`, `validateCSVRecords`, `mapRawRowToRecord`, `downloadCsvTemplate`, `CSVRecord`) are exported alongside the component for use in the consuming submit handler. #### When to use Use this when operators need to register many spare parts at once. Validate the parsed records in your `onSubmit` with `validateCSVRecords` (location/status/model checks, duplicate detection) and return an `{ error }` to surface a message in the modal. #### CSV format Template headers (downloadable from the modal): `part, model, miner model, serial num, mac, status, location, comment`. Max `MAX_CSV_ITEMS` (50) rows per upload. `validateCSVRecords` enforces valid part types, miner models, statuses, locations, per-part-type model subtypes, and duplicate serial/MAC detection (the latter only for controllers). #### Example ```tsx const [isOpen, setIsOpen] = useState(false); return (

setIsOpen(false)} onSubmit={async () => { setIsOpen(false); }} />

); }; ``` @tetherto/mdk-react-devkit ### Move a spare part ```tsx ``` Two-step modal for moving a single spare part. Step one shows the part details (`SparePartDetails`) alongside its current location and status, and lets the user pick a new location, status, and an observation. Step two previews the before → after transition with color-coded badges for confirmation before submitting. #### When to use Use this from a spare-parts inventory row action when an operator moves one part and you want an explicit confirm step showing exactly what will change. For moving many parts at once, use `BatchMoveSparePartsModal` instead. #### Data shape ```ts const sparePart: MoveSparePartModalSparePart = { id: 'sp-001', code: 'CB-AM-CB5_V10-01', // shown via SparePartDetails type: 'CB5_V10', site: 'Site A', serialNum: 'test-miner', macAddress: 'aa:bb:cc:dd:ee:ff', location: 'site.warehouse', // dot-separated location key status: 'ok_repaired', // spare part status key } ``` #### Label & color resolution - Location/status labels are resolved from the passed option lists (`getOptionLabel`). - The current/new badges are colored from `SPARE_PART_LOCATION_BG_COLORS` / `SPARE_PART_STATUS_BG_COLORS`; an unknown location key renders with no background. - The footer shows "No Changes made" until the target location or status differs from the current values, at which point "Save Changes" advances to the confirmation step. #### Example ```tsx Button, MoveSparePartModal, SPARE_PART_LOCATION_LABELS, SPARE_PART_LOCATIONS, SPARE_PART_STATUS_NAMES, SPARE_PART_STATUSES, } from "@tetherto/mdk-react-devkit"; const locationOptions = Object.values(SPARE_PART_LOCATIONS) .filter((value) => value !== SPARE_PART_LOCATIONS.SITE_CONTAINER) .map((value) => ({ value, label: SPARE_PART_LOCATION_LABELS[value] ?? value })); const statusOptions = Object.values(SPARE_PART_STATUSES).map((value) => ({ value, label: SPARE_PART_STATUS_NAMES[value as keyof typeof SPARE_PART_STATUS_NAMES] ?? value, })); const mockSparePart = { id: "sp-001", code: "HB-A001", type: "HB-S19", site: "Site A", serialNum: "SN123456", location: SPARE_PART_LOCATIONS.SITE_WAREHOUSE, status: SPARE_PART_STATUSES.OK_BRAND_NEW, }; const [isOpen, setIsOpen] = useState(false); return (

setIsOpen(false)} sparePart={mockSparePart} locationOptions={locationOptions} statusOptions={statusOptions} onSubmit={async () => { setIsOpen(false); }} />

); }; ``` #### Related API - [**`BatchMoveSparePartsModal`**](/reference/ui/components/dialogs/#batchmovesparepartsmodal) @tetherto/mdk-react-devkit ### Batch-move spare parts ```tsx ``` Modal for moving multiple spare parts at once. Shows the selected parts in a table (code, current location, current status) and lets the user choose a new location and/or status plus an observation, applied to every selected part in one submit. #### When to use Use this when an operator multi-selects spare-part rows and wants to relocate or re-status them together. At least one of location or status must be chosen. For a single part with a confirm step, use `MoveSparePartModal`. #### Data shape ```ts const spareParts: BatchMoveSparePart[] = [ { id: 'sp-001', code: 'HB-A001', location: 'site.warehouse', status: 'ok_brand_new' }, { id: 'sp-002', code: 'HB-A002', location: 'workshop.lab', status: 'faulty' }, ] ``` #### Notes - The form validates that **either** a location or a status is selected before submit. - Table location/status cells are resolved to display labels from the passed option lists. #### Example ```tsx BatchMoveSparePartsModal, Button, SPARE_PART_LOCATION_LABELS, SPARE_PART_LOCATIONS, SPARE_PART_STATUS_NAMES, SPARE_PART_STATUSES, } from "@tetherto/mdk-react-devkit"; const locationOptions = Object.values(SPARE_PART_LOCATIONS) .filter((value) => value !== SPARE_PART_LOCATIONS.SITE_CONTAINER) .map((value) => ({ value, label: SPARE_PART_LOCATION_LABELS[value] ?? value })); const statusOptions = Object.values(SPARE_PART_STATUSES).map((value) => ({ value, label: SPARE_PART_STATUS_NAMES[value as keyof typeof SPARE_PART_STATUS_NAMES] ?? value, })); const mockSpareParts = [ { id: "sp-001", code: "HB-A001", location: SPARE_PART_LOCATIONS.SITE_WAREHOUSE, status: SPARE_PART_STATUSES.OK_BRAND_NEW }, { id: "sp-002", code: "HB-A002", location: SPARE_PART_LOCATIONS.WORKSHOP_LAB, status: SPARE_PART_STATUSES.FAULTY }, { id: "sp-003", code: "CB-B001", location: SPARE_PART_LOCATIONS.SITE_WAREHOUSE, status: SPARE_PART_STATUSES.OK_RECOVERED }, ]; const [isOpen, setIsOpen] = useState(false); return (

setIsOpen(false)} spareParts={mockSpareParts} locationOptions={locationOptions} statusOptions={statusOptions} onSubmit={async () => { setIsOpen(false); }} />

); }; ``` #### Related API - [**`MoveSparePartModal`**](/reference/ui/components/dialogs/#movesparepartmodal) @tetherto/mdk-react-devkit ### View a device movement ```tsx ``` Modal that shows the details of a single historical device movement: a device summary (code, model, site, container, serial number, MAC) and the origin → destination transition of both location and status, with color-coded badges. #### When to use Use this in an inventory "Historical Movements" view when a user selects a movement row and you want to show the full before/after detail of where a device moved and how its status changed. #### Data shape ```ts const movement: MovementData = { origin: 'site.warehouse', // dot-separated location key destination: 'workshop.lab', previousStatus: 'ok_brand_new', // miner status key newStatus: 'faulty', device: { // raw device record (miner / spare part) code: 'M-123', tags: ['code-M-123'], type: 'antminer', info: { site: 'Site A', container: 'C1', serialNum: 'SN-9', macAddress: 'AA:BB' }, }, comments: 'Moved for repair', // optional ReactNode } ``` #### Label & color resolution The component renders data only — all resolution happens in `buildMovementDetailsViewModel`: - Location labels come from `getLocationLabel` (`'site.warehouse'` → `Site Warehouse`). - Location/status badge colors come from `MINER_LOCATION_*` / `MINER_STATUS_*` constants, falling back to a neutral border when a key is unknown. - Status labels come from `MINER_STATUS_NAMES` (`'ok_brand_new'` → `Brand New`). - The device `code` is resolved with `getMinerShortCode`, and `model` falls back from `info.subType` → `type` → `-`. #### Example ```tsx /** * Runnable example for MovementDetailsModal. */ const exampleMovement: MovementData = { origin: 'site.warehouse', destination: 'workshop.lab', previousStatus: 'ok_brand_new', newStatus: 'faulty', device: { code: 'M-1042', tags: ['code-M-1042'], type: 'antminer', info: { site: 'Site A', container: 'C-12', serialNum: 'SN-9981', macAddress: 'AA:BB:CC:DD:EE:FF', }, }, comments: 'Moved to workshop lab for diagnostics.', }

{ console.warn('modal closed') }} />

) ``` @tetherto/mdk-react-devkit ### Delete a spare part ```tsx ``` Confirmation modal for deleting a spare part. Warns that the action is irreversible and surfaces the part code so the user can verify before confirming. #### When to use Use this as the confirm step for a destructive "Delete" row action in a spare-parts inventory view. #### Example ```tsx const [isOpen, setIsOpen] = useState(false); return (

setIsOpen(false)} onConfirm={async () => setIsOpen(false)} sparePart={{ id: "sp-001", code: "HB-A001" }} />

); }; ``` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `AddSparePartModal` Modal for registering a new spare part. Presents a part-type tab strip and a form for miner model, part model, serial number, MAC address (controllers only), status, location, tags, and a comment. Validation is controller-aware: controllers require a MAC address, other parts require a serial number. Receives option lists and the submit handler as props. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isOpen` | `boolean` | ✓ | - | - | | `onClose` | `VoidFunction` | ✓ | - | - | | `partTypes` | `SparePartSubTypesModalPartType[]` | ✓ | - | - | | `defaultPartTypeId` | `string \| undefined` | | - | - | | `modelOptions` | `FormSelectOption[]` | ✓ | - | - | | `isModelOptionsLoading` | `boolean \| undefined` | | - | - | | `minerModelOptions` | `FormSelectOption[]` | ✓ | - | - | | `statusOptions` | `FormSelectOption[]` | ✓ | - | - | | `locationOptions` | `FormSelectOption[]` | ✓ | - | - | | `isControllerPartTypeSelected` | `boolean \| undefined` | | - | - | | `onPartTypeChange` | `(partTypeId: string) => void` | ✓ | - | - | | `onSubmit` | `(values: AddSparePartFormValues) => Promise` | ✓ | - | - | | `isLoading` | `boolean \| undefined` | | - | - | | `subTypesPartTypes` | `SparePartSubTypesModalPartType[] \| undefined` | | - | - | | `subTypesActivePartTypeId` | `string \| undefined` | | - | - | | `subTypes` | `string[] \| undefined` | | - | - | | `onSubTypesPartTypeChange` | `((id: string) => void) \| undefined` | | - | - | | `onAddSubType` | `((name: string) => Promise) \| undefined` | | - | - | | `isSubTypesLoading` | `boolean \| undefined` | | - | - | ### `AlertDialogAction` Primary confirmation button inside an ``; clicking dismisses the dialog and runs the action handler. `agent-ready` ### `AlertDialogCancel` Secondary dismiss button inside an ``; closes the dialog without invoking the destructive action. `agent-ready` ### `AlertDialogContent` Modal content surface for an `` — renders the centered panel above the overlay with focus trap. `agent-ready` ### `AlertDialogDescription` Supporting body text inside an ``; conveys the consequences of the action being confirmed. `agent-ready` ### `AlertDialogFooter` Right-aligned action row inside an `` — hosts the cancel and confirm buttons. `agent-ready` ### `AlertDialogHeader` Top section of an `` that groups the title and description above the action row. `agent-ready` ### `AlertDialogOverlay` Full-viewport scrim rendered behind an `` to block interaction with the page. `agent-ready` ### `AlertDialogTitle` Prominent title text inside an `` summarising the action that requires confirmation. `agent-ready` ### `AssignPoolModal` Modal dialog for bulk-assigning a set of selected miners to a pool config. Displays the miner list, a pool selector with metadata (unit/miner counts, last-updated time), an endpoints preview, and an optional credential template preview. Submission is async; the modal stays open with a loading state until the parent resolves. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isOpen` | `boolean` | ✓ | - | - | | `onClose` | `() => void` | ✓ | - | - | | `onSubmit` | `(values: { pool: PoolSummary; }) => Promise` | ✓ | - | - | | `miners` | `Device[]` | ✓ | - | - | | `poolConfig` | `PoolConfigEntry[]` | ✓ | - | - | ### `BatchMoveSparePartsModal` Modal for moving multiple spare parts at once. Shows the selected parts in a table and lets the user choose a new location and/or status plus an observation, applied to every part. Receives the parts, option lists, and submit handler as props. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isOpen` | `boolean` | ✓ | - | - | | `onClose` | `VoidFunction` | ✓ | - | - | | `spareParts` | `BatchMoveSparePart[]` | ✓ | - | - | | `locationOptions` | `FormSelectOption[]` | ✓ | - | - | | `statusOptions` | `FormSelectOption[]` | ✓ | - | - | | `onSubmit` | `(values: { location: string \| null; status: string \| null; observation: string \| null; }) => void \| Promise` | ✓ | - | - | ### `BulkAddSparePartsModal` Modal for bulk-adding spare parts from a CSV file. Provides a CSV template download, file selection with client-side parsing, and submits the parsed records. Receives the submit handler as a prop; CSV parsing and validation helpers are exported alongside the component. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isOpen` | `boolean` | ✓ | - | - | | `onClose` | `VoidFunction` | ✓ | - | - | | `onSubmit` | `(records: CSVRecord[]) => Promise` | ✓ | - | - | | `isLoading` | `boolean \| undefined` | | - | - | ### `ConfirmDeleteSparePartModal` Confirmation modal for deleting a spare part. Warns that the action is irreversible and surfaces the part code so the user can verify before confirming. Receives the part and confirm handler as props. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `isOpen` | `boolean \| undefined` | | - | - | | `onClose` | `VoidFunction \| undefined` | | - | - | | `onConfirm` | `((sparePart: ConfirmDeleteSparePartModalSparePart) => void \| Promise) \| undefined` | | - | - | | `sparePart` | `ConfirmDeleteSparePartModalSparePart \| undefined` | | - | - | | `isLoading` | `boolean \| undefined` | | - | - | ### `DialogContent` Centered modal surface for a `

Stats Lab

Final exam distribution

Weekly class average