lightnode-sdk 0.7.18 → 0.7.20

package/README.md

@@ -464,17 +464,35 @@ PRIVATE_KEY=0x... npx lightnode worker deregister --yes    # clear stuck + settl
 
 ### Scaffolders (write files into your project)
 
+Server-paid (you host a backend; your funded wallet pays per call):
+
 ```bash
 npx lightnode add inference                    # encrypted inference route or script
 npx lightnode add chat                         # chat UI with conversation history
+npx lightnode add judge                        # pass/fail evaluator route (criteria + evidence)
 npx lightnode add agent                        # scheduled inference (Vercel Cron / setInterval)
 npx lightnode add analytics-dashboard          # read-only network + worker analytics page
 npx lightnode add nft-mint-with-inference      # AI-generated NFT metadata with on-chain provenance
 ```
 
+User-paid (no backend; each visitor signs + pays from their own wallet):
+
+```bash
+npx lightnode add inference-web3               # one-shot inference UI, wallet-signed
+npx lightnode add chat-web3                     # chat UI, wallet-signed (mainnet + testnet aware)
+npx lightnode add judge-web3                    # evaluator UI, wallet-signed
+npx lightnode add wagmi-setup                   # wallet wiring: lib/wagmi + providers + connect button
+```
+
+The `*-web3` scaffolders and `wagmi-setup` write Next.js pages, so run them
+inside a Next.js app (`npx create-next-app@latest .` first if you have none).
+
 All `add` commands accept `--template auto|nextjs-api|hono|node`,
 `--net testnet|mainnet`, and `--force`.
 
+> If `add <name>` reports an unknown target, your `npx` cache is serving an
+> older CLI. Force the current release: `npx lightnode-sdk@latest add <name>`.
+
 ## Networks
 
 | | Testnet | Mainnet |

package/dist/add.js

@@ -321,6 +321,17 @@ function depsNeeded(template) {
     // installed too, otherwise `tsx ...` fails with "command not found".
     return ["lightnode-sdk", "viem", "ws", "tsx"];
 }
