Data hooks

TanStack Query–backed hooks that fetch live data from the MDK backend and project it into view-model shapes ready for MDK foundation components. These hooks sit in the adapter layer so that tag names, aggregate field keys, and unit conversions stay out of the devkit component layer.

All hooks require <MdkProvider> to be mounted in the tree.

At a glance

Prerequisites

• Wrap your app in <MdkProvider>
• Complete the @tetherto/mdk-react-devkit installation and add the dependency

Import

import {
  useActiveIncidents,
  useAuthToken,
  useConsumptionChartData,
  useCurrentAlertDevices,
  useDashboardDateRange,
  useDashboardExport,
  useDashboardTimeRange,
  useHashrateChartData,
  useHistoricalAlerts,
  usePoolRows,
  usePoolStats,
  usePowerModeTimelineData,
  useSiteConsumption,
  useSiteConsumptionChartData,
  useSiteContainerCapacity,
  useSiteEfficiency,
  useSiteHashrate,
  useSiteMinerCounts,
  useSiteMinerStats,
  useSitePowerMeter,
  useSitesOverviewData,
  useTokenPolling,
} from '@tetherto/mdk-react-adapter'

Site data

useSitesOverviewData

Projects raw site-overview container rows and pool stats into a <PoolManagerSitesOverview />-ready shape. Each container receives its per-container hashrate in MH/s, an attached pool-stats row, and a mining / offline status derived from the underlying snapshot.

import { useSitesOverviewData } from '@tetherto/mdk-react-adapter'

Options

Returns

Example

import { useSitesOverviewData } from '@tetherto/mdk-react-adapter'
import { PoolManagerSitesOverview } from '@tetherto/mdk-react-devkit/foundation'

function SiteOverview({ rawUnits, rawPoolStats, loading, latestTailLog }) {
  const { units, isLoading } = useSitesOverviewData({
    units: rawUnits,
    poolStats: rawPoolStats,
    isLoading: loading,
    tailLogItem: latestTailLog,
  })
  return <PoolManagerSitesOverview units={units} isLoading={isLoading} />
}

useSiteConsumption

Projects the freshest power sample from the dashboard's existing tail-log query into a scalar MW value for the header stats strip (<HeaderConsumptionBox />). Delegates fetching to useSiteConsumptionChartData.

import { useSiteConsumption } from '@tetherto/mdk-react-adapter'

Options

Accepts the same UseConsumptionChartDataParams object as useSiteConsumptionChartData.

Returns

useSiteConsumptionChartData

TanStack Query hook that fetches site consumption tail-log samples and returns a <LineChartCard>-ready ChartCardData payload. Applies site-powermeter defaults and converts watts to MW.

import { useSiteConsumptionChartData } from '@tetherto/mdk-react-adapter'

Options

Same UseConsumptionChartDataParams as useSiteConsumption.

Returns

A TanStack UseQueryResult whose data field is ChartCardData — the object accepted by <LineChartCard data={...} />.

Example

import { useSiteConsumptionChartData } from '@tetherto/mdk-react-adapter'
import { LineChartCard } from '@tetherto/mdk-react-devkit/foundation'

function ConsumptionChart() {
  const { data, isLoading } = useSiteConsumptionChartData({ timeline: '5m' })
  return <LineChartCard data={data} isLoading={isLoading} />
}

useSiteContainerCapacity

Reads the aggregated nominal miner capacity across all site containers from the 5-minute tail-log aggregate, giving the denominator shown in the header (e.g. the "2,188" in "MOS / 2,188").

import { useSiteContainerCapacity } from '@tetherto/mdk-react-adapter'

Options

Returns

useSiteEfficiency

Derives site efficiency in W/TH/s by dividing the latest site consumption by the latest hashrate. Both upstream hooks are called internally; pass powerW to override the consumption source (e.g. to use a power-meter reading instead).

import { useSiteEfficiency } from '@tetherto/mdk-react-adapter'

Options

Returns

useSiteHashrate

TanStack Query hook that reads the latest aggregate hashrate from the site tail-log and returns both a PH/s display value and the raw MH/s backend value.

import { useSiteHashrate } from '@tetherto/mdk-react-adapter'

Options

Returns

useSiteMinerCounts

Polls the device list for miners and aggregates them into online / offline / error counts. Uses the last.status field on each device row.

import { useSiteMinerCounts } from '@tetherto/mdk-react-adapter'

Options

Returns

useSiteMinerStats

Polls the stat-rtd realtime aggregate for the live miner stat summary — the MOS total, online/offline breakdown, and active pool worker count shown in the header.

import { useSiteMinerStats } from '@tetherto/mdk-react-adapter'

