lightnode-sdk 0.4.7 → 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.d.ts

@@ -5,43 +5,50 @@
  * The format here MUST match the workers' Go implementation byte for byte,
  * which is what the `lcai-chat-v2` reference client also targets:
  *   - ECDH P-256 key exchange.
- *   - Raw shared secret used DIRECTLY as the AES-256 key (no HKDF).
+ *   - Raw shared secret X coordinate used DIRECTLY as the AES-256 key (no HKDF).
  *   - AES-GCM ciphertext layout: nonce(12) || ciphertext || tag(16).
  *   - Encrypted session key layout: ephemeralPub(65) || nonce(12) || ciphertext || tag(16).
  *
- * Uses the Web Crypto API. Tries `globalThis.crypto` first (real browsers +
- * Node 19+ where it is global), then falls back to `node:crypto`'s
- * `webcrypto` export (Node 18 and StackBlitz's WebContainer, which exposes
- * the node: module but not the global). No hard dependency on Node, and no
- * polyfill in the browser bundle.
+ * Implementation note: this module used to be built on Web Crypto (subtle.*).
+ * That broke in environments where the runtime has a partial Web Crypto
+ * implementation - notably StackBlitz / Bolt WebContainer, where
+ * subtle.generateKey({name:"ECDH",namedCurve:"P-256"}) throws "Unsupported".
+ * The flow is now backed by @noble/curves (P-256) and @noble/ciphers (AES-GCM)
+ * which are pure-JS and identical across every runtime. The only Web Crypto
+ * surface left is getRandomValues, which is reliable everywhere (when missing
+ * we fall back to node:crypto).
  */
+export interface EcdhKeyPair {
+    privateKey: Uint8Array;
+    publicKey: Uint8Array;
+}
 /** A fresh 32-byte symmetric session key (random, never derived). */
 export declare function generateSessionKey(): Promise<Uint8Array>;
-/** Fresh ECDH P-256 keypair (extractable; we need to export the public key on the wire). */
-export declare function generateEcdhKeyPair(): Promise<CryptoKeyPair>;
-/** Export an ECDH public key to its raw uncompressed P-256 encoding (65 bytes). */
-export declare function exportPublicKey(key: CryptoKey): Promise<Uint8Array>;
-/** Import a raw uncompressed P-256 public key (65 bytes) into a CryptoKey. */
-export declare function importPublicKey(raw: Uint8Array): Promise<CryptoKey>;
+/** Fresh ECDH P-256 keypair (32-byte private scalar, 65-byte uncompressed pub). */
+export declare function generateEcdhKeyPair(): Promise<EcdhKeyPair>;
+/** Identity passthrough kept for API back-compat. Public keys are already raw bytes. */
+export declare function exportPublicKey(key: Uint8Array): Uint8Array;
+/** Validate that raw is a well-formed uncompressed P-256 public key (65 bytes). */
+export declare function importPublicKey(raw: Uint8Array): Uint8Array;
 /**
- * Derive a 32-byte shared secret from a local ECDH private key and a remote
- * public key. Returns the raw x-coordinate; deliberately no HKDF, matching the
+ * Derive a 32-byte shared secret (X coordinate of the shared point) from a
+ * local ECDH private key and a remote public key. No HKDF, matching the
  * protocol's `priv.ECDH(remotePub)` output exactly.
  */
-export declare function deriveSharedSecret(privateKey: CryptoKey, remotePublicKey: CryptoKey): Promise<Uint8Array>;
+export declare function deriveSharedSecret(privateKey: Uint8Array, remotePublicKey: Uint8Array): Uint8Array;
 /** Encrypt with AES-256-GCM. Output: nonce(12) || ciphertext || tag(16). */
 export declare function encrypt(key: Uint8Array, plaintext: Uint8Array): Promise<Uint8Array>;
 /** Decrypt AES-256-GCM. Input: nonce(12) || ciphertext || tag(16). */
 export declare function decrypt(key: Uint8Array, ciphertext: Uint8Array): Promise<Uint8Array>;
 /**
- * Wrap (encrypt) a 32-byte session key for delivery to a remote party (e.g. the
- * worker), using a fresh ephemeral ECDH keypair.
+ * Wrap (encrypt) a 32-byte session key for delivery to a remote party
+ * (e.g. the worker), using a fresh ephemeral ECDH keypair.
  *
  * Output: ephemeralPub(65) || nonce(12) || AES-GCM(sharedSecret, sessionKey)
  */
