lightnode-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KykyRykyPaloma
+
+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,105 @@
+# lightnode-sdk
+
+Read-only TypeScript client for **LightChain AI**: workers, jobs, models, on-chain
+registration, and per-model network analytics. Pure reads from the public indexer and
+the chain. No keys, no writes, no native dependencies beyond `viem`.
+
+> Independent, community-built. Not an official LightChain package.
+
+## Install
+
+```bash
+npm install lightnode-sdk viem
+```
+
+## Usage
+
+```ts
+import { LightNode } from "lightnode-sdk";
+
+const ln = new LightNode("mainnet"); // or "testnet"
+
+// One worker
+const worker = await ln.getWorker("0x6781...6e0f");
+const jobs = await ln.getWorkerJobs("0x6781...6e0f", 20);
+const earnings = await ln.getEarningsLcai("0x6781...6e0f"); // whole LCAI
+
+// On-chain truth (independent of the indexer, which can lag a re-register)
+const registered = await ln.isRegistered("0x6781...6e0f"); // true | false | null
+
+// Network-wide
+const stats = await ln.getNetworkStats();      // { total, active, jobsCompleted, totalEarnedLcai, models }
+const models = await ln.getModels();           // [{ name, fee, max_output_tokens, ... }]
+const perModel = await ln.getModelStats();     // completion rate, p50/p95 latency, incomplete, earnings
+const perWorker = await ln.getWorkerStats();   // per-worker reliability, busiest first
+const rollup = await ln.getNetworkAnalytics(); // overall completion / jobs / incomplete / earnings
+
+// Inference cost
+const fee = await ln.estimateFee("llama3-8b"); // whole LCAI per job (on-chain calculateJobFee)
+const id = ln.modelId("llama3-8b");            // keccak256 model id
+```
+
+## API
+
+| Method | Returns |
+| --- | --- |
+| `getWorker(address)` | `Worker \| null` |
+| `getWorkerJobs(address, first?)` | `Job[]` |
+| `getEarningsLcai(address)` | `number` |
+| `isRegistered(address)` | `boolean \| null` (read from chain events) |
+| `getModels()` | `ModelInfo[]` |
+| `getWorkers(first?)` | `Worker[]` |
+| `getNetworkStats()` | `NetworkStats` |
+| `getModelStats(sample?)` | `ModelStat[]` |
+| `getWorkerStats(sample?, limit?)` | `WorkerStat[]` (reliability) |
+| `getNetworkAnalytics(sample?)` | `NetworkAnalytics` |
+| `estimateFee(modelTag)` | `number` (LCAI per job) |
+| `modelId(tag)` | `0x${string}` |
+
+Also exported: `NETWORKS`, `WORKER_REGISTRY`, `REGISTRY_TOPICS`, `aggregateModelStats`,
+`aggregateWorkerStats`, `networkAnalytics`, `JOB_REGISTRY_CONSUMER_ABI`,
+`consumerGatewayUrl`, `fromWei`, and all the types.
+
+## CLI
+
+```bash
+npx lightnode network --net testnet     # network summary
+npx lightnode models                    # registered models + fees
+npx lightnode worker 0x6781…6e0f        # one worker (on-chain + recent jobs)
+npx lightnode registered 0x6781…6e0f    # true | false | null
+npx lightnode fee llama3-8b             # on-chain job fee
+npx lightnode analytics --csv           # per-model performance (CSV)
+npx lightnode reliability               # per-worker reliability
+```
+
+## Submitting inference (advanced)
+
+`estimateFee` + `modelId` + the exported `JOB_REGISTRY_CONSUMER_ABI` give you the
+on-chain primitives. The full submit is a multi-step, encrypted flow and is **not
+bundled** here (it's a large, currently-undocumented protocol surface — shipping it
+half-tested would be worse than pointing you at the verified reference):
+
+1. `createSession(modelId, worker, encWorkerKey, encDisputerKey, dispatcherSig, expiry)` on the JobRegistry.
+2. ECDH-P256 + AES-256-GCM encrypt the prompt with a session key; upload it as a blob to the consumer gateway (`consumerGatewayUrl(net)`); get the EIP-4844 `blobHash`.
+3. `submitJob(sessionId, blobHash)` paying `estimateFee(model)` as native value.
+4. Read the result from the relay stream, or watch the `JobCompleted` event / the job's `responseBlobHash`.
+
+Reference implementation: [lightchain-protocol/lcai-chat-v2](https://github.com/lightchain-protocol/lcai-chat-v2) (`lib/protocol/*`). A managed REST alternative (API-key) also exists at `https://chat2.lightchain.ai/api/v1`.
+
+## Why `isRegistered` reads the chain
+
+The public indexer can report a registered worker as `deregistered` after a
+deregister -> re-register cycle. `isRegistered` instead reads the WorkerRegistry's
+join/exit events directly and returns the latest, so it is correct for any worker.
+
+## Networks
+
+| | mainnet | testnet |
+| --- | --- | --- |
+| chainId | 9200 | 8200 |
+| min stake | 50,000 LCAI | 5,000 LCAI |
+| WorkerRegistry | `0x…1002` (genesis predeploy) | same |
+
+## License
+
+MIT

package/dist/analytics.d.ts

@@ -0,0 +1,11 @@
+import type { Job, ModelInfo, ModelStat, WorkerStat, JobBuckets, NetworkAnalytics } from "./types.js";
+/** Nearest-rank percentile of an ascending-sorted array (null if empty). */
+export declare function percentile(sortedAsc: number[], p: number): number | null;
+/** Bucket a set of jobs into outcomes + latency percentiles + earnings. */
+export declare function classifyJobs(jobs: Job[], nowSec: number): JobBuckets;
+/** Per-model performance, busiest first. */
+export declare function aggregateModelStats(jobs: Job[], models: ModelInfo[], nowSec?: number): ModelStat[];
+/** Per-worker reliability, busiest first (top `limit`). */
+export declare function aggregateWorkerStats(jobs: Job[], nowSec?: number, limit?: number): WorkerStat[];
+/** Network-wide rollup across all models. */
+export declare function networkAnalytics(stats: ModelStat[]): NetworkAnalytics;

package/dist/analytics.js

@@ -0,0 +1,106 @@
+import { fromWei } from "./subgraph.js";
+const STUCK_SEC = 600;
+const isSuccess = (s) => /complet|releas|resolv/i.test(s);
+const isTimedOut = (s) => /timed?[ _-]*out|timeout/i.test(s);
+const isDisputed = (s) => /disput/i.test(s);
+const isAcked = (s) => /acknowled|ack/i.test(s);
+const isSubmitted = (s) => /submit/i.test(s);
+/** Nearest-rank percentile of an ascending-sorted array (null if empty). */
+export function percentile(sortedAsc, p) {
+    if (sortedAsc.length === 0)
+        return null;
+    const rank = Math.ceil((p / 100) * sortedAsc.length);
+    return sortedAsc[Math.min(sortedAsc.length - 1, Math.max(0, rank - 1))];
+}
+/** Bucket a set of jobs into outcomes + latency percentiles + earnings. */
+export function classifyJobs(jobs, nowSec) {
+    let success = 0;
+    let timedOut = 0;
+    let stuck = 0;
+    let disputed = 0;
+    let inFlight = 0;
+    let earnings = 0;
+    const latencies = [];
+    for (const j of jobs) {
+        const s = j.state || "";
+        if (isSuccess(s))
+            success++;
+        else if (isTimedOut(s))
+            timedOut++;
+        else if (isDisputed(s))
+            disputed++;
+        else if (isAcked(s)) {
+            if (j.ack_at && nowSec - j.ack_at > STUCK_SEC)
+                stuck++;
+            else
+                inFlight++;
+        }
+        else if (isSubmitted(s))
+            inFlight++;
+        earnings += fromWei(j.worker_share);
+        if (j.ack_at && j.completed_at && j.completed_at >= j.ack_at)
+            latencies.push(j.completed_at - j.ack_at);
+    }
+    const incomplete = timedOut + stuck;
+    const resolved = success + incomplete + disputed;
+    latencies.sort((a, b) => a - b);
+    return {
+        total: jobs.length,
+        success,
+        timedOut,
+        stuck,
+        disputed,
+        inFlight,
+        incomplete,
+        completionRate: resolved > 0 ? success / resolved : null,
+        p50: percentile(latencies, 50),
+        p95: percentile(latencies, 95),
+        earnings,
+    };
+}
+function groupBy(jobs, key) {
+    const m = new Map();
+    for (const j of jobs) {
+        const k = key(j);
+        if (!k)
+            continue;
+        const arr = m.get(k);
+        if (arr)
+            arr.push(j);
+        else
+            m.set(k, [j]);
+    }
+    return m;
+}
+/** Per-model performance, busiest first. */
+export function aggregateModelStats(jobs, models, nowSec = Math.floor(Date.now() / 1000)) {
+    const nameById = new Map(models.map((m) => [m.id.toLowerCase(), m.name]));
+    return [...groupBy(jobs, (j) => j.model_id?.toLowerCase()).entries()]
+        .map(([id, js]) => ({ modelId: id, name: nameById.get(id) ?? `${id.slice(0, 10)}…`, ...classifyJobs(js, nowSec) }))
+        .sort((a, b) => b.total - a.total);
+}
+/** Per-worker reliability, busiest first (top `limit`). */
+export function aggregateWorkerStats(jobs, nowSec = Math.floor(Date.now() / 1000), limit = 25) {
+    return [...groupBy(jobs, (j) => j.worker).entries()]
+        .map(([address, js]) => ({ address, ...classifyJobs(js, nowSec) }))
+        .sort((a, b) => b.total - a.total)
+        .slice(0, limit);
+}
+/** Network-wide rollup across all models. */
+export function networkAnalytics(stats) {
+    const sum = (f) => stats.reduce((a, s) => a + f(s), 0);
+    const success = sum((s) => s.success);
+    const incomplete = sum((s) => s.incomplete);
+    const disputed = sum((s) => s.disputed);
+    const resolved = success + incomplete + disputed;
+    return {
+        models: stats.length,
+        jobs: sum((s) => s.total),
+        success,
+        incomplete,
+        disputed,
+        inFlight: sum((s) => s.inFlight),
+        completionRate: resolved > 0 ? success / resolved : null,
+        earnings: sum((s) => s.earnings),
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import { LightNode } from "./index.js";
+function flag(name) {
+    const i = process.argv.indexOf(name);
+    return i >= 0 ? process.argv[i + 1] : undefined;
+}
+const positionals = process.argv.slice(2).filter((a) => !a.startsWith("--"));
+const cmd = positionals[0];
+const net = flag("--net") || "mainnet";
+const csv = process.argv.includes("--csv");
+function die(msg) {
+    console.error(msg);
+    process.exit(1);
+}
+const lcai = (wei) => (wei ? Number(BigInt(wei)) / 1e18 : 0);
+const rate = (r) => (r == null ? "-" : `${Math.round(r * 100)}%`);
+const HELP = `lightnode <command> [--net mainnet|testnet]
+
+  network              network summary (workers, jobs, models, earnings)
+  models               registered models + per-job fee
+  worker <addr>        a worker: on-chain registration + recent jobs
+  registered <addr>    true | false | null (read from chain events)
+  fee [model]          on-chain inference fee (default llama3-8b)
+  analytics [--csv]    per-model performance (completion, p50/p95, incomplete)
+  reliability          per-worker reliability, busiest first`;
+async function main() {
+    const ln = new LightNode(net);
+    switch (cmd) {
+        case "network": {
+            console.log(JSON.stringify(await ln.getNetworkAnalytics(), null, 2));
+            break;
+        }
+        case "models": {
+            for (const m of await ln.getModels()) {
+                console.log(`${m.name}\t${lcai(m.fee)} LCAI\t${m.max_output_tokens} tok\t${m.is_whitelisted && m.is_enabled ? "live" : "off"}`);
+            }
+            break;
+        }
+        case "worker": {
+            const addr = positionals[1] ?? die("usage: lightnode worker <address> [--net testnet]");
+            const [w, registered, jobs] = await Promise.all([ln.getWorker(addr), ln.isRegistered(addr), ln.getWorkerJobs(addr, 5)]);
+            console.log(JSON.stringify({ onchainRegistered: registered, worker: w, recentJobs: jobs.map((j) => ({ id: j.id, state: j.state })) }, null, 2));
+            break;
+        }
+        case "registered": {
+            const addr = positionals[1] ?? die("usage: lightnode registered <address>");
+            console.log(String(await ln.isRegistered(addr)));
+            break;
+        }
+        case "fee": {
+            const model = positionals[1] ?? "llama3-8b";
+            console.log(`${await ln.estimateFee(model)} LCAI per job (${model})`);
+            break;
+        }
+        case "analytics": {
+            const stats = await ln.getModelStats();
+            if (csv) {
+                console.log("model,jobs,completion_pct,p50_s,p95_s,incomplete,earnings_lcai");
+                for (const s of stats) {
+                    console.log(`${s.name},${s.total},${s.completionRate != null ? Math.round(s.completionRate * 100) : ""},${s.p50 ?? ""},${s.p95 ?? ""},${s.incomplete},${s.earnings.toFixed(3)}`);
+                }
+            }
+            else {
+                for (const s of stats)
+                    console.log(`${s.name}\t${s.total}j\t${rate(s.completionRate)}\tp50 ${s.p50 ?? "-"}s\tp95 ${s.p95 ?? "-"}s\tinc ${s.incomplete}\t${s.earnings.toFixed(3)} LCAI`);
+            }
+            break;
+        }
+        case "reliability": {
+            for (const w of await ln.getWorkerStats(1000, 20)) {
+                console.log(`${w.address}\t${w.total}j\t${rate(w.completionRate)}\tp50 ${w.p50 ?? "-"}s\tinc ${w.incomplete}\t${w.earnings.toFixed(3)} LCAI`);
+            }
+            break;
+        }
+        default:
+            console.log(HELP);
+    }
+}
+main().catch((e) => die(String(e?.message ?? e)));

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+import { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS } from "./networks.js";
+import { fromWei } from "./subgraph.js";
+import { aggregateModelStats, aggregateWorkerStats, networkAnalytics } from "./analytics.js";
+import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl } from "./inference.js";
+import type { NetworkId, NetworkConfig, Worker, Job, ModelInfo, NetworkStats, ModelStat, WorkerStat, NetworkAnalytics } from "./types.js";
+/**
+ * Read-only client for a LightChain AI network. Pure reads from the public indexer
+ * and the chain; no keys, no writes. Independent, community-built.
+ *
+ * ```ts
+ * import { LightNode } from "lightnode-sdk";
+ * const ln = new LightNode("mainnet");
+ * const worker = await ln.getWorker("0x...");
+ * const registered = await ln.isRegistered("0x..."); // on-chain truth
+ * const perModel = await ln.getModelStats();
+ * ```
+ */
+export declare class LightNode {
+    readonly network: NetworkConfig;
+    constructor(network?: NetworkId | NetworkConfig);
+    /** The full record for one worker (null if the indexer has never seen it). */
+    getWorker(address: string): Promise<Worker | null>;
+    /** Recent jobs for one worker, newest first. */
+    getWorkerJobs(address: string, first?: number): Promise<Job[]>;
+    /** The network's registered models (name, fee, output limit, whitelist flags). */
+    getModels(): Promise<ModelInfo[]>;
+    /** Registered workers (default top 200). */
+    getWorkers(first?: number): Promise<Worker[]>;
+    /** A one-shot summary: totals, active count, jobs completed, earnings, model count. */
+    getNetworkStats(): Promise<NetworkStats>;
+    /** Per-model performance over the last `sample` jobs (completion, p50/p95, incomplete, disputes, earnings). */
+    getModelStats(sample?: number): Promise<ModelStat[]>;
+    /** Network-wide rollup across all models over the last `sample` jobs. */
+    getNetworkAnalytics(sample?: number): Promise<NetworkAnalytics>;
+    /** Per-worker reliability (completion, p50/p95, incomplete) over the last `sample` jobs, busiest first. */
+    getWorkerStats(sample?: number, limit?: number): Promise<WorkerStat[]>;
+    /**
+     * Authoritative registration read straight from the chain's WorkerRegistry events
+     * (true/false), or null when the chain can't answer. Use this over getWorker().status
+     * when you need certainty: the indexer can lag a deregister -> re-register cycle.
+     */
+    isRegistered(address: string): Promise<boolean | null>;
+    /** Settled worker earnings in whole LCAI (from total_earned wei). */
+    getEarningsLcai(address: string): Promise<number>;
+    /** keccak256 of a model tag (its on-chain + indexer id). */
+    modelId(tag: string): `0x${string}`;
+    /** On-chain inference fee for a model, in whole LCAI (what submitJob must be paid). */
+    estimateFee(modelTag: string): Promise<number>;
+}
+export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, };
+export type { NetworkId, NetworkConfig, Worker, Job, ModelInfo, NetworkStats, ModelStat, WorkerStat, NetworkAnalytics };

package/dist/index.js

@@ -0,0 +1,81 @@
+import { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS } from "./networks.js";
+import { fetchWorker, fetchWorkerJobs, fetchRecentJobs, fetchModels, fetchWorkers, summarize, fromWei, } from "./subgraph.js";
+import { isRegistered } from "./onchain.js";
+import { aggregateModelStats, aggregateWorkerStats, networkAnalytics } from "./analytics.js";
+import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl } from "./inference.js";
+/**
+ * Read-only client for a LightChain AI network. Pure reads from the public indexer
+ * and the chain; no keys, no writes. Independent, community-built.
+ *
+ * ```ts
+ * import { LightNode } from "lightnode-sdk";
+ * const ln = new LightNode("mainnet");
+ * const worker = await ln.getWorker("0x...");
+ * const registered = await ln.isRegistered("0x..."); // on-chain truth
+ * const perModel = await ln.getModelStats();
+ * ```
+ */
+export class LightNode {
+    constructor(network = "mainnet") {
+        this.network = typeof network === "string" ? NETWORKS[network] : network;
+        if (!this.network)
+            throw new Error(`unknown network: ${String(network)}`);
+    }
+    /** The full record for one worker (null if the indexer has never seen it). */
+    getWorker(address) {
+        return fetchWorker(this.network, address);
+    }
+    /** Recent jobs for one worker, newest first. */
+    getWorkerJobs(address, first = 20) {
+        return fetchWorkerJobs(this.network, address, first);
+    }
+    /** The network's registered models (name, fee, output limit, whitelist flags). */
+    getModels() {
+        return fetchModels(this.network);
+    }
+    /** Registered workers (default top 200). */
+    getWorkers(first = 200) {
+        return fetchWorkers(this.network, first);
+    }
+    /** A one-shot summary: totals, active count, jobs completed, earnings, model count. */
+    async getNetworkStats() {
+        const [workers, models] = await Promise.all([fetchWorkers(this.network), fetchModels(this.network)]);
+        return summarize(workers, models);
+    }
+    /** Per-model performance over the last `sample` jobs (completion, p50/p95, incomplete, disputes, earnings). */
+    async getModelStats(sample = 1000) {
+        const [jobs, models] = await Promise.all([fetchRecentJobs(this.network, sample), fetchModels(this.network)]);
+        return aggregateModelStats(jobs, models);
+    }
+    /** Network-wide rollup across all models over the last `sample` jobs. */
+    async getNetworkAnalytics(sample = 1000) {
+        return networkAnalytics(await this.getModelStats(sample));
+    }
+    /** Per-worker reliability (completion, p50/p95, incomplete) over the last `sample` jobs, busiest first. */
+    async getWorkerStats(sample = 1000, limit = 25) {
+        const jobs = await fetchRecentJobs(this.network, sample);
+        return aggregateWorkerStats(jobs, Math.floor(Date.now() / 1000), limit);
+    }
+    /**
+     * Authoritative registration read straight from the chain's WorkerRegistry events
+     * (true/false), or null when the chain can't answer. Use this over getWorker().status
+     * when you need certainty: the indexer can lag a deregister -> re-register cycle.
+     */
+    isRegistered(address) {
+        return isRegistered(this.network, address);
+    }
+    /** Settled worker earnings in whole LCAI (from total_earned wei). */
+    async getEarningsLcai(address) {
+        const w = await fetchWorker(this.network, address);
+        return w ? fromWei(w.total_earned) : 0;
+    }
+    /** keccak256 of a model tag (its on-chain + indexer id). */
+    modelId(tag) {
+        return computeModelId(tag);
+    }
+    /** On-chain inference fee for a model, in whole LCAI (what submitJob must be paid). */
+    estimateFee(modelTag) {
+        return estimateJobFee(this.network, modelTag);
+    }
+}
+export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, };

