lightnode-sdk 0.3.1 → 0.4.0

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { LightNode, modelStatsCsv, workerStatsCsv, workerJobsCsv } from "./index.js";
+import { addInference, addAnalyticsDashboard, addNftMint, addChat } from "./add.js";
 function flag(name) {
     const i = process.argv.indexOf(name);
     return i >= 0 ? process.argv[i + 1] : undefined;
@@ -16,14 +17,22 @@ const lcai = (wei) => (wei ? Number(BigInt(wei)) / 1e18 : 0);
 const rate = (r) => (r == null ? "-" : `${Math.round(r * 100)}%`);
 const HELP = `lightnode <command> [--net mainnet|testnet]
 
-  network              network summary (workers, jobs, models, earnings)
-  models               registered models + per-job fee
-  worker <addr>        a worker: on-chain registration + recent jobs
-  jobs <addr> [--csv]  one worker's job history (table or CSV)
-  registered <addr>    true | false | null (read from chain events)
-  fee [model]          on-chain inference fee (default llama3-8b)
-  analytics [--csv]    per-model performance (completion, p50/p95, incomplete)
-  reliability [--csv]  per-worker reliability, busiest first`;
+  network                  network summary (workers, jobs, models, earnings)
+  models                   registered models + per-job fee
+  worker <addr>            a worker: on-chain registration + recent jobs
+  jobs <addr> [--csv]      one worker's job history (table or CSV)
+  registered <addr>        true | false | null (read from chain events)
+  fee [model]              on-chain inference fee (default llama3-8b)
+  analytics [--csv]        per-model performance (completion, p50/p95, incomplete)
+  reliability [--csv]      per-worker reliability, busiest first
+
+  add inference                   end-to-end encrypted inference route/script
+  add chat                        chat-style UI with conversation history
+  add analytics-dashboard         read-only network + worker analytics page
+  add nft-mint-with-inference     AI-generated NFT metadata (provenance on-chain)
+                                  (all add commands: [--template auto|nextjs-api|hono|node] [--force])
+
+To scaffold a new project instead, run: npm create lightnode-app my-app`;
 async function main() {
     const ln = new LightNode(net);
     switch (cmd) {
@@ -89,6 +98,76 @@ async function main() {
             }
             break;
         }
+        case "add": {
+            const sub = positionals[1];
+            const template = flag("--template") ?? "auto";
+            const force = process.argv.includes("--force");
+            const network = (net === "mainnet" ? "mainnet" : "testnet");
+            const known = ["inference", "chat", "analytics-dashboard", "nft-mint-with-inference"];
+            if (!known.includes(sub ?? "")) {
+                die(`usage: lightnode add <${known.join("|")}> [--template auto|nextjs-api|hono|node] [--net testnet|mainnet] [--force]`);
+            }
+            const result = sub === "analytics-dashboard"
+                ? addAnalyticsDashboard({ template, network, force })
+                : sub === "nft-mint-with-inference"
+                    ? addNftMint({ template, network, force })
+                    : sub === "chat"
+                        ? addChat({ template, network, force })
+                        : addInference({ template, network, force });
+            console.log(`▶ add ${sub} (${result.template} template, default network ${result.network})`);
+            for (const f of result.written) {
+                if (f.skipped)
+                    console.log(`  ⤴ ${f.path} (skipped - ${f.reason})`);
+                else
+                    console.log(`  ✓ ${f.path}`);
+            }
+            const anyWritten = result.written.some((f) => !f.skipped);
+            if (!anyWritten) {
+                console.log("\nNothing to do - all target files already exist. Pass --force to overwrite.");
+            }
+            else {
+                console.log(`\nNext steps:`);
+                console.log(`  1. ${result.install}`);
+                if (sub === "nft-mint-with-inference" || sub === "inference" || sub === "chat") {
+                    console.log(`  2. cp .env.example .env  (and put a funded ${result.network} PRIVATE_KEY in it)`);
+                    if (sub === "chat" && result.template === "nextjs-api") {
+                        console.log(`  3. Make sure /api/inference is mounted too (run: npx lightnode add inference)`);
+                        console.log(`  4. npm run dev, open /chat`);
+                    }
+                    else if (sub === "chat") {
+                        console.log(`  3. tsx chat-repl.ts  (interactive terminal chat)`);
+                    }
+                    else if (sub === "nft-mint-with-inference" && result.template === "nextjs-api") {
+                        console.log(`  3. Make sure /api/inference is mounted too (run: npx lightnode add inference)`);
+                        console.log(`  4. npm run dev, open /nft-mint`);
+                    }
+                    else if (result.template === "nextjs-api") {
+                        console.log(`  3. npm run dev  (then POST /api/inference)`);
+                    }
+                    else if (result.template === "hono") {
+                        console.log(`  3. wire inferenceHandler into your Hono app, then start it`);
+                    }
+                    else if (sub === "nft-mint-with-inference") {
+                        console.log(`  3. tsx nft-metadata.ts "My NFT" "concept goes here"`);
+                    }
+                    else {
+                        console.log(`  3. tsx lightchain-inference.ts "your prompt"`);
+                    }
+                }
+                else {
+                    // analytics-dashboard - read-only, no private key needed.
+                    if (result.template === "nextjs-api") {
+                        console.log(`  2. npm run dev, open /lightnode-analytics`);
+                    }
+                    else {
+                        console.log(`  2. tsx lightnode-analytics.ts`);
+                    }
+                }
+                console.log(`\nFree testnet LCAI: https://lightfaucet.ai`);
+                console.log(`Builder docs:     https://lightnode.app/build`);
+            }
+            break;
+        }
         default:
             console.log(HELP);
     }