-export declare function encryptSessionKey(sessionKey: Uint8Array, remotePublicKey: CryptoKey): Promise<Uint8Array>;
+export declare function encryptSessionKey(sessionKey: Uint8Array, remotePublicKey: Uint8Array): Promise<Uint8Array>;
 /** Unwrap a session key encrypted by `encryptSessionKey` using the local ECDH private key. */
-export declare function decryptSessionKey(encWorkerKey: Uint8Array, privateKey: CryptoKey): Promise<Uint8Array>;
+export declare function decryptSessionKey(encWorkerKey: Uint8Array, privateKey: Uint8Array): Promise<Uint8Array>;
 export declare function utf8ToBytes(s: string): Uint8Array;
 export declare function bytesToUtf8(b: Uint8Array): string;
 export declare function bytesToHex(b: Uint8Array): `0x${string}`;

package/dist/crypto.js

@@ -5,114 +5,124 @@
  * The format here MUST match the workers' Go implementation byte for byte,
  * which is what the `lcai-chat-v2` reference client also targets:
  *   - ECDH P-256 key exchange.
- *   - Raw shared secret used DIRECTLY as the AES-256 key (no HKDF).
+ *   - Raw shared secret X coordinate used DIRECTLY as the AES-256 key (no HKDF).
  *   - AES-GCM ciphertext layout: nonce(12) || ciphertext || tag(16).
  *   - Encrypted session key layout: ephemeralPub(65) || nonce(12) || ciphertext || tag(16).
  *
- * Uses the Web Crypto API. Tries `globalThis.crypto` first (real browsers +
- * Node 19+ where it is global), then falls back to `node:crypto`'s
- * `webcrypto` export (Node 18 and StackBlitz's WebContainer, which exposes
- * the node: module but not the global). No hard dependency on Node, and no
- * polyfill in the browser bundle.
+ * Implementation note: this module used to be built on Web Crypto (subtle.*).
+ * That broke in environments where the runtime has a partial Web Crypto
+ * implementation - notably StackBlitz / Bolt WebContainer, where
+ * subtle.generateKey({name:"ECDH",namedCurve:"P-256"}) throws "Unsupported".
+ * The flow is now backed by @noble/curves (P-256) and @noble/ciphers (AES-GCM)
+ * which are pure-JS and identical across every runtime. The only Web Crypto
+ * surface left is getRandomValues, which is reliable everywhere (when missing
+ * we fall back to node:crypto).
  */
+import { p256 } from "@noble/curves/p256";
+import { gcm } from "@noble/ciphers/aes";
 const AES_KEY_BYTES = 32;
 const GCM_NONCE_BYTES = 12;
-const P256_UNCOMPRESSED_KEY_BYTES = 65;
+const GCM_TAG_BYTES = 16;
+const P256_UNCOMPRESSED_KEY_BYTES = 65; // 0x04 || X(32) || Y(32)
 const SESSION_KEY_BYTES = 32;
