lightnode-sdk 0.1.0 → 0.3.1

package/README.md

@@ -1,10 +1,14 @@
 # lightnode-sdk
 
-Read-only TypeScript client for **LightChain AI**: workers, jobs, models, on-chain
-registration, and per-model network analytics. Pure reads from the public indexer and
-the chain. No keys, no writes, no native dependencies beyond `viem`.
+TypeScript client for **LightChain AI**: read workers, jobs, models, on-chain
+registration and per-model analytics, **and run encrypted inference end to end**
+(prepare session, submit prompt, decrypt the streamed response). The SDK is
+non-custodial - it never holds your private key; on-chain calls are signed by
+your wallet via viem. Single peer dep: `viem`.
 
 > Independent, community-built. Not an official LightChain package.
+> Live-verified end-to-end on both **mainnet** (chain 9200) and **testnet** (chain 8200)
+> with real LCAI - example transactions in the "Submitting inference" section below.
 
 ## Install
 
@@ -37,6 +41,10 @@ const rollup = await ln.getNetworkAnalytics(); // overall completion / jobs / in
 // Inference cost
 const fee = await ln.estimateFee("llama3-8b"); // whole LCAI per job (on-chain calculateJobFee)
 const id = ln.modelId("llama3-8b");            // keccak256 model id
+
+// CSV export (same exporters the LightNode dashboard uses)
+import { workerJobsCsv, modelStatsCsv, workerStatsCsv } from "lightnode-sdk";
+const csv = workerJobsCsv(await ln.getWorkerJobs("0x6781...6e0f", 100));
 ```
 
 ## API
@@ -57,34 +65,114 @@ const id = ln.modelId("llama3-8b");            // keccak256 model id
 | `modelId(tag)` | `0x${string}` |
 
 Also exported: `NETWORKS`, `WORKER_REGISTRY`, `REGISTRY_TOPICS`, `aggregateModelStats`,
-`aggregateWorkerStats`, `networkAnalytics`, `JOB_REGISTRY_CONSUMER_ABI`,
-`consumerGatewayUrl`, `fromWei`, and all the types.
+`aggregateWorkerStats`, `networkAnalytics`, `modelStatsCsv`, `workerStatsCsv`,
+`workerJobsCsv`, `JOB_REGISTRY_CONSUMER_ABI`, `consumerGatewayUrl`, `fromWei`, and all
+the types.
 
 ## CLI
 
 ```bash
-npx lightnode network --net testnet     # network summary
-npx lightnode models                    # registered models + fees
-npx lightnode worker 0x6781…6e0f        # one worker (on-chain + recent jobs)
-npx lightnode registered 0x6781…6e0f    # true | false | null
-npx lightnode fee llama3-8b             # on-chain job fee
-npx lightnode analytics --csv           # per-model performance (CSV)
-npx lightnode reliability               # per-worker reliability
+npx lightnode network --net testnet       # network summary
+npx lightnode models                      # registered models + fees
+npx lightnode worker 0x6781…6e0f          # one worker (on-chain + recent jobs)
+npx lightnode jobs 0x6781…6e0f --csv      # one worker's job history (table or CSV)
+npx lightnode registered 0x6781…6e0f      # true | false | null
+npx lightnode fee llama3-8b               # on-chain job fee
+npx lightnode analytics --csv             # per-model performance (CSV)
+npx lightnode reliability --csv           # per-worker reliability (CSV)
 ```
 
-## Submitting inference (advanced)
+## Submitting inference
+
+`v0.3+` ships the encrypted inference-submit flow end to end. Wire-compatible with
+the reference client [`lcai-chat-v2`](https://github.com/lightchain-protocol/lcai-chat-v2)
+(same ECDH-P256 + AES-256-GCM, same gateway endpoints, same `JobRegistry` calls).
+**Live-verified** with real LCAI on both networks before this release:
+
+| Network | Tx | Decrypted model output (excerpt) |
+| --- | --- | --- |
+| testnet (8200) | createSession `0x77686f3f…ef2bc587` · submitJob `0xba9d48c4…293b2bd96` | "Did you know that the deepest part of the ocean, the Mariana Trench, is so deep that if you were to drop Mount Everest into it, its peak would still be more than 1 mile underwater?!" |
+| mainnet (9200) | createSession `0xf091957f…57d4a6ca` · submitJob `0x6ff44a4a…79846bb89` | "Did you know there is a type of jellyfish called the 'Upside-Down Jellyfish' that actually swims on its back, using its tentacles to catch prey and defend itself from predators?" |
+
+The pieces that talk to the chain (`createSession` / `submitJob`) are signed by
+**your** wallet via viem; the SDK only prepares the data, does the crypto, and
+talks to the consumer gateway.
+
+### Auth (your responsibility)
+
+The gateway requires a bearer JWT obtained via the consumer-api's SIWE sign-in.
+The SDK does **not** bundle SIWE - hand the SDK either a fixed token or a
+`() => Promise<string>` thunk that refreshes it on demand.
+
+### End-to-end (sketch)
+
+```ts
+import {
+  LightNode,
+  prepareSession,
+  submitPrompt,
+  decryptResponse,
+  JOB_REGISTRY_CONSUMER_ABI,
+} from "lightnode-sdk";
+import { createWalletClient, http, parseAbi } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+
+const ln = new LightNode("testnet");
+const gateway = ln.gateway({ bearer: () => mySiweJwt() });
+
+// 1) Prepare the session: the gateway picks a worker, we wrap a fresh session
+//    key for the worker (and the disputer, if returned) and get the dispatcher
+//    signature authorising createSession.
+const { sessionKey, createSessionArgs } = await prepareSession(gateway, "llama3-8b");
+
+// 2) Call createSession ON-CHAIN with the prepared args. You sign with your
+//    wallet; the SDK ships the ABI but never custodies the key.
+const wallet = createWalletClient({ account: privateKeyToAccount("0x..."), transport: http(ln.network.rpc) });
+const abi = parseAbi(JOB_REGISTRY_CONSUMER_ABI);
+const sessionTx = await wallet.writeContract({
+  address: ln.network.jobRegistry as `0x${string}`,
+  abi,
+  functionName: "createSession",
+  args: [
+    createSessionArgs.modelId,
+    createSessionArgs.worker,
+    createSessionArgs.encWorkerKey,
+    createSessionArgs.encDisputerKey,
+    createSessionArgs.dispatcherSignature,
+    createSessionArgs.expiry,
+  ],
+});
+// Wait for the receipt and pull the sessionId out of the SessionCreated event.
+
+// 3) Encrypt + upload your prompt. Returns the EIP-4844 blob hash.
+const blobHash = await submitPrompt(gateway, sessionKey, "write a haiku about LCAI");
+
+// 4) Submit the job on-chain, paying the fee:
+const feeLcai = await ln.estimateFee("llama3-8b");
+await wallet.writeContract({
+  address: ln.network.jobRegistry as `0x${string}`,
+  abi,
+  functionName: "submitJob",
+  args: [sessionId, blobHash],
+  value: BigInt(Math.round(feeLcai * 1e18)),
+});
+
+// 5) Watch JobCompleted (or read the response blob via the relay), then decrypt:
+const answer = await decryptResponse(sessionKey, responseCiphertextFromRelay);
+```
 
-`estimateFee` + `modelId` + the exported `JOB_REGISTRY_CONSUMER_ABI` give you the
-on-chain primitives. The full submit is a multi-step, encrypted flow and is **not
-bundled** here (it's a large, currently-undocumented protocol surface — shipping it
-half-tested would be worse than pointing you at the verified reference):
+### What's exported (v0.3)
 
-1. `createSession(modelId, worker, encWorkerKey, encDisputerKey, dispatcherSig, expiry)` on the JobRegistry.
-2. ECDH-P256 + AES-256-GCM encrypt the prompt with a session key; upload it as a blob to the consumer gateway (`consumerGatewayUrl(net)`); get the EIP-4844 `blobHash`.
-3. `submitJob(sessionId, blobHash)` paying `estimateFee(model)` as native value.
-4. Read the result from the relay stream, or watch the `JobCompleted` event / the job's `responseBlobHash`.
+- `prepareSession(gateway, modelTag)` - select + wrap + prepare (steps 1+2).
+- `submitPrompt(gateway, sessionKey, prompt)` - encrypt + upload (step 3).
+- `decryptResponse(sessionKey, ciphertext)` - decrypt the worker's reply (step 5).
+- `GatewayClient` + `consumerGatewayUrl(net)` - typed HTTP client.
+- `crypto.*` - the wire-compatible primitives (`encrypt`, `decrypt`,
+  `encryptSessionKey`, `decryptSessionKey`, `generateEcdhKeyPair`,
+  `generateSessionKey`, hex/base64/utf8 helpers).
+- `JOB_REGISTRY_CONSUMER_ABI` + `estimateJobFee` + `modelId` - on-chain primitives.
 
-Reference implementation: [lightchain-protocol/lcai-chat-v2](https://github.com/lightchain-protocol/lcai-chat-v2) (`lib/protocol/*`). A managed REST alternative (API-key) also exists at `https://chat2.lightchain.ai/api/v1`.
+A managed REST alternative (API-key) also exists at `https://chat2.lightchain.ai/api/v1` for builders who'd rather skip running their own gateway/SIWE auth.
 
 ## Why `isRegistered` reads the chain
 

package/dist/analytics.d.ts

@@ -7,5 +7,11 @@ export declare function classifyJobs(jobs: Job[], nowSec: number): JobBuckets;
 export declare function aggregateModelStats(jobs: Job[], models: ModelInfo[], nowSec?: number): ModelStat[];
 /** Per-worker reliability, busiest first (top `limit`). */
 export declare function aggregateWorkerStats(jobs: Job[], nowSec?: number, limit?: number): WorkerStat[];
