lightnode-sdk 0.7.16 → 0.7.17

package/dist/add.js

@@ -31,57 +31,72 @@ function detectTemplate(cwd) {
         return "hono";
     return "node";
 }
-const HOSTING_GUIDE = `# Hosting LightChain AI inference - your options
-
-A single LightChain mainnet inference takes **60-90 seconds** under normal
-load (the workers do the model run, attest the result on-chain, and return
-the answer). If your server-side route has a function timeout shorter than
-that, every call will fail with a generic timeout error.
-
-This file is a quick reference for picking a host that actually finishes
-the request. If you used \`lightnode add chat-web3\`, ignore everything
-below - that path has NO server-side route to worry about.
-
-## TL;DR
-
-| Need                                  | Use                            |
-|---------------------------------------|--------------------------------|
-| Zero infra, users pay (Web3 dApp)     | \`lightnode add chat-web3\`      |
-| Cheapest server-side host that works  | Railway / Fly.io / Render      |
-| Already on Vercel and need it to fit  | Vercel Pro (60s) + streaming   |
-| You self-host already (Docker, VPS)   | Anywhere - no timeout to fight |
-
-## The detailed table
-
-| Host                | Free / Hobby timeout       | Paid timeout                | Verdict |
-|---------------------|----------------------------|-----------------------------|---------|
-| Vercel Hobby (free) | **10 seconds**             | -                           | **DOES NOT WORK** for mainnet inference. Every call times out. |
-| Vercel Pro ($20/mo) | -                          | 60s default, up to 800s with \`maxDuration\` config | Works if calls finish under 60s; 70-80s calls cut it close. Stream tokens to keep the connection warm. |
-| Cloudflare Workers  | 30s CPU                    | unbounded with Durable Objects | Free tier 30s is too tight; Workers + DO works but is complex. |
-| Railway             | none                       | none                        | **Great fit.** $5/mo for the smallest container, no timeout. Deploy a plain Node server or Next.js. |
-| Fly.io              | none                       | none                        | **Great fit.** Free tier covers small apps, scales to paid. |
-| Render              | none                       | none                        | **Great fit.** $7/mo for the smallest web service. |
-| Netlify Functions   | 26s sync / 15min background | 26s sync / 15min background | Use background functions for inference; sync functions time out. |
-| AWS Lambda          | 15 min                     | 15 min                      | Works, but WebSocket setup for streaming is involved. |
-| Self-host (Docker)  | no limit                   | no limit                    | **Works anywhere.** ECS, Cloud Run, your own VPS, fine. |
-
-## What I recommend
-
-1. **Building a Web3 app where users have wallets?** Switch to \`lightnode add
-   chat-web3\`. Each user signs and pays from their own wallet. You host the
-   static page (Vercel/Netlify/Cloudflare Pages free tier all work). No timeout
-   to fight because there is no server-side inference route.
-
-2. **Building a SaaS chatbot where users do NOT have wallets?** Deploy your
-   inference route on Railway or Fly. Both have no function timeout, scale
-   to traffic, and cost ~$5/mo for small apps. Cheaper than Vercel Pro.
-
-3. **Already committed to Vercel?** Upgrade to Pro and add streaming. The
-   chat template generated by \`lightnode add chat\` already uses streaming
-   tokens, so the connection stays warm while the model runs.
-
-4. **Have a Docker setup already?** Run the inference route in your existing
-   container. No timeout, no per-call cost beyond your existing infra.
+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
 
@@ -98,7 +113,74 @@ 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
-functions.
+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
@@ -252,6 +334,9 @@ export function addInference(opts = {}) {
     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));
@@ -1284,12 +1369,16 @@ export function addChat(opts = {}) {
     const force = !!opts.force;
     const written = [];
     if (template === "nextjs-api") {
-        // 'add chat' is now self-contained: it writes BOTH the chat page AND
-        // the streaming inference route. Previously the user had to remember
-        // to also run 'add inference' separately, which was easy to miss.
+        // '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));
@@ -1616,6 +1705,9 @@ export function addJudge(opts = {}) {
     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

@@ -534,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. npm run dev, open /chat`);
-                        console.log(`     (the chat page + /api/inference streaming route are both already wired up)`);
+                        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}}'`);
                     }
@@ -553,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`);
@@ -574,12 +581,16 @@ async function main() {
                         console.log(`  2. npx tsx lightnode-analytics.ts`);
                     }
                 }
-                // Hosting warning for server-side commands that ship LIGHTNODE-HOSTING.md.
+                // 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. Vercel Hobby (free) times`);
-                    console.log(`  out at 10s; Vercel Pro at 60s. See LIGHTNODE-HOSTING.md (in this folder)`);
-                    console.log(`  for hosts that work - Railway / Fly / Render handle long calls fine.`);
+                    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.16";
+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.16";
+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.16",
+  "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",