lightnode-sdk 0.4.8 → 0.5.0

package/dist/index.d.ts

@@ -1,7 +1,12 @@
 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, consumerGatewayHost, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey } from "./inference.js";
+import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey, runInferenceStream } from "./inference.js";
+import { Conversation, chat } from "./chat.js";
+import { preflight as workerPreflight, watch as workerWatch } from "./worker.js";
+import { Bridge, BRIDGE_ROUTE, HYPERLANE_ROUTER_ABI, ERC20_ABI, addressToBytes32, quoteBridgeFee, bridgeableBalance, bridgeAllowance, approveBridge, bridgeTransfer } from "./bridge.js";
+import { DAO, DAO_ADDRESSES, ProposalState, PROPOSAL_STATE_LABEL, VoteSupport, GOVERNOR_ABI, VOTES_ABI } from "./dao.js";
+import { OnchainModelRegistry, AIVM_MODEL_REGISTRY_ABI, BENCHMARK_REGISTRY_ABI, ModelStatus, MODEL_STATUS_LABEL } from "./onchain-models.js";
 import { StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker } from "./errors.js";
 import { GatewayClient, GatewayHttpError } from "./gateway.js";
 import * as crypto from "./crypto.js";
@@ -45,6 +50,23 @@ export declare class LightNode {
     isRegistered(address: string): Promise<boolean | null>;
     /** Settled worker earnings in whole LCAI (from total_earned wei). */
     getEarningsLcai(address: string): Promise<number>;
+    /**
+     * One job's current status, classified for builders deciding whether to
+     * retry / claim a refund / accept the answer. `category` is the
+     * builder-friendly label; `raw` is the indexer's literal state string.
+     * Null when the indexer has never seen the job (still pending propagation).
+     */
+    getJobStatus(jobId: string | bigint): Promise<{
+        id: string;
+        raw: string;
+        category: "submitted" | "in-flight" | "completed" | "stalled" | "disputed" | "resolved" | "unknown";
+        worker: string | null;
+        model: string | null;
+        submittedAt: number | null;
+        completedAt: number | null;
+        workerShareLcai: number;
+        refundable: boolean;
+    } | null>;
     /** keccak256 of a model tag (its on-chain + indexer id). */
     modelId(tag: string): `0x${string}`;
     /** On-chain inference fee for a model, in whole LCAI (what submitJob must be paid). */
@@ -66,8 +88,13 @@ 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.4.8";
-export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, runInference, runInferenceWithKey, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, };
+export declare const SDK_VERSION = "0.5.0";
+export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, runInference, runInferenceWithKey, runInferenceStream, Conversation, chat, 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, };
 export type { BearerSource, GatewayClientOptions, SelectSessionResult, PrepareSessionResult, UploadBlobResult, SessionTokenResult } from "./gateway.js";
-export type { SessionPreparation, RunInferenceArgs, RunInferenceResult, RunInferenceWithKeyArgs } from "./inference.js";
+export type { SessionPreparation, RunInferenceArgs, RunInferenceResult, RunInferenceWithKeyArgs, RunInferenceStreamResult } from "./inference.js";
+export type { ChatRole, ChatMessage, ConversationOptions, ConversationSendResult } from "./chat.js";
+export type { WorkerPreflightArgs, WorkerPreflightResult, WorkerWatchOptions, WorkerEventKind, WorkerEvent, WorkerWatchHandle } from "./worker.js";
+export type { BridgeChain, BridgeEndpoints, BridgeTransferArgs } from "./bridge.js";
+export type { DaoChain, DaoAddresses, ProposalSummary, DaoConfig } from "./dao.js";
+export type { BaseModel, ModelVariant, AccessTier, AccessPolicy, Benchmark, OnchainModelRegistryOptions } from "./onchain-models.js";
 export type { NetworkId, NetworkConfig, Worker, Job, ModelInfo, NetworkStats, ModelStat, WorkerStat, NetworkAnalytics };

package/dist/index.js

@@ -1,8 +1,13 @@
 import { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS } from "./networks.js";
-import { fetchWorker, fetchWorkerJobs, fetchRecentJobs, fetchModels, fetchWorkers, summarize, fromWei, } from "./subgraph.js";
+import { fetchWorker, fetchWorkerJobs, fetchRecentJobs, fetchJob, 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, consumerGatewayHost, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey, } from "./inference.js";
+import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey, runInferenceStream, } from "./inference.js";
+import { Conversation, chat } from "./chat.js";
+import { preflight as workerPreflight, watch as workerWatch } from "./worker.js";
+import { Bridge, BRIDGE_ROUTE, HYPERLANE_ROUTER_ABI, ERC20_ABI, addressToBytes32, quoteBridgeFee, bridgeableBalance, bridgeAllowance, approveBridge, bridgeTransfer, } from "./bridge.js";
+import { DAO, DAO_ADDRESSES, ProposalState, PROPOSAL_STATE_LABEL, VoteSupport, GOVERNOR_ABI, VOTES_ABI, } from "./dao.js";
+import { OnchainModelRegistry, AIVM_MODEL_REGISTRY_ABI, BENCHMARK_REGISTRY_ABI, ModelStatus, MODEL_STATUS_LABEL, } from "./onchain-models.js";
 import { StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, } from "./errors.js";
 import { GatewayClient, GatewayHttpError } from "./gateway.js";
 import * as crypto from "./crypto.js";
