lightnode-sdk 0.7.17 → 0.7.19

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.d.ts

@@ -70,6 +70,39 @@ export declare function addChatWeb3(opts?: AddOpts): {
     network: Network;
     needsWagmi: boolean;
 };
+/**
+ * `lightnode add inference-web3` - the user-pays counterpart to addInference.
+ *
+ * Browser-only React component. Each visitor signs SIWE + createSession from
+ * their own wallet. No backend, no PRIVATE_KEY, no per-call cost for the dev.
+ *
+ * Fits any one-shot inference UI: classifier, NFT trait generator, content
+ * moderation, evaluator. For multi-turn chat use addChatWeb3; for the
+ * dedicated judge pattern use addJudgeWeb3.
+ */
+export declare function addInferenceWeb3(opts?: AddOpts): {
+    written: WrittenFile[];
+    install: string;
+    template: Template;
+    network: Network;
+    needsWagmi: boolean;
+};
+/**
+ * `lightnode add judge-web3` - the user-pays counterpart to addJudge.
+ *
+ * The LightChallenge pattern with the user paying: visitor submits criteria
+ * + evidence, signs from their own wallet, the structured pass/fail/confidence
+ * verdict comes back with on-chain proof. Fit: challenge completion grading,
+ * NFT trait verification, content moderation, automated scoring - any flow
+ * where the END USER wants a verifiable AI verdict on their own submission.
+ */
+export declare function addJudgeWeb3(opts?: AddOpts): {
+    written: WrittenFile[];
+    install: string;
+    template: Template;
+    network: Network;
+    needsWagmi: boolean;
+};
 export declare function addWagmiSetup(opts?: AddOpts): {
     written: WrittenFile[];
     install: string;

package/dist/add.js

@@ -1140,6 +1140,354 @@ export default function ChatWeb3() {
   );
 }
 `;
+const NEXTJS_INFERENCE_WEB3_PAGE = `// app/inference-web3/page.tsx
+// Generated by 'lightnode add inference-web3'. User-pays one-shot inference:
+// each visitor's wallet signs SIWE + createSession + submitJob. Your app
+// holds zero funds and the answer comes back with on-chain proof anyone
+// can verify.
+//
+// Prereqs:
+//   - wagmi configured (npx lightnode add wagmi-setup if you don't have it)
+//   - the connected wallet has LCAI on the chain it's on
+//     (mainnet 9200 or testnet 8200). Mainnet llama3-8b is 0.02 LCAI per call.
+"use client";
+
+import { useEffect, useState } from "react";
+import { useAccount, useWalletClient, usePublicClient } from "wagmi";
+import { siweSignIn, GatewayClient, runInference, estimateJobFee, NETWORKS } from "lightnode-sdk";
+
+type Result = {
+  answer: string;
+  worker: \`0x\${string}\`;
+  jobId: string;
+  submitJob: \`0x\${string}\`;
+  jobCompleted: \`0x\${string}\` | null;
+  elapsedMs: number;
+};
+
+const MODEL = "llama3-8b";
+
+export default function InferenceWeb3() {
+  const { address, chain } = useAccount();
+  const network: "mainnet" | "testnet" | null =
+    chain?.id === 9200 ? "mainnet" : chain?.id === 8200 ? "testnet" : null;
+  const { data: walletClient } = useWalletClient({ chainId: chain?.id });
+  const publicClient = usePublicClient({ chainId: chain?.id });
+
+  const [system, setSystem] = useState("You are a concise assistant. Reply in one or two short sentences.");
+  const [prompt, setPrompt] = useState("Reply with the single word OK.");
+  const [busy, setBusy] = useState(false);
+  const [busyStage, setBusyStage] = useState("");
+  const [result, setResult] = useState<Result | null>(null);
+  const [err, setErr] = useState<string | null>(null);
+  const [feeLcai, setFeeLcai] = useState<number | null>(null);
+
+  useEffect(() => {
+    if (!network) { setFeeLcai(null); return; }
+    let cancelled = false;
+    estimateJobFee(NETWORKS[network], MODEL).then(
+      (fee) => { if (!cancelled) setFeeLcai(fee); },
+      () => { if (!cancelled) setFeeLcai(null); },
+    );
+    return () => { cancelled = true; };
+  }, [network]);
+
+  async function run() {
+    if (!walletClient || !publicClient || !address || !network) {
+      setErr("Connect a wallet on LightChain mainnet (9200) or testnet (8200) first.");
+      return;
+    }
+    if (!prompt.trim()) return;
+    setBusy(true);
+    setErr(null);
+    setResult(null);
+    const t0 = Date.now();
+    try {
+      setBusyStage("Sign in with your wallet (SIWE)...");
+      const session = await siweSignIn(walletClient as unknown as Parameters<typeof siweSignIn>[0], network);
+
+      setBusyStage("Approve the createSession transaction in your wallet...");
+      const gateway = new GatewayClient({ network, bearer: session.bearer });
+      const composed = system.trim() ? \`\${system.trim()}\\n\\n\${prompt}\` : prompt;
+      const r = await runInference({
+        prompt: composed,
+        gateway,
+        wallet: walletClient as unknown as Parameters<typeof runInference>[0]["wallet"],
+        publicClient: publicClient as unknown as Parameters<typeof runInference>[0]["publicClient"],
+        network: NETWORKS[network],
+        model: MODEL,
+        jobCompletedTimeoutMs: 120_000,
+        maxRetries: 1,
+      });
+      setResult({
+        answer: r.answer,
+        worker: r.worker,
+        jobId: r.jobId?.toString() ?? "",
+        submitJob: r.txs?.submitJob,
+        jobCompleted: r.txs?.jobCompleted ?? null,
+        elapsedMs: Date.now() - t0,
+      });
+    } catch (e) {
+      const msg = (e as Error).message ?? "inference failed";
+      setErr(
+        /user rejected|user denied|reject/i.test(msg) ? "You rejected the wallet popup. Try again."
+        : /insufficient funds|insufficient balance/i.test(msg)
+          ? \`Your wallet has no \${network === "mainnet" ? "LCAI" : "testnet LCAI"}. Top it up before sending.\`
+          : msg.split("\\n")[0]
+      );
+    } finally {
+      setBusy(false);
+      setBusyStage("");
+    }
+  }
+
+  return (
+    <main style={{ maxWidth: 720, margin: "32px auto", padding: 16, fontFamily: "system-ui" }}>
+      <h1>Inference (user-pays)</h1>
+      <p style={{ color: "#666" }}>
+        Signs one encrypted inference from your wallet on{" "}
+        <code>{network ?? "(connect a wallet)"}</code>. Fee:{" "}
+        <code>{feeLcai != null ? \`\${feeLcai} LCAI\` : "(fetching)"}</code> per call plus a small gas amount.
+      </p>
+      {!address && (
+        <div style={{ border: "1px solid #ddd", borderRadius: 8, padding: 12, margin: "12px 0" }}>
+          Connect a wallet to run inference. Drop &lt;ConnectButton /&gt; here or wherever your app exposes one.
+        </div>
+      )}
+
+      <label style={{ display: "block", margin: "12px 0" }}>
+        <div style={{ fontSize: 11, textTransform: "uppercase", color: "#888", marginBottom: 4 }}>System prompt</div>
+        <textarea value={system} onChange={(e) => setSystem(e.target.value)} rows={2}
+          style={{ width: "100%", padding: 8, fontFamily: "monospace", fontSize: 12 }} />
+      </label>
+      <label style={{ display: "block", margin: "12px 0" }}>
+        <div style={{ fontSize: 11, textTransform: "uppercase", color: "#888", marginBottom: 4 }}>Prompt</div>
+        <textarea value={prompt} onChange={(e) => setPrompt(e.target.value)} rows={5}
+          style={{ width: "100%", padding: 8, fontFamily: "monospace", fontSize: 12 }} />
+      </label>
+      <button type="button" onClick={() => run()} disabled={busy || !prompt.trim() || !address || !network}
+        style={{ padding: "8px 16px", borderRadius: 8, cursor: busy ? "wait" : "pointer" }}>
+        {busy ? (busyStage || "Running...") : "Run inference"}
+      </button>
+
+      {err && (
+        <p style={{ marginTop: 12, padding: "8px 12px", border: "1px solid #f5c2c7", background: "#f8d7da", color: "#842029", borderRadius: 6 }}>
+          {err}
+        </p>
+      )}
+
+      {result && (
+        <div style={{ marginTop: 16, padding: 16, border: "1px solid #ddd", borderRadius: 8 }}>
+          <div style={{ fontSize: 11, textTransform: "uppercase", color: "#888", marginBottom: 8 }}>Answer</div>
+          <pre style={{ whiteSpace: "pre-wrap", margin: 0, fontFamily: "inherit" }}>{result.answer}</pre>
+          <div style={{ marginTop: 12, fontSize: 12, color: "#666", display: "flex", gap: 12, flexWrap: "wrap" }}>
+            <span>elapsed {Math.round(result.elapsedMs / 1000)}s</span>
+            <span>job #{result.jobId}</span>
+            <a href={\`https://\${network}.lightscan.app/address/\${result.worker}\`} target="_blank" rel="noopener noreferrer">worker</a>
+            <a href={\`https://\${network}.lightscan.app/tx/\${result.submitJob}\`} target="_blank" rel="noopener noreferrer">submitJob</a>
+            {result.jobCompleted && (
+              <a href={\`https://\${network}.lightscan.app/tx/\${result.jobCompleted}\`} target="_blank" rel="noopener noreferrer">jobCompleted</a>
+            )}
+          </div>
+        </div>
+      )}
+    </main>
+  );
+}
+`;
+const NEXTJS_JUDGE_WEB3_PAGE = `// app/judge-web3/page.tsx
+// Generated by 'lightnode add judge-web3'. The LightChallenge pattern with
+// the user paying: visitor submits criteria + evidence, signs from their own
+// wallet, the verdict comes back with on-chain proof. Pattern fits any
+// platform where users want a verifiable AI verdict on their own submission
+// (challenge completion, NFT trait grading, content moderation, etc.).
+//
+// Prereqs:
+//   - wagmi configured (npx lightnode add wagmi-setup if you don't have it)
+//   - the connected wallet has LCAI on the chain it's on
+"use client";
+
+import { useEffect, useState } from "react";
+import { useAccount, useWalletClient, usePublicClient } from "wagmi";
+import { siweSignIn, GatewayClient, runInference, estimateJobFee, NETWORKS } from "lightnode-sdk";
+
+type Verdict = {
+  passed: boolean;
+  confidence: number;
+  reason: string;
+};
+
+type Result = {
+  verdict: Verdict | null;
+  raw: string;
+  worker: \`0x\${string}\`;
+  jobId: string;
+  submitJob: \`0x\${string}\`;
+  jobCompleted: \`0x\${string}\` | null;
+};
+
+const MODEL = "llama3-8b";
+
+export default function JudgeWeb3() {
+  const { address, chain } = useAccount();
+  const network: "mainnet" | "testnet" | null =
+    chain?.id === 9200 ? "mainnet" : chain?.id === 8200 ? "testnet" : null;
+  const { data: walletClient } = useWalletClient({ chainId: chain?.id });
+  const publicClient = usePublicClient({ chainId: chain?.id });
+
+  const [criteria, setCriteria] = useState("Run a mile under 8 minutes");
+  const [evidence, setEvidence] = useState('{"distance_km": 1.61, "time_minutes": 7.4}');
+  const [busy, setBusy] = useState(false);
+  const [busyStage, setBusyStage] = useState("");
+  const [result, setResult] = useState<Result | null>(null);
+  const [err, setErr] = useState<string | null>(null);
+  const [feeLcai, setFeeLcai] = useState<number | null>(null);
+
+  useEffect(() => {
+    if (!network) { setFeeLcai(null); return; }
+    let cancelled = false;
+    estimateJobFee(NETWORKS[network], MODEL).then(
+      (fee) => { if (!cancelled) setFeeLcai(fee); },
+      () => { if (!cancelled) setFeeLcai(null); },
+    );
+    return () => { cancelled = true; };
+  }, [network]);
+
+  /** Parse the verdict defensively; fall back to the first {...} block. */
+  function parseVerdict(answer: string): Verdict | null {
+    try { return JSON.parse(answer) as Verdict; } catch { /* try regex */ }
+    const m = answer.match(/\\{[\\s\\S]*\\}/);
+    if (m) {
+      try { return JSON.parse(m[0]) as Verdict; } catch { /* keep null */ }
+    }
+    return null;
+  }
+
+  async function run() {
+    if (!walletClient || !publicClient || !address || !network) {
+      setErr("Connect a wallet on LightChain mainnet (9200) or testnet (8200) first.");
+      return;
+    }
+    if (!criteria.trim() || !evidence.trim()) return;
+    // Validate evidence JSON before paying.
+    try { JSON.parse(evidence); } catch {
+      setErr("Evidence is not valid JSON. Fix it and try again.");
+      return;
+    }
+    setBusy(true);
+    setErr(null);
+    setResult(null);
+    try {
+      setBusyStage("Sign in with your wallet (SIWE)...");
+      const session = await siweSignIn(walletClient as unknown as Parameters<typeof siweSignIn>[0], network);
+
+      setBusyStage("Approve the createSession transaction in your wallet...");
+      const gateway = new GatewayClient({ network, bearer: session.bearer });
+      const prompt = \`Criteria: \${criteria.trim()}
+
+Evidence: \${evidence.trim()}
+
+Reply with STRICT JSON only, matching: { "passed": boolean, "confidence": 0-1, "reason": string }\`;
+
+      const r = await runInference({
+        prompt: \`You are a careful judge. Reply with STRICT JSON only, no prose.\\n\\n\${prompt}\`,
+        gateway,
+        wallet: walletClient as unknown as Parameters<typeof runInference>[0]["wallet"],
+        publicClient: publicClient as unknown as Parameters<typeof runInference>[0]["publicClient"],
+        network: NETWORKS[network],
+        model: MODEL,
+        jobCompletedTimeoutMs: 120_000,
+        maxRetries: 1,
+      });
+      setResult({
+        verdict: parseVerdict(r.answer),
+        raw: r.answer,
+        worker: r.worker,
+        jobId: r.jobId?.toString() ?? "",
+        submitJob: r.txs?.submitJob,
+        jobCompleted: r.txs?.jobCompleted ?? null,
+      });
+    } catch (e) {
+      const msg = (e as Error).message ?? "judge failed";
+      setErr(
+        /user rejected|user denied|reject/i.test(msg) ? "You rejected the wallet popup. Try again."
+        : /insufficient funds|insufficient balance/i.test(msg)
+          ? \`Your wallet has no \${network === "mainnet" ? "LCAI" : "testnet LCAI"}. Top it up before submitting.\`
+          : msg.split("\\n")[0]
+      );
+    } finally {
+      setBusy(false);
+      setBusyStage("");
+    }
+  }
+
+  return (
+    <main style={{ maxWidth: 720, margin: "32px auto", padding: 16, fontFamily: "system-ui" }}>
+      <h1>AI Judge (user-pays)</h1>
+      <p style={{ color: "#666" }}>
+        Each submission signs one inference from your wallet on{" "}
+        <code>{network ?? "(connect a wallet)"}</code>. Cost:{" "}
+        <code>{feeLcai != null ? \`\${feeLcai} LCAI\` : "(fetching)"}</code> plus gas. Verdict comes back with on-chain proof.
+      </p>
+      {!address && (
+        <div style={{ border: "1px solid #ddd", borderRadius: 8, padding: 12, margin: "12px 0" }}>
+          Connect a wallet to submit. Drop &lt;ConnectButton /&gt; here or wherever your app exposes one.
+        </div>
+      )}
+
+      <label style={{ display: "block", margin: "12px 0" }}>
+        <div style={{ fontSize: 11, textTransform: "uppercase", color: "#888", marginBottom: 4 }}>Criteria</div>
+        <textarea value={criteria} onChange={(e) => setCriteria(e.target.value)} rows={2}
+          style={{ width: "100%", padding: 8, fontFamily: "monospace", fontSize: 12 }} />
+      </label>
+      <label style={{ display: "block", margin: "12px 0" }}>
+        <div style={{ fontSize: 11, textTransform: "uppercase", color: "#888", marginBottom: 4 }}>Evidence (JSON)</div>
+        <textarea value={evidence} onChange={(e) => setEvidence(e.target.value)} rows={5}
+          style={{ width: "100%", padding: 8, fontFamily: "monospace", fontSize: 12 }} />
+      </label>
+      <button type="button" onClick={() => run()} disabled={busy || !criteria.trim() || !evidence.trim() || !address || !network}
+        style={{ padding: "8px 16px", borderRadius: 8, cursor: busy ? "wait" : "pointer" }}>
+        {busy ? (busyStage || "Judging...") : "Get AI verdict"}
+      </button>
+
+      {err && (
+        <p style={{ marginTop: 12, padding: "8px 12px", border: "1px solid #f5c2c7", background: "#f8d7da", color: "#842029", borderRadius: 6 }}>
+          {err}
+        </p>
+      )}
+
+      {result && (
+        <div style={{ marginTop: 16, padding: 16, border: "1px solid #ddd", borderRadius: 8 }}>
+          <div style={{ fontSize: 11, textTransform: "uppercase", color: "#888", marginBottom: 8 }}>Verdict</div>
+          {result.verdict ? (
+            <div>
+              <div style={{ fontSize: 24, fontWeight: 600, color: result.verdict.passed ? "#2e7d32" : "#c62828" }}>
+                {result.verdict.passed ? "PASSED" : "FAILED"}
+                <span style={{ marginLeft: 12, fontSize: 14, color: "#666" }}>
+                  confidence {Math.round(result.verdict.confidence * 100)}%
+                </span>
+              </div>
+              <p style={{ marginTop: 8, color: "#444" }}>{result.verdict.reason}</p>
+            </div>
+          ) : (
+            <pre style={{ whiteSpace: "pre-wrap", margin: 0, fontFamily: "monospace", fontSize: 12, color: "#666" }}>
+              {result.raw}
+            </pre>
+          )}
+          <div style={{ marginTop: 12, fontSize: 12, color: "#666", display: "flex", gap: 12, flexWrap: "wrap" }}>
+            <span>job #{result.jobId}</span>
+            <a href={\`https://\${network}.lightscan.app/address/\${result.worker}\`} target="_blank" rel="noopener noreferrer">worker</a>
+            <a href={\`https://\${network}.lightscan.app/tx/\${result.submitJob}\`} target="_blank" rel="noopener noreferrer">submitJob</a>
+            {result.jobCompleted && (
+              <a href={\`https://\${network}.lightscan.app/tx/\${result.jobCompleted}\`} target="_blank" rel="noopener noreferrer">jobCompleted</a>
+            )}
+          </div>
+        </div>
+      )}
+    </main>
+  );
+}
+`;
 const NODE_CHAT_REPL = `// chat-repl.ts
 // Generated by 'lightnode add chat'. Interactive chat REPL in your terminal.
 //   npm install lightnode-sdk viem ws
@@ -1426,6 +1774,59 @@ export function addChatWeb3(opts = {}) {
         needsWagmi: !hasWagmi,
     };
 }
+/**
+ * `lightnode add inference-web3` - the user-pays counterpart to addInference.
+ *
+ * Browser-only React component. Each visitor signs SIWE + createSession from
+ * their own wallet. No backend, no PRIVATE_KEY, no per-call cost for the dev.
+ *
+ * Fits any one-shot inference UI: classifier, NFT trait generator, content
+ * moderation, evaluator. For multi-turn chat use addChatWeb3; for the
+ * dedicated judge pattern use addJudgeWeb3.
+ */
+export function addInferenceWeb3(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const network = opts.network ?? "mainnet";
+    const detected = detectTemplate(cwd);
+    const template = opts.template && opts.template !== "auto" ? opts.template : detected;
+    const force = !!opts.force;
+    const written = [];
+    const pkg = readPackageJson(cwd);
+    const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+    const hasWagmi = Boolean(deps["wagmi"]);
+    written.push(writeFile(path.join(cwd, "app/inference-web3/page.tsx"), NEXTJS_INFERENCE_WEB3_PAGE, force));
+    return {
+        written,
+        install: `npm install lightnode-sdk viem` + (hasWagmi ? "" : " wagmi @tanstack/react-query"),
+        template, network, needsWagmi: !hasWagmi,
+    };
+}
+/**
+ * `lightnode add judge-web3` - the user-pays counterpart to addJudge.
+ *
+ * The LightChallenge pattern with the user paying: visitor submits criteria
+ * + evidence, signs from their own wallet, the structured pass/fail/confidence
+ * verdict comes back with on-chain proof. Fit: challenge completion grading,
+ * NFT trait verification, content moderation, automated scoring - any flow
+ * where the END USER wants a verifiable AI verdict on their own submission.
+ */
+export function addJudgeWeb3(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const network = opts.network ?? "mainnet";
+    const detected = detectTemplate(cwd);
+    const template = opts.template && opts.template !== "auto" ? opts.template : detected;
+    const force = !!opts.force;
+    const written = [];
+    const pkg = readPackageJson(cwd);
+    const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+    const hasWagmi = Boolean(deps["wagmi"]);
+    written.push(writeFile(path.join(cwd, "app/judge-web3/page.tsx"), NEXTJS_JUDGE_WEB3_PAGE, force));
+    return {
+        written,
+        install: `npm install lightnode-sdk viem` + (hasWagmi ? "" : " wagmi @tanstack/react-query"),
+        template, network, needsWagmi: !hasWagmi,
+    };
+}
 const WAGMI_CONFIG_FILE = `// lib/wagmi.ts
 // Generated by 'lightnode add wagmi-setup'. Minimal wagmi setup for
 // LightChain mainnet (9200) + testnet (8200). Use this as a starting

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/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 { addInference, addAnalyticsDashboard, addNftMint, addChat, addChatWeb3, addAgent, addJudge, addWagmiSetup } from "./add.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";
 function flag(name) {
@@ -62,13 +62,20 @@ 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`;
 function pickKey() {
@@ -462,25 +469,31 @@ async function main() {
             const template = flag("--template") ?? "auto";
             const force = process.argv.includes("--force");
             const network = (net === "mainnet" ? "mainnet" : "testnet");
-            const known = ["inference", "chat", "chat-web3", "wagmi-setup", "agent", "judge", "analytics-dashboard", "nft-mint-with-inference"];
+            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 result = sub === "analytics-dashboard"
-                ? addAnalyticsDashboard({ template, network, force })
-                : sub === "nft-mint-with-inference"
-                    ? addNftMint({ template, network, force })
-                    : sub === "chat-web3"
-                        ? addChatWeb3({ template, network, force })
-                        : sub === "wagmi-setup"
-                            ? addWagmiSetup({ template, network, force })
-                            : sub === "chat"
-                                ? addChat({ template, network, force })
-                                : sub === "agent"
-                                    ? addAgent({ template, network, force })
-                                    : sub === "judge"
-                                        ? addJudge({ template, network, force })
-                                        : addInference({ template, network, force });
+                const lines = [
+                    `usage: lightnode add <${known.join("|")}> [--template auto|nextjs-api|hono|node] [--net testnet|mainnet] [--force]`,
+                ];
+                // If the requested name is valid in a newer release but missing here,
+                // the user is almost certainly running a stale npx-cached CLI. Point
+                // them at @latest rather than letting them think the command is gone.
+                if (sub) {
+                    lines.push("");
+                    lines.push(`unknown add target "${sub}". If you expected this to work, you may be on an`);
+                    lines.push(`older cached CLI. Force the current version:  npx lightnode-sdk@latest add ${sub}`);
+                }
+                die(lines.join("\n"));
+            }
+            const result = sub === "analytics-dashboard" ? addAnalyticsDashboard({ template, network, force })
+                : sub === "nft-mint-with-inference" ? addNftMint({ template, network, force })
+                    : sub === "chat-web3" ? addChatWeb3({ template, network, force })
+                        : sub === "inference-web3" ? addInferenceWeb3({ template, network, force })
+                            : sub === "judge-web3" ? addJudgeWeb3({ template, network, force })
+                                : sub === "wagmi-setup" ? addWagmiSetup({ template, network, force })
+                                    : sub === "chat" ? addChat({ template, network, force })
+                                        : sub === "agent" ? addAgent({ template, network, force })
+                                            : sub === "judge" ? addJudge({ template, network, force })
+                                                : addInference({ template, network, force });
             console.log(`▶ add ${sub} (${result.template} template, default network ${result.network})`);
             for (const f of result.written) {
                 if (f.skipped)
@@ -493,6 +506,16 @@ 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";
+                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 .`);
+                }
                 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") {
