lightnode-sdk 0.7.1 → 0.7.3

package/README.md

@@ -426,6 +426,8 @@ 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

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,57 @@ export declare const GOVERNOR_ABI: readonly [{
     readonly outputs: readonly [{
         readonly type: "bool";
     }];
+}, {
+    readonly name: "cancel";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "address[]";
+        readonly name: "targets";
+    }, {
+        readonly type: "uint256[]";
+        readonly name: "values";
+    }, {
+        readonly type: "bytes[]";
+        readonly name: "calldatas";
+    }, {
+        readonly type: "bytes32";
+        readonly name: "descriptionHash";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    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 +431,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 +475,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 +511,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. */
@@ -460,5 +550,54 @@ export declare class DAO {
         calldatas: `0x${string}`[];
         descriptionHash: `0x${string}`;
     }): Promise<`0x${string}`>;
+    /**
+     * Cancel a proposal. OZ Governor permits the proposer (and sometimes the
+     * Guardian / Timelock role) to cancel a Pending or Active proposal. Same
+     * `descriptionHash` you'd pass to `queue` / `execute`.
+     */
+    cancel(args: {
+        targets: `0x${string}`[];
+        values: bigint[];
+        calldatas: `0x${string}`[];
+        descriptionHash: `0x${string}`;
+    }): Promise<`0x${string}`>;
+    /**
+     * keccak256 of the raw description string. The Governor stores proposals
+     * keyed by `(targets, values, calldatas, descriptionHash)` rather than
+     * the description itself - this is the same hash the OZ Governor computes
+     * internally. Pass it to `queue`, `execute`, `cancel`, `hashProposal`.
+     */
+    descriptionHash(description: string): `0x${string}`;
+    /**
+     * Predict a proposal id BEFORE submitting. Mirrors `Governor.hashProposal`
+     * on chain so you can compute the id deterministically (the proposer can
+     * persist it ahead of time, drop it into a UI, or sanity-check that a
+     * proposal hasn't already been submitted).
+     */
+    hashProposal(args: {
+        targets: `0x${string}`[];
+        values: bigint[];
+        calldatas: `0x${string}`[];
+        /** Either the description string or the precomputed hash; both accepted. */
+        description: string | `0x${string}`;
+    }): Promise<bigint>;
+    /**
+     * IVotes.balanceOf - wrapped voting-token balance (LCAIBallots on Ethereum
+     * mainnet, native LCAI via the NativeVotes precompile on LightChain
+     * mainnet). Returns wei.
+     */
+    getBallotsBalance(voter: `0x${string}`): Promise<bigint>;
+    /**
+     * Address the voter has delegated to. Wraps `IVotes.delegates`. The zero
+     * address means the voter has not yet delegated, which is the OZ default
+     * (no voting power for self until you self-delegate).
+     */
+    getDelegate(voter: `0x${string}`): Promise<`0x${string}`>;
+    /**
+     * Delegate voting weight to `delegatee` (use the voter's own address to
+     * self-delegate, which is the common first step before voting). Wallet
+     * required.
+     */
+    delegate(delegatee: `0x${string}`): Promise<`0x${string}`>;
 }
 export {};

package/dist/dao.js

@@ -17,7 +17,7 @@
  * This module covers the OZ Governor v5 surface: state machine, propose,
  * castVote, queue, execute. Plus convenience reads of the constants.
  */