package/dist/inference.d.ts

@@ -0,0 +1,24 @@
+import type { NetworkConfig } from "./types.js";
+/** modelId = keccak256(utf8(exact ollama tag)). Joins to the subgraph + contracts. */
+export declare function modelId(tag: string): `0x${string}`;
+/**
+ * On-chain inference fee for a model, in whole LCAI - read from
+ * AIConfig.calculateJobFee(modelId). This is what `submitJob` must be paid (native
+ * value), so a consumer can quote a price before submitting.
+ */
+export declare function estimateJobFee(cfg: NetworkConfig, modelTag: string): Promise<number>;
+/**
+ * The consumer-relevant JobRegistry surface (human-readable, viem-parseable). Use it
+ * to build the full submit flow: createSession -> submitJob(value: fee) -> watch
+ * JobCompleted / read the result blob.
+ *
+ * IMPORTANT: this ABI is reverse-engineered from the official client (lcai-chat-v2),
+ * verified by selector against the deployed bytecode, but NOT from published source.
+ * The full submit also requires an ECDH-P256 + AES-256-GCM handshake with the assigned
+ * worker and a blob upload to the consumer gateway - intentionally NOT bundled here
+ * (it's a large, protocol-specific, currently-undocumented surface). See the SDK
+ * README "Submitting inference" for the verified end-to-end steps and a reference.
+ */
+export declare const JOB_REGISTRY_CONSUMER_ABI: readonly ["function createSession(bytes32 modelId, address worker, bytes encWorkerKey, bytes encDisputerKey, bytes dispatcherSignature, uint256 expiry) payable returns (uint256 sessionId)", "function submitJob(uint256 sessionId, bytes32 blobHash) payable returns (uint256 jobId)", "event SessionCreated(uint256 sessionId, address user, bytes32 indexed modelId, address worker, bytes encWorkerKey, bytes encDisputerKey)", "event JobSubmitted(uint256 jobId, uint256 sessionId, address worker)", "event JobCompleted(uint256 jobId, address worker, bytes32 responseBlobHash, bytes32 responseCiphertextHash)"];
+/** Consumer gateway base URL for a network (SIWE-authenticated; submit blobs + relay). */
+export declare function consumerGatewayUrl(net: "mainnet" | "testnet"): string;