Options

Returns

useSitePowerMeter

Reads the current power-meter reading in watts from the site-level device tagged t-powermeter. Returns a MW conversion alongside the raw watts value.

import { useSitePowerMeter } from '@tetherto/mdk-react-adapter'

Options

Returns

Pool data

usePoolRows

TanStack Query hook that fetches per-pool stats and transforms them into PoolRow[] objects shaped for the pool manager table. Hashrate is normalised from raw H/s to PH/s.

import { usePoolRows } from '@tetherto/mdk-react-adapter'

Options

Returns

A TanStack UseQueryResult whose data is PoolRow[].

usePoolStats

TanStack Query hook that fetches per-pool stats and aggregates them into site-level totals — total workers, online workers, mismatch count, and aggregate hashrate in PH/s.

import { usePoolStats } from '@tetherto/mdk-react-adapter'

Options

Returns

Dashboard

useDashboardDateRange

Owns the single source of truth for the dashboard's date-range picker: a start / end ms-epoch pair with setters and a reset helper that restores the default 24-hour window.

import { useDashboardDateRange } from '@tetherto/mdk-react-adapter'

Options

Returns

Example

import { useDashboardDateRange } from '@tetherto/mdk-react-adapter'
import { DateRangePicker } from '@tetherto/mdk-react-devkit/foundation'

function DashboardHeader() {
  const { start, end, setRange, reset } = useDashboardDateRange()
  return <DateRangePicker start={start} end={end} onChange={setRange} onReset={reset} />
}

useDashboardExport

Reads cached query data for hashrate, consumption, incidents, and pool stats from the TanStack Query client and exposes exportCsv, exportJson, and a unified export(format) callable. Does not trigger refetches — the export represents exactly what is currently displayed.

import { useDashboardExport } from '@tetherto/mdk-react-adapter'

Options

Accepts a UseDashboardExportOptions object containing DashboardQueryRange fields (timeline, start, end, tag) needed to reconstruct the query keys.

Returns

useDashboardTimeRange

Tiny piece of scoped state for the dashboard's timeline selector. Owns the current timeline string and the canonical option list. Chart hooks (useHashrateChartData, useSiteConsumptionChartData, etc.) consume timeline as a prop.

import { useDashboardTimeRange } from '@tetherto/mdk-react-adapter'

Options

Returns

Example

import { useDashboardTimeRange, useSiteHashrate } from '@tetherto/mdk-react-adapter'
import { TimelineSelector } from '@tetherto/mdk-react-devkit/foundation'

function DashboardControls() {
  const { timeline, options, setTimeline } = useDashboardTimeRange()
  const { valuePhs } = useSiteHashrate({ timeline })
  return (
    <>
      <TimelineSelector options={options} value={timeline} onChange={setTimeline} />
      <span>{valuePhs?.toFixed(2)} PH/s</span>
    </>
  )
}

Chart data

useConsumptionChartData

TanStack Query hook returning raw consumption tail-log samples. Most dashboards should use the higher-level useSiteConsumptionChartData, which wraps this hook and returns a <LineChartCard>-ready payload.

import { useConsumptionChartData } from '@tetherto/mdk-react-adapter'

Options

Returns

A TanStack UseQueryResult<TailLogEntry[][], Error> — raw tail-log matrix before projection.

useHashrateChartData

TanStack Query hook combining the site tail-log hashrate series with the per-pool hashrate history into a single ChartCardData payload for <LineChartCard />. Handles unit conversion from both MH/s (tail-log) and raw H/s (pool API) into PH/s for display.

import { useHashrateChartData } from '@tetherto/mdk-react-adapter'

Options

Returns

A TanStack UseQueryResult whose data is ChartCardData — ready for <LineChartCard data={...} />.

usePowerModeTimelineData

TanStack Query hook returning power-mode and status samples shaped for <PowerModeTimelineChart data={...} />.

import { usePowerModeTimelineData } from '@tetherto/mdk-react-adapter'

Options

Returns

A TanStack UseQueryResult<PowerModeTimelineEntry[], Error>.

Auth and token

useAuthToken

Reads ?authToken=… from window.location.search, persists it into the headless authStore, and strips the parameter from the URL via history.replaceState so the token never lingers in the address bar. Router-agnostic by design. Returns the current token from the store so callers can gate navigation on authentication.

import { useAuthToken } from '@tetherto/mdk-react-adapter'

Returns

Example

import { useAuthToken } from '@tetherto/mdk-react-adapter'
import { Navigate, Outlet } from 'react-router-dom'

function ProtectedRoute() {
  const token = useAuthToken()
  return token ? <Outlet /> : <Navigate to="/signin" replace />
}

