Lightchain
Mainnet live

Run a Worker.
Power AI. Earn $LCAI.

Stake LCAI, serve llama3-8b inference jobs, and connect to the worker gateway. The full setup runs from a single Docker image, and rewards land directly in your worker wallet.

What is a Lightchain Node?

What is a Lightchain Node?

Unlike traditional blockchain nodes that only validate ledgers, Lightchain workers execute real AI workloads. Powered by Proof of Intelligence (PoI), every node runs the AIVM to process training, inference, and optimization tasks that help secure the network.

Why Run a Node?

Earn $LCAI rewards

Get paid in LCAI for every inference job your worker completes on the network.

Secure the network

Stake LCAI and contribute compute to a censorship-resistant AI layer.

Run real AI workloads

Claim inference sessions on-chain and stream llama3-8b answers to requesters through the worker gateway.

Before you onboard

Stand up these four prerequisites before you touch the worker image. Every step in the onboarding flow assumes they are already in place.

Docker

Required to pull the worker image and run the sidecar with --restart unless-stopped. On Linux, add yourself to the docker group (sudo usermod -aG docker $USER && newgrp docker), or prefix the docker commands below with sudo.

GPU with 8GB+ VRAM

Enough headroom to serve llama3-8b through Ollama on the host.

Foundry (cast)

Used for key generation, contract reads, balance checks, and funding the worker.

Funder wallet (50,051+ LCAI)

An existing wallet you control. It pays the 50,000 stake plus a gas buffer for the worker's claim, ack, blob and completion transactions, and never doubles as the worker key.

Onboard in nine steps

From a fresh worker key to a running container connected to the worker gateway. Run each command top to bottom, since most steps depend on env vars exported in the previous one.

Phase 00

Generate a fresh worker key

Always use a brand-new key for the worker. Never reuse your funder. The worker key sits in a Docker container next to the keystore password, so it should hold only the working capital you are comfortable exposing on that machine.

  • Run cast wallet new and copy both the address and the private key.
  • Export them as WORKER_ADDR and WORKER_PRIVKEY for later steps.
  • Sanity check that the privkey derives back to the same address before funding it.
Generate worker key
cast wallet new export WORKER_ADDR=0x... # Address line from cast wallet new export WORKER_PRIVKEY=... # Private key line cast wallet address --private-key "$WORKER_PRIVKEY"

Phase 01

Resolve mainnet contract addresses

AIConfig and JobRegistry are resolved from the predeployed WorkerRegistry, and SessionManager from AIConfig. The docker run steps below pick them up from your shell.

  • Set the mainnet RPC URL and predeployed WorkerRegistry address.
  • Read AIConfig and JobRegistry from WorkerRegistry, then SessionManager from AIConfig, via cast call.
  • Echo the values to confirm they exported successfully.
Resolve & export addresses
export RPC_URL=https://rpc.mainnet.lightchain.ai export WORKER_REGISTRY_ADDRESS=0x0000000000000000000000000000000000001002 export AI_CONFIG_ADDRESS=$(cast call $WORKER_REGISTRY_ADDRESS "aiConfig()(address)" --rpc-url $RPC_URL) export JOB_REGISTRY_ADDRESS=$(cast call $WORKER_REGISTRY_ADDRESS "jobRegistry()(address)" --rpc-url $RPC_URL) export SESSION_MANAGER_ADDRESS=$(cast call $AI_CONFIG_ADDRESS "getSessionManagerAddress()(address)" --rpc-url $RPC_URL) echo "AI_CONFIG_ADDRESS=$AI_CONFIG_ADDRESS" echo "JOB_REGISTRY_ADDRESS=$JOB_REGISTRY_ADDRESS" echo "SESSION_MANAGER_ADDRESS=$SESSION_MANAGER_ADDRESS"

Phase 02

Install Ollama and pull a model

The worker calls Ollama on the host to serve inference. Install the runtime, start the server, pull llama3:8b, then alias it to llama3-8b so SUPPORTED_MODELS resolves.

  • Install Ollama and run ollama serve in the background.
  • Pull llama3:8b, the model the worker advertises by default.
  • Alias it as llama3-8b to match SUPPORTED_MODELS.
Install runtime + pull model
curl -fsSL https://ollama.com/install.sh | sh ollama serve & ollama pull llama3:8b ollama cp llama3:8b llama3-8b

Phase 03

Pull the worker Docker image

