lightnode-sdk 0.4.9 → 0.5.0

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { LightNode, modelStatsCsv, workerStatsCsv, workerJobsCsv, runInferenceWithKey, isStalledWorker } from "./index.js";
+import { LightNode, modelStatsCsv, workerStatsCsv, workerJobsCsv, runInferenceWithKey, isStalledWorker, workerPreflight, workerWatch, BRIDGE_ROUTE, DAO, DAO_ADDRESSES } from "./index.js";
 import { addInference, addAnalyticsDashboard, addNftMint, addChat, addAgent } from "./add.js";
 import { createPublicClient, http, parseEther } from "viem";
 import { privateKeyToAccount, generatePrivateKey } from "viem/accounts";
@@ -32,12 +32,24 @@ Read-only network commands (no key):
   network                  network summary (workers, jobs, models, earnings)
   models                   registered models + per-job fee
   worker <addr>            a worker: on-chain registration + recent jobs
+  worker watch <addr>      poll worker status, print event on change
+                           ([--interval 30] [--stale 90])
   jobs <addr> [--csv]      one worker's job history (table or CSV)
+  job <jobId>              one job's status (category, refundable, worker, timings)
   registered <addr>        true | false | null (read from chain events)
   fee [model]              on-chain inference fee (default llama3-8b)
   analytics [--csv]        per-model performance (completion, p50/p95, incomplete)
   reliability [--csv]      per-worker reliability, busiest first
 
+Preflight (needs PRIVATE_KEY in env):
+  worker preflight         run one real test inference, print verdict + timings
+                           ([--key 0x...] [--model llama3-8b] [--deadline 60])
+
+Ecosystem (read-only):
+  bridge addresses         print bridge route (Ethereum <-> LightChain) addresses
+  dao addresses            print LCAI Governor + Timelock + Treasury addresses
+  dao config               print voting delay / period / threshold (live read)
+
 Scaffold templates into the current project:
   add inference                   end-to-end encrypted inference route/script
   add chat                        chat-style UI with conversation history
@@ -145,11 +157,63 @@ async function main() {
             break;
         }
         case "worker": {
-            const addr = positionals[1] ?? die("usage: lightnode worker <address> [--net testnet]");
+            // Two sub-shapes: `lightnode worker <addr>` (one-shot status) and
+            // `lightnode worker watch <addr>` (long-running event stream) and
+            // `lightnode worker preflight` (submit a test inference).
+            const sub = positionals[1];
+            if (sub === "watch") {
+                const addr = positionals[2] ?? die("usage: lightnode worker watch <address> [--interval 30] [--stale 90]");
+                const intervalSec = Number(flag("--interval") ?? "30");
+                const staleSecs = Number(flag("--stale") ?? "90");
+                const handle = workerWatch(ln, addr, { intervalMs: intervalSec * 1000, staleSecs });
+                process.on("SIGINT", () => {
+                    handle.stop();
+                    process.exit(0);
+                });
+                for await (const event of handle.events) {
+                    console.log(JSON.stringify(event));
+                }
+                break;
+            }
+            if (sub === "preflight") {
+                const privateKey = pickKey();
+                const model = flag("--model") ?? "llama3-8b";
+                const deadlineMs = Number(flag("--deadline") ?? "60") * 1000;
+                console.error(`> preflight against ${net} (model=${model}, deadline=${deadlineMs / 1000}s)...`);
+                const r = await workerPreflight({ network: net, privateKey, model, deadlineMs });
+                const explorer = ln.network.explorer;
+                console.log(JSON.stringify({
+                    verdict: r.verdict,
+                    elapsedSec: Math.round(r.elapsedMs / 100) / 10,
+                    worker: r.worker,
+                    summary: r.summary,
+                    txs: {
+                        createSession: r.txs.createSession ? `${explorer}/tx/${r.txs.createSession}` : null,
+                        submitJob: r.txs.submitJob ? `${explorer}/tx/${r.txs.submitJob}` : null,
+                        jobCompleted: r.txs.jobCompleted ? `${explorer}/tx/${r.txs.jobCompleted}` : null,
+                    },
+                    error: r.error,
+                }, null, 2));
+                if (r.verdict === "failed" || r.verdict === "stalled")
+                    process.exit(1);
+                break;
+            }
+            // Default: one-shot worker summary by address.
+            const addr = sub ?? die("usage: lightnode worker <address|watch|preflight> [...]");
             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;
         }
