lightnode-sdk 0.4.9 → 0.5.0

package/dist/worker.js

@@ -0,0 +1,186 @@
+/**
+ * SDK-level worker preflight + watch.
+ *
+ * The desktop app already has local worker-health parsers (parseWorkerHealth,
+ * parseSpeedTest) that need shell access to the running container. Those are
+ * great for operators ON the worker box, but useless for a builder watching
+ * the network from anywhere else.
+ *
+ * This module fills the remote-only gap:
+ *   - `preflight()` runs ONE real test inference against the live network
+ *     and returns a verdict (works / over-deadline / failed). This is the
+ *     "test job before joining a worker pool" the community has been asking
+ *     for; works from any machine with a funded wallet.
+ *   - `watch()` polls a worker's on-chain + indexer status on a fixed
+ *     interval and yields an event each time the status meaningfully
+ *     changes (registered <-> deregistered, last-seen went stale, completion
+ *     rate dropped). Suitable for a CI gate or a `cron` job.
+ *
+ * Both are pure SDK calls. No Docker, no SSH, no privileged access.
+ */
+import { runInferenceWithKey } from "./inference.js";
+import { isStalledWorker } from "./errors.js";
+const DEFAULT_PROMPT = "Reply with the single word OK.";
+/**
+ * Run one real encrypted inference against the live network and classify
+ * the result. Useful as a CI gate ("did the wallet survive a real call this
+ * deploy?") or as a pre-join check for a worker operator who wants to test
+ * the protocol path before staking.
+ */
+export async function preflight(args) {
+    const deadlineMs = args.deadlineMs ?? 60000;
+    const prompt = args.prompt ?? DEFAULT_PROMPT;
+    const t0 = Date.now();
+    try {
+        const r = await runInferenceWithKey({ ...args, prompt });
+        const elapsedMs = Date.now() - t0;
+        const verdict = elapsedMs > deadlineMs ? "over-deadline" : "ok";
+        return {
+            verdict,
+            elapsedMs,
+            summary: verdict === "ok"
+                ? `OK in ${(elapsedMs / 1000).toFixed(1)}s. Worker ${r.worker} replied with ${r.answer.length} chars.`
+                : `Answer arrived but took ${(elapsedMs / 1000).toFixed(1)}s, over the ${(deadlineMs / 1000).toFixed(0)}s deadline.`,
+            answer: r.answer,
+            worker: r.worker,
+            txs: r.txs,
+            error: null,
+        };
+    }
+    catch (e) {
+        const elapsedMs = Date.now() - t0;
+        if (isStalledWorker(e)) {
+            return {
+                verdict: "stalled",
+                elapsedMs,
+                summary: "All retry attempts stalled (workers never produced an answer). Protocol refunds the fees automatically.",
+                answer: "",
+                worker: null,
+                txs: { createSession: null, submitJob: null, jobCompleted: null },
+                error: e.message,
+            };
+        }
+        return {
+            verdict: "failed",
+            elapsedMs,
+            summary: `Test inference failed: ${e.message}`,
+            answer: "",
+            worker: null,
+            txs: { createSession: null, submitJob: null, jobCompleted: null },
+            error: e.message,
+        };
+    }
+}
+/**
+ * Poll one worker's on-chain + indexer status and yield an event each time
+ * something meaningful changes (registration, staleness, completed-jobs
+ * counter, earnings). Runs until `handle.stop()` is called or `maxEvents`
+ * is reached.
+ */
+export function watch(ln, address, opts = {}) {
+    const intervalMs = opts.intervalMs ?? 30000;
+    const staleSecs = opts.staleSecs ?? 90;
+    const maxEvents = opts.maxEvents ?? Number.POSITIVE_INFINITY;
+    const networkId = ln.network.label.toLowerCase().includes("mainnet") ? "mainnet" : "testnet";
+    const queue = [];
+    const waiters = [];
+    let stopped = false;
+    let eventCount = 0;
+    let prevReg = null;
+    let prevStale = null;
+    let prevJobs = null;
+    let prevEarn = null;
+    let timer = null;
+    const push = (kind, state) => {
+        const event = { kind, at: Date.now(), worker: address, network: networkId, state };
+        eventCount++;
+        if (waiters.length > 0) {
+            const resolve = waiters.shift();
+            if (resolve)
+                resolve({ value: event, done: false });
+        }
+        else {
+            queue.push(event);
+        }
+        if (eventCount >= maxEvents)
+            stop();
+    };
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        if (timer)
+            clearTimeout(timer);
+        timer = null;
+        while (waiters.length > 0) {
+            const resolve = waiters.shift();
+            if (resolve)
+                resolve({ value: undefined, done: true });
+        }
+    };
+    const poll = async () => {
+        if (stopped)
+            return;
+        try {
+            const [reg, worker] = await Promise.all([ln.isRegistered(address), ln.getWorker(address)]);
+            const now = Math.floor(Date.now() / 1000);
+            const lastSeenSecsAgo = worker?.last_seen_at != null ? Math.max(0, now - worker.last_seen_at) : null;
+            const isStale = lastSeenSecsAgo == null ? false : lastSeenSecsAgo > staleSecs;
+            const jobs = worker?.jobs_completed ?? null;
+            const earn = worker ? Number(BigInt(worker.total_earned ?? "0")) / 1e18 : 0;
+            const state = {
+                registered: reg,
+                lastSeenSecsAgo,
+                jobsCompleted: jobs,
+                earningsLcai: earn,
+                activeJobs: worker?.active_job_count ?? null,
+                isStale,
+            };
+            // First poll: emit a snapshot so the caller always sees an initial event.
+            if (prevReg === null && prevStale === null && prevJobs === null && prevEarn === null) {
+                push("snapshot", state);
+            }
+            else {
+                if (prevReg === false && reg === true)
+                    push("registered", state);
+                if (prevReg === true && reg === false)
+                    push("deregistered", state);
+                if (prevStale === false && isStale)
+                    push("went-stale", state);
+                if (prevStale === true && !isStale)
+                    push("back-online", state);
+                if (jobs != null && prevJobs != null && jobs > prevJobs)
+                    push("jobs-completed", state);
+                if (earn > (prevEarn ?? 0) + 1e-9)
+                    push("earnings-up", state);
+            }
+            prevReg = reg;
+            prevStale = isStale;
+            prevJobs = jobs;
+            prevEarn = earn;
+        }
+        catch {
+            // Transient indexer / RPC error - do nothing, the next poll will retry.
+        }
+        if (!stopped)
+            timer = setTimeout(poll, intervalMs);
+    };
+    // Kick off the first poll immediately.
+    void poll();
+    return {
+        events: {
+            [Symbol.asyncIterator]() {
+                return {
+                    async next() {
+                        if (queue.length > 0)
+                            return { value: queue.shift(), done: false };
+                        if (stopped)
+                            return { value: undefined, done: true };
+                        return new Promise((resolve) => waiters.push(resolve));
+                    },
+                };
+            },
+        },
+        stop,
+    };
+}

package/package.json

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