lightnode-sdk 0.8.9 → 0.9.0

package/dist/add.js

@@ -963,7 +963,7 @@ const NEXTJS_CHAT_WEB3_PAGE = `// app/chat-web3/page.tsx
 
 import { useEffect, useRef, useState } from "react";
 import { useAccount, useWalletClient, usePublicClient } from "wagmi";
-import { siweSignIn, GatewayClient, runInference, estimateJobFee, NETWORKS } from "lightnode-sdk";
+import { siweSignIn, GatewayClient, LightChatSession, estimateJobFee, NETWORKS } from "lightnode-sdk";
 import { Streamdown } from "streamdown";
 import { ConnectButton } from "@/components/connect-button";
 import { LcaiMark } from "@/components/lcai-mark";
@@ -997,6 +997,9 @@ export default function ChatWeb3() {
   const [err, setErr] = useState<string | null>(null);
   const [feeLcai, setFeeLcai] = useState<number | null>(null);
   const endRef = useRef<HTMLDivElement>(null);
+  // Reused across turns so follow-ups skip SIWE + createSession.
+  const sessionRef = useRef<LightChatSession | null>(null);
+  const sessionKeyRef = useRef<string>("");
 
   // Read the on-chain fee for the connected network so we can show the
   // visitor the real cost per turn before they click Send.
@@ -1037,6 +1040,31 @@ export default function ChatWeb3() {
     });
   }
 
+  /**
+   * Open a session on the first turn (or after expiry / a model or wallet
+   * change), then reuse it so every follow-up turn skips SIWE + createSession.
+   */
+  async function ensureSession(): Promise<LightChatSession> {
+    if (!walletClient || !publicClient || !address || !network) throw new Error("connect a wallet first");
+    const key = \`\${address}:\${network}:\${model}\`;
+    const existing = sessionRef.current;
+    if (existing && !existing.expired && sessionKeyRef.current === key) return existing;
+    setBusyStage("Sign in with your wallet (SIWE)...");
+    const siwe = await siweSignIn(walletClient as unknown as Parameters<typeof siweSignIn>[0], network);
+    setBusyStage("Approve createSession in your wallet (one-time per session)...");
+    const gateway = new GatewayClient({ network, bearer: siwe.bearer });
+    const chat = await LightChatSession.open({
+      gateway,
+      wallet: walletClient as unknown as Parameters<typeof LightChatSession.open>[0]["wallet"],
+      publicClient: publicClient as unknown as Parameters<typeof LightChatSession.open>[0]["publicClient"],
+      network: NETWORKS[network],
+      model,
+    });
+    sessionRef.current = chat;
+    sessionKeyRef.current = key;
+    return chat;
+  }
+
   async function send() {
     if (!walletClient || !publicClient || !address || !network) {
       setErr("Connect a wallet on LightChain mainnet (9200) or testnet (8200) first.");
@@ -1053,26 +1081,21 @@ export default function ChatWeb3() {
     try {
       const system = "You are a concise assistant. Reply in one or two short sentences.";
       const prompt = composePrompt(history, next, system);
-
-      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 result = await runInference({
-        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,
-        jobCompletedTimeoutMs: 120_000,
-        maxRetries: 1,
-        // Stream each decrypted chunk into the assistant bubble as it arrives.
-        onChunk: (_chunk, totalSoFar) => {
-          setBusyStage("");
-          patchLastAssistant({ text: totalSoFar });
-        },
+      const onChunk = (_chunk: string, totalSoFar: string) => {
+        setBusyStage("");
+        patchLastAssistant({ text: totalSoFar });
+      };
+
+      const chat = await ensureSession();
+      setBusyStage("Approve the per-turn transaction in your wallet...");
+      const result = await chat.send(prompt, { onChunk }).catch(async () => {
+        // Session expired or the worker stopped serving - reopen once and retry.
+        sessionRef.current = null;
+        patchLastAssistant({ text: "" });
+        setBusyStage("Re-opening session...");
+        const fresh = await ensureSession();
+        setBusyStage("Approve the per-turn transaction in your wallet...");
+        return fresh.send(prompt, { onChunk });
       });
 
       patchLastAssistant({

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS } from "./networks.js";
 import { fetchWorkerModels, fromWei, resolveJobTransactions } from "./subgraph.js";
 import { aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv } from "./analytics.js";
-import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey, runInferenceStream } from "./inference.js";
+import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey, runInferenceStream, openSession, runJobOnSession, LightChatSession } from "./inference.js";
 import { Conversation, chat } from "./chat.js";
 import { runInferenceBatch } from "./batch.js";
 import { Agent, parseAgentOutput } from "./agent.js";
@@ -135,7 +135,7 @@ export declare class LightNode {
  * may pin an older minor than the local install command suggests).
  */
 export declare const SDK_VERSION = "0.7.20";
-export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, resolveJobTransactions, siweSignIn, siweChallenge, siweVerify, fetchWorkerModels, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, runInference, runInferenceWithKey, runInferenceStream, Conversation, chat, runInferenceBatch, Agent, parseAgentOutput, workerPreflight, workerWatch, Bridge, BRIDGE_ROUTE, HYPERLANE_ROUTER_ABI, ERC20_ABI, addressToBytes32, quoteBridgeFee, bridgeableBalance, bridgeAllowance, approveBridge, bridgeTransfer, DAO, DAO_ADDRESSES, ProposalState, PROPOSAL_STATE_LABEL, VoteSupport, GOVERNOR_ABI, VOTES_ABI, OnchainModelRegistry, AIVM_MODEL_REGISTRY_ABI, BENCHMARK_REGISTRY_ABI, ModelStatus, MODEL_STATUS_LABEL, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, WorkerOperator, WORKER_REGISTRY_ABI, JOB_REGISTRY_OPERATOR_ABI, AI_CONFIG_ABI, JOB_STATE, decodeWorkerError, WorkerOpError, isWorkerOpError, };
+export { 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, openSession, runJobOnSession, LightChatSession, 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";
 export type { ChatRole, ChatMessage, ConversationOptions, ConversationSendResult } from "./chat.js";

package/dist/index.js

@@ -2,7 +2,7 @@ import { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS } from "./networks.js";
 import { fetchWorker, fetchWorkerJobs, fetchWorkerModels, fetchRecentJobs, fetchJob, fetchModels, fetchWorkers, summarize, fromWei, resolveJobTransactions, } from "./subgraph.js";
 import { isRegistered, fetchOnchainEligibleModels } from "./onchain.js";
 import { aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, } from "./analytics.js";
-import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey, runInferenceStream, } from "./inference.js";
+import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey, runInferenceStream, openSession, runJobOnSession, LightChatSession, } from "./inference.js";
 import { Conversation, chat } from "./chat.js";
 import { runInferenceBatch } from "./batch.js";
 import { Agent, parseAgentOutput } from "./agent.js";
@@ -233,6 +233,8 @@ runInference,
 runInferenceWithKey, 
 // v0.4.9 AsyncIterable<string> wrapper around runInferenceWithKey.
 runInferenceStream, 
+// v0.9.0 session reuse: open once, run many jobs (follow-ups skip createSession).
+openSession, runJobOnSession, LightChatSession, 
 // v0.5.0 multi-turn conversation helper (history client-side; one inference per turn).
 Conversation, chat, 
 // v0.6.0 batch runner: many prompts, capped parallelism, stable result order.

package/dist/inference.d.ts

@@ -204,6 +204,72 @@ export interface RunInferenceResult {
         submitTx: `0x${string}`;
     }>;
 }
+/** A live, on-chain session. Open once, then run many jobs through it - each
+ *  follow-up turn skips SIWE + createSession, leaving just the submitJob tx. */
+export interface OpenSession {
+    readonly gateway: GatewayClient;
+    readonly wallet: MinimalWalletClient;
+    readonly publicClient: MinimalPublicClient;
+    readonly network: NetworkConfig;
+    readonly model: string;
+    readonly fee: number;
+    readonly sessionId: bigint;
+    readonly sessionKey: Uint8Array;
+    readonly worker: `0x${string}`;
+    readonly createTx: `0x${string}`;
+    /** Unix seconds when the on-chain session window closes. */
+    readonly expirySec: number;
+}
+export interface OpenSessionArgs {
+    gateway: GatewayClient;
+    wallet: MinimalWalletClient;
+    publicClient: MinimalPublicClient;
+    network: NetworkConfig;
+    model?: string;
+}
+/**
+ * prepareSession + the on-chain createSession tx. Do this once, then run many
+ * jobs through the handle with `runJobOnSession`. Re-open when `expirySec`
+ * passes or the chosen worker stops serving.
+ */
+export declare function openSession(args: OpenSessionArgs): Promise<OpenSession>;
+export interface RunJobOpts {
+    onChunk?: (chunk: string, totalSoFar: string) => void;
+    jobCompletedTimeoutMs?: number;
+    WebSocket?: WebSocketCtor;
+    relayUrl?: string;
+    signal?: AbortSignal;
+}
+/**
+ * Run ONE job against an already-open session: submitPrompt + submitJob + relay
+ * stream + wait for JobCompleted. No SIWE, no createSession.
+ */
+export declare function runJobOnSession(session: OpenSession, prompt: string, opts?: RunJobOpts, attempt?: number): Promise<RunInferenceResult>;
+/**
+ * A reusable, wallet-signed inference session. Open it once (SIWE happens before
+ * this; createSession happens here), then call `.send()` per turn - each
+ * follow-up turn skips createSession, leaving just the submitJob tx. Re-open
+ * (call `LightChatSession.open(...)` again) when `expired` is true or a
+ * `.send()` throws because the worker stopped serving.
+ *
+ * @example
+ * ```ts
+ * const session = await LightChatSession.open({ gateway, wallet, publicClient, network, model: "llama3-8b" });
+ * const a = await session.send("Who wrote The Great Gatsby?", { onChunk });
+ * const b = await session.send("In what year?", { onChunk }); // no createSession
+ * ```
+ */
+export declare class LightChatSession {
+    private readonly session;
+    private constructor();
+    static open(args: OpenSessionArgs): Promise<LightChatSession>;
+    get sessionId(): bigint;
+    get worker(): `0x${string}`;
+    get model(): string;
+    /** true once the on-chain session window has closed; re-open before sending. */
+    get expired(): boolean;
+    send(prompt: string, opts?: RunJobOpts): Promise<RunInferenceResult>;
+}
 /**
  * One call, full encrypted inference. Same code path the live playground at
  * lightnode.app/playground drives, condensed into a single function.

package/dist/inference.js

@@ -228,14 +228,15 @@ function pickWebSocket(provided) {
 function topicAsUint(hex) {
     return BigInt(hex);
 }
-async function runOneAttempt(args, attempt) {
-    const { prompt, gateway, wallet, publicClient, network, model = "llama3-8b", onChunk, jobCompletedTimeoutMs = 120000, } = args;
-    const WS = pickWebSocket(args.WebSocket);
-    const relayUrl = args.relayUrl ?? `wss://relay.${network.id}.lightchain.ai/ws`;
-    // 1. prepareSession
+/**
+ * prepareSession + the on-chain createSession tx. Do this once, then run many
+ * jobs through the handle with `runJobOnSession`. Re-open when `expirySec`
+ * passes or the chosen worker stops serving.
+ */
+export async function openSession(args) {
+    const { gateway, wallet, publicClient, network, model = "llama3-8b" } = args;
     const prepared = await prepareSession(gateway, model);
     const fee = await estimateJobFee(network, model);
-    // 2. createSession on-chain
     const createTx = await wallet.writeContract({
         address: network.jobRegistry,
         abi: JOB_REGISTRY_ABI_PARSED,
@@ -256,7 +257,31 @@ async function runOneAttempt(args, attempt) {
     const createLog = (await publicClient.getLogs({ address: network.jobRegistry, blockHash: createReceipt.blockHash })).find((l) => l.transactionHash === createTx && l.topics[0] === SESSION_CREATED_TOPIC);
     if (!createLog)
         throw new Error("SessionCreated log missing in createSession receipt");
-    const sessionId = topicAsUint(createLog.topics[1]);
+    return {
+        gateway,
+        wallet,
+        publicClient,
+        network,
+        model,
+        fee,
+        sessionId: topicAsUint(createLog.topics[1]),
+        sessionKey: prepared.sessionKey,
+        worker: prepared.createSessionArgs.worker,
+        createTx,
+        expirySec: Number(prepared.createSessionArgs.expiry),
+    };
+}
+/**
+ * Run ONE job against an already-open session: submitPrompt + submitJob + relay
+ * stream + wait for JobCompleted. No SIWE, no createSession.
+ */
+export async function runJobOnSession(session, prompt, opts = {}, attempt = 1) {
+    const { gateway, wallet, publicClient, network, sessionId, sessionKey, worker, fee, createTx } = session;
+    const { onChunk, jobCompletedTimeoutMs = 120000 } = opts;
+    const WS = pickWebSocket(opts.WebSocket);
+    const relayUrl = opts.relayUrl ?? `wss://relay.${network.id}.lightchain.ai/ws`;
+    // Shim so the job body below can keep referencing prepared.* unchanged.
+    const prepared = { sessionKey, createSessionArgs: { worker } };
     // 3. relay token + WebSocket
     let relayToken;
     for (let i = 0; i < 30 && !relayToken; i++) {
@@ -293,6 +318,8 @@ async function runOneAttempt(args, attempt) {
         setTimeout(() => reject(new Error("relay WebSocket open timeout")), 20000);
     });
     const chunks = [];
+    let streamDone = false;
+    let streamDoneAt = null;
     const handleMessage = async (rawData) => {
         const raw = typeof rawData === "string"
             ? rawData
@@ -308,20 +335,26 @@ async function runOneAttempt(args, attempt) {
         catch {
             return;
         }
-        if (!frame?.payload)
-            return;
-        if (frame.type === "chunk") {
-            try {
-                const piece = await decryptResponse(prepared.sessionKey, frame.payload);
-                chunks.push(piece);
-                if (onChunk)
-                    onChunk(piece, chunks.join(""));
-            }
-            catch {
-                /* control frame */
+        // "complete" marks end-of-stream (it may or may not carry a payload).
+        // Record it so the JobCompleted wait can stop promptly instead of polling
+        // the full grace window after the answer is already in hand.
+        if (frame.type === "complete") {
+            streamDone = true;
+            streamDoneAt = Date.now();
+            if (chunks.length === 0 && frame.payload) {
+                try {
+                    const piece = await decryptResponse(prepared.sessionKey, frame.payload);
+                    chunks.push(piece);
+                    if (onChunk)
+                        onChunk(piece, chunks.join(""));
+                }
+                catch {
+                    /* ignore */
+                }
             }
+            return;
         }
-        else if (frame.type === "complete" && chunks.length === 0) {
+        if (frame.type === "chunk" && frame.payload) {
             try {
                 const piece = await decryptResponse(prepared.sessionKey, frame.payload);
                 chunks.push(piece);
@@ -329,7 +362,7 @@ async function runOneAttempt(args, attempt) {
                     onChunk(piece, chunks.join(""));
             }
             catch {
-                /* ignore */
+                /* control frame */
             }
         }
     };
@@ -376,7 +409,8 @@ async function runOneAttempt(args, attempt) {
     //     answer with txs.jobCompleted=null (the answer is still session-key
     //     authentic; the on-chain proof can be polled for separately by callers).
     const deadline = Date.now() + jobCompletedTimeoutMs;
-    const POST_CHUNKS_GRACE_MS = 45000;
+    const POST_CHUNKS_GRACE_MS = 45000; // fallback if the relay never sends a 'complete' frame
+    const POST_DONE_GRACE_MS = 8000; // once the answer is fully in, the worker commits JobCompleted within ~seconds
     const waitStart = Date.now();
     let firstChunkAt = chunks.length > 0 ? waitStart : null;
     const jobIdTopic = (`0x${jobId.toString(16).padStart(64, "0")}`);
@@ -385,9 +419,14 @@ async function runOneAttempt(args, attempt) {
         const now = Date.now();
         if (now >= deadline)
             break;
+        // Answer fully received (relay sent 'complete'): wait only briefly for the
+        // on-chain proof, then return. The answer is already session-key authentic;
+        // callers get txs.jobCompleted=null and can poll the proof later if needed.
+        if (streamDone && now - (streamDoneAt ?? now) >= POST_DONE_GRACE_MS)
+            break;
         if (firstChunkAt != null && now - firstChunkAt >= POST_CHUNKS_GRACE_MS)
             break;
-        await new Promise((res) => setTimeout(res, 3000));
+        await new Promise((res) => setTimeout(res, 1500));
         if (firstChunkAt == null && chunks.length > 0)
             firstChunkAt = Date.now();
         const logs = await publicClient.getLogs({
@@ -414,8 +453,9 @@ async function runOneAttempt(args, attempt) {
             feeLcai: fee,
         });
     }
-    // 7. grace period for the last relay frame, then close
-    await new Promise((res) => setTimeout(res, 4000));
+    // 7. grace period for the last relay frame, then close. If the stream already
+    // signaled 'complete', no more frames are coming - skip the wait.
+    await new Promise((res) => setTimeout(res, streamDone ? 300 : 4000));
     try {
         ws.close();
     }
@@ -436,6 +476,53 @@ async function runOneAttempt(args, attempt) {
         stalled: [],
     };
 }
+/** One attempt = open a fresh session, then run one job through it. */
+async function runOneAttempt(args, attempt) {
+    const session = await openSession({
+        gateway: args.gateway,
+        wallet: args.wallet,
+        publicClient: args.publicClient,
+        network: args.network,
+        model: args.model,
+    });
+    return runJobOnSession(session, args.prompt, {
+        onChunk: args.onChunk,
+        jobCompletedTimeoutMs: args.jobCompletedTimeoutMs,
+        WebSocket: args.WebSocket,
+        relayUrl: args.relayUrl,
+        signal: args.signal,
+    }, attempt);
+}
+/**
+ * A reusable, wallet-signed inference session. Open it once (SIWE happens before
+ * this; createSession happens here), then call `.send()` per turn - each
+ * follow-up turn skips createSession, leaving just the submitJob tx. Re-open
+ * (call `LightChatSession.open(...)` again) when `expired` is true or a
+ * `.send()` throws because the worker stopped serving.
+ *
+ * @example
+ * ```ts
+ * const session = await LightChatSession.open({ gateway, wallet, publicClient, network, model: "llama3-8b" });
+ * const a = await session.send("Who wrote The Great Gatsby?", { onChunk });
+ * const b = await session.send("In what year?", { onChunk }); // no createSession
+ * ```
+ */
+export class LightChatSession {
+    constructor(session) {
+        this.session = session;
+    }
+    static async open(args) {
+        return new LightChatSession(await openSession(args));
+    }
+    get sessionId() { return this.session.sessionId; }
+    get worker() { return this.session.worker; }
+    get model() { return this.session.model; }
+    /** true once the on-chain session window has closed; re-open before sending. */
+    get expired() { return Date.now() / 1000 >= this.session.expirySec; }
+    send(prompt, opts = {}) {
+        return runJobOnSession(this.session, prompt, opts);
+    }
+}
 /**
  * One call, full encrypted inference. Same code path the live playground at
  * lightnode.app/playground drives, condensed into a single function.

package/package.json

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