@gridlock-compute/native-worker 0.1.1

package/README.md

@@ -0,0 +1,222 @@
+# worker-cli
+
+Headless GPU worker for the [Gridlock](https://grid-lock.tech) decentralized inference network. Connects to the [router](https://github.com/Gridlockcompute/router) over WebSocket, registers your **EVM wallet** (`0x…` on Robinhood Chain) as operator identity, and runs chat jobs locally via **Ollama** or **vLLM**.
+
+**Production router:** [https://api.grid-lock.tech](https://api.grid-lock.tech)
+
+## What it is
+
+`worker-cli` (npm package `@gridlock-compute/native-worker`) is the command-line worker client for operators who want to contribute GPU compute without a desktop UI. It:
+
+1. Detects your hardware (GPU or CPU) and runs a short throughput benchmark
+2. Registers with the Gridlock router (`POST /v1/workers/register`) and sets status **Active** so jobs can be dispatched
+3. Maintains REST heartbeats and a persistent WebSocket at `/v1/ws`
+4. Executes inference jobs pushed by the router and reports TTFT, TPOT, and token counts
+5. Optionally attaches a TEE attestation quote at registration and computes job attestation hashes for confidential work
+
+Use the same **0x EVM address** here as on the [web worker dashboard](https://grid-lock.tech/worker) so earnings, jobs, and connection status appear in one place.
+
+Set your **earnings wallet** on the worker dashboard (or via `PATCH /v1/workers/{address}/earnings-wallet`). SLA misses deduct from pending worker earnings; customers receive automatic ledger credits.
+
+Stake native ETH separately from the web console for fee-share boosts — the CLI never needs your private key.
+
+## Features
+
+- **Headless operation** — no Electron, no browser; ideal for servers and Linux GPU boxes
+- **EVM identity** — validates `0x` addresses locally before registration
+- **Live terminal dashboard** — status table with uptime, jobs, throughput, queue depth, and a progress bar while inference runs
+- **WebSocket job dispatch** — real-time job push from the router with automatic reconnect
+- **Hardware detection** — NVIDIA (`nvidia-smi`), AMD (`rocm-smi`), or `CPU · {model}` when no inference GPU is present
+- **Benchmark mode** — `--benchmark` runs throughput test and exits
+- **Confidential jobs** — registration attestation quote + per-job SHA-256 hash for TEE-tier work
+- **Configurable roles** — register as Prefill, Decode, or other worker roles via env/flag
+
+## Prerequisites
+
+- **Node.js** 18 or later
+- **NVIDIA GPU** with CUDA drivers (recommended for local inference)
+- **Ollama** ([download](https://ollama.com/download)) — recommended on Windows and macOS
+- **vLLM** — recommended on Linux/WSL with an OpenAI-compatible server on port 8000
+- An **EVM wallet address** (`0x…`) — private key never required in the CLI
+
+## Installation
+
+**From npm (recommended):**
+
+```bash
+npm install -g @gridlock-compute/native-worker
+gridlock-native-worker --help
+```
+
+**From source:**
+
+```bash
+git clone https://github.com/Gridlockcompute/worker-cli.git
+cd worker-cli
+npm install
+npm run build
+```
+
+Install globally from source (optional):
+
+```bash
+npm link
+gridlock-native-worker --help
+```
+
+Or run directly:
+
+```bash
+node dist/index.js --help
+```
+
+## Quick start
+
+```bash
+# 1. Install Ollama (https://ollama.com/download) or start vLLM on this machine
+
+# 2. Start the worker — connects to https://api.grid-lock.tech
+gridlock-native-worker --wallet 0xYourEvmAddress
+```
+
+On first run with Ollama, the worker lists installed models and prompts you to pick one (or pulls the default if none are installed).
+
+If you already have models, you'll see a selector like:
+
+```
+Installed Ollama models:
+
+  1. llama3.2:3b (2.0 GB)
+  2. phi3:mini (2.2 GB)
+  3. Pull llama3.1:8b (default — not installed yet)
+
+Select model [1-3, default 1]:
+```
+
+Pass `--model llama3.2:3b` or set `GRIDLOCK_OLLAMA_MODEL` to skip the prompt.
+
+Windows PowerShell example:
+
+```powershell
+npm install
+npm run build
+node dist/index.js --wallet 0xYourEvmAddress
+```
+
+## Configuration
+
+### CLI flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--wallet <address>` | — | EVM wallet address `0x…` (**required**, or set `GRIDLOCK_WALLET`) |
+| `--inference <backend>` | `auto` | `auto`, `ollama`, or `vllm` |
+| `--model <tag>` | — | Ollama model (e.g. `llama3.2:3b`); interactive picker if omitted and multiple models exist |
+| `--benchmark` | — | Run benchmark only, then exit |
+| `--version` | — | Print version |
+| `--help` | — | Print help |
+
+### Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GRIDLOCK_WALLET` | — | EVM address (alternative to `--wallet`) |
+| `GRIDLOCK_EARNINGS_WALLET` | operator wallet | Payout wallet sent at registration (`earnings_wallet`) |
+| `GRIDLOCK_INFERENCE` | `auto` | Inference backend: `auto`, `ollama`, or `vllm` |
+| `GRIDLOCK_OLLAMA_URL` | Ollama on this machine (port 11434) | Override if Ollama listens elsewhere |
+| `GRIDLOCK_OLLAMA_MODEL` | `llama3.1:8b` | Ollama model tag |
+| `GRIDLOCK_VLLM_URL` | vLLM on this machine (port 8000) | OpenAI-compatible vLLM base URL |
+| `GRIDLOCK_VLLM_MODEL` | `meta-llama/Llama-3.1-8B-Instruct` | vLLM model id |
+| `GRIDLOCK_ROLE` | `Prefill` | Worker role sent at registration |
+| `GRIDLOCK_TEE_CAPABLE` | `false` | Set `true` to register as TEE-capable |
+| `GRIDLOCK_ATTESTATION_QUOTE_FILE` | — | Path to production NRAS/SEV quote JSON for registration |
+| `GRIDLOCK_ATTESTATION_QUOTE_JSON` | — | Inline attestation quote JSON (alternative to file) |
+| `GRIDLOCK_TEE_TYPE` | `nvidia_cc` | TEE type in dev quotes (`nvidia_cc`, `amd_sev_snp`) |
+| `GRIDLOCK_PLAIN_LOGS` | — | Set `true` to disable the live dashboard and use plain log lines |
+
+All workers connect to **[https://api.grid-lock.tech](https://api.grid-lock.tech)** for registration, heartbeats, and WebSocket job dispatch. Inference (Ollama/vLLM) runs on your machine.
+
+Only **one worker process per wallet** is allowed. A second instance will exit immediately (lock file in `~/.gridlock/`).
+
+## Usage examples
+
+**Standard run:**
+
+```bash
+export GRIDLOCK_WALLET=0xYourEvmAddress
+gridlock-native-worker
+```
+
+**Force vLLM backend:**
+
+```bash
+gridlock-native-worker --wallet 0xYourEvmAddress --inference vllm
+```
+
+**Benchmark only (no registration):**
+
+```bash
+gridlock-native-worker --wallet 0xYourEvmAddress --benchmark
+```
+
+**TEE / confidential registration (dev attestation quote from router challenge):**
+
+```bash
+GRIDLOCK_TEE_CAPABLE=true gridlock-native-worker --wallet 0xYourEvmAddress
+```
+
+For production CC GPUs, provide a vendor attestation quote:
+
+```bash
+export GRIDLOCK_TEE_CAPABLE=true
+export GRIDLOCK_ATTESTATION_QUOTE_FILE=/path/to/quote.json
+gridlock-native-worker --wallet 0xYourEvmAddress
+```
+
+## On-chain registration
+
+The CLI does **not** sign Robinhood Chain transactions itself. When the router has `WORKER_REGISTRY_ONCHAIN_ENABLED=true` and `EVM_*` contract addresses configured, the **router** may register your worker on-chain after `POST /v1/workers/register`. Staking, payouts, and billing are handled via the web dashboard and router APIs.
+
+After starting, the worker connects to `wss://api.grid-lock.tech/v1/ws`, sends `worker:register` with `worker_type: native`, and waits for `job:new` messages.
+
+Monitor your operator on the web: [https://grid-lock.tech/worker](https://grid-lock.tech/worker)
+
+## Development
+
+```bash
+npm run dev          # tsx watch — src/index.ts
+npm run build        # compile TypeScript → dist/
+npm start            # node dist/index.js
+```
+
+Project layout:
+
+```
+worker-cli/
+├── src/
+│   ├── index.ts            # CLI entry (commander)
+│   ├── worker.ts           # WebSocket session + job loop
+│   ├── wallet.ts           # EVM address validation
+│   ├── attestation-quote.ts # Registration TEE quotes
+│   ├── inference.ts        # Ollama / vLLM adapters
+│   ├── ollama.ts           # Ollama bootstrap
+│   ├── gpu.ts              # GPU detection
+│   └── attestation.ts      # Per-job confidential hashing
+├── bin/
+│   └── gridlock-native-worker.cjs
+└── package.json
+```
+
+## Related repos
+
+| Repo | Role |
+|------|------|
+| [router](https://github.com/Gridlockcompute/router) | Hono API — job routing, WebSocket hub, billing |
+| [worker-desktop](https://github.com/Gridlockcompute/worker-desktop) | Electron GUI worker with setup wizard |
+| [contracts](https://github.com/Gridlockcompute/gridlockcompute) | EVM Solidity contracts on Robinhood Chain |
+
+**Website:** [https://grid-lock.tech](https://grid-lock.tech) · **API docs:** [https://grid-lock.tech/docs](https://grid-lock.tech/docs)
+
+## License
+
+MIT

package/bin/gridlock-native-worker.cjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+"use strict";
+
+import("../dist/index.js");

package/dist/attestation-quote.d.ts

@@ -0,0 +1,11 @@
+export interface AttestationQuotePayload {
+    worker_pubkey: string;
+    tee_type: string;
+    nonce: string;
+    enclave_pubkey: string;
+    report_bytes: string;
+    timestamp: number;
+    certificate_chain?: string[];
+}
+/** Resolve TEE attestation quote for worker registration (production file or dev challenge). */
+export declare function resolveRegistrationAttestationQuote(backendUrl: string, wallet: string, teeCapable: boolean): Promise<AttestationQuotePayload | undefined>;

package/dist/attestation-quote.js

@@ -0,0 +1,56 @@
+import { readFileSync } from "node:fs";
+async function fetchChallenge(backendUrl, wallet) {
+    const base = backendUrl.replace(/\/$/, "");
+    const res = await fetch(`${base}/v1/attestation/challenge?wallet=${encodeURIComponent(wallet)}`);
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`attestation challenge failed (${res.status}): ${text.slice(0, 200)}`);
+    }
+    const data = (await res.json());
+    if (!data.nonce)
+        throw new Error("attestation challenge missing nonce");
+    return data.nonce;
+}
+function loadQuoteFromEnv() {
+    const file = process.env.GRIDLOCK_ATTESTATION_QUOTE_FILE?.trim();
+    if (file) {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    const json = process.env.GRIDLOCK_ATTESTATION_QUOTE_JSON?.trim();
+    if (json) {
+        return JSON.parse(json);
+    }
+    return null;
+}
+function buildDevAttestationQuote(wallet, nonce) {
+    const reportBytes = Buffer.from(`mock-${wallet.toLowerCase()}-${nonce}-${Date.now()}`, "utf8").toString("base64");
+    return {
+        worker_pubkey: wallet,
+        tee_type: process.env.GRIDLOCK_TEE_TYPE?.trim() || "nvidia_cc",
+        nonce,
+        enclave_pubkey: process.env.GRIDLOCK_ENCLAVE_PUBKEY?.trim() || wallet,
+        report_bytes: reportBytes,
+        timestamp: Date.now(),
+        certificate_chain: [],
+    };
+}
+/** Resolve TEE attestation quote for worker registration (production file or dev challenge). */
+export async function resolveRegistrationAttestationQuote(backendUrl, wallet, teeCapable) {
+    if (!teeCapable)
+        return undefined;
+    const fromEnv = loadQuoteFromEnv();
+    if (fromEnv) {
+        console.log("[attestation] Using quote from GRIDLOCK_ATTESTATION_QUOTE_FILE / _JSON");
+        return fromEnv;
+    }
+    try {
+        const nonce = await fetchChallenge(backendUrl, wallet);
+        console.log("[attestation] Dev quote from router challenge (production CC GPUs: set GRIDLOCK_ATTESTATION_QUOTE_FILE)");
+        return buildDevAttestationQuote(wallet, nonce);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        console.warn(`[attestation] Skipping registration quote: ${msg}`);
+        return undefined;
+    }
+}

package/dist/attestation.d.ts

@@ -0,0 +1,2 @@
+/** Must match gridlock-backend/src/attestation.ts computeJobAttestationHash. */
+export declare function computeJobAttestationHash(jobId: string, workerAddress: string, response: string): string;

package/dist/attestation.js

@@ -0,0 +1,11 @@
+import { createHash } from "node:crypto";
+/** Must match gridlock-backend/src/attestation.ts computeJobAttestationHash. */
+export function computeJobAttestationHash(jobId, workerAddress, response) {
+    return createHash("sha256")
+        .update(JSON.stringify({
+        jobId,
+        workerAddress,
+        response: response.slice(0, 512),
+    }))
+        .digest("hex");
+}

package/dist/banner.d.ts

@@ -0,0 +1,2 @@
+/** Print banner; returns how many terminal rows it consumed. */
+export declare function printStartupBanner(): number;

package/dist/banner.js

@@ -0,0 +1,41 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const LIME_GREEN = "\x1b[38;2;182;255;60m";
+const RESET = "\x1b[0m";
+const CHEVRONS = `
+   █████████  ███████████   █████ ██████████   █████          ███████      █████████  █████   ████
+  ███▒▒▒▒▒███▒▒███▒▒▒▒▒███ ▒▒███ ▒▒███▒▒▒▒███ ▒▒███         ███▒▒▒▒▒███   ███▒▒▒▒▒███▒▒███   ███▒ 
+ ███     ▒▒▒  ▒███    ▒███  ▒███  ▒███   ▒▒███ ▒███        ███     ▒▒███ ███     ▒▒▒  ▒███  ███   
+▒███          ▒██████████   ▒███  ▒███    ▒███ ▒███       ▒███      ▒███▒███          ▒███████    
+▒███    █████ ▒███▒▒▒▒▒███  ▒███  ▒███    ▒███ ▒███       ▒███      ▒███▒███          ▒███▒▒███   
+▒▒███  ▒▒███  ▒███    ▒███  ▒███  ▒███    ███  ▒███      █▒▒███     ███ ▒▒███     ███ ▒███ ▒▒███  
+ ▒▒█████████  █████   █████ █████ ██████████   ███████████ ▒▒▒███████▒   ▒▒█████████  █████ ▒▒████
+  ▒▒▒▒▒▒▒▒▒  ▒▒▒▒▒   ▒▒▒▒▒ ▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒   ▒▒▒▒▒▒▒▒▒▒▒    ▒▒▒▒▒▒▒      ▒▒▒▒▒▒▒▒▒  ▒▒▒▒▒   ▒▒▒▒ 
+                                                                                                  
+                                                                                                  
+                                                                                                                                                                                                  
+`.trimEnd();
+function shouldColorize() {
+    const { FORCE_COLOR, NO_COLOR } = process.env;
+    if (FORCE_COLOR !== undefined) {
+        return FORCE_COLOR !== "0" && FORCE_COLOR.toLowerCase() !== "false";
+    }
+    if (NO_COLOR !== undefined)
+        return false;
+    return process.stdout.isTTY === true;
+}
+function colorize(text) {
+    if (!shouldColorize())
+        return text;
+    return `${LIME_GREEN}${text}${RESET}`;
+}
+/** Print banner; returns how many terminal rows it consumed. */
+export function printStartupBanner() {
+    const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+    console.log(colorize(CHEVRONS));
+    console.log(colorize(`  Gridlock Native Worker v${pkg.version}`));
+    console.log();
+    return CHEVRONS.split("\n").length + 2;
+}

package/dist/config.d.ts

@@ -0,0 +1,21 @@
+/** Gridlock API — all workers connect here. */
+export declare const GRIDLOCK_API_URL = "https://api.grid-lock.tech";
+export declare function getBackendUrl(): string;
+/** @deprecated Use getBackendUrl() */
+export declare const DEFAULT_BACKEND_URL = "https://api.grid-lock.tech";
+/** Gridlock router — jobs, registration, WebSocket. */
+export declare const ROUTER_URL = "https://api.grid-lock.tech";
+/** vLLM OpenAI-compatible API on this machine (separate inference process). */
+export declare const VLLM_BASE_URL: string;
+/** Resolved at runtime after probing Ollama on this host. */
+export declare let OLLAMA_URL: string;
+export declare function setOllamaUrl(url: string): void;
+export declare const OLLAMA_URL_CANDIDATES: string[];
+export type InferenceBackend = "auto" | "ollama" | "vllm";
+export declare const INFERENCE_BACKEND: InferenceBackend;
+export declare const VLLM_MODEL: string;
+export declare const OLLAMA_MODEL: string;
+export declare const DEFAULT_ROLE: string;
+export declare const BENCHMARK_TOKENS = 32;
+export declare const MAX_OUTPUT_TOKENS = 512;
+export declare function wsUrl(httpBase: string): string;

package/dist/config.js

@@ -0,0 +1,34 @@
+/** Gridlock API — all workers connect here. */
+export const GRIDLOCK_API_URL = "https://api.grid-lock.tech";
+export function getBackendUrl() {
+    return GRIDLOCK_API_URL;
+}
+/** @deprecated Use getBackendUrl() */
+export const DEFAULT_BACKEND_URL = GRIDLOCK_API_URL;
+/** Gridlock router — jobs, registration, WebSocket. */
+export const ROUTER_URL = GRIDLOCK_API_URL;
+const DEFAULT_OLLAMA_PORT = 11434;
+const DEFAULT_VLLM_PORT = 8000;
+/** vLLM OpenAI-compatible API on this machine (separate inference process). */
+export const VLLM_BASE_URL = (process.env.GRIDLOCK_VLLM_URL ?? `http://127.0.0.1:${DEFAULT_VLLM_PORT}/v1`).replace(/\/$/, "");
+/** Resolved at runtime after probing Ollama on this host. */
+export let OLLAMA_URL = (process.env.GRIDLOCK_OLLAMA_URL ?? `http://127.0.0.1:${DEFAULT_OLLAMA_PORT}`).replace(/\/$/, "");
+export function setOllamaUrl(url) {
+    OLLAMA_URL = url.replace(/\/$/, "");
+}
+export const OLLAMA_URL_CANDIDATES = [
+    process.env.GRIDLOCK_OLLAMA_URL?.replace(/\/$/, ""),
+    `http://127.0.0.1:${DEFAULT_OLLAMA_PORT}`,
+].filter(Boolean);
+export const INFERENCE_BACKEND = (process.env.GRIDLOCK_INFERENCE ?? "auto");
+export const VLLM_MODEL = process.env.GRIDLOCK_VLLM_MODEL ?? process.env.GRIDLOCK_MODEL ?? "meta-llama/Llama-3.1-8B-Instruct";
+export const OLLAMA_MODEL = process.env.GRIDLOCK_OLLAMA_MODEL ?? "llama3.1:8b";
+export const DEFAULT_ROLE = process.env.GRIDLOCK_ROLE ?? "Prefill";
+export const BENCHMARK_TOKENS = 32;
+export const MAX_OUTPUT_TOKENS = 512;
+export function wsUrl(httpBase) {
+    const base = httpBase.replace(/\/$/, "");
+    if (base.startsWith("https://"))
+        return base.replace("https://", "wss://") + "/v1/ws";
+    return base.replace("http://", "ws://") + "/v1/ws";
+}

package/dist/console-io.d.ts

@@ -0,0 +1,2 @@
+/** Log without breaking the live stdout dashboard (uses stderr in dashboard mode). */
+export declare function workerLog(...args: unknown[]): void;

package/dist/console-io.js

@@ -0,0 +1,10 @@
+import { isDashboardMode } from "./dashboard.js";
+/** Log without breaking the live stdout dashboard (uses stderr in dashboard mode). */
+export function workerLog(...args) {
+    if (isDashboardMode()) {
+        console.error(...args);
+    }
+    else {
+        console.log(...args);
+    }
+}

package/dist/dashboard.d.ts

@@ -0,0 +1,54 @@
+export type ConnectionStatus = "starting" | "connected" | "disconnected" | "reconnecting";
+export interface DashboardSnapshot {
+    wallet: string;
+    api: string;
+    hardware: string;
+    model: string;
+    inference: string;
+    benchmarkTokPerSec: number;
+    connection: ConnectionStatus;
+    workerStatus: string;
+    jobsCompleted: number;
+    jobsFailed: number;
+    jobsToday: number;
+    tokensTodayBase: number;
+    liveTokPerSec: number | null;
+    queueJobs: number | null;
+    inflightJobs: number | null;
+    workerInflightJobs: number | null;
+    currentJob: {
+        id: string;
+        tokens: number;
+        maxTokens: number;
+        startedAt: number;
+    } | null;
+}
+export interface LiveStatsPatch {
+    jobsToday: number;
+    tokensToday: number;
+    jobsFailedToday: number;
+    workerStatus: string;
+    wsTokPerSec: number;
+    queueJobs: number;
+    inflightJobs: number;
+    workerInflightJobs: number;
+}
+export interface DashboardOptions {
+    /** First terminal row for the dashboard box (1-based, below banner). */
+    anchorRow?: number;
+}
+export interface WorkerDashboard {
+    update(patch: Partial<DashboardSnapshot>): void;
+    applyLiveStats(stats: LiveStatsPatch): void;
+    setJob(jobId: string, maxTokens: number): void;
+    setJobProgress(tokens: number, maxTokens?: number): void;
+    clearJob(jobId: string, success: boolean, tokens: number, elapsedMs: number): void;
+    setConnection(status: ConnectionStatus): void;
+    note(message: string): void;
+    start(): void;
+    stop(): void;
+}
+/** Interactive TTY dashboard — suppresses startup log lines. */
+export declare function isDashboardMode(): boolean;
+export declare function createDashboard(initial: DashboardSnapshot, options?: DashboardOptions): WorkerDashboard;
+export declare function plainLog(msg: string): void;