+/** Full `npm install` line for a template's next-steps, including the dev type
+ *  packages an editor needs. The node/script template uses Node builtins
+ *  (`node:process`, `node:readline`) and imports `ws`, so without @types/node
+ *  and @types/ws a freshly-scaffolded file is a wall of red squiggles in any
+ *  TypeScript-aware editor even though `tsx` runs it fine. */
+function installLine(template) {
+    const runtime = `npm install ${depsNeeded(template).join(" ")}`;
+    if (template === "node")
+        return `${runtime} && npm install -D @types/node @types/ws`;
+    return runtime;
+}
 /**
  * Implementation called by `lightnode add inference [...]`.
  * Returns the list of files written + the install command the user should run.
@@ -347,7 +358,7 @@ export function addInference(opts = {}) {
     written.push(writeFile(path.join(cwd, ".env.example"), ENV_EXAMPLE(network), force));
     return {
         written,
-        install: `npm install ${depsNeeded(template).join(" ")}`,
+        install: installLine(template),
         template,
         network,
     };
@@ -1708,7 +1719,7 @@ export function addAgent(opts = {}) {
         written.push(writeFile(path.join(cwd, "agent.ts"), NODE_AGENT_SCRIPT, force));
     }
     written.push(writeFile(path.join(cwd, ".env.example"), ENV_EXAMPLE(network), force));
-    return { written, install: `npm install ${depsNeeded(template).join(" ")}`, template, network };
+    return { written, install: installLine(template), template, network };
 }
 export function addChat(opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
@@ -1732,7 +1743,7 @@ export function addChat(opts = {}) {
         written.push(writeFile(path.join(cwd, "chat-repl.ts"), NODE_CHAT_REPL, force));
     }
     written.push(writeFile(path.join(cwd, ".env.example"), ENV_EXAMPLE(network), force));
-    return { written, install: `npm install ${depsNeeded(template).join(" ")}`, template, network };
+    return { written, install: installLine(template), template, network };
 }
 /**
  * `lightnode add chat-web3` - the user-pays counterpart to addChat.
@@ -2114,7 +2125,7 @@ export function addJudge(opts = {}) {
         written.push(writeFile(path.join(cwd, "judge.ts"), NODE_JUDGE_SCRIPT, force));
     }
     written.push(writeFile(path.join(cwd, ".env.example"), ENV_EXAMPLE(network), force));
-    return { written, install: `npm install ${depsNeeded(template).join(" ")}`, template, network };
+    return { written, install: installLine(template), template, network };
 }
 export function addNftMint(opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
@@ -2132,7 +2143,7 @@ export function addNftMint(opts = {}) {
     written.push(writeFile(path.join(cwd, ".env.example"), ENV_EXAMPLE(network), force));
     return {
         written,
-        install: `npm install ${depsNeeded(template).join(" ")}`,
+        install: installLine(template),
         template,
         network,
     };

package/dist/cli.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
-import { LightNode, modelStatsCsv, workerStatsCsv, workerJobsCsv, runInferenceWithKey, runInferenceBatch, Agent, isStalledWorker, workerPreflight, workerWatch, WorkerOperator, isWorkerOpError, BRIDGE_ROUTE, DAO, DAO_ADDRESSES } from "./index.js";
+import { LightNode, modelStatsCsv, workerStatsCsv, workerJobsCsv, runInferenceWithKey, runInferenceBatch, Agent, isStalledWorker, workerPreflight, workerWatch, WorkerOperator, isWorkerOpError, BRIDGE_ROUTE, DAO, DAO_ADDRESSES, SDK_VERSION } from "./index.js";
 import { addInference, addInferenceWeb3, addJudgeWeb3, addAnalyticsDashboard, addNftMint, addChat, addChatWeb3, addAgent, addJudge, addWagmiSetup } from "./add.js";
 import { createPublicClient, createWalletClient, http, parseEther } from "viem";
 import { privateKeyToAccount, generatePrivateKey } from "viem/accounts";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
 function flag(name) {
     const i = process.argv.indexOf(name);
     return i >= 0 ? process.argv[i + 1] : undefined;
@@ -62,15 +64,27 @@ Ecosystem (read-only):
   dao addresses            print LCAI Governor + Timelock + Treasury addresses
   dao config               print voting delay / period / threshold (live read)
 
-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)
-  add analytics-dashboard         read-only network + worker analytics page
-  add nft-mint-with-inference     AI-generated NFT metadata (provenance on-chain)
-                                  (all add commands: [--template auto|nextjs-api|hono|node] [--force])
+Scaffold templates into the current project (run inside a Next.js app):
+  Server-paid (you host a backend; your funded wallet pays per call):
+    add inference                 end-to-end encrypted inference route/script
+    add chat                      chat-style UI with conversation history
+    add judge                     pass/fail evaluator route (criteria + evidence)
+    add agent                     scheduled/loop inference (cron-style)
+    add analytics-dashboard       read-only network + worker analytics page
+    add nft-mint-with-inference   AI-generated NFT metadata (provenance on-chain)
+  User-paid (no backend; each visitor signs + pays from their own wallet):
+    add inference-web3            one-shot inference UI, wallet-signed
+    add chat-web3                 chat UI, wallet-signed (mainnet + testnet aware)
+    add judge-web3                evaluator UI, wallet-signed
+    add wagmi-setup               wallet wiring: lib/wagmi + providers + connect button
+                                  (all add commands: [--template auto|nextjs-api|hono|node] [--net testnet|mainnet] [--force])
 
-To scaffold a new project instead, run: npm create lightnode-app my-app`;
+To scaffold a new project instead, run: npm create lightnode-app my-app
+
+Diagnostics:
+  version                  print this CLI's version (also: --version, -v)
+                           (a missing 'add' target usually means an old install -
+                            update with: npm install -g lightnode-sdk@latest)`;
 function pickKey() {
     const k = flag("--key") ?? process.env.PRIVATE_KEY;
     if (!k || !k.startsWith("0x") || k.length !== 66) {
@@ -113,6 +127,14 @@ async function workerJobIds(n, address) {
     return jobs.map((j) => Number(j.id)).filter((x) => Number.isFinite(x));
 }
 async function main() {
+    // Answer `version` / `--version` / `-v` before anything else so a user who
+    // suspects they're on a stale binary can confirm it without a network call
+    // or a funded key. This is the first thing to check when an `add` target
+    // "doesn't exist" - an old global install is the common cause.
+    if (cmd === "version" || process.argv.includes("--version") || process.argv.includes("-v")) {
+        console.log(SDK_VERSION);
+        return;
+    }
     const ln = new LightNode(net);
     switch (cmd) {
         case "chat": {
@@ -464,7 +486,24 @@ async function main() {
             const network = (net === "mainnet" ? "mainnet" : "testnet");
             const known = ["inference", "inference-web3", "chat", "chat-web3", "judge", "judge-web3", "wagmi-setup", "agent", "analytics-dashboard", "nft-mint-with-inference"];
             if (!known.includes(sub ?? "")) {
-                die(`usage: lightnode add <${known.join("|")}> [--template auto|nextjs-api|hono|node] [--net testnet|mainnet] [--force]`);
+                const lines = [
+                    `usage: lightnode add <${known.join("|")}> [--template auto|nextjs-api|hono|node] [--net testnet|mainnet] [--force]`,
+                ];
+                // A target that's missing here but valid in a newer release means the
+                // user is running an OLD lightnode-sdk. The usual cause is an outdated
+                // GLOBAL install (`npm i -g lightnode-sdk`) on PATH, which npx prefers
+                // over the registry - so `npx lightnode-sdk add ...` keeps hitting the
+                // stale binary. We can't know the latest version offline, but we can
+                // show what THIS binary is and the two commands that fix it. Listing
+                // the global update first because that's the one most people miss.
+                if (sub) {
+                    lines.push("");
+                    lines.push(`unknown add target "${sub}" - this CLI is lightnode-sdk v${SDK_VERSION}, which`);
+                    lines.push(`does not have it. You're likely on an older install. Update, then retry:`);
+                    lines.push(`  npm install -g lightnode-sdk@latest     # if 'lightnode' is on your PATH`);
+                    lines.push(`  npx lightnode-sdk@latest add ${sub}   # or force the latest for one run`);
+                }
+                die(lines.join("\n"));
             }
             const result = sub === "analytics-dashboard" ? addAnalyticsDashboard({ template, network, force })
                 : sub === "nft-mint-with-inference" ? addNftMint({ template, network, force })
@@ -488,6 +527,26 @@ async function main() {
                 console.log("\nNothing to do - all target files already exist. Pass --force to overwrite.");
             }
             else {
+                // The *-web3 pages and wagmi-setup are Next.js React files. If no
+                // Next.js app was detected (e.g. an empty folder), nothing can render
+                // what we just wrote - surface that before the numbered steps so the
+                // user scaffolds an app first instead of chasing a non-running page.
+                const isNextOnly = sub === "chat-web3" || sub === "inference-web3" || sub === "judge-web3" || sub === "wagmi-setup";
+                const hasPackageJson = existsSync(join(process.cwd(), "package.json"));
+                if (isNextOnly && result.template !== "nextjs-api") {
+                    console.log(`\nNo Next.js app detected in this folder. ${sub} is a Next.js page, so`);
+                    console.log(`create one here first, then re-run this command:`);
+                    console.log(`  npx create-next-app@latest .`);
+                }
+                else if (!hasPackageJson) {
+                    // A scaffolded script dropped into a bare folder (no package.json)
+                    // gives the editor nothing to resolve Node/ws types against - the
+                    // user sees "Cannot find name 'process'" everywhere. Initialize a
+                    // project first so the install below lands in a real node_modules.
+                    console.log(`\nNo package.json in this folder yet, so your editor can't resolve types`);
+                    console.log(`(you'd see "Cannot find name 'process'" etc.). Initialize a project first:`);
+                    console.log(`  npm init -y`);
+                }
                 console.log(`\nNext steps (these files were added to your CURRENT folder, not a new project):`);
                 console.log(`  1. ${result.install}`);
                 if (sub === "wagmi-setup") {

package/dist/index.d.ts

@@ -134,7 +134,7 @@ 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.7.18";
+export declare const SDK_VERSION = "0.7.20";
 export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, resolveJobTransactions, siweSignIn, siweChallenge, siweVerify, fetchWorkerModels, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, runInference, runInferenceWithKey, runInferenceStream, Conversation, chat, runInferenceBatch, Agent, parseAgentOutput, workerPreflight, workerWatch, Bridge, BRIDGE_ROUTE, HYPERLANE_ROUTER_ABI, ERC20_ABI, addressToBytes32, quoteBridgeFee, bridgeableBalance, bridgeAllowance, approveBridge, bridgeTransfer, DAO, DAO_ADDRESSES, ProposalState, PROPOSAL_STATE_LABEL, VoteSupport, GOVERNOR_ABI, VOTES_ABI, OnchainModelRegistry, AIVM_MODEL_REGISTRY_ABI, BENCHMARK_REGISTRY_ABI, ModelStatus, MODEL_STATUS_LABEL, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, WorkerOperator, WORKER_REGISTRY_ABI, JOB_REGISTRY_OPERATOR_ABI, AI_CONFIG_ABI, JOB_STATE, decodeWorkerError, WorkerOpError, isWorkerOpError, };
 export type { BearerSource, GatewayClientOptions, SelectSessionResult, PrepareSessionResult, UploadBlobResult, SessionTokenResult } from "./gateway.js";
 export type { SessionPreparation, RunInferenceArgs, RunInferenceResult, RunInferenceWithKeyArgs, RunInferenceStreamResult } from "./inference.js";

package/dist/index.js

@@ -213,7 +213,7 @@ 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.7.18";
+export const SDK_VERSION = "0.7.20";
 export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, 
 // v0.7.3 per-job transaction-hash resolver (lifts the upstream
 // subgraph's "block-only" Job entity to a deep-linkable Job + tx pair).

package/package.json

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