lightnode-sdk 0.7.15 → 0.7.17

package/dist/add.d.ts

@@ -70,6 +70,12 @@ export declare function addChatWeb3(opts?: AddOpts): {
     network: Network;
     needsWagmi: boolean;
 };
+export declare function addWagmiSetup(opts?: AddOpts): {
+    written: WrittenFile[];
+    install: string;
+    template: Template;
+    network: Network;
+};
 export declare function addJudge(opts?: AddOpts): {
     written: WrittenFile[];
     install: string;

package/dist/add.js

@@ -31,6 +31,157 @@ function detectTemplate(cwd) {
         return "hono";
     return "node";
 }
+const HOSTING_GUIDE = `# Hosting your LightChain AI app
+
+A single LightChain mainnet inference takes **60-90 seconds** (the workers
+run the model, attest the result on-chain, and return the answer). Anywhere
+that puts a short timeout on your request will fail with a generic timeout
+error. So the question is just: how do you give your route enough time to
+finish?
+
+If you used \`lightnode add chat-web3\`, skip this file - that path has NO
+server-side route, the visitor's own browser does the wait.
+
+## The clean answer: run it yourself
+
+This template ships with a **Dockerfile + docker-compose.yml** so you can
+run the entire stack on your own machine, your own VPS, or anywhere Docker
+runs. Long-running Node processes have no timeout. The result:
+
+\`\`\`bash
+docker compose up --build
+# → http://localhost:3000 ready, no signup, no per-call cost beyond your
+#   LCAI fee, no platform vendor lock-in.
+\`\`\`
+
+That's the recommended path. You own the box, you own the keys, you own
+the uptime. Costs as much as the VPS does - $5/mo on Hetzner gets you a
+2-core machine that handles plenty of traffic.
+
+### Where to run that container
+
+| Where                    | Cost                  | Notes |
+|--------------------------|-----------------------|-------|
+| Your laptop / home server | free                 | Perfect for dev + small personal projects. Expose via Cloudflare Tunnel or Tailscale Funnel if you want a public URL. |
+| Hetzner CX22             | ~€4/mo                | 2 CPU, 4 GB RAM. Generous bandwidth. EU-based. |
+| DigitalOcean droplet     | $4/mo                 | 1 CPU, 512 MB. Bumps to $6 for 1 GB. |
+| OVH VPS                  | ~€3/mo                | Cheap, EU. |
+| AWS Lightsail            | $5/mo                 | 1 CPU, 1 GB. AWS billing if you want it. |
+| Your existing k8s        | $0 marginal           | Just \`docker push\` and \`kubectl apply\`. |
+| Fly.io                   | free tier + $0-5/mo   | Their Docker-native platform, cleanest UX of the paid options. |
+| Railway                  | $5/mo                 | Same idea. No timeout, easy deploys. |
+| Render                   | $7/mo                 | Same idea. |
+| Google Cloud Run         | pay-per-request       | Scales to zero. Watch the 60-minute request limit. |
+
+## When you'd pick a managed platform instead
+
+| Platform            | Trade-off |
+|---------------------|-----------|
+| Vercel Pro ($20/mo) | If you're already deploying your Next.js app on Vercel and don't want to split infra. The 60s function cap is tight for mainnet (70-80s calls cut it close); rely on streaming to keep the connection warm. **Hobby tier (free) does NOT work** - 10s cap, every call times out. |
+| Netlify             | 26s sync function cap is too tight. Use Netlify's "background functions" (15min) and adapt the route to write the result to KV / a webhook. More work. |
+| Cloudflare Workers  | 30s on free, unbounded with Durable Objects. The WebSocket relay setup is more involved than a plain Node server. |
+
+The free-tier serverless platforms (Vercel Hobby, Netlify free, Cloudflare
+free) **all fail** at the 60-90s mark. There's no way around that on those
+plans short of upgrading. If you're not paying anyway, self-host - it's
+strictly cheaper and faster than a $20/mo plan.
+
+## What I'd actually pick
+
+- **First time trying this out**: \`docker compose up\` on your laptop. Free,
+  works in 30 seconds, real end-to-end test of your code.
+- **Going to production with users**: same Dockerfile on a $5/mo Hetzner or
+  Fly VM. You're done; it'll handle plenty of traffic.
+- **You already have a Next.js app on Vercel**: upgrade to Pro and keep your
+  build pipeline. The streaming route works under their 60s cap for most
+  mainnet calls.
+- **You're building a Web3 dApp**: re-run \`lightnode add chat-web3\`. No
+  backend, no LCAI cost for you - each user pays their own way.
+
+## Why the request is slow at all
+
+LightChain inference is not a synchronous LLM call. Each request:
+1. Negotiates an ECDH-encrypted session with a worker (off-chain).
+2. Sends a \`createSession\` tx on-chain (one confirmation).
+3. Uploads the encrypted prompt blob to the gateway.
+4. Sends a \`submitJob\` tx on-chain (one confirmation).
+5. Waits for the worker to run inference + post the encrypted result.
+6. Decrypts the result client-side.
+
+Steps 2, 4, and 5 are the slow part - each waits for a block confirmation
+and worker pickup. The protocol's verifiable-AI guarantee comes from doing
+all of this on-chain instead of just hitting an OpenAI-style API, which is
+the reason the call takes 60-90s instead of 1-2s. There is no way to
+shortcut this on the SDK side; the host just has to allow long-running
+processes - which is exactly what a plain Node server (or Docker container)
+already does for free.
+`;
+/**
+ * Dockerfile that builds your Next.js app and runs it as a long-running
+ * Node server. There is no function timeout on a plain server, so a 60-90s
+ * mainnet inference just works. Multi-stage build keeps the runtime image
+ * around 200 MB.
+ */
+const NEXTJS_DOCKERFILE = `# Generated by 'lightnode add chat' (or 'add inference' / 'add judge').
+# Build a Next.js production image; run with 'docker compose up --build'.
+FROM node:20-alpine AS deps
+WORKDIR /app
+COPY package.json package-lock.json* ./
+RUN npm ci --omit=optional
+
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+ENV NEXT_TELEMETRY_DISABLED=1
+RUN npm run build
+
+FROM node:20-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+COPY --from=builder /app/public ./public
+COPY --from=builder /app/.next ./.next
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package.json ./package.json
+EXPOSE 3000
+# Long-running Node process - no function timeout to fight. Mainnet inference
+# calls (60-90s) complete normally because the process just stays up.
+CMD ["npm", "start"]
+`;
+/**
+ * docker-compose.yml. The 'env_file' line wires .env from the project root
+ * into the container at runtime, so the same PRIVATE_KEY a 'npm run dev'
+ * session uses also flows to the container build.
+ */
+const NEXTJS_DOCKER_COMPOSE = `# Generated by 'lightnode add chat' (or 'add inference' / 'add judge').
+# Quick start: docker compose up --build
+# (then visit http://localhost:3000)
+services:
+  app:
+    build: .
+    image: lightnode-app
+    container_name: lightnode-app
+    ports:
+      - "3000:3000"
+    # PRIVATE_KEY, NETWORK, MODEL are read from .env at runtime.
+    # Make sure .env exists in the same folder as this file (cp .env.example .env).
+    env_file:
+      - .env
+    restart: unless-stopped
+`;
+const DOCKERIGNORE = `# Generated by 'lightnode add chat' (or 'add inference' / 'add judge').
+.git
+.gitignore
+node_modules
+.next
+.env
+.env.local
+.env.*.local
+LIGHTNODE-HOSTING.md
+README.md
+*.log
+`;
 const ENV_EXAMPLE = (net) => `# Funded private key. Testnet works free (faucet at https://lightfaucet.ai).
 PRIVATE_KEY=0x0000000000000000000000000000000000000000000000000000000000000000
 
@@ -182,6 +333,10 @@ export function addInference(opts = {}) {
     const written = [];
     if (template === "nextjs-api") {
         written.push(writeFile(path.join(cwd, "app/api/inference/route.ts"), NEXTJS_ROUTE, force));
+        written.push(writeFile(path.join(cwd, "LIGHTNODE-HOSTING.md"), HOSTING_GUIDE, force));
+        written.push(writeFile(path.join(cwd, "Dockerfile"), NEXTJS_DOCKERFILE, force));
+        written.push(writeFile(path.join(cwd, "docker-compose.yml"), NEXTJS_DOCKER_COMPOSE, force));
+        written.push(writeFile(path.join(cwd, ".dockerignore"), DOCKERIGNORE, force));
     }
     else if (template === "hono") {
         written.push(writeFile(path.join(cwd, "lightchain-inference.ts"), HONO_HANDLER, force));
@@ -590,20 +745,47 @@ export default function Chat() {
     setTurns(next);
     setDraft("");
     setBusy(true);
+    // Reserve the assistant bubble immediately so tokens can stream into it.
+    setTurns([...next, { role: "assistant", text: "" }]);
     try {
-      // Concatenate prior turns so the model has the conversation context.
       const prompt =
         next.map((t) => (t.role === "user" ? \`User: \${t.text}\` : \`Assistant: \${t.text}\`)).join("\\n") +
         "\\nAssistant:";
       const r = await fetch("/api/inference", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ prompt }),
-      }).then((r) => r.json()) as { answer?: string; txs?: Record<string, string>; error?: string };
-      if (!r.answer) throw new Error(r.error ?? "no answer");
-      setTurns([...next, { role: "assistant", text: r.answer, txs: r.txs }]);
+        body: JSON.stringify({ prompt, stream: true }),
+      });
+      if (!r.ok || !r.body) {
+        const err = await r.text().catch(() => "");
+        throw new Error(\`route returned \${r.status}: \${err.slice(0, 200)}\`);
+      }
+      const reader = r.body.getReader();
+      const decoder = new TextDecoder();
+      let assembled = "";
+      let txs: Record<string, string> | undefined;
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        const text = decoder.decode(value, { stream: true });
+        // The route ends the stream with one line of JSON on a new \\u0000
+        // delimiter (a NUL byte we put between the streamed prose and the
+        // metadata). Anything before is body; anything after is metadata.
+        const nulIdx = text.indexOf("\\u0000");
+        if (nulIdx === -1) {
+          assembled += text;
+          setTurns((prev) => prev.map((t, i) => i === prev.length - 1 ? { ...t, text: assembled } : t));
+        } else {
+          assembled += text.slice(0, nulIdx);
+          try { txs = JSON.parse(text.slice(nulIdx + 1)) as Record<string, string>; } catch { /* ignore */ }
+          setTurns((prev) => prev.map((t, i) => i === prev.length - 1 ? { ...t, text: assembled, txs } : t));
+        }
+      }
     } catch (e) {
-      setTurns([...next, { role: "assistant", text: \`(error: \${(e as Error).message})\` }]);
+      // Replace the empty assistant bubble with the error.
+      setTurns((prev) => prev.map((t, i) =>
+        i === prev.length - 1 ? { ...t, text: \`(error: \${(e as Error).message})\` } : t
+      ));
     } finally {
       setBusy(false);
     }
@@ -664,13 +846,99 @@ export default function Chat() {
         </button>
       </div>
       <p style={{ marginTop: 16, fontSize: 12, color: "#888" }}>
-        Make sure <code>/api/inference</code> is mounted - run <code>npx lightnode add inference</code> if you have
-        not. The route signs every call server-side with the PRIVATE_KEY in your .env.
+        Your server signs every call with the PRIVATE_KEY in <code>.env</code>. Cost per turn is paid from that wallet.
+        See <code>LIGHTNODE-HOSTING.md</code> for picking a host that handles 60-90s function calls.
       </p>
     </main>
   );
 }
 `;
+/**
+ * Streaming inference route, paired with NEXTJS_CHAT_PAGE.
+ *
+ * Why a second route: the plain NEXTJS_ROUTE returns JSON in one shot,
+ * which is fine for one-off calls but means the chat UI shows nothing for
+ * 60-90s. This streams decrypted chunks as they arrive (via
+ * runInferenceStream), so the user sees tokens land live and the host
+ * keeps the connection warm. After the last chunk we append a NUL byte
+ * (\\u0000) and a JSON line with the tx hashes so the client can render
+ * the on-chain receipt under the assistant bubble.
+ */
+const NEXTJS_INFERENCE_STREAM_ROUTE = `// app/api/inference/route.ts
+// Generated by 'lightnode add chat'. Streaming inference route - tokens
+// arrive live as the model produces them, then a NUL byte separates them
+// from a final JSON line with the on-chain tx hashes.
+//
+// Pass { stream: true } in the body to get streaming. Without that flag
+// the same route still returns one-shot JSON, which is fine for non-chat
+// integrations.
+//
+// Mainnet 8b inference takes 60-90s. Vercel Hobby caps function execution
+// at 10s and will time out. See LIGHTNODE-HOSTING.md for hosts that work.
+import { NextResponse } from "next/server";
+import { runInferenceWithKey, runInferenceStream } from "lightnode-sdk";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+export const maxDuration = 120;
+
+const NETWORK = (process.env.NETWORK ?? "testnet") as "mainnet" | "testnet";
+const MODEL = process.env.MODEL ?? "llama3-8b";
+
+export async function POST(req: Request) {
+  if (!process.env.PRIVATE_KEY?.startsWith("0x")) {
+    return NextResponse.json({ error: "PRIVATE_KEY not configured" }, { status: 500 });
+  }
+  const body = (await req.json().catch(() => ({}))) as { prompt?: string; system?: string; stream?: boolean };
+  const prompt = body.prompt?.trim();
+  if (!prompt) return NextResponse.json({ error: "prompt is required" }, { status: 400 });
+
+  const args = {
+    network: NETWORK,
+    privateKey: process.env.PRIVATE_KEY as \`0x\${string}\`,
+    model: MODEL,
+    system: body.system?.trim() || undefined,
+    prompt,
+  };
+
+  // One-shot JSON path: same shape as the original 'add inference' route.
+  if (!body.stream) {
+    try {
+      const { answer, worker, txs, jobId } = await runInferenceWithKey(args);
+      return NextResponse.json({
+        answer, worker, jobId: jobId.toString(),
+        txs: { createSession: txs.createSession, submitJob: txs.submitJob, jobCompleted: txs.jobCompleted },
+      });
+    } catch (e) {
+      return NextResponse.json({ error: (e as Error).message }, { status: 500 });
+    }
+  }
+
+  // Streaming path: tokens, NUL byte, then tx metadata as JSON.
+  const stream = runInferenceStream(args);
+  const encoder = new TextEncoder();
+  const body$ = new ReadableStream({
+    async start(controller) {
+      try {
+        for await (const chunk of stream) controller.enqueue(encoder.encode(chunk));
+        const { worker, txs, jobId } = await stream.done;
+        const meta = JSON.stringify({
+          worker, jobId: jobId.toString(),
+          createSession: txs.createSession, submitJob: txs.submitJob, jobCompleted: txs.jobCompleted,
+        });
+        controller.enqueue(encoder.encode("\\u0000" + meta));
+        controller.close();
+      } catch (e) {
+        controller.enqueue(encoder.encode(\`\\u0000{"error":\${JSON.stringify((e as Error).message)}}\`));
+        controller.close();
+      }
+    },
+  });
+  return new Response(body$, {
+    headers: { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" },
+  });
+}
+`;
 const NEXTJS_CHAT_WEB3_PAGE = `// app/chat-web3/page.tsx
 // Generated by 'lightnode add chat-web3'. User-pays chat: each visitor's own
 // wallet signs SIWE + createSession per turn. Your app holds zero funds.
@@ -1101,7 +1369,16 @@ export function addChat(opts = {}) {
     const force = !!opts.force;
     const written = [];
     if (template === "nextjs-api") {
+        // 'add chat' is self-contained: it writes the chat page, the streaming
+        // inference route, the hosting guide, AND the Docker setup so the dev
+        // can run the whole stack locally (or anywhere Docker runs) with one
+        // command. No external host signup, no function-timeout fights.
         written.push(writeFile(path.join(cwd, "app/chat/page.tsx"), NEXTJS_CHAT_PAGE, force));
+        written.push(writeFile(path.join(cwd, "app/api/inference/route.ts"), NEXTJS_INFERENCE_STREAM_ROUTE, force));
+        written.push(writeFile(path.join(cwd, "LIGHTNODE-HOSTING.md"), HOSTING_GUIDE, force));
+        written.push(writeFile(path.join(cwd, "Dockerfile"), NEXTJS_DOCKERFILE, force));
+        written.push(writeFile(path.join(cwd, "docker-compose.yml"), NEXTJS_DOCKER_COMPOSE, force));
+        written.push(writeFile(path.join(cwd, ".dockerignore"), DOCKERIGNORE, force));
     }
     else {
         written.push(writeFile(path.join(cwd, "chat-repl.ts"), NODE_CHAT_REPL, force));
@@ -1149,6 +1426,151 @@ export function addChatWeb3(opts = {}) {
         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
+// point; swap in RainbowKit / Reown AppKit / ConnectKit if you want a
+// richer connect UI.
+import { createConfig, http } from "wagmi";
+import { injected } from "wagmi/connectors";
+import type { Chain } from "viem";
+
+export const lightchainMainnet: Chain = {
+  id: 9200,
+  name: "LightChain",
+  nativeCurrency: { name: "LCAI", symbol: "LCAI", decimals: 18 },
+  rpcUrls: { default: { http: ["https://rpc.mainnet.lightchain.ai"] } },
+  blockExplorers: { default: { name: "Lightscan", url: "https://mainnet.lightscan.app" } },
+};
+
+export const lightchainTestnet: Chain = {
+  id: 8200,
+  name: "LightChain Testnet",
+  nativeCurrency: { name: "LCAI", symbol: "LCAI", decimals: 18 },
+  rpcUrls: { default: { http: ["https://rpc.testnet.lightchain.ai"] } },
+  blockExplorers: { default: { name: "Lightscan", url: "https://testnet.lightscan.app" } },
+};
+
+export const wagmiConfig = createConfig({
+  chains: [lightchainMainnet, lightchainTestnet],
+  // \`injected\` covers MetaMask, Rabby, OKX, Phantom EVM, and any browser
+  // wallet that follows EIP-1193. Add walletConnect() / coinbaseWallet()
+  // here if you want explicit support for those.
+  connectors: [injected()],
+  transports: {
+    [lightchainMainnet.id]: http(),
+    [lightchainTestnet.id]: http(),
+  },
+});
+`;
+const WAGMI_PROVIDERS_FILE = `// app/providers.tsx
+// Generated by 'lightnode add wagmi-setup'. Wraps the app with the
+// wagmi + react-query providers needed for any wagmi hook to work.
+//
+// Import this from your root layout:
+//
+//   // app/layout.tsx
+//   import { Providers } from "./providers";
+//   export default function RootLayout({ children }: { children: React.ReactNode }) {
+//     return (
+//       <html lang="en">
+//         <body><Providers>{children}</Providers></body>
+//       </html>
+//     );
+//   }
+"use client";
+
+import { WagmiProvider } from "wagmi";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { wagmiConfig } from "@/lib/wagmi";
+import type { ReactNode } from "react";
+
+const queryClient = new QueryClient();
+
+export function Providers({ children }: { children: ReactNode }) {
+  return (
+    <WagmiProvider config={wagmiConfig}>
+      <QueryClientProvider client={queryClient}>
+        {children}
+      </QueryClientProvider>
+    </WagmiProvider>
+  );
+}
+`;
+const WAGMI_CONNECT_BUTTON = `// components/connect-button.tsx
+// Generated by 'lightnode add wagmi-setup'. Minimal Connect/Disconnect
+// button using wagmi's useConnect / useAccount hooks. Swap in
+// RainbowKit's ConnectButton or Reown's <w3m-button /> for a richer UI.
+"use client";
+
+import { useAccount, useConnect, useDisconnect, useSwitchChain } from "wagmi";
+
+const LIGHTCHAIN_IDS = new Set<number>([9200, 8200]);
+
+function shortAddress(addr: string): string {
+  return \`\${addr.slice(0, 6)}...\${addr.slice(-4)}\`;
+}
+
+export function ConnectButton() {
+  const { address, chain, isConnected } = useAccount();
+  const { connect, connectors, isPending } = useConnect();
+  const { disconnect } = useDisconnect();
+  const { switchChain, isPending: switching } = useSwitchChain();
+
+  if (!isConnected) {
+    const connector = connectors[0];
+    return (
+      <button
+        type="button"
+        onClick={() => connect({ connector })}
+        disabled={isPending}
+        style={{ padding: "8px 16px", borderRadius: 8, cursor: "pointer" }}
+      >
+        {isPending ? "Connecting..." : "Connect wallet"}
+      </button>
+    );
+  }
+
+  if (chain && !LIGHTCHAIN_IDS.has(chain.id)) {
+    return (
+      <button
+        type="button"
+        onClick={() => switchChain({ chainId: 9200 })}
+        disabled={switching}
+        style={{ padding: "8px 16px", borderRadius: 8, background: "#fee", cursor: "pointer" }}
+      >
+        {switching ? "Switching..." : "Switch to LightChain"}
+      </button>
+    );
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={() => disconnect()}
+      style={{ padding: "8px 16px", borderRadius: 8, cursor: "pointer", fontFamily: "monospace" }}
+    >
+      {address ? shortAddress(address) : "(unknown)"} ({chain?.name}) - disconnect
+    </button>
+  );
+}
+`;
+export function addWagmiSetup(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const network = opts.network ?? "mainnet";
+    const template = opts.template && opts.template !== "auto" ? opts.template : detectTemplate(cwd);
+    const force = !!opts.force;
+    const written = [];
+    written.push(writeFile(path.join(cwd, "lib/wagmi.ts"), WAGMI_CONFIG_FILE, force));
+    written.push(writeFile(path.join(cwd, "app/providers.tsx"), WAGMI_PROVIDERS_FILE, force));
+    written.push(writeFile(path.join(cwd, "components/connect-button.tsx"), WAGMI_CONNECT_BUTTON, force));
+    return {
+        written,
+        install: `npm install wagmi viem @tanstack/react-query`,
+        template,
+        network,
+    };
+}
 const NEXTJS_JUDGE_ROUTE = `// app/api/judge/route.ts
 // Generated by 'lightnode add judge'. See https://lightnode.app/build
 // The LightChallenge-style evaluator: post evidence + criteria, get a
@@ -1282,6 +1704,10 @@ export function addJudge(opts = {}) {
     const written = [];
     if (template === "nextjs-api") {
         written.push(writeFile(path.join(cwd, "app/api/judge/route.ts"), NEXTJS_JUDGE_ROUTE, force));
+        written.push(writeFile(path.join(cwd, "LIGHTNODE-HOSTING.md"), HOSTING_GUIDE, force));
+        written.push(writeFile(path.join(cwd, "Dockerfile"), NEXTJS_DOCKERFILE, force));
+        written.push(writeFile(path.join(cwd, "docker-compose.yml"), NEXTJS_DOCKER_COMPOSE, force));
+        written.push(writeFile(path.join(cwd, ".dockerignore"), DOCKERIGNORE, force));
     }
     else {
         written.push(writeFile(path.join(cwd, "judge.ts"), NODE_JUDGE_SCRIPT, force));

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 } from "./add.js";
+import { addInference, 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) {
@@ -462,7 +462,7 @@ 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", "agent", "judge", "analytics-dashboard", "nft-mint-with-inference"];
+            const known = ["inference", "chat", "chat-web3", "wagmi-setup", "agent", "judge", "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]`);
             }
