lightnode-sdk 0.4.9 → 0.5.0

package/dist/dao.js

@@ -0,0 +1,234 @@
+/**
+ * DAO SDK: typed wrapper around the LCAI Governor (OpenZeppelin Governor v5)
+ * on Ethereum mainnet. Addresses extracted from
+ * `lightchain-protocol/LCAI-dao-frontend/config/index.ts`.
+ *
+ * Governance is currently Ethereum-side (chain 1). Voting on LCAI proposals
+ * happens via the LCAI ERC-20 wrapped as IVotes (LCAIBallots). Execution
+ * goes through LCAITimeLock with the timelock controller managing actual
+ * calldata dispatch.
+ *
+ * Voting parameters (hard-coded in LCAIGovernor.sol constructor):
+ *   - votingDelay      = 7,200 blocks   (~1 day at 12s)
+ *   - votingPeriod     = 100,800 blocks (~14 days at 12s)
+ *   - proposalThreshold = 140,000 LCAI  (votes required to create a proposal)
+ *   - quorum            = 3% of total supply (3-15 by admin)
+ *
+ * This module covers the OZ Governor v5 surface: state machine, propose,
+ * castVote, queue, execute. Plus convenience reads of the constants.
+ */
+import { parseAbi } from "viem";
+/** Confirmed Ethereum mainnet addresses (chain 1). */
+export const DAO_ADDRESSES = {
+    ethereum: {
+        chainId: 1,
+        governor: "0x6dfa413B5900a1a7947BC75E68AbBA093cB2492d",
+        timelock: "0xbE1c37F8C4DA77dD06F4A8AC5098Ec70273093d7",
+        ballots: "0x75F3D01c4D960FE986A598B7954A3b786B29cE49",
+        token: "0x9cA8530CA349c966Fe9ef903Df17a75B8A778927",
+        treasury: "0x07A716a551E5f4CA7D6C71Da9dF1cb1429Dba826",
+        explorer: "https://etherscan.io",
+    },
+};
+/**
+ * The 8-state OZ Governor v5 enum. The string label is what most builders
+ * will want to surface in a UI.
+ */
+export var ProposalState;
+(function (ProposalState) {
+    ProposalState[ProposalState["Pending"] = 0] = "Pending";
+    ProposalState[ProposalState["Active"] = 1] = "Active";
+    ProposalState[ProposalState["Canceled"] = 2] = "Canceled";
+    ProposalState[ProposalState["Defeated"] = 3] = "Defeated";
+    ProposalState[ProposalState["Succeeded"] = 4] = "Succeeded";
+    ProposalState[ProposalState["Queued"] = 5] = "Queued";
+    ProposalState[ProposalState["Expired"] = 6] = "Expired";
+    ProposalState[ProposalState["Executed"] = 7] = "Executed";
+})(ProposalState || (ProposalState = {}));
+export const PROPOSAL_STATE_LABEL = {
+    [ProposalState.Pending]: "pending",
+    [ProposalState.Active]: "active",
+    [ProposalState.Canceled]: "canceled",
+    [ProposalState.Defeated]: "defeated",
+    [ProposalState.Succeeded]: "succeeded",
+    [ProposalState.Queued]: "queued",
+    [ProposalState.Expired]: "expired",
+    [ProposalState.Executed]: "executed",
+};
+/** Vote support values. Maps to OZ's GovernorCountingSimple. */
+export var VoteSupport;
+(function (VoteSupport) {
+    VoteSupport[VoteSupport["Against"] = 0] = "Against";
+    VoteSupport[VoteSupport["For"] = 1] = "For";
+    VoteSupport[VoteSupport["Abstain"] = 2] = "Abstain";
+})(VoteSupport || (VoteSupport = {}));
+/** OZ Governor v5 ABI (subset). */
+export const GOVERNOR_ABI = parseAbi([
+    "function propose(address[] targets, uint256[] values, bytes[] calldatas, string description) external returns (uint256 proposalId)",
+    "function castVote(uint256 proposalId, uint8 support) external returns (uint256)",
+    "function castVoteWithReason(uint256 proposalId, uint8 support, string reason) external returns (uint256)",
+    "function queue(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) external returns (uint256)",
+    "function execute(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) external payable returns (uint256)",
+    "function state(uint256 proposalId) external view returns (uint8)",
+    "function hashProposal(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) external pure returns (uint256)",
+    "function votingDelay() external view returns (uint256)",
+    "function votingPeriod() external view returns (uint256)",
+    "function proposalThreshold() external view returns (uint256)",
+    "function quorum(uint256 timepoint) external view returns (uint256)",
+    "function proposalVotes(uint256 proposalId) external view returns (uint256 againstVotes, uint256 forVotes, uint256 abstainVotes)",
+    "function proposalSnapshot(uint256 proposalId) external view returns (uint256)",
+    "function proposalDeadline(uint256 proposalId) external view returns (uint256)",
+    "function proposalProposer(uint256 proposalId) external view returns (address)",
+    "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)",
+]);
+/** Minimal IVotes ABI for delegate + balance reads (LCAIBallots). */
+export const VOTES_ABI = parseAbi([
+    "function balanceOf(address) external view returns (uint256)",
+    "function getVotes(address) external view returns (uint256)",
+    "function delegates(address) external view returns (address)",
+    "function delegate(address delegatee) external returns (bool)",
+]);
+/**
+ * DAO client. Wraps reads (proposal state, config) + writes (propose, vote,
+ * queue, execute) on the Ethereum LCAIGovernor.
+ */
+export class DAO {
+    constructor(publicClient, chain = "ethereum", walletClient) {
+        this.publicClient = publicClient;
+        this.walletClient = walletClient;
+        this.addresses = DAO_ADDRESSES[chain];
+    }
+    // -------- Reads --------
+    /** Current proposal state by id. */
+    async state(proposalId) {
+        const raw = (await this.publicClient.readContract({
+            address: this.addresses.governor,
+            abi: GOVERNOR_ABI,
+            functionName: "state",
+            args: [proposalId],
+        }));
+        return raw;
+    }
+    /** Full proposal summary by id. Aggregates state + votes + key blocks. */
+    async proposal(proposalId) {
+        const [stateRaw, votesRaw, snapshot, deadline, eta, proposerRaw] = (await Promise.all([
+            this.publicClient.readContract({ address: this.addresses.governor, abi: GOVERNOR_ABI, functionName: "state", args: [proposalId] }),
+            this.publicClient.readContract({ address: this.addresses.governor, abi: GOVERNOR_ABI, functionName: "proposalVotes", args: [proposalId] }),
+            this.publicClient.readContract({ address: this.addresses.governor, abi: GOVERNOR_ABI, functionName: "proposalSnapshot", args: [proposalId] }),
+            this.publicClient.readContract({ address: this.addresses.governor, abi: GOVERNOR_ABI, functionName: "proposalDeadline", args: [proposalId] }),
+            this.publicClient.readContract({ address: this.addresses.governor, abi: GOVERNOR_ABI, functionName: "proposalEta", args: [proposalId] }).catch(() => 0n),
+            this.publicClient.readContract({ address: this.addresses.governor, abi: GOVERNOR_ABI, functionName: "proposalProposer", args: [proposalId] }).catch(() => null),
+        ]));
+        const state = stateRaw;
+        return {
+            id: proposalId,
+            state,
+            stateLabel: PROPOSAL_STATE_LABEL[state] ?? "unknown",
+            proposer: proposerRaw,
+            snapshot,
+            deadline,
+            eta,
+            votes: { againstWei: votesRaw[0], forWei: votesRaw[1], abstainWei: votesRaw[2] },
+        };
+    }
+    /** Whether `voter` has cast a vote on `proposalId`. */
+    hasVoted(proposalId, voter) {
+        return this.publicClient.readContract({
+            address: this.addresses.governor,
+            abi: GOVERNOR_ABI,
+            functionName: "hasVoted",
+            args: [proposalId, voter],
+        });
+    }
+    /** Voting weight of `voter` at a specific block (use the proposal's `snapshot`). */
+    getVotes(voter, timepoint) {
+        return this.publicClient.readContract({
+            address: this.addresses.governor,
+            abi: GOVERNOR_ABI,
+            functionName: "getVotes",
+            args: [voter, timepoint],
+        });
+    }
+    /** Aggregated voting parameters of the LCAIGovernor. */
+    async config() {
+        const [delay, period, threshold] = (await Promise.all([
+            this.publicClient.readContract({ address: this.addresses.governor, abi: GOVERNOR_ABI, functionName: "votingDelay" }),
+            this.publicClient.readContract({ address: this.addresses.governor, abi: GOVERNOR_ABI, functionName: "votingPeriod" }),
+            this.publicClient.readContract({ address: this.addresses.governor, abi: GOVERNOR_ABI, functionName: "proposalThreshold" }),
+        ]));
+        return {
+            votingDelayBlocks: delay,
+            votingPeriodBlocks: period,
+            proposalThresholdWei: threshold,
+            votingPeriodSecs: Number(period) * 12,
+        };
+    }
+    /** Quorum required at a given timepoint (in wei of voting weight). */
+    quorum(timepoint) {
+        return this.publicClient.readContract({
+            address: this.addresses.governor,
+            abi: GOVERNOR_ABI,
+            functionName: "quorum",
+            args: [timepoint],
+        });
+    }
+    // -------- Writes --------
+    /** Cast a For / Against / Abstain vote. Wallet must be the voter and have delegated their LCAI. */
+    castVote(proposalId, support, reason) {
+        if (!this.walletClient)
+            throw new Error("DAO: no wallet client; pass one to the DAO constructor for writes");
+        return reason
+            ? this.walletClient.writeContract({
+                address: this.addresses.governor,
+                abi: GOVERNOR_ABI,
+                functionName: "castVoteWithReason",
+                args: [proposalId, support, reason],
+            })
+            : this.walletClient.writeContract({
+                address: this.addresses.governor,
+                abi: GOVERNOR_ABI,
+                functionName: "castVote",
+                args: [proposalId, support],
+            });
+    }
+    /** Submit a new proposal. Wallet must hold at least `proposalThreshold` delegated votes. */
+    propose(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: "propose",
+            args: [args.targets, args.values, args.calldatas, args.description],
+        });
+    }
+    /** Queue a Succeeded proposal into the timelock. */
+    queue(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: "queue",
+            args: [args.targets, args.values, args.calldatas, args.descriptionHash],
+        });
+    }
+    /**
+     * Execute a Queued proposal. The Governor enforces
+     * `msg.value == sum(values)`; pass the sum as `value`.
+     */
+    execute(args) {
+        if (!this.walletClient)
+            throw new Error("DAO: no wallet client; pass one to the DAO constructor for writes");
+        const totalValue = args.values.reduce((acc, v) => acc + v, 0n);
+        return this.walletClient.writeContract({
+            address: this.addresses.governor,
+            abi: GOVERNOR_ABI,
+            functionName: "execute",
+            args: [args.targets, args.values, args.calldatas, args.descriptionHash],
+            value: totalValue,
+        });
+    }
+}