package/dist/inference.js

@@ -0,0 +1,48 @@
+import { keccak256, toBytes } from "viem";
+// AIConfig.calculateJobFee(bytes32) - verified live on both networks.
+const CALCULATE_JOB_FEE_SELECTOR = "0x33763d83";
+/** modelId = keccak256(utf8(exact ollama tag)). Joins to the subgraph + contracts. */
+export function modelId(tag) {
+    return keccak256(toBytes(tag));
+}
+/**
+ * On-chain inference fee for a model, in whole LCAI - read from
+ * AIConfig.calculateJobFee(modelId). This is what `submitJob` must be paid (native
+ * value), so a consumer can quote a price before submitting.
+ */
+export async function estimateJobFee(cfg, modelTag) {
+    const data = CALCULATE_JOB_FEE_SELECTOR + modelId(modelTag).slice(2);
+    const res = await fetch(cfg.rpc, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_call", params: [{ to: cfg.aiConfig, data }, "latest"] }),
+    });
+    const json = (await res.json());
+    if (json.error || !json.result || json.result === "0x") {
+        throw new Error(json.error?.message ?? "calculateJobFee returned no data");
+    }
+    return Number(BigInt(json.result)) / 1e18;
+}
+/**
+ * The consumer-relevant JobRegistry surface (human-readable, viem-parseable). Use it
+ * to build the full submit flow: createSession -> submitJob(value: fee) -> watch
+ * JobCompleted / read the result blob.
+ *
+ * IMPORTANT: this ABI is reverse-engineered from the official client (lcai-chat-v2),
+ * verified by selector against the deployed bytecode, but NOT from published source.
+ * The full submit also requires an ECDH-P256 + AES-256-GCM handshake with the assigned
+ * worker and a blob upload to the consumer gateway - intentionally NOT bundled here
+ * (it's a large, protocol-specific, currently-undocumented surface). See the SDK
+ * README "Submitting inference" for the verified end-to-end steps and a reference.
+ */
+export const JOB_REGISTRY_CONSUMER_ABI = [
+    "function createSession(bytes32 modelId, address worker, bytes encWorkerKey, bytes encDisputerKey, bytes dispatcherSignature, uint256 expiry) payable returns (uint256 sessionId)",
+    "function submitJob(uint256 sessionId, bytes32 blobHash) payable returns (uint256 jobId)",
+    "event SessionCreated(uint256 sessionId, address user, bytes32 indexed modelId, address worker, bytes encWorkerKey, bytes encDisputerKey)",
+    "event JobSubmitted(uint256 jobId, uint256 sessionId, address worker)",
+    "event JobCompleted(uint256 jobId, address worker, bytes32 responseBlobHash, bytes32 responseCiphertextHash)",
+];
+/** Consumer gateway base URL for a network (SIWE-authenticated; submit blobs + relay). */
+export function consumerGatewayUrl(net) {
+    return `https://chat-api.${net}.lightchain.ai`;
+}

