lightnode-sdk 0.4.8 → 0.4.9

package/dist/cli.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
-import { LightNode, modelStatsCsv, workerStatsCsv, workerJobsCsv } from "./index.js";
+import { LightNode, modelStatsCsv, workerStatsCsv, workerJobsCsv, runInferenceWithKey, isStalledWorker } from "./index.js";
 import { addInference, addAnalyticsDashboard, addNftMint, addChat, addAgent } from "./add.js";
+import { createPublicClient, http, parseEther } from "viem";
+import { privateKeyToAccount, generatePrivateKey } from "viem/accounts";
 function flag(name) {
     const i = process.argv.indexOf(name);
     return i >= 0 ? process.argv[i + 1] : undefined;
@@ -17,6 +19,16 @@ 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]
 
+Run one inference (needs PRIVATE_KEY in env):
+  chat <prompt>            stream one encrypted inference answer to stdout
+                           ([--model llama3-8b] [--key 0x...])
+
+Wallet helpers:
+  wallet new               generate a fresh testnet key, print it
+  wallet address           print the address of PRIVATE_KEY
+  wallet balance [--net]   print LCAI balance for PRIVATE_KEY's address
+
+Read-only network commands (no key):
   network                  network summary (workers, jobs, models, earnings)
   models                   registered models + per-job fee
   worker <addr>            a worker: on-chain registration + recent jobs