@@ -504,24 +527,26 @@ async function main() {
                     console.log(`  4. You can now use any wagmi hook (useAccount, useWalletClient, ...).`);
                     console.log(`     Wallets on chains other than 9200/8200 will be prompted to switch.`);
                 }
-                else if (sub === "chat-web3") {
-                    // chat-web3 has no PRIVATE_KEY (each visitor pays their own way).
+                else if (sub === "chat-web3" || sub === "inference-web3" || sub === "judge-web3") {
+                    // *-web3 variants have no PRIVATE_KEY (each visitor pays their own way).
                     const needsWagmi = result.needsWagmi;
+                    const route = sub === "chat-web3" ? "/chat-web3"
+                        : sub === "inference-web3" ? "/inference-web3"
+                            : "/judge-web3";
                     if (needsWagmi) {
                         console.log(`  2. Get wagmi wired up with one command:`);
                         console.log(`     npx lightnode add wagmi-setup`);
                         console.log(`     (drops lib/wagmi.ts + app/providers.tsx + components/connect-button.tsx)`);
-                        console.log(`  3. Wrap your layout with <Providers> (see step 2 output) and drop`);
-                        console.log(`     <ConnectButton /> somewhere on the page.`);
-                        console.log(`  4. npm run dev, open /chat-web3, connect on chainId ${result.network === "mainnet" ? "9200" : "8200"}.`);
-                        console.log(`     Mainnet llama3-8b costs 0.02 LCAI per turn; testnet is free from https://lightfaucet.ai`);
+                        console.log(`  3. Wrap your layout with <Providers> and drop <ConnectButton /> on the page.`);
+                        console.log(`  4. npm run dev, open ${route}, connect on chainId ${result.network === "mainnet" ? "9200" : "8200"}.`);
+                        console.log(`     Mainnet llama3-8b is 0.02 LCAI per call; testnet is free from https://lightfaucet.ai`);
                     }
                     else {
-                        console.log(`  2. npm run dev, open /chat-web3`);
+                        console.log(`  2. npm run dev, open ${route}`);
                         console.log(`  3. Connect a wallet on LightChain ${result.network === "mainnet" ? "mainnet (chainId 9200)" : "testnet (chainId 8200)"}.`);
-                        console.log(`     Mainnet llama3-8b costs 0.02 LCAI per turn; testnet is free from https://lightfaucet.ai`);
+                        console.log(`     Mainnet llama3-8b is 0.02 LCAI per call; testnet is free from https://lightfaucet.ai`);
                     }
-                    console.log(`\n  Note: chat-web3 has NO server-side route, so it scales infinitely on`);
+                    console.log(`\n  Note: ${sub} has NO server-side route, so it scales infinitely on`);
                     console.log(`  static hosting (Vercel/Netlify/Cloudflare Pages free tier all work).`);
                 }
                 else if (sub === "nft-mint-with-inference" || sub === "inference" || sub === "chat" || sub === "agent" || sub === "judge") {

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.17";
+export declare const SDK_VERSION = "0.7.18";
 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.17";
+export const SDK_VERSION = "0.7.18";
 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.17",
+  "version": "0.7.19",
   "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",