useTokenPolling

Polls the backend token-refresh endpoint at a fixed interval (default 250 s) and writes the new token back into the authStore. Fires the optional onSessionEnded callback on a 401 or 500, which MDK UI Shell uses to redirect back to /signin.

import { useTokenPolling } from '@tetherto/mdk-react-adapter'

Options

Example

import { useTokenPolling } from '@tetherto/mdk-react-adapter'
import { useNavigate } from 'react-router-dom'

function App() {
  const navigate = useNavigate()
  useTokenPolling({ onSessionEnded: () => navigate('/signin') })
  return <Outlet />
}

Incidents

useActiveIncidents

TanStack Query hook returning the list of currently-firing alerts, shaped for <ActiveIncidentsCard items={...} />. Queries devices that have a non-null last.alerts field and maps them via the mapDevicesToIncidents utility.

import { useActiveIncidents } from '@tetherto/mdk-react-adapter'

Options

Returns

A TanStack UseQueryResult<IncidentRow[], Error>.

Example

import { useActiveIncidents } from '@tetherto/mdk-react-adapter'
import { ActiveIncidentsCard } from '@tetherto/mdk-react-devkit/foundation'

function IncidentsFeed() {
  const { data: items = [], isLoading } = useActiveIncidents({ refetchInterval: 20_000 })
  return <ActiveIncidentsCard items={items} isLoading={isLoading} />
}

Alerts

Data hooks that back the full alerts surface: useCurrentAlertDevices feeds the <CurrentAlerts> / <Alerts> table with raw device rows; useHistoricalAlerts fetches and shapes the historical-alerts log for <HistoricalAlerts>. Both require <MdkProvider> in the tree.

See also useActiveIncidents in the Incidents section, which hits the same list-things endpoint but maps results to the dashboard card's IncidentRow[] shape.

useCurrentAlertDevices

TanStack Query hook returning the raw devices that currently carry one or more alerts, as the nested ListThingsDevice[][] envelope the devkit <Alerts> / <CurrentAlerts> table expects. Unlike useActiveIncidents, this hook leaves the payload unshaped so the table can derive its own filter tokens and per-row status. Both hit /auth/list-things; this hook requests a wider field set and uses a distinct cache key.

import { useCurrentAlertDevices } from '@tetherto/mdk-react-adapter'
import type { UseCurrentAlertDevicesOptions } from '@tetherto/mdk-react-adapter'

Options

Returns

A TanStack UseQueryResult<ListThingsDevice[][], Error>.

Example

import { useCurrentAlertDevices } from '@tetherto/mdk-react-adapter'
import { CurrentAlerts } from '@tetherto/mdk-react-devkit/foundation'

function AlertsTable({ filterTags }) {
  const { data, isLoading } = useCurrentAlertDevices({ filterTags })
  return <CurrentAlerts devices={data ?? []} isLoading={isLoading} filterTags={filterTags} />
}

useHistoricalAlerts

TanStack Query hook for the historical-alerts log. Fetches the [start, end] range as successive history-log windows, merges results by uuid, and shapes rows for the devkit <HistoricalAlerts> table via mapHistoryLogToAlerts. Range changes abort the in-flight chunk loop through the query's AbortSignal.

By default the entire range is fetched in a single request. Pass a smaller intervalMs (e.g. ONE_DAY_MS) only for wide ranges where the backend would otherwise cap or slow a single query — that splits the fetch into sequential 24-hour windows.

import { useHistoricalAlerts } from '@tetherto/mdk-react-adapter'
import type { UseHistoricalAlertsOptions } from '@tetherto/mdk-react-adapter'

Options

Returns

A TanStack UseQueryResult<HistoricalAlert[], Error>.

Example

import { useHistoricalAlerts } from '@tetherto/mdk-react-adapter'
import { HistoricalAlerts } from '@tetherto/mdk-react-devkit/foundation'

function AlertHistory({ start, end, filterTags, localFilters, onDateRangeChange }) {
  const { data: alerts = [], isLoading } = useHistoricalAlerts({ start, end })
  return (
    <HistoricalAlerts
      alerts={alerts}
      isLoading={isLoading}
      filterTags={filterTags}
      localFilters={localFilters}
      dateRange={{ start, end }}
      onDateRangeChange={onDateRangeChange}
    />
  )
}

Behaviour notes

• Wide ranges fan out into many requests. The MDK UI Shell page caps the default window at 14 days; pass a tighter [start, end] or set intervalMs to limit per-request payload size.
• The hook removes duplicate rows by uuid after merging chunks, before passing them to mapHistoryLogToAlerts.