Pull the official mainnet worker image. The same image runs the CLI subcommands (import-key, keygen, register, status, deregister) and the long-running sidecar.

Pull worker image
docker pull registry.lightchain.ai/mainnet/worker:latest

Phase 04

Import the worker private key

Encrypt $WORKER_PRIVKEY into a keystore the container can mount. The Address printed by import-key must equal $WORKER_ADDR. If they differ, stop, because the wrong key was imported.

  • Create the keystore directory the container will mount.
  • Run import-key with the private key and your chosen password.
  • Confirm the printed address matches $WORKER_ADDR exactly.
Import key into keystore
mkdir -p ~/lightchain-worker/keys docker run --rm -v ~/lightchain-worker/keys:/data --entrypoint /bin/lightchain-worker registry.lightchain.ai/mainnet/worker:latest import-key --private-key "$WORKER_PRIVKEY" --password <YOUR_PASSWORD> --output /data/eth-keystore

Phase 05

Generate the ECDH encryption key

The worker registers an ECDH public key on-chain so requesters can encrypt jobs to it. Run keygen once to derive and persist the encryption keystore alongside the eth keystore.

Generate ECDH key
docker run --rm -v ~/lightchain-worker/keys:/data -e WORKER_KEYSTORE_PATH=/data/eth-keystore/$(ls ~/lightchain-worker/keys/eth-keystore/ | head -1) -e WORKER_KEYSTORE_PASSWORD=<YOUR_PASSWORD> -e ENCRYPTION_KEYSTORE_PATH=/data/worker-encryption.key -e RPC_URL=https://rpc.mainnet.lightchain.ai -e CHAIN_ID=9200 -e WORKER_REGISTRY_ADDRESS=0x0000000000000000000000000000000000001002 -e AI_CONFIG_ADDRESS=$AI_CONFIG_ADDRESS -e SUPPORTED_MODELS=llama3-8b --entrypoint /bin/lightchain-worker registry.lightchain.ai/mainnet/worker:latest keygen

Phase 06

Fund the worker from your funder wallet

Send LCAI from your funder wallet to $WORKER_ADDR. The worker needs 50,000 LCAI for the minimum stake plus a gas buffer: besides the register tx and the per-job ack, blob and completion txs, it pays for its own claimSession transactions. Fund 50,051 LCAI: the stake, a 50 LCAI gas buffer, and a little on top because registering itself spends gas.

  • Set FUNDER_PRIVKEY to your existing funder wallet, never the worker key.
  • Send 50,051 LCAI to $WORKER_ADDR with cast send.
  • Verify the worker received the funds with cast balance.
Send LCAI to worker
export FUNDER_PRIVKEY=... cast send "$WORKER_ADDR" --value 50051ether --rpc-url "$RPC_URL" --private-key "$FUNDER_PRIVKEY" cast balance "$WORKER_ADDR" --rpc-url "$RPC_URL" | awk '{printf "%.4f LCAI\n", $1/1e18}'

Phase 07

Register on-chain

Submit the registration transaction. This stakes 50,000 LCAI (auto-queried from AIConfig), registers your ECDH public key on-chain, and adds llama3-8b to your supported models.

Register worker
docker run --rm -v ~/lightchain-worker/keys:/data -e WORKER_KEYSTORE_PATH=/data/eth-keystore/$(ls ~/lightchain-worker/keys/eth-keystore/ | head -1) -e WORKER_KEYSTORE_PASSWORD=<YOUR_PASSWORD> -e ENCRYPTION_KEYSTORE_PATH=/data/worker-encryption.key -e RPC_URL=https://rpc.mainnet.lightchain.ai -e CHAIN_ID=9200 -e WORKER_REGISTRY_ADDRESS=0x0000000000000000000000000000000000001002 -e AI_CONFIG_ADDRESS=$AI_CONFIG_ADDRESS -e SUPPORTED_MODELS=llama3-8b --entrypoint /bin/lightchain-worker registry.lightchain.ai/mainnet/worker:latest register

Phase 08

Run the worker and verify

Start the long-running sidecar in detached mode. SORTITION_ENABLED together with WORKER_GATEWAY_URL selects the external profile: the worker claims sessions on-chain itself and uses the gateway to stream answers, send heartbeats, and set its drain marker. The --add-host flag is a no-op on macOS and Windows, but it makes host.docker.internal resolve on Linux. Tail the logs to confirm the worker is fully online.

  • Launch the worker container with --restart unless-stopped so it recovers from reboots.
  • Tail the logs and look for external worker profile, registration validated, authenticated with worker-gateway, sortition mode, and gateway stream connected.
  • Once those lines appear, the worker is sending heartbeats every 10s and watching the chain for sessions to claim. A quiet log is normal until it wins one.