package/dist/errors.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Typed errors thrown by the high-level helpers (`runInference`, gateway calls
+ * inside `prepareSession`, etc.). Catching by class lets callers branch on the
+ * failure mode cleanly instead of regexing message strings.
+ */
+/**
+ * The dispatcher picked a worker and the on-chain `submitJob` succeeded, but the
+ * worker never emitted `JobCompleted` inside the deadline. The protocol times
+ * out and refunds the escrowed fee after its dispute window (a few hours on
+ * testnet, ~24h on mainnet); the consumer does not need to call any timeoutJob.
+ *
+ * Re-running creates a NEW session with a different worker - the assignment is
+ * stochastic, so a retry almost always lands on a healthy one.
+ */
+export declare class StalledWorkerError extends Error {
+    readonly jobId: bigint;
+    readonly worker: `0x${string}`;
+    readonly submitTx: `0x${string}`;
+    readonly feeLcai: number;
+    constructor(args: {
+        jobId: bigint;
+        worker: `0x${string}`;
+        submitTx: `0x${string}`;
+        feeLcai: number;
+    });
+}
+/**
+ * The on-chain `createSession` or `submitJob` reverted with a contract-level
+ * error (NOT a "wallet too poor for gas" error, which surfaces as a viem error
+ * before the tx broadcasts). Surfaces the function name and tx hash so the
+ * caller can inspect on the explorer.
+ */
+export declare class OnChainRevertError extends Error {
+    readonly fn: "createSession" | "submitJob";
+    readonly tx: `0x${string}`;
+    constructor(fn: "createSession" | "submitJob", tx: `0x${string}`);
+}
+/**
+ * The relay token endpoint never returned a usable token inside the poll window.
+ * Usually means the gateway dispatcher couldn't finalise the session - rare in
+ * practice. Re-running creates a fresh session.
+ */
+export declare class RelayTokenTimeoutError extends Error {
+    constructor();
+}
+/**
+ * Authentication or authorisation issue with the consumer gateway - the caller
+ * passed a bad/expired JWT, or the upstream rejected the SIWE handshake.
+ */
+export declare class GatewayAuthError extends Error {
+    readonly status: number;
+    constructor(status: number, body: string);
+}
+/** Convenience predicate so callers don't need `instanceof` if they don't want it. */
+export declare function isStalledWorker(e: unknown): e is StalledWorkerError;

