lightnode-sdk 0.4.8 → 0.5.0

package/dist/onchain-models.d.ts

@@ -0,0 +1,380 @@
+/**
+ * On-chain Model Registry reader (AIVMModelRegistry + BenchmarkRegistry).
+ *
+ * These contracts exist in `lightchain-protocol/lcai-smart-contract` and
+ * describe the full base-model + variant + benchmark + access-policy
+ * surface. As of the time of writing, no public mainnet/testnet deployment
+ * address has been published by the LightChain team - so this module
+ * exposes the typed ABI wrapper and asks the caller to supply the
+ * deployment address when constructing the reader. When LightChain
+ * publishes addresses, we will bake them into a `KNOWN_DEPLOYMENTS` map.
+ *
+ * Usage today (custom deployment):
+ *
+ *   const reader = new OnchainModelRegistry({
+ *     publicClient,
+ *     registry: "0x...",
+ *     benchmarks: "0x...",
+ *   });
+ *   const baseIds = await reader.getBaseModelIds();
+ *
+ * Once LightChain ships the official deployment, this becomes:
+ *
+ *   const reader = new OnchainModelRegistry({ publicClient, network: "mainnet" });
+ */
+export declare const AIVM_MODEL_REGISTRY_ABI: readonly [{
+    readonly name: "getBaseModelIds";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "string[]";
+    }];
+}, {
+    readonly name: "getBaseModel";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "string";
+        readonly name: "modelId";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly type: "string";
+            readonly name: "modelId";
+        }, {
+            readonly type: "string";
+            readonly name: "baseModelCID";
+        }, {
+            readonly type: "string";
+            readonly name: "metadataHash";
+        }, {
+            readonly type: "string";
+            readonly name: "policyVersion";
+        }, {
+            readonly type: "string";
+            readonly name: "benchmarkCID";
+        }, {
+            readonly type: "uint256";
+            readonly name: "createdAt";
+        }, {
+            readonly type: "bool";
+            readonly name: "isActive";
+        }];
+    }];
+}, {
+    readonly name: "getAllVariants";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "string[]";
+    }];
+}, {
+    readonly name: "getTrainerVariants";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "trainer";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "string[]";
+    }];
+}, {
+    readonly name: "getVariant";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "string";
+        readonly name: "variantId";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly type: "string";
+            readonly name: "variantId";
+        }, {
+            readonly type: "string";
+            readonly name: "variantCID";
+        }, {
+            readonly type: "string";
+            readonly name: "metadataHash";
+        }, {
+            readonly type: "string";
+            readonly name: "parentModelId";
+        }, {
+            readonly type: "address";
+            readonly name: "trainer";
+        }, {
+            readonly type: "uint256";
+            readonly name: "trainerStake";
+        }, {
+            readonly type: "uint8";
+            readonly name: "status";
+        }, {
+            readonly type: "uint256";
+            readonly name: "avgScore";
+        }, {
+            readonly type: "string";
+            readonly name: "reportCID";
+        }, {
+            readonly type: "uint256";
+            readonly name: "submittedAt";
+        }, {
+            readonly type: "uint256";
+            readonly name: "validatedAt";
+        }, {
+            readonly type: "uint256";
+            readonly name: "finalizedAt";
+        }, {
+            readonly type: "uint256";
+            readonly name: "validatorCount";
+        }, {
+            readonly type: "bool";
+            readonly name: "challengeWindowOpen";
+        }, {
+            readonly type: "uint256";
+            readonly name: "challengeDeadline";
+        }];
+    }];
+}, {
+    readonly name: "isVariantAvailable";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "string";
+        readonly name: "variantId";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly name: "getAccessPolicy";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "string";
+        readonly name: "variantId";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly type: "bool";
+            readonly name: "requireTicket";
+        }, {
+            readonly type: "uint256";
+            readonly name: "minStakeRequired";
+        }, {
+            readonly type: "address";
+            readonly name: "ticketManager";
+        }, {
+            readonly type: "uint256";
+            readonly name: "ticketTTL";
+        }];
+    }];
+}];
+export declare const BENCHMARK_REGISTRY_ABI: readonly [{
+    readonly name: "listBenchmarks";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "string[]";
+    }];
+}, {
+    readonly name: "listBenchmarksByDomain";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "string";
+        readonly name: "domain";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "string[]";
+    }];
+}, {
+    readonly name: "listBenchmarksByTask";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "string";
+        readonly name: "taskType";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "string[]";
+    }];
+}, {
+    readonly name: "getBenchmark";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "string";
+        readonly name: "benchmarkId";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly type: "string";
+            readonly name: "benchmarkId";
+        }, {
+            readonly type: "string";
+            readonly name: "domain";
+        }, {
+            readonly type: "string";
+            readonly name: "taskType";
+        }, {
+            readonly type: "string";
+            readonly name: "benchmarkCID";
+        }, {
+            readonly type: "string";
+            readonly name: "metadataCID";
+        }, {
+            readonly type: "string";
+            readonly name: "manifestHash";
+        }, {
+            readonly type: "string";
+            readonly name: "wrappedDEK";
+        }, {
+            readonly type: "string";
+            readonly name: "version";
+        }, {
+            readonly type: "address";
+            readonly name: "curator";
+        }, {
+            readonly type: "uint256";
+            readonly name: "registeredAt";
+        }, {
+            readonly type: "bool";
+            readonly name: "encrypted";
+        }, {
+            readonly type: "bool";
+            readonly name: "active";
+        }];
+    }];
+}, {
+    readonly name: "getBenchmarkForVariant";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "string";
+        readonly name: "domain";
+    }, {
+        readonly type: "string";
+        readonly name: "taskType";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "string";
+        readonly name: "benchmarkId";
+    }];
+}];
+/** Model status enum from AIVMModelRegistry. */
+export declare enum ModelStatus {
+    Submitted = 0,
+    Validating = 1,
+    Approved = 2,
+    Rejected = 3,
+    Finalized = 4,
+    Deprecated = 5
+}
+export declare const MODEL_STATUS_LABEL: Record<ModelStatus, string>;
+export interface BaseModel {
+    modelId: string;
+    baseModelCID: string;
+    metadataHash: string;
+    policyVersion: string;
+    benchmarkCID: string;
+    createdAt: bigint;
+    isActive: boolean;
+}
+export interface ModelVariant {
+    variantId: string;
+    variantCID: string;
+    metadataHash: string;
+    parentModelId: string;
+    trainer: `0x${string}`;
+    trainerStake: bigint;
+    status: ModelStatus;
+    avgScore: bigint;
+    reportCID: string;
+    submittedAt: bigint;
+    validatedAt: bigint;
+    finalizedAt: bigint;
+    validatorCount: bigint;
+    challengeWindowOpen: boolean;
+    challengeDeadline: bigint;
+}
+/**
+ * Builder-friendly access tier inferred from the raw AccessPolicyConfig
+ * fields. The contract's policy is more granular (ticket manager, TTL, etc.)
+ * but most consumers want to know "is this model free / paywalled / gated".
+ */
+export type AccessTier = "free" | "paywalled" | "ticket-gated";
+export interface AccessPolicy {
+    requireTicket: boolean;
+    minStakeRequiredWei: bigint;
+    ticketManager: `0x${string}`;
+    ticketTtlSecs: bigint;
+    tier: AccessTier;
+}
+export interface Benchmark {
+    benchmarkId: string;
+    domain: string;
+    taskType: string;
+    benchmarkCID: string;
+    metadataCID: string;
+    manifestHash: string;
+    wrappedDEK: string;
+    version: string;
+    curator: `0x${string}`;
+    registeredAt: bigint;
+    encrypted: boolean;
+    active: boolean;
+}
+interface MinimalPublicClient {
+    readContract: (args: {
+        address: `0x${string}`;
+        abi: readonly unknown[];
+        functionName: string;
+        args?: readonly unknown[];
+    }) => Promise<unknown>;
+}
+export interface OnchainModelRegistryOptions {
+    publicClient: MinimalPublicClient;
+    /** Deployed AIVMModelRegistry address. */
+    registry: `0x${string}`;
+    /** Optional: deployed BenchmarkRegistry address for the benchmark methods. */
+    benchmarks?: `0x${string}`;
+}
+/**
+ * Typed reader for AIVMModelRegistry + BenchmarkRegistry. Pass deployed
+ * contract addresses; the SDK does not bake in defaults until LightChain
+ * publishes them.
+ */
+export declare class OnchainModelRegistry {
+    private readonly opts;
+    readonly registry: `0x${string}`;
+    readonly benchmarks: `0x${string}` | null;
+    constructor(opts: OnchainModelRegistryOptions);
+    getBaseModelIds(): Promise<string[]>;
+    getBaseModel(modelId: string): Promise<BaseModel>;
+    getAllVariants(): Promise<string[]>;
+    getTrainerVariants(trainer: `0x${string}`): Promise<string[]>;
+    getVariant(variantId: string): Promise<ModelVariant>;
+    isVariantAvailable(variantId: string): Promise<boolean>;
+    /**
+     * Variant access policy. The raw struct has four fields; this also adds
+     * a `tier` heuristic ("free" / "paywalled" / "ticket-gated") for builders
+     * who do not want to interpret the fields themselves.
+     */
+    getAccessPolicy(variantId: string): Promise<AccessPolicy>;
+    /** Return only the variants whose parentModelId matches `baseModelId`. */
+    getVariantsForBaseModel(baseModelId: string): Promise<ModelVariant[]>;
+    private requireBenchmarks;
+    listBenchmarks(): Promise<string[]>;
+    listBenchmarksByDomain(domain: string): Promise<string[]>;
+    getBenchmark(benchmarkId: string): Promise<Benchmark>;
+    getBenchmarkForVariant(domain: string, taskType: string): Promise<string>;
+}
+export {};

