Skip to content

fix(ci): unbreak lint workflow + fix 138 pre-existing violations #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
DimitarTAtanasov wants to merge 3 commits into
base: main
Choose a base branch
from
Open

fix(ci): unbreak lint workflow + fix 138 pre-existing violations #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5a6a3e7
fix(ci): rename $args to $dockerArgs in common.ps1 Invoke-Worker
DimitarTAtanasov May 21, 2026
4aab86e
fix(ci): extract markdownlint config to a real file so the workflow runs
DimitarTAtanasov May 22, 2026
2e14dec
style(docs): fix 137 pre-existing markdownlint violations
DimitarTAtanasov May 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 1 addition & 10 deletions .github/workflows/lint.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,13 +61,4 @@ jobs:
- uses: actions/checkout@v4

- uses: DavidAnson/markdownlint-cli2-action@v16
with:
globs: "**/*.md"
config: |
{
"default": true,
"MD013": false,
"MD024": { "siblings_only": true },
"MD033": false,
"MD041": false
}
# globs + config are auto-discovered from .markdownlint-cli2.jsonc in the repo root.
11 changes: 11 additions & 0 deletions .markdownlint-cli2.jsonc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
{
"config": {
"default": true,
"MD013": false,
"MD024": { "siblings_only": true },
"MD033": false,
"MD041": false
},
"globs": ["**/*.md"],
"ignores": ["node_modules"]
}
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
## [Unreleased]

### Added

- Bash scripts (`scripts/bash/`) — full parity with the PowerShell flow, for Linux and macOS users.
- `docs/architecture.md` — sequence diagram of the 8-stage job lifecycle, component glossary, and the metrics reference.
- `docs/installation-{windows,linux,macos}.md` — per-OS install guides with verified commands.
Expand All @@ -20,13 +21,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
- Issue and PR templates.

### Fixed

- `SUPPORTED_MODELS` default switched from `llama3-8b:latest` back to `llama3-8b`. The `:latest` suffix passed the local startup health check but caused every routed job to fail at stage 5 because `keccak256("llama3-8b:latest")` doesn't match the on-chain registered model hash (`keccak256("llama3-8b") = 0xf4a414fa...`). See [troubleshooting issue #1](./docs/troubleshooting.md#1-model-hash-mismatch-stage-5-failure).
- `OLLAMA_URL` on Windows now defaults to the explicit IPv4 `http://192.168.65.254:11434` rather than `host.docker.internal`. On Docker Desktop for Windows, the latter resolves IPv6-first, which can stall Go's HTTP client. See [troubleshooting issue #9](./docs/troubleshooting.md#9-windows-host.docker.internal-ipv6-first).
- `08-run-worker.ps1` now accepts `-NoTail` to skip the blocking `docker logs -f` call after starting the container (useful in automation).
- `07-register.ps1` now accepts `-Force` to skip the `Type 'register' to confirm` prompt (for non-interactive flows).
- `deregister.ps1` now accepts `-Force` for the same reason.

### Changed