+/** Per-model stats as CSV. */
+export declare function modelStatsCsv(stats: ModelStat[]): string;
+/** Per-worker reliability as CSV. */
+export declare function workerStatsCsv(workers: WorkerStat[]): string;
+/** One worker's job history as CSV (one row per job). */
+export declare function workerJobsCsv(jobs: Job[]): string;
 /** Network-wide rollup across all models. */
 export declare function networkAnalytics(stats: ModelStat[]): NetworkAnalytics;

package/dist/analytics.js

@@ -86,6 +86,59 @@ export function aggregateWorkerStats(jobs, nowSec = Math.floor(Date.now() / 1000
         .sort((a, b) => b.total - a.total)
         .slice(0, limit);
 }
+// Shared outcome columns so the per-model and per-worker exports share one shape.
+const STATS_COLUMNS = [
+    "jobs",
+    "success",
+    "incomplete",
+    "timed_out",
+    "stuck",
+    "disputed",
+    "in_flight",
+    "completion_rate_pct",
+    "p50_latency_s",
+    "p95_latency_s",
+    "earnings_lcai",
+];
+function bucketsRow(s) {
+    return [
+        s.total,
+        s.success,
+        s.incomplete,
+        s.timedOut,
+        s.stuck,
+        s.disputed,
+        s.inFlight,
+        s.completionRate != null ? Math.round(s.completionRate * 100) : "",
+        s.p50 ?? "",
+        s.p95 ?? "",
+        s.earnings.toFixed(3),
+    ];
+}
+const toCsv = (rows) => rows.map((r) => r.join(",")).join("\n");
+/** Per-model stats as CSV. */
+export function modelStatsCsv(stats) {
+    return toCsv([["model", ...STATS_COLUMNS], ...stats.map((s) => [s.name, ...bucketsRow(s)])]);
+}
+/** Per-worker reliability as CSV. */
+export function workerStatsCsv(workers) {
+    return toCsv([["worker", ...STATS_COLUMNS], ...workers.map((w) => [w.address, ...bucketsRow(w)])]);
+}
+/** One worker's job history as CSV (one row per job). */
+export function workerJobsCsv(jobs) {
+    const head = ["job_id", "state", "model_id", "processing_s", "worker_share_lcai", "submitted_at", "ack_at", "completed_at"];
+    const rows = jobs.map((j) => [
+        j.id,
+        j.state,
+        j.model_id ?? "",
+        j.ack_at && j.completed_at && j.completed_at >= j.ack_at ? j.completed_at - j.ack_at : "",
+        fromWei(j.worker_share).toFixed(6),
+        j.submitted_at ?? "",
+        j.ack_at ?? "",
+        j.completed_at ?? "",
+    ]);
+    return toCsv([head, ...rows]);
+}
 /** Network-wide rollup across all models. */
 export function networkAnalytics(stats) {
     const sum = (f) => stats.reduce((a, s) => a + f(s), 0);

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { LightNode } from "./index.js";
+import { LightNode, modelStatsCsv, workerStatsCsv, workerJobsCsv } from "./index.js";
 function flag(name) {
     const i = process.argv.indexOf(name);
     return i >= 0 ? process.argv[i + 1] : undefined;
@@ -19,10 +19,11 @@ 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          per-worker reliability, busiest first`;
+  reliability [--csv]  per-worker reliability, busiest first`;
 async function main() {
     const ln = new LightNode(net);
     switch (cmd) {
@@ -42,6 +43,20 @@ async function main() {
             console.log(JSON.stringify({ onchainRegistered: registered, worker: w, recentJobs: jobs.map((j) => ({ id: j.id, state: j.state })) }, null, 2));
             break;
         }
+        case "jobs": {
+            const addr = positionals[1] ?? die("usage: lightnode jobs <address> [--csv] [--net testnet]");
+            const jobs = await ln.getWorkerJobs(addr, 100);
+            if (csv) {
+                console.log(workerJobsCsv(jobs));
+            }
+            else {
+                for (const j of jobs) {
+                    const proc = j.ack_at && j.completed_at && j.completed_at >= j.ack_at ? `${j.completed_at - j.ack_at}s` : "-";
+                    console.log(`#${j.id}\t${j.state}\t${proc}\t${lcai(j.worker_share)} LCAI`);
+                }
+            }
+            break;
+        }
         case "registered": {
             const addr = positionals[1] ?? die("usage: lightnode registered <address>");
             console.log(String(await ln.isRegistered(addr)));
@@ -55,10 +70,7 @@ async function main() {
         case "analytics": {
             const stats = await ln.getModelStats();
             if (csv) {
-                console.log("model,jobs,completion_pct,p50_s,p95_s,incomplete,earnings_lcai");
-                for (const s of stats) {
-                    console.log(`${s.name},${s.total},${s.completionRate != null ? Math.round(s.completionRate * 100) : ""},${s.p50 ?? ""},${s.p95 ?? ""},${s.incomplete},${s.earnings.toFixed(3)}`);
-                }
+                console.log(modelStatsCsv(stats));
             }
             else {
                 for (const s of stats)
@@ -67,8 +79,13 @@ async function main() {
             break;
         }
         case "reliability": {
-            for (const w of await ln.getWorkerStats(1000, 20)) {
-                console.log(`${w.address}\t${w.total}j\t${rate(w.completionRate)}\tp50 ${w.p50 ?? "-"}s\tinc ${w.incomplete}\t${w.earnings.toFixed(3)} LCAI`);
+            const workers = await ln.getWorkerStats(1000, 20);
+            if (csv) {
+                console.log(workerStatsCsv(workers));
+            }
+            else {
+                for (const w of workers)
+                    console.log(`${w.address}\t${w.total}j\t${rate(w.completionRate)}\tp50 ${w.p50 ?? "-"}s\tinc ${w.incomplete}\t${w.earnings.toFixed(3)} LCAI`);
             }
             break;
         }

package/dist/crypto.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Wire-compatible ECDH P-256 + AES-256-GCM helpers for the LightChain AI
+ * inference protocol.
+ *
+ * The format here MUST match the workers' Go implementation byte for byte,
+ * which is what the `lcai-chat-v2` reference client also targets:
+ *   - ECDH P-256 key exchange.
+ *   - Raw shared secret used DIRECTLY as the AES-256 key (no HKDF).
+ *   - AES-GCM ciphertext layout: nonce(12) || ciphertext || tag(16).
+ *   - Encrypted session key layout: ephemeralPub(65) || nonce(12) || ciphertext || tag(16).
+ *
+ * Uses the Web Crypto API exposed via `globalThis.crypto.subtle`, available in
+ * Node 18+ and all modern browsers. No Node-only dependencies; the SDK runs
+ * unchanged in either environment.
+ */
+/** A fresh 32-byte symmetric session key (random, never derived). */
+export declare function generateSessionKey(): Uint8Array;
+/** Fresh ECDH P-256 keypair (extractable; we need to export the public key on the wire). */
+export declare function generateEcdhKeyPair(): Promise<CryptoKeyPair>;
+/** Export an ECDH public key to its raw uncompressed P-256 encoding (65 bytes). */
+export declare function exportPublicKey(key: CryptoKey): Promise<Uint8Array>;
+/** Import a raw uncompressed P-256 public key (65 bytes) into a CryptoKey. */
+export declare function importPublicKey(raw: Uint8Array): Promise<CryptoKey>;
+/**
+ * Derive a 32-byte shared secret from a local ECDH private key and a remote
+ * public key. Returns the raw x-coordinate; deliberately no HKDF, matching the
+ * protocol's `priv.ECDH(remotePub)` output exactly.
+ */
+export declare function deriveSharedSecret(privateKey: CryptoKey, remotePublicKey: CryptoKey): Promise<Uint8Array>;
+/** Encrypt with AES-256-GCM. Output: nonce(12) || ciphertext || tag(16). */
+export declare function encrypt(key: Uint8Array, plaintext: Uint8Array): Promise<Uint8Array>;
+/** Decrypt AES-256-GCM. Input: nonce(12) || ciphertext || tag(16). */
+export declare function decrypt(key: Uint8Array, ciphertext: Uint8Array): Promise<Uint8Array>;
+/**
+ * Wrap (encrypt) a 32-byte session key for delivery to a remote party (e.g. the
+ * worker), using a fresh ephemeral ECDH keypair.
+ *
+ * Output: ephemeralPub(65) || nonce(12) || AES-GCM(sharedSecret, sessionKey)
+ */
+export declare function encryptSessionKey(sessionKey: Uint8Array, remotePublicKey: CryptoKey): Promise<Uint8Array>;
+/** Unwrap a session key encrypted by `encryptSessionKey` using the local ECDH private key. */
+export declare function decryptSessionKey(encWorkerKey: Uint8Array, privateKey: CryptoKey): Promise<Uint8Array>;
+export declare function utf8ToBytes(s: string): Uint8Array;
+export declare function bytesToUtf8(b: Uint8Array): string;
+export declare function bytesToHex(b: Uint8Array): `0x${string}`;
+export declare function hexToBytes(hex: string): Uint8Array;
+export declare function bytesToBase64(b: Uint8Array): string;
+export declare function base64ToBytes(b64: string): Uint8Array;

package/dist/crypto.js

@@ -0,0 +1,148 @@
+/**
+ * Wire-compatible ECDH P-256 + AES-256-GCM helpers for the LightChain AI
+ * inference protocol.
+ *
+ * The format here MUST match the workers' Go implementation byte for byte,
+ * which is what the `lcai-chat-v2` reference client also targets:
+ *   - ECDH P-256 key exchange.
+ *   - Raw shared secret used DIRECTLY as the AES-256 key (no HKDF).
+ *   - AES-GCM ciphertext layout: nonce(12) || ciphertext || tag(16).
+ *   - Encrypted session key layout: ephemeralPub(65) || nonce(12) || ciphertext || tag(16).
+ *
+ * Uses the Web Crypto API exposed via `globalThis.crypto.subtle`, available in
+ * Node 18+ and all modern browsers. No Node-only dependencies; the SDK runs
+ * unchanged in either environment.
+ */
+const AES_KEY_BYTES = 32;
+const GCM_NONCE_BYTES = 12;
+const P256_UNCOMPRESSED_KEY_BYTES = 65;
+const SESSION_KEY_BYTES = 32;
+function subtle() {
+    const c = globalThis.crypto;
+    if (!c?.subtle)
+        throw new Error("Web Crypto unavailable - Node 18+ or a browser is required");
+    return c.subtle;
+}
+function randomBytes(n) {
+    const buf = new Uint8Array(n);
+    globalThis.crypto.getRandomValues(buf);
+    return buf;
+}
+/** A fresh 32-byte symmetric session key (random, never derived). */
+export function generateSessionKey() {
+    return randomBytes(SESSION_KEY_BYTES);
+}
+/** Fresh ECDH P-256 keypair (extractable; we need to export the public key on the wire). */
+export function generateEcdhKeyPair() {
+    return subtle().generateKey({ name: "ECDH", namedCurve: "P-256" }, true, ["deriveBits"]);
+}
+/** Export an ECDH public key to its raw uncompressed P-256 encoding (65 bytes). */
+export async function exportPublicKey(key) {
+    return new Uint8Array(await subtle().exportKey("raw", key));
+}
+/** Import a raw uncompressed P-256 public key (65 bytes) into a CryptoKey. */
+export function importPublicKey(raw) {
+    return subtle().importKey("raw", raw, { name: "ECDH", namedCurve: "P-256" }, true, []);
+}
+/**
+ * Derive a 32-byte shared secret from a local ECDH private key and a remote
+ * public key. Returns the raw x-coordinate; deliberately no HKDF, matching the
+ * protocol's `priv.ECDH(remotePub)` output exactly.
+ */
+export async function deriveSharedSecret(privateKey, remotePublicKey) {
+    return new Uint8Array(await subtle().deriveBits({ name: "ECDH", public: remotePublicKey }, privateKey, 256));
+}
+/** Encrypt with AES-256-GCM. Output: nonce(12) || ciphertext || tag(16). */
+export async function encrypt(key, plaintext) {
+    if (key.length !== AES_KEY_BYTES)
+        throw new Error(`AES key must be ${AES_KEY_BYTES} bytes`);
+    const aesKey = await subtle().importKey("raw", key, "AES-GCM", false, ["encrypt"]);
+    const nonce = randomBytes(GCM_NONCE_BYTES);
+    const ctPlusTag = new Uint8Array(await subtle().encrypt({ name: "AES-GCM", iv: nonce }, aesKey, plaintext));
+    const out = new Uint8Array(GCM_NONCE_BYTES + ctPlusTag.byteLength);
+    out.set(nonce, 0);
+    out.set(ctPlusTag, GCM_NONCE_BYTES);
+    return out;
+}
+/** Decrypt AES-256-GCM. Input: nonce(12) || ciphertext || tag(16). */
+export async function decrypt(key, ciphertext) {
+    if (key.length !== AES_KEY_BYTES)
+        throw new Error(`AES key must be ${AES_KEY_BYTES} bytes`);
+    if (ciphertext.length < GCM_NONCE_BYTES + 16)
+        throw new Error("ciphertext too short");
+    const aesKey = await subtle().importKey("raw", key, "AES-GCM", false, ["decrypt"]);
+    const nonce = ciphertext.slice(0, GCM_NONCE_BYTES);
+    const body = ciphertext.slice(GCM_NONCE_BYTES);
+    return new Uint8Array(await subtle().decrypt({ name: "AES-GCM", iv: nonce }, aesKey, body));
+}
+/**
+ * Wrap (encrypt) a 32-byte session key for delivery to a remote party (e.g. the
+ * worker), using a fresh ephemeral ECDH keypair.
+ *
+ * Output: ephemeralPub(65) || nonce(12) || AES-GCM(sharedSecret, sessionKey)
+ */
+export async function encryptSessionKey(sessionKey, remotePublicKey) {
+    if (sessionKey.length !== SESSION_KEY_BYTES)
+        throw new Error(`session key must be ${SESSION_KEY_BYTES} bytes`);
+    const ephemeral = await generateEcdhKeyPair();
+    const shared = await deriveSharedSecret(ephemeral.privateKey, remotePublicKey);
+    const ct = await encrypt(shared, sessionKey);
+    const pub = await exportPublicKey(ephemeral.publicKey);
+    const out = new Uint8Array(pub.length + ct.length);
+    out.set(pub, 0);
+    out.set(ct, pub.length);
+    return out;
+}
+/** Unwrap a session key encrypted by `encryptSessionKey` using the local ECDH private key. */
+export async function decryptSessionKey(encWorkerKey, privateKey) {
+    if (encWorkerKey.length < P256_UNCOMPRESSED_KEY_BYTES + GCM_NONCE_BYTES + 16) {
+        throw new Error("encrypted session key too short");
+    }
+    const ephemeralPub = await importPublicKey(encWorkerKey.slice(0, P256_UNCOMPRESSED_KEY_BYTES));
+    const ct = encWorkerKey.slice(P256_UNCOMPRESSED_KEY_BYTES);
+    const shared = await deriveSharedSecret(privateKey, ephemeralPub);
+    const sk = await decrypt(shared, ct);
+    if (sk.length !== SESSION_KEY_BYTES)
+        throw new Error(`session key must be ${SESSION_KEY_BYTES} bytes`);
+    return sk;
+}
+// -- text helpers (cross-runtime, no Node Buffer dependency) -----------------
+export function utf8ToBytes(s) {
+    return new TextEncoder().encode(s);
+}
+export function bytesToUtf8(b) {
+    return new TextDecoder().decode(b);
+}
+const HEX = "0123456789abcdef";
+export function bytesToHex(b) {
+    let out = "0x";
+    for (const v of b)
+        out += HEX[v >> 4] + HEX[v & 0xf];
+    return out;
+}
+export function hexToBytes(hex) {
+    const s = hex.startsWith("0x") ? hex.slice(2) : hex;
+    if (s.length % 2 !== 0)
+        throw new Error("hex must be even length");
+    const out = new Uint8Array(s.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(s.slice(i * 2, i * 2 + 2), 16);
+    return out;
+}
+// btoa/atob are globals in Node 18+ and all browsers. Narrow the lookup so
+// strict TS doesn't trip on a missing-on-globalThis interface.
+const g = globalThis;
+export function bytesToBase64(b) {
+    // btoa accepts a binary string; build it from bytes (avoids Node Buffer requirement).
+    let s = "";
+    for (const v of b)
+        s += String.fromCharCode(v);
+    return g.btoa(s);
+}
+export function base64ToBytes(b64) {
+    const s = g.atob(b64);
+    const out = new Uint8Array(s.length);
+    for (let i = 0; i < s.length; i++)
+        out[i] = s.charCodeAt(i);
+    return out;
+}

package/dist/gateway.d.ts

@@ -0,0 +1,97 @@
+/**
+ * HTTP client for the LightChain consumer gateway (a.k.a. chat-api). Exposes
+ * just the endpoints a third-party consumer needs to submit an inference job
+ * and read its result back.
+ *
+ * Auth: the gateway requires a bearer JWT obtained via the consumer-api's SIWE
+ * sign-in flow. The SDK does NOT bundle SIWE; the caller obtains a token (or a
+ * fresh-each-call thunk) by whatever means they prefer and hands it here.
+ */
+import type { NetworkConfig } from "./types.js";
+export declare function consumerGatewayUrl(net: "mainnet" | "testnet"): string;
+/** Either a fixed token, or a function that produces (or refreshes) one. */
+export type BearerSource = string | (() => string | Promise<string>);
+export declare class GatewayHttpError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string);
+}
+export interface SelectSessionResult {
+    worker: `0x${string}`;
+    /**
+     * ECDH P-256 uncompressed public key of the selected worker. The gateway
+     * historically returns this as **base64** for the worker and **hex** for the
+     * disputer; the SDK's `decodePublicKey` accepts either, so callers do not need
+     * to branch.
+     */
+    workerEncryptionKey: string;
+    disputerEncryptionKey?: string;
+    nonce: number;
+    expiry: number;
+}
+export interface PrepareSessionResult {
+    worker: `0x${string}`;
+    /** Dispatcher EIP-712 signature authorising createSession on-chain. */
+    signature: `0x${string}`;
+    nonce: number;
+    expiry: number;
+}
+export interface UploadBlobResult {
+    blobHashes: `0x${string}`[];
+}
+export type SessionTokenResult = {
+    token: string;
+    expiresAt: string;
+} | {
+    status: "pending";
+    message?: string;
+};
+export interface GatewayClientOptions {
+    /** Network ('mainnet' | 'testnet') OR a verified `NetworkConfig`. */
+    network: "mainnet" | "testnet" | NetworkConfig;
+    /** Override the gateway base URL (rarely needed; default is consumerGatewayUrl). */
+    baseUrl?: string;
+    /** Bearer token (or thunk) for authenticated calls. */
+    bearer?: BearerSource;
+    /** Fetch override (testing). */
+    fetch?: typeof fetch;
+}
+/**
+ * Thin HTTP client. Methods throw `GatewayHttpError` on non-2xx; protected
+ * methods throw if no `bearer` was configured.
+ */
+export declare class GatewayClient {
+    readonly baseUrl: string;
+    private readonly bearer?;
+    private readonly fetchImpl;
+    constructor(opts: GatewayClientOptions);
+    /** Public: registered models the gateway will accept. */
+    getModels(): Promise<{
+        models: {
+            id: string;
+            name: string;
+        }[];
+    }>;
+    /** Protected: dispatcher picks a worker for a session and returns its pubkey. */
+    selectSession(modelId: `0x${string}`): Promise<SelectSessionResult>;
+    /**
+     * Protected: hand the dispatcher the encrypted session key it can give the
+     * worker, get back the EIP-712 signature authorising on-chain createSession.
+     *
+     * NOTE: the gateway expects `encWorkerKey` / `encDisputerKey` as **base64**
+     * (NOT hex). The same bytes are passed as **hex** to the on-chain
+     * `createSession`. The high-level `prepareSession(gateway, modelTag)` in
+     * `inference.ts` handles both encodings; if you call this lower-level method
+     * directly, base64-encode the wire bytes before passing them in.
+     */
+    prepareSession(input: {
+        modelId: `0x${string}`;
+        encWorkerKey: string;
+        encDisputerKey: string;
+    }): Promise<PrepareSessionResult>;
+    /** Protected: upload an encrypted prompt blob; returns the EIP-4844 blob hash. */
+    uploadBlob(base64Data: string): Promise<UploadBlobResult>;
+    /** Protected: fetch the relay JWT for an active session (202 = pending). */
+    getSessionToken(sessionId: number): Promise<SessionTokenResult>;
+    private req;
+}

package/dist/gateway.js

@@ -0,0 +1,87 @@
+/**
+ * HTTP client for the LightChain consumer gateway (a.k.a. chat-api). Exposes
+ * just the endpoints a third-party consumer needs to submit an inference job
+ * and read its result back.
+ *
+ * Auth: the gateway requires a bearer JWT obtained via the consumer-api's SIWE
+ * sign-in flow. The SDK does NOT bundle SIWE; the caller obtains a token (or a
+ * fresh-each-call thunk) by whatever means they prefer and hands it here.
+ */
+const GATEWAY_HOSTS = {
+    mainnet: "https://chat-api.mainnet.lightchain.ai",
+    testnet: "https://chat-api.testnet.lightchain.ai",
+};
+export function consumerGatewayUrl(net) {
+    return GATEWAY_HOSTS[net];
+}
+async function resolveBearer(src) {
+    return typeof src === "function" ? await src() : src;
+}
+export class GatewayHttpError extends Error {
+    constructor(status, body) {
+        super(`gateway ${status}: ${body.slice(0, 200)}`);
+        this.name = "GatewayHttpError";
+        this.status = status;
+        this.body = body;
+    }
+}
+/**
+ * Thin HTTP client. Methods throw `GatewayHttpError` on non-2xx; protected
+ * methods throw if no `bearer` was configured.
+ */
+export class GatewayClient {
+    constructor(opts) {
+        const net = typeof opts.network === "string" ? opts.network : opts.network.id;
+        this.baseUrl = (opts.baseUrl ?? consumerGatewayUrl(net)).replace(/\/+$/, "");
+        this.bearer = opts.bearer;
+        this.fetchImpl = opts.fetch ?? fetch.bind(globalThis);
+    }
+    /** Public: registered models the gateway will accept. */
+    getModels() {
+        return this.req("GET", "/api/models");
+    }
+    /** Protected: dispatcher picks a worker for a session and returns its pubkey. */
+    selectSession(modelId) {
+        return this.req("POST", "/api/sessions/select", { modelId });
+    }
+    /**
+     * Protected: hand the dispatcher the encrypted session key it can give the
+     * worker, get back the EIP-712 signature authorising on-chain createSession.
+     *
+     * NOTE: the gateway expects `encWorkerKey` / `encDisputerKey` as **base64**
+     * (NOT hex). The same bytes are passed as **hex** to the on-chain
+     * `createSession`. The high-level `prepareSession(gateway, modelTag)` in
+     * `inference.ts` handles both encodings; if you call this lower-level method
+     * directly, base64-encode the wire bytes before passing them in.
+     */
+    prepareSession(input) {
+        return this.req("POST", "/api/sessions/prepare", input);
+    }
+    /** Protected: upload an encrypted prompt blob; returns the EIP-4844 blob hash. */
+    uploadBlob(base64Data) {
+        return this.req("POST", "/api/blobs", { data: base64Data });
+    }
+    /** Protected: fetch the relay JWT for an active session (202 = pending). */
+    getSessionToken(sessionId) {
+        return this.req("GET", `/api/sessions/${sessionId}/token`);
+    }
+    async req(method, path, body) {
+        const headers = { "Content-Type": "application/json" };
+        if (this.bearer != null)
+            headers["Authorization"] = `Bearer ${await resolveBearer(this.bearer)}`;
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (res.status === 202) {
+            // The session-token endpoint returns 202 while pending; surface as JSON.
+            return (await res.json());
+        }
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new GatewayHttpError(res.status, text);
+        }
+        return (await res.json());
+    }
+}

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 import { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS } from "./networks.js";
 import { fromWei } from "./subgraph.js";
-import { aggregateModelStats, aggregateWorkerStats, networkAnalytics } from "./analytics.js";
-import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl } from "./inference.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 { 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";
 /**
  * Read-only client for a LightChain AI network. Pure reads from the public indexer
@@ -46,6 +48,18 @@ export declare class LightNode {
     modelId(tag: string): `0x${string}`;
     /** On-chain inference fee for a model, in whole LCAI (what submitJob must be paid). */
     estimateFee(modelTag: string): Promise<number>;
+    /**
+     * Configured `GatewayClient` for this network, ready to call the consumer-api
+     * endpoints (`prepareSession` / `uploadBlob` / `getSessionToken`). Pass a
+     * `bearer` (token or thunk) from your SIWE-authenticated session; the SDK
+     * does NOT bundle the SIWE handshake.
+     */
+    gateway(opts?: {
+        bearer?: import("./gateway.js").BearerSource;
+        baseUrl?: string;
+    }): GatewayClient;
 }
-export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, };
+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 type { BearerSource, GatewayClientOptions, SelectSessionResult, PrepareSessionResult, UploadBlobResult, SessionTokenResult } from "./gateway.js";
+export type { SessionPreparation } from "./inference.js";
 export type { NetworkId, NetworkConfig, Worker, Job, ModelInfo, NetworkStats, ModelStat, WorkerStat, NetworkAnalytics };

package/dist/index.js

@@ -1,8 +1,10 @@
 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 } from "./analytics.js";
-import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl } from "./inference.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 { GatewayClient, GatewayHttpError } from "./gateway.js";
+import * as crypto from "./crypto.js";
 /**
  * Read-only client for a LightChain AI network. Pure reads from the public indexer
  * and the chain; no keys, no writes. Independent, community-built.
@@ -77,5 +79,16 @@ export class LightNode {
     estimateFee(modelTag) {
         return estimateJobFee(this.network, modelTag);
     }
+    /**
+     * Configured `GatewayClient` for this network, ready to call the consumer-api
+     * endpoints (`prepareSession` / `uploadBlob` / `getSessionToken`). Pass a
+     * `bearer` (token or thunk) from your SIWE-authenticated session; the SDK
+     * does NOT bundle the SIWE handshake.
+     */
+    gateway(opts = {}) {
+        return new GatewayClient({ network: this.network, ...opts });
+    }
 }
-export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, };
+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, };