Run worker (detached) + tail logs
docker run -d --restart unless-stopped --user root --name lightchain-worker --add-host=host.docker.internal:host-gateway -v ~/lightchain-worker/keys:/data -e WORKER_KEYSTORE_PATH=/data/eth-keystore/$(ls ~/lightchain-worker/keys/eth-keystore/ | head -1) -e WORKER_KEYSTORE_PASSWORD=<YOUR_PASSWORD> -e ENCRYPTION_KEYSTORE_PATH=/data/worker-encryption.key -e RPC_URL=https://rpc.mainnet.lightchain.ai -e CHAIN_ID=9200 -e WORKER_REGISTRY_ADDRESS=0x0000000000000000000000000000000000001002 -e AI_CONFIG_ADDRESS=$AI_CONFIG_ADDRESS -e JOB_REGISTRY_ADDRESS=$JOB_REGISTRY_ADDRESS -e SUPPORTED_MODELS=llama3-8b -e OLLAMA_URL=http://host.docker.internal:11434 -e BEACON_API_URL=https://beacon.mainnet.lightchain.ai -e BLOB_MODE=beacon -e SESSION_KEY_FILE=/data/session-keys.enc -e RELEASE_STATE_PATH=/data/release_state.json -e SORTITION_ENABLED=true -e SESSION_MANAGER_ADDRESS=$SESSION_MANAGER_ADDRESS -e SORTITION_STATE_DIR=/data/sortition-state -e SHUTDOWN_TIMEOUT=240s -e WORKER_GATEWAY_URL=https://worker-gateway.mainnet.lightchain.ai registry.lightchain.ai/mainnet/worker:latest docker logs -f lightchain-worker

Launch checklist

If you can tick every box before docker run, the worker should come online without surprises.

Launch checklist

I generated a brand-new worker key, separate from my funder.

cast wallet address --private-key "$WORKER_PRIVKEY" returns $WORKER_ADDR.

AI_CONFIG_ADDRESS, JOB_REGISTRY_ADDRESS, and SESSION_MANAGER_ADDRESS are exported.

Resolved from the predeployed WorkerRegistry and from AIConfig on mainnet.

My funder wallet sent 50,051+ LCAI to $WORKER_ADDR.

cast balance confirms the worker has stake plus a gas buffer.

Ollama is running and llama3-8b is pulled and aliased.

ollama list shows llama3-8b. The worker reaches it via host.docker.internal:11434.

Logs show registration validated, gateway auth, sortition mode, and gateway stream connected.

Those lines confirm the worker is fully online and watching the chain for sessions to claim.

Network reference

Contract addresses and public endpoints for the selected network. Switch tabs at the top of the page to view mainnet or testnet.

Mainnet reference

Mainnet protocol contract addresses and public endpoints used by the onboarding flow above when Mainnet is selected.

Contract addresses

Predeploys live at the genesis slots; protocol contracts are upgradeable proxies. The 5 protocol contracts (WorkerRegistry, FeePool, AIConfig, JobRegistry, SessionManager) are owned by one team account, 0x8a35E00eff6f3bf125aE5011cc7C603E18B8D616. The Treasury is owned by the Timelock.

  • WorkerRegistryGenesis predeploy

    0x0000000000000000000000000000000000001002

  • FeePoolGenesis predeploy

    0x0000000000000000000000000000000000001004

  • NativeVotesGenesis predeploy

    0x0000000000000000000000000000000000001001

  • AIConfig (proxy)Proxy

    0x24D11533C354092ed6E18b964257819cE78Ce77D

  • JobRegistry (proxy)Proxy

    0xfB15F90298e4CcD7106E76fFB5e520315cC42B0b

  • SessionManager (proxy)Proxy

    0xfFFCed75eF4Cdae0Cc33A27Bb46531B957a9f4e7

  • Treasury (proxy)Proxy

    0x786eDe8C42Ca54E54c9dCECa9b30052CF4743389

  • LightChainGovernor (proxy)Proxy

    0xD216A0c0050EdC3a9E0449EcFDf178A1652b4b68

  • TimelockController48h delay

    0xc783376c8237E8f1ed17d825CE7CBB4c22e3cAE5

Public endpoints

