lightnode-sdk 0.5.0 → 0.6.0

package/README.md

@@ -1,231 +1,338 @@
 # lightnode-sdk
 
-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`.
+[![npm](https://img.shields.io/npm/v/lightnode-sdk?color=7064e9)](https://www.npmjs.com/package/lightnode-sdk)
+[![License: MIT](https://img.shields.io/badge/license-MIT-7064e9.svg)](LICENSE)
 
-> 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
+**The community SDK for LightChain AI.** Encrypted on-chain inference, network
+analytics, multi-turn chat, an Ethereum bridge wrapper, an LCAI Governor
+client, an on-chain model registry reader, worker preflight + watch, and a
+bundled `lightnode` CLI. Non-custodial. Pure JS (works in Node 18+, browsers,
+StackBlitz, Cloudflare Workers, Bun). Single peer dep: `viem`.
 
 ```bash
 npm install lightnode-sdk viem
 ```
 
-## Usage
+LightChain's own docs list official SDKs as "soon"; this fills the gap. Not
+affiliated with LightChain.
 
-```ts
-import { LightNode } from "lightnode-sdk";
+## Five-line "hello world"
 
-const ln = new LightNode("mainnet"); // or "testnet"
+```ts
+import { runInferenceWithKey } from "lightnode-sdk";
 
-// One worker
-const worker = await ln.getWorker("0x6781...6e0f");
-const jobs = await ln.getWorkerJobs("0x6781...6e0f", 20);
-const earnings = await ln.getEarningsLcai("0x6781...6e0f"); // whole LCAI
+const { answer, txs } = await runInferenceWithKey({
+  network: "testnet",                                  // or "mainnet"
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+  prompt: "Reply with a one-sentence fun fact about the ocean.",
+});
 
-// On-chain truth (independent of the indexer, which can lag a re-register)
-const registered = await ln.isRegistered("0x6781...6e0f"); // true | false | null
+console.log(answer);              // the decrypted reply
+console.log(txs.createSession);   // on-chain receipts
+```
 
-// Network-wide
-const stats = await ln.getNetworkStats();      // { total, active, jobsCompleted, totalEarnedLcai, models }
-const models = await ln.getModels();           // [{ name, fee, max_output_tokens, ... }]
-const perModel = await ln.getModelStats();     // completion rate, p50/p95 latency, incomplete, earnings
-const perWorker = await ln.getWorkerStats();   // per-worker reliability, busiest first
-const rollup = await ln.getNetworkAnalytics(); // overall completion / jobs / incomplete / earnings
+In the browser this works as-is. In Node, `ws` is auto-detected if installed,
+so you don't need to pass a WebSocket explicitly.
 
-// 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
+## What's in the SDK
 