package/dist/inference.d.ts

@@ -1,4 +1,6 @@
 import type { NetworkConfig } from "./types.js";
+import { generateEcdhKeyPair } from "./crypto.js";
+import type { GatewayClient } from "./gateway.js";
 /** modelId = keccak256(utf8(exact ollama tag)). Joins to the subgraph + contracts. */
 export declare function modelId(tag: string): `0x${string}`;
 /**
@@ -19,6 +21,76 @@ export declare function estimateJobFee(cfg: NetworkConfig, modelTag: string): Pr
  * (it's a large, protocol-specific, currently-undocumented surface). See the SDK
  * README "Submitting inference" for the verified end-to-end steps and a reference.
  */
-export declare const JOB_REGISTRY_CONSUMER_ABI: readonly ["function createSession(bytes32 modelId, address worker, bytes encWorkerKey, bytes encDisputerKey, bytes dispatcherSignature, uint256 expiry) payable returns (uint256 sessionId)", "function submitJob(uint256 sessionId, bytes32 blobHash) payable returns (uint256 jobId)", "event SessionCreated(uint256 sessionId, address user, bytes32 indexed modelId, address worker, bytes encWorkerKey, bytes encDisputerKey)", "event JobSubmitted(uint256 jobId, uint256 sessionId, address worker)", "event JobCompleted(uint256 jobId, address worker, bytes32 responseBlobHash, bytes32 responseCiphertextHash)"];
-/** Consumer gateway base URL for a network (SIWE-authenticated; submit blobs + relay). */
-export declare function consumerGatewayUrl(net: "mainnet" | "testnet"): string;
+/**
+ * Canonical JobRegistry consumer ABI - parameter names mirror the verified
+ * mainnet contract (paramsHash / ephemeralPubKey / initState / promptHash) so
+ * decoders display sensible labels. The 4-byte selectors are
+ *   createSession(bytes32,address,bytes,bytes,bytes,uint256)  → 0xe80116b4
+ *   submitJob(uint256,bytes32)                                → 0xe3f4f3e9
+ * createSession is payable but called with value=0; submitJob is payable and
+ * must be called with `estimateJobFee(model)` as native value.
+ */
+export declare const JOB_REGISTRY_CONSUMER_ABI: readonly ["function createSession(bytes32 paramsHash, address worker, bytes encWorkerKey, bytes ephemeralPubKey, bytes initState, uint256 expiry) payable returns (uint256 sessionId)", "function submitJob(uint256 sessionId, bytes32 promptHash) payable returns (uint256 jobId)", "event SessionCreated(uint256 indexed sessionId, address indexed user, bytes32 indexed paramsHash, address worker, bytes encWorkerKey, bytes ephemeralPubKey)", "event JobSubmitted(uint256 indexed jobId, uint256 indexed sessionId, address worker)", "event JobCompleted(uint256 indexed jobId, address indexed worker, bytes32 responseHash, bytes32 ciphertextHash)"];
+/**
+ * High-level orchestration for the encrypted inference submit flow.
+ *
+ * The full submit is multi-stage (gateway calls + crypto + an on-chain tx the
+ * caller signs with their wallet). These helpers chain the gateway calls and
+ * the crypto so the caller is left with two well-defined responsibilities:
+ *
+ *   1. Sign and broadcast `createSession(...)` on the JobRegistry using the
+ *      `SessionPreparation.createSessionArgs` returned by `prepareSession`.
+ *   2. Sign and broadcast `submitJob(sessionId, blobHash)` paying
+ *      `estimateJobFee(model)` as native value, using the `blobHash` returned
+ *      by `submitPrompt`. The reply is decrypted with `decryptResponse`.
+ *
+ * Marked BETA: the on-chain calls are exercised; the gateway endpoints + wire
+ * crypto are wire-compatible with the reference client (lcai-chat-v2). Live
+ * end-to-end testing with a funded testnet wallet remains the caller's job.
+ */
+export interface SessionPreparation {
+    /** 32-byte session key the caller persists to encrypt/decrypt subsequent jobs. */
+    sessionKey: Uint8Array;
+    /**
+     * Arguments to pass to JobRegistry.createSession(...), in slot order.
+     *
+     * Parameter names match the canonical on-chain ABI (paramsHash,
+     * ephemeralPubKey, initState) verified live in the LightChain inference
+     * integration guide. The slot mapping is:
+     *   - paramsHash      ← keccak256(model tag)
+     *   - worker          ← prepared.worker
+     *   - encWorkerKey    ← hex(encWorker)              // ECDH-wrap for the worker
+     *   - ephemeralPubKey ← hex(encDisputer)            // ECDH-wrap for the disputer
+     *   - initState       ← prepared.signature          // dispatcher EIP-712 signature
+     *   - expiry          ← prepared.expiry
+     */
+    createSessionArgs: {
+        paramsHash: `0x${string}`;
+        worker: `0x${string}`;
+        encWorkerKey: `0x${string}`;
+        ephemeralPubKey: `0x${string}`;
+        initState: `0x${string}`;
+        expiry: bigint;
+    };
+    nonce: number;
+}
+/**
+ * Step 1 + 2 of the protocol: ask the gateway which worker to use, generate a
+ * fresh session key, wrap it for the worker (and the disputer if one was
+ * returned), and get the dispatcher's signature authorising createSession.
+ *
+ * After this returns, the caller submits the on-chain `createSession` tx with
+ * `createSessionArgs` and remembers `sessionKey` for the rest of the session.
+ */
+export declare function prepareSession(gateway: GatewayClient, modelTag: string): Promise<SessionPreparation>;
+/**
+ * Encrypt a UTF-8 prompt with the session key, upload as a blob, and return
+ * the EIP-4844 blob hash to pass to `submitJob(sessionId, blobHash)`.
+ */
+export declare function submitPrompt(gateway: GatewayClient, sessionKey: Uint8Array, prompt: string): Promise<`0x${string}`>;
+/** Decrypt a worker response (raw bytes or base64 from the relay) with the session key. */
+export declare function decryptResponse(sessionKey: Uint8Array, ciphertext: Uint8Array | string): Promise<string>;
+/** Re-export so callers don't have to import from a second module just for the URL helper. */
+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 };