-import { parseAbi } from "viem";
+import { keccak256, parseAbi, toBytes } from "viem";
 /**
  * Confirmed deployment addresses. Each entry is what an SDK user passes to
  * `new DAO(client, chainKey, walletClient?)`.
@@ -98,6 +98,9 @@ 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)",
+    "function cancel(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) external returns (uint256)",
+    // 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 +193,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) {
@@ -247,4 +319,97 @@ export class DAO {
             value: totalValue,
         });
     }
+    /**
+     * Cancel a proposal. OZ Governor permits the proposer (and sometimes the
+     * Guardian / Timelock role) to cancel a Pending or Active proposal. Same
+     * `descriptionHash` you'd pass to `queue` / `execute`.
+     */
+    cancel(args) {
+        if (!this.walletClient)
+            throw new Error("DAO: no wallet client; pass one to the DAO constructor for writes");
+        return this.walletClient.writeContract({
+            address: this.addresses.governor,
+            abi: GOVERNOR_ABI,
+            functionName: "cancel",
+            args: [args.targets, args.values, args.calldatas, args.descriptionHash],
+        });
+    }
+    // -------- Helpers (pure, no chain reads) --------
+    /**
+     * keccak256 of the raw description string. The Governor stores proposals
+     * keyed by `(targets, values, calldatas, descriptionHash)` rather than
+     * the description itself - this is the same hash the OZ Governor computes
+     * internally. Pass it to `queue`, `execute`, `cancel`, `hashProposal`.
+     */
+    descriptionHash(description) {
+        return keccak256(toBytes(description));
+    }
+    /**
+     * Predict a proposal id BEFORE submitting. Mirrors `Governor.hashProposal`
+     * on chain so you can compute the id deterministically (the proposer can
+     * persist it ahead of time, drop it into a UI, or sanity-check that a
+     * proposal hasn't already been submitted).
+     */
+    async hashProposal(args) {
+        const descHash = typeof args.description === "string" && args.description.startsWith("0x") && args.description.length === 66
+            ? args.description
+            : keccak256(toBytes(args.description));
+        return this.publicClient.readContract({
+            address: this.addresses.governor,
+            abi: GOVERNOR_ABI,
+            functionName: "hashProposal",
+            args: [args.targets, args.values, args.calldatas, descHash],
+        });
+    }
+    // -------- IVotes helpers (LCAIBallots wrapped token) --------
+    /**
+     * IVotes.balanceOf - wrapped voting-token balance (LCAIBallots on Ethereum
+     * mainnet, native LCAI via the NativeVotes precompile on LightChain
+     * mainnet). Returns wei.
+     */
+    getBallotsBalance(voter) {
+        const ballots = this.addresses.ballots;
+        if (!ballots)
+            throw new Error("DAO.getBallotsBalance: this chain has no Ballots address");
+        return this.publicClient.readContract({
+            address: ballots,
+            abi: VOTES_ABI,
+            functionName: "balanceOf",
+            args: [voter],
+        });
+    }
+    /**
+     * Address the voter has delegated to. Wraps `IVotes.delegates`. The zero
+     * address means the voter has not yet delegated, which is the OZ default
+     * (no voting power for self until you self-delegate).
+     */
+    getDelegate(voter) {
+        const ballots = this.addresses.ballots;
+        if (!ballots)
+            throw new Error("DAO.getDelegate: this chain has no Ballots address");
+        return this.publicClient.readContract({
+            address: ballots,
+            abi: VOTES_ABI,
+            functionName: "delegates",
+            args: [voter],
+        });
+    }
+    /**
+     * Delegate voting weight to `delegatee` (use the voter's own address to
+     * self-delegate, which is the common first step before voting). Wallet
+     * required.
+     */
+    delegate(delegatee) {
+        if (!this.walletClient)
+            throw new Error("DAO: no wallet client; pass one to the DAO constructor for writes");
+        const ballots = this.addresses.ballots;
+        if (!ballots)
+            throw new Error("DAO.delegate: this chain has no Ballots address");
+        return this.walletClient.writeContract({
+            address: ballots,
+            abi: VOTES_ABI,
+            functionName: "delegate",
+            args: [delegatee],
+        });
+    }
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS } from "./networks.js";
-import { fromWei } from "./subgraph.js";
+import { fromWei, resolveJobTransactions } from "./subgraph.js";
 import { aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv } from "./analytics.js";
 import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey, runInferenceStream } from "./inference.js";
 import { Conversation, chat } from "./chat.js";
