lightnode-sdk 0.6.1 → 0.7.0

package/README.md

@@ -16,6 +16,12 @@ npm install lightnode-sdk viem
 LightChain's own docs list official SDKs as "soon"; this fills the gap. Not
 affiliated with LightChain.
 
+New to blockchain or Node.js? Read the
+[Getting Started guide](../GETTING-STARTED.md) first. It covers wallets, testnet
+vs mainnet, the `.env` file, and your first AI call in about 5 minutes. Then come
+back here for the full reference. The rest of this README assumes you're
+comfortable with TypeScript and a terminal.
+
 ## Five-line "hello world"
 
 ```ts
@@ -205,6 +211,73 @@ for await (const event of handle.events) {
 }
 ```
 
+### Worker operator (new in 0.7.0)
+
+The **write/ops side** of running a worker - the on-chain actions that are
+otherwise only reachable through the multi-GB worker Docker image, or by
+reverse-engineering the unverified contracts. Pure RPC: run it from a laptop, a
+server, or CI with no worker image at all. This complements (does not replace)
+`workerPreflight`/`workerWatch` above.
+
+Its flagship is **stuck-job recovery**. When a worker acknowledges a job but
+never completes it (Ollama down, machine asleep), that job sits `Acknowledged`
+forever and **blocks deregistration** - and no official tool clears it. The
+JobRegistry's `claimTimeout` is permissionless, so the operator can self-clear
+it. `unstickAndDeregister()` is the one-call rescue.
+
+```ts
+import { WorkerOperator } from "lightnode-sdk";
+import { createPublicClient, createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+
+const chain = { id: 8200, name: "LC Testnet",
+  nativeCurrency: { name: "LCAI", symbol: "LCAI", decimals: 18 },
+  rpcUrls: { default: { http: ["https://rpc.testnet.lightchain.ai"] } } };
+const publicClient = createPublicClient({ transport: http(chain.rpcUrls.default.http[0]), chain });
+const walletClient = createWalletClient({ account: privateKeyToAccount(process.env.WORKER_KEY!), transport: http(chain.rpcUrls.default.http[0]), chain });
+
+const op = new WorkerOperator("testnet", { publicClient, walletClient });
+
+// Reads (no wallet needed): status, live protocol config, typed jobs.
+await op.status();              // { registered, stakeLcai, claimableLcai, belowFloor, ... }
+await op.config();              // live AIConfig: minStake, timeouts, slashBps, fee split
+await op.getJob(974);           // typed Job { state, worker, escrowedFeeWei, timestamps, ... }
+
+// Pre-flight gating - know WHY before you spend gas. Pass the worker's job IDs
+// (from LightNode.getWorkerJobs / the subgraph).
+await op.canDeregister([974, 976, 978, 979]);   // { ok, blockedBy: [974, 976], reason }
+
+// Settlement + exit, Docker-free:
+await op.releaseAll([978, 979]); // settle completed jobs past their dispute window
+await op.withdraw();             // pull earned balance into the worker wallet
+
+// The rescue: clear stuck acked jobs, then deregister + withdraw, in one call.
+await op.unstickAndDeregister([974, 976, 978, 979]);
+```
+
+> **Mainnet slashing.** `claimTimeout` / `clearStuck` / `unstickAndDeregister`
+> finalize a stuck job as `TimedOut`, which **realizes the completion-timeout
+> slash** on mainnet (`config().slashBps.completionTimeout`, 5% of stake per job
+> at writing). Testnet has slashing disabled. It is the deliberate price of
+> unblocking an exit a stuck job would otherwise block forever - only clear jobs
+> you accept are lost.
+
+**Decoded reverts.** The WorkerRegistry/JobRegistry custom errors aren't in the
+4byte directory; `decodeWorkerError(revertData)` turns them into a sentence + the
+fix, and every write throws a `WorkerOpError` carrying the decoded cause:
+
+| Error | Meaning |
+|---|---|
+| `ActiveJobsExist(worker, n)` | deregister blocked by `n` in-flight jobs - `clearStuck()` them first |
+| `DisputeWindowNotElapsed(jobId, releaseAt, now)` | `releaseJob` too early - retry after the window |
+| `InsufficientStake(requested, available)` | `withdrawStake` below the floor - `topUpStake()` + `reinstate()` |
+| `WorkerNotRegistered(addr)` | not a registered worker |
+
+Scope: this is the **operator** surface (register/stake/settle/recover/exit). It
+does not serve jobs - that's the official Go worker daemon. Contracts are
+unverified and may change; treat as 0.x and lean on `decodeWorkerError` to
+surface drift.
+
 ### Batch runner (new in 0.6.0)
 
 Fan out many prompts as parallel encrypted inferences. Capped concurrency, stable result order, per-slot errors so one stalled worker does not kill the batch.

package/dist/add.js

