lightnode-sdk 0.7.0 → 0.7.2

package/README.md

@@ -5,9 +5,10 @@
 
 **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`.
+client, an on-chain model registry reader, worker preflight + watch, a full
+worker-operator surface (register, stake, settle, stuck-job recovery, exit),
+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
@@ -255,6 +256,29 @@ await op.withdraw();             // pull earned balance into the worker wallet
 await op.unstickAndDeregister([974, 976, 978, 979]);
 ```
 
+Full method reference (`jobIds` are the worker's IDs from
+`LightNode.getWorkerJobs` or the subgraph):
+
+| Method | Wallet | What it does |
+|---|---|---|
+| `status()` | no | registration, stake, claimable balance, below-floor flag |
+| `config()` | no | live AIConfig: minStake, timeouts, slash bps, fee split |
+| `getJob(id)` | no | one job as a typed `OnchainJob` struct |
+| `stuckJobs(jobIds)` | no | the acked, past-deadline jobs (with seconds past deadline) |
+| `canDeregister(jobIds)` | no | `{ ok, blockedBy, reason }` without sending a tx |
+| `earnings({ ... })` | no | claimable now vs lifetime vs pending-release |
+| `profitability({ ... })` | no | per-job worker fee net of gas, from the live fee split |
+| `claimTimeout(id)` | yes | time out one stuck job (mainnet: realizes a slash) |
+| `clearStuck(jobIds)` | yes | claimTimeout every past-deadline acked job; returns cleared + skipped |
+| `releaseJob(id)` | yes | settle one completed job past its window |
+| `releaseAll(jobIds)` | yes | settle all releasable completed jobs; skips not-ready ones |
+| `withdraw()` | yes | pull the earned balance into the worker wallet |
+| `topUpStake(lcai)` | yes | add stake |
+| `withdrawStake(lcai)` | yes | remove stake above the floor |
+| `reinstate()` | yes | reactivate a suspended worker |
+| `deregister()` | yes | exit and release stake (reverts if in-flight jobs remain) |
+| `unstickAndDeregister(jobIds)` | yes | clear stuck + release + withdraw + deregister, in one call |
+
 > **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
@@ -402,12 +426,30 @@ npx lightnode dao config                 # live voting delay / period / threshol
 
 ```bash
 PRIVATE_KEY=0x... npx lightnode chat "Write me a haiku about LightChain"
+PRIVATE_KEY=0x... npx lightnode batch prompts.json --concurrency 4   # N prompts in parallel
+PRIVATE_KEY=0x... npx lightnode agent "research X and summarize"     # ReAct agent, built-in tools
 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
 ```
 
