Skip to content

Pearl Mining

OpenJarvis can mine the Pearl Proof-of-Useful-Work chain through local LLM inference. The primary v1 path supports NVIDIA H100/H200 hosts running vLLM with Pearl's Docker miner. The consolidated Pearl integration also includes experimental Apple Silicon and CPU providers through the same MiningProvider registry.

Prerequisites

Requirement v1 expectation
GPU NVIDIA H100 or H200, sm_90a class, at least 70 GB VRAM
OS Linux with nvidia-container-toolkit configured
Docker Docker 24+ with GPU runtime access
Disk At least 200 GB free for the 70B model and build cache
Pearl node Reachable pearld JSON-RPC endpoint, default http://localhost:44107
Wallet Pearl address beginning with prl1q or prl1p

The default vLLM config uses gpu_memory_utilization = 0.96 and max_model_len = 8192 for the Pearl 70B mining model on H100/H200 80 GB GPUs.

To generate a wallet address with Pearl's Oyster wallet, run Pearl's wallet daemon and query it with prlctl --wallet --skipverify -s localhost:44207 getnewaddress. Do not reuse a wallet whose mnemonic has been pasted into logs, chat, or issue trackers.

Quick Start

uv sync --extra mining-pearl-vllm
export PEARLD_RPC_PASSWORD=<your-pearld-password>
export HF_TOKEN=<your-huggingface-token>

uv run jarvis mine init
uv run jarvis mine start
uv run jarvis mine status

mine init writes a [mining] config section and resolves the Pearl Docker image. If Pearl has not published a suitable image for the pinned ref, OpenJarvis falls back to building from the pinned Pearl source checkout. First builds can take 30-60 minutes.

On a shared NVIDIA host, restrict the miner to idle GPUs:

uv run jarvis mine init --cuda-visible-devices 0

This writes [mining.extra].cuda_visible_devices, which mine start passes to Docker instead of exposing every GPU on the machine.

Commands

  • jarvis mine models lists Pearl model support status.
  • jarvis mine inspect-model checks a Pearl model artifact before GPU launch.
  • jarvis mine doctor prints hardware, Docker, Pearl node, wallet, provider, and session checks.
  • jarvis mine init writes the local mining config and resolves the image.
  • jarvis mine start launches the Pearl miner container and writes the runtime sidecar.
  • jarvis mine stop stops the provider and removes the sidecar.
  • jarvis mine status reads live gateway metrics.
  • jarvis mine attach writes a sidecar for a miner you launched manually.
  • jarvis mine logs prints the Docker container log tail.
  • jarvis mine validate-model probes the active vLLM miner and gateway before promoting a planned Pearl model to validated.

Model Support

Run:

jarvis mine models

OpenJarvis only lists Pearl-compatible models published by the Pearl Research Labs Hugging Face org. Raw Hugging Face base models such as meta-llama/Llama-3.3-70B-Instruct or google/gemma-4-31B-it are not mineable by themselves; they need corresponding pearl-ai/*-pearl variants.

The supported Pearl model ids are:

pearl-ai/Llama-3.3-70B-Instruct-pearl
pearl-ai/Gemma-4-31B-it-pearl
pearl-ai/Llama-3.1-8B-Instruct-pearl

pearl-ai/Llama-3.3-70B-Instruct-pearl is the default validated model. Additional public pearl-ai/* artifacts may remain marked planned until they pass the OpenJarvis H100/H200 validation run.

When validating a Pearl org model on a mining host, run:

jarvis mine inspect-model \
  --model pearl-ai/Gemma-4-31B-it-pearl \
  --allow-planned

jarvis mine validate-model \
  --model pearl-ai/Gemma-4-31B-it-pearl \
  --allow-planned \
  --prompt "Say hello in one sentence." \
  --output gemma-4-31b-pearl-validation.json

Attach the JSON artifact to the validation issue when promoting additional models.

v1 Scope

v1 is solo mining only. OpenJarvis does not take fees, custody funds, generate wallet keys, run pools, or operate pearld. Users provide their own Pearl node and payout address.

Unsupported in this PR:

  • Pool mining and the future 20% OpenJarvis fee model
  • AMD GPU mining and non-Pearl backends
  • RTX 4090 or other non-Hopper NVIDIA GPUs
  • Wallet generation or transaction signing inside OpenJarvis

Troubleshooting

Run:

uv run jarvis mine doctor

Read the rows top-down. Fix the first failing dependency before retrying mine start. A Mac or AMD machine should fail honestly at provider capability; those paths are expected to land as separate providers.

Production Readiness

The NVIDIA path requires one real H100/H200 validation run before it should be marketed as a proven earning path. The developer runbook is ../development/mining-nvidia-validation.md.