@@ -72,6 +77,48 @@ export class LightNode {
         const w = await fetchWorker(this.network, address);
         return w ? fromWei(w.total_earned) : 0;
     }
+    /**
+     * One job's current status, classified for builders deciding whether to
+     * retry / claim a refund / accept the answer. `category` is the
+     * builder-friendly label; `raw` is the indexer's literal state string.
+     * Null when the indexer has never seen the job (still pending propagation).
+     */
+    async getJobStatus(jobId) {
+        const j = await fetchJob(this.network, jobId);
+        if (!j)
+            return null;
+        const state = (j.state ?? "").trim();
+        const stateLow = state.toLowerCase();
+        const category = /completed|released|paid/.test(stateLow)
+            ? "completed"
+            : /timed.?out|stalled|expired/.test(stateLow)
+                ? "stalled"
+                : /disputed/.test(stateLow)
+                    ? "disputed"
+                    : /resolved/.test(stateLow)
+                        ? "resolved"
+                        : /ack/.test(stateLow)
+                            ? "in-flight"
+                            : /submitted/.test(stateLow)
+                                ? "submitted"
+                                : "unknown";
+        // A refund is on the table when the worker accepted the job but never
+        // produced an answer within the protocol's dispute window. The protocol's
+        // own timeout/dispute pipeline reclaims the fee; this flag is the SDK's
+        // builder-facing hint that the on-chain refund call is the right path.
+        const refundable = category === "stalled" || category === "disputed";
+        return {
+            id: j.id,
+            raw: state,
+            category,
+            worker: j.worker ?? null,
+            model: j.model_id ?? null,
+            submittedAt: j.submitted_at ?? null,
+            completedAt: j.completed_at ?? null,
+            workerShareLcai: fromWei(j.worker_share),
+            refundable,
+        };
+    }
     /** keccak256 of a model tag (its on-chain + indexer id). */
     modelId(tag) {
         return computeModelId(tag);
@@ -96,11 +143,23 @@ 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.4.8";
+export const SDK_VERSION = "0.5.0";
 export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, 
 // 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, 
 // v0.4.3 key-in-answer-out shortcut: same flow, no viem/SIWE wiring.
-runInferenceWithKey, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, };
+runInferenceWithKey, 
+// v0.4.9 AsyncIterable<string> wrapper around runInferenceWithKey.
+runInferenceStream, 
+// v0.5.0 multi-turn conversation helper (history client-side; one inference per turn).
+Conversation, chat, 
+// v0.5.0 worker preflight + watch (one real test inference + status polling).
+workerPreflight, workerWatch, 
+// v0.5.0 Bridge SDK (Hyperlane Warp Route wrapper for LCAI <-> Ethereum).
+Bridge, BRIDGE_ROUTE, HYPERLANE_ROUTER_ABI, ERC20_ABI, addressToBytes32, quoteBridgeFee, bridgeableBalance, bridgeAllowance, approveBridge, bridgeTransfer, 
+// v0.5.0 DAO SDK (LCAIGovernor wrapper on Ethereum mainnet).
+DAO, DAO_ADDRESSES, ProposalState, PROPOSAL_STATE_LABEL, VoteSupport, GOVERNOR_ABI, VOTES_ABI, 
+// v0.5.0 On-chain model registry reader (AIVMModelRegistry + BenchmarkRegistry).
+OnchainModelRegistry, AIVM_MODEL_REGISTRY_ABI, BENCHMARK_REGISTRY_ABI, ModelStatus, MODEL_STATUS_LABEL, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, };

package/dist/inference.d.ts