-// CSV export (same exporters the LightNode dashboard uses)
-import { workerJobsCsv, modelStatsCsv, workerStatsCsv } from "lightnode-sdk";
-const csv = workerJobsCsv(await ln.getWorkerJobs("0x6781...6e0f", 100));
-```
+### Inference (paid)
 
-## API
-
-| Method | Returns |
-| --- | --- |
-| `getWorker(address)` | `Worker \| null` |
-| `getWorkerJobs(address, first?)` | `Job[]` |
-| `getEarningsLcai(address)` | `number` |
-| `isRegistered(address)` | `boolean \| null` (read from chain events) |
-| `getModels()` | `ModelInfo[]` |
-| `getWorkers(first?)` | `Worker[]` |
-| `getNetworkStats()` | `NetworkStats` |
-| `getModelStats(sample?)` | `ModelStat[]` |
-| `getWorkerStats(sample?, limit?)` | `WorkerStat[]` (reliability) |
-| `getNetworkAnalytics(sample?)` | `NetworkAnalytics` |
-| `estimateFee(modelTag)` | `number` (LCAI per job) |
-| `modelId(tag)` | `0x${string}` |
-
-Also exported: `NETWORKS`, `WORKER_REGISTRY`, `REGISTRY_TOPICS`, `aggregateModelStats`,
-`aggregateWorkerStats`, `networkAnalytics`, `modelStatsCsv`, `workerStatsCsv`,
-`workerJobsCsv`, `JOB_REGISTRY_CONSUMER_ABI`, `consumerGatewayUrl`, `fromWei`, and all
-the types.
+| API | Use when |
+|---|---|
+| **`runInferenceWithKey({ network, privateKey, prompt, ... })`** | One call from a wallet. The SDK builds viem clients, runs SIWE, encrypts, signs, decrypts. ~5 lines total. |
+| **`runInference({ gateway, wallet, publicClient, network, prompt, ... })`** | You already have viem clients + a SIWE JWT. Same internals, no setup duplication. The /playground uses this with a Reown wallet. |
+| **`runInferenceStream({ network, privateKey, prompt, ... })`** | Modern `AsyncIterable<string>` of chunks plus a `done` promise for the final receipt. `for await (const chunk of stream) ...` |
+| **`Conversation` / `chat({ network, privateKey })`** | Multi-turn chat helper. Keeps history client-side; one encrypted inference per `.send()`. Optional `system` prompt, `maxHistoryTurns` cap. |
+| **`prepareSession`, `submitPrompt`, `decryptResponse`** | Lowest-level: drive the protocol step by step. Build custom retry, batching, multi-turn-with-session-reuse on top. |
 
-## CLI
+All four high-level entry points share:
+- Auto-retry on `StalledWorkerError` (default 2 retries, configurable).
+- Auto-resolve `globalThis.WebSocket` in browsers, dynamic-import `ws` in Node.
+- Streaming via `onChunk(piece, totalSoFar)` callback.
+- Byte-perfect crypto vs LightChain's reference client (ECDH P-256 + raw
+  32-byte shared secret + AES-256-GCM, `@noble/curves` and `@noble/ciphers`
+  under the hood).
 
-```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 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)
-
-# Patch an existing project (auto-detects Next.js, Hono, or Node):
-npx lightnode add inference                    # encrypted inference route/script
-npx lightnode add chat                         # chat-style UI with conversation history
-npx lightnode add analytics-dashboard          # read-only network + worker analytics page
-npx lightnode add nft-mint-with-inference      # AI-generated NFT metadata with on-chain provenance
-# All `add` commands accept [--template auto|nextjs-api|hono|node] [--net testnet|mainnet] [--force]
+### Read-only `LightNode` client (free, no key)
 
-# Or scaffold a brand-new project:
-npm create lightnode-app my-app
+```ts
+import { LightNode } from "lightnode-sdk";
+const ln = new LightNode("mainnet"); // or "testnet" or a custom NetworkConfig
+
+await ln.getNetworkStats();              // totals + active count + earnings
+await ln.getModels();                    // ModelInfo[] (name, fee, max tokens)
+await ln.getWorkers(200);                // Worker[], busiest first
+await ln.getWorker("0x...");             // one worker record (or null)
+await ln.getWorkerJobs("0x...", 20);     // recent jobs for one worker
+await ln.getModelStats(1000);            // per-model completion / p50 / p95
+await ln.getWorkerStats(1000, 25);       // per-worker reliability
+await ln.getNetworkAnalytics(1000);      // network-wide rollup
+await ln.isRegistered("0x...");          // chain-truth registration (no indexer lag)
+await ln.getEarningsLcai("0x...");       // settled earnings in LCAI
+await ln.estimateFee("llama3-8b");       // live per-job fee from AIConfig
+await ln.modelId("llama3-8b");           // keccak256 of the model tag
+await ln.getJobStatus(1234n);            // category + refundable flag (new in 0.5.0)
+ln.gateway({ bearer });                  // pre-configured GatewayClient
 ```
 
-## Submitting inference
+Plus the bare-metal aggregators (`aggregateModelStats`, `aggregateWorkerStats`,
+`networkAnalytics`) and CSV exporters (`modelStatsCsv`, `workerStatsCsv`,
+`workerJobsCsv`) for reporting / dashboards.
 
