Solution: LP-0019: AI-Powered Logos Ecosystem Onboarding Toolkit [Prize + Solution]

README.md

@@ -41,6 +41,7 @@ All prizes live in the `[prizes/](prizes/)` directory. Each prize is a markdown
 | [LP-0015](prizes/LP-0015.md) | General cross-program calls via tail calls               | Large  | Closed |
 | [LP-0016](prizes/LP-0016.md) | Anonymous Forum with Threshold Moderation                | Large  | Open   |
 | [LP-0017](prizes/LP-0017.md) | Whistleblower: document upload and indexing Basecamp app     | Medium | Open   |
+| [LP-0019](prizes/LP-0019.md) | AI-Powered Logos Ecosystem Onboarding Toolkit | Medium | Open |
 
 ### Proposing a New Prize
 

prizes/LP-0019.md

@@ -0,0 +1,150 @@
+# LP-0019: AI-Powered Logos Ecosystem Onboarding Toolkit [Open]
+
+**`Status: Open`**
+**`Logos Circle: N/A`**
+
+## Overview
+
+This prize funds a suite of open-source developer tools that lower the barrier to
+understanding and operating within the Logos ecosystem:
+
+1. **A conversational AI assistant** embedded in the Logos validator staking interface,
+   answering questions about the Logos stack, testnet operations, and ecosystem
+   participation — live, without a centralised AI backend requirement.
+
+2. **An AI agent skill** that installs, upgrades, and monitors a Logos testnet node
+   from within any major AI coding assistant (Claude Code, GitHub Copilot, Gemini CLI,
+   and others) with a single command, fetching live release metadata at runtime.
+
+3. **A block indexer and REST API** that ingests all canonical Logos testnet blocks,
+   transactions, and proof-of-leadership key diagnostics into PostgreSQL, and exposes
+   a structured HTTP API for explorer frontends.
+
+Together these three components form an entry-point layer for the Logos ecosystem:
+a developer can ask what Logos is, get guided through running a node, and then observe
+their node's activity on-chain — all using open, self-hosted tooling.
+
+## Motivation
+
+Logos is building privacy-preserving infrastructure. Growing the validator set and
+developer community requires tooling that meets people where they already are: in their
+AI assistants, on staking dashboards, and in their browsers. Today these entry points
+are either missing or require deep protocol knowledge to navigate.
+
+This prize targets the onboarding gap directly: no new protocol modules are required,
+but the result meaningfully expands who can participate in the testnet and how quickly
+they can go from first contact to running a node and querying chain state.
+
+A competitive prize is the right mechanism because the assistant training corpus,
+skill interface design, indexer schema, and API surface admit many valid approaches,
+and the best implementations will be discovered through competition.
+
+## Success Criteria
+
+### AI Documentation Assistant
+
+- [ ] A conversational assistant is live and accessible at a public URL, answering
+  questions about the Logos stack, testnet participation, and node operations.
+- [ ] The assistant is embedded in or linked from a Logos-related validator or staking
+  interface, making it discoverable to validator operators.
+- [ ] The assistant uses Logos documentation as its primary knowledge source and does
+  not return factually incorrect information about the Logos protocol in standard queries.
+- [ ] The assistant is self-hostable: the repository includes deployment instructions
+  for running the assistant independently, with no mandatory dependency on a specific
+  hosted AI provider.
+
+### AI Agent Skill for Node Operations
+
+- [ ] The skill implements three commands: `install` (fresh node setup), `update`
+  (breaking upgrade with state wipe), and `status` (sync mode, peers, block height,
+  wallet balance).
+- [ ] The skill fetches the current stable Logos release from the GitHub API at runtime;
+  it correctly filters out pre-releases, release candidates, and drafts. No hardcoded
+  version strings.
+- [ ] The skill is installable via `npx` with a single command. No prerequisites beyond
+  Node.js.
+- [ ] The skill works with at least **3 distinct AI agent platforms** from: Claude Code,
+  GitHub Copilot, Gemini CLI, OpenAI Codex CLI, opencode, OpenClaw, or equivalent.
+- [ ] A documented `SKILL.md` defines the skill interface. A third party can implement
+  a compatible skill without reading the implementation.
+- [ ] If the GitHub API is unavailable, the skill falls back to the official Logos docs
+  and surfaces a clear message to the operator.
+
+### Block Indexer and Explorer API
+
+- [ ] The indexer ingests all canonical Logos testnet blocks, transactions, and
+  proof-of-leadership key diagnostics from a running Logos node into PostgreSQL.
+- [ ] The indexer correctly derives canonical block heights from the cryptarchia
+  tip chain (Logos v0.1.2 does not expose stable per-block height in the REST API).
+- [ ] A REST API exposes at minimum: blocks (paginated, filterable by finality and
+  canonical status), transactions (paginated), leader-key diagnostics, and a stats
+  summary endpoint.
+- [ ] The indexer and API are deployable via Docker Compose with a single command.
+- [ ] A public deployment of the indexer API is live and queryable during evaluation.
+
+### General
+
+- [ ] All three components are in public repositories licensed under MIT or Apache-2.0.
+- [ ] Each component includes a README with setup, configuration, and usage instructions.
+
+## Scope
+
+### In Scope
+
+- Conversational AI assistant for Logos documentation and ecosystem onboarding.
+- AI agent skill for Logos node installation, upgrade, and status monitoring.
+- Block indexer and REST API for Logos testnet chain data.
+- Self-hosting and deployment documentation for all three components.
+
+### Out of Scope
+
+- Logos Core protocol modules, LEZ programs, or ZK proof generation.
+- Wallet UI or token management interfaces.
+- Windows or macOS node installation support (Logos ships Linux x86_64 binaries only).
+- Full-text search or semantic indexing of transaction content.
+
+## Prize Structure
+
+- **Total Prize:** TBD (determined by Logos team)
+- **Effort:** Medium
+
+## Eligibility
+
+Open to any individual or team. Submissions must be original work. Teams must hold
+the rights to all submitted code and agree to license it under MIT or Apache-2.0.
+
+## Submission Requirements
+
+- Public repositories (MIT or Apache-2.0) for all three components.
+- Live, accessible URLs for the AI assistant and the block indexer API.
+- README files covering setup, deployment, and usage for each component.
+- GitHub issues filed for any Logos tooling problems encountered during development.
+
+## Evaluation Process
+
+Submissions are evaluated first-come-first-served against the success criteria.
+Evaluators may verify live deployments directly via the submitted URLs and clone
+repositories to run locally.
+
+The following policies apply to all prizes (see [evaluation policies](../README.md#evaluation-policies)):
+
+- **Submissions:** each builder (or team) is allowed a maximum of **3 submissions**
+  per prize, with at most **one submission/review per week**.
+- **Feedback:** initial evaluation feedback is limited to a pass/fail indication
+  against the success criteria.
+
+## Resources
+
+- [Logos Blockchain releases](https://github.com/logos-blockchain/logos-blockchain/releases)
+- [Logos quickstart docs](https://github.com/logos-co/logos-docs)
+- [Logos testnet dashboard](https://testnet.blockchain.logos.co/web/)
+- [AgentSkills standard](https://agentskills.io)
+- [LP-0008](LP-0008.md) — Autonomous AI Module (reference for skill interface patterns)
+- [LP-0017](LP-0017.md) — Whistleblower (reference for indexer/storage patterns)
+
+## Potential for Subsequent λPrizes
+
+A follow-up prize may replace the assistant's static document corpus with a
+RAG-backed MCP server (`logos-rag-mcp`) that indexes Logos documentation automatically
+and serves context-aware answers to any compatible AI agent skill — eliminating manual
+updates when Logos documentation changes.

solutions/LP-0019.md

@@ -0,0 +1,159 @@
+# Solution: LP-0019 — AI-Powered Logos Ecosystem Onboarding Toolkit
+
+**Submitted by:** CitizenWeb3
+
+## Summary
+
+Three open-source tools that lower the barrier to understanding and operating
+within the Logos ecosystem — a live AI documentation assistant, an AI agent skill
+for node operations, and a block indexer with REST API for Logos testnet data.
+All three are live and available today.
+
+## Repositories
+
+| Component | Repository | Live |
+|---|---|---|
+| AI Documentation Assistant | https://github.com/citizenweb3/ai-integrations/tree/logos-onboarding-assistant | https://logos.staking.citizenweb3.com |
+| AI Agent Node Skill | https://github.com/citizenweb3/ai-integrations/tree/logos-node | `npx @citizenweb3/ai-integrations logos-node` |
+| Block Indexer + API | https://github.com/citizenweb3/chain-data-indexer/tree/logos-indexer-v0.1.2 | https://github.com/citizenweb3/chain-data-indexer/tree/logos-indexer-v0.1.2#explorer-api, https://validatorinfo.com |
+
+## Approach
+
+### AI Documentation Assistant
+
+A RAG-backed conversational assistant embedded in the CitizenWeb3 validator staking
+interface. It is trained on Logos documentation and answers questions about the stack,
+testnet participation, and node operations. Accessible directly at
+https://logos.staking.citizenweb3.com — no installation required.
+
+The assistant runs without a centralised Logos-specific backend. The staking interface
+entry point (https://staking.citizenweb3.com/chains/logos-testnet) surfaces the assistant
+prominently to validators researching the Logos testnet.
+
+### AI Agent Node Skill
+
+An AI agent skill installable via `npx` or `npm`, compatible with Claude Code, GitHub
+Copilot, Gemini CLI, OpenAI Codex CLI, opencode, and OpenClaw. The skill implements
+three commands:
+
+- `/logos-node install` — full node setup: binary, circuits, systemd service, faucet
+- `/logos-node update` — breaking upgrade: wipe state, re-init, restart
+- `/logos-node status` — sync mode, peers, block height, wallet balance
+
+The skill fetches the current stable Logos release from the GitHub API at runtime,
+filtering out pre-releases and release candidates. If the API is unavailable, it falls
+back to the official Logos quickstart documentation. No hardcoded version strings.
+
+The skill interface is defined in `skill/SKILL.md` — a third party can implement a
+compatible skill in a different language without reading the implementation.
+
+### Block Indexer + API
+
+A TypeScript/PostgreSQL indexer that ingests all canonical Logos testnet blocks,
+transactions, and proof-of-leadership key diagnostics from a running Logos node.
+The indexer handles Logos v0.1.2's lack of stable per-block height in the REST API
+by deriving canonical heights deterministically from the cryptarchia tip chain.
+
+A REST API on port 3001 exposes blocks, transactions, leader keys, and a stats
+summary — used as the data source for the Logos testnet view on
+[validatorinfo.com](https://validatorinfo.com). Deployable via Docker Compose with
+a single command.
+
+### Why this is useful for Logos
+
+These tools target the first 24 hours of a developer or validator's Logos journey:
+understanding what Logos is (assistant), getting a node running (skill), and seeing
+that node's activity on-chain (indexer/explorer). Each tool is self-contained, 
+open-source, and requires no protocol changes.
+
+## Success Criteria Checklist
+
+- [x] **AI assistant live at public URL**: https://logos.staking.citizenweb3.com
+- [x] **Embedded in validator/staking interface**: discoverable via https://staking.citizenweb3.com/chains/logos-testnet
+- [x] **Logos documentation as primary source**: assistant trained on Logos docs
+- [x] **Self-hostable**: logos-onboarding-assistant branch includes deployment instructions
+- [x] **Skill implements install / update / status**: all three commands implemented and documented
+- [x] **Live release resolution at runtime**: GitHub API call in SKILL.md with RC/pre-release filtering
+- [x] **Installable via npx**: `npx @citizenweb3/ai-integrations logos-node`
+- [x] **3+ AI agent platforms**: 6 platforms supported (Claude Code, Copilot, Gemini, Codex, opencode, OpenClaw)
+- [x] **Documented SKILL.md interface**: `skill/SKILL.md` in logos-node branch
+- [x] **Fallback to Logos docs on API failure**: documented in SKILL.md
+- [x] **Indexer ingests canonical blocks, transactions, leader keys**: logos-indexer-v0.1.2 branch
+- [x] **Canonical height derivation**: implemented in `runner/heightRepair.ts` and `runner/canonicalChain.ts`
+- [x] **REST API with blocks, transactions, leader keys, stats**: `/api/v1/*` endpoints, documented in `docs/indexer-api.md`
+- [x] **Docker Compose deployment**: `docker-compose.yaml` in logos-indexer-v0.1.2 branch
+- [x] **Public indexer deployment live**: https://validatorinfo.com (Logos testnet)
+- [x] **All repos public, MIT licensed**: confirmed
+
+## FURPS Self-Assessment
+
+### Functionality
+
+**AI Assistant:** Answers questions about Logos protocol, testnet participation, and node
+operations using Logos documentation as source. Handles follow-up questions in context.
+*Limitation*: knowledge is limited to the documentation corpus at deployment time; real-time
+chain data is not fed into the assistant.
+
+**Node Skill:** Implements install, update, and status for Linux x86_64 nodes.
+*Limitation*: Linux x86_64 only (mirrors current Logos binary availability).
+
+**Indexer:** Indexes all canonical blocks, transactions, and proof-of-leadership keys from
+Logos testnet v0.1.2. Wallet balances are not indexed (pending Logos public API support —
+tracked in `docs/future.md`). Per `docs/future.md`, UTXO/note decoding beyond raw storage
+is deferred to v0.2+.
+
+### Usability
+
+- **Assistant**: single click from the staking interface; no install, no account required.
+- **Node skill**: `npx @citizenweb3/ai-integrations logos-node` in any terminal with Node.js.
+  Then `/logos-node install` inside the agent. Each step explains what it's doing and why.
+- **Indexer**: `cp .env.example .env && docker compose up -d` for a full local deployment.
+
+### Reliability
+
+- **Skill**: falls back to Logos quickstart docs if GitHub API is unreachable. Validates
+  prerequisites (architecture, glibc, disk space) before starting any destructive operation.
+  Documents the binary/circuits version mismatch that causes `StartBlockNotFound` errors.
+- **Indexer**: exponential backoff on node API failures; resumes from last indexed slot on
+  restart; canonical chain tracker cleans up orphan finality on reorgs. Health endpoint
+  returns 503 when node is unreachable.
+
+### Performance
+
+No on-chain operations — no compute unit costs apply.
+
+- **Indexer**: backfill throughput is batch-configurable (`BATCH_SIZE`, default 500 slots).
+  Prometheus metrics exposed at `/metrics` for lag, pool health, and node tip tracking.
+  Typical steady-state lag is <10 slots on a co-located node.
+
+### Supportability
+
+- All three repositories are public with MIT license.
+- Indexer: Docker Compose deployment, `.env.example`, structured JSON logging (`LOG_FORMAT=json`),
+  Prometheus metrics, health endpoint, documented upgrade checklist in `docs/network-upgrades.md`.
+- Node skill: `skill/SKILL.md` interface spec, `skill/sharp-edges.md` known-issue documentation,
+  `skill/install-procedure.md` and `skill/update-procedure.md` step-by-step guides.
+- CI: to be added to logos-node and logos-onboarding-assistant branches.
+
+## Supporting Materials
+
+- **Live AI assistant**: https://logos.staking.citizenweb3.com
+- **Logos testnet entry point**: https://staking.citizenweb3.com/chains/logos-testnet
+- **Node skill npm install**: `npx @citizenweb3/ai-integrations logos-node`
+- **Indexer API (validatorinfo)**: https://validatorinfo.com
+
+## Terms & Conditions
+
+By submitting this solution, I confirm that I have read and agree to the
+[Terms & Conditions](../TERMS.md).
+
+## Additional context
+
+The Logos testnet is also listed and accessible via [ValidatorInfo](https://validatorinfo.com),
+a multi-chain validator explorer built and maintained by CitizenWeb3. While ValidatorInfo
+was not purpose-built for Logos, the Logos indexer branch was developed specifically to
+integrate Logos chain data into the explorer's existing infrastructure.
+
+
+
+