@@ -13,7 +13,7 @@ import { OnchainModelRegistry, AIVM_MODEL_REGISTRY_ABI, BENCHMARK_REGISTRY_ABI,
 import { StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker } from "./errors.js";
 import { GatewayClient, GatewayHttpError } from "./gateway.js";
 import * as crypto from "./crypto.js";
-import type { NetworkId, NetworkConfig, Worker, Job, ModelInfo, NetworkStats, ModelStat, WorkerStat, NetworkAnalytics } from "./types.js";
+import type { NetworkId, NetworkConfig, Worker, Job, JobTransactions, ModelInfo, NetworkStats, ModelStat, WorkerStat, NetworkAnalytics } from "./types.js";
 /**
  * Read-only client for a LightChain AI network. Pure reads from the public indexer
  * and the chain; no keys, no writes. Independent, community-built.
@@ -59,7 +59,9 @@ export declare class LightNode {
      * builder-friendly label; `raw` is the indexer's literal state string.
      * Null when the indexer has never seen the job (still pending propagation).
      */
-    getJobStatus(jobId: string | bigint): Promise<{
+    getJobStatus(jobId: string | bigint, opts?: {
+        withTransactions?: boolean;
+    }): Promise<{
         id: string;
         raw: string;
         category: "submitted" | "in-flight" | "completed" | "stalled" | "disputed" | "resolved" | "unknown";
@@ -69,7 +71,27 @@ export declare class LightNode {
         completedAt: number | null;
         workerShareLcai: number;
         refundable: boolean;
+        /** Block numbers as the indexer recorded them. Null until indexer sees the event. */
+        submitBlock: number | null;
+        completionBlock: number | null;
+        /**
+         * Tx hashes for submitJob + jobCompleted, only resolved when
+         * `withTransactions: true`. Each hash deep-links to Lightscan via
+         * {@link Network.explorerTxUrl}. Costs one eth_getLogs RPC call per
+         * transaction (max two per job); skip the flag if you don't need them.
+         */
+        submitTx: `0x${string}` | null;
+        completionTx: `0x${string}` | null;
     } | null>;
+    /**
+     * Build a Lightscan URL for an arbitrary address or tx hash on this
+     * network. Useful for surfacing deep-links in builder UIs without
+     * each consumer needing to know which explorer corresponds to which
+     * chain.
+     */
+    explorerAddressUrl(address: string): string;
+    explorerTxUrl(hash: string): string;
+    explorerBlockUrl(block: number | bigint): string;
     /** keccak256 of a model tag (its on-chain + indexer id). */
     modelId(tag: string): `0x${string}`;
     /** On-chain inference fee for a model, in whole LCAI (what submitJob must be paid). */
@@ -91,8 +113,8 @@ export declare class LightNode {
  * (especially in registry-proxy environments like StackBlitz where lockfiles
  * may pin an older minor than the local install command suggests).
  */
-export declare const SDK_VERSION = "0.7.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, WorkerOperator, WORKER_REGISTRY_ABI, JOB_REGISTRY_OPERATOR_ABI, AI_CONFIG_ABI, JOB_STATE, decodeWorkerError, WorkerOpError, isWorkerOpError, };
+export declare const SDK_VERSION = "0.7.3";
+export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, resolveJobTransactions, 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";
@@ -100,7 +122,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 };
+export type { NetworkId, NetworkConfig, Worker, Job, JobTransactions, ModelInfo, NetworkStats, ModelStat, WorkerStat, NetworkAnalytics };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS } from "./networks.js";
-import { fetchWorker, fetchWorkerJobs, fetchRecentJobs, fetchJob, fetchModels, fetchWorkers, summarize, fromWei, } from "./subgraph.js";
+import { fetchWorker, fetchWorkerJobs, fetchRecentJobs, fetchJob, fetchModels, fetchWorkers, summarize, fromWei, resolveJobTransactions, } from "./subgraph.js";
 import { isRegistered } from "./onchain.js";
 import { aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, } from "./analytics.js";
 import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey, runInferenceStream, } from "./inference.js";
@@ -86,7 +86,7 @@ export class LightNode {
      * builder-friendly label; `raw` is the indexer's literal state string.
      * Null when the indexer has never seen the job (still pending propagation).
      */
-    async getJobStatus(jobId) {
+    async getJobStatus(jobId, opts = {}) {
         const j = await fetchJob(this.network, jobId);
         if (!j)
             return null;
@@ -110,6 +110,11 @@ export class LightNode {
         // own timeout/dispute pipeline reclaims the fee; this flag is the SDK's
         // builder-facing hint that the on-chain refund call is the right path.
         const refundable = category === "stalled" || category === "disputed";
+        // Tx hashes need a second RPC roundtrip. Opt in only - the historical
+        // shape of getJobStatus stays pure-subgraph for callers who don't ask.
+        const txs = opts.withTransactions
+            ? await resolveJobTransactions(this.network, j.id, { job: j })
+            : { submit: null, completion: null };
         return {
             id: j.id,
             raw: state,
@@ -120,8 +125,27 @@ export class LightNode {
             completedAt: j.completed_at ?? null,
             workerShareLcai: fromWei(j.worker_share),
             refundable,
+            submitBlock: j.submit_block_number ?? null,
+            completionBlock: j.completion_block_number && j.completion_block_number > 0 ? j.completion_block_number : null,
+            submitTx: txs.submit,
+            completionTx: txs.completion,
         };
     }
+    /**
+     * Build a Lightscan URL for an arbitrary address or tx hash on this
+     * network. Useful for surfacing deep-links in builder UIs without
+     * each consumer needing to know which explorer corresponds to which
+     * chain.
+     */
+    explorerAddressUrl(address) {
+        return `${this.network.explorer}/address/${address}`;
+    }
+    explorerTxUrl(hash) {
+        return `${this.network.explorer}/tx/${hash}`;
+    }
+    explorerBlockUrl(block) {
+        return `${this.network.explorer}/block/${block.toString()}`;
+    }
     /** keccak256 of a model tag (its on-chain + indexer id). */
     modelId(tag) {
         return computeModelId(tag);
@@ -146,8 +170,11 @@ 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.1";
-export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, 
+export const SDK_VERSION = "0.7.3";
+export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, 
+// v0.7.3 per-job transaction-hash resolver (lifts the upstream
+// subgraph's "block-only" Job entity to a deep-linkable Job + tx pair).
+resolveJobTransactions, 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, 
 // v0.4 high-level orchestrator: one call, full flow.

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/subgraph.d.ts

@@ -1,4 +1,5 @@
-import type { NetworkConfig, Worker, Job, ModelInfo, NetworkStats } from "./types.js";
+import type { PublicClient } from "viem";
+import type { NetworkConfig, Worker, Job, JobTransactions, ModelInfo, NetworkStats } from "./types.js";
 /** Convert a wei string to a number of whole tokens (18 decimals). */
 export declare function fromWei(wei?: string): number;
 export declare function fetchWorker(cfg: NetworkConfig, address: string): Promise<Worker | null>;
@@ -7,6 +8,26 @@ export declare function fetchJob(cfg: NetworkConfig, jobId: string | bigint): Pr
 export declare function fetchWorkerJobs(cfg: NetworkConfig, address: string, first?: number): Promise<Job[]>;
 /** Recent jobs across the whole network (not one worker), for analytics. */
 export declare function fetchRecentJobs(cfg: NetworkConfig, first?: number): Promise<Job[]>;
+/**
+ * Resolve a job's tx hashes (submitJob + jobCompleted) by re-scanning the
+ * exact blocks the indexer recorded. The upstream subgraph entity stores
+ * `submit_block_number` + `completion_block_number` but NOT the
+ * transactionHash. Re-deriving them needs one RPC eth_getLogs call per
+ * block: at most two calls per job, and each is tightly bounded
+ * (single-block range, single contract, single topic, single jobId match).
+ *
+ * `submit` is null only if the indexer hasn't seen the job yet (we couldn't
+ * resolve the block). `completion` is null until the worker emits
+ * JobCompleted (still-in-flight or stalled jobs).
+ *
+ * Pass a `publicClient` to reuse an existing RPC connection. Without one
+ * the function builds a transient client from `cfg.rpc` - simple but spends
+ * a TCP handshake per call.
+ */
+export declare function resolveJobTransactions(cfg: NetworkConfig, jobId: string | bigint, opts?: {
+    publicClient?: PublicClient;
+    job?: Job | null;
+}): Promise<JobTransactions>;
 export declare function fetchModels(cfg: NetworkConfig): Promise<ModelInfo[]>;
 export declare function fetchWorkers(cfg: NetworkConfig, first?: number): Promise<Worker[]>;
 export declare function summarize(workers: Worker[], models: ModelInfo[]): NetworkStats;

package/dist/subgraph.js

@@ -1,4 +1,8 @@
-import { getAddress } from "viem";
+import { createPublicClient, getAddress, http, toHex, pad } from "viem";
+// keccak256("JobSubmitted(uint256,uint256,address)")
+const JOB_SUBMITTED_TOPIC = "0xfb47370368875d7490803c5653d9496d0a3c5e1b49a17f013ec37abd9d86d356";
+// keccak256("JobCompleted(uint256,address,bytes32,bytes32)")
+const JOB_COMPLETED_TOPIC = "0xdb545db74bae046337ed01971cf61569fd1a1460ff8ed511ab19ceaac1326377";
 const TIMEOUT_MS = 12000;
 async function gql(url, query) {
     const ctrl = new AbortController();
@@ -59,18 +63,85 @@ export async function fetchWorker(cfg, address) {
 /** Fetch one job by its on-chain id. Null when the indexer has never seen it. */
 export async function fetchJob(cfg, jobId) {
     const id = typeof jobId === "bigint" ? jobId.toString() : jobId;
-    const data = await gql(cfg.subgraph, `{ job(id:"${id}") { id state model_id worker submitted_at ack_at completed_at worker_share } }`);
+    const data = await gql(cfg.subgraph, `{ job(id:"${id}") { id state model_id worker submitted_at ack_at completed_at worker_share submit_block_number completion_block_number } }`);
     return data.job ?? null;
 }
 export async function fetchWorkerJobs(cfg, address, first = 20) {
-    const data = await gql(cfg.subgraph, `{ jobs(first:${first}, orderBy:submitted_at, orderDirection:desc, where:{worker:"${checksum(address)}"}) { id state model_id submitted_at ack_at completed_at worker_share } }`);
+    const data = await gql(cfg.subgraph, `{ jobs(first:${first}, orderBy:submitted_at, orderDirection:desc, where:{worker:"${checksum(address)}"}) { id state model_id submitted_at ack_at completed_at worker_share submit_block_number completion_block_number } }`);
     return data.jobs ?? [];
 }
 /** Recent jobs across the whole network (not one worker), for analytics. */
 export async function fetchRecentJobs(cfg, first = 1000) {
-    const data = await gql(cfg.subgraph, `{ jobs(first:${first}, orderBy:submitted_at, orderDirection:desc) { id state model_id worker ack_at completed_at worker_share } }`);
+    const data = await gql(cfg.subgraph, `{ jobs(first:${first}, orderBy:submitted_at, orderDirection:desc) { id state model_id worker ack_at completed_at worker_share submit_block_number completion_block_number } }`);
     return data.jobs ?? [];
 }
+/**
+ * Resolve a job's tx hashes (submitJob + jobCompleted) by re-scanning the
+ * exact blocks the indexer recorded. The upstream subgraph entity stores
+ * `submit_block_number` + `completion_block_number` but NOT the
+ * transactionHash. Re-deriving them needs one RPC eth_getLogs call per
+ * block: at most two calls per job, and each is tightly bounded
+ * (single-block range, single contract, single topic, single jobId match).
+ *
+ * `submit` is null only if the indexer hasn't seen the job yet (we couldn't
+ * resolve the block). `completion` is null until the worker emits
+ * JobCompleted (still-in-flight or stalled jobs).
+ *
+ * Pass a `publicClient` to reuse an existing RPC connection. Without one
+ * the function builds a transient client from `cfg.rpc` - simple but spends
+ * a TCP handshake per call.
+ */
+export async function resolveJobTransactions(cfg, jobId, opts = {}) {
+    const id = typeof jobId === "bigint" ? jobId : BigInt(jobId);
+    const job = opts.job !== undefined ? opts.job : await fetchJob(cfg, id);
+    if (!job)
+        return { submit: null, completion: null };
+    const client = opts.publicClient ??
+        createPublicClient({ transport: http(cfg.rpc) });
+    // Topic 1 is the indexed jobId, padded to 32 bytes. The subgraph keys
+    // entries by exact on-chain jobId so this match is unambiguous.
+    const jobTopic = pad(toHex(id), { size: 32 });
+    const submitBlock = job.submit_block_number ? BigInt(job.submit_block_number) : null;
+    const completionBlock = job.completion_block_number ? BigInt(job.completion_block_number) : null;
+    // Address the contract that emits Job* events. JobRegistry handles both.
+    const address = cfg.jobRegistry;
+    if (!address)
+        return { submit: null, completion: null };
+    const [submitTx, completionTx] = await Promise.all([
+        submitBlock !== null
+            ? fetchTxHashForJobEvent(client, address, JOB_SUBMITTED_TOPIC, jobTopic, submitBlock)
+            : Promise.resolve(null),
+        completionBlock !== null && completionBlock > 0n
+            ? fetchTxHashForJobEvent(client, address, JOB_COMPLETED_TOPIC, jobTopic, completionBlock)
+            : Promise.resolve(null),
+    ]);
+    return { submit: submitTx, completion: completionTx };
+}
+async function fetchTxHashForJobEvent(client, address, eventTopic, jobTopic, block) {
+    // Bypass viem's typed getLogs - it rejects the [topic0, topic1] tuple
+    // without a parsed `event` ABI, and we don't want to ship the full ABI
+    // through this path. The raw eth_getLogs at the transport layer is what
+    // we need: single block, single contract, two-topic match (event sig +
+    // indexed jobId), so the response is at most one log.
+    try {
+        const blockHex = `0x${block.toString(16)}`;
+        const logs = (await client.request({
+            method: "eth_getLogs",
+            params: [
+                {
+                    address,
+                    fromBlock: blockHex,
+                    toBlock: blockHex,
+                    topics: [eventTopic, jobTopic],
+                },
+            ],
+        }));
+        return logs[0]?.transactionHash ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 export async function fetchModels(cfg) {
     const data = await gql(cfg.subgraph, `{ modelinfos { id name fee max_output_tokens is_whitelisted is_enabled } }`);
     return data.modelinfos ?? [];

package/dist/types.d.ts

@@ -43,6 +43,17 @@ export interface Job {
     ack_at?: number;
     completed_at?: number;
     worker_share?: string;
+    submit_block_number?: number;
+    completion_block_number?: number;
+}
+/**
+ * Per-job transaction hashes. Populated lazily by the SDK via
+ * resolveJobTransactions(); not present on the raw subgraph Job entity.
+ * `completion` is null until the worker emits JobCompleted.
+ */
+export interface JobTransactions {
+    submit: `0x${string}` | null;
+    completion: `0x${string}` | null;
 }
 export interface ModelInfo {
     id: 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.1",
+  "version": "0.7.3",
   "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",