+### Worker operator (signs as the worker key)
+
+Run a worker's on-chain lifecycle from the terminal. `status` and `can-deregister`
+are read-only; the rest sign with `PRIVATE_KEY` and act on the worker that key
+controls. Mainnet `clearstuck` and `deregister` realize a slash, so they require
+`--yes`.
+
+```bash
+                  npx lightnode worker status 0x...        # registration, stake, claimable, live config
+PRIVATE_KEY=0x... npx lightnode worker can-deregister      # what blocks the exit, before spending gas
+PRIVATE_KEY=0x... npx lightnode worker settle              # release completed jobs past their window + withdraw
+PRIVATE_KEY=0x... npx lightnode worker withdraw            # pull the earned balance into the worker wallet
+PRIVATE_KEY=0x... npx lightnode worker clearstuck --yes    # claimTimeout acked, past-deadline jobs that block exit
+PRIVATE_KEY=0x... npx lightnode worker deregister --yes    # clear stuck + settle + withdraw + deregister
+```
+
 ### Scaffolders (write files into your project)
 
 ```bash

package/dist/analytics.js

@@ -76,7 +76,7 @@ function groupBy(jobs, key) {
 export function aggregateModelStats(jobs, models, nowSec = Math.floor(Date.now() / 1000)) {
     const nameById = new Map(models.map((m) => [m.id.toLowerCase(), m.name]));
     return [...groupBy(jobs, (j) => j.model_id?.toLowerCase()).entries()]
-        .map(([id, js]) => ({ modelId: id, name: nameById.get(id) ?? `${id.slice(0, 10)}…`, ...classifyJobs(js, nowSec) }))
+        .map(([id, js]) => ({ modelId: id, name: nameById.get(id) ?? `${id.slice(0, 10)}...`, ...classifyJobs(js, nowSec) }))
         .sort((a, b) => b.total - a.total);
 }
 /** Per-worker reliability, busiest first (top `limit`). */

package/dist/dao.d.ts

@@ -329,6 +329,37 @@ export declare const GOVERNOR_ABI: readonly [{
     readonly outputs: readonly [{
         readonly type: "bool";
     }];
+}, {
+    readonly name: "ProposalCreated";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "proposalId";
+    }, {
+        readonly type: "address";
+        readonly name: "proposer";
+    }, {
+        readonly type: "address[]";
+        readonly name: "targets";
+    }, {
+        readonly type: "uint256[]";
+        readonly name: "values";
+    }, {
+        readonly type: "string[]";
+        readonly name: "signatures";
+    }, {
+        readonly type: "bytes[]";
+        readonly name: "calldatas";
+    }, {
+        readonly type: "uint256";
+        readonly name: "voteStart";
+    }, {
+        readonly type: "uint256";
+        readonly name: "voteEnd";
+    }, {
+        readonly type: "string";
+        readonly name: "description";
+    }];
 }];
 /** Minimal IVotes ABI for delegate + balance reads (LCAIBallots). */
 export declare const VOTES_ABI: readonly [{
@@ -380,6 +411,18 @@ interface MinimalPublicClient {
         functionName: string;
         args?: readonly unknown[];
     }) => Promise<unknown>;
+    getBlockNumber?: () => Promise<bigint>;
+    getLogs?: (args: {
+        address?: `0x${string}`;
+        event?: unknown;
+        args?: Record<string, unknown>;
+        fromBlock?: bigint | "earliest" | "latest";
+        toBlock?: bigint | "latest";
+    }) => Promise<ReadonlyArray<{
+        args?: Record<string, unknown>;
+        blockNumber?: bigint;
+        transactionHash?: `0x${string}`;
+    }>>;
 }
 interface MinimalWalletClient {
     writeContract: (args: {
@@ -412,6 +455,20 @@ export interface DaoConfig {
     /** Approx voting period in seconds, assuming 12s/block on Ethereum. */
     votingPeriodSecs: number;
 }
+/**
+ * One row returned by `DAO.recentProposals`. Lightweight summary you can
+ * map straight into a list UI. Use `dao.proposal(id)` for the full vote
+ * counts and exact deadlines.
+ */
+export interface ProposalRow {
+    id: bigint;
+    proposer: `0x${string}`;
+    /** First non-empty line of the proposal `description`. */
+    title: string;
+    state: ProposalState;
+    stateLabel: string;
+    blockNumber: bigint;
+}
 /**
  * DAO client. Wraps reads (proposal state, config) + writes (propose, vote,
  * queue, execute) on the Ethereum LCAIGovernor.
@@ -434,6 +491,19 @@ export declare class DAO {
     config(): Promise<DaoConfig>;
     /** Quorum required at a given timepoint (in wei of voting weight). */
     quorum(timepoint: bigint): Promise<bigint>;
+    /**
+     * List recent proposals on the governor by scanning `ProposalCreated`
+     * events. Scans back `lookbackBlocks` from the current head and returns
+     * up to `limit` proposals (newest first) with their current state.
+     *
+     * Ethereum mainnet RPCs cap a single `getLogs` to 10k blocks; the SDK
+     * chunks the range automatically. Default lookback is 300k blocks
+     * (~40 days) and default limit is 10.
+     */
+    recentProposals(opts?: {
+        lookbackBlocks?: number;
+        limit?: number;
+    }): Promise<ProposalRow[]>;
     /** Cast a For / Against / Abstain vote. Wallet must be the voter and have delegated their LCAI. */
     castVote(proposalId: bigint, support: VoteSupport, reason?: string): Promise<`0x${string}`>;
     /** Submit a new proposal. Wallet must hold at least `proposalThreshold` delegated votes. */

package/dist/dao.js

@@ -98,6 +98,8 @@ export const GOVERNOR_ABI = parseAbi([
     "function proposalEta(uint256 proposalId) external view returns (uint256)",
     "function getVotes(address account, uint256 timepoint) external view returns (uint256)",
     "function hasVoted(uint256 proposalId, address account) external view returns (bool)",
+    // Events - needed for recentProposals() event scan.
+    "event ProposalCreated(uint256 proposalId, address proposer, address[] targets, uint256[] values, string[] signatures, bytes[] calldatas, uint256 voteStart, uint256 voteEnd, string description)",
 ]);
 /** Minimal IVotes ABI for delegate + balance reads (LCAIBallots). */
 export const VOTES_ABI = parseAbi([
@@ -190,6 +192,75 @@ export class DAO {
             args: [timepoint],
         });
     }
+    /**
+     * List recent proposals on the governor by scanning `ProposalCreated`
+     * events. Scans back `lookbackBlocks` from the current head and returns
+     * up to `limit` proposals (newest first) with their current state.
+     *
+     * Ethereum mainnet RPCs cap a single `getLogs` to 10k blocks; the SDK
+     * chunks the range automatically. Default lookback is 300k blocks
+     * (~40 days) and default limit is 10.
+     */
+    async recentProposals(opts = {}) {
+        if (!this.publicClient.getLogs || !this.publicClient.getBlockNumber) {
+            throw new Error("DAO.recentProposals: publicClient does not expose getLogs / getBlockNumber. Use a viem PublicClient.");
+        }
+        const lookback = BigInt(opts.lookbackBlocks ?? 300000);
+        const limit = Math.max(1, opts.limit ?? 10);
+        const head = await this.publicClient.getBlockNumber();
+        const start = head > lookback ? head - lookback : 0n;
+        const CHUNK = 10000n;
+        // ProposalCreated is item index that matches the parsed ABI entry.
+        const event = GOVERNOR_ABI.find((x) => x.type === "event" && x.name === "ProposalCreated");
+        if (!event)
+            throw new Error("DAO.recentProposals: ProposalCreated event missing from GOVERNOR_ABI");
+        // Fan out chunked log reads in parallel - same shape the public proxy
+        // endpoint uses, but driven entirely by the caller's RPC.
+        const ranges = [];
+        for (let from = start; from <= head; from += CHUNK) {
+            const to = from + CHUNK - 1n > head ? head : from + CHUNK - 1n;
+            ranges.push({ from, to });
+        }
+        const rows = [];
+        const settled = await Promise.allSettled(ranges.map((r) => this.publicClient.getLogs({
+            address: this.addresses.governor,
+            event,
+            fromBlock: r.from,
+            toBlock: r.to,
+        })));
+        for (const res of settled) {
+            if (res.status !== "fulfilled")
+                continue;
+            for (const log of res.value) {
+                const args = log.args ?? {};
+                const id = args.proposalId;
+                const proposer = args.proposer;
+                const description = args.description ?? "";
+                if (id == null || !proposer)
+                    continue;
+                const title = description.split(/\r?\n/).map((s) => s.trim()).find(Boolean) ?? `Proposal #${id.toString()}`;
+                rows.push({
+                    id,
+                    proposer,
+                    title: title.length > 140 ? title.slice(0, 137) + "..." : title,
+                    // state filled in below in one batched call
+                    state: 0,
+                    stateLabel: "",
+                    blockNumber: log.blockNumber ?? 0n,
+                });
+            }
+        }
+        // Sort newest-first by id (uint256 monotonic in OZ Governor) and trim.
+        rows.sort((a, b) => (b.id > a.id ? 1 : b.id < a.id ? -1 : 0));
+        const trimmed = rows.slice(0, limit);
+        // Fetch the live state for each in parallel so the row is immediately usable.
+        const states = await Promise.all(trimmed.map((r) => this.state(r.id).catch(() => 0)));
+        return trimmed.map((r, i) => ({
+            ...r,
+            state: states[i],
+            stateLabel: PROPOSAL_STATE_LABEL[states[i]] ?? "unknown",
+        }));
+    }
     // -------- Writes --------
     /** Cast a For / Against / Abstain vote. Wallet must be the voter and have delegated their LCAI. */
     castVote(proposalId, support, reason) {

package/dist/index.d.ts

@@ -91,7 +91,7 @@ export declare class LightNode {
  * (especially in registry-proxy environments like StackBlitz where lockfiles
  * may pin an older minor than the local install command suggests).
  */
-export declare const SDK_VERSION = "0.7.0";
+export declare const SDK_VERSION = "0.7.2";
 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";
@@ -100,7 +100,7 @@ export type { BatchPrompt, BatchResult, RunInferenceBatchArgs } from "./batch.js
 export type { AgentTool, AgentStep, AgentOptions, AgentRunResult } from "./agent.js";
 export type { WorkerPreflightArgs, WorkerPreflightResult, WorkerWatchOptions, WorkerEventKind, WorkerEvent, WorkerWatchHandle } from "./worker.js";
 export type { BridgeChain, BridgeEndpoints, BridgeTransferArgs } from "./bridge.js";
-export type { DaoChain, DaoAddresses, ProposalSummary, DaoConfig } from "./dao.js";
+export type { DaoChain, DaoAddresses, ProposalSummary, ProposalRow, 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

@@ -146,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.7.0";
+export const SDK_VERSION = "0.7.2";
 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, 

package/dist/inference.d.ts

@@ -57,12 +57,12 @@ export interface SessionPreparation {
      * Parameter names match the canonical on-chain ABI (paramsHash,
      * ephemeralPubKey, initState) verified live in the LightChain inference
      * integration guide. The slot mapping is:
-     *   - paramsHash      ← keccak256(model tag)
-     *   - worker          ← prepared.worker
-     *   - encWorkerKey    ← hex(encWorker)              // ECDH-wrap for the worker
-     *   - ephemeralPubKey ← hex(encDisputer)            // ECDH-wrap for the disputer
-     *   - initState       ← prepared.signature          // dispatcher EIP-712 signature
-     *   - expiry          ← prepared.expiry
+     *   - paramsHash      from keccak256(model tag)
+     *   - worker          from prepared.worker
+     *   - encWorkerKey    from hex(encWorker)              // ECDH-wrap for the worker
+     *   - ephemeralPubKey from hex(encDisputer)            // ECDH-wrap for the disputer
+     *   - initState       from prepared.signature          // dispatcher EIP-712 signature
+     *   - expiry          from prepared.expiry
      */
     createSessionArgs: {
         paramsHash: `0x${string}`;

package/dist/worker-operator.d.ts

@@ -236,7 +236,7 @@ export declare class WorkerOperator {
      * 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
+     * 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
@@ -283,8 +283,8 @@ export declare class WorkerOperator {
     /** 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.
+     * The flagship rescue: clear stuck jobs then release any settled completed jobs +
+     * withdraw earnings then 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<{

package/dist/worker-operator.js

@@ -431,7 +431,7 @@ export class WorkerOperator {
      * 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
+     * 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
@@ -526,8 +526,8 @@ export class WorkerOperator {
         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.
+     * The flagship rescue: clear stuck jobs then release any settled completed jobs +
+     * withdraw earnings then 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) {

package/package.json

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