package/dist/index.d.ts

@@ -2,6 +2,11 @@ import { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS } from "./networks.js";
 import { fromWei } 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";
+import { preflight as workerPreflight, watch as workerWatch } from "./worker.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";
 import { StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker } from "./errors.js";
 import { GatewayClient, GatewayHttpError } from "./gateway.js";
 import * as crypto from "./crypto.js";
@@ -45,6 +50,23 @@ export declare class LightNode {
     isRegistered(address: string): Promise<boolean | null>;
     /** Settled worker earnings in whole LCAI (from total_earned wei). */
     getEarningsLcai(address: string): Promise<number>;
+    /**
+     * One job's current status, classified for builders deciding whether to
+     * retry / claim a refund / accept the answer. `category` is the
+     * 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<{
+        id: string;
+        raw: string;
+        category: "submitted" | "in-flight" | "completed" | "stalled" | "disputed" | "resolved" | "unknown";
+        worker: string | null;
+        model: string | null;
+        submittedAt: number | null;
+        completedAt: number | null;
+        workerShareLcai: number;
+        refundable: boolean;
+    } | null>;
     /** 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). */
@@ -66,8 +88,13 @@ 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.4.9";
-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, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, };
+export declare const SDK_VERSION = "0.5.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, 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 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";
+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 { BaseModel, ModelVariant, AccessTier, AccessPolicy, Benchmark, OnchainModelRegistryOptions } from "./onchain-models.js";
 export type { NetworkId, NetworkConfig, Worker, Job, ModelInfo, NetworkStats, ModelStat, WorkerStat, NetworkAnalytics };