package/dist/networks.d.ts

@@ -0,0 +1,19 @@
+import type { NetworkConfig, NetworkId } from "./types.js";
+/**
+ * LightChain AI network constants, verified against the live registries on both
+ * chains. AIConfig + JobRegistry are upgradeable proxies (stable addresses); the
+ * canonical source is WorkerRegistry.aiConfig() / .jobRegistry() if you ever need
+ * to re-resolve them.
+ */
+export declare const NETWORKS: Record<NetworkId, NetworkConfig>;
+/** WorkerRegistry genesis predeploy (same address on both networks). */
+export declare const WORKER_REGISTRY = "0x0000000000000000000000000000000000001002";
+/**
+ * WorkerRegistry event topics, derived empirically from the deployed predeploy
+ * (its source ABI differs from the deployed bytecode, so these are not computed
+ * from a signature). The latest of the two for a worker = its current state.
+ */
+export declare const REGISTRY_TOPICS: {
+    readonly registered: "0x27987c0173113d0f969d0abbf00a8c583fd7f7f44c05af3739f808d2a0afba6f";
+    readonly exited: "0xde576c51e7828c269f7a259c68554d25364b596a7bd816f01d9b8cdb52e88d43";
+};

package/dist/networks.js

@@ -0,0 +1,45 @@
+/**
+ * LightChain AI network constants, verified against the live registries on both
+ * chains. AIConfig + JobRegistry are upgradeable proxies (stable addresses); the
+ * canonical source is WorkerRegistry.aiConfig() / .jobRegistry() if you ever need
+ * to re-resolve them.
+ */
+export const NETWORKS = {
+    mainnet: {
+        id: "mainnet",
+        label: "Mainnet",
+        chainId: 9200,
+        rpc: "https://rpc.mainnet.lightchain.ai",
+        explorer: "https://mainnet.lightscan.app",
+        workerGateway: "https://worker-gateway.mainnet.lightchain.ai",
+        subgraph: "https://workers-api.mainnet.lightchain.ai/graphql",
+        workerRegistry: "0x0000000000000000000000000000000000001002",
+        aiConfig: "0x24D11533C354092ed6E18b964257819cE78Ce77D",
+        jobRegistry: "0xfB15F90298e4CcD7106E76fFB5e520315cC42B0b",
+        minStakeLcai: 50000,
+    },
+    testnet: {
+        id: "testnet",
+        label: "Testnet",
+        chainId: 8200,
+        rpc: "https://rpc.testnet.lightchain.ai",
+        explorer: "https://testnet.lightscan.app",
+        workerGateway: "https://worker-gateway.testnet.lightchain.ai",
+        subgraph: "https://workers-api.testnet.lightchain.ai/graphql",
+        workerRegistry: "0x0000000000000000000000000000000000001002",
+        aiConfig: "0xeCF4Ca5Ba6D97ae586993e170764a1E92231b67e",
+        jobRegistry: "0x531b3a87c5d785441b9cf55b98169f20fd9056a7",
+        minStakeLcai: 5000,
+    },
+};
+/** WorkerRegistry genesis predeploy (same address on both networks). */
+export const WORKER_REGISTRY = "0x0000000000000000000000000000000000001002";
+/**
+ * WorkerRegistry event topics, derived empirically from the deployed predeploy
+ * (its source ABI differs from the deployed bytecode, so these are not computed
+ * from a signature). The latest of the two for a worker = its current state.
+ */
+export const REGISTRY_TOPICS = {
+    registered: "0x27987c0173113d0f969d0abbf00a8c583fd7f7f44c05af3739f808d2a0afba6f",
+    exited: "0xde576c51e7828c269f7a259c68554d25364b596a7bd816f01d9b8cdb52e88d43",
+};

