Build Your First dApp
on Lightchain AI
No coding background? No problem. OrcaAppBuilder walks you through everything — from brainstorming your idea all the way to getting it live and listed on the Lightchain dApp Hub.
Learn to Build on Lightchain
9 lessons that take you from "I've never built anything" to a live app on the Lightchain dApp Hub. Written in plain English — no jargon without an explanation.
Think of a blockchain as a public notebook that thousands of computers around the world all keep a copy of. When you write something in it — like "User A paid User B" — every computer updates its copy. Nobody controls it, nobody can change what's already written, and anyone can read it.
That shared notebook is what makes apps on a blockchain special: payments, ownership records, and agreements happen automatically without a bank, company, or middleman.
Lightchain AI is a blockchain that also has a built-in AI network called AIVM (AI Virtual Machine). This means your app can:
- Accept and send payments in LCAI (Lightchain's currency) — like having a built-in cash register
- Ask AI questions and get real AI responses — without needing an OpenAI account or API key
- Store data or ownership records permanently on the blockchain
Every AI request your app makes gets processed by a network of computers called worker nodes. Those computers earn LCAI for doing the work.
- LCAI — the currency of Lightchain, like "crypto dollars" for this network
- Wallet — your account on the blockchain. An address like 0xABCD...1234. Trust Wallet is what most people use.
- Smart Contract — a mini-program that lives on the blockchain and runs automatically (like a vending machine — you put money in, you get what you paid for)
- AIVM — stands for AI Virtual Machine. Lightchain's built-in AI layer. Your app sends questions to it and gets answers back — like a brain your app can rent by the question.
- dApp — short for "decentralized app." An app that uses a blockchain instead of a traditional server.
- GitHub — a free website where developers store and share code. You'll use it to host your app for free.
- Railway — a service that runs your app's "back end" (the part users don't see) in the cloud, 24/7.
What it is: A website where you store your code and host your app for free. Think of it like Google Docs, but for code.
Why you need it: Your app will live on GitHub Pages — GitHub's free website hosting. When you push an update to GitHub, your app goes live in about 1 minute automatically.
Sign up at: github.com — free account is all you need.
What it is: A service that runs your app's server (the invisible part that processes AI requests) in the cloud, 24/7.
Why you need it: If your app uses AI (AIVM), it needs a server running in the background. Railway is the simplest way to do this — just connect your GitHub repo and Railway handles the rest.
Sign up at: railway.app — start with the free trial.
What it is: A service that manages your domain name (yourapp.ai) and protects your site.
Why you need it: When you're ready to register a real domain, Cloudflare Registrar has some of the cheapest prices. You'll also use Cloudflare's free DNS service to point your domain to your app.
Sign up at: cloudflare.com — free account is all you need to start.
Everything above is browser-based. But to push your code to GitHub, you'll want two desktop tools. Pick the versions that match your computer:
1. GitHub Desktop — the easiest way to put your app files onto GitHub. Drag, click, done. No terminal needed.
👉 Download: desktop.github.com — free, just click the Windows installer and run it.
2. VS Code — free code editor for editing your HTML files. Much better than Notepad.
👉 Download: code.visualstudio.com — click "Download for Windows", run the installer, accept defaults.
3. Python — needed only if you're running an AI (AIVM) server locally. Skip this for now if you're just building a frontend.
👉 Download: python.org/downloads/windows — download the latest version, and check the box "Add Python to PATH" during install.
4. Chrome Extensions (optional but helpful):
👉 MetaMask Chrome Extension — for testing wallet features in your browser during development.
👉 JSON Formatter — makes API responses readable when debugging.
1. GitHub Desktop — easiest way to upload your files to GitHub.
👉 Download: desktop.github.com — free, download the Mac version and drag to Applications.
2. VS Code — free code editor.
👉 Download: code.visualstudio.com — click "Download for Mac", open the zip, drag to Applications.
3. Python — Mac may have Python 3 already. Check by opening Terminal and typing python3 --version. If it shows a version number, you're good. If not:
👉 Download: python.org/downloads/mac-osx
4. Chrome Extensions (optional):
👉 JSON Formatter — useful for debugging API responses.
1. Git — usually pre-installed. Check with git --version. If not:
sudo apt update && sudo apt install git -y
2. VS Code — code.visualstudio.com/download — download the .deb package and install with sudo dpkg -i code_*.deb
3. Python 3 — likely installed. Verify with python3 --version. If not: sudo apt install python3 python3-pip -y
To test your app and pay for AIVM calls during development, you'll need a wallet with some LCAI in it. Here's what you need:
- Trust Wallet — download free from the App Store or Google Play
- Some LCAI — buy on Uniswap (uniswap.org) or get from the Lightchain Discord community
- Lightchain network added to Trust Wallet: Chain ID 9200, RPC: https://rpc.mainnet.lightchain.ai, Symbol: LCAI
Honest answer: not always. Here's a quick guide:
- Collecting LCAI payments from users → Yes, you need a contract
- Minting NFTs (digital collectibles) → Yes, you need a contract
- Just using AI chat in your app → No contract needed (server pays for AI)
- Free informational app → No contract needed
If you're not sure, build the app first without a contract and add one later when users want to pay for things.
The simplest useful contract is a "payment gate" — users send LCAI to get access to your app. Here's the exact pattern used by the Orca Pod apps:
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
contract PaymentGate {
address public owner;
uint256 public price; // price in LCAI (wei)
uint256 public duration = 30 days;
mapping(address => uint256) public accessExpiry;
constructor(uint256 _price) {
owner = msg.sender;
price = _price;
}
// Users call this to pay for access
function purchaseAccess() external payable {
require(msg.value >= price, "Not enough LCAI");
uint256 start = block.timestamp > accessExpiry[msg.sender]
? block.timestamp : accessExpiry[msg.sender];
accessExpiry[msg.sender] = start + duration;
}
// Your app calls this to check if a user has paid
function hasAccess(address user) public view returns (bool) {
return accessExpiry[user] > block.timestamp;
}
// You call this to withdraw the collected LCAI
function withdraw() external {
require(msg.sender == owner);
payable(owner).transfer(address(this).balance);
}
function setPrice(uint256 _price) external {
require(msg.sender == owner);
price = _price;
}
}Option A (Recommended for beginners): Remix IDE — runs entirely in your browser, nothing to install, works on Windows, Mac, and Linux equally.
Option B (Advanced): Foundry command-line tool — faster once set up, but requires a terminal and OS-specific installation.
- Open Remix: Go to remix.ethereum.org in Chrome (no account needed)
- Create the file: In the left panel, click the "+" icon → name it PaymentGate.sol → paste the contract code from above
- Compile it: Click the "Solidity Compiler" icon (looks like an S with arrows) on the left → click Compile PaymentGate.sol → you should see a green checkmark
- Connect your wallet: Click the "Deploy & Run" icon (looks like an Ethereum logo) → under "Environment" choose Injected Provider - MetaMask (or WalletConnect)
- Add Lightchain network to your wallet: Chain ID: 9200, RPC: https://rpc.mainnet.lightchain.ai, Symbol: LCAI
- Set the price: In the Deploy section, enter the price in the constructor field. 1 LCAI = 1000000000000000000 (that's 1 followed by 18 zeros). For 5 LCAI enter 5000000000000000000
- Deploy: Click the orange Deploy button → confirm in your wallet → wait ~10 seconds → your contract address appears at the bottom of the page. Copy it and save it — you'll need it in your app's HTML.
Foundry is faster for repeat deployments and is what the Orca Pod apps use. Installation differs by operating system:
wsl --install
curl -L https://foundry.paradigm.xyz | bash source ~/.bashrc foundryup
forge create PaymentGate.sol:PaymentGate \ --constructor-args 5000000000000000000 \ --private-key YOUR_WALLET_PRIVATE_KEY \ --rpc-url https://rpc.mainnet.lightchain.ai \ --chain-id 9200
curl -L https://foundry.paradigm.xyz | bash source ~/.zshrc foundryup
forge create PaymentGate.sol:PaymentGate \ --constructor-args 5000000000000000000 \ --private-key YOUR_WALLET_PRIVATE_KEY \ --rpc-url https://rpc.mainnet.lightchain.ai \ --chain-id 9200
curl -L https://foundry.paradigm.xyz | bash source ~/.bashrc foundryup
forge create PaymentGate.sol:PaymentGate \ --constructor-args 5000000000000000000 \ --private-key YOUR_WALLET_PRIVATE_KEY \ --rpc-url https://rpc.mainnet.lightchain.ai \ --chain-id 9200
Your app's server (running on Railway) handles the entire AIVM flow behind the scenes. From the user's perspective, they type a question and an answer appears. Simple.
Your Python server on Railway does all 9 steps automatically and just sends the final text response back to your frontend.
Create a file called requirements.txt in your server folder and paste this in exactly. Railway reads this file to install the right packages automatically.
eth-account==0.13.7 web3==7.6.0 cryptography websocket-client requests
If you want to test your server on your Windows PC before pushing to Railway, open Command Prompt (search "cmd" in Start menu) and run:
pip install eth-account==0.13.7 web3==7.6.0 cryptography websocket-client requests
If you see "pip is not recognized", try py -m pip install ... instead. And make sure you checked "Add Python to PATH" when you installed Python (see Step 2).
To run your server locally: py server.py (Windows uses py, not python3)
Open Terminal (search in Spotlight) and run:
pip3 install eth-account==0.13.7 web3==7.6.0 cryptography websocket-client requests
To run your server locally: python3 server.py
pip3 install eth-account==0.13.7 web3==7.6.0 cryptography websocket-client requests
To run: python3 server.py
Once your server is running, your frontend (HTML page) makes one simple call:
async function askAI(userMessage) {
const response = await fetch('https://your-railway-url.up.railway.app/api/chat', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ message: userMessage })
});
const data = await response.json();
return data.reply; // plain text response from the AI
}- Each AI call costs approximately 0.02 LCAI from your dApp wallet
- Your dApp wallet is separate from your personal wallet — fund it with ~100 LCAI to start
- The LIGHTCHAIN_PRIVATE_KEY environment variable on Railway is this dApp wallet's private key
- Never use your personal Trust Wallet key as the dApp wallet key
Most Lightchain dApps are built as a single index.html file. Everything — the design, the buttons, the wallet connection logic — lives in one file. The benefits:
- ✅ No "npm install", no build tools, no complicated setup
- ✅ Works on any computer — just open the file in a browser
- ✅ Hosted for free on GitHub Pages
- ✅ Updates go live in about 60 seconds after you save and push
- ✅ Easy to share — just one file
Every Orca Pod app follows this same skeleton:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Your App Name</title>
<!-- Load ethers.js (wallet connection library) -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/ethers/6.7.0/ethers.umd.min.js"></script>
<style>
/* Your CSS goes here */
body { font-family: sans-serif; background: #0a0f1e; color: #e8eaf0; }
</style>
</head>
<body>
<h1>My Lightchain App</h1>
<button onclick="connectWallet()">Connect Wallet</button>
<div id="address"></div>
<script>
async function connectWallet() {
// This is the only code you need to connect Trust Wallet
const provider = new ethers.BrowserProvider(window.ethereum);
await provider.send('eth_requestAccounts', []);
const signer = await provider.getSigner();
const address = await signer.getAddress();
document.getElementById('address').textContent = 'Connected: ' + address;
}
</script>
</body>
</html>You don't need to be a designer. The Orca Pod apps all use the same simple approach:
- Dark navy background (#080c18) — matches the Lightchain vibe
- Cyan accent color (#00d4ff) for buttons and highlights
- CSS variables so you only define colors once and change everything at once
- CSS Grid or Flexbox for layout — no extra libraries needed
If you want to use the exact same design system as this app, the full CSS is in the OrcaAppBuilder source code — feel free to copy it.
When a user clicks "Connect Wallet" in your app, their Trust Wallet (or MetaMask) pops up asking for permission. Here's the complete, working code:
const LIGHTCHAIN_CHAIN_ID = '0x23F8'; // 9200 in hex
async function connectWallet() {
if (!window.ethereum) {
alert('No wallet found. Please install Trust Wallet or MetaMask.');
return null;
}
try {
// Ask user to approve the connection
const provider = new ethers.BrowserProvider(window.ethereum);
await provider.send('eth_requestAccounts', []);
const signer = await provider.getSigner();
const address = await signer.getAddress();
// Make sure they're on Lightchain (not Ethereum)
const network = await provider.getNetwork();
if (network.chainId !== 9200n) {
// Ask wallet to switch to Lightchain
try {
await window.ethereum.request({
method: 'wallet_switchEthereumChain',
params: [{ chainId: LIGHTCHAIN_CHAIN_ID }]
});
} catch (switchError) {
// If Lightchain isn't in their wallet yet, add it
await window.ethereum.request({
method: 'wallet_addEthereumChain',
params: [{
chainId: LIGHTCHAIN_CHAIN_ID,
chainName: 'Lightchain AI Mainnet',
nativeCurrency: { name: 'LCAI', symbol: 'LCAI', decimals: 18 },
rpcUrls: ['https://rpc.mainnet.lightchain.ai'],
blockExplorerUrls: ['https://mainnet.lightscan.app']
}]
});
}
}
return { provider, signer, address };
} catch (error) {
if (error.code === 4001) {
alert('You declined the connection request. Click Connect Wallet again to try.');
}
return null;
}
}Once the wallet is connected, collecting payment for access is a simple contract call:
const CONTRACT_ADDRESS = '0xYourContractAddress';
const CONTRACT_ABI = [
'function purchaseAccess() external payable',
'function hasAccess(address user) public view returns (bool)'
];
async function purchaseAccess(walletData) {
const contract = new ethers.Contract(CONTRACT_ADDRESS, CONTRACT_ABI, walletData.signer);
// 5 LCAI = '5000000000000000000' (18 zeros = 1 LCAI)
const price = ethers.parseEther('5.0');
try {
const tx = await contract.purchaseAccess({ value: price });
// Show a loading message while the transaction confirms
console.log('Transaction sent:', tx.hash);
await tx.wait(); // Wait for blockchain confirmation
console.log('Payment confirmed!');
return true;
} catch (error) {
if (error.code === 4001) {
alert('You cancelled the transaction in your wallet.');
}
return false;
}
}If your app is a single HTML file with no Python server, GitHub Pages hosts it for free. This is perfect for apps where the AI runs server-side on Railway and your frontend just calls it.
- Create a new repository on GitHub (click the + button at the top)
- Upload your index.html file
- Go to Settings → Pages → set Source to "main branch"
- Your app is live at yourusername.github.io/yourrepo
Every time you update your HTML file and push to GitHub, the live site updates automatically.
If your app needs AIVM or a database, you need a Python server running somewhere. Railway is the simplest option.
- Create a new project on Railway (railway.app)
- Click "New Service" → "GitHub Repo" → pick your repo
- Railway will auto-detect Python and install your requirements.txt
- Set your environment variables (LIGHTCHAIN_PRIVATE_KEY, etc.) in the Railway dashboard
- Every time you push to GitHub, Railway auto-deploys in about 2 minutes
your-app-server/ ├── server.py ← your Python server ├── requirements.txt ← package list (exact versions matter!) ├── Procfile ← tells Railway how to start your server └── railway.toml ← optional: health check config
web: python server.py
Every time you edit your index.html, you push it to GitHub and the live site updates in about 60 seconds. Two ways to do this — pick the one that matches your setup:
- Open GitHub Desktop (download at desktop.github.com if you haven't already)
- Click "Add repository" → find your app folder on your computer
- Edit your index.html in VS Code and save it
- Switch back to GitHub Desktop — your change appears automatically in the left panel
- Type a brief note in the "Summary" box (example: Update: fixed the buy button)
- Click the blue "Commit to main" button → then click "Push origin"
- Go to yourusername.github.io/yourrepo — your app is live in about 60 seconds ✅
If you prefer the terminal, run these commands from inside your project folder:
cd C:\Users\YourName\Desktop\your-app-folder git add index.html git commit -m "Update: describe what you changed" git push origin main
cd ~/Desktop/your-app-folder git add index.html git commit -m "Update: describe what you changed" git push origin main
cd ~/Desktop/your-app-folder git add index.html git commit -m "Update: describe what you changed" git push origin main
Railway auto-deploys from GitHub. To update your server:
cd ~/Desktop/your-server-folder git add -A git commit -m "Update: describe what changed" git push https://yourusername:YOUR_GITHUB_TOKEN@github.com/yourusername/yourrepo.git main
- ☐ Test your app on mobile (open on your phone)
- ☐ Test wallet connection with Trust Wallet
- ☐ Test the AI chat (make sure AIVM responses come through)
- ☐ Add a Terms & Disclaimer to your app (important for liability)
- ☐ Announce in the Lightchain Discord: discord.gg/lightchain
- ✅ Your app is live at a public URL
- ✅ Your app uses the blockchain (AIVM, LCAI payments, or a smart contract)
- ✅ A square logo image (any size, PNG)
- ✅ A thumbnail image (exactly 800×450 pixels — tip: make it in Canva for free)
- ✅ A GitHub account
Create a file called dapp-yourapp.json with this format:
{
"id": "dapp-yourapp",
"name": "Your App Name",
"tagline": "One catchy sentence about what it does",
"description": "2-3 sentences. What your app does, who it helps, and what makes it unique. Be specific — say what blockchain feature it uses.",
"tags": ["AI", "TOOLS", "MAINNET"],
"iconSrc": "/images/dapp-item-logo/yourapp-logo.png",
"imageSrc": "/images/dapp-item-thumb/yourapp-thumb.png",
"externalUrl": "https://yourapp.ai"
}A "PR" (Pull Request) is how you submit your app. It's like saying "here's my addition to your project — please review it."
- Go to: github.com/lightchain-protocol/lcai-dApp-hub
- Click Fork (top right) — this makes your own copy
- In your fork, upload your JSON file to constants/additionalDapps/
- Upload your logo to public/images/dapp-item-logo/
- Upload your thumbnail to public/images/dapp-item-thumb/
- Click Contribute → Open pull request
- Write a short description and submit — the Lightchain team will review it
Find Your App Idea
Not sure what to build? Answer a few questions and our AI will suggest real, buildable app ideas specifically for Lightchain. No experience needed.
Pick the one that excites you most. Don't overthink it — there are no wrong answers.
The AI is coming up with ideas based on what you told us...
Build Your App
Describe your idea or your existing project and get a complete, step-by-step build plan from the AI — including what to create, what tools to use, and sample code.
Fix a Problem
Pick a common issue below or describe your problem in plain English. The AI will walk you through exactly what's wrong and how to fix it.
This error appears even when your private key is perfectly valid. The real cause is a mismatch in the worker's public key format — the AIVM network sometimes returns a 33-byte compressed key instead of a 65-byte uncompressed key, and hardcoded DER headers only handle one format.
The fix: In your Python server, detect the key length before building the DER header:
klen = len(worker_pub_bytes)
if klen == 65: # uncompressed: 04 + x + y
oid = bytes.fromhex('3056301006072a8648ce3d020106052b8104000a034200')
elif klen == 33: # compressed: 02/03 + x
oid = bytes.fromhex('3036301006072a8648ce3d020106052b8104000a032200')
else:
raise ValueError(f'Unexpected key length: {klen}')
wpk = load_der_public_key(oid + worker_pub_bytes, backend=default_backend())Don't see your issue above? Describe it here. Paste any error messages you're seeing.
Your Tools & Accounts
Everything in one place — your accounts, your live apps, and quick links to all the tools you use. Saves to your browser so it's always here when you need it.
Paste your personal URLs for each service so you can get back to them in one click. Leave blank for services you don't use yet.
Links to your live apps, GitHub repos, and Railway dashboards. Add a link here for every project you launch.
Essential tools for building on Lightchain — click any card to open it.
Your Saved Projects
Save your app ideas, build plans, and notes here. Come back anytime to pick up where you left off. Everything saves to your browser — no account needed.