Build with, and run for, LightChain AI.
A community-built developer and operator suite for the LightChain AI network. It has a published SDK for encrypted inference, scaffolders that drop the SDK into any project with one command, a live in-browser playground, and a desktop app for running a worker. One project, two tracks.
If you're new to blockchain or Node.js development, read GETTING-STARTED.md first. It assumes no experience and covers, in about 5 minutes, making a wallet, getting free testnet funds, your first AI call, and the difference between the two ways to build (so you don't end up with a confusing mix of files). The rest of this README and the SDK docs assume you're already comfortable with a terminal and TypeScript.
Two completely separate use cases live in this repo. Pick the one that matches what you actually want.
-
You are a developer. You want to add AI to your own app, paying per call, on a decentralized network instead of a single hosted vendor. Install
lightnode-sdk, paste five lines of code, and your app can run encrypted prompts on the LightChain AI network. The network is decentralized, so it is not one company running it. Your wallet pays for each call directly on chain. -
You have a decent computer. You want to make a bit of LCAI by serving prompts to other people's apps. Install the LightNode desktop app, click through the install wizard, and your machine becomes a worker on the network. The app handles the keys, the staking, the Docker container, and watches the worker so it stays online.
The two halves share one codebase and one community, but most people only need one of them.
lightnode-sdk@0.7.x. The worker-operator surface: run a worker's full on-chain lifecycle from code, the part that previously needed the worker Docker image or reverse-engineering unverified contracts.WorkerOperatorcovers register, stake (topUpStake/withdrawStake/reinstate), settle (releaseJob/releaseAll/withdraw), live protocol config, and the headline stuck-job recovery (claimTimeout/clearStuck/unstickAndDeregister) that clears acknowledged-but-unfinished jobs which otherwise block deregistration, plusdecodeWorkerErrorfor plain-English reverts. New CLI:lightnode worker status | can-deregister | settle | clearstuck | withdraw | deregister.lightnode-sdk@0.6.x. Higher-level abstractions on top of the encrypted inference layer:runInferenceBatch(parallel inference with capped concurrency, stable result order, per-slot errors), theAgentclass (ReAct-style tool calling with<tool>/<answer>markers, works on llama3-8b without native function calling), andAbortSignalsupport acrossrunInference+runInferenceWithKeyso a UI can cancel pending awaits. CLI gainslightnode batch <prompts.json>andlightnode agent <task>.lightnode-sdk@0.5.x. Six SDK modules in one ecosystem release: Bridge SDK (Hyperlane Warp Route, LCAI between Ethereum and LightChain), DAO SDK (LCAIGovernor on Ethereum + LightChainGovernor with NativeVotes precompile on chain 9200), OnchainModelRegistry reader, multi-turnConversation,workerPreflight+workerWatch, andln.getJobStatus(refundable classification).- Interactive CLI runner on
/build. Click a command on the left, hit Run, see the real JSON output in the browser. Backed by a server route that runs the LightNode method server-side. - Live mainnet data on
/build. Four cards showing network stats + top workers + registered models + per-model performance, refreshed every minute, with the SDK snippet that produced each one. - Standalone examples repo at
marinom2/lightnode-exampleswith eight runnable examples (one per SDK module). Opens in StackBlitz in seconds. - Live playground at https://lightnode.app/playground. Connect a wallet, type a prompt, run one real encrypted inference in your browser. Free on testnet.
|
You want encrypted inference in your dApp.
# Brand-new project:
npm create lightnode-app my-app
# Existing project (auto-detects Next.js, Hono, or Node):
npx lightnode add inferenceTry it first: https://lightnode.app/playground Builder hub: https://lightnode.app/build |
You want to earn LCAI by serving inference jobs.
# Download the desktop app:
# https://github.com/marinom2/lightnode/releases
# Or use the web version (copy/paste commands):
# https://lightnode.app/onboardWeb app: https://lightnode.app Operator manual: docs/WORKER_LIFECYCLE.md |
| Package | Version | What it does |
|---|---|---|
lightnode-sdk |
0.7.x |
Full ecosystem: encrypted inference (runInferenceWithKey, runInference, runInferenceStream, Conversation, runInferenceBatch, Agent, AbortSignal everywhere, lower-level prepareSession + submitPrompt + decryptResponse), read-only chain client (LightNode methods + CSV exporters), Bridge SDK, DAO SDK (both governors), OnchainModelRegistry reader, worker preflight + watch, the WorkerOperator write surface (register / stake / settle / stuck-job recovery / deregister), job-status / refund query. Plus the lightnode CLI with read-only + worker-operator subcommands + five add scaffolders. |
create-lightnode-app |
0.2.x |
One-command scaffolder for a brand-new LightChain dApp. Three templates: Node CLI, Next.js, Hono. Pins lightnode-sdk ^0.7.0 so new projects get the full ecosystem out of the box. |
lightnode add (inside lightnode-sdk) |
n/a | Patch an existing project. Auto-detects the framework, writes the right files. Safe to re-run. |
npx lightnode add inference # encrypted inference route or script
npx lightnode add chat # chat UI with conversation history
npx lightnode add agent # scheduled inference (Vercel Cron or setInterval)
npx lightnode add analytics-dashboard # read-only network + worker analytics page
npx lightnode add nft-mint-with-inference # AI-generated NFT metadata with on-chain provenanceAll add commands accept --template auto|nextjs-api|hono|node,
--net testnet|mainnet, and --force.
The SDK exposes everything you need to talk to the LightChain AI network from your own code. It splits into three groups, top to bottom:
1. Encrypted inference (paid). The thing most builders want. Run a prompt, get an answer back, pay per call in LCAI.
| You want to... | Use |
|---|---|
| Run one prompt in five lines. No wallet wiring. | runInferenceWithKey({ network, privateKey, prompt }) |
| Same flow, but you already have viem clients and a SIWE JWT in your app. | runInference({ gateway, wallet, publicClient, network, prompt }) |
| Drive each step yourself (custom retry, custom streaming, multi-turn). | prepareSession, submitPrompt, decryptResponse, plus your own viem calls. |
2. Read-only chain client (free). All the data the network exposes, without paying for anything. Use this for dashboards, leaderboards, gating logic, or to check things before you spend.
import { LightNode } from "lightnode-sdk";
const ln = new LightNode("mainnet");
await ln.getWorker("0x..."); // one worker's full record
await ln.getWorkers(); // all registered workers
await ln.getWorkerJobs("0x...", 20); // recent jobs for a worker
await ln.getModels(); // network's registered models (fees, limits)
await ln.getNetworkStats(); // totals + active count + earnings
await ln.getModelStats(1000); // per-model completion, p50/p95, disputes
await ln.getWorkerStats(1000, 25); // per-worker reliability, busiest first
await ln.getNetworkAnalytics(1000); // network-wide rollup
await ln.isRegistered("0x..."); // authoritative on-chain truth (no indexer lag)
await ln.estimateFee("llama3-8b"); // what `submitJob` will charge3. Helpers. Things you sometimes need around inference: consumerGatewayUrl,
estimateJobFee, the typed errors (StalledWorkerError, OnChainRevertError,
RelayTokenTimeoutError, GatewayAuthError) with the isStalledWorker type
guard, CSV writers (modelStatsCsv, workerStatsCsv, workerJobsCsv), and
fromWei for formatting earnings.
Concrete recipes per common starting point. The right side is what to install and what file ends up where.
| Your starting point | What to run | What you get |
|---|---|---|
| Nothing yet, just want to try | npm create lightnode-app my-app |
A new project with Node, Next.js, or Hono. Pick one, fill in .env, npm start. |
| Empty terminal, one prompt | git clone marinom2/lightnode-examples && cd quickstart-inference && npm start |
A 30-line script. First run prints address + faucet; second run fires the prompt. |
| An existing Next.js app | cd your-app && npx lightnode add inference |
A new app/api/inference/route.ts. POST a JSON body, get the answer back. Wallet stays server-side. |
| An existing Next.js app + a chatbot UI | cd your-app && npx lightnode add chat |
A streaming chat page with conversation history. Same protocol, plus session reuse. |
| A scheduled task (daily summary, monitoring agent) | cd your-app && npx lightnode add agent |
A Vercel Cron route in Next.js, or a setInterval script in plain Node. Includes CRON_SECRET Bearer-auth in the Next.js variant. |
| A Discord bot, Cloudflare Worker, or CLI tool | npm install lightnode-sdk viem ws plus the hono-server snippet |
A Hono /inference endpoint you can host anywhere with Node. |
| A user-facing leaderboard or worker dashboard | cd your-app && npx lightnode add analytics-dashboard |
A read-only page that pulls live network + worker stats and renders them. No keys, no wallet. |
| An NFT mint where each mint generates unique metadata with AI | cd your-app && npx lightnode add nft-mint-with-inference |
A mint flow that runs an inference, anchors the answer to a content hash, and returns metadata. |
| You want users to pay per call from their own wallet (no server custody) | Copy the playground source | The wallet-connect path. User signs createSession + submitJob in their browser, pays the LCAI directly from their connected wallet. |
The biggest decision when wiring inference into your app: whose wallet pays for each call?
- Server-pays (the API-route examples). You hold a hot wallet on the server, top it up, the user just hits your API. Familiar pattern: the user does not need a wallet at all. Cheaper UX for the user. You own the cost.
- User-pays (the playground). The user connects their own wallet and signs the two on-chain transactions per call. You hold no keys and bear no cost, but the user needs LCAI in their wallet. This is the closest to "AI as a primitive" the network offers.
Both use the same SDK. The split is just whether you build it on top of
runInferenceWithKey (server-pays) or wire viem's useWalletClient to a
React component (user-pays).
| Path | What | Time | Cost |
|---|---|---|---|
| Live playground | Browser, connect wallet, run one real inference. | About 30 sec | Free on testnet |
| Open in StackBlitz | Cloud IDE, starter pre-installed. | About 5 sec | Free testnet |
| Open in Codespaces | Full VS Code dev environment with the examples repo. | About 1 min | GitHub free tier covers it |
The SDK is tested end-to-end with real LCAI on both networks before each release.
| Network | createSession tx | submitJob tx |
|---|---|---|
| mainnet (9200) | 0xf091957f...57d4a6ca |
0x6ff44a4a...79846bb89 |
| testnet (8200) | 0x77686f3f...ef2bc587 |
0xba9d48c4...293b2bd96 |
Decrypted output, full receipts, and the source that ran them all live on
lightnode.app/build.
Runnable examples live in their own small repo so cloud IDEs clone them in
seconds: marinom2/lightnode-examples.
The repo has quickstart-inference (about 30 lines, auto-bootstraps a testnet
key on first run), nextjs-api-route, and hono-server.
What is in this repo:
| Path | What |
|---|---|
sdk/ |
The lightnode-sdk source. |
create-lightnode-app/ |
The scaffolder source. |
app/playground/page.tsx |
The full in-browser playground. Same SDK, with Reown/wagmi wallet connect. |
A consumer desktop and web app for running a LightChain AI worker. Same project as the build track, completely separate user flow.
- Real machine readiness. Native CPU, RAM, GPU, VRAM detection, a capacity score, and a Speed test that runs a real inference against the live on-chain deadline.
- One-click, wallet-funded install. Generates and secures the worker key. Funds and stakes from your connected wallet. Registers on chain. Brings the worker online. Shows live progress and plain-English error messages.
- Stays online for you. A watchdog auto-starts Docker and the worker, keeps the model warm, optional downtime alerts via Discord webhook.
- Multi-model serving with a memory-fit gate, and live add-a-model from the dashboard.
- Full lifecycle, no terminal. Live earnings (settled vs pending-release), settle/claim, clear stuck jobs, deregister, gas-aware withdraw, free-up-memory, replaced-key recovery, removed-worker uninstall.
- Honest dashboard. On-chain registration reader (works even when the public indexer lags a deregister + re-register cycle), one honest status pill, per-job processing time vs deadline, CSV export of any worker's job history.
- Network analytics at
/network. Honest completion (jobs the indexer leaves stuck count as failures), p50/p95 latency, per-worker reliability, CSV-exportable.
| Step | Where |
|---|---|
| 1. Download the desktop app | Releases |
| 2. Or use the web app and copy/run commands | https://lightnode.app/onboard |
| 3. Full operator manual | docs/WORKER_LIFECYCLE.md |
| OS | Status |
|---|---|
| macOS (Apple Silicon) | Tested end-to-end on testnet and mainnet. |
| Linux | Installers build in CI and commands are syntax-checked. Full flow not yet hardware-verified. Community testing welcome. |
| Windows | Installers build in CI and PowerShell is parse-checked. Full flow not yet hardware-verified. Community testing welcome. |
LightChain AI runs two networks. Same protocol, different chain IDs and contract addresses.
| Testnet | Mainnet | |
|---|---|---|
| Chain ID | 8200 | 9200 |
| RPC | https://rpc.testnet.lightchain.ai |
https://rpc.mainnet.lightchain.ai |
| Explorer | https://testnet.lightscan.app | https://mainnet.lightscan.app |
| Faucet | https://lightfaucet.ai | n/a, bridge or buy LCAI |
| Worker min stake | 5,000 LCAI | 50,000 LCAI |
| Inference cost | free (testnet LCAI) | about 0.022 LCAI per call |
- Frontend. Next.js 15 (App Router), React 19, Tailwind v4. Wallet via Reown
AppKit (wagmi + viem). Live network data through server-side
/api/*proxy routes (no client CORS, same-origin from the browser's perspective). - Desktop. Tauri v2 shell that loads the hosted web UI and exposes a few
native commands over IPC. A
vercel --proddeploy reaches the desktop app on its next page load. No new installer needed for most changes. - SDK. Pure TypeScript, ESM, ships to npm. Single peer dep:
viem. Works in both browser and Node (Web Crypto viaglobalThis). Source of truth for the SDK ABI, the gateway client, the relay frame format, and the analytics aggregators. - Worker integration. The on-disk keystore and worker container are the source of truth for signing. Any on-chain worker action derives the signing key from the keystore the worker actually runs with and verifies the derived address against the target worker. Refuses to sign one network's action with another network's key.
Longer write-up in docs/ARCHITECTURE.md.
LightNode is non-custodial, on both tracks.
- The SDK never holds your private key. Your wallet signs every on-chain call via viem. The SDK only prepares the data and talks to the consumer gateway.
- The worker app generates the worker key locally, stores it in the OS keychain (with a localStorage fallback on unsigned builds), and writes the toolkit's keystore on disk. All worker payout transactions are signed locally on your machine.
- The funding wallet only reads its address and sends LCAI. It never signs worker operations.
Reporting a vulnerability: SECURITY.md.
.
├── app/ # Next.js routes (lightnode.app)
│ ├── build/ # Builder hub
│ ├── playground/ # Live in-browser inference
│ ├── network/ # Public analytics
│ ├── onboard/ # Worker onboarding wizard
│ ├── dashboard/ # Worker dashboard
│ └── api/ # /api/* proxy + subgraph routes
├── components/ # React UI (worker view, operations, install progress, ...)
├── lib/ # scriptgen, install-progress diagnoser, subgraph client, hardware scoring, ...
├── sdk/ # lightnode-sdk source (published to npm)
├── create-lightnode-app/# create-lightnode-app source (published to npm)
├── desktop/ # Tauri v2 shell (src-tauri)
├── tests/unit + tests/e2e/ # Vitest + Playwright
└── docs/ # Worker lifecycle, architecture, UI/design, releasing
npm run lint && npm run typecheck && npm test && npm run build
npm run test:e2e
cd sdk && npm run typecheck && npm run buildState on main: lint clean, typecheck clean, 220 unit tests, 16 test files,
production build clean, SDK build clean, both CLIs smoke-tested live against
real testnet and mainnet inferences.
See CONTRIBUTING.md. TypeScript with no any. Pure logic in
lib/ with a matching test. Design tokens over hardcoded colors. Conventional
commits.
MIT. See LICENSE. Copyright (c) 2026 KykyRykyPaloma.
LightNode is an independent, community-built tool for the LightChain AI
ecosystem. Not affiliated with or endorsed by the LightChain AI team.
Review the official lightchain-worker-toolkit
for the worker runtime's own security and operational model.