package/dist/errors.js

@@ -0,0 +1,64 @@
+/**
+ * Typed errors thrown by the high-level helpers (`runInference`, gateway calls
+ * inside `prepareSession`, etc.). Catching by class lets callers branch on the
+ * failure mode cleanly instead of regexing message strings.
+ */
+/**
+ * The dispatcher picked a worker and the on-chain `submitJob` succeeded, but the
+ * worker never emitted `JobCompleted` inside the deadline. The protocol times
+ * out and refunds the escrowed fee after its dispute window (a few hours on
+ * testnet, ~24h on mainnet); the consumer does not need to call any timeoutJob.
+ *
+ * Re-running creates a NEW session with a different worker - the assignment is
+ * stochastic, so a retry almost always lands on a healthy one.
+ */
+export class StalledWorkerError extends Error {
+    constructor(args) {
+        super(`worker stalled (jobId=${args.jobId} worker=${args.worker}): no JobCompleted inside the deadline. The protocol will refund the ${args.feeLcai} LCAI fee after the dispute window.`);
+        this.name = "StalledWorkerError";
+        this.jobId = args.jobId;
+        this.worker = args.worker;
+        this.submitTx = args.submitTx;
+        this.feeLcai = args.feeLcai;
+    }
+}
+/**
+ * The on-chain `createSession` or `submitJob` reverted with a contract-level
+ * error (NOT a "wallet too poor for gas" error, which surfaces as a viem error
+ * before the tx broadcasts). Surfaces the function name and tx hash so the
+ * caller can inspect on the explorer.
+ */
+export class OnChainRevertError extends Error {
+    constructor(fn, tx) {
+        super(`${fn} reverted on-chain (tx=${tx})`);
+        this.name = "OnChainRevertError";
+        this.fn = fn;
+        this.tx = tx;
+    }
+}
+/**
+ * The relay token endpoint never returned a usable token inside the poll window.
+ * Usually means the gateway dispatcher couldn't finalise the session - rare in
+ * practice. Re-running creates a fresh session.
+ */
+export class RelayTokenTimeoutError extends Error {
+    constructor() {
+        super("the gateway never issued a relay token for this session (poll timed out)");
+        this.name = "RelayTokenTimeoutError";
+    }
+}
+/**
+ * Authentication or authorisation issue with the consumer gateway - the caller
+ * passed a bad/expired JWT, or the upstream rejected the SIWE handshake.
+ */
+export class GatewayAuthError extends Error {
+    constructor(status, body) {
+        super(`gateway auth failed (${status}): ${body.slice(0, 200)}`);
+        this.name = "GatewayAuthError";
+        this.status = status;
+    }
+}
+/** Convenience predicate so callers don't need `instanceof` if they don't want it. */
+export function isStalledWorker(e) {
+    return e instanceof StalledWorkerError;
+}

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 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 } from "./inference.js";
+import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference } from "./inference.js";
+import { StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker } from "./errors.js";
 import { GatewayClient, GatewayHttpError } from "./gateway.js";
 import * as crypto from "./crypto.js";
 import type { NetworkId, NetworkConfig, Worker, Job, ModelInfo, NetworkStats, ModelStat, WorkerStat, NetworkAnalytics } from "./types.js";
@@ -59,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, };
+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 type { BearerSource, GatewayClientOptions, SelectSessionResult, PrepareSessionResult, UploadBlobResult, SessionTokenResult } from "./gateway.js";
-export type { SessionPreparation } from "./inference.js";
+export type { SessionPreparation, RunInferenceArgs, RunInferenceResult } from "./inference.js";
 export type { NetworkId, NetworkConfig, Worker, Job, ModelInfo, NetworkStats, ModelStat, WorkerStat, NetworkAnalytics };

package/dist/index.js