package/dist/index.js

@@ -1,8 +1,13 @@
 import { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS } from "./networks.js";
-import { fetchWorker, fetchWorkerJobs, fetchRecentJobs, fetchModels, fetchWorkers, summarize, fromWei, } from "./subgraph.js";
+import { fetchWorker, fetchWorkerJobs, fetchRecentJobs, fetchJob, fetchModels, fetchWorkers, summarize, fromWei, } 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";
+import { Conversation, chat } from "./chat.js";
+import { preflight as workerPreflight, watch as workerWatch } from "./worker.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";
 import { StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, } from "./errors.js";
 import { GatewayClient, GatewayHttpError } from "./gateway.js";
 import * as crypto from "./crypto.js";
@@ -72,6 +77,48 @@ export class LightNode {
         const w = await fetchWorker(this.network, address);
         return w ? fromWei(w.total_earned) : 0;
     }
+    /**
+     * One job's current status, classified for builders deciding whether to
+     * retry / claim a refund / accept the answer. `category` is the
+     * 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) {
+        const j = await fetchJob(this.network, jobId);
+        if (!j)
+            return null;
+        const state = (j.state ?? "").trim();
+        const stateLow = state.toLowerCase();
+        const category = /completed|released|paid/.test(stateLow)
+            ? "completed"
+            : /timed.?out|stalled|expired/.test(stateLow)
+                ? "stalled"
+                : /disputed/.test(stateLow)
+                    ? "disputed"
+                    : /resolved/.test(stateLow)
+                        ? "resolved"
+                        : /ack/.test(stateLow)
+                            ? "in-flight"
+                            : /submitted/.test(stateLow)
+                                ? "submitted"
+                                : "unknown";
+        // A refund is on the table when the worker accepted the job but never
+        // produced an answer within the protocol's dispute window. The protocol's
+        // 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";
+        return {
+            id: j.id,
+            raw: state,
+            category,
+            worker: j.worker ?? null,
+            model: j.model_id ?? null,
+            submittedAt: j.submitted_at ?? null,
+            completedAt: j.completed_at ?? null,
+            workerShareLcai: fromWei(j.worker_share),
+            refundable,
+        };
+    }
     /** keccak256 of a model tag (its on-chain + indexer id). */
     modelId(tag) {
         return computeModelId(tag);
@@ -96,7 +143,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.4.9";
+export const SDK_VERSION = "0.5.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, 
@@ -105,4 +152,14 @@ runInference,
 // v0.4.3 key-in-answer-out shortcut: same flow, no viem/SIWE wiring.
 runInferenceWithKey, 
 // v0.4.9 AsyncIterable<string> wrapper around runInferenceWithKey.
-runInferenceStream, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, };
+runInferenceStream, 
+// v0.5.0 multi-turn conversation helper (history client-side; one inference per turn).
+Conversation, chat, 
+// v0.5.0 worker preflight + watch (one real test inference + status polling).
+workerPreflight, workerWatch, 
+// v0.5.0 Bridge SDK (Hyperlane Warp Route wrapper for LCAI <-> Ethereum).
+Bridge, BRIDGE_ROUTE, HYPERLANE_ROUTER_ABI, ERC20_ABI, addressToBytes32, quoteBridgeFee, bridgeableBalance, bridgeAllowance, approveBridge, bridgeTransfer, 
+// 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, };