Index

mining

Pearl mining subsystem.

See spec docs/design/2026-05-05-vllm-pearl-mining-integration-design.md.

Provider modules are soft-imported below — each one fails gracefully if the mining-pearl (or future mining-pearl-mlx etc.) extra isn't installed.

Classes

MiningCapabilities dataclass

MiningCapabilities(
    supported: bool,
    reason: Optional[str] = None,
    estimated_hashrate: Optional[float] = None,
)

Result of a provider's detect() call.

reason is human-readable and surfaced verbatim by diapason mine doctor when supported=False.

MiningConfig dataclass

MiningConfig(
    provider: str,
    wallet_address: str,
    submit_target: SubmitTarget,
    fee_bps: int = 0,
    fee_payout_address: Optional[str] = None,
    extra: dict[str, Any] = dict(),
)

User-supplied mining configuration.

Loaded from the [mining] TOML section by core/config.py.

MiningProvider

Bases: ABC

A mining provider — orchestrates a Pearl mining session.

One provider per (hardware, engine, model) combo. All future hardware/engine paths (Apple Silicon, AMD, Ollama) implement this exact contract. See spec §4.4.

Methods:

detect abstractmethod classmethod

detect(
    hw: HardwareInfo, engine_id: str, model: str
) -> MiningCapabilities

Return whether this provider can run on the given combo.

Must be a pure inspection — no subprocess, no network, no Docker. Used by diapason mine doctor and diapason mine init for fast capability reporting.

Source code in src/diapason/mining/_stubs.py

@classmethod
@abstractmethod
def detect(cls, hw: HardwareInfo, engine_id: str, model: str) -> MiningCapabilities:
    """Return whether this provider can run on the given combo.

    Must be a pure inspection — no subprocess, no network, no Docker. Used
    by ``diapason mine doctor`` and ``diapason mine init`` for fast capability
    reporting.
    """

PoolTarget dataclass

PoolTarget(url: str, worker_id: Optional[str] = None)

Mine through an OJ-operated pool. v2 — raises NotImplementedError in v1.

Sidecar

Read/write helpers for ~/.diapason/runtime/mining.json.

Methods:

write staticmethod

write(path: Path, payload: dict[str, Any]) -> None

Atomically write the sidecar JSON to path.

Source code in src/diapason/mining/_stubs.py

@staticmethod
def write(path: Path, payload: dict[str, Any]) -> None:
    """Atomically write the sidecar JSON to ``path``."""
    path.parent.mkdir(parents=True, exist_ok=True)
    # Atomic write: tmp file + rename
    fd, tmp = tempfile.mkstemp(prefix=".mining-", dir=str(path.parent))
    try:
        with os.fdopen(fd, "w") as fh:
            json.dump(payload, fh, indent=2, sort_keys=True)
        os.replace(tmp, path)
    except Exception:
        try:
            os.unlink(tmp)
        except OSError:
            pass
        raise

SoloTarget dataclass

SoloTarget(pearld_rpc_url: str)

Mine directly to a pearld node. v1 default.