@@ -472,13 +472,15 @@ async function main() {
                     ? addNftMint({ template, network, force })
                     : sub === "chat-web3"
                         ? addChatWeb3({ 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 });
+                        : 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,16 +495,25 @@ async function main() {
             else {
                 console.log(`\nNext steps (these files were added to your CURRENT folder, not a new project):`);
                 console.log(`  1. ${result.install}`);
-                if (sub === "chat-web3") {
+                if (sub === "wagmi-setup") {
+                    console.log(`  2. Import Providers in app/layout.tsx and wrap children:`);
+                    console.log(`     import { Providers } from "./providers";`);
+                    console.log(`     // <body><Providers>{children}</Providers></body>`);
+                    console.log(`  3. Drop <ConnectButton /> anywhere you want a connect UI:`);
+                    console.log(`     import { ConnectButton } from "@/components/connect-button";`);
+                    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).
                     const needsWagmi = result.needsWagmi;
                     if (needsWagmi) {
-                        console.log(`  2. Set up wagmi in your app if you have not already.`);
-                        console.log(`     See https://wagmi.sh/react/getting-started - wrap your root layout with`);
-                        console.log(`     <WagmiProvider config={wagmiConfig}> and add a Connect button using`);
-                        console.log(`     useConnect / RainbowKit / Reown AppKit / ConnectKit, whatever you prefer.`);
-                        console.log(`  3. npm run dev, open /chat-web3`);
-                        console.log(`  4. Connect a wallet on LightChain ${result.network === "mainnet" ? "mainnet (chainId 9200)" : "testnet (chainId 8200)"}.`);
+                        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`);
                     }
                     else {
@@ -510,6 +521,8 @@ async function main() {
                         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(`\n  Note: chat-web3 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") {
                     console.log(`  2. cp .env.example .env  (and put a funded ${result.network} PRIVATE_KEY in it)`);
@@ -521,14 +534,18 @@ async function main() {
                         console.log(`  3. AGENT_INTERVAL_MS=3600000 npx tsx agent.ts   # or run under pm2/systemd`);
                     }
                     else if (sub === "chat" && result.template === "nextjs-api") {
-                        console.log(`  3. Make sure /api/inference is mounted too (run: npx lightnode add inference)`);
-                        console.log(`  4. npm run dev, open /chat`);
+                        console.log(`  3. Pick one:`);
+                        console.log(`     a) docker compose up --build         # run the whole stack yourself, no timeout`);
+                        console.log(`     b) npm run dev                       # local dev only`);
+                        console.log(`     Open http://localhost:3000/chat`);
                     }
                     else if (sub === "chat") {
                         console.log(`  3. npx tsx chat-repl.ts  (interactive terminal chat)`);
                     }
                     else if (sub === "judge" && result.template === "nextjs-api") {
-                        console.log(`  3. npm run dev`);
+                        console.log(`  3. Pick one:`);
+                        console.log(`     a) docker compose up --build         # run the whole stack yourself, no timeout`);
+                        console.log(`     b) npm run dev                       # local dev only`);
                         console.log(`  4. curl -X POST localhost:3000/api/judge -H 'content-type: application/json' \\\\`);
                         console.log(`         -d '{"criteria":"Run a mile under 8 minutes","evidence":{"time_minutes":7.4,"distance_km":1.61}}'`);
                     }
@@ -540,7 +557,10 @@ async function main() {
                         console.log(`  4. npm run dev, open /nft-mint`);
                     }
                     else if (result.template === "nextjs-api") {
-                        console.log(`  3. npm run dev  (then POST /api/inference)`);
+                        console.log(`  3. Pick one:`);
+                        console.log(`     a) docker compose up --build         # run the whole stack yourself, no timeout`);
+                        console.log(`     b) npm run dev                       # local dev only`);
+                        console.log(`     POST http://localhost:3000/api/inference  {"prompt":"hello"}`);
                     }
                     else if (result.template === "hono") {
                         console.log(`  3. wire inferenceHandler into your Hono app, then start it`);
@@ -561,6 +581,17 @@ async function main() {
                         console.log(`  2. npx tsx lightnode-analytics.ts`);
                     }
                 }
+                // Hosting note: the Docker setup we shipped is the recommended path.
+                // The managed platforms (Vercel etc.) are the fallback if a builder is
+                // already committed to one.
+                if (result.template === "nextjs-api"
+                    && (sub === "inference" || sub === "chat" || sub === "judge")) {
+                    console.log(`\n  Hosting: a mainnet inference takes 60-90s. The Dockerfile + docker-compose.yml`);
+                    console.log(`  we just dropped run a long-running Node server with no timeout - that's the`);
+                    console.log(`  recommended path (your laptop, a $5/mo VPS, anywhere Docker runs).`);
+                    console.log(`  Don't use Vercel Hobby (10s cap, every call times out). Vercel Pro works at`);
+                    console.log(`  60s if you'd rather stay on Vercel. See LIGHTNODE-HOSTING.md for the full table.`);
+                }
                 if (result.network === "testnet") {
                     console.log(`\nNo wallet yet? Make one:  npx lightnode wallet new   then fund it free below.`);
                 }

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