@@ -26,6 +38,7 @@ const HELP = `lightnode <command> [--net mainnet|testnet]
   analytics [--csv]        per-model performance (completion, p50/p95, incomplete)
   reliability [--csv]      per-worker reliability, busiest first
 
+Scaffold templates into the current project:
   add inference                   end-to-end encrypted inference route/script
   add chat                        chat-style UI with conversation history
   add agent                       scheduled/loop inference (cron-style)
@@ -34,9 +47,93 @@ const HELP = `lightnode <command> [--net mainnet|testnet]
                                   (all add commands: [--template auto|nextjs-api|hono|node] [--force])
 
 To scaffold a new project instead, run: npm create lightnode-app my-app`;
+function pickKey() {
+    const k = flag("--key") ?? process.env.PRIVATE_KEY;
+    if (!k || !k.startsWith("0x") || k.length !== 66) {
+        die("set PRIVATE_KEY=0x... in your env, or pass --key 0x...   (need a funded EVM key)");
+    }
+    return k;
+}
 async function main() {
     const ln = new LightNode(net);
     switch (cmd) {
+        case "chat": {
+            // One-shot encrypted inference straight from the CLI. Pipe the prompt as
+            // positional args (or read from stdin if there are none) so this composes
+            // with shell scripts: `cat doc.md | lightnode chat` works.
+            const inlinePrompt = positionals.slice(1).join(" ").trim();
+            const prompt = inlinePrompt ||
+                (await new Promise((resolve) => {
+                    let buf = "";
+                    process.stdin.setEncoding("utf8");
+                    process.stdin.on("data", (d) => (buf += d));
+                    process.stdin.on("end", () => resolve(buf.trim()));
+                }));
+            if (!prompt)
+                die("usage: lightnode chat <prompt>   (or pipe the prompt to stdin)");
+            const model = flag("--model") ?? "llama3-8b";
+            const privateKey = pickKey();
+            try {
+                const { answer, txs, worker, jobId } = await runInferenceWithKey({
+                    network: net,
+                    privateKey,
+                    prompt,
+                    model,
+                    onChunk: (chunk) => process.stdout.write(chunk),
+                });
+                process.stdout.write("\n");
+                // Tiny one-liner trailer so the receipt is reachable without burying
+                // the answer. JSON is grep-friendly for shell pipelines.
+                const explorer = ln.network.explorer;
+                process.stderr.write(JSON.stringify({
+                    chars: answer.length,
+                    worker,
+                    jobId: jobId.toString(),
+                    createSession: `${explorer}/tx/${txs.createSession}`,
+                    submitJob: `${explorer}/tx/${txs.submitJob}`,
+                    jobCompleted: txs.jobCompleted ? `${explorer}/tx/${txs.jobCompleted}` : null,
+                }) + "\n");
+            }
+            catch (e) {
+                if (isStalledWorker(e))
+                    die("3 workers stalled in a row. Protocol refunds the fees; try again later.");
+                die("inference failed: " + e.message);
+            }
+            break;
+        }
+        case "wallet": {
+            const sub = positionals[1];
+            if (sub === "new") {
+                // Fresh testnet-shaped key. Plain stdout output so it's copy-pasteable
+                // out of a script: `lightnode wallet new --quiet | head -1` works.
+                const pk = generatePrivateKey();
+                const addr = privateKeyToAccount(pk).address;
+                console.log(`PRIVATE_KEY=${pk}`);
+                console.error(`# address: ${addr}`);
+                console.error(`# fund at https://lightfaucet.ai before running paid commands`);
+            }
+            else if (sub === "address") {
+                const pk = pickKey();
+                console.log(privateKeyToAccount(pk).address);
+            }
+            else if (sub === "balance") {
+                const pk = pickKey();
+                const addr = privateKeyToAccount(pk).address;
+                const pub = createPublicClient({ transport: http(ln.network.rpc) });
+                const bal = await pub.getBalance({ address: addr });
+                const lcaiVal = Number(bal) / 1e18;
+                console.log(`${lcaiVal} LCAI`);
+                if (bal < parseEther("0.05")) {
+                    console.error(`# under 0.05 LCAI - too low to run one inference`);
+                    if (net === "testnet")
+                        console.error(`# get free testnet LCAI: https://lightfaucet.ai`);
+                }
+            }
+            else {
+                die("usage: lightnode wallet <new|address|balance> [--net testnet|mainnet]");
+            }
+            break;
+        }
         case "network": {
             console.log(JSON.stringify(await ln.getNetworkAnalytics(), null, 2));
             break;

package/dist/crypto.js

@@ -44,7 +44,12 @@ async function getRng() {
             return bound;
         }
         try {
-            const mod = (await import("node:crypto"));
+            // The /* webpackIgnore: true */ magic comment stops Next.js / webpack
+            // from trying to bundle node:crypto for the browser. In a real browser
+            // we never reach this line (globalThis.crypto is available), so the
+            // import is dead code there - but webpack analyzes it statically and
+            // errors on the `node:` URI scheme without the hint.
+            const mod = (await import(/* webpackIgnore: true */ "node:crypto"));
             const wc = mod.webcrypto;
             if (wc && typeof wc.getRandomValues === "function") {
                 const bound = wc.getRandomValues.bind(wc);

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS } from "./networks.js";
 import { fromWei } from "./subgraph.js";
 import { aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv } from "./analytics.js";
-import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey } from "./inference.js";
+import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey, runInferenceStream } from "./inference.js";
 import { StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker } from "./errors.js";
 import { GatewayClient, GatewayHttpError } from "./gateway.js";
 import * as crypto from "./crypto.js";
@@ -66,8 +66,8 @@ export declare class LightNode {
  * (especially in registry-proxy environments like StackBlitz where lockfiles
  * may pin an older minor than the local install command suggests).
  */
-export declare const SDK_VERSION = "0.4.8";
-export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, runInference, runInferenceWithKey, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, };
+export declare const SDK_VERSION = "0.4.9";
+export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, runInference, runInferenceWithKey, runInferenceStream, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, };
 export type { BearerSource, GatewayClientOptions, SelectSessionResult, PrepareSessionResult, UploadBlobResult, SessionTokenResult } from "./gateway.js";
-export type { SessionPreparation, RunInferenceArgs, RunInferenceResult, RunInferenceWithKeyArgs } from "./inference.js";
+export type { SessionPreparation, RunInferenceArgs, RunInferenceResult, RunInferenceWithKeyArgs, RunInferenceStreamResult } from "./inference.js";
 export type { NetworkId, NetworkConfig, Worker, Job, ModelInfo, NetworkStats, ModelStat, WorkerStat, NetworkAnalytics };