package/dist/onchain.d.ts

@@ -0,0 +1,8 @@
+import type { NetworkConfig } from "./types.js";
+/**
+ * Authoritative worker registration, read straight from the chain's WorkerRegistry
+ * events (works for ANY worker, independent of the public indexer, which can lag a
+ * deregister -> re-register cycle). Returns true/false from the latest join/exit
+ * event, or null when the chain can't answer (RPC error, or no events for it).
+ */
+export declare function isRegistered(cfg: NetworkConfig, address: string): Promise<boolean | null>;

package/dist/onchain.js

@@ -0,0 +1,57 @@
+import { REGISTRY_TOPICS } from "./networks.js";
+function addressTopic(address) {
+    return "0x" + address.toLowerCase().replace(/^0x/, "").padStart(64, "0");
+}
+/**
+ * Authoritative worker registration, read straight from the chain's WorkerRegistry
+ * events (works for ANY worker, independent of the public indexer, which can lag a
+ * deregister -> re-register cycle). Returns true/false from the latest join/exit
+ * event, or null when the chain can't answer (RPC error, or no events for it).
+ */
+export async function isRegistered(cfg, address) {
+    if (!/^0x[a-fA-F0-9]{40}$/.test(address))
+        return null;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 8000);
+    try {
+        const res = await fetch(cfg.rpc, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: 1,
+                method: "eth_getLogs",
+                params: [
+                    {
+                        address: cfg.workerRegistry,
+                        topics: [[REGISTRY_TOPICS.registered, REGISTRY_TOPICS.exited], addressTopic(address)],
+                        fromBlock: "0x0",
+                        toBlock: "latest",
+                    },
+                ],
+            }),
+            signal: ctrl.signal,
+        });
+        if (!res.ok)
+            return null;
+        const json = (await res.json());
+        const logs = json.result;
+        if (!Array.isArray(logs) || logs.length === 0)
+            return null;
+        let latest = logs[0];
+        for (const lg of logs) {
+            const b = parseInt(lg.blockNumber, 16);
+            const i = parseInt(lg.logIndex, 16);
+            if (b > parseInt(latest.blockNumber, 16) || (b === parseInt(latest.blockNumber, 16) && i > parseInt(latest.logIndex, 16))) {
+                latest = lg;
+            }
+        }
+        return latest.topics?.[0]?.toLowerCase() === REGISTRY_TOPICS.registered;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/subgraph.d.ts

