Gateway plugins

Overview

The Gateway exposes HTTP routes through a declarative plugin system. Each plugin is a directory containing an mdk-plugin.json manifest and one or more controller files. MDK ships a set of default plugins that load automatically; you can mount additional plugins for your own site logic.

Default plugins

MDK ships plugins that load automatically on Gateway startup:

• The telemetry plugin serves site metrics (hashrate, consumption, efficiency, temperature, and more)
• The site-hashrate plugin serves aggregated site hashrate history
• The site-monitor plugin serves site configuration, feature flags, and live per-device hashrate

The plugin reference lists every route each of these plugins serves, with its method, generated from the plugin's mdk-plugin.json. Plugins you mount yourself are documented by their own manifests.

const { startGateway } = require('@tetherto/mdk')

await startGateway({
  kernel,
  port: 3000,
  extraPluginDirs: [
    path.join(__dirname, 'plugins/custom-metrics'),
    path.join(__dirname, 'plugins/alerts')
  ]
})

// controllers/live.js — read live telemetry
module.exports = async function live (req, services) {
  const deviceId = req.query.deviceId
  const telemetry = await services.mdkClient.pullTelemetry(deviceId, 'metrics')
  return { deviceId, ...telemetry }
}

// controllers/command.js — dispatch a command
module.exports = async function command (req, services) {
  const deviceId = req.params.deviceId
  const { mode } = req.body

  const result = await services.mdkClient.sendCommand(deviceId, 'setPowerMode', { mode })

  return {
    deviceId,
    commandId: result.commandId,
    status: result.status
  }
}

The req object

The services object

if (!services.mdkClient) throw new Error('ERR_MDK_CLIENT_UNAVAILABLE')

Read hardware data

For live device data use mdkClient:

// Pull a live metrics snapshot
const tel = await services.mdkClient.pullTelemetry(deviceId, 'metrics')

// Pull the declared capabilities (from the Worker's mdk-contract.json)
const { capabilities } = await services.mdkClient.getCapabilities(deviceId)

// List all registered Workers
const { workers } = await services.mdkClient.listWorkers()

For historical or aggregated series from a Worker's persisted tail-log use dataProxy:

const results = await services.dataProxy.requestData('tailLogRangeAggr', {
  type: 'miner',
  startDate: start,
  endDate: end,
  fields: { hashrate_sum: 1 }
})

The default telemetry controllers show worked examples of both patterns.

Send a command

sendCommand dispatches via the Kernel to the Worker that owns the device. The command must be declared in the Worker's mdk-contract.json. It returns:

const result = await services.mdkClient.sendCommand(deviceId, 'reboot', {})
if (result.status === 'FAILED') throw new Error(result.error)
return { commandId: result.commandId, status: result.status }

Caching

Add a "cache" array of dot-path strings to a route to enable request-level caching. The cache key is composed from the route ID and the resolved values of each path:

{
  "id": "telemetry.hashrate",
  "cache": ["query.start", "query.end", "query.groupBy"],
  ...
}

Pass ?overwriteCache=true to bypass and refresh.

Auth and permissions

The Gateway applies no authentication of its own. Every route a plugin declares is served to any caller, so a route that needs protecting carries that logic in its own controller. Identity is yours to supply: the manifest "auth" and "permissions" fields have no reader and change nothing.

Validate the token with your own identity layer and check it in the handler:

const { validateToken } = require('../lib/my-identity-layer')

module.exports = async function protectedRoute (req, services) {
  const token = req.headers.authorization?.replace('Bearer ', '')
  if (!token) throw new Error('ERR_UNAUTHORIZED')

  const { permissions } = validateToken(token)
  if (!permissions.includes('miner:w')) throw new Error('ERR_FORBIDDEN')

  // Your route logic
}

Manifest validation errors

The plugin loader validates every manifest and handler at startup and throws if anything is wrong:

Next steps

• Try the live site backend example for a complete worked plugin with three routes: a live site overview, a historical series, and a command endpoint running under PM2 or Docker
• Build the minimal dashboard tutorial — end-to-end worked example of the single-plugin + controller pattern
• Understand how Workers declare their data via mdk-contract.json — what mdkClient reads and sendCommand dispatches
• See the full manifest and services reference
• Review the Gateway API and config