` | `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:

.: : ` | Verify the displayed resolved path is relative to `plugin.dir`. Preserve and inspect the nested module error: the file may exist while one of its own imports is missing or incompatible | | `ERR_PLUGIN_HANDLER_NOT_FUNCTION:

.: ` | The CommonJS module must assign a function to `module.exports` | | `ERR_PLUGIN_DUPLICATE_NAME:

.` | Rename or remove the duplicate entry in that section | These fire only once a host process constructs `WorkerRuntime` with your plugin — for errors from that point on (runtime construction, Kernel registration, live requests), 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) Understand the end-user experience of controlling and monitoring your device via the Worker: - Build a [minimal dashboard](/tutorials/quickstart/build-a-dashboard) around one Worker - Run the [full-site example](https://github.com/tetherto/mdk/blob/main/examples/full-site/README.md) with the supported Worker fleet - Connect an [AI agent via the MCP server](https://github.com/tetherto/mdk/blob/main/examples/full-site/docs/mcp-server.md) to query and command your Workers # 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 plugin on `WorkerRuntime` in a Node.js host process. 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: WorkerRuntime, 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 `WorkerRuntime`) 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 { WorkerRuntime } = require("@tetherto/mdk/backend/core/mdk-worker"); const plugin = require("../your-worker-repo/plugin"); async function startVendorWorker({ workerId, kernelTopic, seedDevices }) { const runtime = new WorkerRuntime(plugin, { 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 }; ``` Required `WorkerRuntime` options are `workerId` and a non-empty `devices` array. Each `config` object is passed to the plugin's `connect()`. `kernelTopic` is needed only for DHT discovery. Without a `store`, `WorkerRuntime` 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. `WorkerRuntime` 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 the same frozen `ctx` a handler receives (`{ deviceId, device, config, services }`) for a device that is currently `online`, or `null` otherwise — useful for wiring an external service (for example, a snapshot collector) to a live device outside the request/response cycle. ### Register directly with a live Kernel When Kernel and the Worker host share a process, register the runtime's public key directly. This complete `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 | 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 | | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | Device remains offline after `runtime.start()` | `connect()` failed. Check the device timeout, credentials, address, protocol, and redacted host logs. The current runtime does not reconnect; restore reachability and restart the Worker host | | `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` | ### Request time | Error | Diagnostic and remediation | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ERR_DEVICE_UNAVAILABLE: ` | The device was held offline because `connect()` failed; follow the documented restart/recovery path | | `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 | ## 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/quickstart/build-a-dashboard) around one Worker - Run the [full-site example](https://github.com/tetherto/mdk/blob/main/examples/full-site/README.md) with the supported Worker fleet - Connect an [AI agent via the MCP server](https://github.com/tetherto/mdk/blob/main/examples/full-site/docs/mcp-server.md) to query and command your Workers # Quickstart (/quickstart) } title={Connect hardware} href="/quickstart/connect-hardware" description={ <> Drive a running MDK stack with a mock miner — live telemetry and commands over IPC ⏱️ ~3 min } /> } title={Build dashboards with your AI agent} href="/quickstart/connect-agents" description={ <> Use the CLI to wire Cursor or Claude to MDK with two commands, then build from plain-language prompts ⏱️ ~2 min } /> } title={Build dashboards with React} href="/quickstart/wire-react" description={ <> Install the three MDK React packages and wire MdkProvider ⏱️ ~3 min } /> } title={Explore the demo app} href="/tutorials/ui/explore-the-demo" description={ <> See the UI components rendered in a single demo app ⏱️ ~3 min } /> # Build dashboards with AI (/quickstart/connect-agents) MDK is built so your AI coding agent can build mining dashboards straight from plain-language prompts, without you wiring components by hand. There are two steps: wire your IDE once, then describe what you want. ## Wire your IDE once ### Run init Point the UI CLI at your IDE from your project root: ```bash npx @tetherto/mdk-ui-cli init --ide cursor ``` Use `--ide claude` for Claude. This writes a `.mdk/context.md` agent-context file and an IDE rule (`.cursor/rules/mdk.mdc` for Cursor, `CLAUDE.md` for Claude) so every AI session knows about MDK automatically. ### Prompt your agent Describe the dashboard you want in plain language: > Build me an operations dashboard with live hashrate and a device list. Your agent takes it from there: it finds the right components and hooks, scaffolds the page, and checks that it compiles. You review and run it. ## Next steps

Build any dashboard with an agent Stats Lab walkthrough with UI CLI commands — no fleet backend Runtime agents via MCP Server Monitor and control a live fleet at runtime through the MCP server

- [How agents build with MDK](/concepts/agents): why the results are trustworthy — the local manifests and stable-export contract behind the flow - [UI CLI reference](/guides/ui/ui-cli): every command your agent (or you) can run - [UI Devkit](/reference/ui): browse the component library your agent draws from # Connect hardware (/quickstart/connect-hardware) ## Overview This quickstart walks the shortest path from a fresh clone to a fully wired MDK stack you can drive interactively from a CLI. Everything runs in one Node process, no real hardware required. What you'll have at the end: - A mock Whatsminer M56S serving telemetry on `127.0.0.1:14028` - A Kernel with one Worker registered and one device discovered - An interactive `client.js` REPL talking to Kernel over its IPC socket — pull metrics, list Workers, send commands like `reboot` and `setpower` - (Optional) A Gateway HTTP API on `:3000` so non-Node consumers (browsers, AI agents over MCP) can hit the same stack over REST The example lives in [`examples/backend/mdk-e2e/`](https://github.com/tetherto/mdk/blob/main/examples/backend/README.md#end-to-end-mdk-e2e) and contains six runnable scripts. This tutorial uses three of them: `run.js` for a smoke test, `server.js` for the long-running stack, and `client.js` for interactive control. ## Prerequisites - Node.js >=24 (LTS) - npm >=11 The stack starts a Kernel whose control plane is peer-to-peer over a Hyperswarm DHT, so it needs outbound network access. Without it, the stack stalls at startup while the Kernel tries to reach DHT bootstrap nodes. See [how Workers connect](/concepts/stack/workers) for the Kernel/DHT mechanics. ### Clone and install #### 1.1 Clone the repo ```bash git clone git@github.com:tetherto/mdk.git cd mdk ``` #### 1.2 Install dependencies The monorepo has two workspaces with their own dependency trees. Install both: ```bash backend/core/install-packages.sh ci backend/workers/install-packages.sh ci ``` Each script walks every `package.json` under its workspace and runs `npm ci`. The `examples/mdk-e2e/` package is included automatically — no extra install step needed.

(1.3 Optional) Smoke test the stack

Before going interactive, prove the wiring works. `run.js` starts a mock Whatsminer + Worker + Kernel in one process, exercises a few queries, prints the results, and exits cleanly: ```bash node examples/backend/mdk-e2e/run.js ``` Expected output (the UUID and metric values vary): ```text Devices: [ '8f3e9a2b-7c1d-4e5a-9f8b-6c2d1e3f4a5b [miner-wm-m56s]' ] Telemetry: ONLINE hashrate=170000 power=3500W Commands: reboot, setPowerMode, setLED, setPowerPct, setupPools, saveComment ``` If you see those three lines, every layer is working: the mock is responding, the Worker registered the device, Kernel discovered the Worker over the local DHT topic, and IPC routing is delivering envelopes both ways. The script tears itself down and exits with code 0. If the smoke test fails with `EADDRINUSE` on port 14028, a previous run left a Node process alive. Kill stragglers with `pkill -f mdk-e2e` and retry.

### Run the interactive demo #### 3.1 Start the stack In your terminal: ```bash node examples/backend/mdk-e2e/server.js ``` `server.js` starts the same mock + Worker + Kernel as `run.js`, but stays running and prints the IDs you'll need: ```text Kernel key: 7a4c8b...e3f0 Device: 8f3e9a2b-7c1d-4e5a-9f8b-6c2d1e3f4a5b hp-rpc-cli -s 7a4c8b...e3f0 -m mdk -d '{...}' hp-rpc-cli -s 7a4c8b...e3f0 -m mdk -d '{...}' Ctrl+C to stop. ``` The `Kernel key` is a 64-char hex public key. `Device` is a UUIDv4 generated at registration time. Both vary per run — note the device UUID for the next step. The two `hp-rpc-cli` lines are paste-ready commands for inspecting Kernel over HRPC from another machine. You don't need them for this tutorial — they're there if you have [`hp-rpc-cli`](https://github.com/holepunchto/hp-rpc-cli) installed and want to go off-script. #### 3.2 Connect the interactive client Open a second terminal in the same `mdk` directory: ```bash node examples/backend/mdk-e2e/client.js ``` `client.js` connects to Kernel's default IPC socket and gives you an MDK REPL: ```text MDK Client — connected to IPC: /tmp/mdk/ork.sock Type "help" for commands, "quit" to exit. mdk> ``` #### 3.3 Drive the stack 3.3.1 Discover the telemetry of your (mock) device by entering commands at the `mdk>` prompt, substituting `` with the UUID printed in Step 3.1: ```text mdk> metrics ``` Each command builds an MDK Protocol envelope, writes it to Kernel's IPC socket, and prints the JSON response. 3.3.2 Try changing the power mode and observing the effect: ```text mdk> setpower low mdk> metrics ``` After `setpower ... low` the second `metrics` call should reflect the power mode change.

Full command reference

##### Reads ```text workers — list workers list [deviceId] — list devices count [deviceId] — device count metrics — live telemetry from hardware logs — recent logs settings [deviceId] — worker settings stats [deviceId] — fleet stats config — device config (pools, etc.) capabilities — mdk-contract capabilities state [deviceId] — worker state snapshot ``` ##### Commands ```text reboot — reboot miner setpower — set power mode (normal/low/high) setled [on|off] — toggle LED ``` ```text quit / exit — exit client ```

#### 3.4 Tear down When you're done, exit the client and stop the stack: ```text mdk> quit ``` Then `Ctrl+C` in Terminal 1. ### 4 (Optional) enable Gateway for HTTP access In **Terminal 1**, `Ctrl+C` the running stack, then restart with `--app-node`: ```bash node examples/backend/mdk-e2e/server.js --app-node ``` You'll see an extra line in the startup banner: ```text App-node: http://localhost:3000 (noAuth mode) ``` Confirm it's alive — Gateway has no index page, so hit `/auth/site` directly: ```bash curl http://localhost:3000/auth/site ``` You should see something like `{"site":"Site_Name"}`. In `noAuth` mode most data endpoints (e.g. `/auth/list-things`, `/auth/miners`) are unavailable — they require the cache and auth config that the full Gateway service sets up. `--app-node` in `server.js` is a development shortcut; for full REST access to device telemetry, run Gateway as a full service. See [`backend/core/app-node/`](https://github.com/tetherto/mdk/blob/main/backend/core/app-node/README.md) for setup. `--app-node` runs in `noAuth` mode for development convenience. Do not expose port 3000 outside localhost. ## What just happened Your stack wired up, in order: 1. **Mock device**:`server.js` calls `wmMock.createServer({ port: 14028, ... })` — an HTTP server speaking the Whatsminer protocol with canned telemetry. 2. **Kernel**: `getOrk()` boots the kernel, generates a random DHT topic, and opens an IPC socket at the default path (`os.tmpdir()/mdk/ork.sock`). 3. **Worker**: `startWorker(WM_M56S, { ork })` instantiates the Whatsminer manager, mounts its protocol adapter, and registers with Kernel directly — no DHT round-trip because they share the process. 4. **Thing registration**: `manager.registerThing({ info, opts })` tells the Worker about the device at `127.0.0.1:14028`. The Worker stores the registration and starts polling. 5. **Client**: `client.js` opens the IPC socket from a second process and sends MDK Protocol envelopes (`worker.list`, `telemetry.pull`, `command.request`, ...). Kernel routes them to the Worker, the Worker hits the mock, and the response flows back over IPC. No Gateway here? Right. Gateway is the translator that lets non-Node consumers — browser UIs, AI agents over MCP — speak MDK Protocol to Kernel. `client.js` already speaks MDK Protocol over IPC, so it talks to Kernel directly. Gateway becomes mandatory only when the consumer can't open a UNIX socket. See [`architecture.md#gateway`](/concepts/architecture#gateway). ## Cleanup `Ctrl+C` in Terminal 1 stops the Worker, Kernel, and mock cleanly. `run.js` deletes its own state directory on exit. `server.js` leaves data under `os.tmpdir()/mdk/` — safe to ignore, or remove with: ```bash rm -rf "$TMPDIR/mdk" /tmp/mdk ``` ## Next steps - Go deeper and [run the dashboard demo](/tutorials/full-stack/dashboard): put a browser dashboard on a running stack with live charts. - Or go simpler and walk the simpler [single-script Antminer path](/tutorials/backend-stack/run) - Run a [full site (multiple Workers and devices):](https://github.com/tetherto/mdk/blob/main/examples/backend/mdk-site/site.js) - Understand the [install pattern for any Worker](https://github.com/tetherto/mdk/blob/main/backend/workers/install-pattern.md) - Read all [runnable examples in one place](https://github.com/tetherto/mdk/blob/main/examples/backend/README.md) # Wire React (/quickstart/wire-react) This page walks through the minimum integration of the MDK UI toolkit into a React application. ## Prerequisites - **Node.js** >=24 - **npm** >=11 - **React** 19+ and **react-dom** 19+ ## Install ```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 ``` Then add to your app's `package.json`: ```json { "dependencies": { "@tetherto/mdk-react-devkit": "*", "@tetherto/mdk-react-adapter": "*", "@tetherto/mdk-ui-foundation": "*" } } ``` [Wrap your app](/quickstart/wire-react) in `` from `@tetherto/mdk-react-adapter` when using connected foundation components or adapter store hooks. > **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. ## Wrap your app in MdkProvider `MdkProvider` sets up the TanStack `QueryClient` and the API base URL context. It is required for foundation hooks and components that read shared app state. ```tsx // main.tsx ReactDOM.createRoot(rootElement).render( , ) ``` ## Use the adapter hooks inside React Each hook subscribes the component to the relevant Zustand store and re-renders only when the selected slice changes. ```tsx const Toolbar = () => { const { permissions } = useAuth() const { selectedDevices } = useDevices() const { setAddPendingSubmissionAction } = useActions() // ... } ``` ## Or read / write stores directly outside React The vanilla stores expose `getState()` / `setState()` so utility code, side-effect handlers, and tests can interact with the same source of truth. ```tsx // Outside React (utilities, sagas, etc.) you can read/write directly: devicesStore.getState().setSelectedDevices([]) actionsStore.getState().setAddPendingSubmissionAction({ /* … */ }) ``` ## Theme via design tokens and @layer mdk The compiled stylesheet declares `@layer base`, `mdk`, `app` — so unlayered or `@layer app` styles in your application always win against devkit component styles. MDK ships with `--mdk-color-primary: #f7931a`; override tokens in `:root` only when reskinning. ```css /* app.css — imported AFTER @tetherto/mdk-react-devkit/styles.css */ :root { --mdk-color-primary: #f7931a; --mdk-radius: 6px; } @layer app { .mdk-button--variant-primary { letter-spacing: 0.04em; } } ``` See [Theme](/reference/ui) for design tokens and `@layer` override rules. ## Next steps - [Tutorial](/tutorials/ui/react/tutorial) — full integration walkthrough - [Hooks](/reference/ui/hooks) — state, component, and utility hooks - [Explore the demo](/tutorials/ui/explore-the-demo) — run the demo browser without adding MDK to your own app yet - [Core](/reference/ui/components) — building block reference (`@tetherto/mdk-react-devkit/core`) - [Foundation](/reference/ui/components) — mining-domain components (`@tetherto/mdk-react-devkit/foundation`) # 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. For narrative explanations, see [Architecture](/concepts/architecture); for step-by-step instructions, see [Get started](/quickstart). ## Browse by stack area ### App Toolkit - **[UI Devkit](/reference/app-toolkit/ui-devkit)**: constants, hooks, types, and utilities for the React UI Devkit - **[UI Foundation](/reference/app-toolkit/ui-foundation)**: framework-agnostic headless Zustand stores and TanStack Query factory - **[Hooks](/reference/ui/hooks)**: complete hook catalog: data, state, component, and utility hooks across the adapter and devkit packages ### 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 # 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` | ### 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 the stack](/tutorials/backend-stack/run) - Learn more about: - Multi-process discovery across machines: [Worker discovery](/concepts/stack/workers) - Gateway implementation details (HTTP routing, JWT auth, RBAC) — see [`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/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) `@tetherto/mdk-kernel`'s coordination splits across single-purpose modules. Each owns its own state machine, persistence boundary, and scaling characteristics. Six modules ship in v0.0.1; two more (Fault Supervisor, Concurrency Manager) are deferred to a later release. For the architectural overview that explains how these modules connect, see [Kernel](/concepts/stack/kernel). This page is the per-module spec. ## How to read this page Each accordion below covers one module: - **Responsibility**: what the module owns and the example commands or events it handles. - **Interfaces**: input and output channels, plus the public function names callers depend on. - **State machine**: the canonical diagram for the module's internal lifecycle. - **Crash recovery**: behavior on a fresh start, including how state is reconstructed. - **Scalability**: where the module can be extracted, sharded, or replicated. ## Modules **Responsibility**: validates incoming commands against the generic MDK schema, checks permissions, and resolves the correct Worker based on the `deviceId`. *Example*: when a Gateway sends a `reboot` command for `wm001`, the Dispatcher verifies that `wm001` exists, that `reboot` is a valid capability for it, then passes the request to the State Machine. **Interfaces**: - *Input*: receives generic commands via Holepunch RPC (HRPC) and the MDK Protocol from the Gateway or MCP Handler. - *Output*: hands off validated commands to the Command State Machine. - *Functions*: `dispatchCommand(deviceId, action, payload)` **State machine**: ```mermaid stateDiagram-v2 [*] --> Validating Validating --> RoutingAction : Valid Validating --> Rejected : Invalid RoutingAction --> Enqueued Enqueued --> [*] ``` **Crash recovery**: none needed. In-flight requests fail and must be retried by the client. **Scalability**: extracted easily; can run independently to offload validation. **Responsibility**: tracks the execution lifecycle of every single command in the system. Receives execution results directly via the synchronous HRPC response. If the connection drops or a response is delayed, it relies on the Scheduler to fetch the latest status via `state.pull` so commands cannot hang. *Example*: once the `reboot` command is dispatched it transitions to `EXECUTING`. If the HRPC response returns OK it transitions to `SUCCESS`. If the response hangs, the next `state.pull` fetches the true status from the Worker. **Interfaces**: - *Input*: receives validated commands from the Dispatcher; status updates from HRPC responses or Scheduler ticks. - *Output*: invokes the Worker HRPC execution layer; emits terminal state results to the caller. - *Functions*: `enqueue(command)`, `syncState(commandId)`, `cancel(commandId)` **State machine**: ```mermaid stateDiagram-v2 [*] --> QUEUED QUEUED --> DISPATCHED DISPATCHED --> EXECUTING : HRPC sent EXECUTING --> SUCCESS : state.pull (response) EXECUTING --> FAILED : state.pull (error) EXECUTING --> TIMEOUT TIMEOUT --> QUEUED : Retry allowed TIMEOUT --> FAILED : Max retries SUCCESS --> [*] FAILED --> [*] ``` **Crash recovery**: on startup, performs a recovery sweep of pending commands. `DISPATCHED` and `EXECUTING` commands are forced to `TIMEOUT` (and re-queued if retries are available); `QUEUED` commands are left untouched. **Scalability**: requires state sharding (for example, by device or rack). **Responsibility**: the phonebook for the entire `@tetherto/mdk-kernel` ecosystem. Maps which physical device IDs belong to which connected Worker channels and stores their declared capabilities. *Example*: a `whatsminer-worker` connects and declares it manages `wm001` and `wm002`. The Registry saves this topology so the Dispatcher knows exactly where to route a command for `wm001`. **Interfaces**: - *Input*: `identity.register` requests from Workers. - *Output*: internal events triggering full state lifecycle binding. - *Functions*: `resolveWorkerState(target)` **State machine**: ```mermaid stateDiagram-v2 [*] --> Unregistered Unregistered --> Discovered : DHT peer detected Discovered --> IdentitySaved : identity pulled IdentitySaved --> Ready : capabilities pulled Ready --> Terminated : eviction Terminated --> [*] ``` **Crash recovery**: rebuilt from state, which serves as a baseline to detect Workers that were registered but failed to reconnect. **Scalability**: read-heavy by nature; can be extracted into a read-replica architecture or partitioned by region or rack. **Responsibility**: a lightweight proxy and routing layer between the upper system (UI / AI) and the downstream Workers. Rather than `@tetherto/mdk-kernel` performing heavy time-series aggregations, the *Worker* is responsible for storing and aggregating data for the specific devices it controls. The Collector simply provides an interface to query this data and proxies the response up to the UI (via Gateway) or the AI Agent. **Worker data handling (telemetry context)**: - *Compaction*: the Worker handles compaction of metrics over large time frames. - *Local storage*: Workers should save telemetry data in a local Hyper DB. - *As-requested serving*: the Worker serves data strictly when `@tetherto/mdk-kernel` asks for it, precisely as dictated by the telemetry schemas in `mdk-contract.json`. - *Internal scheduling*: to achieve this without blocking `@tetherto/mdk-kernel`, the Worker may run its own internal scheduler for device polling. **Interfaces**: - *Input*: client or AI telemetry queries (for example, "fetch metrics for device wm001"). - *Output*: normalized telemetry payloads passed straight through from the Worker to the requesting layer. - *Functions*: `proxyTelemetryFetch(deviceId, queryArgs)` **State machine**: ```mermaid stateDiagram-v2 [*] --> Idle Idle --> Proxying : Request received Proxying --> RoutingToClient : Worker returns data Proxying --> Timeout : Worker unresponsive RoutingToClient --> Idle ``` **Scalability**: because the heavy lifting of data storage and aggregation is pushed down into the isolated Worker processes, the Collector remains stateless and highly scalable as a pure asynchronous router. **Responsibility**: the system metronome. Triggers repetitive tasks without holding any domain-specific logic itself. *Example*: emits an internal `tick` event every 5 seconds that the Health Monitor listens to, prompting it to ping all Workers. **Interfaces**: - *Input*: system clock and configured task intervals. - *Output*: injects intents (for example, `telemetry.pull`, `health.ping`) into the Dispatcher or Collector. - *Functions*: `addJob(interval, intent)`, `removeJob(jobId)` **State machine**: ```mermaid stateDiagram-v2 [*] --> Waiting Waiting --> Triggered : Interval elapsed Triggered --> Waiting ``` **Crash recovery**: timers re-initialize from zero on startup. Tasks are strictly idempotent. **Scalability**: scales trivially. Requires basic distributed locking to avoid duplicate ticks in multi-process `@tetherto/mdk-kernel` deployments. **Responsibility**: continuously evaluates the liveness and readiness of every registered Worker to prevent routing messages to dead nodes. *Example*: if `health.ping` to a Worker fails three times in a row, the Health Monitor marks the Worker's status as `SICK` and tells the Registry to halt routing new commands there. **Interfaces**: - *Input*: executes `health.ping` sequentially based on Scheduler ticks. - *Output*: pushes status updates to the Registry. - *Functions*: `pingWorker(workerId)`, `getHealth(workerId)` **State machine**: ```mermaid stateDiagram-v2 [*] --> UNKNOWN UNKNOWN --> HEALTHY : Ping success HEALTHY --> SICK : Ping failed (1) SICK --> DEAD : Ping failed (threshold) SICK --> HEALTHY : Ping success DEAD --> HEALTHY : Reconnected ``` **Crash recovery**: blank slate on startup; re-evaluates all known Workers immediately via ping. **Scalability**: operates locally per `@tetherto/mdk-kernel` kernel, or via independent lightweight ping agents. **Idea**: implements circuit-breaker patterns to protect the overall system from cascading failures caused by bad hardware or software bugs (for example, rejecting commands during a cooling period after repeated errors). **Status**: deferred for the first cut to keep the core orchestrator simple. If the use case arises (such as complex retry backoffs or cluster destabilization), it will be reintroduced. **Idea**: provides guaranteed lock management and queue limits to ensure mutually exclusive commands do not overlap on physical devices. **Status**: deferred for the first cut. The system relies solely on the basic command queue. If explicit global locks or backpressure limits become necessary, this module will be built out. # 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) Every MDK Protocol message uses the same envelope regardless of which layers are talking. This page is the canonical spec for that envelope, the full set of protocol actions, and the base command set every Worker must support. For the architectural narrative explaining when each action fires, see [Architecture](/concepts/architecture#the-mdk-protocol). ## Envelope ```json { "id": "uuid-v4", "version": "0.1.0", "type": "request | response | event", "action": "", "sender": "", "target": " | null", "deviceId": "string | null", "timestamp": 1711640000000, "payload": {} } ``` External consumers (UI or AI agents) only provide `deviceId`; the `target` Worker identity is internally resolved by `@tetherto/mdk-kernel`. A concrete request and response pair, end to end: ```json // request: Gateway asks @tetherto/mdk-kernel to reboot device wm001 { "id": "8d1c-e3a4", "version": "0.1.0", "type": "request", "action": "command.request", "sender": "appNode:fleet-api:1", "target": null, "deviceId": "wm001", "timestamp": 1711640000000, "payload": { "command": "reboot" } } // response: @tetherto/mdk-kernel relays the worker's terminal result { "id": "1f9b-77c2", "version": "0.1.0", "type": "response", "action": "command.result", "sender": "ork:kernel:tx-1", "target": "appNode:fleet-api:1", "deviceId": "wm001", "timestamp": 1711640002145, "payload": { "status": "SUCCESS", "elapsedMs": 2145 } } ``` ## Actions | Action | Type | Direction | Purpose | |---|---|---|---| | *(DHT presence)* | passive | Worker to DHT topic | Worker joins a known Hyperswarm topic; `@tetherto/mdk-kernel` detects its peer connection automatically | | `identity.request` | request | `@tetherto/mdk-kernel` to Worker | Requests the Worker's identity and managed devices | | `capability.request` | request | `@tetherto/mdk-kernel` to Worker | Asks the Worker to declare its full capability schema | | `state.pull` | request | `@tetherto/mdk-kernel` to Worker | Worker returns a snapshot of state-machine status (low cadence tick, e.g., 60s) | | `telemetry.pull` | request | `@tetherto/mdk-kernel` to Worker | Worker returns device metrics plus history (medium cadence tick, e.g., 10s) | | `command.request` | request | `@tetherto/mdk-kernel` to Worker | Resolves the Worker by `deviceId` and dispatches the command for execution | | `health.ping` | request | `@tetherto/mdk-kernel` to Worker | Liveness probe (high cadence tick, e.g., 5s) | ## Base command set The protocol standardizes a Base Command Set supported by every Worker: - `getConfig`: retrieve current device configuration - `setConfig`: update device configuration parameters - `health`: fetch detailed diagnostic health status from the device # 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 | 113 hooks | | [Types](/reference/ui/types) | TypeScript type definitions | 774 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](/quickstart/wire-react) 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](/quickstart/wire-react) - 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 Components (/reference/ui/components/actions) Components for triggering actions and user interactions. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - 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 Components (/reference/ui/components/auth) Components for authentication flows and user sign-in. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - 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 Components (/reference/ui/components/branding) Components for brand identity and visual consistency. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - 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 Components (/reference/ui/components/dashboard) Components for building dashboard layouts and containers. ## Prerequisites - Complete the [installation](/quickstart/wire-react) - 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 MOS-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` | | - | - | | `mosPhs` | `number \| undefined` | | - | MOS-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`. | | `className` | `string \| undefined` | | - | - | ### `HeaderMinersBox` Two-row miner-count cell for the dashboard's header strip. Top row carries the MOS-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). | | `mosTotal` | `number \| undefined` | | - | Optional MOS-side meta line — total miners reporting to MOS. | | `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). | | `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](/quickstart/wire-react) - 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 ` ) } ``` ## Related API - [**`useFormField`**](/reference/ui/hooks/forms/#useformfield) @tetherto/mdk-react-devkit ## Pre-built input field ```tsx ``` ## Related API - [**`FormField`**](/reference/ui/components/forms/#formfield) - [**`useFormField`**](/reference/ui/hooks/forms/#useformfield) ### When to use `FormInput` Use `FormInput` when a standard text-like field should bind directly to `react-hook-form` with the usual label, description, control and validation message. Use the lower-level `FormField` composition when the field needs custom layout or control behaviour. ### `FormInput` example ```tsx ``` @tetherto/mdk-react-devkit ## Date range picker ```tsx ``` Single-date and range-date pickers built on `react-day-picker`. The range picker includes presets and a modal-style popover with Clear / Apply actions. ## `DatePicker` props | Prop | Type | Required | Default | Description | | ------------------- | ------------------------------- | -------- | -------------- | --------------------------------- | | `selected` | `Date` | no | — | Selected date. | | `onSelect` | `(date?: Date) => void` | no | — | Setter. | | `placeholder` | `string` | no | `"Pick a date"`| Trigger button placeholder. | | `dateFormat` | `string` | no | `"MM/dd/yyyy"` | `date-fns` format string. | | `disabled` | `boolean` | no | `false` | Disable the trigger. | | `triggerClassName` | `string` | no | — | Class names on the trigger button.| | `calendarClassName` | `string` | no | — | Class names on the day-picker. | ## `DateRangePicker` props Adds `showPresets`, `presets: PresetItem[]`, `allowFutureDates`, and `modalClassName`. `selected` / `onSelect` use `DateRange`. ## Data contracts ```ts type DateRange = { from: Date | undefined; to?: Date | undefined }; type PresetItem = { label: string; value: DateRange }; ``` ## Example ```tsx /** * Runnable example for DatePicker and DateRangePicker. */ const [date, setDate] = useState() const [range, setRange] = useState() return (

) } ``` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `Cascader` Two-panel hierarchical selector for picking a leaf value from a nested tree (categories → subcategories → leaf). Features: - Two-column layout: categories on left, options on right - Single or multiple selection modes - Search/filter functionality via [**`TagInput`**](/reference/ui/components/forms/#taginput) - Category-level selection (select/deselect all children) - Indeterminate state for partial selections - [**`Tag`**](/reference/ui/components/display/#tag) display for multiple selections - Keyboard navigation support - Disabled state support `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `options` | `CascaderOption[]` | ✓ | - | Hierarchical options to display in the cascader Parent options with children appear in the left panel Child options appear in the right panel when parent is selected | | `value` | `CascaderValue \| CascaderValue[] \| undefined` | | - | Current selected value(s) - For single select: CascaderValue (e.g., ['category', 'option']) - For multiple select: CascaderValue[] (e.g., [['cat1', 'opt1'], ['cat2', 'opt2']]) | | `onChange` | `((value: CascaderValue \| CascaderValue[] \| null) => void) \| undefined` | | - | Callback when selection changes - For single select: receives CascaderValue or null - For multiple select: receives CascaderValue[] or null | | `multiple` | `boolean \| undefined` | | `false` | Enable multiple selection mode - true: Shows checkboxes, allows multiple selections, displays selected items as tags - false: Shows radio buttons, allows single selection | | `placeholder` | `string \| undefined` | | `'Select...'` | Placeholder text shown in the input when no selections are made | | `disabled` | `boolean \| undefined` | | `false` | Disable the entire cascader (input and all options) | | `className` | `string \| undefined` | | - | Custom className for the root cascader element | | `dropdownClassName` | `string \| undefined` | | - | Custom className for the dropdown panels container | ### `Checkbox` [**`Checkbox`**](/reference/ui/components/forms/#checkbox) component with full customization `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `size` | `CheckboxSize \| undefined` | | `'md'` | Size variant of the checkbox | | `color` | `"success" \| "warning" \| "error" \| "primary" \| "default" \| undefined` | | `'primary'` | Color variant when checked | | `radius` | `BorderRadius \| undefined` | | `'none'` | Border radius variant | | `className` | `string \| undefined` | | - | Custom className for the root element | | `indicatorClassName` | `string \| undefined` | | - | Custom className for the indicator element | | `onCheckedChange` | `(((checked: CheckedState) => void) & ((checked: CheckedState) => void)) \| undefined` | | - | Callback when the checked state changes | ### `CurrencyToggler` [**`CurrencyToggler`**](/reference/ui/components/forms/#currencytoggler) component for switching between currencies `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `value` | `string` | ✓ | - | - | | `className` | `string \| undefined` | | - | - | | `currencies` | `(string \| CurrencyItem)[]` | ✓ | - | - | | `onChange` | `(currency: string) => void` | ✓ | - | - | ### `DatePicker` Single-date selection component built on react-day-picker with the MDK dark theme. Controlled via `selected` / `onSelect`. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `selected` | `Date \| undefined` | | - | Currently selected date | | `onSelect` | `((date: Date \| undefined) => void) \| undefined` | | - | Callback when date changes | | `placeholder` | `string \| undefined` | | `"Pick a date"` | Placeholder text when no date is selected | | `dateFormat` | `string \| undefined` | | `"MM/dd/yyyy"` | Date format for display | | `disabled` | `(boolean & (Matcher \| Matcher[])) \| undefined` | | `false` | Whether the picker is disabled | | `triggerClassName` | `string \| undefined` | | - | Custom className for the trigger button | | `calendarClassName` | `string \| undefined` | | - | Custom className for the calendar | ### `DateRangePicker` Date-range selection component with preset shortcuts (last 7/14/30/90 days) and a modal interface. Controlled via `selected` / `onSelect`. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `selected` | `DateRange \| undefined` | | - | Selected date range | | `onSelect` | `((range: DateRange \| undefined) => void) \| undefined` | | - | Callback when date range changes | | `placeholder` | `string \| undefined` | | `"Pick a date range"` | Placeholder text when no range is selected | | `dateFormat` | `string \| undefined` | | `"MM/dd/yyyy"` | Date format for display | | `disabled` | `(boolean & (Matcher \| Matcher[])) \| undefined` | | `false` | Whether the picker is disabled | | `showPresets` | `boolean \| undefined` | | `true` | Whether to show preset buttons | | `presets` | `PresetItem[] \| undefined` | | - | Custom preset items | | `allowFutureDates` | `boolean \| undefined` | | `false` | Whether to allow future dates | | `triggerClassName` | `string \| undefined` | | - | Custom className for the trigger button | | `calendarClassName` | `string \| undefined` | | - | Custom className for the calendar | | `modalClassName` | `string \| undefined` | | - | Custom className for the modal | ### `Form` React Hook [**`Form`**](/reference/ui/components/forms/#form) provider wrapper. Pass the result of `useForm()` as `form` and render fields via [`FormField`](/reference/ui/components/forms/#formfield) / [`FormItem`](/reference/ui/components/forms/#formitem) / [`FormLabel`](/reference/ui/components/forms/#formlabel) / [`FormControl`](/reference/ui/components/forms/#formcontrol) / [`FormMessage`](/reference/ui/components/forms/#formmessage). `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `form` | `UseFormReturn` | ✓ | - | - | | `children` | `React.ReactNode` | ✓ | - | - | ### `FormCascader` Pre-built [**`Cascader`**](/reference/ui/components/forms/#cascader) field component with integrated form state. Perfect for hierarchical selections like categories and subcategories. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string \| undefined` | | - | - | | `description` | `string \| undefined` | | - | - | | `placeholder` | `string \| undefined` | | - | - | | `options` | `CascaderOption[]` | ✓ | - | - | | `multiple` | `boolean \| undefined` | | - | - | | `cascaderProps` | `Omit, "onChange" \| "value" \| "options" \| "placeholder"> \| undefined` | | - | - | ### `FormCheckbox` Pre-built [**`Checkbox`**](/reference/ui/components/forms/#checkbox) field component with integrated form state. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string \| undefined` | | - | - | | `description` | `string \| undefined` | | - | - | | `placeholder` | `string \| undefined` | | - | - | | `checkboxProps` | `({ size?: CheckboxSize \| undefined; color?: ComponentColor \| undefined; radius?: BorderRadius \| undefined; className?: string \| undefined; indicatorClassName?: string \| undefined; onCheckedChange?: ((checked: CheckedState) => void) \| undefi… /* see source */` | | - | - | | `layout` | `"row" \| "column" \| undefined` | | - | - | ### `FormControl` Slot-based wrapper that injects ARIA attributes onto its child input element without adding an extra DOM wrapper. `agent-ready` ### `FormDatePicker` Pre-built [**`DatePicker`**](/reference/ui/components/forms/#datepicker) field component with integrated form state. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string \| undefined` | | - | - | | `description` | `string \| undefined` | | - | - | | `placeholder` | `string \| undefined` | | - | - | | `datePickerProps` | `Omit<{ selected?: Date \| undefined; onSelect?: ((date: Date \| undefined) => void) \| undefined; placeholder?: string \| undefined; dateFormat?: string \| undefined; disabled?: boolean \| undefined; triggerClassName?: string \| undefined; calenda… /* see source */` | | - | - | ### `FormDescription` Optional helper text displayed below the input. `agent-ready` ### `FormField` Wraps react-hook-form's Controller and provides field context to descendants. `agent-ready` ### `FormInput` Pre-built [**`Input`**](/reference/ui/components/forms/#input) field component with integrated form state. Reduces boilerplate by combining [**`FormField`**](/reference/ui/components/forms/#formfield), [**`FormItem`**](/reference/ui/components/forms/#formitem), [**`FormLabel`**](/reference/ui/components/forms/#formlabel), [**`FormControl`**](/reference/ui/components/forms/#formcontrol), and [**`FormMessage`**](/reference/ui/components/forms/#formmessage). `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string \| undefined` | | - | - | | `description` | `string \| undefined` | | - | - | | `placeholder` | `string \| undefined` | | - | - | | `type` | `React.HTMLInputTypeAttribute \| undefined` | | - | - | | `variant` | `"search" \| "default" \| undefined` | | - | - | | `inputProps` | `Omit & React.RefAttributes, "type" \| "variant"> \| undefined` | | - | - | ### `FormItem` Layout wrapper for a form field. Generates a unique ID for accessibility linking. `agent-ready` ### `FormLabel` [**`Label`**](/reference/ui/components/forms/#label) that auto-links to the form field input via generated IDs. Applies error styling when the field has a validation error. `agent-ready` ### `FormMessage` Displays the validation error message from react-hook-form field state. Falls back to children if no error is present. Always renders to prevent layout shift when errors appear. `agent-ready` ### `FormRadioGroup` Pre-built [**`RadioGroup`**](/reference/ui/components/forms/#radiogroup) field component with integrated form state. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string \| undefined` | | - | - | | `description` | `string \| undefined` | | - | - | | `placeholder` | `string \| undefined` | | - | - | | `options` | `FormRadioOption[]` | ✓ | - | - | | `orientation` | `"horizontal" \| "vertical" \| undefined` | | - | - | | `radioGroupProps` | `Omit<{ orientation?: "horizontal" \| "vertical" \| undefined; noGap?: boolean \| undefined; className?: string \| undefined; } & Omit, "ref"> & React.RefAttributes, "defaultV… /* see source */` | | - | - | ### `FormSelect` Pre-built [**`Select`**](/reference/ui/components/forms/#select) field component with integrated form state. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string \| undefined` | | - | - | | `description` | `string \| undefined` | | - | - | | `placeholder` | `string \| undefined` | | - | - | | `options` | `FormSelectOption[]` | ✓ | - | - | | `selectProps` | `Omit \| undefined` | | - | - | ### `FormSwitch` Pre-built [**`Switch`**](/reference/ui/components/forms/#switch) field component with integrated form state. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string \| undefined` | | - | - | | `description` | `string \| undefined` | | - | - | | `placeholder` | `string \| undefined` | | - | - | | `switchProps` | `Omit<{ size?: ComponentSize \| undefined; color?: ComponentColor \| undefined; radius?: BorderRadius \| undefined; className?: string \| undefined; thumbClassName?: string \| undefined; } & Omit, "label" \| "value" \| "placeholder" \| "onTagsChange"> \| undefined` | | - | - | ### `FormTextArea` Pre-built [**`TextArea`**](/reference/ui/components/forms/#textarea) field component with integrated form state. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `label` | `string \| undefined` | | - | - | | `description` | `string \| undefined` | | - | - | | `placeholder` | `string \| undefined` | | - | - | | `textAreaProps` | `(Omit & React.RefAttributes) \| undefined` | | - | - | ### `Input` Text input with optional label, prefix/suffix slots, and a `search` variant. Forwards refs and all native `` attributes. `agent-ready` #### Props | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | `error` | `string \| undefined` | | - | Validation error message. When provided, displays error styling (red border) and the message below the input. | | `label` | `string \| undefined` | | - | Optional label displayed above the input | | `prefix` | `React.ReactNode` | | - | Prefix element displayed before the input (left side) | | `variant` | `"search" \| "default" \| undefined` | | `'default'` | Variant of the input - `default`: Standard text input - `search`: [**`Input`**](/reference/ui/components/forms/#input) with magnifying glass icon on the right | | `size` | `InputSize \| undefined` | | `'default'` | Size of the input - `default`: padding 10px 12px, icon 16px - `medium`: padding 6px 12px, icon 12px | | `wrapperClassName` | `string \| undefined` | | - | Custom className for the root wrapper | | `suffix` | `React.ReactNode` | | - | Suffix element displayed after the input (right side) | ### `Label` Accessible text label for form controls. Associates with an input via `htmlFor` and supports a required-mark indicator. Built on Radix [**`Label`**](/reference/ui/components/forms/#label). `agent-ready` ### `MultiLevelSelect` Multi-level select component with collapsible sections. `agent-ready` ### `MultiSelect` Multi-select picker built on Radix [**`Popover`**](/reference/ui/components/overlays/#popover) + [**`Checkbox`**](/reference/ui/components/forms/#checkbox). Sibling to [` )} /> ) } ``` @tetherto/mdk-react-devkit ## Reset form state ```tsx ``` ## Related API - [**`Form`**](/reference/ui/components/forms/#form) - [**`FormInput`**](/reference/ui/components/forms/#forminput) ### When to use `useFormReset` Use `useFormReset` when resetting a [`react-hook-form`](https://react-hook-form.com/) form also needs before/after callbacks or a reusable dirty-state guard. Call the form object's `reset` method directly when no lifecycle behaviour is needed. ### `useFormReset` workflow Create the form with `useForm`, pass that instance to `useFormReset`, then wire the returned `resetForm` handler to a reset or cancel action. The hook reports `isDirty` from the same form state so the action can be disabled until values change. ### `useFormReset` prerequisite The hook requires a configured `react-hook-form` instance. It composes with [`Form`](/reference/ui/components/forms/#form) and fields such as [`FormInput`](/reference/ui/components/forms/#forminput); it does not create or submit the form. ### `useFormReset` example ```tsx type MinerFields = { name: string; ip: string } function MinerEditForm({ onSubmit }: { onSubmit: (values: MinerFields) => void }) { const form = useForm({ defaultValues: { name: '', ip: '' } }) const { resetForm, isDirty } = useFormReset({ form, onAfterReset: () => console.log('Form reset'), }) return (

) } ``` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `useFormField` Read-only context hook for form field children — returns the field's id, error state, and ARIA attributes. ```typescript () => UseFormFieldReturn ``` ### `useFormReset` Hook to handle form reset with callbacks. ```typescript ({ form, onBeforeReset, onAfterReset, }: UseFormResetOptions) => UseFormResetReturn ``` # Miscellaneous Hooks (/reference/ui/hooks/misc) Miscellaneous and general-purpose hooks. ## Package `@tetherto/mdk-react-devkit` ## Hooks @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `useEnergyReportSite` Merges site energy consumption (v2 /auth/metrics/consumption) with snapshot tail-log and container list data for the Energy report site tab. ```typescript ({ dateRange: _dateRange, consumptionLog, consumptionLoading, consumptionFetching, consumptionError, nominalPowerAvailabilityMw, nominalConfigLoading, tailLog, tailLogLoading, containers, containersLoading, }: UseEnergyReportSiteInput) => U… /* see source */ ``` ### `useHashBalance` Derives hash-balance metrics and chart datasets from finance log entries for the active date range, currency, and timeframe type. Used by hash balance panels. ```typescript ({ data, log, currency, dateRange, timeframeType, }: UseHashBalanceInput) => { siteHashRevenueChartData: BarChartDataResult; networkHashpriceChartData: BarChartDataResult; combinedCostChartData: BarChartDataResult; isEmpty: boolean; periodT… /* see source */ ``` ### `useSubsidyFees` Aggregates raw subsidy-fee log entries into chart-ready datasets keyed by the active period type (day / week / month / year) and surfaces a summary for the matching reporting widgets. Used by [`SubsidyFee`](/reference/ui/components/dashboards/#subsidyfee); expose to downstream apps that need to recompose the same datasets in a custom UI. ```typescript ({ data, log, dateRange }: UseSubsidyFeesInput) => { summary: SubsidyFeeSummary; filteredLog: SubsidyFeesLogEntry[]; aggregatedData: AggregatedPeriodData[]; subsidyFeesChartData: BarChartDataResult; averageFeesChartData: BarChartDataResult;… /* see source */ ``` ### `useUpdateExistedActions` Mutation hook that updates only the changed fields of an existing action record. Removes tags from existing pending submissions if those tags belong to the newly selected devices; if the resulting tag list is empty, the submission itself is removed. This avoids duplicate pending actions for the same device. ```typescript () => { updateExistedActions: ({ actionType, pendingSubmissions, selectedDevices, }: UpdateExistedActionsParams) => void; } ``` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `useHashrate` Base hook for a single [**`Hashrate`**](/reference/ui/components/charts/#hashrate) tab (single-site mode). Normalizes a grouped-hashrate query result to the `{ log, isLoading, error }` shape consumed by [``](/reference/ui/components/charts/#hashratesiteview), [``](/reference/ui/components/charts/#hashrateminertypeview), and [``](/reference/ui/components/charts/#hashrateminingunitview). Call once per tab the consumer needs to render - each tab fetches independently because they use different `groupBy` axes and (typically) different date ranges. ```typescript ({ query }?: UseHashrateOptions) => UseHashrateResult ``` ### `useOperationsDashboard` Shapes raw operational metric logs into chart-ready payloads for the four operational-dashboard cards. DI-style: it never fetches - wire your data layer (RTK Query, TanStack, fixtures) and pass the results in. All unit conversion and series shaping happens here so the chart components stay purely presentational. ```typescript (input?: Partial<{ hashrate: Partial<{ log: readonly OperationsTrendPoint[]; nominalValue: number | null; isLoading: boolean; error: unknown; }>; consumption: Partial<{ log: readonly OperationsTrendPoint[]; nominalValue: number | null; isLo… /* see source */ ``` # Navigation Hooks (/reference/ui/hooks/navigation) Hooks for navigation and routing state. ## Package `@tetherto/mdk-react-devkit` ## Hooks @tetherto/mdk-react-devkit ## Persist sidebar state ```tsx ``` ## Related API - [**`useSidebarSectionState`**](/reference/ui/hooks/navigation/#usesidebarsectionstate) - [**`useSidebarExpandedState`**](/reference/ui/hooks/navigation/#usesidebarexpandedstate) ### When to use sidebar state hooks Use `useSidebarExpandedState` for the whole sidebar's expanded state and `useSidebarSectionState` for an individual section. Both persist their value in `localStorage`, so navigation choices survive a reload. ### Sidebar state example ```tsx useSidebarExpandedState, useSidebarSectionState, } from '@tetherto/mdk-react-devkit' function AppSidebar() { const [expanded, setExpanded] = useSidebarExpandedState(false) const [devicesOpen, setDevicesOpen] = useSidebarSectionState('devices', true) return ( ) } ``` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `useSidebarExpandedState` Custom hook to persist sidebar expanded state in localStorage ```typescript (defaultExpanded: boolean) => [boolean, (expanded: boolean) => void] ``` ### `useSidebarSectionState` Custom hook to persist individual section open/closed states in localStorage ```typescript (sectionId: string, defaultOpen: boolean) => [boolean, (open: boolean) => void] ``` # Operations Centre Hooks (/reference/ui/hooks/op-centre) Hooks for operations centre functionality and monitoring. ## From `@tetherto/mdk-react-adapter` @tetherto/mdk-react-adapter Import the public APIs on this page from [`@tetherto/mdk-react-adapter`](/reference/ui/#tethertomdk-react-adapter). ### `useCabinetDevices` Fetches one LV cabinet's family of devices — the powermeters and temperature sensors whose `info.pos` sits under the cabinet `root` (`buildCabinetDetailParams`) — polled at the Op-Centre realtime cadence and flattened across the per-… ```typescript (root: string, options: UseCabinetDevicesOptions = {}) => UseCabinetDevicesResult ``` ### `useCabinetGroups` Fetches the Explorer cabinet-tab devices (powermeters + temperature sensors) and groups them by their owning container (`info.container`); devices without a container assignment (site-level meters) collect under the `site` group, sorted la… ```typescript (options: UseCabinetGroupsOptions = {}) => UseCabinetGroupsResult ``` ### `useContainerSettings` Fetches per-model container thresholds/parameters from `GET /auth/global/data?type=containerSettings`. Feeds the threshold status indicators (tank pressure, oil/water temperature) on the container widgets and detail tabs. ```typescript (options: UseContainerSettingsOptions = {}) => UseContainerSettingsResult ``` ### `useContainerSnapshots` Fetches the detail snapshots for the selected containers — the richer projection (`buildContainerDetailParams`) that carries `container_specific.pdu_data` plus the tank / cooling / power-mode config the detail panel controls read. `c… ```typescript (containerKeys: string[], options: UseContainerSnapshotsOptions = {}) => UseContainerSnapshotsResult ``` ### `useContainerWidgets` Data source for the Site Overview Container Widgets grid: the container inventory (one card per container) plus the latest per-miner realtime aggregate sample the cards derive their summaries from. Card-shaped payload derivation lives with… ```typescript (options: UseContainerWidgetsOptions = {}) => UseContainerWidgetsResult ``` ### `useExplorerList` Fetches the thing list behind one Explorer tab (`container` / `miner` / `cabinet`) from `GET /auth/list-things`, tag-filtered and projected by the foundation's Explorer params builder. Rows are flattened across the per-Kernel envelope so r… ```typescript (tab: ExplorerTabValue, options: UseExplorerListOptions = {}) => UseExplorerListResult ``` ### `useFeatureFlags` Fetches the deployment feature flags from `GET /auth/featureConfig` (camelCase route — there is no `/auth/feature-config`). Static deployment config — fetched once per session, no polling. Gates optional tabs/sub-routes (`containerCharts`,… ```typescript (options: UseFeatureFlagsOptions = {}) => UseFeatureFlagsResult ``` ### `usePduLayout` Fetches a container type's static PDU socket grid from `GET /auth/pdu-layout`. The grid is provisioned in the container worker's `pduGridLayout` config keyed by the exact type string — an unprovisioned type is a backend 400 (`ERR_PDU_LAYOU… ```typescript (params: UsePduLayoutParams, options: UsePduLayoutOptions = {}) => UsePduLayoutResult ``` ### `useRackLayout` Fetches the rack structure for a worker type from `GET /auth/list-racks` (`type` is required — the backend 400s with `ERR_TYPE_INVALID` without it). Feeds the Explorer rack grouping. ```typescript (params: UseRackLayoutParams, options: UseRackLayoutOptions = {}) => UseRackLayoutResult ``` ### `useSite` Fetches the configured site label from `GET /auth/site`. Static deployment config — fetched once per session, no polling. ```typescript (options: UseSiteOptions = {}) => UseSiteResult ``` ### `useThingComment` Device-comment writes for the Explorer detail panel — add, edit, and delete against `/auth/thing/comment` (the author is stamped server-side from the session token). Comments ride on the thing rows themselves (`comments` in the list-things… ```typescript () => UseThingCommentResult ``` ### `useThingDetail` Fetches a single thing by id from `GET /auth/list-things` with the full Op Centre field projection — the data source for the Explorer detail panel and the container Thing-detail view. ```typescript (id: string | undefined, options: UseThingDetailOptions = {}) => UseThingDetailResult ``` ## From `@tetherto/mdk-react-devkit` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `useExplorerSelection` Bridges the Explorer table selection into the shared `devicesStore` that the write-control cards read. Given the active tab and the table's row-selection, it dispatches the matching setters — containers → `selectMultipleContainers`, miners → `setSelectDevice` + `selectDeviceTag`, cabinets → `selectLVCabinet` — and, for containers/miners, fetches the richer detail snapshots (`useContainerSnapshots`) so the controls see the full `last.snap` config (tank / cooling / power-mode) the lean list projection omits, then derives the per-socket selection into the store. Selections are reset whenever the selection or tab changes and on unmount, so a stale selection can never drive the panel. ```typescript ({ deviceType, rows, selected, }: UseExplorerSelectionParams) => UseExplorerSelectionResult ``` ### `useMinerDetail` Reads the miner selection the [`useExplorerSelection`](/reference/ui/hooks/op-centre/#useexplorerselection) bridge writes into `devicesStore` and shapes the head miner for the read-only cards of the miner detail panel — the info rows ([`MinerInfoCard`](/reference/ui/components/widgets/#minerinfocard)) and the per-chip frequency / temperature stats ([`MinerChipsCard`](/reference/ui/components/widgets/#minerchipscard)). The write controls ([`MinerControlsCard`](/reference/ui/components/widgets/#minercontrolscard)) and the aggregate stats ([`StatsGroupCard`](/reference/ui/components/widgets/#statsgroupcard)) read the same store directly. ```typescript () => UseMinerDetailResult ``` # Permission Hooks (/reference/ui/hooks/permission) Hooks for checking permissions and managing access control. ## Package `@tetherto/mdk-react-adapter` ## Hooks @tetherto/mdk-react-adapter ## Check a permission ```tsx ``` ## Related API - [**`useAuth`**](/reference/ui/hooks/store/#useauth) ### When to use `useCheckPerm` Use `useCheckPerm` for a single reactive permission, write-access or capability gate in a React component. It reads the current permissions from the same auth store exposed by [`useAuth`](/reference/ui/hooks/store/#useauth). ### `useCheckPerm` example ```tsx function EditUsersButton() { const canEditUsers = useCheckPerm({ perm: 'users:write' }) return canEditUsers ? : null } ``` @tetherto/mdk-react-adapter Import the public APIs on this page from [`@tetherto/mdk-react-adapter`](/reference/ui/#tethertomdk-react-adapter). ### `useCheckPerm` Hook to check if the current user has a specific permission. Reads `permissions` from the headless `authStore` via `@tetherto/mdk-react-adapter`. ```typescript ({ perm, write, cap }: PermissionCheck) => boolean ``` ### `useHasPerms` Hook returning a permission-check callback bound to the current `authStore.permissions`. ```typescript () => ((req: PermissionRequest) => boolean) ``` ### `useIsFeatureEditingEnabled` Hook to check if the current user has the capability to edit feature flags. ```typescript () => boolean ``` # Settings Hooks (/reference/ui/hooks/settings) Hooks for managing user settings and preferences. ## Package `@tetherto/mdk-react-devkit` ## Hooks @tetherto/mdk-react-devkit ## Header controls ```tsx ``` ## Related API - [**`useNotification`**](/reference/ui/hooks/feedback/#usenotification) ### When to use `useHeaderControls` Use `useHeaderControls` in settings UI that reads or changes the shared header item preferences. It exposes the current preferences together with focused toggle and reset handlers. ### `useHeaderControls` notification behaviour `handleToggle` and `handleReset` show a success notification. Avoid calling either handler from rapidly changing state or an effect that can repeat, because each invocation creates another toast. ### `useHeaderControls` example ```tsx function HeaderSettings() { const { preferences, handleToggle, handleReset } = useHeaderControls() return (

{Object.entries(preferences).map(([key, visible]) => ( handleToggle(key, event.target.checked)} /> {key} ))}

) } ``` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `useHeaderControls` Read/write hook for the global header-controls store (toggles, sticky flag, theme). ```typescript () => { preferences: HeaderPreferences; isLoading: boolean; error: null; handleToggle: (key: keyof HeaderPreferences, value: boolean) => void; handleReset: () => void; } ``` # Store Hooks (/reference/ui/hooks/store) Hooks for accessing Zustand stores and managing application state. ## Package `@tetherto/mdk-react-adapter` ## Hooks @tetherto/mdk-react-adapter ## Core store hooks ```tsx ``` ## Related API - [**`useNotification`**](/reference/ui/hooks/feedback/#usenotification) ### When to use core store hooks Use these hooks when a React component needs a reactive view of the headless Foundation stores: `useAuth` for session state, `useTimezone` for the selected IANA timezone, `useNotifications` for the unread count and `useActions` for the pending operator-action queue. Non-React code can read the corresponding Foundation store directly. ### Core store hooks example ```tsx useActions, useAuth, useNotifications, useTimezone, } from '@tetherto/mdk-react-adapter' function ShellStatus() { const { token } = useAuth() const { timezone } = useTimezone() const { count } = useNotifications() const { pendingSubmissions } = useActions() return (

Session: {token ? 'Active' : 'Signed out'}
Timezone: {timezone}
Unread: {count}
Pending actions: {pendingSubmissions.length}

) } ``` @tetherto/mdk-react-adapter ## Device store access ```tsx ``` ### When to use `useDevices` Use `useDevices` in React components that need the headless device inventory or current device selection. It is the React-bound view of `devicesStore`; code outside React should use the foundation store directly. ### `useDevices` example ```tsx function DeviceToolbar() { const { selectedDevices, setSelectedDevices } = useDevices() return (

Selected: {selectedDevices.length}

) } ``` @tetherto/mdk-react-adapter Import the public APIs on this page from [`@tetherto/mdk-react-adapter`](/reference/ui/#tethertomdk-react-adapter). ### `useActions` React-bound view of the headless `actionsStore` (command queue + lifecycle). ```typescript () => ActionsStore ``` ### `useAuth` React-bound view of the headless `authStore`. Equivalent of `useStore(authStore)` — exposed as a hook for ergonomic callsites. ```typescript () => AuthStore ``` ### `useDevices` React-bound view of the headless `devicesStore` (miners, containers, PDUs). ```typescript () => DevicesStore ``` ### `useNotifications` React-bound view of the headless `notificationStore` (toast queue + history). ```typescript () => NotificationStore ``` ### `useTimezone` React-bound view of the headless `timezoneStore` (selected IANA zone). ```typescript () => TimezoneStore ``` # Table Hooks (/reference/ui/hooks/tables) Hooks for table components and data management. ## Package `@tetherto/mdk-react-devkit` ## Hooks @tetherto/mdk-react-devkit ## Explorer data ```tsx ``` ## Related API - [**`DataTable`**](/reference/ui/components/tables/#datatable) @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `useExplorerData` Explorer list data hook: fetches the things behind one tab (`useExplorerList`) and shapes them for [``](/reference/ui/components/tables/#deviceexplorer) — applying the toolbar's search + filter selections client-side and deriving the search-autocomplete and filter-cascader options from the fetched rows. The tag-based backend query lives in `@tetherto/mdk-ui-foundation`; this hook only reads snapshot fields for display filtering. Search, status-filter and (in [`DeviceExplorer`](/reference/ui/components/tables/#deviceexplorer)) column sort are all **client-side**, over a tag-filtered, capped fetch — this mirrors MOS/the reference app. Fine for containers/cabinets; for very large miner fleets this fetches the cap and filters in the browser (no server paging). Push status into the foundation query + wire `limit`/`offset` if that ceiling is ever hit. ```typescript (options: UseExplorerDataOptions) => UseExplorerDataResult ``` # UI Hooks (/reference/ui/hooks/ui) General-purpose UI state hooks. ## Package `@tetherto/mdk-react-adapter` ## Hooks @tetherto/mdk-react-adapter Import the public APIs on this page from [`@tetherto/mdk-react-adapter`](/reference/ui/#tethertomdk-react-adapter). ### `useMinerDuplicateValidation` Async validation hook that flags duplicate miners against the device inventory (MAC / serial / IP / human-facing code). ```typescript () => { duplicateError: boolean; isDuplicateCheckLoading: boolean; checkDuplicate: (selectedEditSocket: { miner?: { id?: string | undefined; } | undefined; } | null, { macAddress, serialNumber, addre… ``` ### `usePduViewer` Pan/zoom controller for the PDU floor-plan viewer. ```typescript () => UsePduViewerReturn ``` ### `useStaticMinerIpAssignment` Derives the static IP address a miner should receive based on its physical position (container number + socket coordinates). ```typescript (selectedEditSocket: Partial) => { minerIp: string; setMinerIp: React.Dispatch>; isStaticIpAssignment: boolean; } ``` # Utility Hooks (/reference/ui/hooks/utility) General-purpose utility hooks. ## From `@tetherto/mdk-react-adapter` @tetherto/mdk-react-adapter Import the public APIs on this page from [`@tetherto/mdk-react-adapter`](/reference/ui/#tethertomdk-react-adapter). ### `useBeepSound` Plays a repeating beep sound at a configurable interval. ```typescript ({ isAllowed = DEFAULTS.IS_ALLOWED, volume = DEFAULTS.VOLUME, delayMs = DEFAULTS.DELAY_MS, }: UseBeepSoundOptions = {}) => void ``` ### `useContextualModal` Headless open/close state for a modal that needs to remember the subject it was opened against (the row being edited, the device being inspected, etc.). ```typescript ({ onOpen, onClose, }: UseContextualModalParams = {}) => { modalOpen: boolean; handleClose: () => void; handleOpen: (sub: T | null) => void; subject: T | null; setSubject: React.Dispatch DeviceResolution ``` ### `useKeyDown` Tracks whether a specific keyboard key is currently held down. ```typescript (keyName: string) => boolean ``` ### `useLocalStorage` Custom hook for type-safe localStorage access with cross-tab sync. ```typescript (key: string, defaultValue: T) => [T, (value: T | ((prev: T) => T)) => void, VoidFunction] ``` ### `usePagination` Custom hook for managing pagination state ```typescript (args: PaginationArgs = {}) => UsePaginationReturn ``` ### `usePlatform` SSR-safe React hook returning the detected client OS. ```typescript () => PlatformResult ``` ### `useSubtractedTime` Returns `Date.now() - diff`, refreshing on a fixed interval (default 5s). ```typescript (diff: number, interval = DEFAULT_INTERVAL) => number ``` ### `useTimezoneFormatter` Timezone-aware date formatting hook. ```typescript () => UseTimezoneFormatterReturn ``` ### `useWindowSize` Hook to track window size changes ```typescript () => WindowSize ``` ## From `@tetherto/mdk-react-devkit` @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `useCostSummary` Base hook for the cost-summary reporting page (single-site mode). Owns the date-range / period UI state and the pure transform from a v2 `/auth/finance/cost-summary` response into headline metrics and time-series. Consumers wire their own fetch (RTK Query, TanStack Query, fixtures, ...) and pass the result through `query` - the hook never fetches itself. Multi-site mode is composed at the page level (T-13) by feeding a different response shape to the same view-model primitives; this base hook stays single-site to keep the input contract narrow. ```typescript ({ query, ...dateRangeOptions }?: UseCostSummaryOptions) => { queryParams: CostSummaryQueryParams | null; isLoading: boolean; error: {} | null; metrics: CostSummaryDisplayMetrics | null; costLog: readonly CostTimeSeriesEntry[]; btcPriceLog:… /* see source */ ``` # Widget Hooks (/reference/ui/hooks/widgets) Hooks for dashboard widgets and data cards. ## Package `@tetherto/mdk-react-devkit` ## Hooks @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `useContainerThresholds` Hook that reads and updates the temperature/pressure/power thresholds for a single container. Features: - Load and save container threshold settings - Auto-save default thresholds when none exist - Validate and auto-adjust overlapping thresholds - Handle reset to saved/default values ```typescript ({ data, onSave, }: UseContainerThresholdsProps) => UseContainerThresholdsReturn ``` ### `useFinancialDateRange` Resolves the active financial date range (start/end) used by every reporting-section query. ```typescript (options?: UseFinancialDateRangeOptions | undefined) => UseFinancialDateRangeResult ``` # Types (/reference/ui/types) TypeScript type definitions exported from `@tetherto/mdk-react-devkit` and `@tetherto/mdk-ui-foundation`. ## Browse by category ### From `@tetherto/mdk-react-devkit` | Category | Description | |----------|-------------| | [Cards](/reference/ui/types/cards) | Card component type definitions | | [General](/reference/ui/types/devkit-general) | General component and hook types | ### From `@tetherto/mdk-ui-foundation` | Category | Description | |----------|-------------| | [API](/reference/ui/types/api) | API request/response types | | [Dashboard](/reference/ui/types/foundation-dashboard) | Dashboard data types | | [General](/reference/ui/types/foundation-general) | General utility types | ## Import pattern ```tsx ``` # API Types (/reference/ui/types/api) Type definitions for API requests and responses. ## Package `@tetherto/mdk-ui-foundation` ## Types @tetherto/mdk-ui-foundation Import the public APIs on this page from [`@tetherto/mdk-ui-foundation`](/reference/ui/#tethertomdk-ui-foundation). ### `ActionsParams` Free-form query parameters for `GET /auth/actions`. Array values are serialized comma-separated (e.g. `?status=VOTING,APPROVED`). ```typescript type ActionsParams = Record ``` ### `ActionTypeQuery` One entry in the `queries` array sent to `GET /auth/actions?queries=…`. ```typescript type ActionTypeQuery = { type: 'voting' | 'ready' | 'executing' | 'done' | string opts?: { reverse?: boolean; limit?: number; [key: string]: unknown } } ``` ### `AggregatedPool` Aggregated pool row from `GET /auth/pools` (hashrate / workers / balance / revenue / summary). Feeds the Dashboard pool panel, not the Pools list. ```typescript type AggregatedPool = { name?: string hashrate?: number workers?: number balance?: number revenue?: number [key: string]: unknown } ``` ### `AlertSeverity` Severity literal expected by the `ActiveIncidentsCard` row component. ```typescript type AlertSeverity = 'critical' | 'high' | 'medium' ``` ### `AuthTokenRequest` Request body for `POST /auth/token`. The token endpoint refreshes the session and (optionally) downgrades the role set. ```typescript type AuthTokenRequest = { roles?: string[] ttl?: number ips?: string[] scope?: string } ``` ### `AuthTokenResponse` Response from `POST /auth/token`. ```typescript type AuthTokenResponse = { token: string } ``` ### `CancelActionsPayload` Arguments for `DELETE /auth/actions/:type/cancel?ids=<comma>`. ```typescript type CancelActionsPayload = { /** Action type URL segment (e.g. `voting`). */ type: string ids: Array } ``` ### `ContainerPoolStat` Per-container override-count row from `GET /auth/pools/stats/containers`. ```typescript type ContainerPoolStat = { container: string overriddenConfig?: number [key: string]: unknown } ``` ### `ContainerSettingsEntry` One row of `GET /auth/global/data?type=containerSettings` (verified live 2026-07-01 — the response is a flat array, not the per-Kernel envelope). `thresholds` is keyed by threshold type (`oilTemperature`, `tankPressure`, `waterTemperature`… ```typescript type ContainerSettingsEntry = { model: string site?: string parameters?: Record thresholds?: Record } ``` ### `ContainerThresholdLevels` Threshold band for one container parameter. Which levels are present varies per parameter (verified live: `oilTemperature` carries `alert`/`alarm`, `waterTemperature` carries `alarmLow`/`alarmHigh`). ```typescript type ContainerThresholdLevels = { criticalLow?: number alarmLow?: number alert?: number normal?: number alarm?: number alarmHigh?: number criticalHigh?: number } ``` ### `DeviceAlert` Single alert record carried on a device under `last.alerts`. The list-things endpoint returns alerts as nested arrays — see `getAlertsForDevices` for the canonical extractor. ```typescript type DeviceAlert = { uuid?: string name: string description: string message?: string severity: string createdAt: number | string type?: string } ``` ### `ExtDataParams` Query parameters for `GET /auth/ext-data` — a small key-value gateway the backend exposes for non-tail-log data sources (minerpool, mempool, etc.). ```typescript type ExtDataParams = { /** Provider id — e.g. `minerpool`, `mempool`. */ type: string /** JSON-stringified provider-specific filter. */ query?: string } ``` ### `FeatureConfigResponse` Response from `GET /auth/featureConfig` (note the camelCase path — there is no `/auth/feature-config` route). Typed loosely: the flag set is deployment-specific. The backend may also return multi-site keys (`isMultiSiteModeEnabled`, `siteL… ```typescript type FeatureConfigResponse = { [key: string]: unknown } ``` ### `GlobalDataParams` Query parameters for `GET /auth/global/data`. `type` selects the global data set (e.g. `containerSettings`); `model` optionally narrows container settings to one settings-model (`bd`, `mbt`, `hydro`, `immersion`). ```typescript type GlobalDataParams = { type: string model?: string overwriteCache?: boolean } ``` ### `HashRateLogEntry` Narrowed variant where the hashrate aggregate is present. The dashboard chart components default to this attribute when no `powerAttribute` override is provided. ```typescript type HashRateLogEntry = TailLogEntry & { hashrate_mhs_1m_sum_aggr?: number hashrate_mhs_5m_sum_aggr?: number } ``` ### `HistoricalAlert` A single historical alert row returned by `GET /auth/history-log?logType=alerts`. ```typescript type HistoricalAlert = { uuid?: string name: string description: string message?: string severity: string createdAt: number | string code?: string | number /** Owning device, when th… ``` ### `HistoryLogParams` Query parameters for `GET /auth/history-log` (alerts / info-level history). ```typescript type HistoryLogParams = { logType: 'alerts' | 'info' start?: number end?: number limit?: number offset?: number query?: string } ``` ### `ListRacksParams` Query parameters for `GET /auth/list-racks`. `type` is the worker type (e.g. `miner`, `container`) — omitting it returns `ERR_TYPE_INVALID`. ```typescript type ListRacksParams = { type: string overwriteCache?: boolean } ``` ### `ListThingsDevice` Shape returned by `GET /auth/list-things` for a single device entry. Fields are typed to the union of what the known field projections request (miner explorer, container units, dashboard). Consumers that project fewer fields still satisfy… ```typescript type ListThingsDevice = { id: string type: string status?: string tags?: string[] code?: string rack?: string containerId?: string username?: string address?: string | null err?: stri… ``` ### `ListThingsParams` Query parameters for `GET /auth/list-things`. `query` and `fields` are JSON-stringified Mongo-style selectors. ```typescript type ListThingsParams = { type?: string tag?: string status?: number | string query?: string fields?: string limit?: number offset?: number } ``` ### `LiveAction` A single live action returned by the backend voting queue. ```typescript type LiveAction = { id: string /** The action verb (e.g. `setupPools`, `registerPoolConfig`). */ action?: string type?: string status?: string /** Email/username of the submitte… ``` ### `LiveActionsResponse` Response shape of `GET /auth/actions?queries=…` — a one-element array whose single object maps each requested type to its result list. ```typescript type LiveActionsResponse = { voting?: LiveAction[] ready?: LiveAction[] executing?: LiveAction[] done?: LiveAction[] [key: string]: LiveAction[] | undefined } ``` ### `MinerEntry` A miner row from `GET /auth/miners`, carrying its assigned `poolConfig`. Only the id is guaranteed; the rest is consumed via `lodash.get`. ```typescript type MinerEntry = { id: string [key: string]: unknown } ``` ### `MinerpoolExtDataEntry` Single minerpool ext-data envelope. Backend nests these in `Array<Array<…>>` (per-pool grouping + per-timestamp grouping), so consumers `_head(_head(…))`. ```typescript type MinerpoolExtDataEntry = { ts?: string stats?: PoolMinerStats[] } ``` ### `MinerpoolStatsHistoryEntry` Single sample from the paginated `type=minerpool, key=stats-history` ext-data feed used by the multi-series Hash Rate chart. Each entry carries a timestamp and a snapshot of every configured pool's `hashrate` at that point in time. ```typescript type MinerpoolStatsHistoryEntry = { ts: number stats: PoolMinerStats[] } ``` ### `MinersParams` Query parameters for `GET /auth/miners`. `filter`, `fields`, and `sort` are JSON-stringified Mongo-style selectors; `search` is free text matched across id / code / serial / mac. ```typescript type MinersParams = { filter?: string fields?: string sort?: string search?: string limit?: number offset?: number } ``` ### `MinersResponse` Paginated envelope returned by `GET /auth/miners` — page `data` plus site-wide pagination metadata. ```typescript type MinersResponse = { data: MinerEntry[] totalCount: number offset: number limit: number hasMore: boolean } ``` ### `PduLayoutItem` One PDU row in the static grid layout. `power_w` / `current_a` / `offline` are absent in the static layout and filled from live `pdu_data`. ```typescript type PduLayoutItem = { pdu: string sockets: PduLayoutSocket[] power_w?: number | string current_a?: number | string offline?: boolean } ``` ### `PduLayoutParams` Query parameters for `GET /auth/pdu-layout`. `type` is the full container type string (e.g. `container-bd-d40-m56`). ```typescript type PduLayoutParams = { type: string overwriteCache?: boolean } ``` ### `PduLayoutResponse` Response from `GET /auth/pdu-layout` (verified live 2026-07-01). The backend sources this from the container worker's `pduGridLayout` config, keyed by the exact container type, and 400s with `ERR_PDU_LAYOUT_NOT_FOUND` when no layout is pro… ```typescript type PduLayoutResponse = { type: string layout: PduLayoutItem[] } ``` ### `PduLayoutSocket` One socket in a PDU grid. `enabled` reflects the static layout default; live on/off state comes from the device's `pdu_data` merge. ```typescript type PduLayoutSocket = { socket: string enabled: boolean cooling?: boolean } ``` ### `PoolBalanceHistoryEntry` A single revenue/hashrate sample from `GET /auth/pools/:pool/balance-history`. ```typescript type PoolBalanceHistoryEntry = { ts?: number revenue?: number hashrate?: number /** Settled balance for the bucket (equals `revenue` in the current backend). */ balance?: number [key: string… ``` ### `PoolBalanceHistoryParams` Query parameters for `GET /auth/pools/:pool/balance-history`. The backend requires both `start` and `end` (Unix ms) and rejects the request otherwise; they are typed optional only so a param object can be built incrementally. ```typescript type PoolBalanceHistoryParams = { /** Window start (Unix ms). Required by the backend. */ start?: number /** Window end (Unix ms). Required by the backend. */ end?: number range?: '1D' | '1W'… ``` ### `PoolBalanceHistoryResponse` Response envelope for `GET /auth/pools/:pool/balance-history` — the backend wraps the samples in `{ log }`. ```typescript type PoolBalanceHistoryResponse = { log: PoolBalanceHistoryEntry[] } ``` ### `PoolConfigEntry` Raw pool-configuration row from `GET /auth/configs/pool`. This is the shape the devkit `usePoolConfigs` transform consumes to build a `PoolSummary`. ```typescript type PoolConfigEntry = { id: string poolConfigName: string description: string poolUrls: PoolConfigUrl[] miners: number containers: number updatedAt: string | number } ``` ### `PoolConfigForDeviceResponse` Response for `GET /auth/pools/config/:id` — the device's assigned pool config id and the count of miners overriding their container's config. ```typescript type PoolConfigForDeviceResponse = { poolConfig: string | null overriddenConfig: number } ``` ### `PoolConfigUrl` A single pool-URL endpoint as stored on a pool configuration. `url` is a `stratum+tcp://host:port` string; the devkit `usePoolConfigs` transform parses it into host/port/role for display. ```typescript type PoolConfigUrl = { url: string pool: string workerName?: string workerPassword?: string } ``` ### `PoolMinerStats` Per-pool stats entry returned by `GET /auth/ext-data?type=minerpool`. Each configured pool (`f2pool`, `ocean`, …) contributes one row. ```typescript type PoolMinerStats = { poolType?: string /** Subaccount / user the pool worker submits shares under. */ username?: string /** * Pool-reported hashrate in **H/s** (raw hashes per se… ``` ### `PoolsResponse` Response envelope for `GET /auth/pools` — the aggregated `pools` list plus a site-wide `summary`. The backend wraps the array, so consumers must read `.pools` rather than treating the payload as an array. ```typescript type PoolsResponse = { pools: AggregatedPool[] summary: PoolsSummary } ``` ### `PoolsSummary` Site-wide totals returned alongside the pool list by `GET /auth/pools`. ```typescript type PoolsSummary = { poolCount: number totalHashrate: number totalWorkers: number totalBalance: number } ``` ### `PowerModeTimelineEntry` Power-mode timeline entry — carries grouped per-miner mode/status maps keyed by miner id. Consumed by `PowerModeTimelineChart`. ```typescript type PowerModeTimelineEntry = TailLogEntry & { power_mode_group_aggr?: Record status_group_aggr?: Record } ``` ### `Rack` A single rack entry from `GET /auth/list-racks`. Typed loosely — the `listRacks` RPC response shape has not been captured against a live backend yet (staging returned no rack data at verification time). ```typescript type Rack = { id?: string name?: string [key: string]: unknown } ``` ### `SiteResponse` Response from `GET /auth/site` — the configured site label. ```typescript type SiteResponse = { site: string } ``` ### `SiteStatusAlerts` Alert counts by severity from the live site-status snapshot. ```typescript type SiteStatusAlerts = { critical: number high: number medium: number total: number } ``` ### `SiteStatusLive` Composite live site-status snapshot from `GET /auth/site/status/live`. Aggregates site-wide hashrate, power, efficiency, miner/alert/pool counts, and the snapshot timestamp (`ts`, Unix ms). Polled on a short interval. ```typescript type SiteStatusLive = { hashrate: SiteStatusMetric power: SiteStatusPower efficiency: SiteStatusMetric miners: SiteStatusMiners alerts: SiteStatusAlerts pools: SiteStatusPools /** S… ``` ### `SiteStatusMetric` A `{ value, unit }` measurement, optionally annotated with a `nominal` (rated) value and a `utilization` percentage (`value / nominal * 100`). ```typescript type SiteStatusMetric = { value: number unit: string nominal?: number utilization?: number } ``` ### `SiteStatusMiners` Miner population counts from the live site-status snapshot. ```typescript type SiteStatusMiners = { online: number offline: number error: number total: number containerCapacity: number } ``` ### `SiteStatusPools` Pool-side aggregates from the live site-status snapshot. ```typescript type SiteStatusPools = { totalHashrate: { value: number; unit: string } activeWorkers: number totalWorkers: number } ``` ### `SiteStatusPower` Power metric from the live site-status snapshot. Like `SiteStatusMetric` but with an `alert` message and a hard `error` flag. ```typescript type SiteStatusPower = SiteStatusMetric & { alert?: string error?: boolean } ``` ### `SubmitBatchActionsPayload` Body for `POST /auth/actions/voting/batch` — a set of staged actions plus a client-generated `batchActionUID` the backend uses to group them. ```typescript type SubmitBatchActionsPayload = { batchActionsPayload: VotingActionPayload[] batchActionUID: string suffix?: string /** Batch-level annotations (e.g. `{ isBackFromMaintenance }` on miner move… ``` ### `TailLogEntry` A single time-bucketed entry from `GET /auth/tail-log`. Backend returns `Array<Array<TailLogEntry>>` (outer wrapping is the per-worker grouping — single-site dashboards take `_head(response)`). ```typescript type TailLogEntry = { ts: number /** All other fields are dynamic aggregates requested via `aggrFields`. */ [key: string]: unknown } ``` ### `TailLogMultiParams` Query parameters for `GET /auth/tail-log/multi` — the batched variant of tail-log. `keys` is required (comma-separated `stat-*` keys); the rest mirrors the Fastify schema in `miningos-gateway`. {todo: update miningos-gateway} ```typescript type TailLogMultiParams = { keys: string start?: number end?: number offset?: number limit?: number fields?: string aggrFields?: string aggrTimes?: string overwriteCache?: boolean } ``` ### `TailLogParams` Query parameters for `GET /auth/tail-log`. Mirrors the Fastify schema in `miningos-gateway`. `aggrFields` is a JSON-stringified object describing which aggregate columns to include in each row. ```typescript type TailLogParams = { key: string type?: string tag?: string start?: number end?: number offset?: number limit?: number fields?: string aggrFields?: string aggrTimes?: string merg… ``` ### `ThingCommentBody` Body for `POST | PUT | DELETE /auth/thing/comment` (add / edit / delete a device comment — one Fastify schema covers all three verbs). `rackId` + `thingId` + `comment` are required; `id` and `ts` identify an existing comment for edit/delet… ```typescript type ThingCommentBody = { rackId: string thingId: string comment: string /** Existing comment id — required when editing or deleting. */ id?: string pos?: string ts?: number } ``` ### `ThingConfigParams` Query parameters for `GET /auth/thing-config` — both fields are required by the Fastify schema. ```typescript type ThingConfigParams = { type: string requestType: string } ``` ### `VoteActionPayload` Body for `PUT /auth/actions/voting/:id/vote`. ```typescript type VoteActionPayload = { id: string | number approve: boolean } ``` ### `VotingActionObjectParam` Object-shaped `params[]` entry on a voting submission. Pool create/update carry `{ type: 'pool', data }` (+ `id` for updates); assign-pool carries `{ poolConfigId, configType: 'pool' }`; `switchSocket` carries `{ pdu, socket, enabled }`; `… ```typescript type VotingActionObjectParam = { type?: string id?: string poolConfigId?: string configType?: string data?: Record [key: string]: unknown } ``` ### `VotingActionParam` A single `params[]` entry on a voting submission. Positional and action-specific: device actions carry primitives (`setPowerMode` sends `['sleep']`, `setLED` sends `[true]`, `setTankEnabled` sends `[3, true]`), pool/thing actions carry {@l… ```typescript type VotingActionParam = string | number | boolean | VotingActionObjectParam ``` ### `VotingActionPayload` Body for `POST /auth/actions/:type` (default `voting`). `type` selects the URL segment and is stripped from the JSON body before posting — the remaining fields (`query`, `action`, `params`, `rackType`, …) form the request body. ```typescript type VotingActionPayload = { /** URL segment under `/auth/actions/:type`. Defaults to `voting`. */ type?: string query?: Record action?: string params?: VotingActionPara… ``` # Card Types (/reference/ui/types/cards) Type definitions for card components. ## Package `@tetherto/mdk-react-devkit` ## Types @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `MiningPoolRow` Display contract for one row of the `<MiningPoolsPanel />` table. Adapter hooks (e.g. `usePoolRows`) shape their output to fit this type; consumers can also build rows by hand for fixtures or demos. ```typescript type MiningPoolRow = { /** Stable React key. */ id: string /** Display name (e.g. `minerpool-f2pool-shelf-0`). */ name: string /** 24h revenue in BTC; rendered as `0.00 BTC` when undefined. */ revenue24hBtc?: number /** Hashrate in PH/s — used for display (TH/… ``` # Devkit General Types (/reference/ui/types/devkit-general) General type definitions from the react-devkit package. ## Package `@tetherto/mdk-react-devkit` ## Types @tetherto/mdk-react-devkit Import the public APIs on this page from [`@tetherto/mdk-react-devkit`](/reference/ui/#tethertomdk-react-devkit). ### `ActionButtonConfirmation` ```typescript type ActionButtonConfirmation = { title: string cancelLabel?: string confirmLabel?: string icon?: React.ReactNode onCancel?: VoidFunction onConfirm?: VoidFunction description?: React.ReactNode } ``` ### `ActionButtonProps` ```typescript type ActionButtonProps = { label?: string loading?: boolean disabled?: boolean className?: string variant?: TActionButtonVariant confirmation: ActionButtonConfirmation /** Confirmation mode: popover (inline) or dialog (modal). Default: popover */ mode?: 'popover'… ``` ### `ActionNameKey` ```typescript type ActionNameKey = keyof typeof ACTION_NAMES_MAP ``` ### `ActionNameValue` ```typescript type ActionNameValue = (typeof ACTION_NAMES_MAP)[ActionNameKey] ``` ### `ActionStatusTypeKey` ```typescript type ActionStatusTypeKey = keyof typeof ACTION_STATUS_TYPES ``` ### `ActionStatusTypeValue` ```typescript type ActionStatusTypeValue = (typeof ACTION_STATUS_TYPES)[ActionStatusTypeKey] ``` ### `ActionTypeKey` ```typescript type ActionTypeKey = keyof typeof ACTION_TYPES ``` ### `ActionTypeValue` ```typescript type ActionTypeValue = (typeof ACTION_TYPES)[ActionTypeKey] ``` ### `ActiveIncidentsCardPartialProps` ```typescript type ActiveIncidentsCardPartialProps = Partial<{ label: string isLoading: boolean className: string skeletonRows: number emptyMessage: string items: TIncidentRowProps[] onItemClick: (id: string) => void }> ``` ### `ActiveTimeframe` Which single control “owns” the range: others show placeholders (mutually exclusive UI). ```typescript type ActiveTimeframe = 'year' | 'month' | 'week' ``` ### `ActualEbitdaCardProps` ```typescript type ActualEbitdaCardProps = { value: number } ``` ### `AddSparePartFormValues` Values collected by the register-part form. Select fields are nullable until chosen. ```typescript type AddSparePartFormValues = { partTypeId: string; model: string | null; parentDeviceModel: string | null; serialNum: string; macAddress: string; status: string | null; location: string | null; comment: string; tags: string[]; } ``` ### `AddSparePartModalProps` Props for `AddSparePartModal`; option lists and handlers are supplied by the caller. ```typescript type AddSparePartModalProps = { isOpen: boolean; onClose: VoidFunction; partTypes: SparePartSubTypesModalPartType[]; defaultPartTypeId?: string; modelOptions: FormSelectOption[]; isModelOptionsLoading?: boolean; minerModelOptions: FormSelectOption[]; statusOptions: For… ``` ### `AddUserModalProps` ```typescript type AddUserModalProps = { open: boolean onClose: VoidFunction roles: RoleOption[] onSubmit: (data: { name: string; email: string; role: string }) => Promise isSubmitting?: boolean } ``` ### `AlarmItemData` ```typescript type AlarmItemData = { title: string subtitle: string body: string uuid?: string status: string [key: string]: unknown } ``` ### `AlarmsBellButtonCounts` ```typescript type AlarmsBellButtonCounts = { critical?: number high?: number medium?: number } ``` ### `AlarmsBellButtonProps` ```typescript type AlarmsBellButtonProps = { /** Severity-bucketed alarm counts rendered in the stacked badge. */ counts?: AlarmsBellButtonCounts /** Click handler — typically opens an alerts panel or routes to /alerts. */ onClick?: (event: MouseEvent) => void /*… ``` ### `Alert` ```typescript type Alert = { id?: string severity: string createdAt: number | string name: string description: string message?: string uuid?: string code?: string | number [key: string]: unknown } ``` ### `AlertActions` ```typescript type AlertActions = { onAlertClick?: (id: string, uuid: string) => void id?: string uuid: string } ``` ### `AlertConfirmationModalProps` ```typescript type AlertConfirmationModalProps = { isOpen: boolean onOk: VoidFunction } ``` ### `AlertLocalFilters` ```typescript type AlertLocalFilters = { severity?: string[] | string status?: string[] type?: string[] id?: string[] thing?: { id?: string } [key: string]: unknown } ``` ### `AlertSeverity` ```typescript type AlertSeverity = (typeof ALERT_SEVERITY_TYPES)[keyof typeof ALERT_SEVERITY_TYPES] ``` ### `AlertsProps` ```typescript type AlertsProps = { /** * Devices payload powering the "Current Alerts" table. * Mirrors the API response shape of `useGetListThingsQuery({ ... alerts query })`. */ devices?: Device[][] /** * Loading flag for the "Current Alerts" table. */ isCurrentAlertsLo… ``` ### `AlertsTableTitleProps` ```typescript type AlertsTableTitleProps = { title: ReactNode subtitle?: ReactNode className?: string } ``` ### `AlertTableRecord` ```typescript type AlertTableRecord = { shortCode: string device: string alertName: string description?: string message?: string severity: string createdAt: number | string id?: string uuid: string actions?: AlertActions /** * Hidden tokens (uuid, ip-/mac-/sn-/firmware- tags,… ``` ### `ApiErrorKey` ```typescript type ApiErrorKey = keyof typeof API_ERRORS ``` ### `ApiErrorValue` ```typescript type ApiErrorValue = (typeof API_ERRORS)[ApiErrorKey] ``` ### `ApiResponse` ```typescript type ApiResponse = { data: T message?: string status: number } ``` ### `AppHeaderProps` ```typescript type AppHeaderProps = { /** Left-most slot — typically the app's brand lockup / logo. */ logo?: ReactNode /** Left-edge content — e.g. a sidebar collapse toggle button. */ start?: ReactNode /** Middle slot — typically the dashboard's stats strip. */ children?:… ``` ### `AreaChartProps` ```typescript type AreaChartProps = { /** Chart data - required, provided by parent */ data: ChartJS<'line'>['data'] /** Chart.js options - merged with defaults */ options?: ChartJS<'line'>['options'] /** Custom HTML tooltip configuration. When provided, replaces the default… ``` ### `ArrowIconProps` ```typescript type ArrowIconProps = { isOpen?: boolean } & IconProps ``` ### `AssignPoolModalProps` ```typescript type AssignPoolModalProps = { isOpen: boolean onClose: () => void onSubmit: (values: { pool: PoolSummary }) => Promise miners: Device[] poolConfig: PoolConfigData[] } ``` ### `AttentionLevelColorKey` ```typescript type AttentionLevelColorKey = keyof typeof ATTENTION_LEVEL_COLORS ``` ### `AuthCapKey` ```typescript type AuthCapKey = keyof typeof AUTH_CAPS ``` ### `AuthCapValue` ```typescript type AuthCapValue = (typeof AUTH_CAPS)[AuthCapKey] ``` ### `AverageDowntimeChartData` ```typescript type AverageDowntimeChartData = { labels: string[] curtailment?: number[] operationalIssues?: number[] } ``` ### `AverageDowntimeChartProps` ```typescript type AverageDowntimeChartProps = Partial<{ title: string unit: string height: number barWidth: number className: string isLoading: boolean emptyMessage: string data: AverageDowntimeChartData /** Formats Y-axis ticks, tooltips, and bar data labels (values are 0–1 rates). *… ``` ### `AvgAllInCostChartProps` ```typescript type AvgAllInCostChartProps = { data?: ReadonlyArray dateRange: FinancialDateRange | null isLoading?: boolean } ``` ### `AvgAllInCostDataPoint` ```typescript type AvgAllInCostDataPoint = { ts: number revenueUSDPerMWh: number costUSDPerMWh: number } ``` ### `AvgHistoryRangeKey` ```typescript type AvgHistoryRangeKey = keyof typeof AVG_HISTORY_RANGES ``` ### `AvgHistoryRangeValue` ```typescript type AvgHistoryRangeValue = (typeof AVG_HISTORY_RANGES)[AvgHistoryRangeKey] ``` ### `AxisTitleText` ```typescript type AxisTitleText = { x: string y: string } ``` ### `BadgeColors` Display colors for a status/location badge. ```typescript type BadgeColors = { backgroundColor: string borderColor: string } ``` ### `BadgeProps` ```typescript type BadgeProps = { /** * Badge content (wraps children with badge) */ children?: ReactNode /** * Number to display in badge * If > overflowCount, will show "overflowCount+" */ count?: number /** * Maximum count to display * @default 99 */ overflowCount?: n… ``` ### `BadgeStatus` Badge status options ```typescript type BadgeStatus = 'success' | 'processing' | 'error' | 'warning' | 'default' ``` ### `BarChartConstant` ```typescript type BarChartConstant = { label: string value: number color?: string borderDash?: number[] yAxisID?: string } ``` ### `BarChartInput` ```typescript type BarChartInput = { labels?: string[] series: BarChartSeries[] lines?: BarChartLine[] constants?: BarChartConstant[] } ``` ### `BarChartItemBorderColorKey` ```typescript type BarChartItemBorderColorKey = keyof typeof BAR_CHART_ITEM_BORDER_COLORS ``` ### `BarChartLine` ```typescript type BarChartLine = { label: string values: number[] | Record color?: string yAxisID?: string tension?: number pointRadius?: number pointHoverRadius?: number } ``` ### `BarChartProps` ```typescript type BarChartProps = { /** Chart data - required, provided by parent. Use `as any` for mixed bar+line datasets. */ data: any /** Chart.js options - merged with defaults */ options?: ChartJS<'bar'>['options'] /** Stack bars on top of each other */ isStacked?: b… ``` ### `BarChartSeries` ```typescript type BarChartSeries = { label: string values: number[] | Record color?: string /** Assign a stack group id to stack multiple series together */ stack?: string /** Gradient opacity stops (default { top: 0.3, bottom: 0.1 }) */ gradient?: { top: nu… ``` ### `BatchActionTypeKey` ```typescript type BatchActionTypeKey = keyof typeof BATCH_ACTION_TYPES ``` ### `BatchActionTypeValue` ```typescript type BatchActionTypeValue = (typeof BATCH_ACTION_TYPES)[BatchActionTypeKey] ``` ### `BatchMoveSparePart` A spare part shown in the batch-move table. ```typescript type BatchMoveSparePart = { id: string; code: string; location: string; status: string; } ``` ### `BatchMoveSparePartsModalProps` Props for `BatchMoveSparePartsModal`; unselected location/status arrive as `null` on submit. ```typescript type BatchMoveSparePartsModalProps = { isOpen: boolean; onClose: VoidFunction; spareParts: BatchMoveSparePart[]; locationOptions: FormSelectOption[]; statusOptions: FormSelectOption[]; onSubmit: (values: { location: string | null; status: string | null; observation: string |… ``` ### `BitcoinPriceCardProps` ```typescript type BitcoinPriceCardProps = { value: number } ``` ### `BitcoinProducedCardProps` ```typescript type BitcoinProducedCardProps = { value: number } ``` ### `BitcoinProducedChartProps` ```typescript type BitcoinProducedChartProps = { chartData: BarChartDataResult isLoading?: boolean hasAllZeros?: boolean height?: number } ``` ### `BitcoinProductionCostCardProps` ```typescript type BitcoinProductionCostCardProps = { value: number } ``` ### `BitMainControlsTabProps` ```typescript type BitMainControlsTabProps = { /** Device data */ data: Device } ``` ### `BitMainHydroSettingsProps` ```typescript type BitMainHydroSettingsProps = { /** Device data */ data?: Device } ``` ### `BitMainImmersionSummaryBoxContainerSettings` ```typescript type BitMainImmersionSummaryBoxContainerSettings = { thresholds?: Record } ``` ### `BitMainImmersionSummaryBoxProps` ```typescript type BitMainImmersionSummaryBoxProps = { data?: Device containerSettings?: BitMainImmersionSummaryBoxContainerSettings | null } ``` ### `BorderRadius` Border radius variants Used by Checkbox, Switch, Radio ```typescript type BorderRadius = 'none' | 'small' | 'medium' | 'large' | 'full' ``` ### `BreadcrumbItem` ```typescript type BreadcrumbItem = { label: string href?: string onClick?: VoidFunction } ``` ### `BreadcrumbsProps` ```typescript type BreadcrumbsProps = { items: BreadcrumbItem[] showBack?: boolean backLabel?: string className?: string itemClassName?: string backClassName?: string onBackClick?: VoidFunction separator?: ReactNode } ``` ### `BtcAveragePriceProps` ```typescript type BtcAveragePriceProps = Partial<{ /** * BTC price in USD; formatted with grouping and no decimal places. * When `null`, `undefined`, non-finite, or negative, the value shows `-` (`FALLBACK` from format utils). */ price: number | null /** * Label for the BTC avera… ``` ### `BtcPriceTimeSeriesEntry` ```typescript type BtcPriceTimeSeriesEntry = { ts: number priceUSD: number } ``` ### `BuildAvgAllInCostInputArgs` ```typescript type BuildAvgAllInCostInputArgs = { data?: ReadonlyArray dateRange: FinancialDateRange | null } ``` ### `BuildBarChartOptionsInput` ```typescript type BuildBarChartOptionsInput = { isHorizontal?: boolean isStacked?: boolean yTicksFormatter?: (value: number) => string yRightTicksFormatter?: ((value: number) => string) | null displayColors?: boolean legendPosition?: 'top' | 'bottom' | 'left' | 'right' legendAlign?: '… ``` ### `BuildProductionCostInputArgs` ```typescript type BuildProductionCostInputArgs = { costLog: ReadonlyArray btcPriceLog: ReadonlyArray dateRange: FinancialDateRange | null } ``` ### `BulkAddSparePartsModalProps` Props for `BulkAddSparePartsModal`; `onSubmit` receives the parsed CSV records. ```typescript type BulkAddSparePartsModalProps = { isOpen: boolean; onClose: VoidFunction; onSubmit: (records: CSVRecord[]) => Promise<{ error?: string } | void>; isLoading?: boolean; } ``` ### `ButtonIconPosition` Button icon position ```typescript type ButtonIconPosition = 'left' | 'right' ``` ### `ButtonProps` Props for `Button`. Extends all native `<button>` attributes. ```typescript type ButtonProps = Partial< { /** Show a spinner instead of the content and disable the button. */ loading: boolean /** Make the button stretch to fill its container. */ fullWidth: boolean /** Icon node rendered alongside `children`. */ icon: ReactNode /** V… ``` ### `ButtonSize` Button-specific size including icon-only variant ```typescript type ButtonSize = ComponentSize | 'icon' ``` ### `ButtonVariant` Component-specific prop types ```typescript type ButtonVariant = | 'primary' | 'secondary' | 'danger' | 'tertiary' | 'link' | 'nav-link' | 'icon' | 'outline' | 'ghost' ``` ### `CabinetDetailCardProps` ```typescript type CabinetDetailCardProps = { /** Cabinet display title (`LV Cabinet 1` / transformer title). */ title: string /** Non-root powermeter reading rows. */ powerMeters: CabinetReadingRow[] /** The cabinet-root temperature reading, when present. */ rootTempSensor?: Cabine… ``` ### `CabinetReadingRow` One sensor / powermeter reading row rendered in the cabinet detail. ```typescript type CabinetReadingRow = { /** Stable key — the source device id. */ id: string /** Display name (sensor / powermeter name). */ label: string /** Formatted reading, or `-` when unavailable. */ value: string /** Unit shown next to the value. */ unit: string /** Sev… ``` ### `CardBodyProps` Props for `CardBody` slot. Forwards all native `<div>` attributes. ```typescript type CardBodyProps = HTMLAttributes ``` ### `CardComponent` ```typescript type CardComponent = ForwardRefExoticComponent> & { Header: typeof CardHeader Body: typeof CardBody Footer: typeof CardFooter } ``` ### `CardFooterProps` Props for `CardFooter` slot. Forwards all native `<div>` attributes. ```typescript type CardFooterProps = HTMLAttributes ``` ### `CardHeaderProps` Props for `CardHeader` slot. Forwards all native `<div>` attributes. ```typescript type CardHeaderProps = HTMLAttributes ``` ### `CardProps` Props for `Card`. Forwards all native `<div>` attributes. ```typescript type CardProps = HTMLAttributes ``` ### `CascaderOption` Cascader option type - represents a hierarchical option with optional children ```typescript type CascaderOption = { /** Unique value for the option */ value: string | number | boolean /** Display label for the option */ label: string /** Child options (creates a nested category) */ children?: CascaderOption[] /** Whether the option is disabled */ disa… ``` ### `CascaderProps` Cascader component props ```typescript type CascaderProps = { /** * Hierarchical options to display in the cascader * Parent options with children appear in the left panel * Child options appear in the right panel when parent is selected */ options: CascaderOption[] /** * Current selected value(s)… ``` ### `CascaderValue` Cascader value type - array representing the path from parent to child Example: ['electronics', 'phones'] means category 'electronics', option 'phones' ```typescript type CascaderValue = (string | number | boolean)[] ``` ### `ChangeConfirmationModalProps` ```typescript type ChangeConfirmationModalProps = { open: boolean title: string onConfirm: VoidFunction onClose: VoidFunction children: ReactNode confirmText?: string destructive?: boolean } ``` ### `ChartColorKey` ```typescript type ChartColorKey = keyof typeof CHART_COLORS ``` ### `ChartContainerProps` ```typescript type ChartContainerProps = { title?: string /** * 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. */ titleExtra?: Reac… ``` ### `ChartDataByDevice` ```typescript type ChartDataByDevice = { [deviceName: string]: ChartDataset } ``` ### `ChartDataPoint` ```typescript type ChartDataPoint = { x: number | string y: number } ``` ### `ChartEntry` ```typescript type ChartEntry = { ts: number | string container_specific_stats_group_aggr: Record } ``` ### `ChartExpandActionProps` ```typescript type ChartExpandActionProps = { /** Whether the parent chart is currently expanded to full width. */ isExpanded: boolean /** Toggles the expanded state. */ onToggle?: VoidFunction } ``` ### `ChartLabelKey` ```typescript type ChartLabelKey = keyof typeof CHART_LABELS ``` ### `ChartLabelValue` ```typescript type ChartLabelValue = (typeof CHART_LABELS)[ChartLabelKey] ``` ### `ChartLegendOpacityKey` ```typescript type ChartLegendOpacityKey = keyof typeof CHART_LEGEND_OPACITY ``` ### `ChartLegendOpacityValue` ```typescript type ChartLegendOpacityValue = (typeof CHART_LEGEND_OPACITY)[ChartLegendOpacityKey] ``` ### `ChartLegendPosition` ```typescript type ChartLegendPosition = 'top' | 'bottom' | 'left' | 'right' | 'center' | 'chartArea' ``` ### `ChartPerformanceKey` ```typescript type ChartPerformanceKey = keyof typeof CHART_PERFORMANCE ``` ### `ChartRange` ```typescript type ChartRange = { min: Date | number max: Date | number } ``` ### `ChartStatsFooterItem` ```typescript type ChartStatsFooterItem = { label: string value: string | number } ``` ### `ChartStatsFooterProps` ```typescript type ChartStatsFooterProps = Partial<{ /** Min/Max/Avg values row */ minMaxAvg: MinMaxAvgValues /** Additional stats displayed in a columnar grid */ stats: ChartStatsFooterItem[] /** Number of stat items per column (default: 1) */ statsPerColumn: number /** Secondary… ``` ### `ChartTitleKey` ```typescript type ChartTitleKey = keyof typeof CHART_TITLES ``` ### `ChartTitleValue` ```typescript type ChartTitleValue = (typeof CHART_TITLES)[ChartTitleKey] ``` ### `ChartTooltipConfig` ```typescript type ChartTooltipConfig = { /** Color for label text. Use 'dataset' to match dataset border color. Defaults to COLOR.WHITE_ALPHA_05 */ labelColor?: string | 'dataset' /** Color for value text. Use 'dataset' to match dataset border color. Defaults to 'dataset' */ va… ``` ### `ChartTypeKey` ```typescript type ChartTypeKey = keyof typeof CHART_TYPES ``` ### `ChartTypeValue` ```typescript type ChartTypeValue = (typeof CHART_TYPES)[ChartTypeKey] ``` ### `CheckboxProps` ```typescript type CheckboxProps = { /** * Size variant of the checkbox * @default 'md' */ size?: CheckboxSize /** * Color variant when checked * @default 'primary' */ color?: ComponentColor /** * Border radius variant * @default 'none' */ radius?: BorderRadius /** * Custom… ``` ### `CheckboxSize` ```typescript type CheckboxSize = 'xs' | ComponentSize ``` ### `ChipData` ```typescript type ChipData = { index: number current: number } ``` ### `ColorKey` ```typescript type ColorKey = keyof typeof COLOR ``` ### `ColorValue` ```typescript type ColorValue = (typeof COLOR)[ColorKey] ``` ### `ColorVariant` Color variants for components Comprehensive set including all semantic colors ```typescript type ColorVariant = | 'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info' ``` ### `ComponentColor` Component color options (subset of ColorVariant) Used by form components like Checkbox, Switch, Radio, Typography ```typescript type ComponentColor = 'default' | 'primary' | 'success' | 'warning' | 'error' ``` ### `ComponentSize` Common shared types used across components ```typescript type ComponentSize = 'sm' | 'md' | 'lg' ``` ### `ConfirmDeleteSparePartModalProps` Props for `ConfirmDeleteSparePartModal`. ```typescript type ConfirmDeleteSparePartModalProps = { isOpen?: boolean; onClose?: VoidFunction; onConfirm?: (sparePart: ConfirmDeleteSparePartModalSparePart) => Promise | void; sparePart?: ConfirmDeleteSparePartModalSparePart; isLoading?: boolean; } ``` ### `ConfirmDeleteSparePartModalSparePart` The spare part targeted for deletion. ```typescript type ConfirmDeleteSparePartModalSparePart = { id: string; code: string; } ``` ### `ConsumptionNominalValueType` ```typescript type ConsumptionNominalValueType = typeof CONSUMPTION_NOMINAL_VALUE_W ``` ### `Container` ```typescript type Container = { info?: Partial last?: Partial } & Device ``` ### `ContainerActionValue` ```typescript type ContainerActionValue = (typeof CONTAINER_ACTIONS)[number] ``` ### `ContainerActivityData` Miner-state counts fed to the embedded activity chart (online / offline / faulted / …). ```typescript type ContainerActivityData = { total?: number } & Record ``` ### `ContainerActivityError` Error envelope surfaced by the activity chart when its data fails to load. ```typescript type ContainerActivityError = { data?: { message?: string }; [key: string]: unknown } | null ``` ### `ContainerChartCombinationOption` ```typescript type ContainerChartCombinationOption = { value: string label: string } ``` ### `ContainerChartsDatasetBorderColorResolver` ```typescript type ContainerChartsDatasetBorderColorResolver = (args: { chartTitle: string datasetLabel: string datasetIndex: number }) => string | undefined ``` ### `ContainerChartsProps` ```typescript type ContainerChartsProps = { /** When false, shows an empty state (feature gate). @default true */ featureEnabled?: boolean /** Message when `featureEnabled` is false */ disabledMessage?: string /** Options for the combination selector */ combinations: ContainerChar… ``` ### `ContainerControlsBoxProps` ```typescript type ContainerControlsBoxProps = { data?: Device isBatch?: boolean isCompact?: boolean // --- data from outside (no API calls inside) --- selectedDevices?: Device[] pendingSubmissions?: PendingSubmission[] alarmsDataItems?: TimelineItemData[] tailLogData?: UnknownRecord[]… ``` ### `ContainerDetailPlaceholderProps` ```typescript type ContainerDetailPlaceholderProps = { /** Human label of the tab this placeholder stands in for, e.g. "PDU Layout". */ label: string } ``` ### `ContainerDetailProps` ```typescript type ContainerDetailProps = { /** * Container display name shown in the header. Optional — omit it when the * host already renders the container name as the page title (e.g. the shell's * `PageLayout`), so the name is not shown twice. */ name?: ReactNode /** Ordered… ``` ### `ContainerDetailTab` A single tab in the container detail strip. ```typescript type ContainerDetailTab = { /** Route segment / Radix value, e.g. `"home"`, `"pdu"`. */ key: string /** Human label, e.g. `"PDU Layout"`. */ label: string } ``` ### `ContainerInfo` ```typescript type ContainerInfo = { container: string type?: string rack?: string nominalMinerCapacity?: string cooling_system: Record cdu: Record primary_supply_temp: number second_supply_temp1: number second_supply_temp2: number supply_l… ``` ### `ContainerLast` ```typescript type ContainerLast = { snap: { stats?: Partial } alerts: unknown[] | null err: string | null } ``` ### `ContainerPduData` ```typescript type ContainerPduData = { power_w: number status: number } ``` ### `ContainerPosInfo` ```typescript type ContainerPosInfo = { containerInfo: Partial pdu: string | number socket: string | number pos: string [key: string]: unknown } ``` ### `ContainerSnap` ```typescript type ContainerSnap = { stats?: Partial config?: Record } ``` ### `ContainerSpecific` ```typescript type ContainerSpecific = { pdu_data: Partial[] [key: string]: unknown } ``` ### `ContainerStats` ```typescript type ContainerStats = { status: string ambient_temp_c: number humidity_percent: number power_w: number container_specific: Partial distribution_box1_power_w: number distribution_box2_power_w: number stats: Record temperature_… ``` ### `ContainerWidgetCardProps` ```typescript type ContainerWidgetCardProps = { /** Container display name shown in the header row. */ title: string /** Latest container power draw in watts (rendered in kW by the top row). */ power?: number /** Power unit label shown next to the reading. */ powerUnit?: string /** Pe… ``` ### `ContainerWidgetItem` One container's card data plus the stable id used for keys and click routing. ```typescript type ContainerWidgetItem = ContainerWidgetCardProps & { id: string } ``` ### `ContainerWidgetsProps` ```typescript type ContainerWidgetsProps = { /** Card-ready data for every container, shaped by the data hook. */ containers: ContainerWidgetItem[] /** Section heading. */ title?: string /** Shows a spinner while the first load is in flight. */ isLoading?: boolean /** Error message… ``` ### `CostChartsProps` ```typescript type CostChartsProps = { costLog: ReadonlyArray btcPriceLog: ReadonlyArray totals: CostSummaryMonetaryTotals | null dateRange: FinancialDateRange | null avgAllInCostData?: ReadonlyArray isLoadi… ``` ### `CostChromeProps` ```typescript type CostChromeProps = { /** Period selector element. Pass `` for the OSS-style year/month picker. */ controls: ReactElement /** * Optional "Set Monthly Cost" header action slot. * * A `ReactElement` slot (rather than an href string) so consum… ``` ### `CostContentProps` ```typescript type CostContentProps = CostViewModelProps & CostQueryStateProps & { dateRange: FinancialDateRange | null /** Optional revenue/cost time-series for the Avg All-in Cost panel. */ avgAllInCostData?: ReadonlyArray } ``` ### `CostMetricsProps` ```typescript type CostMetricsProps = { metrics: CostSummaryDisplayMetrics } ``` ### `CostProps` ```typescript type CostProps = CostContentProps & CostChromeProps ``` ### `CostQueryStateProps` ```typescript type CostQueryStateProps = { isLoading?: boolean error?: unknown } ``` ### `CostSummaryDisplayMetrics` ```typescript type CostSummaryDisplayMetrics = { allInCost: CostSummaryMetric energyCost: CostSummaryMetric operationsCost: CostSummaryMetric } ``` ### `CostSummaryLogEntry` ```typescript type CostSummaryLogEntry = { ts: number consumptionMWh: number energyCostsUSD: number operationalCostsUSD: number totalCostsUSD: number allInCostPerMWh: number | null energyCostPerMWh: number | null btcPrice: number } ``` ### `CostSummaryMetric` ```typescript type CostSummaryMetric = { label: string unit: string value: number | null isHighlighted?: boolean } ``` ### `CostSummaryMonetaryTotals` ```typescript type CostSummaryMonetaryTotals = { totalEnergyCostsUSD: number totalOperationalCostsUSD: number totalCostsUSD: number totalConsumptionMWh: number } ``` ### `CostSummaryQueryParams` ```typescript type CostSummaryQueryParams = { start: number end: number period: FinancePeriod } ``` ### `CostSummaryQueryResult` ```typescript type CostSummaryQueryResult = { data?: CostSummaryResponse isLoading?: boolean error?: unknown } ``` ### `CostSummaryResponse` ```typescript type CostSummaryResponse = FinanceResponse ``` ### `CostSummaryTotals` ```typescript type CostSummaryTotals = { totalEnergyCostsUSD: number totalOperationalCostsUSD: number totalCostsUSD: number totalConsumptionMWh: number avgAllInCostPerMWh: number | null avgEnergyCostPerMWh: number | null avgBtcPrice: number | null } ``` ### `CostSummaryViewModel` ```typescript type CostSummaryViewModel = { metrics: CostSummaryDisplayMetrics | null costLog: ReadonlyArray btcPriceLog: ReadonlyArray totals: CostSummaryMonetaryTotals | null avgBtcPrice: number | null } ``` ### `CostTimeSeriesEntry` ```typescript type CostTimeSeriesEntry = { ts: number totalCostUSD: number energyCostUSD: number operationalCostUSD: number } ``` ### `CostViewModelProps` Subset of `useCostSummary` output that the Cost composite page needs. Defined as a standalone type so consumers wiring up their own data flow can pass an object of this shape without coupling to the hook's full return. ```typescript type CostViewModelProps = { metrics: CostSummaryDisplayMetrics | null costLog: ReadonlyArray btcPriceLog: ReadonlyArray totals: CostSummaryMonetaryTotals | null } ``` ### `CreateIconOptions` ```typescript type CreateIconOptions = { displayName: string viewBox: string defaultWidth?: number defaultHeight?: number multiColor?: boolean path: ReactNode | ((props: { color: string }) => ReactNode) } ``` ### `CrossThingTypeKey` ```typescript type CrossThingTypeKey = keyof typeof CROSS_THING_TYPES ``` ### `CrossThingTypeValue` ```typescript type CrossThingTypeValue = (typeof CROSS_THING_TYPES)[CrossThingTypeKey] ``` ### `CSVRecord` ```typescript type CSVRecord = { partType?: string; model?: string; parentDeviceModel?: string; serialNum?: string; macAddress?: string; status?: string; location?: string; comment?: string; rackId?: string; [key: string]: unknown; } ``` ### `CurrencyKey` ```typescript type CurrencyKey = keyof typeof CURRENCY ``` ### `CurrencyUnit` ```typescript type CurrencyUnit = ValueUnit & { unit: string } ``` ### `CurrencyValue` ```typescript type CurrencyValue = (typeof CURRENCY)[CurrencyKey] ``` ### `CurrentAlertsProps` ```typescript type CurrentAlertsProps = { /** * Raw devices (with last.alerts) used to derive current alerts from. * Shape mirrors the API response from the source app. */ devices?: Device[][] isLoading?: boolean /** * Filters controlled outside (typically by URL severity param)… ``` ### `CurtailmentResult` ```typescript type CurtailmentResult = { curtailmentMWh: number curtailmentRate: number } ``` ### `DashboardDateRange` ```typescript type DashboardDateRange = { /** Window start, milliseconds since epoch. */ start: number /** Window end, milliseconds since epoch. */ end: number } ``` ### `DashboardDateRangePickerProps` ```typescript type DashboardDateRangePickerProps = { /** Current range as `{ start, end }` epoch-millisecond timestamps. */ value: DashboardDateRange /** Fires with the next `{ start, end }` window when the user applies a range. */ onChange: (next: DashboardDateRange) => void /** Display f… ``` ### `DashboardProps` ```typescript type DashboardProps = { stats?: DashboardStats isStatsLoading?: boolean alerts?: Alert[] onNavigationClick: (url: string) => void onViewAllAlerts: VoidFunction } ``` ### `DashboardStats` ```typescript type DashboardStats = { items: StatItem[] } ``` ### `DataLabelProps` ```typescript type DataLabelProps = Partial<{ /** * Range start; formatted in the active timezone (`dd/MM/yy`). */ startDate: Date | null /** * Range end; formatted in the active timezone (`dd/MM/yy`). */ endDate: Date | null /** * Label text; defaults to `PERIOD`. */ label:… ``` ### `DataTableProps` ```typescript type DataTableProps = { /** * The data to be shown in the table. See https://tanstack.com/table/v8/docs/guide/data */ data: I[] /** * The column configuration table. See https://tanstack.com/table/v8/docs/guide/column-defs */ columns: DataTableColumnDef… ``` ### `DateFormatType` ```typescript type DateFormatType = | typeof DATE_FORMAT | typeof DATE_FORMAT_SLASHED | typeof SHORT_DATE_FORMAT ``` ### `DatePickerProps` ```typescript type DatePickerProps = { /** * Currently selected date */ selected?: Date /** * Callback when date changes */ onSelect?: (date: Date | undefined) => void /** * Placeholder text when no date is selected * @default "Pick a date" */ placeholder?: string /** * Date… ``` ### `DateRange` ```typescript type DateRange = { from: Date | undefined to?: Date | undefined } ``` ### `DateRangeKey` ```typescript type DateRangeKey = keyof typeof DATE_RANGE ``` ### `DateRangePickerProps` ```typescript type DateRangePickerProps = { /** * Selected date range */ selected?: DateRange /** * Callback when date range changes */ onSelect?: (range: DateRange | undefined) => void /** * Placeholder text when no range is selected * @default "Pick a date range" */ placeholder?… ``` ### `DateRangeValue` ```typescript type DateRangeValue = (typeof DATE_RANGE)[DateRangeKey] ``` ### `DateTimeFormatType` ```typescript type DateTimeFormatType = typeof DATE_TIME_FORMAT | typeof DATE_TIME_FORMAT_WITH_SECONDS ``` ### `DetailLegendItem` ```typescript type DetailLegendItem = { /** Legend label text */ label: string /** Color for the legend icon */ color: string /** Custom icon to display (defaults to a colored square) */ icon?: ReactNode /** Current value display */ currentValue?: { value: number | string unit… ``` ### `DetailLegendProps` ```typescript type DetailLegendProps = { /** Legend items to display */ items: DetailLegendItem[] /** Callback when a legend item is toggled */ onToggle?: (label: string, index: number) => void /** Custom class name */ className?: string } ``` ### `Device` ```typescript type Device = { id: string type: string tags?: string[] rack?: string last?: DeviceLast username?: string info?: DeviceInfo containerId?: string address?: string | null code?: string alerts?: Alert[] | null powerMeters?: Device[] tempSensors?: Device[]… ``` ### `DeviceAttributeView` A single labelled device attribute row. ```typescript type DeviceAttributeView = { label: string value: string } ``` ### `DeviceData` ```typescript type DeviceData = { id: string | undefined type: string | undefined tags?: string[] rack?: string snap: ContainerSnap alerts?: Alert[] | null username?: string info?: DeviceInfo containerId?: string address?: string | null err?: string | null [key: string]:… ``` ### `DeviceExplorerDeviceData` ```typescript type DeviceExplorerDeviceData = Device ``` ### `DeviceExplorerDeviceType` ```typescript type DeviceExplorerDeviceType = (typeof DEVICE_EXPLORER_DEVICE_TYPE)[keyof typeof DEVICE_EXPLORER_DEVICE_TYPE] ``` ### `DeviceExplorerFilterOption` ```typescript type DeviceExplorerFilterOption = { value: string label: string children?: DeviceExplorerFilterOption[] } ``` ### `DeviceExplorerProps` ```typescript type DeviceExplorerProps = { deviceType: DeviceExplorerDeviceType className?: string selectedDevices?: DataTableRowSelectionState onSelectedDevicesChange?: (selections: DataTableRowSelectionState) => void } & ForwardedToolbarProps & ForwardedTableProps ``` ### `DeviceExplorerSearchOption` ```typescript type DeviceExplorerSearchOption = { value: string label: string } ``` ### `DeviceInfo` ```typescript type DeviceInfo = { container?: string pos?: string poolConfig?: string serialNum?: string macAddress?: string | null posHistory?: Partial [key: string]: unknown } ``` ### `DeviceLast` ```typescript type DeviceLast = { err?: string | null type?: string snap?: ContainerSnap alerts?: Alert[] | null [key: string]: unknown } ``` ### `DeviceStatus` ```typescript type DeviceStatus = (typeof DEVICE_STATUS)[keyof typeof DEVICE_STATUS] ``` ### `DialogContentProps` ```typescript type DialogContentProps = { title?: string description?: string closeOnClickOutside?: boolean closeOnEscape?: boolean } & DialogHeaderProps ``` ### `DialogHeaderProps` ```typescript type DialogHeaderProps = { bare?: boolean closable?: boolean onClose?: VoidFunction } ``` ### `DisplayMode` ```typescript type DisplayMode = typeof CURRENCY.USD_LABEL | typeof CURRENCY.BTC_LABEL ``` ### `DividerOrientation` ```typescript type DividerOrientation = 'horizontal' | 'vertical' ``` ### `DividerProps` ```typescript type DividerProps = { /** Line orientation */ orientation?: DividerOrientation /** Line style */ dashed?: boolean dotted?: boolean /** Text or node rendered in the middle of the divider */ children?: ReactNode /** Horizontal alignment of the label */ align?:… ``` ### `DividerType` ```typescript type DividerType = 'solid' | 'dashed' | 'dotted' ``` ### `DoughnutChartDataset` ```typescript type DoughnutChartDataset = { label: string value: number color?: string } ``` ### `DoughnutChartProps` ```typescript type DoughnutChartProps = { /** Array of labelled slices */ data: DoughnutChartDataset[] /** Unit suffix shown in tooltips */ unit?: string /** Chart.js options – merged with defaults */ options?: ChartJS<'doughnut'>['options'] /** Doughnut cutout percentage (defau… ``` ### `EbitdaChartsProps` ```typescript type EbitdaChartsProps = { showEbitdaBarChart: boolean ebitdaChartData: BarChartDataResult btcDisplayData: BarChartDataResult isLoading: boolean hasBtcProducedAllZeros: boolean } ``` ### `EbitdaDisplayMetrics` Display metrics for the financial EBITDA reporting surface (foundation). Values mirror Mining OS `Views/Financial/EBITDA/EBITDA.types` `EbitdaMetrics`. ```typescript type EbitdaDisplayMetrics = { bitcoinProductionCost: number bitcoinPrice: number bitcoinProduced: number ebitdaSellingBTC: number actualEbitda: number ebitdaNotSellingBTC: number } ``` ### `EbitdaHodlCardProps` ```typescript type EbitdaHodlCardProps = { value: number currentBTCPrice: number } ``` ### `EbitdaLogEntry` ```typescript type EbitdaLogEntry = { ts: number revenueBTC: number revenueUSD: number btcPrice: number powerW: number hashrateMhs: number consumptionMWh: number energyCostsUSD: number operationalCostsUSD: number totalCostsUSD: number ebitdaSelling: number ebitdaHodl: number… ``` ### `EbitdaMetricsProps` ```typescript type EbitdaMetricsProps = { metrics: EbitdaDisplayMetrics currentBTCPrice: number } ``` ### `EbitdaProps` ```typescript type EbitdaProps = { metrics: EbitdaDisplayMetrics | null ebitdaChartInput: ToBarChartDataInput | null btcProducedChartInput: ToBarChartDataInput | null hasBtcProducedAllZeros: boolean showEbitdaBarChart: boolean currentBTCPrice: number datePicker: ReactElem… ``` ### `EbitdaQueryParams` ```typescript type EbitdaQueryParams = { start: number end: number period: FinancePeriod } ``` ### `EbitdaResponse` ```typescript type EbitdaResponse = FinanceResponse ``` ### `EbitdaSellingCardProps` ```typescript type EbitdaSellingCardProps = { value: number } ``` ### `EbitdaTotals` ```typescript type EbitdaTotals = { totalRevenueBTC: number totalRevenueUSD: number totalCostsUSD: number totalEbitdaSelling: number totalEbitdaHodl: number avgBtcProductionCost: number | null currentBtcPrice: number } ``` ### `EbitdaViewModel` ```typescript type EbitdaViewModel = { metrics: EbitdaDisplayMetrics | null ebitdaChartInput: ToBarChartDataInput | null btcProducedChartInput: ToBarChartDataInput | null hasBtcProducedAllZeros: boolean currentBTCPrice: number /** When false, hide the EBITDA bar group (Mining… ``` ### `EfficiencyDateRange` ```typescript type EfficiencyDateRange = { start: number; end: number } ``` ### `EfficiencyMinerTypeTailLog` ```typescript type EfficiencyMinerTypeTailLog = Record ``` ### `EfficiencyMinerTypeViewProps` ```typescript type EfficiencyMinerTypeViewProps = Omit ``` ### `EfficiencyMinerUnitTailLog` ```typescript type EfficiencyMinerUnitTailLog = Record ``` ### `EfficiencyMinerUnitViewProps` ```typescript type EfficiencyMinerUnitViewProps = Omit ``` ### `EfficiencySiteViewProps` ```typescript type EfficiencySiteViewProps = { log?: MetricsEfficiencyLogEntry[] avgEfficiency?: number | null nominalValue?: number | null isLoading?: boolean dateRange?: EfficiencyDateRange onDateRangeChange?: (range: EfficiencyDateRange) => void onReset?: VoidFunction } ``` ### `EfficiencyTabValue` ```typescript type EfficiencyTabValue = (typeof EfficiencyTabTypes)[keyof typeof EfficiencyTabTypes] ``` ### `EmptyStateImage` ```typescript type EmptyStateImage = 'default' | 'simple' | ReactNode ``` ### `EmptyStateProps` ```typescript type EmptyStateProps = { /** * Description text or ReactNode displayed below the image */ description: ReactNode /** * Image to display. Use "default" for the standard illustration, * "simple" for a minimal icon, or pass a custom ReactNode. * @default "default"… ``` ### `EmptyStateSize` ```typescript type EmptyStateSize = ComponentSize ``` ### `EnabledDisableToggleProps` ```typescript type EnabledDisableToggleProps = { value: unknown tankNumber: number | string isButtonDisabled: boolean isOffline: boolean onToggle: (params: EnabledDisableToggleCbParams) => void } ``` ### `EnergyBalanceCostChartsProps` ```typescript type EnergyBalanceCostChartsProps = { costChartData: BarChartDataResult btcUnit: EnergyCostChartInput['btcUnit'] powerChartInput: ThresholdLineChartInput displayMode: DisplayMode barLabelFormatter: (v: number) => string onDisplayModeChange: (mode: DisplayMode) => void /** Sh… ``` ### `EnergyBalanceCostMetricsProps` ```typescript type EnergyBalanceCostMetricsProps = { metrics: EnergyCostMetrics } ``` ### `EnergyBalanceData` ```typescript type EnergyBalanceData = { revenueMetrics: EnergyRevenueMetrics | null costMetrics: EnergyCostMetrics | null energyRevenueChartInput: ThresholdBarChartInput averageDowntimeData: AverageDowntimeChartData powerChartInput: ThresholdLineChartInput powerChartCostInput:… ``` ### `EnergyBalanceLogEntry` ```typescript type EnergyBalanceLogEntry = { ts: number powerW: number consumptionMWh: number revenueBTC: number revenueUSD: number btcPrice: number energyCostUSD: number totalCostUSD: number energyRevenuePerMWh: number | null allInCostPerMWh: number | null profitUSD: number curtai… ``` ### `EnergyBalancePowerChartProps` ```typescript type EnergyBalancePowerChartProps = { height?: number fillHeight?: boolean periodType: PeriodType chartInput: ThresholdLineChartInput } ``` ### `EnergyBalanceProps` ```typescript type EnergyBalanceProps = { viewModel: EnergyBalanceViewModel onTabChange: (tab: EnergyBalanceTab) => void onRevenueDisplayModeChange: (mode: DisplayMode) => void onCostDisplayModeChange: (mode: DisplayMode) => void isDemoMode?: boolean /** Slot for timeframe / dat… ``` ### `EnergyBalanceQueryParams` ```typescript type EnergyBalanceQueryParams = { start: number end: number period: FinancePeriod } ``` ### `EnergyBalanceResponse` ```typescript type EnergyBalanceResponse = FinanceResponse ``` ### `EnergyBalanceRevenueChartsProps` ```typescript type EnergyBalanceRevenueChartsProps = { revenueChartData: BarChartDataResult averageDowntimeData: AverageDowntimeChartData powerChartInput: ThresholdLineChartInput displayMode: DisplayMode barLabelFormatter: (v: number) => string onDisplayModeChange: (mode: DisplayMode) => voi… ``` ### `EnergyBalanceRevenueMetricsProps` ```typescript type EnergyBalanceRevenueMetricsProps = { metrics: EnergyRevenueMetrics } ``` ### `EnergyBalanceTab` ```typescript type EnergyBalanceTab = 'revenue' | 'cost' ``` ### `EnergyBalanceTotals` ```typescript type EnergyBalanceTotals = { totalRevenueBTC: number totalRevenueUSD: number totalCostUSD: number totalProfitUSD: number avgCostPerMWh: number | null avgRevenuePerMWh: number | null totalConsumptionMWh: number avgCurtailmentRate: number | null avgOperationalIssuesRa… ``` ### `EnergyBalanceViewModel` ```typescript type EnergyBalanceViewModel = EnergyBalanceData & { activeTab: EnergyBalanceTab revenueDisplayMode: DisplayMode costDisplayMode: DisplayMode isLoading: boolean errors: string[] hasDateSelection: boolean } ``` ### `EnergyCostChartInput` ```typescript type EnergyCostChartInput = ThresholdBarChartInput & { btcUnit: string | null } ``` ### `EnergyCostChartProps` ```typescript type EnergyCostChartProps = { chartData: BarChartDataResult btcUnit: EnergyCostChartInput['btcUnit'] displayMode: DisplayMode barLabelFormatter: (v: number) => string onDisplayModeChange: (mode: DisplayMode) => void height?: number } ``` ### `EnergyCostMetrics` ```typescript type EnergyCostMetrics = { avgPowerConsumption: number avgEnergyCost: number avgAllInCost: number avgPowerAvailability: number avgOperationsCost: number avgEnergyRevenue: number } ``` ### `EnergyMetricCardProps` ```typescript type EnergyMetricCardProps = { name: string value: number unit: string fallback?: string } ``` ### `EnergyReportBarChartLegacy` ```typescript type EnergyReportBarChartLegacy = { labels: string[] dataSet1: { label: string; data: number[] } } ``` ### `EnergyReportBarViewProps` ```typescript type EnergyReportBarViewProps = { title: string isEmpty?: boolean isLoading?: boolean chartInput?: ToBarChartDataInput onTimeFrameChange?: (start: Date, end: Date) => void } ``` ### `EnergyReportContainer` ```typescript type EnergyReportContainer = Container & { containerId?: string minersCount?: number } ``` ### `EnergyReportDateRange` ```typescript type EnergyReportDateRange = { start: number; end: number } ``` ### `EnergyReportGroupedBarViewProps` ```typescript type EnergyReportGroupedBarViewProps = { isLoading?: boolean containers?: Container[] groupedConsumption?: MetricsConsumptionGroupedResponse onTimeFrameChange?: EnergyReportBarViewProps['onTimeFrameChange'] } ``` ### `EnergyReportMinerSliceConfig` ```typescript type EnergyReportMinerSliceConfig = { title: string groupBy: MetricsConsumptionGroupBy filterCategory?: (category: string) => boolean getLabelName: (category: string, containers?: Container[]) => string } ``` ### `EnergyReportMinerTypeViewProps` ```typescript type EnergyReportMinerTypeViewProps = EnergyReportGroupedBarViewProps ``` ### `EnergyReportMinerUnitViewProps` ```typescript type EnergyReportMinerUnitViewProps = EnergyReportGroupedBarViewProps ``` ### `EnergyReportMinerViewSlice` ```typescript type EnergyReportMinerViewSlice = (typeof ENERGY_REPORT_MINER_VIEW_SLICES)[keyof typeof ENERGY_REPORT_MINER_VIEW_SLICES] ``` ### `EnergyReportProps` ```typescript type EnergyReportProps = { defaultTab?: EnergyReportTabValue siteView?: Omit & { dateRange?: EnergyReportDateRange } minerTypeView?: EnergyReportMinerTypeViewProps minerUnitView?: EnergyReportMinerUnitViewProps className?: s… ``` ### `EnergyReportSiteViewProps` ```typescript type EnergyReportSiteViewProps = Omit & { snapshotLoading?: boolean onRefetchSnapshot?: VoidFunction dateRange: EnergyReportDateRange onDateRangeChange?: (range: EnergyReportDateRange) => void } ``` ### `EnergyReportTabValue` ```typescript type EnergyReportTabValue = (typeof ENERGY_REPORT_TAB_TYPES)[keyof typeof ENERGY_REPORT_TAB_TYPES] ``` ### `EnergyReportTailLogItem` ```typescript type EnergyReportTailLogItem = Record< string, EnergyReportTailLogNumericBucket | number | undefined > ``` ### `EnergyReportTailLogNumericBucket` ```typescript type EnergyReportTailLogNumericBucket = Record ``` ### `EnergyRevenueChartProps` ```typescript type EnergyRevenueChartProps = { chartData: BarChartDataResult displayMode: DisplayMode barLabelFormatter: (v: number) => string onDisplayModeChange: (mode: DisplayMode) => void height?: number } ``` ### `EnergyRevenueMetrics` ```typescript type EnergyRevenueMetrics = { curtailmentRate: number operationalIssuesRate: number } ``` ### `EntryData` ```typescript type EntryData = { [key: string]: number | null | undefined } ``` ### `ErrorBoundaryProps` ```typescript type ErrorBoundaryProps = { /** * Fallback UI to render when an error is caught. * If not provided, a default error panel with expandable stack trace is shown. */ fallback?: ReactNode /** * Name of the wrapped component (shown in the default fallback) */ componentN… ``` ### `ErrorCardProps` ```typescript type ErrorCardProps = { /** * Error message string. Supports `\n` for line breaks. */ error: string /** * Title displayed above the error message * @default "Errors" */ title?: string /** * Display variant. "card" shows a bordered container, "inline" shows flat… ``` ### `ErrorCardVariant` ```typescript type ErrorCardVariant = 'card' | 'inline' ``` ### `ErrorWithTimestamp` ```typescript type ErrorWithTimestamp = { msg?: string message?: string timestamp?: number | string } ``` ### `ExplorerDetailProps` ```typescript type ExplorerDetailProps = { /** The active Explorer tab — selects which per-type panel renders. */ deviceType: DeviceExplorerDeviceType /** Router navigate used by alarm rows to deep-link into `/alerts/:id`. */ onNavigate?: (path: string) => void /** Compact layout… ``` ### `ExplorerLayoutProps` ```typescript type ExplorerLayoutProps = { /** Page heading. */ title?: string /** Optional header controls (export button, etc.) shown next to the title. */ headerActions?: ReactNode /** The list column — typically a tab switch plus the device/container table. */ list: ReactNode… ``` ### `ExplorerRowSelection` Row-selection map from `<DeviceExplorer>` — thing id → selected. ```typescript type ExplorerRowSelection = Record ``` ### `ExplorerThingDetailRow` ```typescript type ExplorerThingDetailRow = { label: string value: string } ``` ### `ExportButtonProps` ```typescript type ExportButtonProps = { /** Fires with the chosen format when the user picks an item. */ onExport: (format: ExportFormat) => void /** Formats to offer in the dropdown — defaults to `['csv', 'json']`. */ formats?: readonly ExportFormat[] /** Button label — defau… ``` ### `ExportFormat` ```typescript type ExportFormat = 'csv' | 'json' ``` ### `ExtraTooltipData` ```typescript type ExtraTooltipData = Record ``` ### `FeatureFlagsSettingsProps` ```typescript type FeatureFlagsSettingsProps = { featureFlags: Record isEditingEnabled: boolean isLoading?: boolean isSaving?: boolean onSave: (flags: Record) => void className?: string } ``` ### `FieldName` Extract field names from a form schema with type safety. Useful for creating type-safe field name constants. ```typescript type FieldName = FieldPath ``` ### `FilterSelectionTuple` ```typescript type FilterSelectionTuple = CascaderValue ``` ### `FinancePeriod` Finance v2 API types - shapes returned by `/auth/finance/*` endpoints. These are the contracts consumers feed back through the reporting-tool base hooks (`useEbitda`, `useEnergyBalance`, ...). The mdk hooks accept `{ data, isLoading, error }` where `data` matches the *Response types declared here. Foundation does not own the RTK Query / HTTP layer itself - see api-integration-todo.md. ```typescript type FinancePeriod = 'daily' | 'weekly' | 'monthly' | 'yearly' ``` ### `FinanceQueryParams` ```typescript type FinanceQueryParams = { start: number end: number period?: FinancePeriod overwriteCache?: boolean } ``` ### `FinanceResponse` ```typescript type FinanceResponse = { log: Log[] summary: Summary } ``` ### `FinanceRevenueLogEntry` ```typescript type FinanceRevenueLogEntry = { ts: number revenueBTC: number feesBTC: number netRevenueBTC: number } ``` ### `FinanceRevenueQueryParams` ```typescript type FinanceRevenueQueryParams = FinanceQueryParams & { pool?: string } ``` ### `FinanceRevenueResponse` ```typescript type FinanceRevenueResponse = FinanceResponse ``` ### `FinanceRevenueTotals` ```typescript type FinanceRevenueTotals = { totalRevenueBTC: number totalFeesBTC: number totalNetRevenueBTC: number } ``` ### `FinancialDateRange` ```typescript type FinancialDateRange = { start: number end: number period?: PeriodValue } ``` ### `FinancialRangeChangeOptions` ```typescript type FinancialRangeChangeOptions = { year?: number month?: number period?: PeriodValue } ``` ### `FlexAlign` Flex/Grid alignment options Used by Popover, charts, and layout components ```typescript type FlexAlign = 'start' | 'center' | 'end' ``` ### `FormatHashBalanceValueOptions` ```typescript type FormatHashBalanceValueOptions = { forAxis?: boolean } ``` ### `FormCascaderProps` ```typescript type FormCascaderProps = BaseFormFieldProps & { options: CascaderOption[] multiple?: boolean cascaderProps?: Omit< React.ComponentProps, 'value' | 'onChange' | 'options' | 'placeholder' > } ``` ### `FormCheckboxProps` ```typescript type FormCheckboxProps = BaseFormFieldProps & { checkboxProps?: React.ComponentProps layout?: 'row' | 'column' } ``` ### `FormDatePickerProps` ```typescript type FormDatePickerProps = BaseFormFieldProps & { datePickerProps?: Omit, 'selected' | 'onSelect'> } ``` ### `FormInputProps` ```typescript type FormInputProps = BaseFormFieldProps & { type?: React.ComponentProps['type'] variant?: React.ComponentProps['variant'] inputProps?: Omit, 'type' | 'variant'> } ``` ### `FormProps` Form wrapper that provides react-hook-form context to child components. ```typescript type FormProps = Omit< ComponentProps<'form'>, 'children' > & { form: UseFormReturn children: ReactNode } ``` ### `FormRadioGroupProps` ```typescript type FormRadioGroupProps = BaseFormFieldProps & { options: FormRadioOption[] orientation?: 'horizontal' | 'vertical' radioGroupProps?: Omit< React.ComponentProps, 'onValueChange' | 'defaultValue' | 'orientation' > } ``` ### `FormRadioOption` ```typescript type FormRadioOption = { value: string label: string disabled?: boolean } ``` ### `FormSelectOption` ```typescript type FormSelectOption = { value: string label: string disabled?: boolean } ``` ### `FormSelectProps` ```typescript type FormSelectProps = BaseFormFieldProps & { options: FormSelectOption[] selectProps?: Omit, 'onValueChange' | 'defaultValue'> } ``` ### `FormSwitchProps` ```typescript type FormSwitchProps = BaseFormFieldProps & { switchProps?: Omit, 'checked' | 'onCheckedChange'> layout?: 'row' | 'column' } ``` ### `FormTagInputProps` ```typescript type FormTagInputProps = BaseFormFieldProps & { options?: TagInputOption[] allowCustomTags?: boolean variant?: 'default' | 'search' tagInputProps?: Omit< React.ComponentProps, 'value' | 'onTagsChange' | 'label' | 'placeholder'… ``` ### `FormTextAreaProps` ```typescript type FormTextAreaProps = BaseFormFieldProps & { textAreaProps?: React.ComponentProps } ``` ### `GaugeChartProps` ```typescript type GaugeChartProps = { /** Value between 0 and 1 (e.g. 0.75 = 75%). Values outside the range are clamped. */ percent: number /** Arc colours in HEX format. */ colors?: string[] /** Arc thickness as a fraction of the gauge radius (0–1). */ arcWidth?: number /**… ``` ### `GetAlertsTableColumnsOptions` ```typescript type GetAlertsTableColumnsOptions = { getFormattedDate: (date: Date) => string } ``` ### `GetColumnConfigParams` ```typescript type GetColumnConfigParams = { getFormattedDate: (date: Date) => string renderAction: (device: DeviceExplorerDeviceData) => React.ReactNode } ``` ### `GlobalConfig` ```typescript type GlobalConfig = { nominalSiteHashrate_MHS?: number nominalAvailablePowerMWh?: number nominalPowerConsumption_MW?: number nominalWeightedAvgEfficiency_WThs?: number nominalMinerCapacity?: number isAutoSleepAllowed?: boolean siteEnergyDataThresholdMWh?: num… ``` ### `HashBalanceCostPanelProps` ```typescript type HashBalanceCostPanelProps = HashBalancePanelProps ``` ### `HashBalanceCurrency` ```typescript type HashBalanceCurrency = typeof CURRENCY.USD_LABEL | typeof CURRENCY.BTC_LABEL ``` ### `HashBalanceMetric` ```typescript type HashBalanceMetric = { label: string unit: string value: number isHighlighted?: boolean } ``` ### `HashBalancePanelProps` ```typescript type HashBalancePanelProps = Pick< UseHashBalanceInput, 'data' | 'log' | 'dateRange' | 'timeframeType' > & { isLoading?: boolean } ``` ### `HashBalanceProps` ```typescript type HashBalanceProps = Partial<{ isError: boolean isLoading: boolean errorMessage: string className: string tabsClassName: string tabsListClassName: string data: HashRevenueResponse | null initialDateRange: FinancialDateRange onDateRangeChange: (dateRange: Finan… ``` ### `HashBalanceRevenuePanelProps` ```typescript type HashBalanceRevenuePanelProps = HashBalancePanelProps & { currency: HashBalanceCurrency onCurrencyChange: (currency: HashBalanceCurrency) => void } ``` ### `HashrateBarChartData` ```typescript type HashrateBarChartData = { labels: string[] series: { label: string values: number[] color: string }[] } ``` ### `HashrateDateRange` ```typescript type HashrateDateRange = { start: number; end: number } ``` ### `HashrateFilterOption` ```typescript type HashrateFilterOption = { value: string label: string } ``` ### `HashrateGroupBy` groupBy axis for the v2 grouped hashrate endpoint. - `miner` returns one bucket per miner-type id. - `container` returns one bucket per container id (plus rollup keys that the utils layer filters out - see `getCleanGroupedEntries`). ```typescript type HashrateGroupBy = 'miner' | 'container' ``` ### `HashrateGroupedLog` ```typescript type HashrateGroupedLog = ReadonlyArray ``` ### `HashrateGroupedLogEntry` Single bucket of a v2 `/auth/metrics/hashrate` grouped response. `hashrateMhs` keys are either miner-type ids (`groupBy=miner`) or container ids (`groupBy=container`) depending on which response the consumer fetched. Values are in MH/s; the view layer converts to TH/s for display. ```typescript type HashrateGroupedLogEntry = { ts: number hashrateMhs: Record } ``` ### `HashrateGroupedQueryData` ```typescript type HashrateGroupedQueryData = { log?: HashrateGroupedLog } ``` ### `HashrateLabelDivisorKey` ```typescript type HashrateLabelDivisorKey = keyof typeof HASHRATE_LABEL_DIVISOR ``` ### `HashrateLabelDivisorValue` ```typescript type HashrateLabelDivisorValue = (typeof HASHRATE_LABEL_DIVISOR)[HashrateLabelDivisorKey] ``` ### `HashrateMinerTypeViewProps` ```typescript type HashrateMinerTypeViewProps = { /** Hashrate log grouped by miner type (groupBy=miner). */ log?: HashrateGroupedLog isLoading?: boolean dateRange?: HashrateDateRange onDateRangeChange?: (range: HashrateDateRange) => void onReset?: VoidFunction } ``` ### `HashrateMiningUnitViewProps` ```typescript type HashrateMiningUnitViewProps = { /** Hashrate log grouped by container / mining unit (groupBy=container). */ log?: HashrateGroupedLog isLoading?: boolean dateRange?: HashrateDateRange onDateRangeChange?: (range: HashrateDateRange) => void onReset?: VoidFunction } ``` ### `HashrateProps` ```typescript type HashrateProps = { /** Tab selected on first render. Defaults to the Site View. */ defaultTab?: HashrateTabValue /** Props forwarded to the Site View tab. */ siteView?: HashrateSiteViewProps /** Props forwarded to the Miner Type View tab. */ minerTypeView?… ``` ### `HashrateQueryState` ```typescript type HashrateQueryState = { data?: HashrateGroupedQueryData isLoading?: boolean error?: unknown } ``` ### `HashrateSeries` ```typescript type HashrateSeries = { label: string color?: string points: HashrateSeriesPoint[] } ``` ### `HashrateSeriesPoint` ```typescript type HashrateSeriesPoint = { ts: string value: number } ``` ### `HashrateSiteViewChartData` ```typescript type HashrateSiteViewChartData = { series: HashrateSeries[] } ``` ### `HashrateSiteViewProps` ```typescript type HashrateSiteViewProps = { /** Hashrate log grouped by miner type. */ log?: HashrateGroupedLog /** Loading state - drives the chart spinner. */ isLoading?: boolean /** Selected date range used by the host to drive the query. */ dateRange?: HashrateDateRange /** Fi… ``` ### `HashrateTabValue` ```typescript type HashrateTabValue = (typeof HashrateTabTypes)[keyof typeof HashrateTabTypes] ``` ### `HashrateUnit` ```typescript type HashrateUnit = ValueUnit & { unit: string } ``` ### `HashRevenueLogEntry` ```typescript type HashRevenueLogEntry = { ts: number revenueBTC: number feesBTC: number revenueUSD: number feesUSD: number btcPrice: number hashrateMhs: number hashRevenueBTCPerPHsPerDay: number | null hashRevenueUSDPerPHsPerDay: number | null hashCostBTCPerPHsPerDay: number | n… ``` ### `HashRevenueResponse` ```typescript type HashRevenueResponse = FinanceResponse ``` ### `HashRevenueTotals` ```typescript type HashRevenueTotals = { avgHashRevenueBTCPerPHsPerDay: number | null avgHashRevenueUSDPerPHsPerDay: number | null avgHashCostBTCPerPHsPerDay: number | null avgHashCostUSDPerPHsPerDay: number | null avgNetworkHashPriceBTCPerPHsPerDay: number | null avgNetworkHas… ``` ### `HeaderConsumptionBoxProps` ```typescript type HeaderConsumptionBoxProps = { icon?: ReactNode /** Current site-level power consumption, in megawatts. */ valueMw?: number /** Unit label — defaults to `MW`. */ unit?: string className?: string } ``` ### `HeaderControlsSettingsProps` ```typescript type HeaderControlsSettingsProps = { preferences: HeaderPreferences isLoading?: boolean onToggle: (key: keyof HeaderPreferences, value: boolean) => void onReset: VoidFunction className?: string } ``` ### `HeaderEfficiencyBoxProps` ```typescript type HeaderEfficiencyBoxProps = { icon?: ReactNode /** Efficiency in watts per TH/s. */ valueWthS?: number /** Unit label — defaults to `W/TH/S`. */ unit?: string className?: string } ``` ### `HeaderHashrateBoxProps` ```typescript type HeaderHashrateBoxProps = { icon?: ReactNode /** MOS-side aggregate hashrate in PH/s. */ mosPhs?: number /** Pool-side aggregate hashrate in PH/s. */ poolPhs?: number /** Hashrate unit label — defaults to `PH/s`. */ unit?: string className?: string } ``` ### `HeaderMinersBoxProps` ```typescript type HeaderMinersBoxProps = { /** Icon shown next to the "Miners" label. Caller-provided so the package stays icon-agnostic. */ icon?: ReactNode /** Total miners across the site (denominator of the `158 / 2,188` ratio). */ total?: number /** Online miners (the `158`… ``` ### `HeaderPreferences` ```typescript type HeaderPreferences = { poolMiners: boolean mosMiners: boolean poolHashrate: boolean mosHashrate: boolean consumption: boolean efficiency: boolean } ``` ### `HeaderStatsBarProps` ```typescript type HeaderStatsBarProps = { /** Stat boxes to render in order, left-to-right. */ children: ReactNode /** Optional class hook. */ className?: string } ``` ### `HeatmapCell` A single heatmap cell. ```typescript type HeatmapCell = { /** Numeric value driving the cell colour; `null` renders the empty colour. */ value: number | null /** Text shown in the cell (defaults to the value when `showValues` is on). */ label?: string /** Stable React key (defaults to the row/c… ``` ### `HeatmapCellContext` Context handed to `renderCell` for a single cell. ```typescript type HeatmapCellContext = { /** The colour resolved for this cell from the gradient (or the empty colour). */ color: string /** Zero-based row index. */ row: number /** Zero-based column index. */ col: number } ``` ### `HeatmapKey` ```typescript type HeatmapKey = keyof typeof HEATMAP ``` ### `HeatmapLegendProps` ```typescript type HeatmapLegendProps = { /** Value (or pre-formatted label) at the low end of the scale. */ min: number | string /** Value (or pre-formatted label) at the high end of the scale. */ max: number | string /** Unit suffix appended to `min`/`max`. */ unit?: string /*… ``` ### `HeatmapModeKey` ```typescript type HeatmapModeKey = keyof typeof HEATMAP_MODE ``` ### `HeatmapModeValue` ```typescript type HeatmapModeValue = (typeof HEATMAP_MODE)[HeatmapModeKey] ``` ### `HeatmapProps` ```typescript type HeatmapProps = { /** Rows of cells (row-major). Rows may be ragged. */ data: HeatmapCell[][] /** Range floor; auto-derived from the finite values when omitted. */ min?: number /** Range ceiling; auto-derived from the finite values when omitted. */ max?:… ``` ### `HighlightedValueProps` ```typescript type HighlightedValueProps = { value: string | number unit?: string className?: string style?: CSSProperties } ``` ### `HistoricalAlertsProps` ```typescript type HistoricalAlertsProps = { /** * Pre-fetched historical alerts log entries (each with a `thing` device payload). */ alerts?: Alert[] isLoading?: boolean /** * Filters and search tags coming from the parent (typically shared with `CurrentAlerts`). */ localFilters:… ``` ### `HistoricalAlertsRange` ```typescript type HistoricalAlertsRange = { start: number end: number } ``` ### `IconProps` ```typescript type IconProps = { /** Sets both width and height */ size?: number | string /** Only affects single-color icons (default: 'currentColor') */ color?: string children?: never } & SVGAttributes ``` ### `ImportExportSettingsProps` ```typescript type ImportExportSettingsProps = { onExport: VoidFunction onImport: (data: SettingsExportData) => void onParseFile?: (file: File) => Promise isExporting?: boolean isImporting?: boolean className?: string } ``` ### `IndicatorColor` ```typescript type IndicatorColor = | 'red' | 'gray' | 'blue' | 'yellow' | 'green' | 'purple' | 'amber' | 'slate' ``` ### `IndicatorProps` ```typescript type IndicatorProps = { /** * Color variant of the indicator * @default 'gray' */ color?: IndicatorColor /** * Size variant of the indicator * @default 'md' */ size?: ComponentSize /** * Custom className for the root element */ className?: string /** * When tru… ``` ### `InputProps` ```typescript type InputProps = Omit, 'prefix' | 'size'> & { /** * Optional label displayed above the input */ label?: string /** * HTML id for the input. Required when using label for accessibility. */ id?: string /** * Variant of the input * - `… ``` ### `InputSize` ```typescript type InputSize = 'default' | 'medium' ``` ### `LabeledCardNavigateOptions` ```typescript type LabeledCardNavigateOptions = Partial<{ href: string target: string }> ``` ### `LabeledCardProps` ```typescript type LabeledCardProps = Partial<{ isDark: boolean className: string hasNoWrap: boolean isRelative: boolean isFullWidth: boolean hasNoMargin: boolean hasNoBorder: boolean isFullHeight: boolean isScrollable: boolean label: ReactNode children: ReactNode getNavigateO… ``` ### `LabelToIgnoreValue` ```typescript type LabelToIgnoreValue = (typeof LABEL_TO_IGNORE)[number] ``` ### `LegendItem` ```typescript type LegendItem = { label: string color: string hidden?: boolean } ``` ### `LightWeightLineChartProps` ```typescript type LightWeightLineChartProps = { /** * Mutable ref to hold the LightWeightCharts reference */ chartRef?: MutableRefObject /** * Data of the chart */ data: LineChartData /** * Callback to format ticks on y axis. If `priceFormatter` is given. It would be… ``` ### `LineChartCardData` ```typescript type LineChartCardData = { /** Chart datasets */ datasets: LineChartCardDataset[] } & Partial<{ /** Y-axis tick formatter */ yTicksFormatter: (value: number) => string /** Price formatter for lightweight-charts */ priceFormatter: (value: number) => string /** Whet… ``` ### `LineChartCardDataset` ```typescript type LineChartCardDataset = { /** Label for the dataset (used in legend) */ label?: string /** Line color */ borderColor: string /** Data points */ data: Array<{ x: number; y: number | null }> /** Whether this dataset is visible */ visible?: boolean /** Custom icon f… ``` ### `LineChartCardProps` ```typescript type LineChartCardProps = Partial<{ /** Pre-adapted chart data (use this OR rawData+dataAdapter) */ data: LineChartCardData /** Raw data to be transformed by dataAdapter */ rawData: unknown /** Adapter to transform rawData into LineChartCardData */ dataAdapter: (da… ``` ### `LineChartData` ```typescript type LineChartData = { datasets: LineDataset[] } ``` ### `LineDataPoint` ```typescript type LineDataPoint = { x: number; y: number | null | undefined } ``` ### `LineDataset` ```typescript type LineDataset = { label?: string visible?: boolean borderColor: string borderWidth?: number extraTooltipData?: ExtraTooltipData data: LineDataPoint[] } ``` ### `LineSeriesApi` ```typescript type LineSeriesApi = ISeriesApi<'Line', Time> ``` ### `LoaderProps` ```typescript type LoaderProps = { /** * Size of each dot in pixels * @default 10 */ size?: number /** * Number of dots to display * @default 5 */ count?: 3 | 5 | 7 /** * Color variant of the loader * @default 'orange' */ color?: 'red' | 'gray' | 'blue' | 'amber' | 'orang… ``` ### `LocalFilters` ```typescript type LocalFilters = Record ``` ### `LogActivityIconProps` ```typescript type LogActivityIconProps = { status: string } ``` ### `LogData` ```typescript type LogData = { uuid: string body: string title: string status: string subtitle: string } ``` ### `LogDotProps` ```typescript type LogDotProps = { type: string status: string } ``` ### `LogFormattedAlertData` ```typescript type LogFormattedAlertData = { title: string subtitle: string status: string severityLevel: number creationDate: number | string body: string id: string uuid?: string [key: string]: unknown } ``` ### `LogItemProps` ```typescript type LogItemProps = { data: LogData onLogClicked?: (uuid: string) => void } ``` ### `LogPagination` ```typescript type LogPagination = { current: number total: number pageSize: number handlePaginationChange: (page: number) => void } ``` ### `LogRowProps` ```typescript type LogRowProps = { log: LogData type: string style?: CSSProperties onLogClicked?: (uuid: string) => void } ``` ### `LogsCardProps` ```typescript type LogsCardProps = Partial<{ type: string label: string isDark: boolean isLoading: boolean logsData: LogData[] emptyMessage: string skeletonRows: number pagination: LogPagination onLogClicked: (uuid: string) => void }> ``` ### `LvCabinetRecord` ```typescript type LvCabinetRecord = { id: string powerMeters?: PowerMeter[] } ``` ### `ManageUserModalProps` ```typescript type ManageUserModalProps = { open: boolean onClose: VoidFunction user: SettingsUser roles: RoleOption[] rolePermissions: Record> permissionLabels: Record onSubmit: (data: { id: string; name: string; email: string; ro… ``` ### `MaxUnitValueKey` ```typescript type MaxUnitValueKey = keyof typeof MAX_UNIT_VALUE ``` ### `MaxUnitValueValue` ```typescript type MaxUnitValueValue = (typeof MAX_UNIT_VALUE)[MaxUnitValueKey] ``` ### `Maybe` ```typescript type Maybe = T | null | undefined ``` ### `MdkWordmarkProps` ```typescript type MdkWordmarkProps = { /** Visual size of the wordmark. `sm` ≈ 24px tall, `md` ≈ 32px, `lg` ≈ 64px. */ size?: MdkWordmarkSize /** Optional class hook on the outer `
Foundation
Public, end-to-end but rudimentary]) it1[[Jun–Jul 2026
New release every 2 weeks]] end subgraph lab [Lab testing] p2([Jul 2026
Lab testing
Complete end-to-end, lab only]) it2[[Aug–Oct 2026
New release every 2 weeks]] end subgraph onsite [On site testing] p3([Oct 2026
On site testing
Testing at real sites]) it3[[Nov–Dec 2026
New release every 2 weeks]] end subgraph prod [Production Ready] p4([Dec 2026
Production Ready
Production-ready baseline]) end p1 --> it1 --> p2 --> it2 --> p3 --> it3 --> p4 style foundation fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A style lab fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A style onsite fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A style prod fill:#F7931A,stroke:#1A1A1A,color:#1A1A1A ``` ## Release plan Phase descriptions below focus on the **level of maturity and production-readiness** at each stage. The exact feature scope of each two-week release is decided as we go and is not fixed by this roadmap. ### Foundation *Released end of May 2026.* The first public release is about **visibility, direction, and feedback**. It is intentionally rudimentary: developers can clone it, run an end-to-end example, and get a concrete feel for how MDK fits together. Interfaces are expected to change. The goal is to show where MDK is heading and invite feedback from developers, partners, and early contributors — not to support real workloads. ### Lab testing *Target: end of July 2026.* At this stage MDK is **complete enough to build against end to end**. Developers can run a full workflow and experiment with MDK in their own labs. It is **not stable** — breaking changes are still expected between releases — and it is **not ready for production**. The goal is to validate the end-to-end developer workflow and surface integration gaps before MDK is exposed to real operational conditions. ### On site testing *Target: end of October 2026.* This is the first stage intended for **testing at real sites**. MDK should be stable enough to run on site under real operating conditions, while still being monitored closely. The goal is to validate performance, robustness, deployment workflows, and operational fit in real scenarios. This is not yet a stability commitment — interfaces may still change before production readiness. ### Production Ready *Target: end of December 2026.* This is the first **production-ready** release (`1.0.0`). By this point MDK offers a solid baseline for production deployment, with stable core interfaces, validated workflows, and documentation that supports adoption by operators, integrators, and developers building on top of the platform. From here, standard semver compatibility guarantees apply. # Tutorials (/tutorials) ## New to MDK? Go from stack to dashboard Three short tutorials take you from a running MDK stack to a browser dashboard demo. First you watch the stack run, then you drive it from the CLI, then you launch the demo dashboard on top. Climb straight through, or jump to the rung you need. } className="@max-lg:col-span-1" title={1. Run the stack} href="/tutorials/backend-stack/run" description={ Observe — one command brings up Kernel with a mock device registered } /> } className="@max-lg:col-span-1" title={2. Control from the CLI} href="/tutorials/backend-stack/cli" description={ Interact — drive a running stack from a REPL over IPC } /> } className="@max-lg:col-span-1" title={3. Run a dashboard demo} href="/tutorials/full-stack/dashboard" description={ Demo — run a React dashboard with live charts on the stack } /> ## Get started with your framework } title={React} href="/tutorials/ui/react" description={ Pick a path: lean Quickstart, full Tutorial, or browse the component packages } /> } title={Build with your AI agent} href="/quickstart/connect-agents" description={ <> Reactive hooks for Vue } /> ## Next steps - Learn more about the high-level [architecture](/concepts/architecture): runtime stack and deployment modes - Compare [deployment topologies](/concepts/deployment-topologies): single process or supervised services - Run a site from the [deployment guides](/guides/deployment) - [Contribute](/support/community/contributing) # Backend stack tutorials (/tutorials/backend-stack) See the [whole stack demo at once](/tutorials/quickstart/full-stack) booting all the Worker families for a live site, mock hardware, a Gateway API, and a React dashboard in one command. ## Overview This page presents three short tutorials that build on each other. Each rung adds one layer of capability: first you watch the stack run, then you drive it, then you run a browser demo on top. | Rung | You'll | You'll end with | Mock hardware | Time | |---|---|---|---|---| | [1. Run the stack](/tutorials/backend-stack/run) | **Observe** — run one command and watch a stack come up | Device list, telemetry, and commands printed | Whatsminer M56S | `< 3 min` | | [2. Control devices from the CLI](/tutorials/backend-stack/cli) | **Interact** — drive a running stack from a REPL | Live telemetry and commands over HRPC via the kernel key file | Whatsminer M56S | `< 3 min` | | [3. Run the dashboard demo](/tutorials/full-stack/dashboard) | **Run** — launch a browser dashboard on the stack | A React dashboard with live charts at `:3030` | Whatsminer M56S | `< 15 min` after a one-time UI build | **New to MDK? Start with [1. Run the stack](/tutorials/backend-stack/run).** Each rung links to the next, so you can climb straight through. All three rungs use the same Whatsminer example to keep things simple. To see MDK working with different hardware, check out the [full site example](/tutorials/quickstart/full-stack) which runs multiple Worker families (Antminers, Whatsminers, containers, power meters) simultaneously — all using the same MDK API. Each rung is self-contained and repeats the clone-and-install step, so you can start at whichever one you need. ## Next steps - If Kernel, Worker, manager, or thing are unfamiliar, read [`terminology.md`](/reference/glossary) - Build the [smallest version of the full MDK stack: **one Worker, one Gateway route, one static HTML page](/tutorials/quickstart/build-a-dashboard) - Run the [full stack demo](/tutorials/quickstart/full-stack) # 2. Control from CLI (/tutorials/backend-stack/cli) *Get started · 2 of 3 · Control devices from the CLI* If Kernel, Worker, manager, or thing are unfamiliar, read [`terminology.md`](/reference/glossary) first. ## Overview This is rung 2 of the [Get started](/tutorials/backend-stack) ladder: **interact**. It walks the shortest path from a fresh clone to a fully wired MDK stack you can drive interactively from a CLI. Everything runs in one Node process, no real hardware required. What you'll have at the end: - A mock Whatsminer M56S serving telemetry on `127.0.0.1:14028` - An Kernel with one Worker registered and one device discovered - An interactive `client.js` REPL talking to Kernel over HRPC — pull metrics, list Workers, send commands like `reboot` and `setpower` - (Optional) A Gateway HTTP API on `:3000` so non-Node consumers (browsers, AI agents over MCP) can hit the same stack over REST Same shape as [rung 1](/tutorials/backend-stack/run): the stack still boots with `getKernel()`, `startWhatsminerWorker()`, and `kernel.registerWorker()`. What's new here is a second process — `client.js` — that connects over HRPC (using the key Kernel publishes to its key file) and drives the running stack. The example lives in [`examples/backend/mdk-e2e/`](https://github.com/tetherto/mdk/blob/main/examples/backend/README.md#end-to-end-mdk-e2e) and contains six runnable scripts. This tutorial uses three of them: `run.js` for a smoke test, `server.js` for the long-running stack, and `client.js` for interactive control. ## Prerequisites - Node.js >=24 (LTS) - npm >=11 HRPC relies on HyperDHT for peer connectivity, including when Kernel and the Worker share a process. Review the [network requirements and checks](/guides/miners/troubleshooting#example-does-not-print-a-kernel-key) if startup stalls. ### Clone and install #### 1.1 Clone the repo ```bash git clone git@github.com:tetherto/mdk.git cd mdk ``` #### 1.2 Install dependencies The monorepo has two workspaces with their own dependency trees. Install both: ```bash backend/core/install-packages.sh ci backend/workers/install-packages.sh ci ``` Each script walks every `package.json` under its workspace and runs `npm ci`. The `examples/mdk-e2e/` package is included automatically — no extra install step needed.

(1.3 Optional) Smoke test the stack

Before going interactive, prove the wiring works. `run.js` starts a mock Whatsminer + Worker + Kernel in one process, exercises a few queries, prints the results, and exits cleanly: ```bash node examples/backend/mdk-e2e/run.js ``` Expected output (the UUID and metric values vary): ```text Devices: [ '8f3e9a2b-7c1d-4e5a-9f8b-6c2d1e3f4a5b [miner-wm-m56s]' ] Telemetry: ONLINE hashrate=170000 power=3500W Commands: reboot, setPowerMode, setLED, setPowerPct, setupPools, saveComment ``` If you see those three lines, every layer is working: the mock is responding, the Worker registered the device with Kernel directly in-process (no DHT lookup), and envelope routing is delivering messages both ways. The script tears itself down and exits with code 0. If the smoke test fails with `EADDRINUSE` on port 14028, a previous run left a Node process alive. Kill stragglers with `pkill -f mdk-e2e` and retry.

### Run the interactive demo #### 3.1 Start the stack In your terminal: ```bash node examples/backend/mdk-e2e/server.js ``` `server.js` starts the same mock + Worker + Kernel as `run.js`, but stays running and prints the IDs you'll need: ```text Kernel key: 7a4c8b...e3f0 Device: 8f3e9a2b-7c1d-4e5a-9f8b-6c2d1e3f4a5b hp-rpc-cli -s 7a4c8b...e3f0 -m mdk -d '{...}' hp-rpc-cli -s 7a4c8b...e3f0 -m mdk -d '{...}' Ctrl+C to stop. ``` The `Kernel key` is a 64-char hex public key. `Device` is a UUIDv4 generated at registration time. Both vary per run — note the device UUID for the next step. The two `hp-rpc-cli` lines are paste-ready commands for inspecting Kernel over HRPC from another machine. You don't need them for this tutorial — they're there if you have [`hp-rpc-cli`](https://github.com/holepunchto/hp-rpc-cli) installed and want to go off-script. #### 3.2 Connect the interactive client Open a second terminal in the same `mdk` directory: ```bash node examples/backend/mdk-e2e/client.js ``` `client.js` reads the Kernel key from the key file Kernel published at startup (`os.tmpdir()/mdk/.kernel-key` — or pass a key as the first argument), connects over HRPC, and gives you an MDK REPL: ```text Client — connected to Kernel over HRPC: 7a4c8b… Type "help" for commands, "quit" to exit. mdk> ``` #### 3.3 Drive the stack 3.3.1 Discover the telemetry of your (mock) device by entering commands at the `mdk>` prompt, substituting `` with the UUID printed in Step 3.1: ```text mdk> metrics ``` Each command builds an MDK Protocol envelope, sends it to Kernel over HRPC, and prints the JSON response. 3.3.2 Try changing the power mode and observing the effect: ```text mdk> setpower low mdk> metrics ``` After `setpower ... low` the second `metrics` call should reflect the power mode change.

Full command reference

**Reads** ```text workers — list workers list [deviceId] — list devices count [deviceId] — device count metrics — live telemetry from hardware logs — recent logs settings [deviceId] — worker settings stats [deviceId] — fleet stats config — device config (pools, etc.) capabilities — mdk-contract capabilities state [deviceId] — worker state snapshot ``` **Commands** ```text reboot — reboot miner setpower — set power mode (normal/low/high) setled [on|off] — toggle LED ``` ```text quit / exit — exit client ```

Add real auth (Google OAuth)

The `start all` shortcut above runs in `noAuth` mode so you can see the dashboard immediately. To exercise the real authentication flow — a Google sign-in that issues a bearer token the dashboard sends on every request — configure OAuth and start the services without the `noAuth` shortcut. **1. Create a Google OAuth 2.0 client** 1. Go to [Google Cloud Console API credentials](https://console.cloud.google.com/apis/credentials) 2. Create an **OAuth 2.0 Client ID** (type: *Web application*) 3. Add to **Authorized redirect URIs**: `http://localhost:3000/oauth/google/callback` 4. Add to **Authorized JavaScript origins**: `http://localhost:3030` 5. Copy the **Client ID** and **Client Secret** **2. Configure Gateway** Edit `backend/core/gateway/config/facs/httpd-oauth2.config.json` (copy from `.example` if it doesn't exist) and fill in your client ID and secret: ```json { "h0": { "method": "google", "credentials": { "client": { "id": "", "secret": "" } }, "startRedirectPath": "/oauth/google", "callbackUri": "http://localhost:3000/oauth/google/callback", "callbackUriUI": "http://localhost:3000", "users": [] } } ``` **3. Set yourself as super-admin** In `backend/core/gateway/config/facs/auth.config.json`, set `superAdmin` to your Google account email: ```json { "a0": { "superAdmin": "you@example.com" } } ``` **4. Run with auth** Start Gateway and the UI without the `VITE_NO_AUTH` shortcut (run them directly rather than via `start all`), open `http://localhost:3030`, click **Sign in with Google**, and authorise with the super-admin email. The dashboard then shows live data behind the token. For the full setup, see the example's [`README.md`](https://github.com/tetherto/mdk/tree/main/examples/e2e).

## Continue Previous: [2. Control devices from the CLI](/tutorials/backend-stack/cli) You've climbed the whole ladder: observed a stack, driven it from a CLI, and built a live UI on it. ## Go deeper - The [full example, including the OAuth setup and how to add a new data panel](https://github.com/tetherto/mdk/tree/main/examples/e2e) - Learn more about [MDK UI toolkit (components, hooks, theming)](https://github.com/tetherto/mdk/blob/main/ui/README.md) - [Run a full site (multiple Workers and devices)](https://github.com/tetherto/mdk/blob/main/examples/backend/mdk-site/site.js) - Read [all runnable examples in one place](https://github.com/tetherto/mdk/blob/main/examples/backend/README.md) # Build a minimal single-page dashboard (/tutorials/quickstart/build-a-dashboard) # Build a minimal single-page dashboard [`examples/full-site`](https://github.com/tetherto/mdk/tree/main/examples/full-site) is the fullest demonstration of the MDK stack: multiple Worker processes spanning miners, containers, power meters, sensors, and miner pools, plus a multi-page React + Vite dashboard built on `@tetherto/mdk-react-devkit`. That breadth is the point of that example — but it also means it's a lot to read through if all you want is to understand (or prototype against) the actual wiring: Kernel, one Worker, a Gateway route, a page that polls it. This guide builds the smallest version of that same shape: **one Worker, one Gateway route, one React page**. It teaches the same end-to-end shape as `examples/full-site` — including its UI layer, `@tetherto/mdk-react-devkit` components driven by `@tetherto/mdk-react-adapter` hooks — without that example's family-specific adapters, persistence, history, commands, multi-page router, or chart aggregation. If **Kernel**, **Worker**, or **Gateway** are unfamiliar terms, read [the architecture overview](/concepts/architecture) first. This tutorial also assumes you've skimmed [Build a third-party Worker](/guides/workers/build-a-worker) — the one Worker used here is [`backend/workers/samples/demo-worker`](https://github.com/tetherto/mdk/blob/main/backend/workers/samples/demo-worker/index.js), the same zero-dependency reference Worker that tutorial is built around. ## Overview This tutorial builds the smallest version of the full MDK stack: **one Worker, one Gateway route, one React page**. What you'll have at the end: ```text examples/minimal-dashboard/ package.json start.js # boots Kernel + the one Worker + Gateway, one process plugins/ dashboard/ mdk-plugin.json # one route: GET /overview controllers/ overview.js # lists every Worker's devices + live telemetry ui/ package.json tsconfig.json vite.config.ts index.html src/ main.tsx # + render OverviewPage OverviewPage.tsx # polls /overview, renders devkit components ``` No router, no charts, no hand-rolled CSS — one page built from three `@tetherto/mdk-react-devkit` primitives (`LabeledCard`, `DataTable`, `Badge`) and one `@tetherto/mdk-react-adapter` hook (`useQuery`), the same building blocks `examples/full-site/ui` uses, minus the parts (router, sidebar, line charts, domain panels) this single-page, single-Worker dashboard doesn't need. ## Prerequisites - Node.js `>=24` - This repo checked out, with the backend and UI dependencies installed once from the repository root: ```bash npm run setup:core npm run setup:workers npm run setup:ui npm run build:ui ``` Running `npm run setup` from `examples/full-site` is also supported, but it is broader: it installs these backend and UI dependencies plus the full-site example and UI dependencies and builds the UI packages. - Commands below assume a new `examples/minimal-dashboard/` directory alongside `examples/full-site/` ### Pick the Worker Use [`backend/workers/samples/demo-worker`](https://github.com/tetherto/mdk/blob/main/backend/workers/samples/demo-worker/index.js) as-is — it needs no worker-infra services (provisioning stores, alert templates), just `WorkerRuntime` and its own bundled mock device. Nothing in the steps below is specific to it, though: swap in `startWhatsminerWorker`, `startAntminerWorker`, or your own Worker from [Build a third-party Worker](/guides/workers/build-a-worker) and everything past the next step is unchanged. ### Boot Kernel and Worker in the same process The simplest of the three discovery modes ([full trade-offs here](/concepts/deployment-topologies#the-trade-off)): one Node process owns both the Kernel and the Worker, so there's no key file or DHT topic to manage. `examples/minimal-dashboard/start.js`: ```js 'use strict' const path = require('path') const { getKernel, waitForDiscovery } = require('../../backend/core/mdk') const { startDemoWorker } = require('../backend/demo-worker-caller') const demoMock = require('../../backend/workers/samples/demo-worker/mock/server') const ROOT = path.join(__dirname, '.mdk-data') const MOCK_PORT = 9101 const HTTP_PORT = Number(process.env.MDK_HTTP_PORT) || 3000 function onceListening (mock) { if (mock.server.listening) return Promise.resolve() return new Promise((resolve) => mock.server.once('listening', resolve)) } async function main () { // the one fake device this dashboard will show — swap for real hardware later const mock = demoMock.createServer({ host: '127.0.0.1', port: MOCK_PORT, serial: 'WM3-0001' }) await onceListening(mock) // Kernel + the one Worker, same process const kernel = await getKernel({ root: ROOT }) const worker = await startDemoWorker({ workerId: 'demo-worker-1', storeDir: path.join(ROOT, 'demo-worker-store'), seedDevices: [{ id: 'demo-0', opts: { host: '127.0.0.1', port: MOCK_PORT } }] }) await kernel.registerWorker(worker.runtime.getPublicKey()) await waitForDiscovery(kernel, { minWorkers: 1 }) console.log('worker registered: %s', worker.deviceIds.join(', ')) } module.exports = { main, ROOT, HTTP_PORT } if (require.main === module) main().catch((err) => { console.error(err); process.exit(1) }) ``` The demo Worker package exports a plugin and SQLite helper, not a boot function. The separate [`demo-worker-caller`](https://github.com/tetherto/mdk/blob/main/examples/backend/demo-worker-caller/index.js) used here owns `WorkerRuntime`, device configuration, persistence, sampling, and shutdown. `getKernel({ root: ROOT })` with no `topic`/`discovery` option defaults to DHT discovery with a fresh random topic. This example then registers the Worker's public key directly because both objects are in the same process. See the [discovery model](/concepts/stack/workers#discovery-model) for the DHT, Local, and Same-process options to use in other deployments. ### Write the one Gateway plugin route A [Gateway plugin](/guides/gateway/plugins) is a directory with a manifest and a controller. This one has a single read-only route that lists every registered Worker's devices and pulls each one's default `metrics` telemetry bundle — no per-device-family branching, because there's only one family here. #### 3.1 Write the plugin manifest `examples/minimal-dashboard/plugins/dashboard/mdk-plugin.json`: ```json { "name": "@your-org/mdk-plugin-dashboard", "version": "0.1.0", "description": "Minimal dashboard plugin: one route that lists every registered device and its live telemetry.", "routes": [ { "id": "dashboard.overview", "handler": "./controllers/overview.js", "auth": false, "http": { "method": "GET", "path": "/overview" }, "description": "Live snapshot of every device across every registered Worker.", "safety": "read-only" } ] } ``` #### 3.2 Write the controller `examples/minimal-dashboard/plugins/dashboard/controllers/overview.js`: ```js 'use strict' module.exports = async function overview (req, services) { const { workers } = await services.mdkClient.listWorkers() const devices = await Promise.all( workers.flatMap((w) => (w.deviceIds || []).map(async (deviceId) => { const tel = await services.mdkClient.pullTelemetry(deviceId, 'metrics') return { deviceId, workerId: w.workerId, workerState: w.state, ...tel.metrics } })) ) return { ts: Date.now(), devices } } ``` A controller is `async (req, services) => value` — return a plain object, the Gateway serializes it to JSON itself; you never touch `res`. `services.mdkClient` is the same client used everywhere else in MDK — no knowledge of the underlying MDK Protocol envelope required. With more than one Worker family mixed in (miners, powermeters, sensors, ...) you'd branch by `deviceFamily` instead of spreading `tel.metrics` blindly — see [`examples/full-site/plugins/site/lib/site.js`](https://github.com/tetherto/mdk/blob/main/examples/full-site/plugins/site/lib/site.js) for that pattern once you outgrow this one. ### Serve the plugin and static page from the same Gateway Add `startGateway` to `start.js`, mounting the plugin via `extraPluginDirs` and the built UI (Step 5's `ui/dist`) via `common.staticRootPath`. This is the complete canonical file; its boot order is mock, Kernel, Worker, registration, readiness, then Gateway: ```js 'use strict' const path = require('path') const { getKernel, startGateway, waitForDiscovery } = require('../../backend/core/mdk') const { startDemoWorker } = require('../backend/demo-worker-caller') const demoMock = require('../../backend/workers/samples/demo-worker/mock/server') const ROOT = path.join(__dirname, '.mdk-data') const MOCK_PORT = 9101 const HTTP_PORT = Number(process.env.MDK_HTTP_PORT) || 3000 function onceListening (mock) { if (mock.server.listening) return Promise.resolve() return new Promise((resolve) => mock.server.once('listening', resolve)) } async function main () { // Start the mock device before its Worker tries to connect. const mock = demoMock.createServer({ host: '127.0.0.1', port: MOCK_PORT, serial: 'WM3-0001' }) await onceListening(mock) // Start Kernel, then the Worker runtime that hosts the demo Worker plugin. const kernel = await getKernel({ root: ROOT }) const worker = await startDemoWorker({ workerId: 'demo-worker-1', storeDir: path.join(ROOT, 'demo-worker-store'), seedDevices: [{ id: 'demo-0', opts: { host: '127.0.0.1', port: MOCK_PORT } }] }) // Register the Worker and wait until it is ready before accepting HTTP traffic. await kernel.registerWorker(worker.runtime.getPublicKey()) await waitForDiscovery(kernel, { minWorkers: 1 }) await startGateway({ kernel, noAuth: true, port: HTTP_PORT, root: path.join(ROOT, 'gateway'), tmpdir: path.join(ROOT, 'gateway'), extraPluginDirs: [path.join(__dirname, 'plugins', 'dashboard')], common: { staticRootPath: path.join(__dirname, 'ui', 'dist') } }) console.log('worker registered: %s', worker.deviceIds.join(', ')) console.log(`dashboard up: http://localhost:${HTTP_PORT}/`) } module.exports = { main, ROOT, HTTP_PORT } if (require.main === module) main().catch((err) => { console.error(err); process.exit(1) }) ``` The route's `"auth": false` and Gateway's `noAuth: true` are **local-development settings**. Do not expose this Gateway directly to an untrusted network. Production deployments require TLS termination, authentication, authorization, and network policy. Before production, remove `noAuth: true`, set the route's `"auth"` to `true`, and declare its required `"permissions"`. Write routes also need input validation, rate limits, and auditing. Serve the built page from `common.staticRootPath`, not a separate server on its own port. Gateway plugin controllers only receive `(req, services)` — never the underlying reply object — so a controller has no way to set `Access-Control-Allow-Origin`, and Gateway has no built-in CORS support. Building the UI (Step 5) and serving `ui/dist` from `staticRootPath` keeps `fetch('/overview')` same-origin with zero CORS configuration. This is also why `examples/full-site`'s Vite *dev* server proxies `/site/*` to the Gateway port instead of calling it cross-origin — Step 5's `vite.config.ts` proxies `/overview` the same way for hot-reload development. ### Write the single-page UI with MDK devkit components Instead of hand-rolled HTML, the page is a small React + Vite app built from the same packages `examples/full-site/ui` uses — `@tetherto/mdk-react-adapter` for the provider and data hook, `@tetherto/mdk-react-devkit` for the components — scaled down to what one route needs: no router (one page), no charts (no history endpoint here), no sidebar. Three primitives do the job: `LabeledCard` for the section container, `DataTable` for the sortable device grid, and `Badge` to color-code `workerState`. `examples/minimal-dashboard/ui/package.json`: ```json { "name": "@your-org/mdk-minimal-dashboard-ui", "type": "module", "version": "0.1.0", "private": true, "scripts": { "dev": "vite", "build": "tsc --noEmit && vite build" }, "dependencies": { "@tetherto/mdk-react-adapter": "file:../../../ui/packages/react-adapter", "@tetherto/mdk-react-devkit": "file:../../../ui/packages/react-devkit", "react": "^19.2.0", "react-dom": "^19.2.0" }, "devDependencies": { "@types/react": "^19.2.14", "@types/react-dom": "^19.2.3", "@vitejs/plugin-react": "^4.3.4", "typescript": "^5.7.3", "vite": "^6.3.5" } } ``` `examples/minimal-dashboard/ui/tsconfig.json`: ```json { "compilerOptions": { "target": "ES2022", "jsx": "react-jsx", "lib": ["ES2022", "DOM", "DOM.Iterable"], "types": ["vite/client"], "module": "ESNext", "moduleResolution": "bundler", "strict": true, "skipLibCheck": true, "noEmit": true }, "include": ["src/**/*", "vite.config.ts"], "exclude": ["node_modules", "dist"] } ``` `examples/minimal-dashboard/ui/vite.config.ts` — the dev-only proxy so `fetch('/overview')` stays same-origin against the Gateway port, the same pattern [`examples/full-site/ui/vite.config.ts`](https://github.com/tetherto/mdk/blob/main/examples/full-site/ui/vite.config.ts) uses for `/site/*`: ```ts declare const process: { env: Record } const apiPort = process.env.VITE_API_PORT || '3000' plugins: [react()], server: { port: Number(process.env.MDK_UI_PORT) || 3041, proxy: { '/overview': `http://localhost:${apiPort}` } } }) ``` `examples/minimal-dashboard/ui/index.html`: ```html MDK dashboard

``` `examples/minimal-dashboard/ui/src/main.tsx` — `` wires the TanStack Query client `useQuery` needs and resolves the API base URL, exactly as it does in [`examples/full-site/ui/src/main.tsx`](https://github.com/tetherto/mdk/blob/main/examples/full-site/ui/src/main.tsx): ```tsx const rootElement = document.getElementById('root') if (!rootElement) throw new Error('ERR_ROOT_ELEMENT_MISSING') // Same-origin: the Vite dev proxy forwards /overview to the gateway; // in production the Gateway serves this build from staticRootPath. ReactDOM.createRoot(rootElement).render( ) ``` `examples/minimal-dashboard/ui/src/OverviewPage.tsx` — `useQuery` polls the route from Step 3 the same way [`examples/full-site/ui/src/SitePage.tsx`](https://github.com/tetherto/mdk/blob/main/examples/full-site/ui/src/SitePage.tsx) polls `/site/overview`; `DataTable` and `Badge` replace that page's hand-rolled markup: ```tsx type Device = { deviceId: string workerId: string workerState: string hashrate_rt?: number power?: number temperature?: number } type Overview = { ts: number; devices: Device[] } function get(base: string, path: string): Promise { return fetch(`${base}${path}`).then((res) => { if (!res.ok) throw new Error(`HTTP ${res.status}`) return res.json() as Promise }) } function stateBadgeStatus(state: string): 'success' | 'error' | 'default' { if (state === 'ready') return 'success' if (state === 'offline') return 'error' return 'default' } const columns: DataTableColumnDef[] = [ { accessorKey: 'deviceId', header: 'Device' }, { accessorKey: 'workerId', header: 'Worker' }, { id: 'workerState', header: 'Worker state', cell: ({ row }) => { const state = (row.original.workerState || 'unknown').toLowerCase() return } }, { accessorKey: 'hashrate_rt', header: 'Hashrate (TH/s)', cell: ({ getValue }) => (Number(getValue()) || 0).toFixed(2) }, { accessorKey: 'power', header: 'Power (W)', cell: ({ getValue }) => (Number(getValue()) || 0).toFixed(0) }, { accessorKey: 'temperature', header: 'Temp (°C)', cell: ({ getValue }) => (Number(getValue()) || 0).toFixed(1) } ] const { apiBaseUrl } = useMdkContext() const overview = useQuery({ queryKey: ['dashboard-overview'], queryFn: () => get(apiBaseUrl, '/overview'), refetchInterval: 3000 }) return (

data={overview.data?.devices ?? []} columns={columns} getRowId={(row) => row.deviceId} loading={overview.isLoading} enablePagination={false} />

) } ``` A controller is `async (req, services) => value`; a page is `useQuery` + devkit components — neither one touches the other's plumbing. `OverviewPage` never imports `mdkClient`, and `overview.js` never imports React. ### Run it #### 6.1 Add package.json `examples/minimal-dashboard/package.json`: ```json { "name": "@your-org/mdk-minimal-dashboard", "version": "0.1.0", "private": true, "scripts": { "build": "npm --prefix ui run build", "start": "node start.js" } } ``` #### 6.2 Start the dashboard Install each package's own dependencies, build the UI once, then boot the backend: ```bash cd examples/minimal-dashboard npm install npm --prefix ui install npm run build npm run start ``` Open `http://localhost:3000/` — the page polls `/overview` every 3 seconds and shows the one `demo-0` device reporting live telemetry from its mock. Confirm the API directly with: ```bash curl -s http://localhost:3000/overview ``` You should see JSON shaped like `{ "ts": ..., "devices": [{ "deviceId": "demo-0", "workerId": "demo-worker-1", "workerState": "READY", "hashrate_rt": ..., "power": ..., "temperature": ... }] }`. ### Hot-reload UI development Vite does **not** replace the Gateway. Without hot reload you open `:3000` (Gateway serves the built `ui/dist`). With hot reload you still need the Gateway for `/overview`, and Vite only serves the React app and proxies that path. Keep **both** terminals running: **Terminal 1 — Gateway** (do not stop this): ```bash cd examples/minimal-dashboard npm run start ``` Wait for `dashboard up: http://localhost:3000/`. **Terminal 2 — Vite**: ```bash cd examples/minimal-dashboard VITE_API_PORT=3000 npm --prefix ui run dev ``` Open **`http://localhost:3041/`** (the Vite port), not `:3000`. Step 5's proxy forwards `/overview` to the Gateway on `VITE_API_PORT`. If Terminal 1 is down, Vite logs `http proxy error: /overview` / `ECONNREFUSED` and the table stays empty. ## Next steps - **More Workers, zero controller changes**: `overview.js` already loops over every registered Worker generically. Register a second Worker the same way (Step 2's `startDemoWorker` + `startWhatsminerWorker`, etc., both followed by `kernel.registerWorker(...)`) and it appears in `/overview` for free. - **A write route**: Add a second manifest entry (`POST /devices/{deviceId}/command`) calling `services.mdkClient.sendCommand(deviceId, 'setPowerMode', { mode })`, following the `command.js` example in [Gateway plugins](/guides/gateway/plugins), and a `Button` in `OverviewPage.tsx` that `POST`s to it. Before deploying any physical write command, require narrowly scoped authorization, validate its payload and target state, apply rate limits, and record an audit trail. - **More pages, charts, history**: Add `react-router-dom` and a second route/page, or graduate to the domain layer (`@tetherto/mdk-react-devkit/domain`'s `LineChartCard`, `MetricCard`, header stats bar) once the Gateway plugin grows a history endpoint to feed them — see [`examples/full-site/ui/src/DashboardPage.tsx`](https://github.com/tetherto/mdk/blob/main/examples/full-site/ui/src/DashboardPage.tsx) and [`examples/full-site/plugins/site/controllers/history.js`](https://github.com/tetherto/mdk/blob/main/examples/full-site/plugins/site/controllers/history.js) for that shape. - **Separate processes or hosts**: Replace the direct registration in Step 2 with Local discovery for processes on one machine or DHT discovery for separate hosts, as described in the [discovery model](/concepts/stack/workers#discovery-model). ## Troubleshooting | Symptom | Cause | | --- | --- | | `/overview` returns `{ devices: [] }` | `kernel.registerWorker(...)` wasn't awaited, or `startGateway` was called before `waitForDiscovery` resolved | | `/overview` returns `500` / `Cannot read properties of null` | Controller spread `tel.metrics` when `pullTelemetry` returned `null` — use `(tel && tel.metrics) \|\| {}` as in Step 3 | | `pullTelemetry` throws / device shows zeros | The Worker's `connect()` couldn't reach the mock at boot — confirm the mock's `listening` event fired before `startDemoWorker` seeded it (Step 2's `onceListening`) | | Vite shows `http proxy error: /overview` / `ECONNREFUSED`, page at `:3041` has no data | Gateway is not listening on the proxy target — keep `npm run start` running in another terminal, and set `VITE_API_PORT` to that Gateway port (default `3000`). Open `:3041`, not `:3000` | | Browser `fetch('/overview')` fails from Vite with CORS / wrong host when Gateway is up | See the CORS note in Step 4 — the Vite proxy must target the Gateway (`VITE_API_PORT`); do not call a different origin from the page | | `ERR_PLUGIN_HANDLER_NOT_FOUND: routes.dashboard.overview: ./controllers/overview.js` on Gateway boot | `extraPluginDirs` must point at the directory *containing* `mdk-plugin.json`, not the controller file itself | | Gateway boots but the page 404s | `common.staticRootPath` must be an absolute path (`path.join(__dirname, 'ui', 'dist')`) pointing at a *built* UI (`npm run build` in Step 6), not a relative string or the unbuilt `ui/src` | | `Cannot find module '@tetherto/mdk-react-devkit'` when building `ui/` | Run the Prerequisites' `npm run setup:ui && npm run build:ui` from the repo root first — the UI packages ship pre-built `dist/` output that `ui/`'s `package.json` depends on via `file:` links | # Run the full-site example (/tutorials/quickstart/full-stack-demo) ## Overview This tutorial presents the [full-site example](https://github.com/tetherto/mdk/tree/main/examples/full-site) end to end running the full MDK stack: multiple configured Workers across a range of device families, their mock device servers, a Gateway HTTP API, and a React dashboard, all in one command. What you'll have at the end: - The supported fleet: multiple miner types, container types, and power meters; one sensor family with two inlet sensors; and two mining pools, each backed by mock hardware that speaks the real wire protocol - A Gateway API at `:3007` serving `/site/overview`, `/site/history`, and `/site/miners/:id/command` - A React dashboard at `:3040` with live hashrate, power, and device status - An MCP server exposing the site's device registry, telemetry, and commands as tools for AI agents The example can boot in one Node.js process (`node start.js`) or as separate processes through an interactive REPL (`node cli.js`). This tutorial uses `start.js` — the simplest path. ## Prerequisites - Node.js >=24 (LTS) - npm >=11 ### Install the example #### 1.1 Clone the repo ```bash git clone git@github.com:tetherto/mdk.git cd mdk ``` #### 1.2 Run setup ```bash cd examples/full-site npm run setup ``` `setup` installs `backend/core`, `backend/workers`, the UI workspace devkit packages, and this example's own dependencies. It runs once; subsequent starts skip it. The script walks several workspaces; first run takes 1-2 minutes. ### Start the site Start with a small fleet (3 miners per family, 9 total) for a fast first boot: ```bash node start.js --miners 3 ``` Wait for the terminal to print the Gateway and UI URLs: ```text Gateway http://localhost:3007 UI http://localhost:3040 ``` Open `http://localhost:3040` in a browser. The dashboard shows live hashrate, total power, and a per-device breakdown. Verify via the API: ```bash curl -s http://localhost:3007/site/overview | jq '{miners: (.miners|length), containers: (.containers|length), pools: (.pools|length), sensors: (.sensors|length)}' ``` Expected output: ```text { "miners": 9, "containers": 2, "pools": 2, "sensors": 2 } ``` The default fleet (100 miners per family, 300 total) opens 900+ file descriptors simultaneously. Before switching from `--miners 3` to the full fleet, run `ulimit -n 4096` in the same terminal session. ## What just happened 1. **Setup** installed `backend/core`, `backend/workers`, the MDK UI devkit, and this example — all the packages `start.js` imports at boot. 2. **Mock hardware** — `mocks.js` started one server per device family (miners on TCP, containers on HTTP and MQTT, power meters and sensors on Modbus, pools on REST). They speak the real wire protocols; every Worker driver runs its true connect, collect, and command paths against them. 3. **Kernel** — `getKernel()` started the orchestration layer that discovers Workers as they register and routes telemetry pulls and commands to them. 4. **Workers** — eleven `bootWorker()` calls, one per configured Worker spec, each dispatching to that family's `start{X}Worker()` boot function (`startWhatsminerWorker`, `startAvalonWorker`, ...) to construct a `WorkerRuntime` and connect it to the Kernel. 5. **Gateway** — `startGateway()` mounted the site plugin from `plugins/site/` and opened the HTTP server on `:3007`. The plugin aggregates data across the configured Workers through `mdkClient`. 6. **UI** — a Vite React dev server started on `:3040`, serving a dashboard built from MDK devkit components. 7. **MCP server** — an MCP server started over HRPC, exposing the site's device registry, telemetry, and command dispatch as tools for AI agents. ## Cleanup `Ctrl+C` stops mocks, Workers, Kernel, Gateway, and the UI dev server cleanly. State (Kernel key, Worker seeds, device registry, and tail-log history) persists in `.mdk-data/`. To wipe it: ```bash rm -rf examples/full-site/.mdk-data ``` ## Next steps - If Kernel, Gateway, Worker, manager, or thing are unfamiliar, read [terminology](/reference/glossary) - Run the same supported Worker fleet under PM2 or Docker — [Multi-process deployment guide](/guides/deployment/run-all-workers-site) - Add [custom plugins to the Gateway HTTP API](/guides/gateway/plugins) - Connect an [AI agent to the MCP server](https://github.com/tetherto/mdk/blob/main/examples/full-site/docs/mcp-server.md) to query and command the site - Explore [the interactive CLI process manager](https://github.com/tetherto/mdk/tree/main/examples/full-site) for per-process logs, runtime seeding, and live status # Explore the demo (/tutorials/ui/explore-the-demo) This page presents a copy/paste method to clone the MDK UI monorepo, run the demo, and browse the full component library live. ## Prerequisites - **Node.js** >=24 - **npm** >=11 - **React** 19+ and **react-dom** 19+ ## Run the demo One copy/paste: four steps — clone, install, build, run. ```bash # Requires an SSH key configured for your GitHub account git clone git@github.com:tetherto/mdk.git cd mdk/ui npm install && npm run build npm run dev:catalog ``` ```bash git clone https://github.com/tetherto/mdk.git cd mdk/ui npm install && npm run build npm run dev:catalog ``` Open [http://localhost:5173/mdk](http://localhost:5173/mdk). You'll land in the demo browser — a sidebar of the full MDK component library, covering core primitives (buttons, inputs, tables, charts, dialogs) and mining-domain components (operations centre, vendor containers, alerts, pool manager, settings). ### What the demo wires The demo app uses [`@tetherto/mdk-ui-foundation`](/reference/app-toolkit/ui-foundation), `@tetherto/mdk-react-adapter`, and `@tetherto/mdk-react-devkit` with ``. ## Next steps - [Wire React](/quickstart/wire-react): install all three packages and wrap your app in `MdkProvider` - [Wire a React app](/tutorials/ui/react/tutorial): scaffold an app with `MdkProvider` and adapter hooks - [Learn more about the React MDK UI Devkit](/tutorials/ui/react) # Get started with React (/tutorials/ui/react) ## TL;DR - **One provider, zero Redux**: install and wrap your app in `` so connected foundation components and adapter hooks share the same stores and API client - Presentational [`/core` and `/foundation`](/reference/ui/components) imports can work without the provider - Anything that reads app state needs the provider ## Choose your path } title={Quickstart} href="/quickstart/wire-react" description={ <> Install all three packages, wrap in MdkProvider, wire stores and theming ⏱️ <3 min } /> } title={Explore the demo} href="/tutorials/ui/explore-the-demo" description={ <> Single copy/paste to clone the monorepo and browse the full demo app in your browser ⏱️ <1 min } /> } title={Tutorial} href="/tutorials/ui/react/tutorial" description={ <> Step-by-step app scaffold with MdkProvider, adapter hooks, and foundation components ⏱️ <5 min } /> } title={Build dashboards with your AI agent} href="/quickstart/connect-agents" description={ Wire Cursor or Claude to MDK with the UI CLI, then build from plain-language prompts } /> ## Prerequisites - **Node.js** >=24 - **npm** >=11 - **React** 19+ and **react-dom** 19+ ## About the React stack The React UI Devkit is published as **three workspace packages** in the [MDK monorepo](https://github.com/tetherto/mdk): - **[`@tetherto/mdk-ui-foundation`](/reference/app-toolkit/ui-foundation)** — headless state (Zustand vanilla stores), a TanStack `QueryClient` factory, telemetry primitives, and the command state machine. No React. - **`@tetherto/mdk-react-adapter`** — React bindings: ``, store hooks (`useAuth`, `useDevices`, `useNotifications`, `useTimezone`, `useActions`) and re-exports of `useQuery` / `useMutation`. - **`@tetherto/mdk-react-devkit`** — the React UI library: `./core` primitives and `./foundation` mining-domain components, hooks, and styles. `@tetherto/mdk-ui-foundation` is framework-agnostic; the adapter and devkit are React-specific. Add all three to your app’s `package.json`, then wrap the tree once in **``** from `@tetherto/mdk-react-adapter`. **`@tetherto/mdk-ui-foundation`** is the brain in the back room. It remembers who is logged in, which miners are selected, and what timezone the operator uses — but it has no buttons and no React. Other code (including non-React utilities) can read and update it with `getState()` / `setState()`. **`@tetherto/mdk-react-adapter`** plugs that brain into React. `` turns it on for your whole app. Hooks like `useAuth` and `useDevices` let components listen to one slice of state and re-render when that slice changes. **[`/core`](/reference/ui/components)** (`import … from '@tetherto/mdk-react-devkit/core'`) is the generic UI toolkit. Buttons, inputs, dialogs, tabs, charts, sidebars, toasts, tables. Nothing in it knows what a miner is. It owns colours, fonts, spacing, and the shared styling recipes. **[`/foundation`](/reference/ui/components)** (`import … from '@tetherto/mdk-react-devkit/foundation'`) is built on top of core. It knows about miners, containers, pools, hashrate, alarms, operators, permissions, and settings dashboards. Domain hooks and connected components expect `` to be in place. ## Next steps - Explore the [Component reference](/reference/ui/components): `@tetherto/mdk-react-devkit/core` primitives and `/foundation` mining-domain components - See the [UI Devkit overview](/reference/ui) for how the headless layer fits other frameworks - Browse the [Hooks](/reference/ui/hooks) reference — state, component, and utility hooks # Build a dashboard with an agent (/tutorials/ui/react/build-any-dashboard-with-an-agent) This tutorial walks a **realistic agent session** end to end: the same two-step flow as [Build dashboards with your AI agent](/quickstart/connect-agents). ## Overview MDK's React UI Devkit's library of presentational and composable building blocks can be used wherever suits you. Mining is one of many disciplines that benefits from charts, tables, tabs, and stat cards. Your telemetry; your dash. You bring *your* labels, *your* mock data, and *your* layout. The first thing we built was [Mining Dashboards](/tutorials/ui/react). What will you build? IoT fleet backend reporting, workout metrics motivation app, weather stats? Your data; your choice. The prompt asked for a **statistics tutorial page** so students can explore distributions, trends, and raw grades. You see every: - [UI CLI](/guides/ui/ui-cli) command the agent would run - Resulting page code - Run instructions We use mock JSON in the browser. No Kernel, Worker, pool API, or fleet backend is required. Presentational imports from `@tetherto/mdk-react-devkit/core` are enough for a highly visual, shippable UI. ## What you'll learn 1. **Domain is yours.** Component contracts describe shape and behavior (chart datasets, table columns), not industry vocabulary. 2. **The agent path is unchanged.** `init` → plain-language intent → local manifests → scaffold → `check`. 3. **Visual density is supported.** Bar charts, line trends, sortable tables, and stat cards compose into a dashboard that *looks* like a product, not a wireframe. The demo app is **Stats Lab**: a fictional intro statistics course where Teaching Assistants review quiz score histograms, weekly class averages, and per-student grades. ## Prerequisites - **Node.js** >=24 - **npm** >=11 - **React** 19+ and **react-dom** 19+ - A project folder inside the MDK UI monorepo (this walkthrough uses `apps/stats-lab`, same pattern as [Wire a React app](/tutorials/ui/react/tutorial#create-your-app)) - [Build dashboards with your AI agent](/quickstart/connect-agents) wired once (`mdk-ui init`) or willingness to run `init` in step 1 ## Agent session walkthrough ### Wire the IDE (same as agents) From your app or monorepo project root: ```bash npx @tetherto/mdk-ui-cli init --ide cursor ``` This writes `.mdk/context.md` and `.cursor/rules/mdk.mdc` so the session already knows the UI CLI surface. See [init](/guides/ui/ui-cli#init). ### State a non-mining intent Paste a prompt that names the domain explicitly so the agent does not reach for hashrate widgets: > Build a **statistics tutorial dashboard** for students in `apps/stats-lab`. Include: > > - A **histogram** of final exam scores (bar chart buckets 50–59 through 90–100) > - A **line chart** of weekly class average over six weeks > - A **sortable table** of students with midterm, final, and section > - Three **summary stat cards**: mean final, median final, enrollment count > > Use mock data in the repo. Import only from `@tetherto/mdk-react-devkit/core` and `@tetherto/mdk-react-devkit/foundation` where > needed. No mining APIs. The agent's job is unchanged from [Build dashboards with your AI agent](/quickstart/connect-agents#prompt-your-agent): discover exports, scaffold, and verify compile. ### Discovery commands the agent runs Behind the prompt, a well-behaved session issues deterministic CLI lookups (no model calls). A representative transcript: ```bash npx @tetherto/mdk-ui-cli suggest "statistics dashboard histogram line chart data table stat cards" ``` Typically returns chart-category components near the top — `BarChart`, `LineChart`, and closely related chart primitives. General-purpose components like `DataTable`, `SingleStatCard`, and `Tabs` score lower on chart-focused queries and are best found with the `find --category` commands in the next accordion. Because we asked for mock data only, the agent skips adapter hooks like `useDevices`. ```bash npx @tetherto/mdk-ui-cli find --category charts --format table npx @tetherto/mdk-ui-cli find --category tables --format table ``` Narrows to chart primitives and table components with stable exports. ```bash npx @tetherto/mdk-ui-cli docs BarChart npx @tetherto/mdk-ui-cli docs LineChart npx @tetherto/mdk-ui-cli example LineChart npx @tetherto/mdk-ui-cli docs DataTable ``` The agent copies real prop shapes (`LineChartData` millisecond `x` values, `DataTableColumnDef` accessors) instead of inventing APIs. ```bash npx @tetherto/mdk-ui-cli add page StatsLab \ --component BarChart \ --component LineChart \ --component DataTable \ --component SingleStatCard npx @tetherto/mdk-ui-cli check apps/stats-lab/src/App.tsx ``` `add page` emits a starter layout; the agent fills in mock datasets and labels. `check` validates imports and component prop contracts against the real package barrels; the app build in the local run verifies the final Vite project. Full command reference: [UI CLI](/guides/ui/ui-cli). ### Review the scaffolded page After the agent edits `App.tsx`, a Stats Lab dashboard might look like this: ```tsx BarChart, LineChart, DataTable, Tabs, TabsList, TabsTrigger, TabsContent, } from '@tetherto/mdk-react-devkit/core' type Student = { id: string name: string section: 'A' | 'B' midterm: number final: number } const students: Student[] = [ { id: '1', name: 'Alex Kim', section: 'A', midterm: 82, final: 88 }, { id: '2', name: 'Jordan Lee', section: 'B', midterm: 74, final: 79 }, { id: '3', name: 'Sam Rivera', section: 'A', midterm: 91, final: 94 }, { id: '4', name: 'Taylor Ng', section: 'B', midterm: 68, final: 72 }, { id: '5', name: 'Casey Park', section: 'A', midterm: 85, final: 90 }, ] const weekStart = (weekIndex: number): number => new Date(2025, 0, 6 + weekIndex * 7).valueOf() const StatsLab = (): React.JSX.Element => { const [sorting, setSorting] = useState([]) const finals = students.map((s) => s.final) const meanFinal = finals.reduce((a, b) => a + b, 0) / finals.length const sortedFinals = [...finals].sort((a, b) => a - b) const medianFinal = sortedFinals[Math.floor(sortedFinals.length / 2)] const histogram = useMemo( () => ({ labels: ['50–59', '60–69', '70–79', '80–89', '90–100'], datasets: [ { label: 'Students', data: [1, 2, 4, 6, 3], backgroundColor: '#6366f1', }, ], }), [], ) const weeklyAverage = useMemo( () => ({ datasets: [ { label: 'Class average', borderColor: '#22c55e', data: [71, 74, 76, 79, 81, 83].map((y, i) => ({ x: weekStart(i), y, })), }, ], }), [], ) const columns: DataTableColumnDef[] = [ { accessorKey: 'name', header: 'Student' }, { accessorKey: 'section', header: 'Section' }, { accessorKey: 'midterm', header: 'Midterm' }, { accessorKey: 'final', header: 'Final' }, ] return (

Stats Lab

Intro statistics — interpret distributions and trends

Charts Roster

Final exam distribution

Weekly class average

) } ``` Nothing in this file references pools, workers, or TH/s. The same components appear on mining pages because the **data model is generic**. ## Run Stats Lab locally Follow the same monorepo workflow as [Wire a React app](/tutorials/ui/react/tutorial). If you already completed that tutorial, skip to **Run the app** with `stats-lab` as the workspace name. ### Clone and build the UI monorepo ```bash git clone https://github.com/tetherto/mdk.git cd mdk ``` ```bash git clone git@github.com:tetherto/mdk.git cd mdk ``` ```bash npm install npm run build ``` ### Scaffold `apps/stats-lab` ```bash cd apps npm create vite@latest stats-lab -- --template react-ts cd stats-lab ``` Add workspace dependencies to `package.json`: ```jsonc "@tetherto/mdk-react-devkit": "*", "@tetherto/mdk-react-adapter": "*", "@tetherto/mdk-ui-foundation": "*", ``` Install from the monorepo root: ```bash cd ../.. npm install ``` ### Wrap with `MdkProvider` In `apps/stats-lab/src/main.tsx`, mirror [Wire a React app — Wrap your app in MdkProvider](/tutorials/ui/react/tutorial#wrap-your-app-in-mdkprovider): ```tsx // … ``` Mock data does not call the API; the provider satisfies components that expect React context. ### Run the app From the monorepo root: ```bash npm -w stats-lab run build ``` Then start Vite: ```bash npm -w stats-lab run dev ``` Or from the app folder: ```bash cd apps/stats-lab npm run dev ``` Open the URL Vite prints (typically `http://localhost:5173`). You should see **Stats Lab** with histogram, trend line, stat cards, and a sortable roster tab. ### Optional: compare with the MDK demo app Same commands as [Wire a React app — Run the demo app](/tutorials/ui/react/tutorial#run-the-demo-app): ```bash npm run dev:catalog ``` Open [http://localhost:5173/mdk](http://localhost:5173/mdk) to browse mining-oriented examples, then contrast with Stats Lab: **same primitives, different story**. ## Why the agent stays accurate Manifests list real exports, `check` catches many invented props, and `docs` / `example` ground the session in shipped contracts. The app build remains the final TypeScript and Vite verification. ## Next steps - [Build dashboards with your AI agent](/quickstart/connect-agents): the two-step entry point - [UI CLI reference](/guides/ui/ui-cli): every command in the discovery transcript - [Chart components](/reference/ui/components/charts): `BarChart`, `LineChart`, and related data shapes - [Data display](/reference/ui/components/display): `DataTable` sorting and pagination - [Wire a React app](/tutorials/ui/react/tutorial): hands-on monorepo setup without an agent # Your first component (/tutorials/ui/react/first-component) This tutorial assists first-time users to understand how to render a single MDK component in a React app as fast as possible. This path skips `` which works for presentational `/core` and `/foundation` imports. For adapter hooks or connected foundation components, continue with [Wire a React app](/tutorials/ui/react/tutorial). ## Prerequisites - **Node.js** >=24 - **npm** >=11 - **React** 19+ and **react-dom** 19+ ### Clone and build The MDK UI (`mdk/ui`) is an npm workspace. Clone the repository, install at the workspace root, and build all packages before adding an app or running the demo. #### 1.1 Clone the repository ```bash git clone https://github.com/tetherto/mdk.git cd mdk/ui ``` ```bash # Requires an SSH key configured for your GitHub account git clone git@github.com:tetherto/mdk.git cd mdk/ui ``` #### 1.2 Install and build ```bash npm install npm run build ``` This builds `@tetherto/mdk-react-devkit` and the other packages in the `ui/` workspace. ### Create your app #### 2.1 Scaffold a Vite React app Create a new React app in the `apps/` folder: ```bash cd apps npm create vite@latest my-app -- --template react-ts cd my-app ``` Ignore the CLI "Now run" instructions — follow the MDK-specific steps below. #### 2.2 Add MDK to `package.json` Open `package.json` and add the workspace dependency: ```jsonc "@tetherto/mdk-react-devkit": "*", ``` ```jsonc { "name": "my-app", "private": true, "version": "0.0.0", "type": "module", "scripts": { "dev": "vite", "build": "tsc -b && vite build", "lint": "eslint .", "preview": "vite preview" }, "dependencies": { "@tetherto/mdk-react-devkit": "*", // [!code ++] "react": "^19.2.6", // [!code highlight] "react-dom": "^19.2.6" // [!code highlight] }, } ``` Vite also adds a `devDependencies` block (`eslint`, `typescript`, `vite`, `@types/*`); leave that block as is. #### 2.3 Install from the workspace root ```bash cd ../.. # from apps/my-app back up to the workspace root mdk/ui npm install ``` ### Import styles #### 3.1 Import the MDK stylesheet Import the MDK stylesheet once in your app's entry point (typically `src/main.tsx`): ```tsx ``` ```tsx createRoot(document.getElementById('root')!).render( , ) ``` ### Render your first component > This example replaces `App.tsx` with a single mining metric tile that toggles between a normal and an alarmed state. #### 4.1 Replace `App.tsx` with the demo This pulls a button from `@tetherto/mdk-react-devkit/core` and a domain component (`SingleStatCard`) from `@tetherto/mdk-react-devkit/foundation`: ```tsx function App() { const [overheating, setOverheating] = useState(false) return (