@@ -341,7 +341,9 @@ function depsNeeded(template) {
         return ["lightnode-sdk", "viem", "ws"];
     if (template === "hono")
         return ["lightnode-sdk", "viem", "ws"];
-    return ["lightnode-sdk", "viem", "ws"];
+    // The node/script template is run with `npx tsx <file>.ts`, so tsx must be
+    // installed too, otherwise `tsx ...` fails with "command not found".
+    return ["lightnode-sdk", "viem", "ws", "tsx"];
 }
 /**
  * Implementation called by `lightnode add inference [...]`.

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { LightNode, modelStatsCsv, workerStatsCsv, workerJobsCsv, runInferenceWithKey, runInferenceBatch, Agent, isStalledWorker, workerPreflight, workerWatch, BRIDGE_ROUTE, DAO, DAO_ADDRESSES } from "./index.js";
+import { LightNode, modelStatsCsv, workerStatsCsv, workerJobsCsv, runInferenceWithKey, runInferenceBatch, Agent, isStalledWorker, workerPreflight, workerWatch, WorkerOperator, isWorkerOpError, BRIDGE_ROUTE, DAO, DAO_ADDRESSES } from "./index.js";
 import { addInference, addAnalyticsDashboard, addNftMint, addChat, addAgent } from "./add.js";
-import { createPublicClient, http, parseEther } from "viem";
+import { createPublicClient, createWalletClient, http, parseEther } from "viem";
 import { privateKeyToAccount, generatePrivateKey } from "viem/accounts";
 function flag(name) {
     const i = process.argv.indexOf(name);
@@ -45,9 +45,16 @@ Read-only network commands (no key):
   analytics [--csv]        per-model performance (completion, p50/p95, incomplete)
   reliability [--csv]      per-worker reliability, busiest first
 
-Preflight (needs PRIVATE_KEY in env):
+Worker operator (needs PRIVATE_KEY in env; signs as the worker key):
   worker preflight         run one real test inference, print verdict + timings
                            ([--key 0x...] [--model llama3-8b] [--deadline 60])
+  worker status [addr]     registration, stake, claimable, live protocol config
+  worker can-deregister    check what blocks the exit (in-flight jobs), no spend
+  worker settle            release completed jobs past their window + withdraw
+  worker clearstuck        claimTimeout acked, past-deadline jobs (unblocks exit)
+                           (mainnet realizes a per-job slash; needs --yes)
+  worker withdraw          pull the earned balance into the worker wallet
+  worker deregister        clear stuck + settle + withdraw + deregister (mainnet: --yes)
 
 Ecosystem (read-only):
   bridge addresses         print bridge route (Ethereum <-> LightChain) addresses
@@ -70,6 +77,40 @@ function pickKey() {
     }
     return k;
 }
+const viemChain = (n) => ({
+    id: n.network.chainId,
+    name: n.network.label,
+    nativeCurrency: { name: "LCAI", symbol: "LCAI", decimals: 18 },
+    rpcUrls: { default: { http: [n.network.rpc] } },
+});
+/** A read-only WorkerOperator for the given worker address (no key). */
+function readOperator(n, address) {
+    const chain = viemChain(n);
+    const publicClient = createPublicClient({ transport: http(n.network.rpc), chain });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return new WorkerOperator(n.network, { publicClient: publicClient, workerAddress: address });
+}
+/** A write-capable WorkerOperator signed by PRIVATE_KEY / --key. The viem clients
+ *  are cast to the SDK's structural Minimal* types (same boundary cast the
+ *  inference module uses) - viem's strict writeContract union does not accept the
+ *  intentionally-loose Minimal shape directly. */
+function writeOperator(n) {
+    const chain = viemChain(n);
+    const account = privateKeyToAccount(pickKey());
+    const publicClient = createPublicClient({ transport: http(n.network.rpc), chain });
+    const walletClient = createWalletClient({ account, transport: http(n.network.rpc), chain });
+    return new WorkerOperator(n.network, {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        publicClient: publicClient,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        walletClient: walletClient,
+    });
+}
+/** The worker's job IDs from the indexer, used to drive on-chain settle/clear. */
+async function workerJobIds(n, address) {
+    const jobs = await n.getWorkerJobs(address, 100);
+    return jobs.map((j) => Number(j.id)).filter((x) => Number.isFinite(x));
+}
 async function main() {
     const ln = new LightNode(net);
     switch (cmd) {
@@ -202,8 +243,78 @@ async function main() {
                     process.exit(1);
                 break;
             }
+            // Operator subcommands (the write/ops side). status is read-only; the rest
+            // sign with PRIVATE_KEY / --key and act on the worker that key controls.
+            if (sub === "status") {
+                const addr = positionals[2] ?? (flag("--key") || process.env.PRIVATE_KEY ? privateKeyToAccount(pickKey()).address : die("usage: lightnode worker status <address>   (or set PRIVATE_KEY)"));
+                const op = readOperator(ln, addr);
+                const [st, cfg] = await Promise.all([op.status(), op.config()]);
+                console.log(JSON.stringify({ ...st, stakeWei: st.stakeWei.toString(), minStakeWei: st.minStakeWei.toString(), claimableWei: st.claimableWei.toString(), config: { minStakeLcai: cfg.minStakeLcai, completionTimeoutSec: cfg.completionTimeoutSec, slashBps: cfg.slashBps } }, null, 2));
+                break;
+            }
+            if (sub === "can-deregister") {
+                const op = writeOperator(ln);
+                const ids = await workerJobIds(ln, privateKeyToAccount(pickKey()).address);
+                const r = await op.canDeregister(ids);
+                console.log(JSON.stringify({ ok: r.ok, blockedBy: r.blockedBy.map(String), reason: r.reason }, null, 2));
+                break;
+            }
+            if (sub === "settle") {
+                const op = writeOperator(ln);
+                const addr = privateKeyToAccount(pickKey()).address;
+                const ids = await workerJobIds(ln, addr);
+                console.error(`> releasing completed jobs on ${net}...`);
+                const rel = await op.releaseAll(ids);
+                let withdrawTx;
+                if ((await op.status()).claimableWei > 0n)
+                    withdrawTx = await op.withdraw();
+                console.log(JSON.stringify({ released: rel.released.map((r) => ({ jobId: r.jobId.toString(), tx: r.tx })), notReady: rel.notReady.map(String), withdrawTx: withdrawTx ?? null }, null, 2));
+                break;
+            }
+            if (sub === "clearstuck") {
+                const op = writeOperator(ln);
+                const addr = privateKeyToAccount(pickKey()).address;
+                const ids = await workerJobIds(ln, addr);
+                if (net === "mainnet" && !process.argv.includes("--yes")) {
+                    const cfg = await op.config();
+                    die(`clearstuck finalizes stuck jobs as TimedOut, realizing a ${cfg.slashBps.completionTimeout / 100}% slash per job on mainnet. Re-run with --yes to confirm.`);
+                }
+                console.error(`> clearing stuck (acknowledged, past-deadline) jobs on ${net}...`);
+                const r = await op.clearStuck(ids);
+                console.log(JSON.stringify({ cleared: r.cleared.map((c) => ({ jobId: c.jobId.toString(), tx: c.tx })), skipped: r.skipped.map(String) }, null, 2));
+                break;
+            }
+            if (sub === "withdraw") {
+                const op = writeOperator(ln);
+                const before = (await op.status()).claimableLcai;
+                if (before <= 0) {
+                    console.log(JSON.stringify({ withdrawn: 0, note: "no claimable balance in the JobRegistry" }, null, 2));
+                    break;
+                }
+                const tx = await op.withdraw();
+                console.log(JSON.stringify({ withdrawnLcai: before, tx }, null, 2));
+                break;
+            }
+            if (sub === "deregister") {
+                const op = writeOperator(ln);
+                const addr = privateKeyToAccount(pickKey()).address;
+                const ids = await workerJobIds(ln, addr);
+                if (net === "mainnet" && !process.argv.includes("--yes")) {
+                    die("deregister on mainnet may require clearing stuck jobs first (which realizes a slash). Run 'worker can-deregister' to check, then re-run with --yes.");
+                }
+                try {
+                    const r = await op.unstickAndDeregister(ids);
+                    console.log(JSON.stringify({ cleared: r.cleared.map((c) => c.jobId.toString()), released: r.released.map((c) => c.jobId.toString()), withdrawTx: r.withdrawTx ?? null, deregisterTx: r.deregisterTx }, null, 2));
+                }
+                catch (e) {
+                    if (isWorkerOpError(e))
+                        die(`deregister failed: ${e.message}`);
+                    throw e;
+                }
+                break;
+            }
             // Default: one-shot worker summary by address.
-            const addr = sub ?? die("usage: lightnode worker <address|watch|preflight> [...]");
+            const addr = sub ?? die("usage: lightnode worker <address|watch|preflight|status|can-deregister|settle|clearstuck|withdraw|deregister> [...]");
             const [w, registered, jobs] = await Promise.all([ln.getWorker(addr), ln.isRegistered(addr), ln.getWorkerJobs(addr, 5)]);
             console.log(JSON.stringify({ onchainRegistered: registered, worker: w, recentJobs: jobs.map((j) => ({ id: j.id, state: j.state })) }, null, 2));
             break;
@@ -347,7 +458,7 @@ async function main() {
                 console.log("\nNothing to do - all target files already exist. Pass --force to overwrite.");
             }
             else {
-                console.log(`\nNext steps:`);
+                console.log(`\nNext steps (these files were added to your CURRENT folder, not a new project):`);
                 console.log(`  1. ${result.install}`);
                 if (sub === "nft-mint-with-inference" || sub === "inference" || sub === "chat" || sub === "agent") {
                     console.log(`  2. cp .env.example .env  (and put a funded ${result.network} PRIVATE_KEY in it)`);
@@ -356,14 +467,14 @@ async function main() {
                         console.log(`  4. Deploy. Vercel Cron fires /api/agent on the schedule in vercel.json`);
                     }
                     else if (sub === "agent") {
-                        console.log(`  3. AGENT_INTERVAL_MS=3600000 tsx agent.ts   # or run under pm2/systemd`);
+                        console.log(`  3. AGENT_INTERVAL_MS=3600000 npx tsx agent.ts   # or run under pm2/systemd`);
                     }
                     else if (sub === "chat" && result.template === "nextjs-api") {
                         console.log(`  3. Make sure /api/inference is mounted too (run: npx lightnode add inference)`);
                         console.log(`  4. npm run dev, open /chat`);
                     }
                     else if (sub === "chat") {
-                        console.log(`  3. tsx chat-repl.ts  (interactive terminal chat)`);
+                        console.log(`  3. npx tsx chat-repl.ts  (interactive terminal chat)`);
                     }
                     else if (sub === "nft-mint-with-inference" && result.template === "nextjs-api") {
                         console.log(`  3. Make sure /api/inference is mounted too (run: npx lightnode add inference)`);
@@ -376,10 +487,10 @@ async function main() {
                         console.log(`  3. wire inferenceHandler into your Hono app, then start it`);
                     }
                     else if (sub === "nft-mint-with-inference") {
-                        console.log(`  3. tsx nft-metadata.ts "My NFT" "concept goes here"`);
+                        console.log(`  3. npx tsx nft-metadata.ts "My NFT" "concept goes here"`);
                     }
                     else {
-                        console.log(`  3. tsx lightchain-inference.ts "your prompt"`);
+                        console.log(`  3. npx tsx lightchain-inference.ts "your prompt"`);
                     }
                 }
                 else {
@@ -388,11 +499,15 @@ async function main() {
                         console.log(`  2. npm run dev, open /lightnode-analytics`);
                     }
                     else {
-                        console.log(`  2. tsx lightnode-analytics.ts`);
+                        console.log(`  2. npx tsx lightnode-analytics.ts`);
                     }
                 }
+                if (result.network === "testnet") {
+                    console.log(`\nNo wallet yet? Make one:  npx lightnode wallet new   then fund it free below.`);
+                }
                 console.log(`\nFree testnet LCAI: https://lightfaucet.ai`);
                 console.log(`Builder docs:     https://lightnode.app/build`);
+                console.log(`New to all this?  See GETTING-STARTED.md in the lightnode repo.`);
             }
             break;
         }

package/dist/index.d.ts

@@ -6,6 +6,7 @@ import { Conversation, chat } from "./chat.js";
 import { runInferenceBatch } from "./batch.js";
 import { Agent, parseAgentOutput } from "./agent.js";
 import { preflight as workerPreflight, watch as workerWatch } from "./worker.js";
+import { WorkerOperator, WORKER_REGISTRY_ABI, JOB_REGISTRY_OPERATOR_ABI, AI_CONFIG_ABI, JOB_STATE, decodeWorkerError, WorkerOpError, isWorkerOpError } from "./worker-operator.js";
 import { Bridge, BRIDGE_ROUTE, HYPERLANE_ROUTER_ABI, ERC20_ABI, addressToBytes32, quoteBridgeFee, bridgeableBalance, bridgeAllowance, approveBridge, bridgeTransfer } from "./bridge.js";
 import { DAO, DAO_ADDRESSES, ProposalState, PROPOSAL_STATE_LABEL, VoteSupport, GOVERNOR_ABI, VOTES_ABI } from "./dao.js";
 import { OnchainModelRegistry, AIVM_MODEL_REGISTRY_ABI, BENCHMARK_REGISTRY_ABI, ModelStatus, MODEL_STATUS_LABEL } from "./onchain-models.js";
@@ -90,8 +91,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.6.1";
-export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, 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, };
+export declare const SDK_VERSION = "0.7.0";
+export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, 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";
@@ -101,4 +102,5 @@ export type { WorkerPreflightArgs, WorkerPreflightResult, WorkerWatchOptions, Wo
 export type { BridgeChain, BridgeEndpoints, BridgeTransferArgs } from "./bridge.js";
 export type { DaoChain, DaoAddresses, ProposalSummary, DaoConfig } from "./dao.js";
 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, ModelInfo, NetworkStats, ModelStat, WorkerStat, NetworkAnalytics };

package/dist/index.js

@@ -7,6 +7,7 @@ import { Conversation, chat } from "./chat.js";
 import { runInferenceBatch } from "./batch.js";
 import { Agent, parseAgentOutput } from "./agent.js";
 import { preflight as workerPreflight, watch as workerWatch } from "./worker.js";
+import { WorkerOperator, WORKER_REGISTRY_ABI, JOB_REGISTRY_OPERATOR_ABI, AI_CONFIG_ABI, JOB_STATE, decodeWorkerError, WorkerOpError, isWorkerOpError, } from "./worker-operator.js";
 import { Bridge, BRIDGE_ROUTE, HYPERLANE_ROUTER_ABI, ERC20_ABI, addressToBytes32, quoteBridgeFee, bridgeableBalance, bridgeAllowance, approveBridge, bridgeTransfer, } from "./bridge.js";
 import { DAO, DAO_ADDRESSES, ProposalState, PROPOSAL_STATE_LABEL, VoteSupport, GOVERNOR_ABI, VOTES_ABI, } from "./dao.js";
 import { OnchainModelRegistry, AIVM_MODEL_REGISTRY_ABI, BENCHMARK_REGISTRY_ABI, ModelStatus, MODEL_STATUS_LABEL, } from "./onchain-models.js";
@@ -145,7 +146,7 @@ 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.6.1";
+export const SDK_VERSION = "0.7.0";
 export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, 
 // v0.3 inference-submit surface (BETA - see README "Submitting inference").
 GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, 
@@ -168,4 +169,8 @@ Bridge, BRIDGE_ROUTE, HYPERLANE_ROUTER_ABI, ERC20_ABI, addressToBytes32, quoteBr
 // v0.5.0 DAO SDK (LCAIGovernor wrapper on Ethereum mainnet).
 DAO, DAO_ADDRESSES, ProposalState, PROPOSAL_STATE_LABEL, VoteSupport, GOVERNOR_ABI, VOTES_ABI, 
 // v0.5.0 On-chain model registry reader (AIVMModelRegistry + BenchmarkRegistry).
-OnchainModelRegistry, AIVM_MODEL_REGISTRY_ABI, BENCHMARK_REGISTRY_ABI, ModelStatus, MODEL_STATUS_LABEL, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, };
+OnchainModelRegistry, AIVM_MODEL_REGISTRY_ABI, BENCHMARK_REGISTRY_ABI, ModelStatus, MODEL_STATUS_LABEL, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, 
+// v0.7.0 worker-OPERATOR surface: the write/ops side (stuck-job recovery,
+// Docker-free settle/exit, revert decoding, live config). Complements the
+// read-only worker preflight/watch above; does not duplicate it.
+WorkerOperator, WORKER_REGISTRY_ABI, JOB_REGISTRY_OPERATOR_ABI, AI_CONFIG_ABI, JOB_STATE, decodeWorkerError, WorkerOpError, isWorkerOpError, };