-**Easy mode (`runInference` — v0.4+):** one async call drives the whole protocol —
-SIWE → prepareSession → on-chain createSession → relay WS → encrypt + upload prompt
-→ on-chain submitJob → decrypt streamed chunks → wait for `JobCompleted` →
-return the assembled answer + three tx hashes. Built-in retry on `StalledWorkerError`.
+### Bridge SDK (new in 0.5.0)
+
+Typed wrapper around the LightChain Hyperlane Warp Route bridge.
 
 ```ts
-import { LightNode, GatewayClient, runInference } from "lightnode-sdk";
-import WS from "ws"; // omit in the browser
+import { Bridge, BRIDGE_ROUTE } from "lightnode-sdk";
+import { createPublicClient, createWalletClient, http, parseEther } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
 
-const ln = new LightNode("testnet");
-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,
-  onChunk: (chunk) => process.stdout.write(chunk), // live streaming
-  maxRetries: 2,                                    // auto-retry on stall
+const account = privateKeyToAccount(process.env.PRIVATE_KEY!);
+const ethPub = createPublicClient({ transport: http(BRIDGE_ROUTE.ethereum.rpc) });
+const ethWal = createWalletClient({ account, transport: http(BRIDGE_ROUTE.ethereum.rpc) });
+
+const bridge = new Bridge(ethPub, ethWal);
+
+// Quote the Hyperlane gas payment for one message
+const fee = await bridge.quoteFee("ethereum", "lightchain-mainnet");
+
+// One-time ERC-20 approval (MaxUint256 by default)
+await bridge.approve();
+
+// Send 100 LCAI to your own address on LightChain mainnet
+await bridge.transfer({
+  from: "ethereum",
+  to: "lightchain-mainnet",
+  amount: parseEther("100"),
+  recipient: account.address,
+  fee,
 });
-console.log("\n", txs); // { createSession, submitJob, jobCompleted }
 ```
 
-The lower-level helpers (`prepareSession`, `submitPrompt`, `decryptResponse`,
-the typed errors `StalledWorkerError` / `OnChainRevertError` / `GatewayAuthError`
-/ `RelayTokenTimeoutError`) stay exported for builders who want a different
-retry policy or to reuse a session across prompts.
+For the reverse direction, wire `BRIDGE_ROUTE["lightchain-mainnet"].rpc`
+instead and `from: "lightchain-mainnet"`. The SDK attaches native LCAI as
+value automatically.
+
+Confirmed addresses (baked in):
+| Side | Role | Address |
+|------|------|---------|
+| Ethereum | HypERC20Collateral | `0x01f80bb8e78e79881E8Ec7832fB6C2c59f64e353` |
+| Ethereum | LCAI ERC-20 | `0x9cA8530CA349c966Fe9ef903Df17a75B8A778927` |
+| LightChain | HypNative | `0xEc7096A3116EE769457C939617375Ec1785AA6f1` |
 
-### Manual mode (the full surface)
+### DAO SDK (new in 0.5.0)
 
-`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:
+OpenZeppelin Governor v5 wrapper for the LCAIGovernor on Ethereum mainnet.
 
-| 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?" |
+```ts
+import { DAO, VoteSupport, PROPOSAL_STATE_LABEL } from "lightnode-sdk";
+
+// Read
+const dao = new DAO(publicClient, "ethereum");
+const cfg = await dao.config();                   // delay / period / threshold
+const p = await dao.proposal(12345n);             // state + votes + key blocks
+console.log(p.stateLabel);                        // "active" | "queued" | ...
+
+// Write (needs wallet)
+const daoRW = new DAO(publicClient, "ethereum", walletClient);
+await daoRW.castVote(12345n, VoteSupport.For, "I support this");
+await daoRW.propose({ targets, values, calldatas, description });
+await daoRW.queue({ targets, values, calldatas, descriptionHash });
+await daoRW.execute({ targets, values, calldatas, descriptionHash });
+```
 
-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.
+Confirmed Ethereum addresses (baked in):
+- LCAIGovernor `0x6dfa413B5900a1a7947BC75E68AbBA093cB2492d`
+- LCAITimeLock `0xbE1c37F8C4DA77dD06F4A8AC5098Ec70273093d7`
+- LCAIBallots (IVotes) `0x75F3D01c4D960FE986A598B7954A3b786B29cE49`
+- LCAI ERC-20 `0x9cA8530CA349c966Fe9ef903Df17a75B8A778927`
+- LCAITreasury `0x07A716a551E5f4CA7D6C71Da9dF1cb1429Dba826`
 
-### Auth (your responsibility)
+Voting params (live-read via `dao.config()`): ~1 day delay, ~14 day period,
+140k LCAI threshold, 3% quorum.
 
-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.
+### On-chain Model Registry reader (new in 0.5.0)
 
-### End-to-end (sketch)
+Typed reader for `AIVMModelRegistry` + `BenchmarkRegistry`. Since LightChain
+has not published a public deployment address, you pass yours explicitly:
 
 ```ts
-import {
-  LightNode,
-  prepareSession,
-  submitPrompt,
-  decryptResponse,
-  JOB_REGISTRY_CONSUMER_ABI,
-} from "lightnode-sdk";
-import { createWalletClient, http, parseAbi } from "viem";
-import { privateKeyToAccount } from "viem/accounts";
+import { OnchainModelRegistry, MODEL_STATUS_LABEL } from "lightnode-sdk";
 
