lightnode-sdk 0.7.8 → 0.7.10

package/dist/auth.d.ts

@@ -0,0 +1,106 @@
+/**
+ * SIWE sign-in against LightChain's consumer-api. The gateway accepts the
+ * JWT minted here as its `Authorization: Bearer <token>` header, so this
+ * unlocks every protected gateway endpoint (selectSession, prepareSession,
+ * uploadBlob, getSessionToken).
+ *
+ * Reverse-engineered from lightchain-protocol/lcai-chat-v2 (the official
+ * chat reference app). The same two endpoints work on mainnet and testnet
+ * - only the host differs (see {@link NetworkConfig.consumerApi}).
+ *
+ *   1. `GET  /api/auth/challenge?address=0x...`
+ *        -> { nonce: string, message: string }
+ *      The server pre-builds the SIWE message; clients sign it verbatim.
+ *
+ *   2. `POST /api/auth/verify` body { message, signature }
+ *        -> { success, address, token, user }
+ *      `token` is the JWT bearer for the gateway.
+ *
+ * Returns a {@link SiweSession} that the SDK's GatewayClient consumes as
+ * its `bearer` source. The session also exposes `expiresAt` so consumers
+ * can refresh proactively.
+ */
+import type { NetworkId, NetworkConfig } from "./types.js";
+/**
+ * Minimal subset of viem's `WalletClient` we need to sign the SIWE
+ * message. Accepts viem's `WalletClient`, wagmi's `useWalletClient().data`,
+ * or any structurally compatible object with `account.address` and
+ * `signMessage`.
+ */
+export interface SiweWalletClient {
+    account?: {
+        address?: `0x${string}`;
+    };
+    signMessage(args: {
+        account: `0x${string}` | {
+            address: `0x${string}`;
+        };
+        message: string;
+    }): Promise<`0x${string}`>;
+}
+export interface SiweChallenge {
+    nonce: string;
+    message: string;
+}
+export interface SiweVerifyResult {
+    success: boolean;
+    address: `0x${string}`;
+    token: string;
+    user?: {
+        id: string;
+        username?: string | null;
+        walletAddress: `0x${string}`;
+        type: string;
+    };
+}
+export interface SiweSession {
+    /** ES256K JWT bearer accepted by the worker-gateway. */
+    token: string;
+    /** Wallet that signed the message. */
+    address: `0x${string}`;
+    /** Network the session is bound to. */
+    network: NetworkId;
+    /** SIWE message expiry as a unix-ms timestamp (null when not parseable). */
+    expiresAt: number | null;
+    /**
+     * Drop-in `BearerSource` for `new GatewayClient({ bearer })`. Returns
+     * the same JWT for every call; refresh by calling {@link siweSignIn}
+     * again before {@link expiresAt} elapses.
+     */
+    bearer: () => string;
+}
+/**
+ * Fetch a SIWE challenge for `address` from the network's consumer-api.
+ * The returned `message` is the canonical SIWE string the wallet must
+ * sign verbatim - do NOT reformat or strip whitespace.
+ */
+export declare function siweChallenge(network: NetworkId | NetworkConfig, address: `0x${string}`, opts?: {
+    signal?: AbortSignal;
+}): Promise<SiweChallenge>;
+/**
+ * Verify a signed SIWE message and mint a JWT bearer.
+ */
+export declare function siweVerify(network: NetworkId | NetworkConfig, args: {
+    message: string;
+    signature: `0x${string}`;
+}, opts?: {
+    signal?: AbortSignal;
+}): Promise<SiweVerifyResult>;
+/**
+ * End-to-end SIWE sign-in: challenge -> sign -> verify -> JWT.
+ *
+ * ```ts
+ * import { siweSignIn, GatewayClient } from "lightnode-sdk";
+ * // browser: walletClient from wagmi's useWalletClient().data
+ * const session = await siweSignIn(walletClient, "testnet");
+ * const gateway = new GatewayClient({ network: "testnet", bearer: session.bearer });
+ * // ... use the gateway normally (runInference, selectSession, etc.)
+ * ```
+ *
+ * Pass `address` explicitly when the wallet client cannot expose its own
+ * account (some viem clients are intentionally accountless).
+ */
+export declare function siweSignIn(walletClient: SiweWalletClient, network: NetworkId | NetworkConfig, opts?: {
+    address?: `0x${string}`;
+    signal?: AbortSignal;
+}): Promise<SiweSession>;