- Project layout: PowerShell scripts moved from `scripts/*.ps1` to `scripts/powershell/`, with `scripts/bash/` added alongside.
- `WORKER_PASSWORD` is now generated as a 32-character cryptographically random string on first run of `00-generate-key.ps1`, instead of relying on the user to choose one.
- `secrets.{ps1,env}` is created with restrictive ACLs (Windows: current user only via `Set-Acl`; Linux/macOS: `chmod 600`) automatically.
Expand All @@ -37,6 +40,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
Initial PowerShell port of the [official Lightchain worker onboarding](https://workers-testnet.lightchain.ai/run-node).

### Added

- `scripts/*.ps1` covering phases 00-08 (key gen, contract resolve, ollama prep, image pull, key import, ECDH gen, fund, register, run).
- `scripts/status.ps1`, `scripts/stop.ps1`, `scripts/deregister.ps1`, `scripts/sweep-rewards.ps1`, `scripts/tail-jobs.ps1` for day-2 ops.
- `scripts/common.ps1` with shared `Invoke-Worker` helper.
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ If your change is invasive (new env var, new script, new dependency), describe y

Conventional Commits style preferred but not enforced:

```
```text
fix: handle host.docker.internal IPv6-first on Windows
docs: add stage 5 hash-mismatch entry to troubleshooting
feat: add sweep-rewards --dry-run
Expand Down
106 changes: 53 additions & 53 deletions README.md
View file
Open in desktop

Large diffs are not rendered by default.

78 changes: 39 additions & 39 deletions docs/architecture.md
View file
Open in desktop

Large diffs are not rendered by default.

16 changes: 8 additions & 8 deletions docs/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@

### Is this toolkit official?

No. It's an independent community toolkit. The official documentation is at https://workers-testnet.lightchain.ai/run-node. This toolkit automates and extends that flow, with PowerShell support for Windows users and battle-tested fixes for the gotchas we hit in production.
No. It's an independent community toolkit. The official documentation is at <https://workers-testnet.lightchain.ai/run-node>. This toolkit automates and extends that flow, with PowerShell support for Windows users and battle-tested fixes for the gotchas we hit in production.

### Mainnet or testnet — which should I start with?

**Testnet first**, if it's your first time. Testnet LCAI comes free from the faucet (https://lightfaucet.ai/), so you can practice the full onboarding with zero financial risk. Once you're comfortable, switch `$env:NETWORK = "mainnet"` and follow the same flow with real LCAI.
**Testnet first**, if it's your first time. Testnet LCAI comes free from the faucet (<https://lightfaucet.ai/>), so you can practice the full onboarding with zero financial risk. Once you're comfortable, switch `$env:NETWORK = "mainnet"` and follow the same flow with real LCAI.

### How much can I earn?

Expand Down Expand Up @@ -157,12 +157,12 @@ Lightchain uses EIP-4844 blobs for prompts and responses (rather than calldata)

### What's the difference between the Worker Gateway and the Dispatcher?

| | Worker Gateway | Dispatcher |
|---|---|---|
| Protocol | WebSocket | HTTPS / REST |
| Talks to | Workers (push jobs) | Requesters (accept inference requests) |
| Purpose | Schedules + load-balances jobs to live workers | Front-door for inference clients; creates JobRegistry entries |
| Worker env var | `WORKER_GATEWAY_URL` | (not used by worker) |
| | Worker Gateway | Dispatcher |
| -------------- | ---------------------------------------------- | ------------------------------------------------------------- |
| Protocol | WebSocket | HTTPS / REST |
| Talks to | Workers (push jobs) | Requesters (accept inference requests) |
| Purpose | Schedules + load-balances jobs to live workers | Front-door for inference clients; creates JobRegistry entries |
| Worker env var | `WORKER_GATEWAY_URL` | (not used by worker) |

You only interact with the Dispatcher if you're building an *inference client* (sending prompts to the network). For running a worker, you only need the gateway.

Expand Down
4 changes: 2 additions & 2 deletions docs/installation-linux.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Tested on **Ubuntu 24.04 LTS** with an NVIDIA RTX 4070. Should work identically
| Tool | Version | Purpose |
| ----------------------------- | ------- | --------------------------------------------- |
| **Docker Engine** | ≥ 26.0 | Runs the worker container |
| **NVIDIA Container Toolkit** | latest | Only if you want Ollama in Docker (we won't) |
| **NVIDIA Container Toolkit** | latest | Only if you want Ollama in Docker (we won't) |
| **Ollama** | ≥ 0.5 | Local LLM runtime |
| **Foundry (cast)** | ≥ 1.7.1 | EVM wallet ops, contract reads |
| **Bash** | ≥ 4.0 | Required for several scripts |
Expand Down Expand Up @@ -122,7 +122,7 @@ sudo systemctl edit ollama

Add:

```
```ini
[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"
```
Expand Down
28 changes: 14 additions & 14 deletions docs/installation-macos.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,25 +6,25 @@ Tested on **macOS 14 Sonoma** (M2 Pro). Should work identically on macOS 13+ on

Apple Silicon (M1/M2/M3/M4) does **not** have CUDA — Ollama uses Metal acceleration instead, which is automatic and fast. **Performance comparison for llama3-8b inference (rough):**

| Hardware | Tokens/sec | Job time (typical) |
| -------------------- | ----------- | ------------------ |
| M1 8 GB | ~10 | very slow |
| M1 Pro / M2 8 GB | ~20 | borderline |
| M2 Pro 16 GB | ~30-40 | usable |
| M3 Max / M4 Max | ~70-90 | comfortable |
| RTX 3060 (CUDA, 12GB)| ~80 | comfortable |
| RTX 4070 (CUDA, 12GB)| ~120 | competitive |
| Hardware | Tokens/sec | Job time (typical) |
| --------------------- | ----------- | ------------------ |
| M1 8 GB | ~10 | very slow |
| M1 Pro / M2 8 GB | ~20 | borderline |
| M2 Pro 16 GB | ~30-40 | usable |
| M3 Max / M4 Max | ~70-90 | comfortable |
| RTX 3060 (CUDA, 12GB) | ~80 | comfortable |
| RTX 4070 (CUDA, 12GB) | ~120 | competitive |

If you're on an 8 GB Mac, you can run the worker but expect to lose timeouts on some jobs. **16 GB unified memory** is the practical floor for competitive throughput.

## Required software

| Tool | Version | Purpose | Install |
| ------------------ | ------- | ------------------------------------ | -------------------------------------- |
| **Docker Desktop** | ≥ 4.30 | Runs the worker container | `brew install --cask docker` |
| **Ollama** | ≥ 0.5 | Local LLM runtime | `brew install ollama` |
| Tool | Version | Purpose | Install |
| ------------------ | ------- | ------------------------------------ | ----------------------------------------------------------- |
| **Docker Desktop** | ≥ 4.30 | Runs the worker container | `brew install --cask docker` |
| **Ollama** | ≥ 0.5 | Local LLM runtime | `brew install ollama` |
| **Foundry (cast)** | ≥ 1.7.1 | EVM wallet ops, contract reads | `curl -L https://foundry.paradigm.xyz \| bash && foundryup` |
| **Bash** | ≥ 4.0 | Required for several scripts | `brew install bash` |
| **Bash** | ≥ 4.0 | Required for several scripts | `brew install bash` |

## Install steps

Expand Down Expand Up @@ -70,7 +70,7 @@ bash --version # GNU bash, version 5.x

macOS hasn't shipped a newer bash since 2007 because bash 4+ is GPLv3 (Apple won't bundle GPLv3 code). Several scripts (e.g. `04-import-key.sh`, `06-fund-worker.sh`) use the `${var,,}` lowercase parameter expansion introduced in bash 4.0. On the stock bash you'll see:

```
```text
./04-import-key.sh: line 35: ${reported,,}: bad substitution
```

Expand Down
10 changes: 5 additions & 5 deletions docs/installation-windows.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,12 @@ Tested on **Windows 11** (build 26200, PowerShell 5.1+). Should work identically

## Required software

| Tool | Version | Purpose | Install |
| ------------------- | ------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------ |
| **Docker Desktop** | ≥ 4.30 | Runs the worker container | `winget install --id Docker.DockerDesktop --exact` |
| **Ollama** | ≥ 0.5 | Local LLM runtime | `winget install --id Ollama.Ollama --exact` |
| Tool | Version | Purpose | Install |
| ------------------- | ------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| **Docker Desktop** | ≥ 4.30 | Runs the worker container | `winget install --id Docker.DockerDesktop --exact` |
| **Ollama** | ≥ 0.5 | Local LLM runtime | `winget install --id Ollama.Ollama --exact` |
| **Foundry (cast)** | ≥ 1.7.1 | EVM wallet ops, contract reads, on-chain sends | Download from [foundry-rs releases](https://github.com/foundry-rs/foundry/releases) |
| **WSL2** (optional) | latest | Only needed if you prefer Bash over PowerShell | `wsl --install` (built into Windows 10/11) |
| **WSL2** (optional) | latest | Only needed if you prefer Bash over PowerShell | `wsl --install` (built into Windows 10/11) |

## One-shot installer

Expand Down
16 changes: 8 additions & 8 deletions docs/onboarding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,14 @@ The toolkit's `00-*` through `08-*` scripts walk you through onboarding. This do

## Cost summary (mainnet)

| Item | Amount | Reversible? |
| ----------------------------- | --------------------------------- | ---------------------------------------------- |
| Item | Amount | Reversible? |
| ----------------------------- | --------------------------------- | -------------------------------------------------------------------- |
| Stake | 50,000 LCAI | Yes — `deregister` returns it to worker wallet (minus any slashing). |
| Funding tx gas | < 0.01 LCAI | No (spent on gas). |
| Registration tx gas | < 0.05 LCAI | No. |
| Gas buffer in worker wallet | ~5 LCAI (recommended) | Yes — sweep when no longer needed. |
| Per-job ack + complete gas | < 0.001 LCAI per job | No. |
| **Total upfront** | **~50,005 LCAI** | |
| Funding tx gas | < 0.01 LCAI | No (spent on gas). |
| Registration tx gas | < 0.05 LCAI | No. |
| Gas buffer in worker wallet | ~5 LCAI (recommended) | Yes — sweep when no longer needed. |
| Per-job ack + complete gas | < 0.001 LCAI per job | No. |
| **Total upfront** | **~50,005 LCAI** | |

## Phase 00 — Generate a fresh worker key

Expand Down Expand Up @@ -264,7 +264,7 @@ The full env block passed to the container includes all the values from `env.{ps

### Healthy startup looks like this

```
```text
INFO worker registration validated — on-chain key matches local key address=0x6BE4...
WARN ollama model verification failed (non-fatal) error="missing models on Ollama server: [llama3-8b]"
INFO blob mode: eip-4844 (beacon)
Expand Down
2 changes: 1 addition & 1 deletion docs/operations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ After [onboarding](./onboarding.md) is done, these are the things you'll actuall

A successful job log block looks like this (timestamps and IDs vary):

```
```text
INFO ws_job_received jobId=543
INFO processing job jobID=543 model="f4a414fa..." sessionID=336
INFO stage 1: sending ack tx jobID=543 stage=ack timeout=15s
Expand Down
Loading
Loading