The integration model
What MDK can be extended with, and by which of its two extension points
Two extension points, named after what they extend
| Worker plugin | Gateway plugin | |
|---|---|---|
| Extends | The Worker tier | The Gateway tier |
| Declares itself with | mdk-contract.json (the Worker contract) | mdk-plugin.json |
| That declaration is read by | Kernel today (routing, validation); no other reader exists in this repo today | The Gateway loader (routes, auth flag) |
| Job | Speak one device family's native protocol; expose it as telemetry + commands | Add an HTTP route: aggregate, authenticate, or otherwise sit between a caller and @tetherto/mdk-client |
The naming is literal: a Worker plugin is a plugin for a Worker, a Gateway plugin is a plugin for the Gateway. Neither extends Kernel: Kernel has no plugin system, by design (see Architecture).
mdk-plugin.json gets the same treatment, for Gateway plugins
A Gateway plugin's manifest declares its routes (id, handler, http.method/http.path, response schema,
constraints, examples, errors, safety). The Gateway's plugin loader reads it to mount routes and validate the
manifest shape at load time; nothing about it is hand-wired into the Gateway's own code path per plugin.
Workers are not only hardware
A Worker plugin wraps whatever answers to "one device, one connection, one set of telemetry/commands"; that's just as often a non-hardware integration:
- A pool API Worker: telemetry is your hashrate/earnings from the pool's own API, "commands" might be switching workers between pools; no physical device involved at all.
- An accounting sync Worker: telemetry is a ledger balance or a sync status pulled from a third-party service, with no ASIC anywhere in the picture.
Both get the exact same treatment from Kernel as a physical miner: identity, capabilities, telemetry pull, command dispatch. Kernel does not know or care that there is no hardware behind either one.
What this buys you
Write the integration once (one Worker plugin per device family, one Gateway plugin per route you need) and every consumer built against the standard round trip works with it for free: the same dashboard code, the same agent tooling, the same Gateway auth model, regardless of which device family or which route it's actually talking to underneath.
Contract versioning today
There is no enforced compatibility mechanism between contract versions today. A Worker plugin's mdk-contract.json
has no version field of its own: the package's package.json semver is the only version signal, and nothing in
Kernel or the Gateway checks it against a caller's expectations. In practice this means: a contract's shape is
whatever the currently-loaded plugin declares, and there's no compatibility gate protecting a caller written
against an older shape. If a contract's telemetry or command names change, that's a breaking change for anything
built against the old names, with no automated warning today.
Next steps
- Build a Worker plugin for a new device family
- Understand the Gateway plugin authoring flow
- Understand the storage model: what a Worker plugin decides to persist
- Understand architecture: where both extension points sit in the round trip
Next steps
- Build a Worker plugin for a new device family
- Understand the storage model
- Understand architecture