package/dist/auth.js

@@ -0,0 +1,144 @@
+/**
+ * SIWE sign-in against LightChain's consumer-api. The gateway accepts the
+ * JWT minted here as its `Authorization: Bearer <token>` header, so this
+ * unlocks every protected gateway endpoint (selectSession, prepareSession,
+ * uploadBlob, getSessionToken).
+ *
+ * Reverse-engineered from lightchain-protocol/lcai-chat-v2 (the official
+ * chat reference app). The same two endpoints work on mainnet and testnet
+ * - only the host differs (see {@link NetworkConfig.consumerApi}).
+ *
+ *   1. `GET  /api/auth/challenge?address=0x...`
+ *        -> { nonce: string, message: string }
+ *      The server pre-builds the SIWE message; clients sign it verbatim.
+ *
+ *   2. `POST /api/auth/verify` body { message, signature }
+ *        -> { success, address, token, user }
+ *      `token` is the JWT bearer for the gateway.
+ *
+ * Returns a {@link SiweSession} that the SDK's GatewayClient consumes as
+ * its `bearer` source. The session also exposes `expiresAt` so consumers
+ * can refresh proactively.
+ */
+import { NETWORKS } from "./networks.js";
+const REQUEST_TIMEOUT_MS = 15000;
+function resolveNetwork(network) {
+    if (typeof network === "string") {
+        const cfg = NETWORKS[network];
+        if (!cfg)
+            throw new Error(`siweSignIn: unknown network "${network}"`);
+        return cfg;
+    }
+    return network;
+}
+async function httpJson(url, init) {
+    const ctrl = new AbortController();
+    const onAbort = () => ctrl.abort();
+    init.signal?.addEventListener("abort", onAbort);
+    const timer = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
+    try {
+        const res = await fetch(url, {
+            method: init.method,
+            headers: { Accept: "application/json", ...(init.body ? { "content-type": "application/json" } : {}) },
+            body: init.body ? JSON.stringify(init.body) : undefined,
+            signal: ctrl.signal,
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            // Surface the server-side validation message when present.
+            const detail = text.length < 400 ? text : `${text.slice(0, 380)}...`;
+            throw new Error(`siwe ${url}: ${res.status} ${detail}`);
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new Error(`siwe ${url}: non-JSON response (${text.slice(0, 120)})`);
+        }
+    }
+    finally {
+        clearTimeout(timer);
+        init.signal?.removeEventListener("abort", onAbort);
+    }
+}
+/**
+ * Fetch a SIWE challenge for `address` from the network's consumer-api.
+ * The returned `message` is the canonical SIWE string the wallet must
+ * sign verbatim - do NOT reformat or strip whitespace.
+ */
+export async function siweChallenge(network, address, opts = {}) {
+    const cfg = resolveNetwork(network);
+    if (!cfg.consumerApi) {
+        throw new Error(`siweChallenge: network "${cfg.id}" has no consumerApi configured`);
+    }
+    const url = `${cfg.consumerApi.replace(/\/+$/, "")}/api/auth/challenge?address=${address}`;
+    return httpJson(url, { method: "GET", signal: opts.signal });
+}
+/**
+ * Verify a signed SIWE message and mint a JWT bearer.
+ */
+export async function siweVerify(network, args, opts = {}) {
+    const cfg = resolveNetwork(network);
+    if (!cfg.consumerApi) {
+        throw new Error(`siweVerify: network "${cfg.id}" has no consumerApi configured`);
+    }
+    const url = `${cfg.consumerApi.replace(/\/+$/, "")}/api/auth/verify`;
+    const out = await httpJson(url, {
+        method: "POST",
+        body: { message: args.message, signature: args.signature },
+        signal: opts.signal,
+    });
+    if (!out.success || !out.token) {
+        throw new Error("siweVerify: gateway returned success=false or missing token");
+    }
+    return out;
+}
+/**
+ * Extract a SIWE message's `Expiration Time` (ISO-8601) and convert to a
+ * unix-ms timestamp. Best-effort: returns null if the field is absent or
+ * unparseable.
+ */
+function parseExpiry(message) {
+    const m = message.match(/Expiration Time:\s*(\S+)/);
+    if (!m)
+        return null;
+    const t = Date.parse(m[1]);
+    return Number.isFinite(t) ? t : null;
+}
+/**
+ * End-to-end SIWE sign-in: challenge -> sign -> verify -> JWT.
+ *
+ * ```ts
+ * import { siweSignIn, GatewayClient } from "lightnode-sdk";
+ * // browser: walletClient from wagmi's useWalletClient().data
+ * const session = await siweSignIn(walletClient, "testnet");
+ * const gateway = new GatewayClient({ network: "testnet", bearer: session.bearer });
+ * // ... use the gateway normally (runInference, selectSession, etc.)
+ * ```
+ *
+ * Pass `address` explicitly when the wallet client cannot expose its own
+ * account (some viem clients are intentionally accountless).
+ */
+export async function siweSignIn(walletClient, network, opts = {}) {
+    const cfg = resolveNetwork(network);
+    const address = opts.address ?? walletClient.account?.address;
+    if (!address) {
+        throw new Error("siweSignIn: walletClient has no account; pass `address` explicitly");
+    }
+    const { message } = await siweChallenge(cfg, address, { signal: opts.signal });
+    // viem's signMessage requires `account` even when one is set on the
+    // client; passing it explicitly works with both wagmi and bare viem.
+    const signature = await walletClient.signMessage({
+        account: walletClient.account?.address ?? address,
+        message,
+    });
+    const verified = await siweVerify(cfg, { message, signature }, { signal: opts.signal });
+    const token = verified.token;
+    return {
+        token,
+        address: verified.address ?? address,
+        network: cfg.id,
+        expiresAt: parseExpiry(message),
+        bearer: () => token,
+    };
+}

package/dist/index.d.ts

@@ -12,6 +12,7 @@ import { DAO, DAO_ADDRESSES, ProposalState, PROPOSAL_STATE_LABEL, VoteSupport, G
 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 { siweSignIn, siweChallenge, siweVerify } from "./auth.js";
 import * as crypto from "./crypto.js";
 import type { NetworkId, NetworkConfig, Worker, Job, JobTransactions, ModelInfo, WorkerModel, ServedModel, NetworkStats, ModelStat, WorkerStat, NetworkAnalytics } from "./types.js";
 /**
@@ -133,8 +134,8 @@ 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.7.8";
-export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, resolveJobTransactions, fetchWorkerModels, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, runInference, runInferenceWithKey, runInferenceStream, Conversation, chat, runInferenceBatch, Agent, parseAgentOutput, 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, WorkerOperator, WORKER_REGISTRY_ABI, JOB_REGISTRY_OPERATOR_ABI, AI_CONFIG_ABI, JOB_STATE, decodeWorkerError, WorkerOpError, isWorkerOpError, };
+export declare const SDK_VERSION = "0.7.10";
+export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, resolveJobTransactions, siweSignIn, siweChallenge, siweVerify, fetchWorkerModels, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, runInference, runInferenceWithKey, runInferenceStream, Conversation, chat, runInferenceBatch, Agent, parseAgentOutput, 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, WorkerOperator, WORKER_REGISTRY_ABI, JOB_REGISTRY_OPERATOR_ABI, AI_CONFIG_ABI, JOB_STATE, decodeWorkerError, WorkerOpError, isWorkerOpError, };
 export type { BearerSource, GatewayClientOptions, SelectSessionResult, PrepareSessionResult, UploadBlobResult, SessionTokenResult } from "./gateway.js";
 export type { SessionPreparation, RunInferenceArgs, RunInferenceResult, RunInferenceWithKeyArgs, RunInferenceStreamResult } from "./inference.js";
 export type { ChatRole, ChatMessage, ConversationOptions, ConversationSendResult } from "./chat.js";
@@ -146,3 +147,4 @@ export type { DaoChain, DaoAddresses, ProposalSummary, ProposalRow, DaoConfig }
 export type { BaseModel, ModelVariant, AccessTier, AccessPolicy, Benchmark, OnchainModelRegistryOptions } from "./onchain-models.js";
 export type { MinimalWalletClient, MinimalPublicClient, WorkerOperatorOpts, WorkerProtocolConfig, WorkerStatus, DeregisterReadiness, StuckJob, EarningsBreakdown, OnchainJob, JobState, DecodedWorkerError, } from "./worker-operator.js";
 export type { NetworkId, NetworkConfig, Worker, Job, JobTransactions, ModelInfo, WorkerModel, ServedModel, NetworkStats, ModelStat, WorkerStat, NetworkAnalytics };
+export type { SiweWalletClient, SiweChallenge, SiweVerifyResult, SiweSession } from "./auth.js";

package/dist/index.js

@@ -13,6 +13,7 @@ import { DAO, DAO_ADDRESSES, ProposalState, PROPOSAL_STATE_LABEL, VoteSupport, G
 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 { siweSignIn, siweChallenge, siweVerify } from "./auth.js";
 import * as crypto from "./crypto.js";
 /**
  * Read-only client for a LightChain AI network. Pure reads from the public indexer
@@ -212,11 +213,15 @@ 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.7.8";
+export const SDK_VERSION = "0.7.10";
 export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, 
 // v0.7.3 per-job transaction-hash resolver (lifts the upstream
 // subgraph's "block-only" Job entity to a deep-linkable Job + tx pair).
 resolveJobTransactions, 
+// v0.7.10 SIWE sign-in against the consumer-api: returns a JWT bearer
+// the worker-gateway accepts. End-to-end wallet-signed inference with
+// no shared demo-wallet state.
+siweSignIn, siweChallenge, siweVerify, 
 // v0.7.4 per-worker model-registration list (the authoritative "what is
 // this worker offering to serve" signal, not derived from past jobs).
 fetchWorkerModels, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, 

package/dist/inference.js

@@ -78,25 +78,35 @@ export async function prepareSession(gateway, modelTag) {
     // The gateway returns 409 selection_mismatch when a NEWER selectSession()
     // for the same wallet supersedes ours between the select and the prepare.
     // The error message is literally "re-run POST /api/sessions/select", so we
-    // do exactly that: rebuild from a fresh selection. The cap stops a busy
-    // pool of callers from looping forever - 4 attempts at 250ms / 750ms /
-    // 1500ms covers every churn pattern we have seen.
-    const MAX_ATTEMPTS = 4;
-    const BACKOFFS_MS = [0, 250, 750, 1500];
+    // do exactly that: rebuild from a fresh selection. Backoff spans several
+    // seconds because the gateway's selection TTL can be in that range - quick
+    // retries inside that window just hit the same stuck state. Random jitter
+    // keeps two concurrent callers from synchronising on identical schedules.
+    const MAX_ATTEMPTS = 6;
+    const BACKOFFS_MS = [0, 500, 1500, 4000, 9000, 18000];
+    const jitter = (ms) => ms + Math.floor(Math.random() * 250);
     let lastErr = null;
+    const isSelectionMismatch = (e) => {
+        const msg = e instanceof Error ? e.message : String(e);
+        return /selection_mismatch|selection was superseded|409/.test(msg);
+    };
     for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
         if (attempt > 0)
-            await new Promise((r) => setTimeout(r, BACKOFFS_MS[attempt]));
-        const selected = await gateway.selectSession(id);
-        const sessionKey = await generateSessionKey();
-        // Workers' pubkeys arrive as base64; disputer's as hex - decodePublicKey
-        // accepts either.
-        const workerPub = await importPublicKey(decodePublicKey(selected.workerEncryptionKey));
-        const encWorker = await encryptSessionKey(sessionKey, workerPub);
-        const encDisputer = selected.disputerEncryptionKey
-            ? await encryptSessionKey(sessionKey, await importPublicKey(decodePublicKey(selected.disputerEncryptionKey)))
-            : new Uint8Array(0);
+            await new Promise((r) => setTimeout(r, jitter(BACKOFFS_MS[attempt])));
         try {
+            // Wrap BOTH gateway calls. selectSession itself can 409 if a newer
+            // call has already superseded ours by the time the gateway processes
+            // it. prepareSession 409s when the same happens between select and
+            // prepare. The whole select -> prepare flow is one atomic unit.
+            const selected = await gateway.selectSession(id);
+            const sessionKey = await generateSessionKey();
+            // Workers' pubkeys arrive as base64; disputer's as hex - decodePublicKey
+            // accepts either.
+            const workerPub = await importPublicKey(decodePublicKey(selected.workerEncryptionKey));
+            const encWorker = await encryptSessionKey(sessionKey, workerPub);
+            const encDisputer = selected.disputerEncryptionKey
+                ? await encryptSessionKey(sessionKey, await importPublicKey(decodePublicKey(selected.disputerEncryptionKey)))
+                : new Uint8Array(0);
             const prepared = await gateway.prepareSession({
                 modelId: id,
                 encWorkerKey: bytesToBase64(encWorker),
@@ -117,8 +127,7 @@ export async function prepareSession(gateway, modelTag) {
         }
         catch (e) {
             lastErr = e;
-            const msg = e instanceof Error ? e.message : String(e);
-            if (!/selection_mismatch|selection was superseded|409/.test(msg))
+            if (!isSelectionMismatch(e))
                 throw e;
             // else loop: a newer select stole this session, try again from select.
         }

package/dist/networks.js

@@ -12,6 +12,7 @@ export const NETWORKS = {
         rpc: "https://rpc.mainnet.lightchain.ai",
         explorer: "https://mainnet.lightscan.app",
         workerGateway: "https://worker-gateway.mainnet.lightchain.ai",
+        consumerApi: "https://chat-api.mainnet.lightchain.ai",
         subgraph: "https://workers-api.mainnet.lightchain.ai/graphql",
         workerRegistry: "0x0000000000000000000000000000000000001002",
         aiConfig: "0x24D11533C354092ed6E18b964257819cE78Ce77D",
@@ -31,6 +32,7 @@ export const NETWORKS = {
         rpc: "https://rpc.testnet.lightchain.ai",
         explorer: "https://testnet.lightscan.app",
         workerGateway: "https://worker-gateway.testnet.lightchain.ai",
+        consumerApi: "https://chat-api.testnet.lightchain.ai",
         subgraph: "https://workers-api.testnet.lightchain.ai/graphql",
         workerRegistry: "0x0000000000000000000000000000000000001002",
         aiConfig: "0xeCF4Ca5Ba6D97ae586993e170764a1E92231b67e",

package/dist/types.d.ts

@@ -6,6 +6,16 @@ export interface NetworkConfig {
     rpc: string;
     explorer: string;
     workerGateway: string;
+    /**
+     * LightChain consumer-api host (SIWE sign-in + JWT issuance). The worker
+     * gateway accepts the JWT minted here as its Authorization Bearer.
+     *
+     * - `GET  {consumerApi}/api/auth/challenge?address=0x...` -> { nonce, message }
+     * - `POST {consumerApi}/api/auth/verify`  body { message, signature } -> { token, ... }
+     *
+     * Wrapped end-to-end by {@link siweSignIn}.
+     */
+    consumerApi: string;
     subgraph: string;
     /** Genesis predeploy, same address on both networks. */
     workerRegistry: string;

package/package.json

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