package/dist/onchain-models.js

@@ -0,0 +1,187 @@
+/**
+ * On-chain Model Registry reader (AIVMModelRegistry + BenchmarkRegistry).
+ *
+ * These contracts exist in `lightchain-protocol/lcai-smart-contract` and
+ * describe the full base-model + variant + benchmark + access-policy
+ * surface. As of the time of writing, no public mainnet/testnet deployment
+ * address has been published by the LightChain team - so this module
+ * exposes the typed ABI wrapper and asks the caller to supply the
+ * deployment address when constructing the reader. When LightChain
+ * publishes addresses, we will bake them into a `KNOWN_DEPLOYMENTS` map.
+ *
+ * Usage today (custom deployment):
+ *
+ *   const reader = new OnchainModelRegistry({
+ *     publicClient,
+ *     registry: "0x...",
+ *     benchmarks: "0x...",
+ *   });
+ *   const baseIds = await reader.getBaseModelIds();
+ *
+ * Once LightChain ships the official deployment, this becomes:
+ *
+ *   const reader = new OnchainModelRegistry({ publicClient, network: "mainnet" });
+ */
+import { parseAbi } from "viem";
+export const AIVM_MODEL_REGISTRY_ABI = parseAbi([
+    "function getBaseModelIds() external view returns (string[])",
+    "function getBaseModel(string modelId) external view returns ((string modelId, string baseModelCID, string metadataHash, string policyVersion, string benchmarkCID, uint256 createdAt, bool isActive))",
+    "function getAllVariants() external view returns (string[])",
+    "function getTrainerVariants(address trainer) external view returns (string[])",
+    "function getVariant(string variantId) external view returns ((string variantId, string variantCID, string metadataHash, string parentModelId, address trainer, uint256 trainerStake, uint8 status, uint256 avgScore, string reportCID, uint256 submittedAt, uint256 validatedAt, uint256 finalizedAt, uint256 validatorCount, bool challengeWindowOpen, uint256 challengeDeadline))",
+    "function isVariantAvailable(string variantId) external view returns (bool)",
+    "function getAccessPolicy(string variantId) external view returns ((bool requireTicket, uint256 minStakeRequired, address ticketManager, uint256 ticketTTL))",
+]);
+export const BENCHMARK_REGISTRY_ABI = parseAbi([
+    "function listBenchmarks() external view returns (string[])",
+    "function listBenchmarksByDomain(string domain) external view returns (string[])",
+    "function listBenchmarksByTask(string taskType) external view returns (string[])",
+    "function getBenchmark(string benchmarkId) external view returns ((string benchmarkId, string domain, string taskType, string benchmarkCID, string metadataCID, string manifestHash, string wrappedDEK, string version, address curator, uint256 registeredAt, bool encrypted, bool active))",
+    "function getBenchmarkForVariant(string domain, string taskType) external view returns (string benchmarkId)",
+]);
+/** Model status enum from AIVMModelRegistry. */
+export var ModelStatus;
+(function (ModelStatus) {
+    ModelStatus[ModelStatus["Submitted"] = 0] = "Submitted";
+    ModelStatus[ModelStatus["Validating"] = 1] = "Validating";
+    ModelStatus[ModelStatus["Approved"] = 2] = "Approved";
+    ModelStatus[ModelStatus["Rejected"] = 3] = "Rejected";
+    ModelStatus[ModelStatus["Finalized"] = 4] = "Finalized";
+    ModelStatus[ModelStatus["Deprecated"] = 5] = "Deprecated";
+})(ModelStatus || (ModelStatus = {}));
+export const MODEL_STATUS_LABEL = {
+    [ModelStatus.Submitted]: "submitted",
+    [ModelStatus.Validating]: "validating",
+    [ModelStatus.Approved]: "approved",
+    [ModelStatus.Rejected]: "rejected",
+    [ModelStatus.Finalized]: "finalized",
+    [ModelStatus.Deprecated]: "deprecated",
+};
+/**
+ * Typed reader for AIVMModelRegistry + BenchmarkRegistry. Pass deployed
+ * contract addresses; the SDK does not bake in defaults until LightChain
+ * publishes them.
+ */
+export class OnchainModelRegistry {
+    constructor(opts) {
+        this.opts = opts;
+        this.registry = opts.registry;
+        this.benchmarks = opts.benchmarks ?? null;
+    }
+    // -------- AIVMModelRegistry reads --------
+    getBaseModelIds() {
+        return this.opts.publicClient.readContract({
+            address: this.registry,
+            abi: AIVM_MODEL_REGISTRY_ABI,
+            functionName: "getBaseModelIds",
+        });
+    }
+    getBaseModel(modelId) {
+        return this.opts.publicClient.readContract({
+            address: this.registry,
+            abi: AIVM_MODEL_REGISTRY_ABI,
+            functionName: "getBaseModel",
+            args: [modelId],
+        });
+    }
+    getAllVariants() {
+        return this.opts.publicClient.readContract({
+            address: this.registry,
+            abi: AIVM_MODEL_REGISTRY_ABI,
+            functionName: "getAllVariants",
+        });
+    }
+    getTrainerVariants(trainer) {
+        return this.opts.publicClient.readContract({
+            address: this.registry,
+            abi: AIVM_MODEL_REGISTRY_ABI,
+            functionName: "getTrainerVariants",
+            args: [trainer],
+        });
+    }
+    async getVariant(variantId) {
+        const raw = (await this.opts.publicClient.readContract({
+            address: this.registry,
+            abi: AIVM_MODEL_REGISTRY_ABI,
+            functionName: "getVariant",
+            args: [variantId],
+        }));
+        return { ...raw, status: raw.status };
+    }
+    isVariantAvailable(variantId) {
+        return this.opts.publicClient.readContract({
+            address: this.registry,
+            abi: AIVM_MODEL_REGISTRY_ABI,
+            functionName: "isVariantAvailable",
+            args: [variantId],
+        });
+    }
+    /**
+     * Variant access policy. The raw struct has four fields; this also adds
+     * a `tier` heuristic ("free" / "paywalled" / "ticket-gated") for builders
+     * who do not want to interpret the fields themselves.
+     */
+    async getAccessPolicy(variantId) {
+        const raw = (await this.opts.publicClient.readContract({
+            address: this.registry,
+            abi: AIVM_MODEL_REGISTRY_ABI,
+            functionName: "getAccessPolicy",
+            args: [variantId],
+        }));
+        let tier = "free";
+        if (raw.requireTicket)
+            tier = "ticket-gated";
+        else if (raw.minStakeRequired > 0n)
+            tier = "paywalled";
+        return {
+            requireTicket: raw.requireTicket,
+            minStakeRequiredWei: raw.minStakeRequired,
+            ticketManager: raw.ticketManager,
+            ticketTtlSecs: raw.ticketTTL,
+            tier,
+        };
+    }
+    /** Return only the variants whose parentModelId matches `baseModelId`. */
+    async getVariantsForBaseModel(baseModelId) {
+        const allIds = await this.getAllVariants();
+        const variants = await Promise.all(allIds.map((id) => this.getVariant(id)));
+        return variants.filter((v) => v.parentModelId === baseModelId);
+    }
+    // -------- BenchmarkRegistry reads --------
+    requireBenchmarks() {
+        if (!this.benchmarks)
+            throw new Error("OnchainModelRegistry: no BenchmarkRegistry address; pass `benchmarks` in the constructor");
+        return this.benchmarks;
+    }
+    listBenchmarks() {
+        return this.opts.publicClient.readContract({
+            address: this.requireBenchmarks(),
+            abi: BENCHMARK_REGISTRY_ABI,
+            functionName: "listBenchmarks",
+        });
+    }
+    listBenchmarksByDomain(domain) {
+        return this.opts.publicClient.readContract({
+            address: this.requireBenchmarks(),
+            abi: BENCHMARK_REGISTRY_ABI,
+            functionName: "listBenchmarksByDomain",
+            args: [domain],
+        });
+    }
+    getBenchmark(benchmarkId) {
+        return this.opts.publicClient.readContract({
+            address: this.requireBenchmarks(),
+            abi: BENCHMARK_REGISTRY_ABI,
+            functionName: "getBenchmark",
+            args: [benchmarkId],
+        });
+    }
+    getBenchmarkForVariant(domain, taskType) {
+        return this.opts.publicClient.readContract({
+            address: this.requireBenchmarks(),
+            abi: BENCHMARK_REGISTRY_ABI,
+            functionName: "getBenchmarkForVariant",
+            args: [domain, taskType],
+        });
+    }
+}

