{"id":50505645,"url":"https://github.com/marinom2/lightnode","last_synced_at":"2026-06-02T16:00:30.909Z","repository":{"id":360160610,"uuid":"1248573688","full_name":"marinom2/lightnode","owner":"marinom2","description":"Community-built developer + operator suite for the LightChain AI network: encrypted-inference SDK, scaffolders, live playground, and the desktop worker app.","archived":false,"fork":false,"pushed_at":"2026-06-01T09:26:43.000Z","size":14497,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T11:10:33.684Z","etag":null,"topics":["ai","decentralized-ai","encrypted-inference","lightchain","nextjs","sdk","tauri","typescript","web3"],"latest_commit_sha":null,"homepage":"https://lightnode.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marinom2.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-24T20:22:50.000Z","updated_at":"2026-06-01T09:26:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/marinom2/lightnode","commit_stats":null,"previous_names":["marinom2/lightnode"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/marinom2/lightnode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marinom2%2Flightnode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marinom2%2Flightnode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marinom2%2Flightnode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marinom2%2Flightnode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marinom2","download_url":"https://codeload.github.com/marinom2/lightnode/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marinom2%2Flightnode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33829346,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","decentralized-ai","encrypted-inference","lightchain","nextjs","sdk","tauri","typescript","web3"],"created_at":"2026-06-02T16:00:17.655Z","updated_at":"2026-06-02T16:00:30.902Z","avatar_url":"https://github.com/marinom2.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"public/lightnode-mark.png\" alt=\"LightNode\" width=\"88\" /\u003e\n\n# LightNode\n\n**Build with, and run for, LightChain AI.**\n\nA community-built developer and operator suite for the LightChain AI network. It\nhas a published SDK for encrypted inference, scaffolders that drop the SDK into\nany project with one command, a live in-browser playground, and a desktop app\nfor running a worker. One project, two tracks.\n\n[![CI](https://github.com/marinom2/lightnode/actions/workflows/ci.yml/badge.svg)](https://github.com/marinom2/lightnode/actions/workflows/ci.yml)\n[![lightnode-sdk on npm](https://img.shields.io/npm/v/lightnode-sdk?color=7064e9\u0026label=lightnode-sdk)](https://www.npmjs.com/package/lightnode-sdk)\n[![create-lightnode-app on npm](https://img.shields.io/npm/v/create-lightnode-app?color=7064e9\u0026label=create-lightnode-app)](https://www.npmjs.com/package/create-lightnode-app)\n[![License: MIT](https://img.shields.io/badge/license-MIT-7064e9.svg)](LICENSE)\n[![LightChain AI](https://img.shields.io/badge/LightChain%20AI-ecosystem%20tool-dd00ac.svg)](https://lightchain.ai)\n\n\u003c/div\u003e\n\n## Never done this before? Start here\n\nIf you're new to blockchain or Node.js development, read\n[GETTING-STARTED.md](GETTING-STARTED.md) first. It assumes no experience and\ncovers, in about 5 minutes, making a wallet, getting free testnet funds, your first\nAI call, and the difference between the two ways to build (so you don't end up\nwith a confusing mix of files). The rest of this README and the SDK docs assume\nyou're already comfortable with a terminal and TypeScript.\n\n## What you can do with this\n\nTwo completely separate use cases live in this repo. Pick the one that matches\nwhat you actually want.\n\n1. **You are a developer.** You want to add AI to your own app, paying per call,\n   on a decentralized network instead of a single hosted vendor. Install\n   `lightnode-sdk`, paste five lines of code, and your app can run encrypted\n   prompts on the LightChain AI network. The network is decentralized, so it is\n   not one company running it. Your wallet pays for each call directly on chain.\n\n2. **You have a decent computer.** You want to make a bit of LCAI by serving\n   prompts to other people's apps. Install the LightNode desktop app, click\n   through the install wizard, and your machine becomes a worker on the network.\n   The app handles the keys, the staking, the Docker container, and watches the\n   worker so it stays online.\n\nThe two halves share one codebase and one community, but most people only need\none of them.\n\n## Recently shipped\n\n- `lightnode-sdk@0.7.x`. The **worker-operator** surface: run a worker's full\n  on-chain lifecycle from code, the part that previously needed the worker\n  Docker image or reverse-engineering unverified contracts. `WorkerOperator`\n  covers register, stake (`topUpStake` / `withdrawStake` / `reinstate`), settle\n  (`releaseJob` / `releaseAll` / `withdraw`), live protocol config, and the\n  headline **stuck-job recovery** (`claimTimeout` / `clearStuck` /\n  `unstickAndDeregister`) that clears acknowledged-but-unfinished jobs which\n  otherwise block deregistration, plus `decodeWorkerError` for plain-English\n  reverts. New CLI: `lightnode worker status | can-deregister | settle |\n  clearstuck | withdraw | deregister`. The latest 0.7.x sends\n  `deregisterWorker()` directly with a gas-correct limit, so a worker can exit\n  and recover its stake with no toolkit clone, no Docker, and no running\n  container, even after a half-finished install.\n- `lightnode-sdk@0.6.x`. Higher-level abstractions on top of the encrypted\n  inference layer: **`runInferenceBatch`** (parallel inference with capped\n  concurrency, stable result order, per-slot errors), the **`Agent`** class\n  (ReAct-style tool calling with `\u003ctool\u003e` / `\u003canswer\u003e` markers, works on\n  llama3-8b without native function calling), and **`AbortSignal`** support\n  across `runInference` + `runInferenceWithKey` so a UI can cancel pending\n  awaits. CLI gains `lightnode batch \u003cprompts.json\u003e` and `lightnode agent \u003ctask\u003e`.\n- `lightnode-sdk@0.5.x`. Six SDK modules in one ecosystem release: **Bridge\n  SDK** (Hyperlane Warp Route, LCAI between Ethereum and LightChain),\n  **DAO SDK** (LCAIGovernor on Ethereum + LightChainGovernor with NativeVotes\n  precompile on chain 9200), **OnchainModelRegistry reader**, **multi-turn\n  `Conversation`**, **`workerPreflight` + `workerWatch`**, and\n  **`ln.getJobStatus`** (refundable classification).\n- **Interactive CLI runner on `/build`**. Click a command on the left,\n  hit Run, see the real JSON output in the browser. Backed by a server\n  route that runs the LightNode method server-side.\n- **Live mainnet data on `/build`**. Four cards showing network stats +\n  top workers + registered models + per-model performance, refreshed\n  every minute, with the SDK snippet that produced each one.\n- **Standalone examples repo** at\n  [`marinom2/lightnode-examples`](https://github.com/marinom2/lightnode-examples)\n  with eight runnable examples (one per SDK module). Opens in StackBlitz\n  in seconds.\n- Live playground at \u003chttps://lightnode.app/playground\u003e. Connect a wallet,\n  type a prompt, run one real encrypted inference in your browser. Free on\n  testnet.\n\n---\n\n## Pick your path\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### Build with LightChain AI\n\nYou want **encrypted inference in your dApp**.\n\n- One SDK call wraps the full protocol (SIWE auth, ECDH-P256 + AES-GCM\n  crypto, on-chain `createSession` + `submitJob`, decrypted streaming\n  response).\n- Non-custodial. The SDK never holds a key. Your wallet signs.\n- About 0.022 LCAI per call on mainnet, free on testnet.\n- Live-tested on both networks before every release.\n\n```bash\n# Brand-new project:\nnpm create lightnode-app my-app\n\n# Existing project (auto-detects Next.js, Hono, or Node):\nnpx lightnode add inference\n```\n\nTry it first: \u003chttps://lightnode.app/playground\u003e\n\nBuilder hub: \u003chttps://lightnode.app/build\u003e\n\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### Run a LightChain AI worker\n\nYou want to **earn LCAI** by serving inference jobs.\n\n- One-click install on your machine. Wallet, keys, stake, register, live.\n- No terminal, no Docker fight, no manual key handling.\n- A watchdog keeps it online. Deregister and withdraw are one click each.\n- Tested on macOS. Linux and Windows are wired up and welcome bug reports.\n\n```bash\n# Download the desktop app:\n# https://github.com/marinom2/lightnode/releases\n\n# Or use the web version (copy/paste commands):\n# https://lightnode.app/onboard\n```\n\nWeb app: \u003chttps://lightnode.app\u003e\n\nOperator manual: [docs/WORKER_LIFECYCLE.md](docs/WORKER_LIFECYCLE.md)\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## Build track in detail\n\n### Three published packages\n\n| Package | Version | What it does |\n| --- | --- | --- |\n| [`lightnode-sdk`](https://www.npmjs.com/package/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. |\n| [`create-lightnode-app`](https://www.npmjs.com/package/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. |\n| `lightnode add` (inside `lightnode-sdk`) | n/a | Patch an existing project. Auto-detects the framework, writes the right files. Safe to re-run. |\n\n### The `add` catalog\n\nServer-paid (you host a backend; your funded wallet pays per call):\n\n```bash\nnpx lightnode add inference                    # encrypted inference route or script\nnpx lightnode add chat                         # chat UI with conversation history\nnpx lightnode add judge                        # pass/fail evaluator route (criteria + evidence)\nnpx lightnode add agent                        # scheduled inference (Vercel Cron or setInterval)\nnpx lightnode add analytics-dashboard          # read-only network + worker analytics page\nnpx lightnode add nft-mint-with-inference      # AI-generated NFT metadata with on-chain provenance\n```\n\nUser-paid (no backend; each visitor signs + pays from their own wallet):\n\n```bash\nnpx lightnode add inference-web3               # one-shot inference UI, wallet-signed\nnpx lightnode add chat-web3                     # chat UI, wallet-signed (mainnet + testnet aware)\nnpx lightnode add judge-web3                    # evaluator UI, wallet-signed\nnpx lightnode add wagmi-setup                   # wallet wiring: lib/wagmi + providers + connect button\n```\n\nThe `*-web3` scaffolders are one command end to end: run in an empty folder and\nthey scaffold a Next.js app, write the page with a wired Connect button, bundle\nthe wagmi config + providers + connect button, wrap your layout with\n`\u003cProviders\u003e`, and `npm install` the deps. Run inside an existing Next.js app\nand they skip the scaffold and just add what's missing. Opt out with\n`--no-scaffold` and `--no-install`.\n\nAll `add` commands accept `--template auto|nextjs-api|hono|node`,\n`--net testnet|mainnet`, `--force`, `--no-install`, and `--no-scaffold`.\n\n\u003e If `add \u003cname\u003e` reports an unknown target, an old global install or npx cache\n\u003e is shadowing the registry. Force the current release with\n\u003e `npx lightnode-sdk@latest add \u003cname\u003e`, or update the global:\n\u003e `npm install -g lightnode-sdk@latest`.\n\n### What can I actually do with the SDK?\n\nThe SDK exposes everything you need to talk to the LightChain AI network from\nyour own code. It splits into three groups, top to bottom:\n\n**1. Encrypted inference (paid).** The thing most builders want. Run a prompt,\nget an answer back, pay per call in LCAI.\n\n| You want to... | Use |\n| --- | --- |\n| Run one prompt in five lines. No wallet wiring. | `runInferenceWithKey({ network, privateKey, prompt })` |\n| Same flow, but you already have viem clients and a SIWE JWT in your app. | `runInference({ gateway, wallet, publicClient, network, prompt })` |\n| Drive each step yourself (custom retry, custom streaming, multi-turn). | `prepareSession`, `submitPrompt`, `decryptResponse`, plus your own viem calls. |\n\n**2. Read-only chain client (free).** All the data the network exposes, without\npaying for anything. Use this for dashboards, leaderboards, gating logic, or\nto check things before you spend.\n\n```ts\nimport { LightNode } from \"lightnode-sdk\";\nconst ln = new LightNode(\"mainnet\");\n\nawait ln.getWorker(\"0x...\");          // one worker's full record\nawait ln.getWorkers();                // all registered workers\nawait ln.getWorkerJobs(\"0x...\", 20);  // recent jobs for a worker\nawait ln.getModels();                 // network's registered models (fees, limits)\nawait ln.getNetworkStats();           // totals + active count + earnings\nawait ln.getModelStats(1000);         // per-model completion, p50/p95, disputes\nawait ln.getWorkerStats(1000, 25);    // per-worker reliability, busiest first\nawait ln.getNetworkAnalytics(1000);   // network-wide rollup\nawait ln.isRegistered(\"0x...\");       // authoritative on-chain truth (no indexer lag)\nawait ln.estimateFee(\"llama3-8b\");    // what `submitJob` will charge\n```\n\n**3. Helpers.** Things you sometimes need around inference: `consumerGatewayUrl`,\n`estimateJobFee`, the typed errors (`StalledWorkerError`, `OnChainRevertError`,\n`RelayTokenTimeoutError`, `GatewayAuthError`) with the `isStalledWorker` type\nguard, CSV writers (`modelStatsCsv`, `workerStatsCsv`, `workerJobsCsv`), and\n`fromWei` for formatting earnings.\n\n### If you have project X, do Y\n\nConcrete recipes per common starting point. The right side is what to install\nand what file ends up where.\n\n| Your starting point | What to run | What you get |\n| --- | --- | --- |\n| 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`. |\n| Empty terminal, one prompt | `git clone marinom2/lightnode-examples \u0026\u0026 cd quickstart-inference \u0026\u0026 npm start` | A 30-line script. First run prints address + faucet; second run fires the prompt. |\n| An existing Next.js app | `cd your-app \u0026\u0026 npx lightnode add inference` | A new `app/api/inference/route.ts`. POST a JSON body, get the answer back. Wallet stays server-side. |\n| An existing Next.js app + a chatbot UI | `cd your-app \u0026\u0026 npx lightnode add chat` | A streaming chat page with conversation history. Same protocol, plus session reuse. |\n| A scheduled task (daily summary, monitoring agent) | `cd your-app \u0026\u0026 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. |\n| 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. |\n| A user-facing leaderboard or worker dashboard | `cd your-app \u0026\u0026 npx lightnode add analytics-dashboard` | A read-only page that pulls live network + worker stats and renders them. No keys, no wallet. |\n| An NFT mint where each mint generates unique metadata with AI | `cd your-app \u0026\u0026 npx lightnode add nft-mint-with-inference` | A mint flow that runs an inference, anchors the answer to a content hash, and returns metadata. |\n| 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`. |\n\n### Two patterns: server-pays vs user-pays\n\nThe biggest decision when wiring inference into your app: **whose wallet pays\nfor each call?**\n\n- **Server-pays** (the API-route examples). You hold a hot wallet on the\n  server, top it up, the user just hits your API. Familiar pattern: the user\n  does not need a wallet at all. Cheaper UX for the user. You own the cost.\n- **User-pays** (the playground). The user connects their own wallet and signs\n  the two on-chain transactions per call. You hold no keys and bear no cost,\n  but the user needs LCAI in their wallet. This is the closest to \"AI as a\n  primitive\" the network offers.\n\nBoth use the same SDK. The split is just whether you build it on top of\n`runInferenceWithKey` (server-pays) or wire viem's `useWalletClient` to a\nReact component (user-pays).\n\n### Three ways to try\n\n| Path | What | Time | Cost |\n| --- | --- | --- | --- |\n| **[Live playground](https://lightnode.app/playground)** | Browser, connect wallet, run one real inference. | About 30 sec | Free on testnet |\n| **[Open in StackBlitz](https://stackblitz.com/github/marinom2/lightnode-examples/tree/main/quickstart-inference)** | Cloud IDE, starter pre-installed. | About 5 sec | Free testnet |\n| **[Open in Codespaces](https://codespaces.new/marinom2/lightnode-examples)** | Full VS Code dev environment with the examples repo. | About 1 min | GitHub free tier covers it |\n\n### Live-tested\n\nThe SDK is tested end-to-end with real LCAI on both networks before each release.\n\n| Network | createSession tx | submitJob tx |\n| --- | --- | --- |\n| mainnet (9200) | [`0xf091957f...57d4a6ca`](https://mainnet.lightscan.app/tx/0xf091957f515eb472e71f6d442ee24c9c74e948412e2b7ad658dfbb4b57d4a6ca) | [`0x6ff44a4a...79846bb89`](https://mainnet.lightscan.app/tx/0x6ff44a4aa4b08cd38715369705a4338af3bb6ee456f2b8819d62fc779846bb89) |\n| testnet (8200) | [`0x77686f3f...ef2bc587`](https://testnet.lightscan.app/tx/0x77686f3fc37573f0745f256a5c74f5944d3a2a7de745129bd918e8b0ef2bc587) | [`0xba9d48c4...293b2bd96`](https://testnet.lightscan.app/tx/0xba9d48c4f8eacf24d363ceb884f6c6c2fcca54a82fa0a341625944d293b2bd96) |\n\nDecrypted output, full receipts, and the source that ran them all live on\n[`lightnode.app/build`](https://lightnode.app/build).\n\n### Example projects\n\nRunnable examples live in their own small repo so cloud IDEs clone them in\nseconds: [`marinom2/lightnode-examples`](https://github.com/marinom2/lightnode-examples).\nThe repo has quickstart-inference (about 30 lines, auto-bootstraps a testnet\nkey on first run), nextjs-api-route, and hono-server.\n\nWhat is in this repo:\n\n| Path | What |\n| --- | --- |\n| [`sdk/`](sdk) | The `lightnode-sdk` source. |\n| [`create-lightnode-app/`](create-lightnode-app) | The scaffolder source. |\n| [`app/playground/page.tsx`](app/playground/page.tsx) | The full in-browser playground. Same SDK, with Reown/wagmi wallet connect. |\n\n---\n\n## Worker track in detail\n\nA consumer desktop and web app for **running** a LightChain AI worker. Same\nproject as the build track, completely separate user flow.\n\n### What it does\n\n- **Real machine readiness.** Native CPU, RAM, GPU, VRAM detection, a capacity\n  score, and a Speed test that runs a real inference against the live on-chain\n  deadline.\n- **One-click, wallet-funded install.** Generates and secures the worker key.\n  Funds and stakes from your connected wallet. Registers on chain. Brings the\n  worker online. Shows live progress and plain-English error messages.\n- **Stays online for you.** A watchdog auto-starts Docker and the worker, keeps\n  the model warm, optional downtime alerts via Discord webhook.\n- **Multi-model serving** with a memory-fit gate, and live add-a-model from\n  the dashboard.\n- **Full lifecycle, no terminal.** Live earnings (settled vs pending-release),\n  settle/claim, clear stuck jobs, deregister, gas-aware withdraw, free-up-memory,\n  replaced-key recovery, removed-worker uninstall.\n- **Honest dashboard.** On-chain registration reader (works even when the\n  public indexer lags a deregister + re-register cycle), one honest status pill,\n  per-job processing time vs deadline, CSV export of any worker's job history.\n- **Network analytics** at `/network`. Honest completion (jobs the indexer\n  leaves stuck count as failures), p50/p95 latency, per-worker reliability,\n  CSV-exportable.\n\n### Getting started\n\n| Step | Where |\n| --- | --- |\n| 1. Download the desktop app | [Releases](https://github.com/marinom2/lightnode/releases/latest) |\n| 2. Or use the web app and copy/run commands | \u003chttps://lightnode.app/onboard\u003e |\n| 3. Full operator manual | [docs/WORKER_LIFECYCLE.md](docs/WORKER_LIFECYCLE.md) |\n\n### Platform support (honest status)\n\n| OS | Status |\n| --- | --- |\n| macOS (Apple Silicon) | Tested end-to-end on testnet and mainnet. |\n| Linux | Installers build in CI and commands are syntax-checked. Full flow not yet hardware-verified. Community testing welcome. |\n| Windows | Installers build in CI and PowerShell is parse-checked. Full flow not yet hardware-verified. Community testing welcome. |\n\n---\n\n## Networks\n\nLightChain AI runs two networks. Same protocol, different chain IDs and contract\naddresses.\n\n| | Testnet | Mainnet |\n| --- | --- | --- |\n| Chain ID | 8200 | 9200 |\n| RPC | `https://rpc.testnet.lightchain.ai` | `https://rpc.mainnet.lightchain.ai` |\n| Explorer | \u003chttps://testnet.lightscan.app\u003e | \u003chttps://mainnet.lightscan.app\u003e |\n| Faucet | \u003chttps://lightfaucet.ai\u003e | n/a, bridge or buy LCAI |\n| Worker min stake | 5,000 LCAI | 50,000 LCAI |\n| Inference cost | free (testnet LCAI) | about 0.022 LCAI per call |\n\n---\n\n## Architecture (one line per layer)\n\n- **Frontend.** Next.js 15 (App Router), React 19, Tailwind v4. Wallet via Reown\n  AppKit (wagmi + viem). Live network data through server-side `/api/*` proxy\n  routes (no client CORS, same-origin from the browser's perspective).\n- **Desktop.** Tauri v2 shell that loads the hosted web UI and exposes a few\n  native commands over IPC. A `vercel --prod` deploy reaches the desktop app on\n  its next page load. No new installer needed for most changes.\n- **SDK.** Pure TypeScript, ESM, ships to npm. Single peer dep: `viem`. Works in\n  both browser and Node (Web Crypto via `globalThis`). Source of truth for the\n  SDK ABI, the gateway client, the relay frame format, and the analytics\n  aggregators.\n- **Worker integration.** The on-disk keystore and worker container are the\n  source of truth for signing. Any on-chain worker action derives the signing\n  key from the keystore the worker actually runs with and verifies the derived\n  address against the target worker. Refuses to sign one network's action with\n  another network's key.\n\nLonger write-up in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).\n\n---\n\n## Security and key handling\n\nLightNode is **non-custodial**, on both tracks.\n\n- The **SDK** never holds your private key. Your wallet signs every on-chain\n  call via viem. The SDK only prepares the data and talks to the consumer\n  gateway.\n- The **worker app** generates the worker key locally, stores it in the OS\n  keychain (with a localStorage fallback on unsigned builds), and writes the\n  toolkit's keystore on disk. All worker payout transactions are signed locally\n  on your machine.\n- The funding wallet only reads its address and sends LCAI. It never signs\n  worker operations.\n\nReporting a vulnerability: [SECURITY.md](SECURITY.md).\n\n---\n\n## Repo layout (top-level)\n\n```\n.\n├── app/                 # Next.js routes (lightnode.app)\n│   ├── build/           # Builder hub\n│   ├── playground/      # Live in-browser inference\n│   ├── network/         # Public analytics\n│   ├── onboard/         # Worker onboarding wizard\n│   ├── dashboard/       # Worker dashboard\n│   └── api/             # /api/* proxy + subgraph routes\n├── components/          # React UI (worker view, operations, install progress, ...)\n├── lib/                 # scriptgen, install-progress diagnoser, subgraph client, hardware scoring, ...\n├── sdk/                 # lightnode-sdk source (published to npm)\n├── create-lightnode-app/# create-lightnode-app source (published to npm)\n├── desktop/             # Tauri v2 shell (src-tauri)\n├── tests/unit + tests/e2e/  # Vitest + Playwright\n└── docs/                # Worker lifecycle, architecture, UI/design, releasing\n```\n\n---\n\n## Quality gate\n\n```bash\nnpm run lint \u0026\u0026 npm run typecheck \u0026\u0026 npm test \u0026\u0026 npm run build\nnpm run test:e2e\ncd sdk \u0026\u0026 npm run typecheck \u0026\u0026 npm run build\n```\n\nState on `main`: lint clean, typecheck clean, 229 unit tests across 16 test\nfiles, 13 Playwright end-to-end smoke tests, production build clean, SDK build\nclean, both CLIs smoke-tested live against real testnet and mainnet inferences.\n\n---\n\n## Documentation\n\nEvery guide in one place. Start with the one that matches what you are doing.\n\n**New here**\n- [GETTING-STARTED.md](GETTING-STARTED.md) - a zero-experience walkthrough:\n  make a wallet, get free testnet LCAI, and run your first AI call in about five\n  minutes.\n\n**Building on LightChain AI**\n- [sdk/README.md](sdk/README.md) - the full `lightnode-sdk` reference: every\n  function, the bundled CLI, and the typed errors.\n- [create-lightnode-app/README.md](create-lightnode-app/README.md) - the project\n  scaffolder and its three templates.\n- [lightnode.app/build](https://lightnode.app/build) - the live builder hub:\n  runnable snippets, real network data, and the in-browser playground.\n\n**Running a worker**\n- [docs/WORKER_LIFECYCLE.md](docs/WORKER_LIFECYCLE.md) - the operator's manual:\n  install, earn, settle, clear stuck jobs, deregister, and withdraw, with the\n  on-chain mechanics behind each step.\n- [docs/UI_AND_DESIGN.md](docs/UI_AND_DESIGN.md) - a screen-by-screen tour of the\n  app and every operation it runs.\n\n**How it is built**\n- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - one codebase, two shells (web +\n  Tauri desktop), and how worker actions are signed safely.\n- [SECURITY.md](SECURITY.md) - the non-custodial key model: what leaves your\n  machine and what never does.\n- [CONTRIBUTING.md](CONTRIBUTING.md) - setup, conventions, and the local quality\n  gate.\n- [DEPLOY.md](DEPLOY.md) - deploying the web app to Vercel.\n- [docs/RELEASING.md](docs/RELEASING.md) - cutting and signing the desktop\n  installers.\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). TypeScript with no `any`. Pure logic in\n`lib/` with a matching test. Design tokens over hardcoded colors. Conventional\ncommits.\n\n---\n\n## License\n\nMIT. See [LICENSE](LICENSE). Copyright (c) 2026 **KykyRykyPaloma**.\n\n*LightNode is an independent, community-built tool for the LightChain AI\necosystem. Not affiliated with or endorsed by the LightChain AI team.\nReview the official [`lightchain-worker-toolkit`](https://github.com/lightchain-protocol/lightchain-worker-toolkit)\nfor the worker runtime's own security and operational model.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarinom2%2Flightnode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarinom2%2Flightnode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarinom2%2Flightnode/lists"}