package/dist/worker-operator.d.ts

@@ -0,0 +1,336 @@
+/**
+ * Worker-OPERATOR module - the write/ops side of running a LightChain worker.
+ *
+ * The published `lightnode-sdk` is read-only (observe a worker) and the existing
+ * `worker.ts` does remote preflight/watch. This module is different: it performs
+ * the on-chain OPERATOR actions that, today, are either impossible from code or
+ * require the multi-GB worker Docker image and reverse-engineering unverified
+ * contracts. It is deliberately NOT a re-wrap of the worker toolkit's happy path:
+ *
+ *   1. Stuck-job recovery  - claimTimeout / clearStuck / unstickAndDeregister.
+ *      The toolkit, the daemon, AND the published SDK all lack this. claimTimeout
+ *      is permissionless on-chain (verified), so an operator CAN self-clear the
+ *      acknowledged-but-never-completed jobs that block deregister. Nothing else
+ *      exposes it.
+ *   2. Revert decoding     - the WorkerRegistry/JobRegistry custom errors aren't
+ *      even in the 4byte directory; decodeWorkerError turns them into a sentence
+ *      plus the fix.
+ *   3. Pre-flight gating   - canDeregister()/simulate tell you a tx will revert,
+ *      and WHY, before you spend gas.
+ *   4. Docker-free settle+exit - deregister/releaseJob/withdraw/stake ops over
+ *      pure RPC, from a laptop / CI / server, with no worker image running.
+ *   5. Real economics      - settled vs pending, claimable, profitability (net of
+ *      gas), forecast - joins subgraph + on-chain workerBalance + window math.
+ *   6. Live protocol config - the AIConfig stake/timeouts/slash-bps/fee-split, so
+ *      nobody hardcodes "50,000" again.
+ *   7. Typed getJob/getSession - the exact struct layouts (no published ABI).
+ *
+ * Conventions match the rest of the SDK: viem writes via a structural
+ * `MinimalWalletClient` (viem stays a soft dep), `NETWORKS` for config, the
+ * errors.ts class+guard style. Reuses `crypto.ts` for P-256 / AES-GCM.
+ *
+ * Source of truth for selectors/structs/errors: verified live on mainnet 9200 +
+ * the official worker Go bindings. JobRegistry/WorkerRegistry impls are
+ * UNVERIFIED on the explorer, so this is pinned to a snapshot - treat as 0.x and
+ * lean on decodeWorkerError() to surface any future drift instead of failing
+ * silently.
+ */
+import type { NetworkConfig, NetworkId } from "./types.js";
+export interface MinimalWalletClient {
+    writeContract: (args: {
+        address: `0x${string}`;
+        abi: readonly unknown[];
+        functionName: string;
+        args: readonly unknown[];
+        value?: bigint;
+        gas?: bigint;
+    }) => Promise<`0x${string}`>;
+    account?: {
+        address?: `0x${string}`;
+    } | `0x${string}`;
+}
+export interface MinimalPublicClient {
+    readContract: (args: {
+        address: `0x${string}`;
+        abi: readonly unknown[];
+        functionName: string;
+        args?: readonly unknown[];
+    }) => Promise<unknown>;
+    waitForTransactionReceipt: (args: {
+        hash: `0x${string}`;
+    }) => Promise<{
+        status: "success" | "reverted";
+        blockNumber: bigint;
+        gasUsed?: bigint;
+        effectiveGasPrice?: bigint;
+    }>;
+    simulateContract?: (args: {
+        address: `0x${string}`;
+        abi: readonly unknown[];
+        functionName: string;
+        args?: readonly unknown[];
+        account?: `0x${string}`;
+        value?: bigint;
+    }) => Promise<unknown>;
+}
+/** WorkerRegistry (genesis predeploy 0x...1002). Operator + stake surface. */
+export declare const WORKER_REGISTRY_ABI: readonly ["function registerWorker(bytes encryptionPubKey) payable", "function deregisterWorker()", "function addSupportedModel(bytes32 modelId)", "function removeSupportedModel(bytes32 modelId)", "function topUpStake() payable", "function withdrawStake(uint256 amount)", "function reinstate()", "function isWorkerRegistered(address worker) view returns (bool)", "function getWorkerStake(address worker) view returns (uint256)", "function getWorkerEncryptionKey(address worker) view returns (bytes)", "function getMinWorkerStake() view returns (uint256)", "function isEligible(address worker, bytes32 modelId) view returns (bool)"];
+/** JobRegistry (proxy). Job lifecycle + settlement + the timeout primitive.
+ *  The Job struct is a named human-readable struct (abitype needs a named
+ *  struct, not an inline `tuple(...)`, for the getJob return). */
+export declare const JOB_REGISTRY_OPERATOR_ABI: readonly ["struct Job { uint256 jobId; address worker; uint8 state; uint256 escrowedFee; bytes32 promptBlobHash; bytes32 responseBlobHash; uint64 submittedAt; uint64 ackAt; uint64 completedAt; uint64 deadlineAt; uint256 r10; uint256 r11; uint256 r12; uint256 r13; uint256 r14; uint256 r15; uint256 submitBlockNumber; uint256 completionBlockNumber; }", "function acknowledgeJob(uint256 jobId)", "function completeJob(uint256 jobId, bytes32 responseBlobHash, bytes32 responseCiphertextHash)", "function releaseJob(uint256 jobId)", "function releaseJobs(uint256[] jobIds)", "function claimTimeout(uint256 jobId)", "function withdraw()", "function workerBalance(address worker) view returns (uint256)", "function getJob(uint256 jobId) view returns (Job)"];
+/** AIConfig (verified ABI). Live protocol parameters. */
+export declare const AI_CONFIG_ABI: readonly ["function getMinWorkerStake() view returns (uint256)", "function getCompletionTimeout() view returns (uint256)", "function getAckTimeout() view returns (uint256)", "function getResolutionTimeout() view returns (uint256)", "function getDisputeWindow() view returns (uint256)", "function getTimeoutSlashBps() view returns (uint256)", "function getCompletionTimeoutSlashBps() view returns (uint256)", "function getDisputeSlashBps() view returns (uint256)", "function getMaxSlashBps() view returns (uint256)", "function getProtocolFeeBps() view returns (uint256)", "function getWorkerFeeBps() view returns (uint256)", "function getFeePoolBps() view returns (uint256)", "function getSuspensionThreshold() view returns (uint256)", "function getSuspensionCooldown() view returns (uint256)", "function getModelFee(bytes32 modelId) view returns (uint256)", "function isModelEnabled(bytes32 modelId) view returns (bool)"];
+/** On-chain JobState. Order is ABI-load-bearing - do not reorder. */
+export declare const JOB_STATE: readonly ["Submitted", "Acknowledged", "Completed", "TimedOut", "Disputed", "Resolved", "Released"];
+export type JobState = (typeof JOB_STATE)[number];
+export interface OnchainJob {
+    jobId: bigint;
+    worker: `0x${string}`;
+    state: JobState;
+    /** Raw enum index, in case a future contract adds states. */
+    stateIndex: number;
+    escrowedFeeWei: bigint;
+    promptBlobHash: `0x${string}`;
+    responseBlobHash: `0x${string}`;
+    submittedAt: number;
+    ackAt: number;
+    completedAt: number;
+    deadlineAt: number;
+    submitBlockNumber: bigint;
+    completionBlockNumber: bigint;
+}
+export interface DecodedWorkerError {
+    /** 4-byte selector, e.g. "0x592f994b". */
+    selector: `0x${string}`;
+    /** Solidity error name, or "Unknown" when unrecognized. */
+    name: string;
+    /** Decoded args, best-effort (uint/address words). */
+    args: Array<string | bigint>;
+    /** Plain-English explanation + the fix. */
+    message: string;
+}
+/**
+ * Decode raw revert data (the `data: "0x.."` from an eth_call/estimateGas
+ * failure) into a named, explained error. Falls back to {name:"Unknown"} so the
+ * caller always gets *something* even if the contract drifts.
+ */
+export declare function decodeWorkerError(revertData: string | null | undefined): DecodedWorkerError;
+/**
+ * Operator-side typed error (mirrors the errors.ts convention: named class +
+ * readonly fields + an `is...` guard). Carries the decoded contract error.
+ */
+export declare class WorkerOpError extends Error {
+    readonly op: string;
+    readonly decoded?: DecodedWorkerError;
+    readonly tx?: `0x${string}`;
+    constructor(op: string, message: string, opts?: {
+        decoded?: DecodedWorkerError;
+        tx?: `0x${string}`;
+    });
+}
+export declare function isWorkerOpError(e: unknown): e is WorkerOpError;
+/** Live AIConfig protocol parameters (read from chain, never hardcoded). */
+export interface WorkerProtocolConfig {
+    minStakeWei: bigint;
+    minStakeLcai: number;
+    completionTimeoutSec: number;
+    ackTimeoutSec: number;
+    resolutionTimeoutSec: number;
+    disputeWindowSec: number;
+    /** Slash basis points: ack-timeout, completion-timeout, dispute, max cap. */
+    slashBps: {
+        ackTimeout: number;
+        completionTimeout: number;
+        dispute: number;
+        max: number;
+    };
+    /** Fee split basis points (protocol/worker/feePool sum to 10000). */
+    feeBps: {
+        protocol: number;
+        worker: number;
+        feePool: number;
+    };
+    suspensionThreshold: number;
+    suspensionCooldownSec: number;
+}
+export interface WorkerStatus {
+    address: `0x${string}`;
+    registered: boolean;
+    stakeWei: bigint;
+    stakeLcai: number;
+    minStakeWei: bigint;
+    /** stake - minStake, in LCAI (negative = below floor / deactivated). */
+    headroomLcai: number;
+    belowFloor: boolean;
+    /** Claimable worker balance in the JobRegistry (earned, not yet withdrawn). */
+    claimableWei: bigint;
+    claimableLcai: number;
+}
+export interface DeregisterReadiness {
+    ok: boolean;
+    /** Job IDs blocking deregistration (in-flight / acked-incomplete). */
+    blockedBy: bigint[];
+    reason: string;
+}
+export interface StuckJob {
+    /**
+     * The ID to pass to claimTimeout/getJob - i.e. the SAME id you looked the job
+     * up by (the subgraph/display id). IMPORTANT: this is NOT the struct's internal
+     * `jobId` field, which is a different counter; calling claimTimeout with the
+     * struct field hits the wrong job. Always use this lookupId for writes.
+     */
+    lookupId: bigint;
+    /** The struct's internal jobId field (informational; do NOT use for writes). */
+    jobId: bigint;
+    state: JobState;
+    ackAt: number;
+    /** Seconds past the completion deadline (>0 means claimTimeout is eligible). */
+    pastDeadlineSec: number;
+    escrowedFeeWei: bigint;
+}
+export interface EarningsBreakdown {
+    /** Already withdrawn-able now (in the JobRegistry workerBalance). */
+    claimableLcai: number;
+    /** Lifetime earned (from the subgraph total_earned). */
+    lifetimeLcai: number;
+    /** Completed jobs awaiting their release window before they pay out. */
+    pendingReleaseCount: number;
+    jobsCompleted: number;
+    jobsTimedOut: number;
+}
+export interface WorkerOperatorOpts {
+    publicClient: MinimalPublicClient;
+    /** Required for writes (register/deregister/release/claimTimeout/withdraw/stake). */
+    walletClient?: MinimalWalletClient;
+    /** Worker address. Defaults to walletClient.account.address when present. */
+    workerAddress?: `0x${string}`;
+}
+export declare class WorkerOperator {
+    readonly network: NetworkConfig;
+    private readonly pub;
+    private readonly wallet?;
+    private readonly addr;
+    private cfgCache?;
+    constructor(network: NetworkId | NetworkConfig, opts: WorkerOperatorOpts);
+    private requireWallet;
+    private get jobReg();
+    private get workerReg();
+    private read;
+    /** Send a write and wait for the receipt, decoding any revert into a WorkerOpError. */
+    private send;
+    /** Live AIConfig parameters (cached after first read). */
+    config(): Promise<WorkerProtocolConfig>;
+    /** One-call worker status: registration, stake, floor, claimable balance. */
+    status(): Promise<WorkerStatus>;
+    /** Typed on-chain job (the struct layout has no published ABI). */
+    getJob(jobId: bigint | number): Promise<OnchainJob>;
+    /**
+     * Jobs this worker acknowledged but never completed that are now past the
+     * completion deadline - the ones that block deregister and are clearable via
+     * claimTimeout. Needs the worker's job IDs (from the subgraph / LightNode
+     * client); on-chain there is no enumerator. Pass the candidate IDs in.
+     */
+    stuckJobs(candidateJobIds: Array<bigint | number>): Promise<StuckJob[]>;
+    /**
+     * Clear one stuck (acknowledged-but-never-completed, past-deadline) job.
+     * Permissionless on-chain - the worker itself may call it.
+     *
+     * ⚠️ MAINNET SLASH: this finalizes the job as TimedOut, which realizes the
+     * completion-timeout slash on the worker's stake (mainnet:
+     * `config().slashBps.completionTimeout` = 5% of stake per job at the time of
+     * writing; TESTNET has slashing disabled, so it's free there). This is the
+     * deliberate price of unblocking deregister - a stuck acked job otherwise
+     * blocks the exit forever. Call `config()` first to see the live slash bps, and
+     * only clear jobs you've accepted are lost. Verify eligibility with
+     * `stuckJobs([id])` (pastDeadlineSec > 0) before calling.
+     */
+    claimTimeout(jobId: bigint | number): Promise<`0x${string}`>;
+    /**
+     * Clear every past-deadline acked job in `candidateJobIds`. Returns the txs and
+     * the IDs it skipped (not stuck / not past deadline). Each cleared job realizes
+     * its completion-timeout slash - see slashBps.completionTimeout in config().
+     */
+    clearStuck(candidateJobIds: Array<bigint | number>): Promise<{
+        cleared: Array<{
+            jobId: bigint;
+            tx: `0x${string}`;
+        }>;
+        skipped: bigint[];
+    }>;
+    /**
+     * Will deregister succeed right now? Reads the active-job count by checking the
+     * candidate IDs (on-chain there's no enumerator, so pass the worker's job IDs).
+     * Returns the blocking job IDs and a human reason - BEFORE you spend gas.
+     */
+    canDeregister(candidateJobIds?: Array<bigint | number>): Promise<DeregisterReadiness>;
+    /** Settle one completed job past its dispute window. Permissionless. */
+    releaseJob(jobId: bigint | number): Promise<`0x${string}`>;
+    /**
+     * Settle every releasable completed job in `candidateJobIds`. Skips jobs still
+     * inside the dispute window (DisputeWindowNotElapsed) rather than failing the
+     * batch - uses per-job calls so one not-ready job can't revert the rest.
+     */
+    releaseAll(candidateJobIds: Array<bigint | number>): Promise<{
+        released: Array<{
+            jobId: bigint;
+            tx: `0x${string}`;
+        }>;
+        notReady: bigint[];
+    }>;
+    /** Pull the worker's earned balance from the JobRegistry into the wallet. */
+    withdraw(): Promise<`0x${string}`>;
+    /** Deregister - releases stake to the wallet. Reverts (ActiveJobsExist) if any in-flight job remains. */
+    deregister(): Promise<`0x${string}`>;
+    /**
+     * The flagship rescue: clear stuck jobs → release any settled completed jobs +
+     * withdraw earnings → deregister. The one flow no official tool provides.
+     * Pass the worker's known job IDs (from the subgraph). Returns every tx done.
+     */
+    unstickAndDeregister(candidateJobIds: Array<bigint | number>): Promise<{
+        cleared: Array<{
+            jobId: bigint;
+            tx: `0x${string}`;
+        }>;
+        released: Array<{
+            jobId: bigint;
+            tx: `0x${string}`;
+        }>;
+        withdrawTx?: `0x${string}`;
+        deregisterTx: `0x${string}`;
+    }>;
+    topUpStake(lcai: number): Promise<`0x${string}`>;
+    withdrawStake(lcai: number): Promise<`0x${string}`>;
+    reinstate(): Promise<`0x${string}`>;
+    /**
+     * Earnings breakdown: claimable-now (on-chain workerBalance) plus lifetime +
+     * pending-release counts derived from the worker record + its jobs. The caller
+     * passes the subgraph-sourced worker record and jobs (e.g. from LightNode) so
+     * this module stays free of a GraphQL dependency.
+     */
+    earnings(input: {
+        lifetimeEarnedWei?: bigint | string;
+        jobsCompleted?: number;
+        jobsTimedOut?: number;
+        jobs?: Array<{
+            state: string;
+        }>;
+    }): Promise<EarningsBreakdown>;
+    /**
+     * Net profitability: per-job worker fee (from live AIConfig fee split + the
+     * model fee) minus an estimated gas cost per job. Pure math over live config so
+     * an operator can answer "is this worth running" without a spreadsheet.
+     */
+    profitability(input: {
+        modelTag?: string;
+        modelFeeWei?: bigint;
+        gasPerJobLcai?: number;
+        jobsPerDay?: number;
+    }): Promise<{
+        workerFeeLcaiPerJob: number;
+        gasLcaiPerJob: number;
+        netLcaiPerJob: number;
+        breakEvenJobsPerDay: number | null;
+        projectedDailyLcai: number | null;
+    }>;
+}

