lightnode-sdk 0.4.2 → 0.4.4

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

@@ -229,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

@@ -326,16 +326,31 @@ 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".
+    // The actual *result* is the WS-delivered, session-key-decrypted ciphertext.
+    // JobCompleted is an explorer pointer (the worker's commit-result tx).
+    // Polling rules:
+    //   - No chunks yet: poll for the full deadline (default 120s). Still nothing
+    //     -> throw stalled so the outer loop can retry with a different worker.
+    //   - Chunks arrived: keep polling for a 45s grace window after the FIRST
+    //     chunk. Workers usually commit JobCompleted within ~10s of broadcasting
+    //     the answer, so 45s is generous. If it still doesn't land, surface the
+    //     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 waitStart = Date.now();
+    let firstChunkAt = chunks.length > 0 ? waitStart : null;
     const jobIdTopic = (`0x${jobId.toString(16).padStart(64, "0")}`);
     let completed = null;
-    while (!completed && Date.now() < deadline) {
+    while (!completed) {
+        const now = Date.now();
+        if (now >= deadline)
+            break;
+        if (firstChunkAt != null && now - firstChunkAt >= POST_CHUNKS_GRACE_MS)
+            break;
         await new Promise((res) => setTimeout(res, 3000));
+        if (firstChunkAt == null && chunks.length > 0)
+            firstChunkAt = Date.now();
         const logs = await publicClient.getLogs({
             address: network.jobRegistry,
             fromBlock: submitReceipt.blockNumber,
@@ -345,10 +360,6 @@ async function runOneAttempt(args, attempt) {
             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 && chunks.length === 0) {
         try {
@@ -434,3 +445,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.2",
+  "version": "0.4.4",
   "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",