From a0951ab3d7f98b51f7582148329e9bce841db4cf Mon Sep 17 00:00:00 2001 From: serejandmyself Date: Fri, 15 May 2026 23:20:05 +0100 Subject: [PATCH 1/4] Revise LP-0019 prize details and success criteria Updated the LP-0019 prize document to include detailed descriptions of the AI-powered tools, success criteria, and eligibility requirements for participants. --- prizes/LP-0019.md | 150 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 prizes/LP-0019.md diff --git a/prizes/LP-0019.md b/prizes/LP-0019.md new file mode 100644 index 0000000..624bc73 --- /dev/null +++ b/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. From 2b628a0ce5b9c7289d262f39ad5c921d8fd63081 Mon Sep 17 00:00:00 2001 From: serejandmyself Date: Fri, 15 May 2026 23:21:14 +0100 Subject: [PATCH 2/4] Update README.md --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 39f9913..d8bfa77 100644 --- a/README.md +++ b/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 From 9b1a0334a34b4ef8d849c38307884d0fe3d56fc6 Mon Sep 17 00:00:00 2001 From: serejandmyself Date: Fri, 15 May 2026 23:24:37 +0100 Subject: [PATCH 3/4] Create LP-0019.md --- solutions/LP-0019.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 solutions/LP-0019.md diff --git a/solutions/LP-0019.md b/solutions/LP-0019.md new file mode 100644 index 0000000..9207776 --- /dev/null +++ b/solutions/LP-0019.md @@ -0,0 +1,18 @@ +# Solution: LP-0018 — AI-Powered Logos Ecosystem Onboarding Toolkit + +**Team:** CitizenWeb3 + +## Repositories + +| Component | Repository | Branch | Live URL | +|---|---|---|---| +| AI Documentation Assistant | citizenweb3/ai-integrations | logos-onboarding-assistant | https://logos.staking.citizenweb3.com | +| AI Agent Node Skill | citizenweb3/ai-integrations | logos-node | https://www.npmjs.com/package/@citizenweb3/ai-integrations | +| Block Indexer + API | citizenweb3/chain-data-indexer | logos-indexer-v0.1.2 | https://github.com/citizenweb3/chain-data-indexer/tree/logos-indexer-v0.1.2#explorer-api | + +## 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. From 4c9384fa5cc72e689cae5cbe57f21c249d812c2f Mon Sep 17 00:00:00 2001 From: serejandmyself Date: Sat, 16 May 2026 00:19:04 +0100 Subject: [PATCH 4/4] Update LP-0019.md --- solutions/LP-0019.md | 155 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 148 insertions(+), 7 deletions(-) diff --git a/solutions/LP-0019.md b/solutions/LP-0019.md index 9207776..6e1535a 100644 --- a/solutions/LP-0019.md +++ b/solutions/LP-0019.md @@ -1,14 +1,151 @@ -# Solution: LP-0018 — AI-Powered Logos Ecosystem Onboarding Toolkit +# Solution: LP-0019 — AI-Powered Logos Ecosystem Onboarding Toolkit -**Team:** CitizenWeb3 +**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 | Branch | Live URL | -|---|---|---|---| -| AI Documentation Assistant | citizenweb3/ai-integrations | logos-onboarding-assistant | https://logos.staking.citizenweb3.com | -| AI Agent Node Skill | citizenweb3/ai-integrations | logos-node | https://www.npmjs.com/package/@citizenweb3/ai-integrations | -| Block Indexer + API | citizenweb3/chain-data-indexer | logos-indexer-v0.1.2 | https://github.com/citizenweb3/chain-data-indexer/tree/logos-indexer-v0.1.2#explorer-api | +| 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 @@ -16,3 +153,7 @@ The Logos testnet is also listed and accessible via [ValidatorInfo](https://vali 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. + + + +