package/dist/worker-operator.js

@@ -0,0 +1,590 @@
+/**
+ * Worker-OPERATOR module - the write/ops side of running a LightChain worker.
+ *
+ * The published `lightnode-sdk` is read-only (observe a worker) and the existing
+ * `worker.ts` does remote preflight/watch. This module is different: it performs
+ * the on-chain OPERATOR actions that, today, are either impossible from code or
+ * require the multi-GB worker Docker image and reverse-engineering unverified
+ * contracts. It is deliberately NOT a re-wrap of the worker toolkit's happy path:
+ *
+ *   1. Stuck-job recovery  - claimTimeout / clearStuck / unstickAndDeregister.
+ *      The toolkit, the daemon, AND the published SDK all lack this. claimTimeout
+ *      is permissionless on-chain (verified), so an operator CAN self-clear the
+ *      acknowledged-but-never-completed jobs that block deregister. Nothing else
+ *      exposes it.
+ *   2. Revert decoding     - the WorkerRegistry/JobRegistry custom errors aren't
+ *      even in the 4byte directory; decodeWorkerError turns them into a sentence
+ *      plus the fix.
+ *   3. Pre-flight gating   - canDeregister()/simulate tell you a tx will revert,
+ *      and WHY, before you spend gas.
+ *   4. Docker-free settle+exit - deregister/releaseJob/withdraw/stake ops over
+ *      pure RPC, from a laptop / CI / server, with no worker image running.
+ *   5. Real economics      - settled vs pending, claimable, profitability (net of
+ *      gas), forecast - joins subgraph + on-chain workerBalance + window math.
+ *   6. Live protocol config - the AIConfig stake/timeouts/slash-bps/fee-split, so
+ *      nobody hardcodes "50,000" again.
+ *   7. Typed getJob/getSession - the exact struct layouts (no published ABI).
+ *
+ * Conventions match the rest of the SDK: viem writes via a structural
+ * `MinimalWalletClient` (viem stays a soft dep), `NETWORKS` for config, the
+ * errors.ts class+guard style. Reuses `crypto.ts` for P-256 / AES-GCM.
+ *
+ * Source of truth for selectors/structs/errors: verified live on mainnet 9200 +
+ * the official worker Go bindings. JobRegistry/WorkerRegistry impls are
+ * UNVERIFIED on the explorer, so this is pinned to a snapshot - treat as 0.x and
+ * lean on decodeWorkerError() to surface any future drift instead of failing
+ * silently.
+ */
+import { parseAbi } from "viem";
+import { NETWORKS } from "./networks.js";
+// ===========================================================================
+// ABIs - minimal, operator-facing. Verified selectors (see module header).
+// Human-readable strings; viem parseAbi-compatible if the caller wants typing.
+// ===========================================================================
+/** WorkerRegistry (genesis predeploy 0x...1002). Operator + stake surface. */
+export const WORKER_REGISTRY_ABI = [
+    "function registerWorker(bytes encryptionPubKey) payable",
+    "function deregisterWorker()",
+    "function addSupportedModel(bytes32 modelId)",
+    "function removeSupportedModel(bytes32 modelId)",
+    "function topUpStake() payable",
+    "function withdrawStake(uint256 amount)",
+    "function reinstate()",
+    "function isWorkerRegistered(address worker) view returns (bool)",
+    "function getWorkerStake(address worker) view returns (uint256)",
+    "function getWorkerEncryptionKey(address worker) view returns (bytes)",
+    "function getMinWorkerStake() view returns (uint256)",
+    "function isEligible(address worker, bytes32 modelId) view returns (bool)",
+];
+/** JobRegistry (proxy). Job lifecycle + settlement + the timeout primitive.
+ *  The Job struct is a named human-readable struct (abitype needs a named
+ *  struct, not an inline `tuple(...)`, for the getJob return). */
+export const JOB_REGISTRY_OPERATOR_ABI = [
+    "struct Job { uint256 jobId; address worker; uint8 state; uint256 escrowedFee; bytes32 promptBlobHash; bytes32 responseBlobHash; uint64 submittedAt; uint64 ackAt; uint64 completedAt; uint64 deadlineAt; uint256 r10; uint256 r11; uint256 r12; uint256 r13; uint256 r14; uint256 r15; uint256 submitBlockNumber; uint256 completionBlockNumber; }",
+    "function acknowledgeJob(uint256 jobId)",
+    "function completeJob(uint256 jobId, bytes32 responseBlobHash, bytes32 responseCiphertextHash)",
+    "function releaseJob(uint256 jobId)",
+    "function releaseJobs(uint256[] jobIds)",
+    "function claimTimeout(uint256 jobId)",
+    "function withdraw()",
+    "function workerBalance(address worker) view returns (uint256)",
+    "function getJob(uint256 jobId) view returns (Job)",
+];
+/** AIConfig (verified ABI). Live protocol parameters. */
+export const AI_CONFIG_ABI = [
+    "function getMinWorkerStake() view returns (uint256)",
+    "function getCompletionTimeout() view returns (uint256)",
+    "function getAckTimeout() view returns (uint256)",
+    "function getResolutionTimeout() view returns (uint256)",
+    "function getDisputeWindow() view returns (uint256)",
+    "function getTimeoutSlashBps() view returns (uint256)",
+    "function getCompletionTimeoutSlashBps() view returns (uint256)",
+    "function getDisputeSlashBps() view returns (uint256)",
+    "function getMaxSlashBps() view returns (uint256)",
+    "function getProtocolFeeBps() view returns (uint256)",
+    "function getWorkerFeeBps() view returns (uint256)",
+    "function getFeePoolBps() view returns (uint256)",
+    "function getSuspensionThreshold() view returns (uint256)",
+    "function getSuspensionCooldown() view returns (uint256)",
+    "function getModelFee(bytes32 modelId) view returns (uint256)",
+    "function isModelEnabled(bytes32 modelId) view returns (bool)",
+];
+// viem's readContract/writeContract need a PARSED ABI (objects), not the
+// human-readable strings above. We keep the strings exported for readability and
+// parse them once here for the actual on-chain calls.
+const WORKER_REGISTRY_ABI_PARSED = parseAbi(WORKER_REGISTRY_ABI);
+const JOB_REGISTRY_OPERATOR_ABI_PARSED = parseAbi(JOB_REGISTRY_OPERATOR_ABI);
+const AI_CONFIG_ABI_PARSED = parseAbi(AI_CONFIG_ABI);
+// ===========================================================================
+// Enums + struct types (pinned from the worker Go bindings + live decode).
+// ===========================================================================
+/** On-chain JobState. Order is ABI-load-bearing - do not reorder. */
+export const JOB_STATE = [
+    "Submitted",
+    "Acknowledged",
+    "Completed",
+    "TimedOut",
+    "Disputed",
+    "Resolved",
+    "Released",
+];
+/** selector -> spec. Verified against live reverts on mainnet 9200. */
+const WORKER_ERROR_TABLE = {
+    "0x592f994b": {
+        name: "ActiveJobsExist",
+        types: ["address", "uint256"],
+        explain: (a) => `Can't deregister/withdraw yet: this worker still has ${a[1]} in-flight job(s) on-chain. ` +
+            `Clear them first - acknowledged-but-unfinished jobs are cleared with claimTimeout (clearStuck() does this), ` +
+            `then deregister succeeds.`,
+    },
+    "0xcb9a70eb": {
+        name: "WorkerNotRegistered",
+        types: ["address"],
+        explain: (a) => `Address ${a[0]} is not a registered worker (or the job/worker referenced doesn't exist). ` +
+            `Register first, or check you're using the worker's own key.`,
+    },
+    "0x98f5b6c5": {
+        name: "DisputeWindowNotElapsed",
+        types: ["uint256", "uint256", "uint256"],
+        explain: (a) => {
+            const releaseAt = Number(a[1] ?? 0);
+            const now = Number(a[2] ?? 0);
+            const mins = releaseAt > now ? Math.ceil((releaseAt - now) / 60) : 0;
+            return (`Job ${a[0]} isn't releasable yet - it's still inside the dispute window. ` +
+                (mins ? `Releasable in ~${mins} min (at unix ${releaseAt}). ` : "") +
+                `releaseAll() skips jobs that aren't ready; retry later.`);
+        },
+    },
+    "0x45be0a26": {
+        name: "InsufficientStake",
+        types: ["uint256", "uint256"],
+        explain: (a) => `Insufficient stake: requested ${a[0]} but only ${a[1]} is available above the minimum. ` +
+            `Withdraw less, or you're below the floor - topUpStake() then reinstate().`,
+    },
+    "0x50c83b95": {
+        name: "JobNotFound",
+        types: ["uint256"],
+        explain: (a) => `Job ${a[0]} does not exist on this network.`,
+    },
+    "0x95e2fa37": {
+        name: "SessionNotFound",
+        types: ["uint256"],
+        explain: (a) => `Session ${a[0]} does not exist on this network.`,
+    },
+    "0x149ce097": {
+        name: "SessionNotActive",
+        types: ["uint256"],
+        explain: (a) => `Session ${a[0]} is not Active (closed or expired).`,
+    },
+    "0xa458261b": {
+        name: "InsufficientFee",
+        types: ["uint256", "uint256"],
+        explain: (a) => `Underfunded: sent ${a[0]} wei but ${a[1]} is required.`,
+    },
+    "0xe06b2da5": {
+        name: "NoBalanceToWithdraw",
+        types: ["address"],
+        explain: (a) => `Nothing to withdraw - ${a[0]} has a zero worker balance in the JobRegistry.`,
+    },
+    "0x4a0bfec1": {
+        name: "NotAuthorized",
+        types: ["address"],
+        explain: (a) => `${a[0]} is not authorized for this action (disputer/dispatcher-gated).`,
+    },
+};
+/** Read a 32-byte ABI word at slot i from hex data (after the 4-byte selector). */
+function wordAt(dataNo0x, i) {
+    return dataNo0x.slice(i * 64, i * 64 + 64);
+}
+/**
+ * Decode raw revert data (the `data: "0x.."` from an eth_call/estimateGas
+ * failure) into a named, explained error. Falls back to {name:"Unknown"} so the
+ * caller always gets *something* even if the contract drifts.
+ */
+export function decodeWorkerError(revertData) {
+    const data = (revertData ?? "").toLowerCase();
+    if (!data.startsWith("0x") || data.length < 10) {
+        return { selector: "0x", name: "Unknown", args: [], message: "No revert data to decode." };
+    }
+    const selector = data.slice(0, 10);
+    const spec = WORKER_ERROR_TABLE[selector];
+    const body = data.slice(10);
+    if (!spec) {
+        return {
+            selector,
+            name: "Unknown",
+            args: [],
+            message: `Unrecognized revert ${selector}. The worker contracts are unverified and may have changed; check the explorer.`,
+        };
+    }
+    const args = spec.types.map((t, i) => {
+        const w = wordAt(body, i);
+        if (!w)
+            return t === "address" ? "0x" : 0n;
+        if (t === "address")
+            return (`0x${w.slice(24)}`);
+        return BigInt(`0x${w || "0"}`);
+    });
+    return { selector, name: spec.name, args, message: spec.explain(args) };
+}
+/**
+ * Operator-side typed error (mirrors the errors.ts convention: named class +
+ * readonly fields + an `is...` guard). Carries the decoded contract error.
+ */
+export class WorkerOpError extends Error {
+    constructor(op, message, opts) {
+        super(message);
+        this.name = "WorkerOpError";
+        this.op = op;
+        this.decoded = opts?.decoded;
+        this.tx = opts?.tx;
+    }
+}
+export function isWorkerOpError(e) {
+    return e instanceof WorkerOpError;
+}
+/** Pull the `data:` revert blob out of a viem/provider error of unknown shape. */
+function extractRevertData(err) {
+    const seen = new Set();
+    const walk = (o) => {
+        if (!o || typeof o !== "object" || seen.has(o))
+            return undefined;
+        seen.add(o);
+        const rec = o;
+        for (const k of ["data", "raw"]) {
+            const v = rec[k];
+            if (typeof v === "string" && /^0x[0-9a-fA-F]{8,}$/.test(v))
+                return v;
+            if (v && typeof v === "object") {
+                const inner = v.data;
+                if (typeof inner === "string" && /^0x[0-9a-fA-F]{8,}$/.test(inner))
+                    return inner;
+            }
+        }
+        for (const k of ["cause", "error", "details", "walk"]) {
+            const found = walk(rec[k]);
+            if (found)
+                return found;
+        }
+        return undefined;
+    };
+    return walk(err);
+}
+// ===========================================================================
+// Config + helpers
+// ===========================================================================
+const BPS = 10000n;
+const toLcai = (wei) => Number(wei) / 1e18;
+const toWeiFromLcai = (lcai) => BigInt(Math.round(lcai * 1e18));
+function normalizeJob(raw) {
+    // viem returns the tuple either as an array or an object depending on ABI form.
+    const t = raw;
+    const get = (k, i) => (Array.isArray(t) ? t[i] : t[k]);
+    const idx = Number(get("state", 2) ?? 0);
+    return {
+        jobId: BigInt(get("jobId", 0) ?? 0),
+        worker: get("worker", 1) ?? "0x",
+        state: JOB_STATE[idx] ?? "Submitted",
+        stateIndex: idx,
+        escrowedFeeWei: BigInt(get("escrowedFee", 3) ?? 0),
+        promptBlobHash: get("promptBlobHash", 4) ?? "0x",
+        responseBlobHash: get("responseBlobHash", 5) ?? "0x",
+        submittedAt: Number(get("submittedAt", 6) ?? 0),
+        ackAt: Number(get("ackAt", 7) ?? 0),
+        completedAt: Number(get("completedAt", 8) ?? 0),
+        deadlineAt: Number(get("deadlineAt", 9) ?? 0),
+        submitBlockNumber: BigInt(get("submitBlockNumber", 16) ?? 0),
+        completionBlockNumber: BigInt(get("completionBlockNumber", 17) ?? 0),
+    };
+}
+export class WorkerOperator {
+    constructor(network, opts) {
+        this.network = typeof network === "string" ? NETWORKS[network] : network;
+        if (!this.network)
+            throw new Error(`WorkerOperator: unknown network ${String(network)}`);
+        this.pub = opts.publicClient;
+        this.wallet = opts.walletClient;
+        const acct = opts.walletClient?.account;
+        const fromWallet = typeof acct === "string" ? acct : acct?.address;
+        const a = (opts.workerAddress ?? fromWallet);
+        if (!a)
+            throw new Error("WorkerOperator: provide workerAddress or a walletClient with an account");
+        this.addr = a.toLowerCase();
+    }
+    requireWallet(op) {
+        if (!this.wallet)
+            throw new WorkerOpError(op, `${op} needs a walletClient - construct WorkerOperator with one.`);
+        return this.wallet;
+    }
+    get jobReg() {
+        return this.network.jobRegistry;
+    }
+    get workerReg() {
+        return this.network.workerRegistry;
+    }
+    async read(address, abi, functionName, args = []) {
+        return this.pub.readContract({ address, abi, functionName, args });
+    }
+    /** Send a write and wait for the receipt, decoding any revert into a WorkerOpError. */
+    async send(op, address, abi, functionName, args, value) {
+        const wallet = this.requireWallet(op);
+        let tx;
+        try {
+            tx = await wallet.writeContract({ address, abi, functionName, args, ...(value !== undefined ? { value } : {}) });
+        }
+        catch (err) {
+            const decoded = decodeWorkerError(extractRevertData(err));
+            throw new WorkerOpError(op, `${op} reverted before broadcast: ${decoded.message}`, { decoded });
+        }
+        const receipt = await this.pub.waitForTransactionReceipt({ hash: tx });
+        if (receipt.status !== "success") {
+            throw new WorkerOpError(op, `${op} reverted on-chain (tx=${tx})`, { tx });
+        }
+        return tx;
+    }
+    // ---- 6) Live protocol config -------------------------------------------
+    /** Live AIConfig parameters (cached after first read). */
+    async config() {
+        if (this.cfgCache)
+            return this.cfgCache;
+        const a = this.network.aiConfig;
+        const r = (fn) => this.read(a, AI_CONFIG_ABI_PARSED, fn);
+        const [minStake, completion, ack, resolution, dispute, ackSlash, compSlash, dispSlash, maxSlash, protoFee, workerFee, poolFee, suspThresh, suspCool,] = await Promise.all([
+            r("getMinWorkerStake"),
+            r("getCompletionTimeout"),
+            r("getAckTimeout"),
+            r("getResolutionTimeout"),
+            r("getDisputeWindow"),
+            r("getTimeoutSlashBps"),
+            r("getCompletionTimeoutSlashBps"),
+            r("getDisputeSlashBps"),
+            r("getMaxSlashBps"),
+            r("getProtocolFeeBps"),
+            r("getWorkerFeeBps"),
+            r("getFeePoolBps"),
+            r("getSuspensionThreshold"),
+            r("getSuspensionCooldown"),
+        ]);
+        this.cfgCache = {
+            minStakeWei: minStake,
+            minStakeLcai: toLcai(minStake),
+            completionTimeoutSec: Number(completion),
+            ackTimeoutSec: Number(ack),
+            resolutionTimeoutSec: Number(resolution),
+            disputeWindowSec: Number(dispute),
+            slashBps: {
+                ackTimeout: Number(ackSlash),
+                completionTimeout: Number(compSlash),
+                dispute: Number(dispSlash),
+                max: Number(maxSlash),
+            },
+            feeBps: { protocol: Number(protoFee), worker: Number(workerFee), feePool: Number(poolFee) },
+            suspensionThreshold: Number(suspThresh),
+            suspensionCooldownSec: Number(suspCool),
+        };
+        return this.cfgCache;
+    }
+    // ---- status / reads -----------------------------------------------------
+    /** One-call worker status: registration, stake, floor, claimable balance. */
+    async status() {
+        // minStake is sourced from AIConfig (verified live on BOTH networks), not
+        // WorkerRegistry.getMinWorkerStake - the testnet WorkerRegistry impl differs
+        // and reverts that getter. AIConfig is the canonical source either way.
+        const [registered, stakeWei, minStakeWei, claimableWei] = await Promise.all([
+            this.read(this.workerReg, WORKER_REGISTRY_ABI_PARSED, "isWorkerRegistered", [this.addr]),
+            this.read(this.workerReg, WORKER_REGISTRY_ABI_PARSED, "getWorkerStake", [this.addr]),
+            this.read(this.network.aiConfig, AI_CONFIG_ABI_PARSED, "getMinWorkerStake"),
+            this.read(this.jobReg, JOB_REGISTRY_OPERATOR_ABI_PARSED, "workerBalance", [this.addr]),
+        ]);
+        const headroomLcai = toLcai(stakeWei - minStakeWei);
+        return {
+            address: this.addr,
+            registered,
+            stakeWei,
+            stakeLcai: toLcai(stakeWei),
+            minStakeWei,
+            headroomLcai,
+            belowFloor: registered && stakeWei < minStakeWei,
+            claimableWei,
+            claimableLcai: toLcai(claimableWei),
+        };
+    }
+    // ---- 7) Typed getJob ----------------------------------------------------
+    /** Typed on-chain job (the struct layout has no published ABI). */
+    async getJob(jobId) {
+        const raw = await this.read(this.jobReg, JOB_REGISTRY_OPERATOR_ABI_PARSED, "getJob", [BigInt(jobId)]);
+        return normalizeJob(raw);
+    }
+    // ---- 1) Stuck-job recovery ---------------------------------------------
+    /**
+     * Jobs this worker acknowledged but never completed that are now past the
+     * completion deadline - the ones that block deregister and are clearable via
+     * claimTimeout. Needs the worker's job IDs (from the subgraph / LightNode
+     * client); on-chain there is no enumerator. Pass the candidate IDs in.
+     */
+    async stuckJobs(candidateJobIds) {
+        const cfg = await this.config();
+        const now = Math.floor(Date.now() / 1000);
+        const out = [];
+        for (const id of candidateJobIds) {
+            const j = await this.getJob(id);
+            if (j.worker.toLowerCase() !== this.addr)
+                continue;
+            if (j.state !== "Acknowledged")
+                continue;
+            // Deadline: prefer the on-chain deadlineAt, else ackAt + completionTimeout.
+            const deadline = j.deadlineAt || (j.ackAt ? j.ackAt + cfg.completionTimeoutSec : 0);
+            const past = deadline ? now - deadline : 0;
+            out.push({
+                // The id the caller passed IS the claimTimeout/getJob key - not j.jobId.
+                lookupId: BigInt(id),
+                jobId: j.jobId,
+                state: j.state,
+                ackAt: j.ackAt,
+                pastDeadlineSec: past,
+                escrowedFeeWei: j.escrowedFeeWei,
+            });
+        }
+        return out;
+    }
+    /**
+     * Clear one stuck (acknowledged-but-never-completed, past-deadline) job.
+     * Permissionless on-chain - the worker itself may call it.
+     *
+     * ⚠️ MAINNET SLASH: this finalizes the job as TimedOut, which realizes the
+     * completion-timeout slash on the worker's stake (mainnet:
+     * `config().slashBps.completionTimeout` = 5% of stake per job at the time of
+     * writing; TESTNET has slashing disabled, so it's free there). This is the
+     * deliberate price of unblocking deregister - a stuck acked job otherwise
+     * blocks the exit forever. Call `config()` first to see the live slash bps, and
+     * only clear jobs you've accepted are lost. Verify eligibility with
+     * `stuckJobs([id])` (pastDeadlineSec > 0) before calling.
+     */
+    async claimTimeout(jobId) {
+        return this.send("claimTimeout", this.jobReg, JOB_REGISTRY_OPERATOR_ABI_PARSED, "claimTimeout", [BigInt(jobId)]);
+    }
+    /**
+     * Clear every past-deadline acked job in `candidateJobIds`. Returns the txs and
+     * the IDs it skipped (not stuck / not past deadline). Each cleared job realizes
+     * its completion-timeout slash - see slashBps.completionTimeout in config().
+     */
+    async clearStuck(candidateJobIds) {
+        const stuck = await this.stuckJobs(candidateJobIds);
+        const cleared = [];
+        const skipped = [];
+        for (const s of stuck) {
+            if (s.pastDeadlineSec <= 0) {
+                skipped.push(s.lookupId);
+                continue;
+            }
+            // Use lookupId (the getJob/claimTimeout key), NOT the struct's jobId field.
+            const tx = await this.claimTimeout(s.lookupId);
+            cleared.push({ jobId: s.lookupId, tx });
+        }
+        return { cleared, skipped };
+    }
+    // ---- 3) Pre-flight gating ----------------------------------------------
+    /**
+     * Will deregister succeed right now? Reads the active-job count by checking the
+     * candidate IDs (on-chain there's no enumerator, so pass the worker's job IDs).
+     * Returns the blocking job IDs and a human reason - BEFORE you spend gas.
+     */
+    async canDeregister(candidateJobIds = []) {
+        const st = await this.status();
+        if (!st.registered)
+            return { ok: false, blockedBy: [], reason: "Worker is not registered." };
+        const stuck = await this.stuckJobs(candidateJobIds);
+        const inflight = stuck.map((s) => s.lookupId);
+        if (inflight.length === 0) {
+            return { ok: true, blockedBy: [], reason: "No in-flight jobs detected; deregister should succeed." };
+        }
+        return {
+            ok: false,
+            blockedBy: inflight,
+            reason: `${inflight.length} acknowledged-but-unfinished job(s) block deregister. clearStuck() them first (realizes a per-job timeout slash), then deregister.`,
+        };
+    }
+    // ---- 4) Settlement + exit (Docker-free) --------------------------------
+    /** Settle one completed job past its dispute window. Permissionless. */
+    async releaseJob(jobId) {
+        return this.send("releaseJob", this.jobReg, JOB_REGISTRY_OPERATOR_ABI_PARSED, "releaseJob", [BigInt(jobId)]);
+    }
+    /**
+     * Settle every releasable completed job in `candidateJobIds`. Skips jobs still
+     * inside the dispute window (DisputeWindowNotElapsed) rather than failing the
+     * batch - uses per-job calls so one not-ready job can't revert the rest.
+     */
+    async releaseAll(candidateJobIds) {
+        const released = [];
+        const notReady = [];
+        for (const id of candidateJobIds) {
+            const j = await this.getJob(id);
+            if (j.state !== "Completed")
+                continue;
+            // releaseJob takes the SAME lookup id passed to getJob, not j.jobId.
+            const lookupId = BigInt(id);
+            try {
+                const tx = await this.releaseJob(lookupId);
+                released.push({ jobId: lookupId, tx });
+            }
+            catch (e) {
+                if (isWorkerOpError(e) && e.decoded?.name === "DisputeWindowNotElapsed") {
+                    notReady.push(lookupId);
+                    continue;
+                }
+                throw e;
+            }
+        }
+        return { released, notReady };
+    }
+    /** Pull the worker's earned balance from the JobRegistry into the wallet. */
+    async withdraw() {
+        return this.send("withdraw", this.jobReg, JOB_REGISTRY_OPERATOR_ABI_PARSED, "withdraw", []);
+    }
+    /** Deregister - releases stake to the wallet. Reverts (ActiveJobsExist) if any in-flight job remains. */
+    async deregister() {
+        return this.send("deregister", this.workerReg, WORKER_REGISTRY_ABI_PARSED, "deregisterWorker", []);
+    }
+    /**
+     * The flagship rescue: clear stuck jobs → release any settled completed jobs +
+     * withdraw earnings → deregister. The one flow no official tool provides.
+     * Pass the worker's known job IDs (from the subgraph). Returns every tx done.
+     */
+    async unstickAndDeregister(candidateJobIds) {
+        const cleared = (await this.clearStuck(candidateJobIds)).cleared;
+        const released = (await this.releaseAll(candidateJobIds)).released;
+        let withdrawTx;
+        const st = await this.status();
+        if (st.claimableWei > 0n)
+            withdrawTx = await this.withdraw();
+        const deregisterTx = await this.deregister();
+        return { cleared, released, withdrawTx, deregisterTx };
+    }
+    // ---- stake ops ----------------------------------------------------------
+    async topUpStake(lcai) {
+        return this.send("topUpStake", this.workerReg, WORKER_REGISTRY_ABI_PARSED, "topUpStake", [], toWeiFromLcai(lcai));
+    }
+    async withdrawStake(lcai) {
+        return this.send("withdrawStake", this.workerReg, WORKER_REGISTRY_ABI_PARSED, "withdrawStake", [toWeiFromLcai(lcai)]);
+    }
+    async reinstate() {
+        return this.send("reinstate", this.workerReg, WORKER_REGISTRY_ABI_PARSED, "reinstate", []);
+    }
+    // ---- 5) Real economics --------------------------------------------------
+    /**
+     * Earnings breakdown: claimable-now (on-chain workerBalance) plus lifetime +
+     * pending-release counts derived from the worker record + its jobs. The caller
+     * passes the subgraph-sourced worker record and jobs (e.g. from LightNode) so
+     * this module stays free of a GraphQL dependency.
+     */
+    async earnings(input) {
+        const claimableWei = (await this.read(this.jobReg, JOB_REGISTRY_OPERATOR_ABI_PARSED, "workerBalance", [this.addr]));
+        const pendingRelease = (input.jobs ?? []).filter((j) => /complet/i.test(j.state)).length;
+        return {
+            claimableLcai: toLcai(claimableWei),
+            lifetimeLcai: input.lifetimeEarnedWei ? toLcai(BigInt(input.lifetimeEarnedWei)) : 0,
+            pendingReleaseCount: pendingRelease,
+            jobsCompleted: input.jobsCompleted ?? 0,
+            jobsTimedOut: input.jobsTimedOut ?? 0,
+        };
+    }
+    /**
+     * Net profitability: per-job worker fee (from live AIConfig fee split + the
+     * model fee) minus an estimated gas cost per job. Pure math over live config so
+     * an operator can answer "is this worth running" without a spreadsheet.
+     */
+    async profitability(input) {
+        const cfg = await this.config();
+        let feeWei = input.modelFeeWei ?? 0n;
+        if (!feeWei && input.modelTag) {
+            feeWei = (await this.read(this.network.aiConfig, AI_CONFIG_ABI_PARSED, "getModelFee", [(await import("./inference.js")).modelId(input.modelTag)]));
+        }
+        const workerFeeWei = (feeWei * BigInt(cfg.feeBps.worker)) / BPS;
+        const workerFeeLcaiPerJob = toLcai(workerFeeWei);
+        const gasLcaiPerJob = input.gasPerJobLcai ?? 0.001; // ack+complete+release ≈ tiny on LightChain
+        const netLcaiPerJob = workerFeeLcaiPerJob - gasLcaiPerJob;
+        const breakEvenJobsPerDay = netLcaiPerJob > 0 ? 0 : null;
+        const projectedDailyLcai = input.jobsPerDay != null ? netLcaiPerJob * input.jobsPerDay : null;
+        return { workerFeeLcaiPerJob, gasLcaiPerJob, netLcaiPerJob, breakEvenJobsPerDay, projectedDailyLcai };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightnode-sdk",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Read-only TypeScript client for LightChain AI: workers, jobs, models, on-chain registration, and per-model network analytics. Independent, community-built (not an official LightChain package).",
   "type": "module",
   "main": "./dist/index.js",