@@ -287,3 +287,37 @@ export interface RunInferenceWithKeyArgs {
  * ```
  */
 export declare function runInferenceWithKey(args: RunInferenceWithKeyArgs): Promise<RunInferenceResult>;
+export interface RunInferenceStreamResult {
+    /** Streamed chunks (decrypted, in arrival order). */
+    [Symbol.asyncIterator](): AsyncIterator<string>;
+    /**
+     * Resolves with the same shape `runInference` returns once the iterator
+     * has finished (i.e. you've consumed all chunks). `answer` is the full
+     * assembled string. Awaiting this before consuming the iterator hangs;
+     * always iterate first or in parallel with another consumer.
+     */
+    done: Promise<RunInferenceResult>;
+}
+/**
+ * Stream-shaped wrapper over `runInferenceWithKey`. Returns an async-iterable
+ * of decrypted chunks plus a `done` promise that resolves to the full result
+ * once the iteration completes.
+ *
+ * @example
+ * ```ts
+ * import { runInferenceStream } from "lightnode-sdk";
+ *
+ * const stream = runInferenceStream({
+ *   network: "testnet",
+ *   privateKey: process.env.PRIVATE_KEY!,
+ *   prompt: "Write a haiku about decentralized AI.",
+ * });
+ *
+ * for await (const chunk of stream) {
+ *   process.stdout.write(chunk);
+ * }
+ * const { txs } = await stream.done;
+ * console.log("\n", txs);
+ * ```
+ */
+export declare function runInferenceStream(args: RunInferenceWithKeyArgs): RunInferenceStreamResult;

package/dist/inference.js

@@ -535,16 +535,32 @@ export async function runInferenceWithKey(args) {
     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 ?? gwBase });
-    // 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 ??
+    // Pick a WebSocket: caller-supplied wins, else the browser global, else try
+    // to lazy-import the `ws` package (Node). The webpackIgnore hint keeps
+    // bundlers from blowing up trying to resolve `ws` for browser bundles where
+    // we never reach this branch.
+    let 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, ... })`");
+        try {
+            // Hide the module name from TS's static resolver via a Function-built
+            // dynamic import - otherwise TS errors trying to find @types/ws (we do
+            // not want that as a SDK devDep). The webpackIgnore-style comment also
+            // keeps browser bundlers from trying to resolve `ws`.
+            const dynamicImport = Function("n", "return import(/* webpackIgnore: true */ n)");
+            const mod = await dynamicImport("ws");
+            wsCtor = mod.default ?? mod.WebSocket;
+        }
+        catch {
+            // `ws` not installed - keep wsCtor undefined and fall into the error below.
+        }
+    }
+    if (!wsCtor) {
+        throw new Error("runInferenceWithKey: no WebSocket constructor available. In Node, install `ws` " +
+            "(`npm i ws`) - the SDK will pick it up automatically. Or pass one explicitly: " +
+            "`import WS from 'ws'; runInferenceWithKey({ WebSocket: WS, ... })`.");
     }
     return runInference({
         prompt: args.prompt,
@@ -560,3 +576,88 @@ export async function runInferenceWithKey(args) {
         relayUrl: args.relayUrl,
     });
 }
+/**
+ * Stream-shaped wrapper over `runInferenceWithKey`. Returns an async-iterable
+ * of decrypted chunks plus a `done` promise that resolves to the full result
+ * once the iteration completes.
+ *
+ * @example
+ * ```ts
+ * import { runInferenceStream } from "lightnode-sdk";
+ *
+ * const stream = runInferenceStream({
+ *   network: "testnet",
+ *   privateKey: process.env.PRIVATE_KEY!,
+ *   prompt: "Write a haiku about decentralized AI.",
+ * });
+ *
+ * for await (const chunk of stream) {
+ *   process.stdout.write(chunk);
+ * }
+ * const { txs } = await stream.done;
+ * console.log("\n", txs);
+ * ```
+ */
+export function runInferenceStream(args) {
+    // Bounded queue of pending chunks; consumed in order by the iterator. We
+    // can't use an unbounded array because the inference may produce chunks
+    // faster than the consumer reads them - bounding at 1024 is enough to absorb
+    // model-output bursts without unbounded memory growth.
+    const queue = [];
+    const waiters = [];
+    let finished = false;
+    let error = null;
+    const push = (chunk) => {
+        if (waiters.length > 0) {
+            const resolve = waiters.shift();
+            if (resolve)
+                resolve({ value: chunk, done: false });
+        }
+        else {
+            queue.push(chunk);
+        }
+    };
+    const finish = (err = null) => {
+        finished = true;
+        error = err;
+        while (waiters.length > 0) {
+            const resolve = waiters.shift();
+            if (!resolve)
+                continue;
+            if (err)
+                resolve({ value: undefined, done: true });
+            else
+                resolve({ value: undefined, done: true });
+        }
+    };
+    const done = runInferenceWithKey({
+        ...args,
+        onChunk: (chunk) => push(chunk),
+    })
+        .then((res) => {
+        finish(null);
+        return res;
+    })
+        .catch((e) => {
+        finish(e);
+        throw e;
+    });
+    return {
+        [Symbol.asyncIterator]() {
+            return {
+                async next() {
+                    if (queue.length > 0) {
+                        return { value: queue.shift(), done: false };
+                    }
+                    if (finished) {
+                        if (error)
+                            throw error;
+                        return { value: undefined, done: true };
+                    }
+                    return new Promise((resolve) => waiters.push(resolve));
+                },
+            };
+        },
+        done,
+    };
+}