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. The latest 0.7.x sendsderegisterWorker()directly with a gas-correct limit, so a worker can exit and recover its stake with no toolkit clone, no Docker, and no running container, even after a half-finished install.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. |
Server-paid (you host a backend; your funded wallet pays per call):
npx lightnode add inference # encrypted inference route or script
npx lightnode add chat # chat UI with conversation history
npx lightnode add judge # pass/fail evaluator route (criteria + evidence)
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 provenanceUser-paid (no backend; each visitor signs + pays from their own wallet):
npx lightnode add inference-web3 # one-shot inference UI, wallet-signed
npx lightnode add chat-web3 # chat UI, wallet-signed (mainnet + testnet aware)
npx lightnode add judge-web3 # evaluator UI, wallet-signed
npx lightnode add wagmi-setup # wallet wiring: lib/wagmi + providers + connect buttonThe *-web3 scaffolders are one command end to end: run in an empty folder and
they scaffold a Next.js app, write the page with a wired Connect button, bundle
the wagmi config + providers + connect button, wrap your layout with
<Providers>, and npm install the deps. Run inside an existing Next.js app
and they skip the scaffold and just add what's missing. Opt out with
--no-scaffold and --no-install.
All add commands accept --template auto|nextjs-api|hono|node,
--net testnet|mainnet, --force, --no-install, and --no-scaffold.
If
add <name>reports an unknown target, an old global install or npx cache is shadowing the registry. Force the current release withnpx lightnode-sdk@latest add <name>, or update the global:npm install -g lightnode-sdk@latest.
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) | npx lightnode add chat-web3 (or inference-web3 / judge-web3) |
One command, even in an empty folder: scaffolds Next.js, writes the page with a wired Connect button, bundles wagmi + providers, wraps the layout, and installs deps. Each visitor signs createSession + submitJob in their browser and pays the LCAI directly - no backend, no .env. |
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, 229 unit tests across 16 test
files, 13 Playwright end-to-end smoke tests, production build clean, SDK build
clean, both CLIs smoke-tested live against real testnet and mainnet inferences.
Every guide in one place. Start with the one that matches what you are doing.
New here
- GETTING-STARTED.md - a zero-experience walkthrough: make a wallet, get free testnet LCAI, and run your first AI call in about five minutes.
Building on LightChain AI
- sdk/README.md - the full
lightnode-sdkreference: every function, the bundled CLI, and the typed errors. - create-lightnode-app/README.md - the project scaffolder and its three templates.
- lightnode.app/build - the live builder hub: runnable snippets, real network data, and the in-browser playground.
Running a worker
- docs/WORKER_LIFECYCLE.md - the operator's manual: install, earn, settle, clear stuck jobs, deregister, and withdraw, with the on-chain mechanics behind each step.
- docs/UI_AND_DESIGN.md - a screen-by-screen tour of the app and every operation it runs.
How it is built
- docs/ARCHITECTURE.md - one codebase, two shells (web + Tauri desktop), and how worker actions are signed safely.
- SECURITY.md - the non-custodial key model: what leaves your machine and what never does.
- CONTRIBUTING.md - setup, conventions, and the local quality gate.
- DEPLOY.md - deploying the web app to Vercel.
- docs/RELEASING.md - cutting and signing the desktop installers.
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.