Miner status

) } ``` #### 4.2 Run your app From the workspace root mdk/ui, start the dev server for your app. The `-w` name must match the `name` field in `apps/my-app/package.json` (`my-app` from step 2.1): ```bash npm -w my-app run dev ``` Alternatively, from the app folder: ```bash cd apps/my-app npm run dev ``` You should see a card showing `Inlet temperature 28 °C` with a **Simulate overheat** button below it. Click the button and the card flips into an alarm state: red border, red text, value jumps to `78 °C`, and the whole card pulses. Click **Cool down** to reset. That is `@tetherto/mdk-react-devkit/core` (the `Button`) and `@tetherto/mdk-react-devkit/foundation` (the `SingleStatCard`) working together: generic primitives plus mining-domain components, in one app. ## Next steps - To browse the full kit in one app first, see [Explore the demo](/tutorials/ui/explore-the-demo) - [Wire a React app](/tutorials/ui/react/tutorial): add `` and adapter hooks for connected foundation components - [Quickstart](/quickstart/wire-react): minimum integration reference (install, provider, stores, theming) - [Components](/reference/ui/components): primitives and mining-domain components reference (`@tetherto/mdk-react-devkit/core` and `/foundation`) # Wire a React app (/tutorials/ui/react/tutorial) This tutorial walks you through the full React stack: three workspace packages, ``, and adapter hooks. For a faster path that renders one presentational component without the provider, see [Your first component](/tutorials/ui/react/first-component). ## Prerequisites - **Node.js** >=24 - **npm** >=11 - **React** 19+ and **react-dom** 19+ ### Clone and build The `mdk/ui` directory is the npm workspace root. Clone the repository, install at the workspace root, and build all packages before adding an app or running the demo. #### 1.1 Clone the repository ```bash git clone https://github.com/tetherto/mdk.git cd mdk/ui ``` ```bash # Requires an SSH key configured for your GitHub account git clone git@github.com:tetherto/mdk.git cd mdk/ui ``` #### 1.2 Install and build ```bash npm install npm run build ``` This builds `@tetherto/mdk-react-devkit` and the other packages in the `ui/` workspace. ### Create your app #### 2.1 Scaffold a Vite React app Create a new React app in the `apps/` folder: ```bash cd apps npm create vite@latest my-app -- --template react-ts cd my-app ``` Ignore the CLI "Now run" instructions — follow the MDK-specific steps below. #### 2.2 Add MDK to `package.json` Open `package.json` and add all three workspace packages: ```jsonc "@tetherto/mdk-react-devkit": "*", "@tetherto/mdk-react-adapter": "*", "@tetherto/mdk-ui-foundation": "*", ``` ```jsonc { "name": "my-app", "private": true, "version": "0.0.0", "type": "module", "scripts": { "dev": "vite", "build": "tsc -b && vite build", "lint": "eslint .", "preview": "vite preview" }, "dependencies": { "@tetherto/mdk-react-devkit": "*", // [!code ++] "@tetherto/mdk-react-adapter": "*", // [!code ++] "@tetherto/mdk-ui-foundation": "*", // [!code ++] "react": "^19.2.6", // [!code highlight] "react-dom": "^19.2.6" // [!code highlight] }, } ``` Vite also adds a `devDependencies` block (`eslint`, `typescript`, `vite`, `@types/*`); leave that block as is. #### 2.3 Install from the workspace root ```bash cd ../.. # from apps/my-app back up to the workspace root mdk/ui npm install ``` ### Wrap your app in MdkProvider `` wires the headless stores from [`@tetherto/mdk-ui-foundation`](/reference/app-toolkit/ui-foundation) into React and sets up the TanStack `QueryClient`. It is required for adapter hooks and connected foundation components. See also [Quickstart — Wrap your app in MdkProvider](/quickstart/wire-react#wrap-your-app-in-mdkprovider). #### 3.1 Update `main.tsx` ```tsx ``` Wrap ``: ```tsx ``` ```tsx createRoot(document.getElementById('root')!).render( , ) ``` ### Use adapter hooks and render a component Adapter hooks subscribe to Zustand stores and re-render when the selected slice changes. This example uses `useAuth` and `useDevices` from the adapter, then renders a presentational `SingleStatCard` from foundation. #### 4.1 Replace `App.tsx` ```tsx function App() { const { permissions } = useAuth() const { selectedDevices } = useDevices() return (

Operator dashboard

Selected devices: {selectedDevices?.length ?? 0}

Permissions loaded: {permissions ? 'yes' : 'no'}

) } ``` Connected foundation components (device explorers, pool manager, settings dashboards) expect `` and often read multiple stores. Start with presentational imports while you wire your API; swap in connected components as your backend comes online. ### Run your app From the workspace root `mdk/ui`: ```bash npm -w my-app run dev ``` Or from the app folder: ```bash cd apps/my-app npm run dev ``` You should see the operator dashboard with device and permission readouts plus a temperature card. The adapter hooks confirm `` is wired — without it, they would throw. ## Next steps - [Quickstart](/quickstart/wire-react): install reference, store hooks, and theming - [Components](/reference/ui/components): primitives and mining-domain components reference (`@tetherto/mdk-react-devkit/core` and `/foundation`) ### Run the demo app If you are already at the workspace root `mdk/ui`: ```bash npm run dev:catalog ``` If your shell is still in the app folder: ```bash cd ../.. # apps/my-app → apps → workspace root mdk/ui npm run dev:catalog ``` Open [http://localhost:5173/mdk](http://localhost:5173/mdk) to browse examples.