-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,
-  ],
+const reader = new OnchainModelRegistry({
+  publicClient,
+  registry: "0x...",       // AIVMModelRegistry deployment
+  benchmarks: "0x...",     // optional, only for benchmark methods
 });
-// 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)),
+
+const baseIds = await reader.getBaseModelIds();
+const variantIds = await reader.getAllVariants();
+const variant = await reader.getVariant("...");
+const policy = await reader.getAccessPolicy("...");   // tier: "free" | "paywalled" | "ticket-gated"
+const variants = await reader.getVariantsForBaseModel(baseId);
+```
+
+Surfaces the full ABI for both contracts plus a builder-friendly `tier`
+heuristic derived from the raw `AccessPolicyConfig`.
+
+### Worker preflight + watch (new in 0.5.0)
+
+Remote operational SDK for the worker network. No SSH, no Docker. Works from
+any machine with a funded wallet (preflight) or no key at all (watch).
+
+```ts
+import { workerPreflight, workerWatch, LightNode } from "lightnode-sdk";
+
+// One real test inference. Returns verdict, elapsed time, on-chain receipts.
+const r = await workerPreflight({
+  network: "testnet",
+  privateKey: process.env.PRIVATE_KEY!,
+  model: "llama3-8b",
+  deadlineMs: 60_000,
 });
+console.log(r.verdict);    // "ok" | "over-deadline" | "stalled" | "failed"
+console.log(r.summary);    // human one-liner
+console.log(r.txs);        // createSession + submitJob + jobCompleted
+
+// Watch a worker's on-chain + indexer state. AsyncIterable of events.
+const ln = new LightNode("mainnet");
+const handle = workerWatch(ln, "0xWorker...", { intervalMs: 30_000 });
+for await (const event of handle.events) {
+  console.log(event.kind);   // "snapshot" | "registered" | "went-stale" | "back-online" | "jobs-completed" | "earnings-up"
+  console.log(event.state);  // { registered, lastSeenSecsAgo, jobsCompleted, earningsLcai, ... }
+}
+```
+
+### Typed errors
 
-// 5) Watch JobCompleted (or read the response blob via the relay), then decrypt:
-const answer = await decryptResponse(sessionKey, responseCiphertextFromRelay);
+```ts
+import { isStalledWorker, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError } from "lightnode-sdk";
+
+try {
+  await runInferenceWithKey({ ... });
+} catch (e) {
+  if (isStalledWorker(e)) { /* worker never produced an answer; protocol refunds */ }
+  // ...
+}
 ```
 
-### What's exported (v0.3)
+| Error | When |
+|---|---|
+| `StalledWorkerError` | Worker ack'd then went silent. After `maxRetries`, raised. Protocol refunds. |
+| `OnChainRevertError` | `createSession` or `submitJob` reverted. Includes the tx hash. |
+| `RelayTokenTimeoutError` | Gateway dispatcher never issued the relay JWT (transient). |
+| `GatewayAuthError` | SIWE handshake or JWT issue. Re-auth and retry. |
+
+## CLI
+
+`lightnode` is bundled. Read-only commands work anywhere; chat / wallet / preflight need `PRIVATE_KEY`.
+
+### Read-only (no key)
+
+```bash
+npx lightnode network                    # network summary JSON
+npx lightnode models                     # registered models + fees
+npx lightnode worker 0x...               # one worker + 5 recent jobs
+npx lightnode jobs 0x... --csv           # job history
+npx lightnode registered 0x...           # true | false | null (chain truth)
+npx lightnode fee llama3-8b              # per-job LCAI fee
+npx lightnode analytics --csv            # per-model performance
+npx lightnode reliability --csv          # per-worker reliability
+npx lightnode job 1234                   # job status + refundable flag
+npx lightnode worker watch 0x... --interval 30   # JSON event per state change
+npx lightnode bridge addresses           # bridge route
+npx lightnode dao addresses              # LCAI Governor addresses
+npx lightnode dao config                 # live voting delay / period / threshold
+```
 
-- `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.
+### Need PRIVATE_KEY
 
-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.
+```bash
+PRIVATE_KEY=0x... npx lightnode chat "Write me a haiku about LightChain"
+PRIVATE_KEY=0x... npx lightnode wallet address
+PRIVATE_KEY=0x... npx lightnode wallet balance --net testnet
+                  npx lightnode wallet new           # generates a fresh key
+PRIVATE_KEY=0x... npx lightnode worker preflight --net testnet
+```
 