@@ -2,7 +2,8 @@ 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, } from "./inference.js";
+import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, } from "./inference.js";
+import { StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, } from "./errors.js";
 import { GatewayClient, GatewayHttpError } from "./gateway.js";
 import * as crypto from "./crypto.js";
 /**
@@ -91,4 +92,6 @@ export class LightNode {
 }
 export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, 
 // v0.3 inference-submit surface (BETA - see README "Submitting inference").
-GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, };
+GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, 
+// v0.4 high-level orchestrator: one call, full flow.
+runInference, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, };

package/dist/inference.d.ts

@@ -94,3 +94,133 @@ export declare function decryptResponse(sessionKey: Uint8Array, ciphertext: Uint
 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 };
+interface MinimalWalletClient {
+    writeContract: (args: {
+        address: `0x${string}`;
+        abi: readonly unknown[];
+        functionName: string;
+        args: readonly unknown[];
+        value?: bigint;
+        gas?: bigint;
+    }) => Promise<`0x${string}`>;
+}
+interface MinimalPublicClient {
+    waitForTransactionReceipt: (args: {
+        hash: `0x${string}`;
+    }) => Promise<{
+        status: "success" | "reverted";
+        blockHash: `0x${string}`;
+        blockNumber: bigint;
+    }>;
+    getLogs: (args: {
+        address: `0x${string}`;
+        event?: unknown;
+        args?: Record<string, unknown>;
+        fromBlock?: bigint;
+        toBlock?: bigint | "latest";
+        blockHash?: `0x${string}`;
+    }) => Promise<Array<{
+        transactionHash: `0x${string}`;
+        blockNumber: bigint;
+        data: `0x${string}`;
+        topics: `0x${string}`[];
+        args?: Record<string, unknown>;
+    }>>;
+}
+interface MinimalWebSocket {
+    binaryType?: string;
+    close: () => void;
+    addEventListener?: (type: "message" | "open" | "error" | "close", listener: (ev: {
+        data?: unknown;
+    }) => void, options?: {
+        once?: boolean;
+    }) => void;
+    on?: (type: "message" | "open" | "error" | "close", listener: (data?: unknown) => void) => void;
+    once?: (type: "open" | "error" | "close", listener: (data?: unknown) => void) => void;
+}
+type WebSocketCtor = new (url: string) => MinimalWebSocket;
+export interface RunInferenceArgs {
+    /** The plaintext prompt to send. UTF-8 encoded before encryption. */
+    prompt: string;
+    /** Authenticated GatewayClient (with bearer JWT). */
+    gateway: GatewayClient;
+    /** viem WalletClient used to sign createSession + submitJob. */
+    wallet: MinimalWalletClient;
+    /** viem PublicClient used for receipts + log queries. */
+    publicClient: MinimalPublicClient;
+    /** The target NetworkConfig (typically `new LightNode("testnet").network`). */
+    network: NetworkConfig;
+    /** 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 90s. */
+    jobCompletedTimeoutMs?: number;
+    /**
+     * WebSocket constructor. In a browser, omit and `globalThis.WebSocket` is
+     * used. In Node, pass `WS` from the `ws` package.
+     */
+    WebSocket?: WebSocketCtor;
+    /**
+     * Override the relay URL (defaults to `wss://relay.<network>.lightchain.ai/ws`).
+     * Useful for tests / mirrors.
+     */
+    relayUrl?: string;
+}
+export interface RunInferenceResult {
+    /** The decrypted, fully-assembled model answer. */
+    answer: string;
+    /** The three on-chain transactions in the chain of proof. */
+    txs: {
+        createSession: `0x${string}`;
+        submitJob: `0x${string}`;
+        jobCompleted: `0x${string}`;
+    };
+    /** The dispatcher-assigned worker that produced this response. */
+    worker: `0x${string}`;
+    sessionId: bigint;
+    jobId: bigint;
+    /** How many attempts were paid for (including the successful one). */
+    attempts: number;
+    /** Any prior attempts whose workers stalled (their fees are refunded by the protocol). */
+    stalled: Array<{
+        jobId: bigint;
+        worker: `0x${string}`;
+        submitTx: `0x${string}`;
+    }>;
+}
+/**
+ * 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 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";