@circuit-llm/node 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Circuit LLM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# @circuit-llm/node
+
+> Join and manage a Circuit mesh node from code: the inference-mesh control plane (register / ready / heartbeat) and the public node registry (announce / ping). The heavy GPU serving stays in the node image.
+
+Part of the **[Circuit SDK](https://github.com/Circuit-LLM/circuit-sdk)**. [Contribute a node →](https://github.com/Circuit-LLM/circuit-sdk/blob/main/docs/contributing-a-node.md)
+
+## Install
+
+```bash
+npm install @circuit-llm/node
+```
+
+## Usage
+
+```ts
+import { MeshControl, generateMeshIdentity } from '@circuit-llm/node';
+
+const identity = generateMeshIdentity();
+const mesh = new MeshControl({ controlUrl: 'http://control:18932', identity });
+const { assignment } = await mesh.register({
+  endpoint: ['1.2.3.4', 5000],
+  capacityLayers: 40,
+  modelFp: 'qwen2.5-72b-awq',
+});
+await mesh.ready();   // …then heartbeat
+```
+
+Also: `NodeRegistry` (public announce/ping) and `signMeshBody` / `verifyMeshBody`. Pair with [@circuit-llm/onchain](https://github.com/Circuit-LLM/circuit-sdk/tree/main/packages/onchain) to verify what's staked.

package/dist/index.d.ts

@@ -0,0 +1,125 @@
+import crypto from 'node:crypto';
+import { Identity } from '@circuit-llm/core';
+
+interface MeshIdentity {
+    /** raw ed25519 public key, hex (this IS the node_id). */
+    nodeId: string;
+    /** raw ed25519 seed, hex (32 bytes) — for persistence. */
+    seedHex: string;
+    /** private KeyObject — for signing. */
+    privateKey: crypto.KeyObject;
+}
+declare function generateMeshIdentity(): MeshIdentity;
+/** Reconstruct a mesh identity from its 32-byte seed (hex). */
+declare function meshIdentityFromSeed(seedHex: string): MeshIdentity;
+/** Stamp {node_id, ts} and attach an ed25519 `sig` over the compact sorted JSON of
+ *  the body-minus-sig. `now` (unix seconds) is injectable for tests. */
+declare function signMeshBody(identity: MeshIdentity, body: Record<string, unknown>, now?: number): Record<string, unknown>;
+/** Server-side counterpart — verify a signed mesh body. */
+declare function verifyMeshBody(body: Record<string, unknown>): boolean;
+
+interface MeshControlOptions {
+    controlUrl: string;
+    /** Required to register (signs the body); ready/heartbeat/drain only need the node_id. */
+    identity?: MeshIdentity;
+    nodeId?: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+interface RegisterParams {
+    endpoint: [string, number];
+    capacityLayers: number;
+    modelFp: string;
+    region?: string;
+    payoutWallet?: string;
+    reachability?: string;
+    orchestrator?: boolean;
+    /** Re-register for an already-loaded slot. */
+    loadedLayers?: [number, number];
+}
+interface RegisterResult {
+    assignment: {
+        start: number;
+        end: number;
+    } | null;
+    orch_index?: number | null;
+    model_fp: string;
+    session_key: string;
+    coordinator: [string, number];
+    replication: number;
+}
+declare class MeshControlError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+declare class MeshControl {
+    readonly nodeId: string | undefined;
+    private readonly base;
+    private readonly identity?;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(opts: MeshControlOptions);
+    /** Join the mesh. Requires an identity (signs the request). Returns the assigned
+     *  slot, derived session key, etc. */
+    register(p: RegisterParams): Promise<RegisterResult>;
+    /** Mark this node READY (serving). */
+    ready(): Promise<{
+        ok?: boolean;
+    }>;
+    /** Heartbeat. `registered:false` means the control plane forgot us → re-register. */
+    heartbeat(): Promise<{
+        ok?: boolean;
+        registered?: boolean;
+    }>;
+    /** Gracefully leave. */
+    drain(): Promise<{
+        ok?: boolean;
+    }>;
+    /** Current mesh topology (free). */
+    topology(): Promise<{
+        slots: unknown[];
+        coverage_ok: boolean;
+        model_fp?: string;
+        replication?: number;
+    }>;
+    health(): Promise<unknown>;
+    private requireNodeId;
+    private post;
+    private get;
+    private parse;
+}
+
+interface NodeRegistryOptions {
+    registryUrl: string;
+    identity: Identity;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+interface AnnounceParams {
+    version: string;
+    shards?: string[];
+    region?: string;
+    agentRunning?: boolean;
+    apiPort?: number | null;
+    [k: string]: unknown;
+}
+declare class NodeRegistry {
+    readonly nodeId: string;
+    private readonly base;
+    private readonly identity;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(opts: NodeRegistryOptions);
+    /** Register this node; returns the registered node record. */
+    announce(p: AnnounceParams): Promise<unknown>;
+    /** Heartbeat with an optional status update. */
+    ping(update?: Record<string, unknown>): Promise<unknown>;
+    /** Remove this node's record. */
+    deregister(): Promise<unknown>;
+    /** List active peers (optionally filtered, e.g. { shard }). */
+    getPeers(filters?: Record<string, string>): Promise<unknown[]>;
+    private signedPost;
+    private parse;
+}
+
+export { type AnnounceParams, MeshControl, MeshControlError, type MeshControlOptions, type MeshIdentity, NodeRegistry, type NodeRegistryOptions, type RegisterParams, type RegisterResult, generateMeshIdentity, meshIdentityFromSeed, signMeshBody, verifyMeshBody };

package/dist/index.js

@@ -0,0 +1,223 @@
+// src/mesh-identity.ts
+import crypto from "crypto";
+import { stableStringify } from "@circuit-llm/core";
+var PKCS8_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+var SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+function rawPubHex(pub) {
+  const der = pub.export({ type: "spki", format: "der" });
+  return Buffer.from(der.subarray(der.length - 32)).toString("hex");
+}
+function rawSeedHex(priv) {
+  const der = priv.export({ type: "pkcs8", format: "der" });
+  return Buffer.from(der.subarray(der.length - 32)).toString("hex");
+}
+function generateMeshIdentity() {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
+  return { nodeId: rawPubHex(publicKey), seedHex: rawSeedHex(privateKey), privateKey };
+}
+function meshIdentityFromSeed(seedHex) {
+  const seed = Buffer.from(seedHex, "hex");
+  if (seed.length !== 32) throw new Error("ed25519 seed must be 32 bytes (64 hex chars)");
+  const privateKey = crypto.createPrivateKey({
+    key: Buffer.concat([PKCS8_PREFIX, seed]),
+    format: "der",
+    type: "pkcs8"
+  });
+  return { nodeId: rawPubHex(crypto.createPublicKey(privateKey)), seedHex, privateKey };
+}
+function signMeshBody(identity, body, now = Math.floor(Date.now() / 1e3)) {
+  const stamped = { ...body, node_id: identity.nodeId, ts: now };
+  const sig = crypto.sign(null, Buffer.from(stableStringify(stamped)), identity.privateKey).toString("hex");
+  return { ...stamped, sig };
+}
+function verifyMeshBody(body) {
+  try {
+    const sig = String(body.sig);
+    const nodeId = String(body.node_id);
+    const pub = crypto.createPublicKey({
+      key: Buffer.concat([SPKI_PREFIX, Buffer.from(nodeId, "hex")]),
+      format: "der",
+      type: "spki"
+    });
+    const rest = { ...body };
+    delete rest.sig;
+    return crypto.verify(null, Buffer.from(stableStringify(rest)), pub, Buffer.from(sig, "hex"));
+  } catch {
+    return false;
+  }
+}
+
+// src/mesh-control.ts
+var MeshControlError = class extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.name = "MeshControlError";
+    this.status = status;
+  }
+};
+var MeshControl = class {
+  nodeId;
+  base;
+  identity;
+  fetchImpl;
+  timeoutMs;
+  constructor(opts) {
+    this.base = opts.controlUrl.replace(/\/$/, "");
+    this.identity = opts.identity;
+    this.nodeId = opts.identity?.nodeId ?? opts.nodeId;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.timeoutMs = opts.timeoutMs ?? 1e4;
+  }
+  /** Join the mesh. Requires an identity (signs the request). Returns the assigned
+   *  slot, derived session key, etc. */
+  async register(p) {
+    if (!this.identity) throw new Error("register requires a MeshIdentity to sign the request");
+    const body = {
+      endpoint: p.endpoint,
+      capacity_layers: p.capacityLayers,
+      model_fp: p.modelFp,
+      reachability: p.reachability ?? "public",
+      region: p.region ?? "",
+      payout_wallet: p.payoutWallet ?? "",
+      orchestrator: !!p.orchestrator
+    };
+    if (p.loadedLayers) body.loaded_layers = p.loadedLayers;
+    return this.post("/register", signMeshBody(this.identity, body));
+  }
+  /** Mark this node READY (serving). */
+  ready() {
+    return this.post("/ready", { node_id: this.requireNodeId() });
+  }
+  /** Heartbeat. `registered:false` means the control plane forgot us → re-register. */
+  heartbeat() {
+    return this.post("/heartbeat", { node_id: this.requireNodeId() });
+  }
+  /** Gracefully leave. */
+  drain() {
+    return this.post("/drain", { node_id: this.requireNodeId() });
+  }
+  /** Current mesh topology (free). */
+  topology() {
+    return this.get("/topology");
+  }
+  health() {
+    return this.get("/health");
+  }
+  requireNodeId() {
+    if (!this.nodeId) throw new Error("no node_id (pass identity or nodeId)");
+    return this.nodeId;
+  }
+  async post(path, body) {
+    const res = await this.fetchImpl(`${this.base}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(this.timeoutMs)
+    });
+    return this.parse(res, path);
+  }
+  async get(path) {
+    const res = await this.fetchImpl(`${this.base}${path}`, { signal: AbortSignal.timeout(this.timeoutMs) });
+    return this.parse(res, path);
+  }
+  async parse(res, path) {
+    const text = await res.text();
+    let body;
+    try {
+      body = text ? JSON.parse(text) : null;
+    } catch {
+      body = text;
+    }
+    if (!res.ok) {
+      const msg = body?.error ?? `HTTP ${res.status}`;
+      throw new MeshControlError(res.status, `${path}: ${msg}`);
+    }
+    return body;
+  }
+};
+
+// src/node-registry.ts
+import { signRequest } from "@circuit-llm/core";
+var NodeRegistry = class {
+  nodeId;
+  base;
+  identity;
+  fetchImpl;
+  timeoutMs;
+  constructor(opts) {
+    this.base = opts.registryUrl.replace(/\/$/, "");
+    this.identity = opts.identity;
+    this.nodeId = opts.identity.nodeId;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.timeoutMs = opts.timeoutMs ?? 1e4;
+  }
+  /** Register this node; returns the registered node record. */
+  async announce(p) {
+    const { version, shards, region, agentRunning, apiPort, ...extra } = p;
+    const body = {
+      nodeId: this.nodeId,
+      version,
+      shards: shards ?? ["all"],
+      region: region ?? "unknown",
+      agentRunning: agentRunning ?? false,
+      apiPort: apiPort ?? null,
+      ...extra
+    };
+    const r = await this.signedPost("/api/network/nodes/announce", body);
+    return r.node ?? r;
+  }
+  /** Heartbeat with an optional status update. */
+  ping(update = {}) {
+    return this.signedPost("/api/network/nodes/ping", { nodeId: this.nodeId, ...update });
+  }
+  /** Remove this node's record. */
+  async deregister() {
+    const headers = signRequest(this.identity, {});
+    const res = await this.fetchImpl(`${this.base}/api/network/nodes/${encodeURIComponent(this.nodeId)}`, {
+      method: "DELETE",
+      headers,
+      signal: AbortSignal.timeout(this.timeoutMs)
+    });
+    return this.parse(res);
+  }
+  /** List active peers (optionally filtered, e.g. { shard }). */
+  async getPeers(filters = {}) {
+    const qs = new URLSearchParams(filters).toString();
+    const res = await this.fetchImpl(`${this.base}/api/network/nodes${qs ? `?${qs}` : ""}`, {
+      signal: AbortSignal.timeout(this.timeoutMs)
+    });
+    const r = await this.parse(res);
+    return r.nodes ?? [];
+  }
+  async signedPost(path, body) {
+    const headers = signRequest(this.identity, body);
+    const res = await this.fetchImpl(`${this.base}${path}`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(this.timeoutMs)
+    });
+    return this.parse(res);
+  }
+  async parse(res) {
+    const text = await res.text();
+    let body;
+    try {
+      body = text ? JSON.parse(text) : null;
+    } catch {
+      body = text;
+    }
+    if (!res.ok) throw new Error(body?.error ?? `HTTP ${res.status}`);
+    return body;
+  }
+};
+export {
+  MeshControl,
+  MeshControlError,
+  NodeRegistry,
+  generateMeshIdentity,
+  meshIdentityFromSeed,
+  signMeshBody,
+  verifyMeshBody
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@circuit-llm/node",
+  "version": "0.2.1",
+  "description": "Circuit SDK node — join/manage a mesh node from code: the inference-mesh control plane (register/ready/heartbeat) + the public node registry (announce/ping). The heavy GPU serving stays in the node image.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --conditions=development --test test/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json",
+    "build": "tsup src/index.ts --format esm --dts --clean --out-dir dist",
+    "prepack": "tsup src/index.ts --format esm --dts --clean --out-dir dist"
+  },
+  "dependencies": {
+    "@circuit-llm/core": "0.2.1"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Circuit-LLM/circuit-sdk.git",
+    "directory": "packages/node"
+  },
+  "homepage": "https://github.com/Circuit-LLM/circuit-sdk/tree/main/packages/node#readme",
+  "bugs": {
+    "url": "https://github.com/Circuit-LLM/circuit-sdk/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}