-let resolvedCrypto = null;
-let resolvingCrypto = null;
-async function getCrypto() {
-    if (resolvedCrypto)
-        return resolvedCrypto;
-    if (resolvingCrypto)
-        return resolvingCrypto;
-    resolvingCrypto = (async () => {
-        const diag = [];
+// Random source: try globalThis.crypto.getRandomValues (every modern browser
+// and Node 19+ global), fall back to node:crypto.webcrypto.getRandomValues
+// (Node 18, WebContainer). All algorithm-side crypto is pure JS, so this is
+// the only Web-Crypto-flavored thing the SDK still needs.
+let resolvedRng = null;
+let resolvingRng = null;
+async function getRng() {
+    if (resolvedRng)
+        return resolvedRng;
+    if (resolvingRng)
+        return resolvingRng;
+    resolvingRng = (async () => {
         const g = globalThis.crypto;
-        diag.push(`globalThis.crypto=${g ? "present" : "missing"}`);
-        if (g)
-            diag.push(`globalThis.crypto.subtle=${g.subtle ? "present" : "missing"}`);
-        if (g)
-            diag.push(`globalThis.crypto.getRandomValues=${typeof g.getRandomValues}`);
-        if (g?.subtle && typeof g.getRandomValues === "function") {
-            const provider = { subtle: g.subtle, getRandomValues: g.getRandomValues.bind(g) };
-            resolvedCrypto = provider;
-            return provider;
+        if (g && typeof g.getRandomValues === "function") {
+            const bound = g.getRandomValues.bind(g);
+            resolvedRng = bound;
+            return bound;
         }
-        // Node 18 + StackBlitz WebContainer: globalThis.crypto may be missing, but
-        // `node:crypto` exposes the same Web Crypto API via `webcrypto`.
-        let nodeCryptoError = null;
         try {
-            const mod = (await import("node:crypto"));
-            diag.push(`node:crypto=imported`);
+            // 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;
-            diag.push(`node:crypto.webcrypto=${wc ? "present" : "missing"}`);
-            if (wc)
-                diag.push(`node:crypto.webcrypto.subtle=${wc.subtle ? "present" : "missing"}`);
-            if (wc)
-                diag.push(`node:crypto.webcrypto.getRandomValues=${typeof wc.getRandomValues}`);
-            if (wc?.subtle && typeof wc.getRandomValues === "function") {
-                const provider = { subtle: wc.subtle, getRandomValues: wc.getRandomValues.bind(wc) };
-                resolvedCrypto = provider;
-                return provider;
+            if (wc && typeof wc.getRandomValues === "function") {
+                const bound = wc.getRandomValues.bind(wc);
+                resolvedRng = bound;
+                return bound;
             }
         }
-        catch (err) {
-            nodeCryptoError = err.message;
-            diag.push(`node:crypto=import threw: ${nodeCryptoError}`);
+        catch {
+            // browser bundle without a global crypto - fall through to the throw
         }
-        throw new Error("Web Crypto unavailable. The SDK requires either globalThis.crypto (Node 19+ or any modern browser) " +
-            "or node:crypto.webcrypto (Node 18, StackBlitz WebContainer). Diagnostic: " +
-            diag.join("; "));
+        throw new Error("Secure random source unavailable: neither globalThis.crypto.getRandomValues nor " +
+            "node:crypto.webcrypto.getRandomValues was found. Requires Node 18+ or a modern browser.");
     })();
     try {
-        return await resolvingCrypto;
+        return await resolvingRng;
     }
     finally {
-        resolvingCrypto = null;
+        resolvingRng = null;
     }
 }
-async function subtle() {
-    return (await getCrypto()).subtle;
-}
 async function randomBytes(n) {
     const buf = new Uint8Array(n);
-    (await getCrypto()).getRandomValues(buf);
+    (await getRng())(buf);
     return buf;
 }
 /** A fresh 32-byte symmetric session key (random, never derived). */
 export function generateSessionKey() {
     return randomBytes(SESSION_KEY_BYTES);
 }
-/** Fresh ECDH P-256 keypair (extractable; we need to export the public key on the wire). */
+/** Fresh ECDH P-256 keypair (32-byte private scalar, 65-byte uncompressed pub). */
 export async function generateEcdhKeyPair() {
-    return (await subtle()).generateKey({ name: "ECDH", namedCurve: "P-256" }, true, ["deriveBits"]);
-}
-/** Export an ECDH public key to its raw uncompressed P-256 encoding (65 bytes). */
-export async function exportPublicKey(key) {
-    return new Uint8Array(await (await subtle()).exportKey("raw", key));
-}
-/** Import a raw uncompressed P-256 public key (65 bytes) into a CryptoKey. */
-export async function importPublicKey(raw) {
-    return (await subtle()).importKey("raw", raw, { name: "ECDH", namedCurve: "P-256" }, true, []);
+    // Use our RNG (proven available) instead of noble's, so a missing
+    // globalThis.crypto fails loudly at one site rather than in noble's internals.
+    const privateKey = await randomBytes(32);
+    // P-256 private scalars must be < n; the chance of collision is astronomically
+    // small, but noble validates this when we call getPublicKey, so any bad draw
+    // throws (and we'd just retry - but it has never been hit in practice).
+    const publicKey = p256.getPublicKey(privateKey, false);
+    return { privateKey, publicKey };
+}
+/** Identity passthrough kept for API back-compat. Public keys are already raw bytes. */
+export function exportPublicKey(key) {
+    return key;
+}
+/** Validate that raw is a well-formed uncompressed P-256 public key (65 bytes). */
+export function importPublicKey(raw) {
+    if (raw.length !== P256_UNCOMPRESSED_KEY_BYTES || raw[0] !== 0x04) {
+        throw new Error(`expected uncompressed P-256 public key (${P256_UNCOMPRESSED_KEY_BYTES} bytes, leading 0x04)`);
+    }
+    // Round-trip through noble to confirm the point is on the curve. Throws if not.
+    p256.ProjectivePoint.fromHex(raw);
+    return raw;
 }
 /**
- * Derive a 32-byte shared secret from a local ECDH private key and a remote
- * public key. Returns the raw x-coordinate; deliberately no HKDF, matching the
+ * Derive a 32-byte shared secret (X coordinate of the shared point) from a
+ * local ECDH private key and a remote public key. No HKDF, matching the
  * protocol's `priv.ECDH(remotePub)` output exactly.
  */
-export async function deriveSharedSecret(privateKey, remotePublicKey) {
-    return new Uint8Array(await (await subtle()).deriveBits({ name: "ECDH", public: remotePublicKey }, privateKey, 256));
+export function deriveSharedSecret(privateKey, remotePublicKey) {
+    // noble returns 65 bytes uncompressed (0x04 || X || Y) when isCompressed=false.
+    // The protocol's shared secret is just X.
+    const sharedPoint = p256.getSharedSecret(privateKey, remotePublicKey, false);
+    return sharedPoint.slice(1, 1 + AES_KEY_BYTES);
 }
 /** Encrypt with AES-256-GCM. Output: nonce(12) || ciphertext || tag(16). */
 export async function encrypt(key, plaintext) {
     if (key.length !== AES_KEY_BYTES)
         throw new Error(`AES key must be ${AES_KEY_BYTES} bytes`);
-    const s = await subtle();
-    const aesKey = await s.importKey("raw", key, "AES-GCM", false, ["encrypt"]);
     const nonce = await randomBytes(GCM_NONCE_BYTES);
-    const ctPlusTag = new Uint8Array(await s.encrypt({ name: "AES-GCM", iv: nonce }, aesKey, plaintext));
-    const out = new Uint8Array(GCM_NONCE_BYTES + ctPlusTag.byteLength);
+    // noble's gcm returns plaintext.length + 16 (tag appended). Layout in our
+    // wire format is nonce || ct+tag.
+    const ctPlusTag = gcm(key, nonce).encrypt(plaintext);
+    const out = new Uint8Array(GCM_NONCE_BYTES + ctPlusTag.length);
     out.set(nonce, 0);
     out.set(ctPlusTag, GCM_NONCE_BYTES);
     return out;
@@ -121,17 +131,15 @@ export async function encrypt(key, plaintext) {
 export async function decrypt(key, ciphertext) {
     if (key.length !== AES_KEY_BYTES)
         throw new Error(`AES key must be ${AES_KEY_BYTES} bytes`);
-    if (ciphertext.length < GCM_NONCE_BYTES + 16)
+    if (ciphertext.length < GCM_NONCE_BYTES + GCM_TAG_BYTES)
         throw new Error("ciphertext too short");
-    const s = await subtle();
-    const aesKey = await s.importKey("raw", key, "AES-GCM", false, ["decrypt"]);
     const nonce = ciphertext.slice(0, GCM_NONCE_BYTES);
     const body = ciphertext.slice(GCM_NONCE_BYTES);
-    return new Uint8Array(await s.decrypt({ name: "AES-GCM", iv: nonce }, aesKey, body));
+    return gcm(key, nonce).decrypt(body);
 }
 /**
- * Wrap (encrypt) a 32-byte session key for delivery to a remote party (e.g. the
- * worker), using a fresh ephemeral ECDH keypair.
+ * Wrap (encrypt) a 32-byte session key for delivery to a remote party
+ * (e.g. the worker), using a fresh ephemeral ECDH keypair.
  *
  * Output: ephemeralPub(65) || nonce(12) || AES-GCM(sharedSecret, sessionKey)
  */
@@ -139,22 +147,21 @@ export async function encryptSessionKey(sessionKey, remotePublicKey) {
     if (sessionKey.length !== SESSION_KEY_BYTES)
         throw new Error(`session key must be ${SESSION_KEY_BYTES} bytes`);
     const ephemeral = await generateEcdhKeyPair();
-    const shared = await deriveSharedSecret(ephemeral.privateKey, remotePublicKey);
+    const shared = deriveSharedSecret(ephemeral.privateKey, remotePublicKey);
     const ct = await encrypt(shared, sessionKey);
-    const pub = await exportPublicKey(ephemeral.publicKey);
-    const out = new Uint8Array(pub.length + ct.length);
-    out.set(pub, 0);
-    out.set(ct, pub.length);
+    const out = new Uint8Array(ephemeral.publicKey.length + ct.length);
+    out.set(ephemeral.publicKey, 0);
+    out.set(ct, ephemeral.publicKey.length);
     return out;
 }
 /** Unwrap a session key encrypted by `encryptSessionKey` using the local ECDH private key. */
 export async function decryptSessionKey(encWorkerKey, privateKey) {
-    if (encWorkerKey.length < P256_UNCOMPRESSED_KEY_BYTES + GCM_NONCE_BYTES + 16) {
+    if (encWorkerKey.length < P256_UNCOMPRESSED_KEY_BYTES + GCM_NONCE_BYTES + GCM_TAG_BYTES) {
         throw new Error("encrypted session key too short");
     }
-    const ephemeralPub = await importPublicKey(encWorkerKey.slice(0, P256_UNCOMPRESSED_KEY_BYTES));
+    const ephemeralPub = importPublicKey(encWorkerKey.slice(0, P256_UNCOMPRESSED_KEY_BYTES));
     const ct = encWorkerKey.slice(P256_UNCOMPRESSED_KEY_BYTES);
-    const shared = await deriveSharedSecret(privateKey, ephemeralPub);
+    const shared = deriveSharedSecret(privateKey, ephemeralPub);
     const sk = await decrypt(shared, ct);
     if (sk.length !== SESSION_KEY_BYTES)
         throw new Error(`session key must be ${SESSION_KEY_BYTES} bytes`);

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.7";
-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.7";
+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.7",
+  "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",
@@ -46,6 +46,8 @@
     "url": "https://github.com/marinom2/lightnode/issues"
   },
   "dependencies": {
+    "@noble/ciphers": "^1.0.0",
+    "@noble/curves": "^1.0.0",
     "viem": ">=2"
   },
   "engines": {