package/dist/inference.js

@@ -1,4 +1,18 @@
 import { keccak256, toBytes } from "viem";
+import { generateSessionKey, generateEcdhKeyPair, importPublicKey, encryptSessionKey, encrypt, decrypt, hexToBytes, bytesToHex, bytesToBase64, base64ToBytes, utf8ToBytes, bytesToUtf8, } from "./crypto.js";
+// The gateway returns the worker pubkey as base64 and the disputer pubkey as
+// hex (per the verified integration guide). Both decode to 65-byte uncompressed
+// P-256 points - sniff the format so the caller never has to branch.
+function decodePublicKey(s) {
+    const stripped = s.startsWith("0x") ? s.slice(2) : s;
+    if (/^[0-9a-fA-F]{130}$/.test(stripped))
+        return hexToBytes(stripped);
+    const bytes = base64ToBytes(s);
+    if (bytes.length !== 65) {
+        throw new Error(`public key decoded to ${bytes.length} bytes; expected 65 (P-256 uncompressed)`);
+    }
+    return bytes;
+}
 // AIConfig.calculateJobFee(bytes32) - verified live on both networks.
 const CALCULATE_JOB_FEE_SELECTOR = "0x33763d83";
 /** modelId = keccak256(utf8(exact ollama tag)). Joins to the subgraph + contracts. */