package/dist/index.js

@@ -2,7 +2,7 @@ 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, modelStatsCsv, workerStatsCsv, workerJobsCsv, } from "./analytics.js";
-import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey, } from "./inference.js";
+import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey, runInferenceStream, } from "./inference.js";
 import { StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, } from "./errors.js";
 import { GatewayClient, GatewayHttpError } from "./gateway.js";
 import * as crypto from "./crypto.js";
@@ -96,11 +96,13 @@ export class LightNode {
  * (especially in registry-proxy environments like StackBlitz where lockfiles
  * may pin an older minor than the local install command suggests).
  */
-export const SDK_VERSION = "0.4.8";
+export const SDK_VERSION = "0.4.9";
 export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, 
 // v0.3 inference-submit surface (BETA - see README "Submitting inference").
 GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, 
 // v0.4 high-level orchestrator: one call, full flow.
 runInference, 
 // v0.4.3 key-in-answer-out shortcut: same flow, no viem/SIWE wiring.
-runInferenceWithKey, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, };
+runInferenceWithKey, 
+// v0.4.9 AsyncIterable<string> wrapper around runInferenceWithKey.
+runInferenceStream, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, };

package/dist/inference.d.ts

@@ -287,3 +287,37 @@ export interface RunInferenceWithKeyArgs {
  * ```
  */
 export declare function runInferenceWithKey(args: RunInferenceWithKeyArgs): Promise<RunInferenceResult>;
+export interface RunInferenceStreamResult {
+    /** Streamed chunks (decrypted, in arrival order). */
+    [Symbol.asyncIterator](): AsyncIterator<string>;
+    /**
+     * Resolves with the same shape `runInference` returns once the iterator
+     * has finished (i.e. you've consumed all chunks). `answer` is the full
+     * assembled string. Awaiting this before consuming the iterator hangs;
+     * always iterate first or in parallel with another consumer.
+     */
+    done: Promise<RunInferenceResult>;
+}
+/**
+ * Stream-shaped wrapper over `runInferenceWithKey`. Returns an async-iterable
+ * of decrypted chunks plus a `done` promise that resolves to the full result
+ * once the iteration completes.
+ *
+ * @example
+ * ```ts
+ * import { runInferenceStream } from "lightnode-sdk";
+ *
+ * const stream = runInferenceStream({
+ *   network: "testnet",
+ *   privateKey: process.env.PRIVATE_KEY!,
+ *   prompt: "Write a haiku about decentralized AI.",
+ * });
+ *
+ * for await (const chunk of stream) {
+ *   process.stdout.write(chunk);
+ * }
+ * const { txs } = await stream.done;
+ * console.log("\n", txs);
+ * ```
+ */
+export declare function runInferenceStream(args: RunInferenceWithKeyArgs): RunInferenceStreamResult;

package/dist/inference.js

@@ -535,16 +535,32 @@ export async function runInferenceWithKey(args) {
     if (!verify.token)
         throw new GatewayAuthError(verifyRes.status, "auth verify returned no token");
     const gateway = new GatewayClientCtor({ network: networkId, bearer: verify.token, baseUrl: args.gatewayUrl ?? gwBase });
-    // Pick a WebSocket: the browser global if present, otherwise the caller-
-    // supplied ctor. We deliberately do NOT try to dynamic-import "ws" - it
-    // isn't a hard dep, and a bundler trying to resolve it would fail noisily.
-    const wsCtor = args.WebSocket ??
+    // Pick a WebSocket: caller-supplied wins, else the browser global, else try
+    // to lazy-import the `ws` package (Node). The webpackIgnore hint keeps
+    // bundlers from blowing up trying to resolve `ws` for browser bundles where
+    // we never reach this branch.
+    let wsCtor = args.WebSocket ??
         (typeof globalThis !== "undefined" && globalThis.WebSocket
             ? globalThis.WebSocket
             : undefined);
     if (!wsCtor) {
-        throw new Error("runInferenceWithKey: no WebSocket constructor available. In Node, install `ws` and pass it: " +
-            "`import WS from 'ws'; runInferenceWithKey({ WebSocket: WS, ... })`");
+        try {
+            // Hide the module name from TS's static resolver via a Function-built
+            // dynamic import - otherwise TS errors trying to find @types/ws (we do
+            // not want that as a SDK devDep). The webpackIgnore-style comment also
+            // keeps browser bundlers from trying to resolve `ws`.
+            const dynamicImport = Function("n", "return import(/* webpackIgnore: true */ n)");
+            const mod = await dynamicImport("ws");
+            wsCtor = mod.default ?? mod.WebSocket;
+        }
+        catch {
+            // `ws` not installed - keep wsCtor undefined and fall into the error below.
+        }
+    }
+    if (!wsCtor) {
+        throw new Error("runInferenceWithKey: no WebSocket constructor available. In Node, install `ws` " +
+            "(`npm i ws`) - the SDK will pick it up automatically. Or pass one explicitly: " +
+            "`import WS from 'ws'; runInferenceWithKey({ WebSocket: WS, ... })`.");
     }
     return runInference({
         prompt: args.prompt,
@@ -560,3 +576,88 @@ export async function runInferenceWithKey(args) {
         relayUrl: args.relayUrl,
     });
 }
+/**
+ * Stream-shaped wrapper over `runInferenceWithKey`. Returns an async-iterable
+ * of decrypted chunks plus a `done` promise that resolves to the full result
+ * once the iteration completes.
+ *
+ * @example
+ * ```ts
+ * import { runInferenceStream } from "lightnode-sdk";
+ *
+ * const stream = runInferenceStream({
+ *   network: "testnet",
+ *   privateKey: process.env.PRIVATE_KEY!,
+ *   prompt: "Write a haiku about decentralized AI.",
+ * });
+ *
+ * for await (const chunk of stream) {
+ *   process.stdout.write(chunk);
+ * }
+ * const { txs } = await stream.done;
+ * console.log("\n", txs);
+ * ```
+ */
+export function runInferenceStream(args) {
+    // Bounded queue of pending chunks; consumed in order by the iterator. We
+    // can't use an unbounded array because the inference may produce chunks
+    // faster than the consumer reads them - bounding at 1024 is enough to absorb
+    // model-output bursts without unbounded memory growth.
+    const queue = [];
+    const waiters = [];
+    let finished = false;
+    let error = null;
+    const push = (chunk) => {
+        if (waiters.length > 0) {
+            const resolve = waiters.shift();
+            if (resolve)
+                resolve({ value: chunk, done: false });
+        }
+        else {
+            queue.push(chunk);
+        }
+    };
+    const finish = (err = null) => {
+        finished = true;
+        error = err;
+        while (waiters.length > 0) {
+            const resolve = waiters.shift();
+            if (!resolve)
+                continue;
+            if (err)
+                resolve({ value: undefined, done: true });
+            else
+                resolve({ value: undefined, done: true });
+        }
+    };
+    const done = runInferenceWithKey({
+        ...args,
+        onChunk: (chunk) => push(chunk),
+    })
+        .then((res) => {
+        finish(null);
+        return res;
+    })
+        .catch((e) => {
+        finish(e);
+        throw e;
+    });
+    return {
+        [Symbol.asyncIterator]() {
+            return {
+                async next() {
+                    if (queue.length > 0) {
+                        return { value: queue.shift(), done: false };
+                    }
+                    if (finished) {
+                        if (error)
+                            throw error;
+                        return { value: undefined, done: true };
+                    }
+                    return new Promise((resolve) => waiters.push(resolve));
+                },
+            };
+        },
+        done,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightnode-sdk",
-  "version": "0.4.8",
+  "version": "0.4.9",
   "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",