@@ -0,0 +1,10 @@
+import type { NetworkConfig, Worker, Job, ModelInfo, NetworkStats } from "./types.js";
+/** Convert a wei string to a number of whole tokens (18 decimals). */
+export declare function fromWei(wei?: string): number;
+export declare function fetchWorker(cfg: NetworkConfig, address: string): Promise<Worker | null>;
+export declare function fetchWorkerJobs(cfg: NetworkConfig, address: string, first?: number): Promise<Job[]>;
+/** Recent jobs across the whole network (not one worker), for analytics. */
+export declare function fetchRecentJobs(cfg: NetworkConfig, first?: number): Promise<Job[]>;
+export declare function fetchModels(cfg: NetworkConfig): Promise<ModelInfo[]>;
+export declare function fetchWorkers(cfg: NetworkConfig, first?: number): Promise<Worker[]>;
+export declare function summarize(workers: Worker[], models: ModelInfo[]): NetworkStats;

package/dist/subgraph.js

@@ -0,0 +1,84 @@
+import { getAddress } from "viem";
+const TIMEOUT_MS = 12000;
+async function gql(url, query) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ query }),
+            signal: ctrl.signal,
+        });
+        if (!res.ok)
+            throw new Error(`subgraph ${res.status}`);
+        const json = (await res.json());
+        if (json.errors)
+            throw new Error(json.errors[0]?.message ?? "subgraph error");
+        return json.data;
+    }
+    catch (e) {
+        if (e.name === "AbortError")
+            throw new Error(`subgraph timeout after ${TIMEOUT_MS}ms`);
+        throw e;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function checksum(addr) {
+    try {
+        return getAddress(addr);
+    }
+    catch {
+        return addr;
+    }
+}
+/** Convert a wei string to a number of whole tokens (18 decimals). */
+export function fromWei(wei) {
+    if (!wei)
+        return 0;
+    try {
+        return Number(BigInt(wei)) / 1e18;
+    }
+    catch {
+        return 0;
+    }
+}
+export async function fetchWorker(cfg, address) {
+    try {
+        const data = await gql(cfg.subgraph, `{ worker(id:"${checksum(address)}") { id status stake active_job_count jobs_completed jobs_timed_out total_earned last_seen_at created_at } }`);
+        return data.worker ?? null;
+    }
+    catch (e) {
+        if (/not found/i.test(e.message))
+            return null; // unknown worker
+        throw e;
+    }
+}
+export async function fetchWorkerJobs(cfg, address, first = 20) {
+    const data = await gql(cfg.subgraph, `{ jobs(first:${first}, orderBy:submitted_at, orderDirection:desc, where:{worker:"${checksum(address)}"}) { id state model_id submitted_at ack_at completed_at worker_share } }`);
+    return data.jobs ?? [];
+}
+/** Recent jobs across the whole network (not one worker), for analytics. */
+export async function fetchRecentJobs(cfg, first = 1000) {
+    const data = await gql(cfg.subgraph, `{ jobs(first:${first}, orderBy:submitted_at, orderDirection:desc) { id state model_id worker ack_at completed_at worker_share } }`);
+    return data.jobs ?? [];
+}
+export async function fetchModels(cfg) {
+    const data = await gql(cfg.subgraph, `{ modelinfos { id name fee max_output_tokens is_whitelisted is_enabled } }`);
+    return data.modelinfos ?? [];
+}
+export async function fetchWorkers(cfg, first = 200) {
+    const data = await gql(cfg.subgraph, `{ workers(first:${first}) { id status stake active_job_count jobs_completed jobs_timed_out total_earned last_seen_at created_at } }`);
+    return data.workers ?? [];
+}
+export function summarize(workers, models) {
+    return {
+        total: workers.length,
+        active: workers.filter((w) => w.status === "active").length,
+        jobsCompleted: workers.reduce((s, w) => s + (w.jobs_completed ?? 0), 0),
+        totalEarnedLcai: workers.reduce((s, w) => s + fromWei(w.total_earned), 0),
+        models: models.filter((m) => m.is_enabled && m.is_whitelisted).length,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,81 @@
+export type NetworkId = "mainnet" | "testnet";
+export interface NetworkConfig {
+    id: NetworkId;
+    label: string;
+    chainId: number;
+    rpc: string;
+    explorer: string;
+    workerGateway: string;
+    subgraph: string;
+    /** Genesis predeploy, same address on both networks. */
+    workerRegistry: string;
+    aiConfig: string;
+    jobRegistry: string;
+    minStakeLcai: number;
+}
+export interface Worker {
+    id: string;
+    status: string;
+    stake: string;
+    active_job_count?: number;
+    jobs_completed?: number;
+    jobs_timed_out?: number;
+    total_earned?: string;
+    last_seen_at?: number;
+    created_at?: number;
+}
+export interface Job {
+    id: string;
+    state: string;
+    model_id?: string;
+    worker?: string;
+    submitted_at?: number;
+    ack_at?: number;
+    completed_at?: number;
+    worker_share?: string;
+}
+export interface ModelInfo {
+    id: string;
+    name: string;
+    fee: string;
+    max_output_tokens: number;
+    is_whitelisted: boolean;
+    is_enabled: boolean;
+}
+export interface NetworkStats {
+    total: number;
+    active: number;
+    jobsCompleted: number;
+    totalEarnedLcai: number;
+    models: number;
+}
+export interface JobBuckets {
+    total: number;
+    success: number;
+    timedOut: number;
+    stuck: number;
+    disputed: number;
+    inFlight: number;
+    incomplete: number;
+    completionRate: number | null;
+    p50: number | null;
+    p95: number | null;
+    earnings: number;
+}
+export interface ModelStat extends JobBuckets {
+    modelId: string;
+    name: string;
+}
+export interface WorkerStat extends JobBuckets {
+    address: string;
+}
+export interface NetworkAnalytics {
+    models: number;
+    jobs: number;
+    success: number;
+    incomplete: number;
+    disputed: number;
+    inFlight: number;
+    completionRate: number | null;
+    earnings: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "lightnode-sdk",
+  "version": "0.1.0",
+  "description": "Read-only TypeScript client for LightChain AI: workers, jobs, models, on-chain registration, and per-model network analytics. Independent, community-built (not an official LightChain package).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "lightnode": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "lightchain",
+    "lightchain-ai",
+    "ai",
+    "worker",
+    "web3",
+    "evm",
+    "sdk"
+  ],
+  "author": "KykyRykyPaloma",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marinom2/lightnode.git",
+    "directory": "sdk"
+  },
+  "homepage": "https://github.com/marinom2/lightnode/tree/main/sdk#readme",
+  "bugs": {
+    "url": "https://github.com/marinom2/lightnode/issues"
+  },
+  "dependencies": {
+    "viem": ">=2"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}