lightnode-sdk 0.3.2 → 0.4.0

package/dist/inference.js

@@ -126,3 +126,296 @@ export async function decryptResponse(sessionKey, ciphertext) {
 export { consumerGatewayUrl, GatewayClient } from "./gateway.js";
 /** Optional helper: generate the caller's own ECDH keypair if they want one (e.g. acting as the disputer). */
 export { generateEcdhKeyPair };
+// ----------------------------------------------------------------------------
+// runInference - one call, full flow.
+//
+// Turns the seven-stage protocol (auth -> prepare -> createSession -> open relay
+// -> uploadBlob -> submitJob -> stream + decrypt -> wait JobCompleted) into a
+// single async call. Supports:
+//
+//   - onChunk callback     for live streaming to a UI / stdout
+//   - maxRetries           auto-retry on StalledWorkerError (default 2)
+//   - WebSocket            inject a constructor (Node: `ws`. Browser: omit and
+//                          globalThis.WebSocket is used.)
+//
+// This is the API a builder should reach for first. The lower-level helpers
+// (prepareSession, submitPrompt, decryptResponse) are still exported for
+// builders who want to do something the orchestrator doesn't cover (e.g.
+// reuse a session across multiple prompts, custom retry policy).
+// ----------------------------------------------------------------------------
+import { StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError } from "./errors.js";
+const JOB_REGISTRY_ABI_PARSED = [
+    {
+        type: "function",
+        name: "createSession",
+        stateMutability: "payable",
+        inputs: [
+            { name: "paramsHash", type: "bytes32" },
+            { name: "worker", type: "address" },
+            { name: "encWorkerKey", type: "bytes" },
+            { name: "ephemeralPubKey", type: "bytes" },
+            { name: "initState", type: "bytes" },
+            { name: "expiry", type: "uint256" },
+        ],
+        outputs: [{ name: "sessionId", type: "uint256" }],
+    },
+    {
+        type: "function",
+        name: "submitJob",
+        stateMutability: "payable",
+        inputs: [
+            { name: "sessionId", type: "uint256" },
+            { name: "promptHash", type: "bytes32" },
+        ],
+        outputs: [{ name: "jobId", type: "uint256" }],
+    },
+];
+// Pre-computed topic hashes for the three events we listen for.
+// keccak256("SessionCreated(uint256,address,bytes32,address,bytes,bytes)")
+const SESSION_CREATED_TOPIC = "0xedf9fab204f0bb366f5b33ff07f441f4e387a833e86bfe1364a42ae2c7e05d73";
+// keccak256("JobSubmitted(uint256,uint256,address)")
+const JOB_SUBMITTED_TOPIC = "0xfb47370368875d7490803c5653d9496d0a3c5e1b49a17f013ec37abd9d86d356";
+// keccak256("JobCompleted(uint256,address,bytes32,bytes32)")
+const JOB_COMPLETED_TOPIC = "0xdb545db74bae046337ed01971cf61569fd1a1460ff8ed511ab19ceaac1326377";
+function pickWebSocket(provided) {
+    if (provided)
+        return provided;
+    const g = globalThis.WebSocket;
+    if (!g) {
+        throw new Error("no WebSocket available - either run in a browser or pass { WebSocket: require('ws') }");
+    }
+    return g;
+}
+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 WS = pickWebSocket(args.WebSocket);
+    const relayUrl = args.relayUrl ?? `wss://relay.${network.id}.lightchain.ai/ws`;
+    // 1. prepareSession
+    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,
+        functionName: "createSession",
+        args: [
+            prepared.createSessionArgs.paramsHash,
+            prepared.createSessionArgs.worker,
+            prepared.createSessionArgs.encWorkerKey,
+            prepared.createSessionArgs.ephemeralPubKey,
+            prepared.createSessionArgs.initState,
+            prepared.createSessionArgs.expiry,
+        ],
+        gas: 1000000n,
+    });
+    const createReceipt = await publicClient.waitForTransactionReceipt({ hash: createTx });
+    if (createReceipt.status !== "success")
+        throw new OnChainRevertError("createSession", createTx);
+    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]);
+    // 3. relay token + WebSocket
+    let relayToken;
+    for (let i = 0; i < 30 && !relayToken; i++) {
+        const r = await gateway.getSessionToken(Number(sessionId));
+        if ("token" in r && r.token)
+            relayToken = r.token;
+        else
+            await new Promise((res) => setTimeout(res, 1000));
+    }
+    if (!relayToken)
+        throw new RelayTokenTimeoutError();
+    const ws = new WS(`${relayUrl}?token=${encodeURIComponent(relayToken)}`);
+    try {
+        ws.binaryType = "arraybuffer";
+    }
+    catch {
+        /* not a browser-style WS; ignore */
+    }
+    // Wait for open, supporting both browser (addEventListener) and Node ws (once).
+    await new Promise((resolve, reject) => {
+        const onOpen = () => resolve();
+        const onError = (e) => reject(e instanceof Error ? e : new Error("WebSocket open failed"));
+        if (ws.once) {
+            ws.once("open", onOpen);
+            ws.once("error", onError);
+        }
+        else if (ws.addEventListener) {
+            ws.addEventListener("open", onOpen, { once: true });
+            ws.addEventListener("error", onError, { once: true });
+        }
+        else {
+            reject(new Error("WebSocket has neither once nor addEventListener"));
+        }
+        setTimeout(() => reject(new Error("relay WebSocket open timeout")), 20000);
+    });
+    const chunks = [];
+    const handleMessage = async (rawData) => {
+        const raw = typeof rawData === "string"
+            ? rawData
+            : rawData instanceof ArrayBuffer
+                ? new TextDecoder().decode(rawData)
+                : typeof rawData.toString === "function"
+                    ? rawData.toString()
+                    : "";
+        let frame;
+        try {
+            frame = JSON.parse(raw);
+        }
+        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 */
+            }
+        }
+        else if (frame.type === "complete" && chunks.length === 0) {
+            try {
+                const piece = await decryptResponse(prepared.sessionKey, frame.payload);
+                chunks.push(piece);
+                if (onChunk)
+                    onChunk(piece, chunks.join(""));
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    };
+    if (ws.on) {
+        ws.on("message", handleMessage);
+    }
+    else if (ws.addEventListener) {
+        ws.addEventListener("message", (ev) => handleMessage(ev.data));
+    }
+    // 4. encrypt + upload prompt
+    const promptHash = await submitPrompt(gateway, prepared.sessionKey, prompt);
+    // 5. submitJob on-chain
+    const submitTx = await wallet.writeContract({
+        address: network.jobRegistry,
+        abi: JOB_REGISTRY_ABI_PARSED,
+        functionName: "submitJob",
+        args: [sessionId, promptHash],
+        value: BigInt(Math.round(fee * 1e18)),
+        gas: 500000n,
+    });
+    const submitReceipt = await publicClient.waitForTransactionReceipt({ hash: submitTx });
+    if (submitReceipt.status !== "success") {
+        try {
+            ws.close();
+        }
+        catch {
+            /* ignore */
+        }
+        throw new OnChainRevertError("submitJob", submitTx);
+    }
+    const jobLog = (await publicClient.getLogs({ address: network.jobRegistry, blockHash: submitReceipt.blockHash })).find((l) => l.transactionHash === submitTx && l.topics[0] === JOB_SUBMITTED_TOPIC);
+    if (!jobLog)
+        throw new Error("JobSubmitted log missing in submitJob receipt");
+    const jobId = topicAsUint(jobLog.topics[1]);
+    // 6. wait for JobCompleted
+    const deadline = Date.now() + jobCompletedTimeoutMs;
+    const jobIdTopic = (`0x${jobId.toString(16).padStart(64, "0")}`);
+    let completed = null;
+    while (!completed && Date.now() < deadline) {
+        await new Promise((res) => setTimeout(res, 3000));
+        const logs = await publicClient.getLogs({
+            address: network.jobRegistry,
+            fromBlock: submitReceipt.blockNumber,
+            toBlock: "latest",
+        });
+        completed =
+            logs.find((l) => l.topics[0] === JOB_COMPLETED_TOPIC && l.topics[1] === jobIdTopic) ?? null;
+    }
+    if (!completed) {
+        try {
+            ws.close();
+        }
+        catch {
+            /* ignore */
+        }
+        throw new StalledWorkerError({
+            jobId,
+            worker: prepared.createSessionArgs.worker,
+            submitTx,
+            feeLcai: fee,
+        });
+    }
+    // 7. grace period for the last relay frame, then close
+    await new Promise((res) => setTimeout(res, 4000));
+    try {
+        ws.close();
+    }
+    catch {
+        /* ignore */
+    }
+    return {
+        answer: chunks.join(""),
+        txs: { createSession: createTx, submitJob: submitTx, jobCompleted: completed.transactionHash },
+        worker: prepared.createSessionArgs.worker,
+        sessionId,
+        jobId,
+        attempts: attempt,
+        stalled: [],
+    };
+}
+/**
+ * One call, full encrypted inference. Same code path the live playground at
+ * lightnode.app/playground drives, condensed into a single function.
+ *
+ * @example
+ * ```ts
+ * import { LightNode, runInference, GatewayClient } from "lightnode-sdk";
+ * import { createPublicClient, createWalletClient, http } from "viem";
+ * import { privateKeyToAccount } from "viem/accounts";
+ * import WS from "ws";
+ *
+ * const ln = new LightNode("testnet");
+ * const wallet = createWalletClient({ account: privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`), transport: http(ln.network.rpc) });
+ * const publicClient = createPublicClient({ transport: http(ln.network.rpc) });
+ * const gateway = new GatewayClient({ network: "testnet", bearer: await getJwt() });
+ *
+ * const { answer, txs } = await runInference({
+ *   prompt: "Reply with a one-sentence fun fact about the ocean.",
+ *   gateway, wallet, publicClient, network: ln.network,
+ *   WebSocket: WS, // omit in the browser
+ *   onChunk: (chunk) => process.stdout.write(chunk),
+ *   maxRetries: 2,
+ * });
+ *
+ * console.log("\n", txs);
+ * ```
+ */
+export async function runInference(args) {
+    const maxRetries = args.maxRetries ?? 2;
+    const stalled = [];
+    for (let attempt = 1; attempt <= maxRetries + 1; attempt++) {
+        try {
+            const result = await runOneAttempt(args, attempt);
+            return { ...result, stalled };
+        }
+        catch (err) {
+            if (err instanceof StalledWorkerError && attempt <= maxRetries) {
+                stalled.push({ jobId: err.jobId, worker: err.worker, submitTx: err.submitTx });
+                continue;
+            }
+            throw err;
+        }
+    }
+    // Unreachable - the loop either returns or throws.
+    throw new StalledWorkerError({ jobId: 0n, worker: "0x0000000000000000000000000000000000000000", submitTx: "0x", feeLcai: 0 });
+}
+/** Re-export the typed errors at this layer so a single import covers everything. */
+export { StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker } from "./errors.js";

package/package.json

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