From 2ae449e8ccc51982d0e81c550b7a403eb95affb8 Mon Sep 17 00:00:00 2001 From: Martin Marinov Date: Sun, 31 May 2026 17:00:40 +0300 Subject: [PATCH] docs: add beginner onboarding and fix newcomer CLI footguns Make the SDK approachable for developers new to blockchain/Node.js, additively (no existing reference content removed). - add GETTING-STARTED.md: zero-assumptions guide (wallet, faucet, first call, testnet vs mainnet, the create-lightnode-app vs `lightnode add` distinction, troubleshooting table) - README/sdk/create-lightnode-app: link to the guide as an on-ramp - create-lightnode-app: make `cd ` prominent and explain the `Missing script: "dev"` error new users hit when running in the wrong dir - lightnode add: clarify files land in the CURRENT folder, not a new one - fix: install tsx for the node/script template and use `npx tsx` in printed run steps so `tsx .ts` no longer fails with command-not-found --- GETTING-STARTED.md | 192 ++++++++++++++++++++++++++++++ README.md | 9 ++ create-lightnode-app/README.md | 13 ++ create-lightnode-app/src/index.ts | 19 ++- sdk/README.md | 6 + sdk/src/add.ts | 4 +- sdk/src/cli.ts | 16 ++- 7 files changed, 246 insertions(+), 13 deletions(-) create mode 100644 GETTING-STARTED.md diff --git a/GETTING-STARTED.md b/GETTING-STARTED.md new file mode 100644 index 0000000..67dd2a9 --- /dev/null +++ b/GETTING-STARTED.md @@ -0,0 +1,192 @@ +# Getting Started (for first-timers) + +Never built a blockchain or Node.js app before? Start here. This guide assumes +no prior experience and explains every term the first time it appears. Once +you've done this once, the [SDK README](sdk/README.md) and +[main README](README.md) will make sense. + +## What this is, in plain words + +LightChain AI is a network where you send a text prompt to an AI model and get +an answer back, like calling any hosted AI API, except: + +- It runs on a blockchain (a shared, decentralized ledger), so no single company + owns it. +- Your prompt is encrypted end-to-end, so the network sees only scrambled bytes, + never your text. +- You pay per request from your own wallet instead of a monthly bill. + +This repo (`lightnode`) is a community toolkit that makes that easy: +`lightnode-sdk` (a code library plus a `lightnode` command) and +`create-lightnode-app` (a project generator). + +## The words you need to know + +| Word | What it means here | +|---|---| +| Wallet | A secret number (your "private key") that signs and pays for requests. Its public "address" is where you receive funds. | +| Private key | The secret half of the wallet. Looks like `0x` followed by 64 characters. Anyone who has it controls the wallet, so never share it. | +| Gas | The small fee every blockchain action costs. On LightChain it's paid in LCAI. | +| LCAI | LightChain's coin. Free on testnet, real money on mainnet. | +| Testnet | A free practice copy of the network. Use this while learning. | +| Mainnet | The real network. Costs real LCAI. Don't use it until you're confident. | + +While learning, always use testnet. It's free. + +## One-time setup (about 5 minutes) + +### 1. Install Node.js + +You need Node.js 18 or newer. Check what you have: + +```bash +node --version +``` + +If that errors or shows a version below 18, install the latest LTS from +. `npm` (the package manager) comes bundled with it. + +### 2. Make a wallet + +```bash +npx lightnode wallet new +``` + +This prints two things: + +``` +PRIVATE_KEY=0x... (64 hex characters) your secret +# address: 0x... your public address +``` + +Copy both somewhere safe. This key is for testnet practice only. Never put real +money on a key you generated and pasted into a terminal. + +### 3. Get free testnet funds + +Go to , paste your address (the `0x...` from the +`# address:` line, not the private key), and request LCAI. You get about 2 LCAI +per day, which is plenty for many test calls. + +### 4. Check it arrived + +```bash +PRIVATE_KEY=0x...your-key... npx lightnode wallet balance --net testnet +``` + +You should see a balance above 0 LCAI. Setup is done. + +## Your first AI call (no project needed) + +The fastest possible test is one command, straight from the terminal: + +```bash +PRIVATE_KEY=0x...your-key... npx lightnode chat "Write a one-line fun fact about the ocean." --net testnet +``` + +It signs a request, runs it on testnet, and streams the answer back. If you see +text appear, everything works. + +What just happened: the CLI created an on-chain session, submitted your prompt as +a transaction, and decrypted the worker's reply locally. The fees came out of +your free testnet LCAI. + +## Two ways to build (don't mix them up) + +This is the most common source of confusion for new users, so read it carefully. +There are two separate tools, for two different situations. Pick one. + +### Tool A: `create-lightnode-app` (start a brand-new project) + +Use this when you have no project yet and want a complete one generated for you +in a new folder. + +```bash +npm create lightnode-app my-app +# answer the prompts: choose a template, choose testnet +``` + +This creates a new folder called `my-app/` with everything inside it. You must +go into it before running anything: + +```bash +cd my-app # the step that's easy to forget +cp .env.example .env # then paste your PRIVATE_KEY into .env, keep NETWORK=testnet +npm install +npm run dev # (nextjs template) then open http://localhost:3000 +# or: npm start "your prompt" (node template) +``` + +If you see `npm error Missing script: "dev"`, you ran it in the wrong folder. The +commands only work inside `my-app/`. Run `cd my-app` first. + +### Tool B: `lightnode add` (bolt onto a project you already have) + +Use this when you already have a folder or project and want to drop AI files into +it. These commands write files into your current folder. They do not create a new +one. + +```bash +npx lightnode add inference # a basic prompt-to-answer file +npx lightnode add nft-mint-with-inference # generate NFT metadata with AI +``` + +After it runs, follow its printed steps (install, set up `.env`, then run with +`npx tsx .ts`). + +| | Tool A: `create-lightnode-app` | Tool B: `lightnode add` | +|---|---|---| +| When | Starting fresh | Adding to an existing folder | +| Creates a new folder? | Yes (`my-app/`) | No (writes into current folder) | +| You must `cd` after? | Yes | No | +| Run with | `npm run dev` / `npm start` | `npx tsx .ts` | + +Running both in the same folder (as the README's NFT example shows) is what +creates a confusing mix of loose files and a sub-project. For learning, use just +one. + +## The `.env` file (where your secret lives) + +Both tools expect a file named `.env` holding your key. It is git-ignored so it +never gets committed. A typical `.env`: + +``` +PRIVATE_KEY=0x...your-testnet-key... +NETWORK=testnet +MODEL=llama3-8b +``` + +You create it by copying the template the tool generated: + +```bash +cp .env.example .env +``` + +Then open `.env` in your editor and paste your real key over the placeholder. +The placeholder `0x000...000` in `.env.example` is fake and will not work. You +must replace it with your real funded key. + +## When something breaks + +| Message you see | What it means | Fix | +|---|---|---| +| `npm error Missing script: "dev"` | You're in the wrong folder | `cd` into the project folder first | +| `command not found: tsx` | The script runner isn't available | Use `npx tsx .ts` (the `npx` matters) | +| `set PRIVATE_KEY in .env` / `set PRIVATE_KEY=0x...` | No real key configured | Put your key in `.env` (or pass `--key 0x...`) | +| `under 0.05 LCAI - too low` | Wallet has no funds | Fund your address at | +| `workers stalled` / `worker stalled` | A network worker didn't answer | Run it again (fees are refunded) | +| `auth ... failed` / `502` | Couldn't reach the network | Check your internet and retry | + +## Where to go next + +- [sdk/README.md](sdk/README.md): every SDK function and CLI command (the full + reference). Has a 5-line "hello world". +- [create-lightnode-app/README.md](create-lightnode-app/README.md): all the + project templates. +- Playground (no install, runs in your browser): +- Builder docs: +- Runnable examples (open in your browser via StackBlitz): + + +Start with the first AI call above, then try Tool A to scaffold your first real +project. diff --git a/README.md b/README.md index 0e5494b..badb668 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,15 @@ for running a worker. One project, two tracks. +## Never done this before? Start here + +If you're new to blockchain or Node.js development, read +[GETTING-STARTED.md](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. + ## What you can do with this Two completely separate use cases live in this repo. Pick the one that matches diff --git a/create-lightnode-app/README.md b/create-lightnode-app/README.md index df24187..b5ad0a9 100644 --- a/create-lightnode-app/README.md +++ b/create-lightnode-app/README.md @@ -9,6 +9,19 @@ npm create lightnode-app my-app Pick a template, set a private key, you're inference-enabled in ~2 minutes. +First time? Read the [Getting Started guide](../GETTING-STARTED.md). It walks you +through making a wallet, getting free testnet funds, and your first AI call with +no prior experience. + +Note: this command creates a new folder (`my-app/`). You must `cd my-app` before +running `npm install` or `npm run dev`. Running them in the parent folder fails +with `npm error Missing script: "dev"`. + +Want to add inference to a folder you already have instead of making a new +project? Use `npx lightnode add inference` (see +[the SDK](https://www.npmjs.com/package/lightnode-sdk)). That writes files into +your current folder and does not create a subfolder. + ## Templates | Template | What you get | Run | diff --git a/create-lightnode-app/src/index.ts b/create-lightnode-app/src/index.ts index 7a847c2..8e52297 100644 --- a/create-lightnode-app/src/index.ts +++ b/create-lightnode-app/src/index.ts @@ -105,17 +105,24 @@ async function main() { console.log(`\n✅ scaffolded ${projectName} (${template}, ${network}) at ${dest}`); console.log("\nNext steps:"); - console.log(` cd ${projectName}`); - console.log(` cp .env.example .env # put a funded ${network} private key in PRIVATE_KEY`); + console.log(` cd ${projectName} # do this first. Every command below only works inside this folder.`); + console.log(` cp .env.example .env # then paste a funded ${network} private key into PRIVATE_KEY`); console.log(` npm install`); if (template === "nextjs-api") { - console.log(` npm run dev # open http://localhost:3000\n`); + console.log(` npm run dev # open http://localhost:3000`); } else if (template === "hono") { - console.log(` npm start # server on http://localhost:3000/inference\n`); + console.log(` npm start # server on http://localhost:3000/inference`); } else { - console.log(` npm start "your prompt"\n`); + console.log(` npm start "your prompt"`); + } + console.log(""); + console.log(`(If you see npm error Missing script: "dev" you ran it in the wrong folder. Run cd ${projectName} first.)`); + if (network === "testnet") { + console.log(`No wallet yet? Make one: npx lightnode wallet new then fund it free at https://lightfaucet.ai`); + } else { + console.log(`Heads up: mainnet spends real LCAI per call. To try it free, re-scaffold with --network testnet.`); + console.log(`Free testnet LCAI at https://lightfaucet.ai.`); } - console.log(`Free testnet LCAI at https://lightfaucet.ai.`); console.log(`Live in-browser playground at https://lightnode.app/playground.`); } diff --git a/sdk/README.md b/sdk/README.md index 30f65e0..0685c30 100644 --- a/sdk/README.md +++ b/sdk/README.md @@ -16,6 +16,12 @@ npm install lightnode-sdk viem LightChain's own docs list official SDKs as "soon"; this fills the gap. Not affiliated with LightChain. +New to blockchain or Node.js? Read the +[Getting Started guide](../GETTING-STARTED.md) first. It covers wallets, testnet +vs mainnet, the `.env` file, and your first AI call in about 5 minutes. Then come +back here for the full reference. The rest of this README assumes you're +comfortable with TypeScript and a terminal. + ## Five-line "hello world" ```ts diff --git a/sdk/src/add.ts b/sdk/src/add.ts index 9c7f3e0..4532802 100644 --- a/sdk/src/add.ts +++ b/sdk/src/add.ts @@ -359,7 +359,9 @@ function writeFile(abs: string, contents: string, force: boolean): WrittenFile { function depsNeeded(template: Template): string[] { if (template === "nextjs-api") return ["lightnode-sdk", "viem", "ws"]; if (template === "hono") return ["lightnode-sdk", "viem", "ws"]; - return ["lightnode-sdk", "viem", "ws"]; + // The node/script template is run with `npx tsx .ts`, so tsx must be + // installed too, otherwise `tsx ...` fails with "command not found". + return ["lightnode-sdk", "viem", "ws", "tsx"]; } /** diff --git a/sdk/src/cli.ts b/sdk/src/cli.ts index 7352040..f94d04d 100644 --- a/sdk/src/cli.ts +++ b/sdk/src/cli.ts @@ -353,7 +353,7 @@ async function main() { if (!anyWritten) { console.log("\nNothing to do - all target files already exist. Pass --force to overwrite."); } else { - console.log(`\nNext steps:`); + console.log(`\nNext steps (these files were added to your CURRENT folder, not a new project):`); console.log(` 1. ${result.install}`); if (sub === "nft-mint-with-inference" || sub === "inference" || sub === "chat" || sub === "agent") { console.log(` 2. cp .env.example .env (and put a funded ${result.network} PRIVATE_KEY in it)`); @@ -361,12 +361,12 @@ async function main() { console.log(` 3. Set CRON_SECRET in your Vercel env vars + edit AGENT_TASK in .env`); console.log(` 4. Deploy. Vercel Cron fires /api/agent on the schedule in vercel.json`); } else if (sub === "agent") { - console.log(` 3. AGENT_INTERVAL_MS=3600000 tsx agent.ts # or run under pm2/systemd`); + console.log(` 3. AGENT_INTERVAL_MS=3600000 npx tsx agent.ts # or run under pm2/systemd`); } else if (sub === "chat" && result.template === "nextjs-api") { console.log(` 3. Make sure /api/inference is mounted too (run: npx lightnode add inference)`); console.log(` 4. npm run dev, open /chat`); } else if (sub === "chat") { - console.log(` 3. tsx chat-repl.ts (interactive terminal chat)`); + console.log(` 3. npx tsx chat-repl.ts (interactive terminal chat)`); } else if (sub === "nft-mint-with-inference" && result.template === "nextjs-api") { console.log(` 3. Make sure /api/inference is mounted too (run: npx lightnode add inference)`); console.log(` 4. npm run dev, open /nft-mint`); @@ -375,20 +375,24 @@ async function main() { } else if (result.template === "hono") { console.log(` 3. wire inferenceHandler into your Hono app, then start it`); } else if (sub === "nft-mint-with-inference") { - console.log(` 3. tsx nft-metadata.ts "My NFT" "concept goes here"`); + console.log(` 3. npx tsx nft-metadata.ts "My NFT" "concept goes here"`); } else { - console.log(` 3. tsx lightchain-inference.ts "your prompt"`); + console.log(` 3. npx tsx lightchain-inference.ts "your prompt"`); } } else { // analytics-dashboard - read-only, no private key needed. if (result.template === "nextjs-api") { console.log(` 2. npm run dev, open /lightnode-analytics`); } else { - console.log(` 2. tsx lightnode-analytics.ts`); + console.log(` 2. npx tsx lightnode-analytics.ts`); } } + if (result.network === "testnet") { + console.log(`\nNo wallet yet? Make one: npx lightnode wallet new then fund it free below.`); + } console.log(`\nFree testnet LCAI: https://lightfaucet.ai`); console.log(`Builder docs: https://lightnode.app/build`); + console.log(`New to all this? See GETTING-STARTED.md in the lightnode repo.`); } break; }