lightnode-sdk 0.4.1 → 0.4.3

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS } from "./networks.js";
 import { fromWei } from "./subgraph.js";
 import { aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv } from "./analytics.js";
-import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference } from "./inference.js";
+import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey } from "./inference.js";
 import { StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker } from "./errors.js";
 import { GatewayClient, GatewayHttpError } from "./gateway.js";
 import * as crypto from "./crypto.js";
@@ -60,7 +60,7 @@ export declare class LightNode {
         baseUrl?: string;
     }): GatewayClient;
 }
-export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, runInference, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, };
+export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, runInference, runInferenceWithKey, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, };
 export type { BearerSource, GatewayClientOptions, SelectSessionResult, PrepareSessionResult, UploadBlobResult, SessionTokenResult } from "./gateway.js";
-export type { SessionPreparation, RunInferenceArgs, RunInferenceResult } from "./inference.js";
+export type { SessionPreparation, RunInferenceArgs, RunInferenceResult, RunInferenceWithKeyArgs } from "./inference.js";
 export type { NetworkId, NetworkConfig, Worker, Job, ModelInfo, NetworkStats, ModelStat, WorkerStat, NetworkAnalytics };

package/dist/index.js

@@ -2,7 +2,7 @@ import { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS } from "./networks.js";
 import { fetchWorker, fetchWorkerJobs, fetchRecentJobs, fetchModels, fetchWorkers, summarize, fromWei, } from "./subgraph.js";
 import { isRegistered } from "./onchain.js";
 import { aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, } from "./analytics.js";
-import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, } from "./inference.js";
+import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey, } from "./inference.js";
 import { StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, } from "./errors.js";
 import { GatewayClient, GatewayHttpError } from "./gateway.js";
 import * as crypto from "./crypto.js";
@@ -94,4 +94,6 @@ export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggreg
 // v0.3 inference-submit surface (BETA - see README "Submitting inference").
 GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, 
 // v0.4 high-level orchestrator: one call, full flow.
-runInference, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, };
+runInference, 
+// v0.4.3 key-in-answer-out shortcut: same flow, no viem/SIWE wiring.
+runInferenceWithKey, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, };

package/dist/inference.d.ts

@@ -159,7 +159,7 @@ export interface RunInferenceArgs {
     onChunk?: (chunk: string, totalSoFar: string) => void;
     /** Retry count if a worker stalls. Default 2 (so up to 3 paid attempts). */
     maxRetries?: number;
-    /** How long to wait for JobCompleted before declaring the worker stalled. Default 90s. */
+    /** How long to wait for JobCompleted before declaring the worker stalled. Default 120s. */
     jobCompletedTimeoutMs?: number;
     /**
      * WebSocket constructor. In a browser, omit and `globalThis.WebSocket` is
@@ -179,7 +179,12 @@ export interface RunInferenceResult {
     txs: {
         createSession: `0x${string}`;
         submitJob: `0x${string}`;
-        jobCompleted: `0x${string}`;
+        /**
+         * Worker's commit-result tx. Null if the on-chain event hasn't landed by the
+         * deadline but the WS-delivered, session-key-decrypted answer DID arrive -
+         * in that case the answer is still authentic; this is just the explorer link.
+         */
+        jobCompleted: `0x${string}` | null;
     };
     /** The dispatcher-assigned worker that produced this response. */
     worker: `0x${string}`;