+        case "job": {
+            const id = positionals[1] ?? die("usage: lightnode job <jobId> [--net testnet]");
+            const status = await ln.getJobStatus(id);
+            if (!status) {
+                console.log(JSON.stringify({ jobId: id, status: "not-indexed" }, null, 2));
+                break;
+            }
+            console.log(JSON.stringify(status, null, 2));
+            break;
+        }
         case "jobs": {
             const addr = positionals[1] ?? die("usage: lightnode jobs <address> [--csv] [--net testnet]");
             const jobs = await ln.getWorkerJobs(addr, 100);
@@ -196,6 +260,45 @@ async function main() {
             }
             break;
         }
+        case "bridge": {
+            const sub = positionals[1];
+            if (sub === "addresses") {
+                console.log(JSON.stringify(BRIDGE_ROUTE, null, 2));
+                break;
+            }
+            die("usage: lightnode bridge <addresses>");
+            break;
+        }
+        case "dao": {
+            const sub = positionals[1];
+            if (sub === "addresses") {
+                console.log(JSON.stringify(DAO_ADDRESSES.ethereum, null, 2));
+                break;
+            }
+            if (sub === "config") {
+                // Live read against Ethereum mainnet. We use viem's HTTP transport
+                // via a minimal inline client (no ethers dep). This is the only
+                // ecosystem read that needs a live RPC, so we wire it lazily.
+                const { createPublicClient, http } = await import("viem");
+                const ethRpc = flag("--rpc") ?? "https://eth.llamarpc.com";
+                const pub = createPublicClient({ transport: http(ethRpc) });
+                // The DAO ctor accepts a structurally-typed MinimalPublicClient; viem's
+                // PublicClient satisfies it. The unknown cast is the standard SDK pattern
+                // for keeping the public API free of viem generic noise.
+                const dao = new DAO(pub, "ethereum");
+                const cfg = await dao.config();
+                console.log(JSON.stringify({
+                    votingDelayBlocks: cfg.votingDelayBlocks.toString(),
+                    votingPeriodBlocks: cfg.votingPeriodBlocks.toString(),
+                    votingPeriodSecs: cfg.votingPeriodSecs,
+                    proposalThresholdLcai: Number(cfg.proposalThresholdWei) / 1e18,
+                    addresses: dao.addresses,
+                }, null, 2));
+                break;
+            }
+            die("usage: lightnode dao <addresses|config> [--rpc <ethereum-rpc>]");
+            break;
+        }
         case "add": {
             const sub = positionals[1];
             const template = flag("--template") ?? "auto";

package/dist/dao.d.ts

@@ -0,0 +1,439 @@
+/**
+ * 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.
+ */
+export type DaoChain = "ethereum";
+export interface DaoAddresses {
+    chainId: number;
+    /** OZ Governor contract. */
+    governor: `0x${string}`;
+    /** Timelock controller. queue/execute dispatch through this. */
+    timelock: `0x${string}`;
+    /** ERC-20 wrapped as IVotes; this is what users delegate / hold to vote. */
+    ballots: `0x${string}`;
+    /** LCAI ERC-20 (the underlying governance token). */
+    token: `0x${string}`;
+    /** Treasury contract holding DAO funds. */
+    treasury: `0x${string}`;
+    explorer: string;
+}
+/** Confirmed Ethereum mainnet addresses (chain 1). */
+export declare const DAO_ADDRESSES: Record<DaoChain, DaoAddresses>;
+/**
+ * The 8-state OZ Governor v5 enum. The string label is what most builders
+ * will want to surface in a UI.
+ */
+export declare enum ProposalState {
+    Pending = 0,
+    Active = 1,
+    Canceled = 2,
+    Defeated = 3,
+    Succeeded = 4,
+    Queued = 5,
+    Expired = 6,
+    Executed = 7
+}
+export declare const PROPOSAL_STATE_LABEL: Record<ProposalState, string>;
+/** Vote support values. Maps to OZ's GovernorCountingSimple. */
+export declare enum VoteSupport {
+    Against = 0,
+    For = 1,
+    Abstain = 2
+}
+/** OZ Governor v5 ABI (subset). */
+export declare const GOVERNOR_ABI: readonly [{
+    readonly name: "propose";
+    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: "string";
+        readonly name: "description";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "proposalId";
+    }];
+}, {
+    readonly name: "castVote";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "proposalId";
+    }, {
+        readonly type: "uint8";
+        readonly name: "support";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "castVoteWithReason";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "proposalId";
+    }, {
+        readonly type: "uint8";
+        readonly name: "support";
+    }, {
+        readonly type: "string";
+        readonly name: "reason";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "queue";
+    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: "execute";
+    readonly type: "function";
+    readonly stateMutability: "payable";
+    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: "state";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "proposalId";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint8";
+    }];
+}, {
+    readonly name: "hashProposal";
+    readonly type: "function";
+    readonly stateMutability: "pure";
+    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: "votingDelay";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "votingPeriod";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "proposalThreshold";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "quorum";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "timepoint";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "proposalVotes";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "proposalId";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "againstVotes";
+    }, {
+        readonly type: "uint256";
+        readonly name: "forVotes";
+    }, {
+        readonly type: "uint256";
+        readonly name: "abstainVotes";
+    }];
+}, {
+    readonly name: "proposalSnapshot";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "proposalId";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "proposalDeadline";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "proposalId";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "proposalProposer";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "proposalId";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "address";
+    }];
+}, {
+    readonly name: "proposalEta";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "proposalId";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "getVotes";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "account";
+    }, {
+        readonly type: "uint256";
+        readonly name: "timepoint";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "hasVoted";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "proposalId";
+    }, {
+        readonly type: "address";
+        readonly name: "account";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}];
+/** Minimal IVotes ABI for delegate + balance reads (LCAIBallots). */
+export declare const VOTES_ABI: readonly [{
+    readonly name: "balanceOf";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "getVotes";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "delegates";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "address";
+    }];
+}, {
+    readonly name: "delegate";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "delegatee";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}];
+interface MinimalPublicClient {
+    readContract: (args: {
+        address: `0x${string}`;
+        abi: readonly unknown[];
+        functionName: string;
+        args?: readonly unknown[];
+    }) => Promise<unknown>;
+}
+interface MinimalWalletClient {
+    writeContract: (args: {
+        address: `0x${string}`;
+        abi: readonly unknown[];
+        functionName: string;
+        args: readonly unknown[];
+        value?: bigint;
+        gas?: bigint;
+    }) => Promise<`0x${string}`>;
+}
+export interface ProposalSummary {
+    id: bigint;
+    state: ProposalState;
+    stateLabel: string;
+    proposer: `0x${string}` | null;
+    snapshot: bigint;
+    deadline: bigint;
+    eta: bigint;
+    votes: {
+        againstWei: bigint;
+        forWei: bigint;
+        abstainWei: bigint;
+    };
+}
+export interface DaoConfig {
+    votingDelayBlocks: bigint;
+    votingPeriodBlocks: bigint;
+    proposalThresholdWei: bigint;
+    /** Approx voting period in seconds, assuming 12s/block on Ethereum. */
+    votingPeriodSecs: number;
+}
+/**
+ * DAO client. Wraps reads (proposal state, config) + writes (propose, vote,
+ * queue, execute) on the Ethereum LCAIGovernor.
+ */
+export declare class DAO {
+    private readonly publicClient;
+    private readonly walletClient?;
+    /** Addresses for the configured DAO chain. Currently only Ethereum mainnet. */
+    readonly addresses: DaoAddresses;
+    constructor(publicClient: MinimalPublicClient, chain?: DaoChain, walletClient?: MinimalWalletClient | undefined);
+    /** Current proposal state by id. */
+    state(proposalId: bigint): Promise<ProposalState>;
+    /** Full proposal summary by id. Aggregates state + votes + key blocks. */
+    proposal(proposalId: bigint): Promise<ProposalSummary>;
+    /** Whether `voter` has cast a vote on `proposalId`. */
+    hasVoted(proposalId: bigint, voter: `0x${string}`): Promise<boolean>;
+    /** Voting weight of `voter` at a specific block (use the proposal's `snapshot`). */
+    getVotes(voter: `0x${string}`, timepoint: bigint): Promise<bigint>;
+    /** Aggregated voting parameters of the LCAIGovernor. */
+    config(): Promise<DaoConfig>;
+    /** Quorum required at a given timepoint (in wei of voting weight). */
+    quorum(timepoint: bigint): Promise<bigint>;
+    /** 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. */
+    propose(args: {
+        targets: `0x${string}`[];
+        values: bigint[];
+        calldatas: `0x${string}`[];
+        description: string;
+    }): Promise<`0x${string}`>;
+    /** Queue a Succeeded proposal into the timelock. */
+    queue(args: {
+        targets: `0x${string}`[];
+        values: bigint[];
+        calldatas: `0x${string}`[];
+        descriptionHash: `0x${string}`;
+    }): Promise<`0x${string}`>;
+    /**
+     * Execute a Queued proposal. The Governor enforces
+     * `msg.value == sum(values)`; pass the sum as `value`.
+     */
+    execute(args: {
+        targets: `0x${string}`[];
+        values: bigint[];
+        calldatas: `0x${string}`[];
+        descriptionHash: `0x${string}`;
+    }): Promise<`0x${string}`>;
+}
+export {};