The RPC, beacon, and gateway URLs the worker uses out of the box.

  • Chain RPC

    https://rpc.mainnet.lightchain.ai

  • Archive RPC

    https://archive.mainnet.lightchain.ai

  • Beacon API

    https://beacon.mainnet.lightchain.ai

  • Worker Gateway

    https://worker-gateway.mainnet.lightchain.ai

  • Status page

    https://status.mainnet.lightchain.ai

Operate, monitor, and exit

Once the worker is live, these are the commands and flows you will come back to. They use the same image and env vars from the onboarding steps.

Check registration status

Run the status subcommand against the same keystore you used to register. It confirms stake, supported models, and on-chain worker health without restarting the sidecar.

Check status
docker run --rm -v ~/lightchain-worker/keys:/data -e WORKER_KEYSTORE_PATH=/data/eth-keystore/$(ls ~/lightchain-worker/keys/eth-keystore/ | head -1) -e WORKER_KEYSTORE_PASSWORD=<YOUR_PASSWORD> -e ENCRYPTION_KEYSTORE_PATH=/data/worker-encryption.key -e RPC_URL=https://rpc.mainnet.lightchain.ai -e CHAIN_ID=9200 -e WORKER_REGISTRY_ADDRESS=0x0000000000000000000000000000000000001002 -e AI_CONFIG_ADDRESS=$AI_CONFIG_ADDRESS -e SUPPORTED_MODELS=llama3-8b --entrypoint /bin/lightchain-worker registry.lightchain.ai/mainnet/worker:latest status

Tail jobs in real time

Filter docker logs for claimed session request, stage 1, job completed, and serve job failed to watch the worker win sessions and serve their jobs. A quiet log is normal while other workers win the draws.

Tail job logs
docker logs -f --tail=0 lightchain-worker 2>&1 | grep -E "claimed session request|stage 1|job completed|serve job failed"

Stop the worker

Stop and remove the running sidecar container. A running worker keeps claiming sessions until its process stops, so the drain subcommand alone does not take it out of rotation. On SIGTERM it stops claiming and starts no new job at once, and the jobs it is still running get up to SHUTDOWN_TIMEOUT (240 s in the Phase 08 command) to finish; docker stop -t 300 leaves it that time. Images before worker release v0.0.5 end a running job at once, so pull the image again before relying on this. Later jobs in sessions it already claimed time out while it is offline. Your keystore, encryption key, and worker state stay on disk under ~/lightchain-worker/keys, and your registration plus stake remain on-chain. Restart with the docker run command from Phase 08 to come back online; leave the starting-block files as they are.

Stop & remove container
docker stop -t 300 lightchain-worker && docker rm lightchain-worker

Deregister and withdraw stake

Run deregister with the same keystore env vars used in Phase 07. It reverts with ActiveJobsExist until every job the worker completed is past its dispute window and released; the Drain & Graceful Exit page in the docs has the release step. It removes the worker from the registry and returns the 50,000 LCAI stake (minus any slashing penalties) to the worker wallet. From there, transfer it to your designated wallet using cast send or a wallet UI.

Deregister worker
docker run --rm -v ~/lightchain-worker/keys:/data -e WORKER_KEYSTORE_PATH=/data/eth-keystore/$(ls ~/lightchain-worker/keys/eth-keystore/ | head -1) -e WORKER_KEYSTORE_PASSWORD=<YOUR_PASSWORD> -e ENCRYPTION_KEYSTORE_PATH=/data/worker-encryption.key -e RPC_URL=https://rpc.mainnet.lightchain.ai -e CHAIN_ID=9200 -e WORKER_REGISTRY_ADDRESS=0x0000000000000000000000000000000000001002 -e AI_CONFIG_ADDRESS=$AI_CONFIG_ADDRESS -e SUPPORTED_MODELS=llama3-8b --entrypoint /bin/lightchain-worker registry.lightchain.ai/mainnet/worker:latest deregister
Hardware requirements

Hardware Requirements

Confirm your hardware clears the minimum spec, or matches the recommended spec for headroom, before you start onboarding.

SpecificationMinimumRecommended
CPU4 Cores (x86_64)16 Cores (AMD/Intel)
RAM16GB DDR464GB+ DDR5
Storage512GB NVMe SSD2TB NVMe Gen4
GPU8GB VRAM (llama3-8b)24GB+ VRAM (RTX 4090/A100)
Internet100 Mbps Up/Down1 Gbps Symmetric
FAQ

Frequently Asked Questions