@@ -224,3 +229,61 @@ export interface RunInferenceResult {
 export declare function runInference(args: RunInferenceArgs): Promise<RunInferenceResult>;
 /** Re-export the typed errors at this layer so a single import covers everything. */
 export { StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker } from "./errors.js";
+import type { NetworkId } from "./types.js";
+export interface RunInferenceWithKeyArgs {
+    /** Network ID (`"testnet"` / `"mainnet"`) or a custom NetworkConfig. */
+    network: NetworkId | NetworkConfig;
+    /**
+     * A funded EVM private key, hex with `0x` prefix. Pays the job fee + gas and
+     * signs createSession + submitJob. NEVER hardcode this - load from env.
+     */
+    privateKey: string;
+    /** The plaintext prompt to send. UTF-8 encoded before encryption. */
+    prompt: string;
+    /** Inference model tag. Default: `"llama3-8b"`. */
+    model?: string;
+    /**
+     * Streaming callback invoked once per decrypted relay chunk. Use for live
+     * stdout / UI updates. Optional - the final `answer` is returned either way.
+     */
+    onChunk?: (chunk: string, totalSoFar: string) => void;
+    /** Retry count if a worker stalls. Default 2 (so up to 3 paid attempts). */
+    maxRetries?: number;
+    /** How long to wait for JobCompleted before declaring the worker stalled. Default 120s. */
+    jobCompletedTimeoutMs?: number;
+    /**
+     * WebSocket constructor. In a browser this is auto-detected from
+     * `globalThis.WebSocket`. In Node, pass `WS` from the `ws` package
+     * (`import WS from "ws"`) - `ws` is not a hard dep of this SDK.
+     */
+    WebSocket?: WebSocketCtor;
+    /** Override the relay URL (defaults to `wss://relay.<network>.lightchain.ai/ws`). */
+    relayUrl?: string;
+    /**
+     * Override the consumer-api gateway URL. Defaults to a network-derived URL.
+     * Useful for tests / mirrors / proxying through your own backend.
+     */
+    gatewayUrl?: string;
+}
+/**
+ * One call, key-in / answer-out encrypted inference. Builds viem clients,
+ * runs the SIWE handshake, opens the encrypted session, submits + decrypts,
+ * and returns. Same proof chain (`createSession`, `submitJob`, `jobCompleted`)
+ * as the lower-level `runInference`.
+ *
+ * @example
+ * ```ts
+ * import { runInferenceWithKey } from "lightnode-sdk";
+ * import WS from "ws";
+ *
+ * const { answer, txs } = await runInferenceWithKey({
+ *   network: "testnet",
+ *   privateKey: process.env.PRIVATE_KEY!,
+ *   prompt: "Reply with a one-sentence fun fact about the ocean.",
+ *   WebSocket: WS, // omit in the browser
+ * });
+ *
+ * console.log(answer);
+ * ```
+ */
+export declare function runInferenceWithKey(args: RunInferenceWithKeyArgs): Promise<RunInferenceResult>;

package/dist/inference.js

@@ -190,7 +190,7 @@ function topicAsUint(hex) {
     return BigInt(hex);
 }
 async function runOneAttempt(args, attempt) {
-    const { prompt, gateway, wallet, publicClient, network, model = "llama3-8b", onChunk, jobCompletedTimeoutMs = 90000, } = args;
+    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
@@ -326,6 +326,11 @@ async function runOneAttempt(args, attempt) {
         throw new Error("JobSubmitted log missing in submitJob receipt");
     const jobId = topicAsUint(jobLog.topics[1]);
     // 6. wait for JobCompleted
+    // KEY INVARIANT: the real result is the WS-delivered, session-key-decrypted
+    // ciphertext. JobCompleted is an explorer pointer (the worker's commit-result
+    // tx). If the WS already produced an answer (chunks.length > 0) we MUST
+    // accept it even if the on-chain event hasn't landed - throwing stalled here
+    // wipes a delivered answer on retry, which reads as "the call returned nothing".
     const deadline = Date.now() + jobCompletedTimeoutMs;
     const jobIdTopic = (`0x${jobId.toString(16).padStart(64, "0")}`);
     let completed = null;
@@ -338,8 +343,14 @@ async function runOneAttempt(args, attempt) {
         });
         completed =
             logs.find((l) => l.topics[0] === JOB_COMPLETED_TOPIC && l.topics[1] === jobIdTopic) ?? null;
+        if (completed)
+            break;
+        // If the WS already delivered the answer, stop polling - no point burning
+        // more time on a confirmation that only serves as an explorer link.
+        if (chunks.length > 0)
+            break;
     }
-    if (!completed) {
+    if (!completed && chunks.length === 0) {
         try {
             ws.close();
         }
@@ -363,7 +374,11 @@ async function runOneAttempt(args, attempt) {
     }
     return {
         answer: chunks.join(""),
-        txs: { createSession: createTx, submitJob: submitTx, jobCompleted: completed.transactionHash },
+        // completed may be null when the answer arrived via the WS but JobCompleted
+        // hasn't landed on-chain yet. The decrypted answer is still authentic
+        // (session-key bound); callers can poll for the event later if they want
+        // the explorer-link form of the proof.
+        txs: { createSession: createTx, submitJob: submitTx, jobCompleted: completed?.transactionHash ?? null },
         worker: prepared.createSessionArgs.worker,
         sessionId,
         jobId,
@@ -419,3 +434,100 @@ export async function runInference(args) {
 }
 /** Re-export the typed errors at this layer so a single import covers everything. */
 export { StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker } from "./errors.js";
+import { NETWORKS } from "./networks.js";
+import { GatewayClient as GatewayClientCtor, consumerGatewayUrl as consumerGatewayUrlFn } from "./gateway.js";
+import { GatewayAuthError } from "./errors.js";
+import { createPublicClient as viemCreatePublicClient, createWalletClient as viemCreateWalletClient, http as viemHttp } from "viem";
+import { privateKeyToAccount as viemPrivateKeyToAccount } from "viem/accounts";
+/**
+ * One call, key-in / answer-out encrypted inference. Builds viem clients,
+ * runs the SIWE handshake, opens the encrypted session, submits + decrypts,
+ * and returns. Same proof chain (`createSession`, `submitJob`, `jobCompleted`)
+ * as the lower-level `runInference`.
+ *
+ * @example
+ * ```ts
+ * import { runInferenceWithKey } from "lightnode-sdk";
+ * import WS from "ws";
+ *
+ * const { answer, txs } = await runInferenceWithKey({
+ *   network: "testnet",
+ *   privateKey: process.env.PRIVATE_KEY!,
+ *   prompt: "Reply with a one-sentence fun fact about the ocean.",
+ *   WebSocket: WS, // omit in the browser
+ * });
+ *
+ * console.log(answer);
+ * ```
+ */
+export async function runInferenceWithKey(args) {
+    // Resolve the network config and validate the key shape up front so a
+    // mistyped key fails BEFORE we touch the RPC or the gateway.
+    const network = typeof args.network === "string" ? NETWORKS[args.network] : args.network;
+    if (!network)
+        throw new Error(`unknown network: ${String(args.network)}`);
+    const networkId = (typeof args.network === "string" ? args.network : "mainnet");
+    const key = args.privateKey?.trim();
+    if (!key || !key.startsWith("0x") || key.length !== 66) {
+        throw new Error("runInferenceWithKey: privateKey must be a 0x-prefixed 32-byte hex string");
+    }
+    const account = viemPrivateKeyToAccount(key);
+    const chain = {
+        id: network.chainId,
+        name: network.label,
+        nativeCurrency: { name: "LCAI", symbol: "LCAI", decimals: 18 },
+        rpcUrls: { default: { http: [network.rpc] } },
+    };
+    // Keep viem's real types here so signMessage / etc. are typed. The MinimalX
+    // casts only happen at the runInference() call site below.
+    const publicClient = viemCreatePublicClient({ transport: viemHttp(network.rpc), chain });
+    const wallet = viemCreateWalletClient({ account, transport: viemHttp(network.rpc), chain });
+    // One-shot SIWE handshake. We do this inline (rather than re-export it) so
+    // the caller doesn't need a second import; in browsers + Node it works the
+    // same against the consumer-api gateway.
+    const gwBase = args.gatewayUrl ?? consumerGatewayUrlFn(networkId);
+    const chRes = await fetch(`${gwBase}/api/auth/challenge?address=${account.address}`, {
+        headers: { Accept: "application/json" },
+    });
+    if (!chRes.ok)
+        throw new GatewayAuthError(chRes.status, await chRes.text());
+    const ch = (await chRes.json());
+    if (!ch.message)
+        throw new GatewayAuthError(chRes.status, "auth challenge returned no message");
+    const signature = await wallet.signMessage({ account, message: ch.message });
+    const verifyRes = await fetch(`${gwBase}/api/auth/verify`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body: JSON.stringify({ message: ch.message, signature }),
+    });
+    if (!verifyRes.ok)
+        throw new GatewayAuthError(verifyRes.status, await verifyRes.text());
+    const verify = (await verifyRes.json());
+    if (!verify.token)
+        throw new GatewayAuthError(verifyRes.status, "auth verify returned no token");
+    const gateway = new GatewayClientCtor({ network: networkId, bearer: verify.token, baseUrl: args.gatewayUrl });
+    // Pick a WebSocket: the browser global if present, otherwise the caller-
+    // supplied ctor. We deliberately do NOT try to dynamic-import "ws" - it
+    // isn't a hard dep, and a bundler trying to resolve it would fail noisily.
+    const wsCtor = args.WebSocket ??
+        (typeof globalThis !== "undefined" && globalThis.WebSocket
+            ? globalThis.WebSocket
+            : undefined);
+    if (!wsCtor) {
+        throw new Error("runInferenceWithKey: no WebSocket constructor available. In Node, install `ws` and pass it: " +
+            "`import WS from 'ws'; runInferenceWithKey({ WebSocket: WS, ... })`");
+    }
+    return runInference({
+        prompt: args.prompt,
+        gateway,
+        wallet: wallet,
+        publicClient: publicClient,
+        network,
+        model: args.model,
+        onChunk: args.onChunk,
+        maxRetries: args.maxRetries,
+        jobCompletedTimeoutMs: args.jobCompletedTimeoutMs,
+        WebSocket: wsCtor,
+        relayUrl: args.relayUrl,
+    });
+}

package/package.json

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