-## Why `isRegistered` reads the chain
+### Scaffolders (write files into your project)
 
-The public indexer can report a registered worker as `deregistered` after a
-deregister -> re-register cycle. `isRegistered` instead reads the WorkerRegistry's
-join/exit events directly and returns the latest, so it is correct for any worker.
+```bash
+npx lightnode add inference                    # encrypted inference route or script
+npx lightnode add chat                         # chat UI with conversation history
+npx lightnode add agent                        # scheduled inference (Vercel Cron / setInterval)
+npx lightnode add analytics-dashboard          # read-only network + worker analytics page
+npx lightnode add nft-mint-with-inference      # AI-generated NFT metadata with on-chain provenance
+```
+
+All `add` commands accept `--template auto|nextjs-api|hono|node`,
+`--net testnet|mainnet`, and `--force`.
 
 ## Networks
 
-| | mainnet | testnet |
-| --- | --- | --- |
-| chainId | 9200 | 8200 |
-| min stake | 50,000 LCAI | 5,000 LCAI |
-| WorkerRegistry | `0x…1002` (genesis predeploy) | same |
+| | Testnet | Mainnet |
+|---|---|---|
+| Chain ID | 8200 | 9200 |
+| RPC | `https://rpc.testnet.lightchain.ai` | `https://rpc.mainnet.lightchain.ai` |
+| Explorer | <https://testnet.lightscan.app> | <https://mainnet.lightscan.app> |
+| Faucet | <https://lightfaucet.ai> (~2 LCAI / IP / day) | n/a (bridge from Ethereum) |
+| Inference cost | free | ~0.022 LCAI per call |
+| Worker stake | 5,000 LCAI | 50,000 LCAI |
+
+## Examples
+
+Tiny standalone repo: <https://github.com/marinom2/lightnode-examples>.
+Eight runnable examples covering every SDK module:
+
+- `quickstart-inference/` (30-line one-shot)
+- `multi-turn-chat/` (interactive REPL)
+- `nextjs-api-route/` (drop-in App Router route)
+- `hono-server/` (any-Node microservice)
+- `bridge-transfer/` (LCAI bridge in both directions)
+- `dao-vote/` (read + vote LCAI Governor)
+- `worker-preflight/` (one real test inference + watch)
+- `model-registry-read/` (AIVMModelRegistry reader)
+
+Open any of them in StackBlitz in about 5 seconds:
+
+```
+https://stackblitz.com/github/marinom2/lightnode-examples/tree/main/quickstart-inference
+```
+
+## Non-custodial
+
+- The SDK never holds your key. Every on-chain call is signed via viem in
+  your process.
+- End-to-end encryption: your prompt is encrypted to the worker's ECDH pubkey
+  before it leaves your machine. The gateway, the relay, and any third party
+  in the path see only ciphertext.
+- The session key is ephemeral (32 random bytes per session). Never persisted.
+- Browser bundles work too: noble-backed crypto, no Web Crypto algorithm
+  dependency, no Node-only imports.
+
+## Compatibility
+
+| Runtime | Status |
+|---|---|
+| Node 18+ | Tested; `ws` auto-detected. |
+| Modern browsers | Works via `globalThis.WebSocket`. The /playground uses it. |
+| StackBlitz / Bolt WebContainer | Works since 0.4.8 (noble crypto, lightnode.app CORS proxy). |
+| Cloudflare Workers / Bun | Works. Pass a `WebSocket` ctor if the runtime lacks one. |
+
+## Provenance
+
+The protocol surface (consumer gateway, relay, JobRegistry ABI, crypto
+layout) is built against
+[LightChain's reference client](https://github.com/lightchain-protocol/lcai-chat-v2)
+and cert-transparency host enumeration. Crypto is byte-perfect vs the
+reference (`@noble/curves` for P-256, `@noble/ciphers` for AES-256-GCM).
+
+If LightChain ships official SDKs that supersede this one, we'll archive the
+inference path and keep the analytics + bridge + DAO + preflight modules.
 
 ## License
 
-MIT
+MIT. Independent, community-built. Not affiliated with or endorsed by the
+LightChain team.

package/dist/agent.d.ts

@@ -0,0 +1,122 @@
+import { type RunInferenceWithKeyArgs } from "./inference.js";
+/**
+ * One tool the agent can call. The model decides when by emitting a tool
+ * call block; the handler returns plain JSON which is threaded back into
+ * the next turn as an observation.
+ *
+ * The handler MUST return JSON-serializable data so the model can read
+ * it back. Use `String()` to stringify primitives, `JSON.stringify`-able
+ * objects otherwise.
+ */
+export interface AgentTool {
+    /** Short snake_case name. The model uses this exact string in tool calls. */
+    name: string;
+    /** One-line description shown to the model so it knows when to use the tool. */
+    description: string;
+    /**
+     * Argument schema, very informal: { argName: "string description" }. The
+     * model is told to fill in matching JSON values; the SDK does not enforce
+     * types beyond JSON parsing.
+     */
+    args: Record<string, string>;
+    /** Run the tool. Return JSON-serializable data (string, number, object, etc.). */
+    handler: (args: Record<string, unknown>) => Promise<unknown> | unknown;
+}
+/** One step in the agent's reasoning loop. */
+export type AgentStep = {
+    kind: "thought";
+    text: string;
+} | {
+    kind: "tool_call";
+    name: string;
+    args: Record<string, unknown>;
+    result: unknown;
+} | {
+    kind: "tool_error";
+    name: string;
+    args: Record<string, unknown>;
+    error: string;
+} | {
+    kind: "answer";
+    text: string;
+};
+export interface AgentRunResult {
+    /** The model's final answer. May be empty if maxIterations was hit. */
+    answer: string;
+    /** Every step taken (thoughts + tool calls + final answer). Useful for debugging + UI. */
+    steps: AgentStep[];
+    /** Total inferences fired. Each iteration is one inference, so this is also iteration count. */
+    iterations: number;
+    /** True if the loop bailed because it ran out of iterations without an `answer` block. */
+    hitLimit: boolean;
+}
+export interface AgentOptions extends Omit<RunInferenceWithKeyArgs, "prompt" | "system"> {
+    /** Human-readable goal / persona. Becomes the BASE system prompt; the tool harness is appended automatically. */
+    system?: string;
+    /** Tools the model is allowed to call. */
+    tools: ReadonlyArray<AgentTool>;
+    /** Hard cap on reasoning steps. Default 5. */
+    maxIterations?: number;
+    /** Called after every step (thought / tool call / answer). Useful for live UI. */
+    onStep?: (step: AgentStep) => void;
+}
+/**
+ * ReAct-style agent on top of `runInferenceWithKey`. Each iteration:
+ *   1. The SDK sends a system prompt that lists tools + the JSON tool-call
+ *      format to the model, plus the running transcript.
+ *   2. The model emits either a tool call (`<tool>name {"k":"v"}</tool>`)
+ *      or a final answer (`<answer>...</answer>`).
+ *   3. The SDK parses, runs the tool, threads the result back, repeats.
+ *
+ * Designed for smaller open models (llama3-8b). The protocol is simple
+ * string markers, not native function calling, so it works on any model
+ * the LightChain network exposes.
+ *
+ * @example
+ * ```ts
+ * import { Agent } from "lightnode-sdk";
+ *
+ * const agent = new Agent({
+ *   network: "testnet",
+ *   privateKey: process.env.PRIVATE_KEY!,
+ *   model: "llama3-8b",
+ *   system: "You are a careful research assistant.",
+ *   tools: [
+ *     {
+ *       name: "add",
+ *       description: "Add two integers and return the sum.",
+ *       args: { a: "first integer", b: "second integer" },
+ *       handler: ({ a, b }) => Number(a) + Number(b),
+ *     },
+ *   ],
+ *   maxIterations: 3,
+ * });
+ *
+ * const { answer, steps } = await agent.run("What is 17 + 25?");
+ * console.log(answer); // "42"
+ * ```
+ */
+export declare class Agent {
+    private readonly opts;
+    constructor(opts: AgentOptions);
+    run(userMessage: string): Promise<AgentRunResult>;
+    private buildSystemPrompt;
+}
+type ParsedOutput = {
+    kind: "tool_call";
+    name: string;
+    args: Record<string, unknown>;
+} | {
+    kind: "answer";
+    text: string;
+} | {
+    kind: "thought";
+    text: string;
+};
+/**
+ * Parse the model's raw output into either a tool call, a final answer, or
+ * a thought (everything else). Tolerant of whitespace and the model
+ * forgetting to close a tag. Visible for testing.
+ */
+export declare function parseAgentOutput(raw: string): ParsedOutput;
+export {};