@@ -35,14 +49,80 @@ export async function estimateJobFee(cfg, modelTag) {
  * (it's a large, protocol-specific, currently-undocumented surface). See the SDK
  * README "Submitting inference" for the verified end-to-end steps and a reference.
  */
+/**
+ * Canonical JobRegistry consumer ABI - parameter names mirror the verified
+ * mainnet contract (paramsHash / ephemeralPubKey / initState / promptHash) so
+ * decoders display sensible labels. The 4-byte selectors are
+ *   createSession(bytes32,address,bytes,bytes,bytes,uint256)  → 0xe80116b4
+ *   submitJob(uint256,bytes32)                                → 0xe3f4f3e9
+ * createSession is payable but called with value=0; submitJob is payable and
+ * must be called with `estimateJobFee(model)` as native value.
+ */
 export const JOB_REGISTRY_CONSUMER_ABI = [
-    "function createSession(bytes32 modelId, address worker, bytes encWorkerKey, bytes encDisputerKey, bytes dispatcherSignature, uint256 expiry) payable returns (uint256 sessionId)",
-    "function submitJob(uint256 sessionId, bytes32 blobHash) payable returns (uint256 jobId)",
-    "event SessionCreated(uint256 sessionId, address user, bytes32 indexed modelId, address worker, bytes encWorkerKey, bytes encDisputerKey)",
-    "event JobSubmitted(uint256 jobId, uint256 sessionId, address worker)",
-    "event JobCompleted(uint256 jobId, address worker, bytes32 responseBlobHash, bytes32 responseCiphertextHash)",
+    "function createSession(bytes32 paramsHash, address worker, bytes encWorkerKey, bytes ephemeralPubKey, bytes initState, uint256 expiry) payable returns (uint256 sessionId)",
+    "function submitJob(uint256 sessionId, bytes32 promptHash) payable returns (uint256 jobId)",
+    "event SessionCreated(uint256 indexed sessionId, address indexed user, bytes32 indexed paramsHash, address worker, bytes encWorkerKey, bytes ephemeralPubKey)",
+    "event JobSubmitted(uint256 indexed jobId, uint256 indexed sessionId, address worker)",
+    "event JobCompleted(uint256 indexed jobId, address indexed worker, bytes32 responseHash, bytes32 ciphertextHash)",
 ];
-/** Consumer gateway base URL for a network (SIWE-authenticated; submit blobs + relay). */
-export function consumerGatewayUrl(net) {
-    return `https://chat-api.${net}.lightchain.ai`;
+/**
+ * Step 1 + 2 of the protocol: ask the gateway which worker to use, generate a
+ * fresh session key, wrap it for the worker (and the disputer if one was
+ * returned), and get the dispatcher's signature authorising createSession.
+ *
+ * After this returns, the caller submits the on-chain `createSession` tx with
+ * `createSessionArgs` and remembers `sessionKey` for the rest of the session.
+ */
+export async function prepareSession(gateway, modelTag) {
+    const id = modelId(modelTag);
+    const selected = await gateway.selectSession(id);
+    const sessionKey = 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);
+    // The gateway expects the wrapped keys as BASE64; the same bytes are passed
+    // as HEX to the on-chain createSession. Sending hex to the gateway makes the
+    // dispatcher reject the prepare with an opaque error.
+    const prepared = await gateway.prepareSession({
+        modelId: id,
+        encWorkerKey: bytesToBase64(encWorker),
+        encDisputerKey: bytesToBase64(encDisputer),
+    });
+    return {
+        sessionKey,
+        nonce: prepared.nonce,
+        createSessionArgs: {
+            paramsHash: id,
+            worker: prepared.worker,
+            encWorkerKey: bytesToHex(encWorker),
+            ephemeralPubKey: bytesToHex(encDisputer),
+            initState: prepared.signature,
+            expiry: BigInt(prepared.expiry),
+        },
+    };
+}
+/**
+ * Encrypt a UTF-8 prompt with the session key, upload as a blob, and return
+ * the EIP-4844 blob hash to pass to `submitJob(sessionId, blobHash)`.
+ */
+export async function submitPrompt(gateway, sessionKey, prompt) {
+    const ct = await encrypt(sessionKey, utf8ToBytes(prompt));
+    const res = await gateway.uploadBlob(bytesToBase64(ct));
+    const first = res.blobHashes?.[0];
+    if (!first)
+        throw new Error("gateway returned no blob hashes");
+    return first;
+}
+/** Decrypt a worker response (raw bytes or base64 from the relay) with the session key. */
+export async function decryptResponse(sessionKey, ciphertext) {
+    const bytes = typeof ciphertext === "string" ? base64ToBytes(ciphertext) : ciphertext;
+    return bytesToUtf8(await decrypt(sessionKey, bytes));
 }
+/** Re-export so callers don't have to import from a second module just for the URL helper. */
+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 };

package/package.json

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