package/dist/subgraph.d.ts

@@ -2,6 +2,8 @@ import type { NetworkConfig, Worker, Job, ModelInfo, NetworkStats } from "./type
 /** 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>;
+/** Fetch one job by its on-chain id. Null when the indexer has never seen it. */
+export declare function fetchJob(cfg: NetworkConfig, jobId: string | bigint): Promise<Job | null>;
 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[]>;

package/dist/subgraph.js

@@ -56,6 +56,12 @@ export async function fetchWorker(cfg, address) {
         throw e;
     }
 }
+/** 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 } }`);
+    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 } }`);
     return data.jobs ?? [];

package/dist/worker.d.ts

@@ -0,0 +1,104 @@
+/**
+ * SDK-level worker preflight + watch.
+ *
+ * The desktop app already has local worker-health parsers (parseWorkerHealth,
+ * parseSpeedTest) that need shell access to the running container. Those are
+ * great for operators ON the worker box, but useless for a builder watching
+ * the network from anywhere else.
+ *
+ * This module fills the remote-only gap:
+ *   - `preflight()` runs ONE real test inference against the live network
+ *     and returns a verdict (works / over-deadline / failed). This is the
+ *     "test job before joining a worker pool" the community has been asking
+ *     for; works from any machine with a funded wallet.
+ *   - `watch()` polls a worker's on-chain + indexer status on a fixed
+ *     interval and yields an event each time the status meaningfully
+ *     changes (registered <-> deregistered, last-seen went stale, completion
+ *     rate dropped). Suitable for a CI gate or a `cron` job.
+ *
+ * Both are pure SDK calls. No Docker, no SSH, no privileged access.
+ */
+import { type RunInferenceWithKeyArgs } from "./inference.js";
+import { LightNode } from "./index.js";
+export interface WorkerPreflightArgs extends Omit<RunInferenceWithKeyArgs, "prompt"> {
+    /**
+     * Prompt to send. Defaults to a tiny, deterministic prompt so the test is
+     * cheap (one short answer is enough to verify the round trip).
+     */
+    prompt?: string;
+    /**
+     * Verdict deadline. If the inference takes longer than this many ms but
+     * still completes, the verdict is "over-deadline" instead of "ok". Default
+     * 60s, matching the protocol's typical good-worker p95.
+     */
+    deadlineMs?: number;
+}
+export interface WorkerPreflightResult {
+    verdict: "ok" | "over-deadline" | "stalled" | "failed";
+    /** Total elapsed milliseconds from the first SDK call to the decrypted answer. */
+    elapsedMs: number;
+    /** Plain-English summary suitable for printing to a CLI or alerting. */
+    summary: string;
+    /** The actual decrypted answer (may be empty on failure). */
+    answer: string;
+    /** Address of the dispatcher-assigned worker that produced (or failed) the response. */
+    worker: `0x${string}` | null;
+    /** On-chain receipts. `jobCompleted` may be null when the WS delivered the answer but the on-chain event is still propagating. */
+    txs: {
+        createSession: `0x${string}` | null;
+        submitJob: `0x${string}` | null;
+        jobCompleted: `0x${string}` | null;
+    };
+    /** Underlying error if the test did not complete cleanly. */
+    error: string | null;
+}
+/**
+ * Run one real encrypted inference against the live network and classify
+ * the result. Useful as a CI gate ("did the wallet survive a real call this
+ * deploy?") or as a pre-join check for a worker operator who wants to test
+ * the protocol path before staking.
+ */
+export declare function preflight(args: WorkerPreflightArgs): Promise<WorkerPreflightResult>;
+export interface WorkerWatchOptions {
+    /** Polling interval in milliseconds. Default 30s. Indexer / RPC usage scales linearly. */
+    intervalMs?: number;
+    /**
+     * Mark the worker as "stale" when its last_seen_at is older than this many
+     * seconds. Default 90 (matches the worker daemon's heartbeat cadence + grace).
+     */
+    staleSecs?: number;
+    /**
+     * Stop polling automatically after this many events. Default Infinity (the
+     * caller controls lifetime via the returned `stop()` function).
+     */
+    maxEvents?: number;
+}
+export type WorkerEventKind = "snapshot" | "registered" | "deregistered" | "went-stale" | "back-online" | "jobs-completed" | "earnings-up";
+export interface WorkerEvent {
+    kind: WorkerEventKind;
+    at: number;
+    worker: string;
+    network: "mainnet" | "testnet";
+    /** Snapshot of the worker at the moment the event was raised. */
+    state: {
+        registered: boolean | null;
+        lastSeenSecsAgo: number | null;
+        jobsCompleted: number | null;
+        earningsLcai: number;
+        activeJobs: number | null;
+        isStale: boolean;
+    };
+}
+export interface WorkerWatchHandle {
+    /** AsyncIterable of events; consume with `for await (const e of handle.events) ...`. */
+    events: AsyncIterable<WorkerEvent>;
+    /** Stop polling and end the iterator gracefully. */
+    stop: () => void;
+}
+/**
+ * Poll one worker's on-chain + indexer status and yield an event each time
+ * something meaningful changes (registration, staleness, completed-jobs
+ * counter, earnings). Runs until `handle.stop()` is called or `maxEvents`
+ * is reached.
+ */
+export declare function watch(ln: LightNode, address: string, opts?: WorkerWatchOptions): WorkerWatchHandle;