lightnode-sdk 0.3.1 → 0.3.2

package/README.md

@@ -80,6 +80,12 @@ npx lightnode registered 0x6781…6e0f      # true | false | null
 npx lightnode fee llama3-8b               # on-chain job fee
 npx lightnode analytics --csv             # per-model performance (CSV)
 npx lightnode reliability --csv           # per-worker reliability (CSV)
+
+# Scaffold inference into an existing project (auto-detects Next.js, Hono, or Node):
+npx lightnode add inference [--template auto|nextjs-api|hono|node] [--net testnet|mainnet] [--force]
+
+# Or scaffold a brand-new project:
+npm create lightnode-app my-app
 ```
 
 ## Submitting inference

package/dist/add.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `lightnode add inference` - patch an EXISTING project to do encrypted
+ * LightChain AI inference. Detects the framework from package.json (Next.js,
+ * Hono, or plain Node) and writes the appropriate route/script + a .env.example
+ * if one isn't already there. Idempotent: existing files are not overwritten
+ * unless --force is passed.
+ *
+ * No runtime dependencies; templates are inlined as string literals.
+ */
+type Template = "nextjs-api" | "hono" | "node";
+type Network = "testnet" | "mainnet";
+interface AddOpts {
+    template?: Template | "auto";
+    network?: Network;
+    force?: boolean;
+    cwd?: string;
+}
+interface WrittenFile {
+    path: string;
+    skipped?: boolean;
+    reason?: string;
+}
+/**
+ * Implementation called by `lightnode add inference [...]`.
+ * Returns the list of files written + the install command the user should run.
+ */
+export declare function addInference(opts?: AddOpts): {
+    written: WrittenFile[];
+    install: string;
+    template: Template;
+    network: Network;
+};
+export {};

package/dist/add.js

@@ -0,0 +1,372 @@
+/**
+ * `lightnode add inference` - patch an EXISTING project to do encrypted
+ * LightChain AI inference. Detects the framework from package.json (Next.js,
+ * Hono, or plain Node) and writes the appropriate route/script + a .env.example
+ * if one isn't already there. Idempotent: existing files are not overwritten
+ * unless --force is passed.
+ *
+ * No runtime dependencies; templates are inlined as string literals.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+function readPackageJson(cwd) {
+    const p = path.join(cwd, "package.json");
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(p, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function detectTemplate(cwd) {
+    const pkg = readPackageJson(cwd);
+    if (!pkg)
+        return "node";
+    const all = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+    if (all["next"])
+        return "nextjs-api";
+    if (all["hono"])
+        return "hono";
+    return "node";
+}
+const ENV_EXAMPLE = (net) => `# Funded private key. Testnet works free (faucet at https://lightfaucet.ai).
+PRIVATE_KEY=0x0000000000000000000000000000000000000000000000000000000000000000
+
+NETWORK=${net}
+MODEL=llama3-8b
+`;
+const NEXTJS_ROUTE = `// app/api/inference/route.ts
+// Generated by 'lightnode add inference'. See https://lightnode.app/build
+import { NextResponse } from "next/server";
+import WS from "ws";
+import { createPublicClient, createWalletClient, http, parseAbi, parseAbiItem, parseEther, type Log } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import {
+  LightNode, prepareSession, submitPrompt, decryptResponse,
+  estimateJobFee, consumerGatewayUrl, JOB_REGISTRY_CONSUMER_ABI,
+  GatewayClient, type NetworkId,
+} from "lightnode-sdk";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+export const maxDuration = 120;
+
+const NETWORK = (process.env.NETWORK ?? "testnet") as NetworkId;
+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 };
+  const prompt = body.prompt?.trim();
+  if (!prompt) return NextResponse.json({ error: "prompt is required" }, { status: 400 });
+
+  const ln = new LightNode(NETWORK);
+  const cfg = ln.network;
+  const acct = privateKeyToAccount(process.env.PRIVATE_KEY as \`0x\${string}\`);
+  const chain = { id: cfg.chainId, name: cfg.label, nativeCurrency: { name: "LCAI", symbol: "LCAI", decimals: 18 }, rpcUrls: { default: { http: [cfg.rpc] } } };
+  const pub = createPublicClient({ transport: http(cfg.rpc), chain });
+  const wal = createWalletClient({ account: acct, transport: http(cfg.rpc), chain });
+  const abi = parseAbi(JOB_REGISTRY_CONSUMER_ABI);
+
+  const ch = await (await fetch(\`\${consumerGatewayUrl(NETWORK)}/api/auth/challenge?address=\${acct.address}\`)).json() as { message?: string };
+  if (!ch.message) return NextResponse.json({ error: "auth challenge failed" }, { status: 502 });
+  const sig = await wal.signMessage({ message: ch.message });
+  const verify = await (await fetch(\`\${consumerGatewayUrl(NETWORK)}/api/auth/verify\`, {
+    method: "POST", headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ message: ch.message, signature: sig }),
+  })).json() as { token?: string };
+  if (!verify.token) return NextResponse.json({ error: "auth verify failed" }, { status: 502 });
+
+  const gateway = new GatewayClient({ network: NETWORK, bearer: verify.token });
+  const { sessionKey, createSessionArgs } = await prepareSession(gateway, MODEL);
+  const fee = await estimateJobFee(cfg, MODEL);
+  const createTx = await wal.writeContract({
+    address: cfg.jobRegistry as \`0x\${string}\`, abi, functionName: "createSession",
+    args: [createSessionArgs.paramsHash, createSessionArgs.worker, createSessionArgs.encWorkerKey, createSessionArgs.ephemeralPubKey, createSessionArgs.initState, createSessionArgs.expiry],
+    gas: 1_000_000n,
+  });
+  const createReceipt = await pub.waitForTransactionReceipt({ hash: createTx });
+  const sessionCreated = parseAbiItem("event SessionCreated(uint256 indexed sessionId, address indexed user, bytes32 indexed paramsHash, address worker, bytes encWorkerKey, bytes ephemeralPubKey)");
+  const sessionLog = (await pub.getLogs({ address: cfg.jobRegistry as \`0x\${string}\`, event: sessionCreated, blockHash: createReceipt.blockHash })).find((l) => l.transactionHash === createTx);
+  const sessionId = sessionLog?.args.sessionId;
+  if (!sessionId) return NextResponse.json({ error: "SessionCreated missing" }, { status: 500 });
+
+  let relayToken: string | undefined;
+  for (let i = 0; i < 30 && !relayToken; i++) {
+    const r = await gateway.getSessionToken(Number(sessionId));
+    if ("token" in r && r.token) relayToken = r.token; else await new Promise((res) => setTimeout(res, 1000));
+  }
+  if (!relayToken) return NextResponse.json({ error: "relay token never became ready" }, { status: 504 });
+  const ws = new WS(\`wss://relay.\${NETWORK}.lightchain.ai/ws?token=\${encodeURIComponent(relayToken)}\`);
+  const chunks: string[] = [];
+  await new Promise<void>((res, rej) => { ws.once("open", () => res()); ws.once("error", rej); });
+  ws.on("message", async (data: Buffer) => {
+    let f: { type?: string; payload?: string };
+    try { f = JSON.parse(data.toString("utf8")); } catch { return; }
+    if (!f.payload) return;
+    if (f.type === "chunk") { try { chunks.push(await decryptResponse(sessionKey, f.payload)); } catch {} }
+    else if (f.type === "complete" && chunks.length === 0) { try { chunks.push(await decryptResponse(sessionKey, f.payload)); } catch {} }
+  });
+
+  const promptHash = await submitPrompt(gateway, sessionKey, prompt);
+  const submitTx = await wal.writeContract({
+    address: cfg.jobRegistry as \`0x\${string}\`, abi, functionName: "submitJob",
+    args: [sessionId, promptHash], value: parseEther(String(fee)), gas: 500_000n,
+  });
+  const submitReceipt = await pub.waitForTransactionReceipt({ hash: submitTx });
+  const jobSubmitted = parseAbiItem("event JobSubmitted(uint256 indexed jobId, uint256 indexed sessionId, address worker)");
+  const jobLog = (await pub.getLogs({ address: cfg.jobRegistry as \`0x\${string}\`, event: jobSubmitted, blockHash: submitReceipt.blockHash })).find((l) => l.transactionHash === submitTx);
+  const jobId = jobLog?.args.jobId;
+  if (!jobId) return NextResponse.json({ error: "JobSubmitted missing" }, { status: 500 });
+
+  const jobCompleted = parseAbiItem("event JobCompleted(uint256 indexed jobId, address indexed worker, bytes32 responseHash, bytes32 ciphertextHash)");
+  const deadline = Date.now() + 90_000;
+  let completed: Log | null = null;
+  while (!completed && Date.now() < deadline) {
+    await new Promise((res) => setTimeout(res, 3000));
+    const logs = await pub.getLogs({ address: cfg.jobRegistry as \`0x\${string}\`, event: jobCompleted, args: { jobId }, fromBlock: submitReceipt.blockNumber });
+    if (logs.length) completed = logs[0] as Log;
+  }
+  await new Promise((res) => setTimeout(res, 4000));
+  ws.close();
+  if (!completed) return NextResponse.json({ error: "worker stalled", txs: { createSession: createTx, submitJob: submitTx } }, { status: 504 });
+
+  return NextResponse.json({
+    answer: chunks.join(""),
+    txs: { createSession: createTx, submitJob: submitTx, jobCompleted: completed.transactionHash },
+    sessionId: sessionId.toString(),
+    jobId: jobId.toString(),
+    worker: createSessionArgs.worker,
+  });
+}
+`;
+const HONO_HANDLER = `// lightchain-inference.ts
+// Generated by 'lightnode add inference'. See https://lightnode.app/build
+// Plug the handler below into your Hono router:
+//
+//   import { Hono } from "hono";
+//   import { inferenceHandler } from "./lightchain-inference.js";
+//   const app = new Hono();
+//   app.post("/inference", inferenceHandler);
+//
+import WS from "ws";
+import { createPublicClient, createWalletClient, http, parseAbi, parseAbiItem, parseEther, type Log } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import type { Context } from "hono";
+import {
+  LightNode, prepareSession, submitPrompt, decryptResponse,
+  estimateJobFee, consumerGatewayUrl, JOB_REGISTRY_CONSUMER_ABI,
+  GatewayClient, type NetworkId,
+} from "lightnode-sdk";
+
+const NETWORK = (process.env.NETWORK ?? "testnet") as NetworkId;
+const MODEL = process.env.MODEL ?? "llama3-8b";
+
+export async function inferenceHandler(c: Context) {
+  if (!process.env.PRIVATE_KEY?.startsWith("0x")) return c.json({ error: "PRIVATE_KEY not set" }, 500);
+  const body = await c.req.json().catch(() => ({} as { prompt?: string }));
+  const prompt = body.prompt?.trim();
+  if (!prompt) return c.json({ error: "prompt is required" }, 400);
+
+  const ln = new LightNode(NETWORK);
+  const cfg = ln.network;
+  const acct = privateKeyToAccount(process.env.PRIVATE_KEY as \`0x\${string}\`);
+  const chain = { id: cfg.chainId, name: cfg.label, nativeCurrency: { name: "LCAI", symbol: "LCAI", decimals: 18 }, rpcUrls: { default: { http: [cfg.rpc] } } };
+  const pub = createPublicClient({ transport: http(cfg.rpc), chain });
+  const wal = createWalletClient({ account: acct, transport: http(cfg.rpc), chain });
+  const abi = parseAbi(JOB_REGISTRY_CONSUMER_ABI);
+
+  const ch = await (await fetch(\`\${consumerGatewayUrl(NETWORK)}/api/auth/challenge?address=\${acct.address}\`)).json() as { message?: string };
+  if (!ch.message) return c.json({ error: "auth challenge failed" }, 502);
+  const sig = await wal.signMessage({ message: ch.message });
+  const verify = await (await fetch(\`\${consumerGatewayUrl(NETWORK)}/api/auth/verify\`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ message: ch.message, signature: sig }) })).json() as { token?: string };
+  if (!verify.token) return c.json({ error: "auth verify failed" }, 502);
+  const gateway = new GatewayClient({ network: NETWORK, bearer: verify.token });
+
+  const { sessionKey, createSessionArgs } = await prepareSession(gateway, MODEL);
+  const fee = await estimateJobFee(cfg, MODEL);
+  const createTx = await wal.writeContract({
+    address: cfg.jobRegistry as \`0x\${string}\`, abi, functionName: "createSession",
+    args: [createSessionArgs.paramsHash, createSessionArgs.worker, createSessionArgs.encWorkerKey, createSessionArgs.ephemeralPubKey, createSessionArgs.initState, createSessionArgs.expiry],
+    gas: 1_000_000n,
+  });
+  const createReceipt = await pub.waitForTransactionReceipt({ hash: createTx });
+  const sessionCreated = parseAbiItem("event SessionCreated(uint256 indexed sessionId, address indexed user, bytes32 indexed paramsHash, address worker, bytes encWorkerKey, bytes ephemeralPubKey)");
+  const sessionLog = (await pub.getLogs({ address: cfg.jobRegistry as \`0x\${string}\`, event: sessionCreated, blockHash: createReceipt.blockHash })).find((l) => l.transactionHash === createTx);
+  const sessionId = sessionLog?.args.sessionId;
+  if (!sessionId) return c.json({ error: "SessionCreated missing" }, 500);
+
+  let relayToken: string | undefined;
+  for (let i = 0; i < 30 && !relayToken; i++) { const r = await gateway.getSessionToken(Number(sessionId)); if ("token" in r && r.token) relayToken = r.token; else await new Promise((res) => setTimeout(res, 1000)); }
+  if (!relayToken) return c.json({ error: "relay token never became ready" }, 504);
+  const ws = new WS(\`wss://relay.\${NETWORK}.lightchain.ai/ws?token=\${encodeURIComponent(relayToken)}\`);
+  const chunks: string[] = [];
+  await new Promise<void>((res, rej) => { ws.once("open", () => res()); ws.once("error", rej); });
+  ws.on("message", async (data: Buffer) => {
+    let f: { type?: string; payload?: string };
+    try { f = JSON.parse(data.toString("utf8")); } catch { return; }
+    if (!f.payload) return;
+    if (f.type === "chunk") { try { chunks.push(await decryptResponse(sessionKey, f.payload)); } catch {} }
+    else if (f.type === "complete" && chunks.length === 0) { try { chunks.push(await decryptResponse(sessionKey, f.payload)); } catch {} }
+  });
+
+  const promptHash = await submitPrompt(gateway, sessionKey, prompt);
+  const submitTx = await wal.writeContract({
+    address: cfg.jobRegistry as \`0x\${string}\`, abi, functionName: "submitJob",
+    args: [sessionId, promptHash], value: parseEther(String(fee)), gas: 500_000n,
+  });
+  const submitReceipt = await pub.waitForTransactionReceipt({ hash: submitTx });
+  const jobSubmitted = parseAbiItem("event JobSubmitted(uint256 indexed jobId, uint256 indexed sessionId, address worker)");
+  const jobLog = (await pub.getLogs({ address: cfg.jobRegistry as \`0x\${string}\`, event: jobSubmitted, blockHash: submitReceipt.blockHash })).find((l) => l.transactionHash === submitTx);
+  const jobId = jobLog?.args.jobId;
+  if (!jobId) return c.json({ error: "JobSubmitted missing" }, 500);
+
+  const jobCompleted = parseAbiItem("event JobCompleted(uint256 indexed jobId, address indexed worker, bytes32 responseHash, bytes32 ciphertextHash)");
+  const deadline = Date.now() + 90_000;
+  let completed: Log | null = null;
+  while (!completed && Date.now() < deadline) {
+    await new Promise((res) => setTimeout(res, 3000));
+    const logs = await pub.getLogs({ address: cfg.jobRegistry as \`0x\${string}\`, event: jobCompleted, args: { jobId }, fromBlock: submitReceipt.blockNumber });
+    if (logs.length) completed = logs[0] as Log;
+  }
+  await new Promise((res) => setTimeout(res, 4000));
+  ws.close();
+  if (!completed) return c.json({ error: "worker stalled", txs: { createSession: createTx, submitJob: submitTx } }, 504);
+  return c.json({ answer: chunks.join(""), txs: { createSession: createTx, submitJob: submitTx, jobCompleted: completed.transactionHash }, sessionId: sessionId.toString(), jobId: jobId.toString(), worker: createSessionArgs.worker });
+}
+`;
+const NODE_SCRIPT = `// lightchain-inference.ts
+// Generated by 'lightnode add inference'. Run with: tsx lightchain-inference.ts "your prompt"
+import WS from "ws";
+import { createPublicClient, createWalletClient, http, parseAbi, parseAbiItem, parseEther, type Log } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import {
+  LightNode, prepareSession, submitPrompt, decryptResponse,
+  estimateJobFee, consumerGatewayUrl, JOB_REGISTRY_CONSUMER_ABI,
+  GatewayClient, type NetworkId,
+} from "lightnode-sdk";
+
+const NETWORK = (process.env.NETWORK ?? "testnet") as NetworkId;
+const MODEL = process.env.MODEL ?? "llama3-8b";
+const PROMPT = process.argv.slice(2).join(" ").trim() || "Reply with a one-sentence fun fact.";
+const PRIVATE_KEY = process.env.PRIVATE_KEY as \`0x\${string}\` | undefined;
+if (!PRIVATE_KEY?.startsWith("0x") || PRIVATE_KEY.length !== 66) { console.error("set PRIVATE_KEY in .env"); process.exit(1); }
+
+const ln = new LightNode(NETWORK);
+const cfg = ln.network;
+const acct = privateKeyToAccount(PRIVATE_KEY);
+const chain = { id: cfg.chainId, name: cfg.label, nativeCurrency: { name: "LCAI", symbol: "LCAI", decimals: 18 }, rpcUrls: { default: { http: [cfg.rpc] } } };
+const pub = createPublicClient({ transport: http(cfg.rpc), chain });
+const wal = createWalletClient({ account: acct, transport: http(cfg.rpc), chain });
+const abi = parseAbi(JOB_REGISTRY_CONSUMER_ABI);
+
+const ch = await (await fetch(\`\${consumerGatewayUrl(NETWORK)}/api/auth/challenge?address=\${acct.address}\`)).json() as { message?: string };
+if (!ch.message) throw new Error("auth challenge failed");
+const sig = await wal.signMessage({ message: ch.message });
+const verify = await (await fetch(\`\${consumerGatewayUrl(NETWORK)}/api/auth/verify\`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ message: ch.message, signature: sig }) })).json() as { token?: string };
+if (!verify.token) throw new Error("auth verify failed");
+const gateway = new GatewayClient({ network: NETWORK, bearer: verify.token });
+
+const { sessionKey, createSessionArgs } = await prepareSession(gateway, MODEL);
+const fee = await estimateJobFee(cfg, MODEL);
+const createTx = await wal.writeContract({
+  address: cfg.jobRegistry as \`0x\${string}\`, abi, functionName: "createSession",
+  args: [createSessionArgs.paramsHash, createSessionArgs.worker, createSessionArgs.encWorkerKey, createSessionArgs.ephemeralPubKey, createSessionArgs.initState, createSessionArgs.expiry],
+  gas: 1_000_000n,
+});
+const createReceipt = await pub.waitForTransactionReceipt({ hash: createTx });
+const sessionCreated = parseAbiItem("event SessionCreated(uint256 indexed sessionId, address indexed user, bytes32 indexed paramsHash, address worker, bytes encWorkerKey, bytes ephemeralPubKey)");
+const sessionLog = (await pub.getLogs({ address: cfg.jobRegistry as \`0x\${string}\`, event: sessionCreated, blockHash: createReceipt.blockHash })).find((l) => l.transactionHash === createTx);
+if (!sessionLog?.args.sessionId) throw new Error("SessionCreated missing");
+const sessionId = sessionLog.args.sessionId;
+
+let relayToken: string | undefined;
+for (let i = 0; i < 30 && !relayToken; i++) {
+  const r = await gateway.getSessionToken(Number(sessionId));
+  if ("token" in r && r.token) relayToken = r.token; else await new Promise((res) => setTimeout(res, 1000));
+}
+if (!relayToken) throw new Error("relay token never became ready");
+const ws = new WS(\`wss://relay.\${NETWORK}.lightchain.ai/ws?token=\${encodeURIComponent(relayToken)}\`);
+const chunks: string[] = [];
+await new Promise<void>((res, rej) => { ws.once("open", () => res()); ws.once("error", rej); });
+ws.on("message", async (data: Buffer) => {
+  let f: { type?: string; payload?: string };
+  try { f = JSON.parse(data.toString("utf8")); } catch { return; }
+  if (!f.payload) return;
+  if (f.type === "chunk") { try { chunks.push(await decryptResponse(sessionKey, f.payload)); } catch {} }
+  else if (f.type === "complete" && chunks.length === 0) { try { chunks.push(await decryptResponse(sessionKey, f.payload)); } catch {} }
+});
+
+const promptHash = await submitPrompt(gateway, sessionKey, PROMPT);
+const submitTx = await wal.writeContract({
+  address: cfg.jobRegistry as \`0x\${string}\`, abi, functionName: "submitJob",
+  args: [sessionId, promptHash], value: parseEther(String(fee)), gas: 500_000n,
+});
+const submitReceipt = await pub.waitForTransactionReceipt({ hash: submitTx });
+const jobSubmitted = parseAbiItem("event JobSubmitted(uint256 indexed jobId, uint256 indexed sessionId, address worker)");
+const jobLog = (await pub.getLogs({ address: cfg.jobRegistry as \`0x\${string}\`, event: jobSubmitted, blockHash: submitReceipt.blockHash })).find((l) => l.transactionHash === submitTx);
+const jobId = jobLog?.args.jobId;
+if (!jobId) throw new Error("JobSubmitted missing");
+
+const jobCompleted = parseAbiItem("event JobCompleted(uint256 indexed jobId, address indexed worker, bytes32 responseHash, bytes32 ciphertextHash)");
+const deadline = Date.now() + 90_000;
+let completed: Log | null = null;
+while (!completed && Date.now() < deadline) {
+  await new Promise((res) => setTimeout(res, 3000));
+  const logs = await pub.getLogs({ address: cfg.jobRegistry as \`0x\${string}\`, event: jobCompleted, args: { jobId }, fromBlock: submitReceipt.blockNumber });
+  if (logs.length) completed = logs[0] as Log;
+}
+if (!completed) { console.error("worker stalled - re-run for a different worker"); process.exit(1); }
+await new Promise((res) => setTimeout(res, 4000));
+ws.close();
+console.log("\\n=== ANSWER ===\\n" + chunks.join("") + "\\n");
+console.log("createSession:", createTx, "\\nsubmitJob:    ", submitTx, "\\njobCompleted: ", completed.transactionHash);
+process.exit(0);
+`;
+function writeFile(abs, contents, force) {
+    const rel = path.relative(process.cwd(), abs) || abs;
+    if (fs.existsSync(abs) && !force) {
+        return { path: rel, skipped: true, reason: "already exists (use --force to overwrite)" };
+    }
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, contents);
+    return { path: rel };
+}
+function depsNeeded(template) {
+    if (template === "nextjs-api")
+        return ["lightnode-sdk", "viem", "ws"];
+    if (template === "hono")
+        return ["lightnode-sdk", "viem", "ws"];
+    return ["lightnode-sdk", "viem", "ws"];
+}
+/**
+ * Implementation called by `lightnode add inference [...]`.
+ * Returns the list of files written + the install command the user should run.
+ */
+export function addInference(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const network = opts.network ?? "testnet";
+    const template = opts.template && opts.template !== "auto" ? opts.template : detectTemplate(cwd);
+    const force = !!opts.force;
+    const written = [];
+    if (template === "nextjs-api") {
+        written.push(writeFile(path.join(cwd, "app/api/inference/route.ts"), NEXTJS_ROUTE, force));
+    }
+    else if (template === "hono") {
+        written.push(writeFile(path.join(cwd, "lightchain-inference.ts"), HONO_HANDLER, force));
+    }
+    else {
+        written.push(writeFile(path.join(cwd, "lightchain-inference.ts"), NODE_SCRIPT, force));
+    }
+    written.push(writeFile(path.join(cwd, ".env.example"), ENV_EXAMPLE(network), force));
+    return {
+        written,
+        install: `npm install ${depsNeeded(template).join(" ")}`,
+        template,
+        network,
+    };
+}

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { LightNode, modelStatsCsv, workerStatsCsv, workerJobsCsv } from "./index.js";
+import { addInference } from "./add.js";
 function flag(name) {
     const i = process.argv.indexOf(name);
     return i >= 0 ? process.argv[i + 1] : undefined;
@@ -16,14 +17,19 @@ const lcai = (wei) => (wei ? Number(BigInt(wei)) / 1e18 : 0);
 const rate = (r) => (r == null ? "-" : `${Math.round(r * 100)}%`);
 const HELP = `lightnode <command> [--net mainnet|testnet]
 
-  network              network summary (workers, jobs, models, earnings)
-  models               registered models + per-job fee
-  worker <addr>        a worker: on-chain registration + recent jobs
-  jobs <addr> [--csv]  one worker's job history (table or CSV)
-  registered <addr>    true | false | null (read from chain events)
-  fee [model]          on-chain inference fee (default llama3-8b)
-  analytics [--csv]    per-model performance (completion, p50/p95, incomplete)
-  reliability [--csv]  per-worker reliability, busiest first`;
+  network                  network summary (workers, jobs, models, earnings)
+  models                   registered models + per-job fee
+  worker <addr>            a worker: on-chain registration + recent jobs
+  jobs <addr> [--csv]      one worker's job history (table or CSV)
+  registered <addr>        true | false | null (read from chain events)
+  fee [model]              on-chain inference fee (default llama3-8b)
+  analytics [--csv]        per-model performance (completion, p50/p95, incomplete)
+  reliability [--csv]      per-worker reliability, busiest first
+
+  add inference            patch the current project for end-to-end inference
+                           [--template auto|nextjs-api|hono|node] [--force]
+
+To scaffold a new project instead, run: npm create lightnode-app my-app`;
 async function main() {
     const ln = new LightNode(net);
     switch (cmd) {
@@ -89,6 +95,39 @@ async function main() {
             }
             break;
         }
+        case "add": {
+            const sub = positionals[1];
+            if (sub !== "inference")
+                die("usage: lightnode add inference [--template auto|nextjs-api|hono|node] [--net testnet|mainnet] [--force]");
+            const template = flag("--template") ?? "auto";
+            const force = process.argv.includes("--force");
+            const result = addInference({ template, network: net === "mainnet" ? "mainnet" : "testnet", force });
+            console.log(`▶ add inference (${result.template} template, default network ${result.network})`);
+            for (const f of result.written) {
+                if (f.skipped)
+                    console.log(`  ⤴ ${f.path} (skipped - ${f.reason})`);
+                else
+                    console.log(`  ✓ ${f.path}`);
+            }
+            const anyWritten = result.written.some((f) => !f.skipped);
+            if (!anyWritten) {
+                console.log("\nNothing to do - all target files already exist. Pass --force to overwrite.");
+            }
+            else {
+                console.log(`\nNext steps:`);
+                console.log(`  1. ${result.install}`);
+                console.log(`  2. cp .env.example .env  (and put a funded ${result.network} PRIVATE_KEY in it)`);
+                if (result.template === "nextjs-api")
+                    console.log(`  3. npm run dev  (then POST /api/inference)`);
+                else if (result.template === "hono")
+                    console.log(`  3. wire inferenceHandler into your Hono app, then start it`);
+                else
+                    console.log(`  3. tsx lightchain-inference.ts "your prompt"`);
+                console.log(`\nFree testnet LCAI: https://lightfaucet.ai`);
+                console.log(`Builder docs:     https://lightnode.app/build`);
+            }
+            break;
+        }
         default:
             console.log(HELP);
     }

package/package.json

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