Run a Whatsminer Worker

Overview

Whatsminer support ships as the external whatsminer-mdk-worker contract plugin — a plain mdk-contract.json plus handler files, with no startWhatsminerWorker export, no provisioning store, no alerts/stats templates, and no model validation. You host it yourself on WorkerRuntimeV2 through a small adapter; this repo ships two working ones to copy from (examples/full-site/backend/whatsminer-adapter.js, examples/mvp-site/backend/whatsminer-adapter.js).

Prerequisites

Review the common deployment prerequisites before you start.

Deployment-specific requirements:

The whatsminer-mdk-worker package added as a dependency (it's distributed as a git dependency, not on the npm registry — see its own README for the exact version/ref to pin)
A Node.js service or script in your deployment that constructs the adapter below and registers the resulting Worker
A supported Whatsminer device reachable from the machine or container running the Worker
The miner API reachable over encrypted TCP: port 4028 for API v2 (the default) or 4433 for API v3
The Whatsminer API password — the plugin negotiates a session token from it; there is no separate username

Development

Run against a mock

The plugin ships its own mock at whatsminer-mdk-worker/mock/api-v3-server. examples/mvp-site boots one mock per seed device and points the adapter's devices at them — read startMocks alongside startWhatsminerWorker in that example's backend/site.js for the full wiring (mock lifecycle, port assignment, device seeding all come from config/devices.json).

There is no minimal single-file runnable example for Whatsminer anymore (the old repo-root example shipped against the retired in-repo package); the full-site and mvp-site example stacks are the reference implementation. cd examples/mvp-site && npm run setup:example && npm start boots the whole stack — Kernel, mocks, and the Whatsminer Worker included — against seed data in config/devices.json.

Connect a miner

2.1 Write the adapter

whatsminer-mdk-worker has no boot helper of its own — construct a WorkerRuntimeV2 pointed at the package directory, translating your seed device list into the { deviceId, config } shape it expects:

const path = require('path')
const { WorkerRuntimeV2 } = require('@tetherto/mdk-worker')

const PKG_DIR = path.dirname(require.resolve('whatsminer-mdk-worker/package.json'))

async function startWhatsminerWorker (opts) {
  const devices = (opts.seedDevices || []).map((seed) => ({
    deviceId: seed.id || seed.info?.serialNum,
    config: { ...seed.opts }
  }))

  const runtime = new WorkerRuntimeV2(PKG_DIR, {
    workerId: opts.workerId,
    kernelTopic: opts.kernelTopic || null,
    storeDir: opts.storeDir,
    devices
  })

  await runtime.start()
  return { runtime, seeded: devices.length, stop: () => runtime.stop() }
}

module.exports = { startWhatsminerWorker }

This is the adapter examples/full-site/backend/whatsminer-adapter.js ships, trimmed of its input validation and debug logging — copy the real file rather than this excerpt for a production deployment.

2.2 Register your miner

Add this to the Node.js service or script that runs your Worker. The snippet shows the minimum boot call seeding one Whatsminer device; replace the example IP address and password with your miner's values:

const { getKernel } = require('@tetherto/mdk')
const { startWhatsminerWorker } = require('./whatsminer-adapter')

const kernel = await getKernel()

const worker = await startWhatsminerWorker({
  workerId: 'whatsminer-rack-1',
  storeDir: './store/whatsminer-rack-1',
  seedDevices: [{
    info: { serialNum: 'WM-001' },
    opts: { address: '192.168.1.10', port: 4028, password: 'admin' }
  }]
})
await kernel.registerWorker(worker.runtime.getPublicKey())

Make sure each miner's IP is reachable from the machine or container running the Worker before registering. Commands act on physical hardware. Prioritize thermal safety.

The device list is fixed at construction — there is no registerThing/updateThing/forgetThings equivalent. Adding, updating, or removing a device means editing seedDevices and restarting the Worker.

The whatsminer-mdk-worker README documents the plugin's own mdk-contract.json, supported models, and connection options in full; the shared install pattern covers the broader deployment mechanics.

Troubleshooting

There is no minimal single-file development example to check readiness output against — the reference deployment is examples/mvp-site's full stack (npm start prints MDK_READY worker devices=<n> once the Whatsminer Worker is up).

If the Worker does not come up, or a mock port is already in use, follow miner troubleshooting.

Next steps

Understand the deployment topologies for running the Worker service
Review whatsminer-mdk-worker's own mdk-contract.json for telemetry units, command shapes, and error codes — it isn't vendored into this repo

Run a Whatsminer Worker

On this page