CKB Dev Doctor
Lightweight developer diagnostics toolkit for CKB builders
1. Project Overview
CKB Dev Doctor is a lightweight open-source CLI diagnostics toolkit designed to help developers quickly validate their development environment when building applications on the Nervos CKB blockchain.
The project focuses on a single practical goal: reducing onboarding friction for new CKB builders by providing automated checks for the most common setup issues.
Many developers entering the CKB ecosystem must configure multiple components such as:
- CKB node or RPC endpoints
- Indexer services
- configuration files
- local development environment dependencies
Misconfiguration or connectivity issues frequently lead to debugging sessions that slow down development.
CKB Dev Doctor provides a simple command-line tool that performs automated diagnostics and generates clear reports about the readiness of a developer’s local environment.
The tool focuses on a narrow and realistic scope appropriate for the Spark Program:
- environment diagnostics
- RPC and indexer reachability checks
- configuration validation
- basic workflow readiness validation
- human-readable and JSON diagnostic reports
Target users:
- developers building on Nervos CKB
- hackathon participants and early-stage builders
- developers onboarding to the CKB ecosystem
- infrastructure teams verifying local development environments
The project is a developer tooling prototype, not infrastructure or protocol-level software.
2. Team Information
Milan Matejic, GitHub: @Mateja3m
Independent software engineer specializing in developer tooling, SDK development, and open-source infrastructure for Web3 ecosystems.
Relevant experience includes:
- More than 2 years contributing to the Intersect Member Area (Cardano ecosystem);
- 18 published npm packages focused on developer tooling and CLI utilities.
- Building tooling and SDKs across multiple blockchain ecosystems including:
- Cardano
- Solana
- Fuel
- Starknet
- Aptos
- Sui
Previous work includes:
- open-source CLI developer tools
- blockchain SDK integrations
- developer validation frameworks
- ecosystem onboarding utilities
The developer has experience delivering small, focused open-source tools with clear documentation and working demos, which aligns well with the goals of the Spark Program.
Repository for this project:
Published npm package:
https://www.npmjs.com/package/@idoa/dev-doctor-ckb
3. Technical Architecture and Interaction Flow
The project is intentionally designed as a simple CLI-based architecture with minimal complexity.
Core components:
CLI Layer
A TypeScript-based command-line interface that exposes diagnostic commands.
Diagnostics Engine
A modular system of checks validating different aspects of the developer environment.
Report Generator
Outputs results in both:
- human-readable text
- machine-readable JSON format
Optional Demo Application
A small browser-based UI demonstrating diagnostic results using mock data.
3.1 Developer Interaction Flow
- Developer installs the CLI package.
Example:
npm install -g @idoa/dev-doctor-ckb
- Developer runs the diagnostics command.
Example:
ckb-doctor report
- The CLI runs a series of checks including:
- local environment validation
- configuration file checks
- RPC endpoint connectivity
- indexer availability
- basic workflow readiness
- The CLI generates a report summarizing results.
Example output:
PASS Developer environment
PASS Configuration
PASS RPC endpoint
WARN Indexer endpoint
PASS Workflow readiness
- Developers can optionally export results as JSON for CI/CD pipelines.
3.2 Diagnostic Checks
The CLI will include several diagnostic modules:
Environment checks
- Node.js version compatibility
- required dependencies
Configuration checks
- presence and validity of configuration files
RPC checks
- connectivity to CKB RPC endpoints
Indexer checks
- reachability of indexer services
Workflow checks
- validation of basic development workflow readiness
4. Project Milestones (5 Weeks)
Milestone 1 (Weeks 1-2): Foundation and Core CLI
- finalize CLI architecture
- implement environment diagnostics
- implement RPC connectivity checks
- implement configuration validation
- establish project documentation structure
Deliverables:
- working CLI prototype
- open-source repository
- initial diagnostic checks
Milestone 2 (Weeks 3-4): Extended Diagnostics
- implement indexer availability checks
- implement workflow readiness validation
- add JSON report generation
- add basic test coverage
Deliverables:
- expanded diagnostic modules
- automated report output
- improved documentation
Milestone 3 (Week 5): Documentation and Demo
- prepare complete documentation
- finalize CLI usage examples
- provide a simple demo interface
- record demonstration video
Deliverables:
- public demo
- documentation
- example workflow demonstrations
5. Budget: $1,000
Total requested budget: $1,000
Payment structure:
- 50% in CKB
- 50% in USD-denominated stable asset (e.g. USDI equivalent)
Budget allocation:
Development work - $700
Documentation and demo - $200
Infrastructure and hosting - $100
6. Core Deliverables
6.1 Runnable CLI Tool
A publicly available CLI package capable of:
- running diagnostics for CKB developer environments
- generating human-readable reports
- exporting JSON diagnostic results
6.2 Open Source Repository
MIT Licensed repository including:
- full TypeScript source code
- CLI command implementation
- diagnostics modules
- tests
- configuration examples
Repository:
6.3 npm Package
Published package enabling easy installation:
https://www.npmjs.com/package/@idoa/dev-doctor-ckb
6.4 Documentation
Documentation will include:
- installation guide
- CLI command reference
- configuration examples
- developer onboarding instructions
6.5 Demo
The project will include:
- demo interface displaying diagnostic results
- example workflows
- short demonstration video
6.6 Known Limitations
The initial prototype will intentionally remain lightweight.
Limitations include:
- limited set of diagnostic checks
- no automated fixes for detected issues
- focused on development environments rather than production nodes
Future improvements may expand the number of diagnostics and integrations.
6.7 Actionable Diagnostics and Remediation Guidance
Each diagnostic check will include actionable remediation guidance in case of WARN or FAIL results.
Instead of only reporting status, the CLI will provide:
- possible causes of the issue
- step-by-step suggestions for resolving it
- clear commands or configuration fixes where applicable
Example:
FAIL RPC endpoint unreachable
Possible causes:
- CKB node is not running
- incorrect RPC port configuration
- network connectivity issue
Suggested fix:
- start the node using
ckb run - verify RPC port (default: 8114)
- check configuration file values
This significantly improves the tool’s practical value for onboarding developers.
Remediation guidance will be statically defined within the tool in English, with optional Chinese translations included in the documentation and structured output.
The AI-assisted mode does not require any external API integration. It provides structured JSON output and a prompt template, allowing developers to use their preferred AI tools for further assistance.
6.8 AI-Friendly Output Mode
The CLI will include an optional AI-oriented output mode:
This mode will output:
- structured JSON diagnostics
- a prebuilt prompt template for large language models
Example output structure:
{
"summary": { "pass": 4, "warn": 1, "fail": 0 },
"checks": [...],
"prompt": "You are a CKB expert. Analyze this diagnostic report and provide step-by-step fixes."
}
7. Relevance to the CKB Ecosystem
CKB Dev Doctor improves the developer experience within the Nervos ecosystem by providing a simple tool to diagnose common setup issues.
Benefits for the ecosystem:
- easier onboarding for new developers
- faster debugging of development environments
- standardized diagnostics for CKB tooling
- reusable infrastructure for future developer tools
By reducing friction in the setup process, the project contributes to a smoother development experience for builders working with CKB.
8. How to Verify
The project includes a reproducible verification process allowing both the committee and the community to validate that the tool works as intended.
Verification steps:
Step 1 – Install the CLI
npm install -g @idoa/dev-doctor-ckb
or run directly using npx:
npx @idoa/dev-doctor-ckb report
Step 2 – Prepare a simple test configuration
Example configuration file:
ckb-doctor.config.json
Example contents:
{
“rpc”: “http://localhost:8114”,
“indexer”: “http://localhost:8116”
}
Step 3 – Run diagnostics
Run the main diagnostic command:
ckb-doctor report
Expected output example:
PASS Developer environment
PASS Configuration
PASS RPC endpoint
WARN Indexer endpoint
PASS Workflow readiness
Step 4 – Verify JSON report output
ckb-doctor report --json
Expected JSON structure:
{
“summary”: {
“pass”: 4,
“warn”: 1,
“fail”: 0
}
}
Verification success criteria:
- CLI executes without runtime errors
- environment diagnostics run successfully
- RPC and indexer checks produce expected results
- JSON report format is generated correctly
The repository also includes tests and example configurations for reproducible verification.
9. Current State vs Funded Work
The project currently includes a working proof-of-concept CLI prototype.
To clearly define the development scope, the current and final diagnostic capabilities are listed below.
9.1 Current State (Implemented Diagnostics)
The current prototype supports a minimal but functional set of diagnostics:
Environment Check
Checks if Node.js ≥ 18 is installed.
PASS: version ≥ 18
FAIL: missing or unsupported version
Configuration Check
Validates presence and format of configuration file.
PASS: file exists and valid JSON
FAIL: missing or invalid configuration
RPC Connectivity Check
Tests reachability of the configured CKB RPC endpoint.
PASS: HTTP 200 response
FAIL: endpoint unreachable
Indexer Connectivity Check
Tests reachability of indexer endpoint.
PASS: endpoint responds
WARN: unexpected response
FAIL: endpoint unreachable
Workflow Readiness Check
Validates that CLI and configuration load successfully.
PASS: CLI executes and config loads
FAIL: execution or loading fails
9.2 Final State at Project Completion (Funded Work)
The funded work extends the prototype into a more complete CKB-focused diagnostic tool.
Each diagnostic will include:
- clear pass/fail logic
- explanation of failure causes
- actionable remediation guidance
- suggested commands or configuration fixes
Expanded diagnostics include:
CKB RPC Capability Check
Validates required RPC methods:
- get_tip_header
- get_block
- get_transaction
PASS: all methods respond
FAIL: missing or failing methods
Indexer Data Consistency Check
Validates synchronization between RPC and indexer.
PASS: data consistent
WARN: indexer lag detected
FAIL: inconsistent or unavailable
CKB Transaction Query Check
Tests ability to query transactions via RPC.
PASS: valid response
FAIL: query error
Cell Model Interaction Check
Validates basic cell interaction logic.
PASS: cell data parsed correctly
FAIL: invalid or failed query
Developer Workflow Simulation
Simulates a minimal end-to-end developer flow.
PASS: all steps succeed
FAIL: any step fails
Remediation Guidance (New Capability)
Each diagnostic will provide actionable remediation guidance.
Example:
FAIL RPC endpoint unreachable
Possible causes:
- node not running
- incorrect RPC port
- network issue
Suggested fix:
- run
ckb run - verify RPC port (default 8114)
- check configuration
This transforms the tool from a passive diagnostic into an active onboarding assistant for developers.
10. CKB-Specific Relevance
While some diagnostics such as Node.js version checks are generic, the tool is specifically designed to address the typical development workflow of the CKB ecosystem.
CKB development environments typically involve several components that must work together correctly:
- CKB node or RPC endpoint
- Indexer service
- transaction and cell interaction tools
- configuration files for development frameworks
The tool includes checks specifically targeting the CKB environment, including:
- validation of CKB RPC endpoint availability
- verification of indexer service connectivity
- configuration validation for CKB development setup
- workflow readiness checks related to typical CKB development flows
The goal is not to replace existing infrastructure, but to provide a lightweight diagnostics layer for developers onboarding into the CKB ecosystem.
This makes the tool particularly useful for:
- hackathon participants
- early-stage builders
- developers setting up local development environments for the first time
11. Web5 Alignment
The project aligns with Web5 principles by focusing on developer empowerment and decentralized infrastructure usability.
Web5 emphasizes user-controlled systems, decentralized identity, and open infrastructure that developers can easily build upon.
CKB Dev Doctor contributes to this vision by:
- improving accessibility of decentralized infrastructure
- reducing friction for developers interacting with CKB nodes and services
- enabling easier onboarding into the CKB ecosystem
- providing open-source tooling that can be reused and extended by the community
Rather than adding additional centralized services, the tool helps developers interact directly with decentralized CKB infrastructure in a more reliable way.
This aligns with the broader Web5 philosophy of enabling open, developer-driven ecosystems.
12. AI-Assisted Developer Experience
The project introduces an AI-friendly diagnostics layer to support modern development workflows.
In addition to standard CLI output, the tool will provide:
- structured JSON reports for machine parsing
- an optional
-aimode combining diagnostics with a prompt template
This allows developers to:
- quickly understand issues
- use AI tools for guided debugging
- reduce time spent on manual troubleshooting
Rather than replacing documentation, this feature enhances accessibility by integrating diagnostics with AI-assisted problem solving.
This approach aligns with current trends in developer experience and improves onboarding efficiency for new CKB builders.
CKB Dev Doctor
面向 CKB 开发者的轻量级开发环境诊断工具
1. 项目概述
CKB Dev Doctor 是一个轻量级开源 CLI 诊断工具，旨在帮助开发者在 Nervos CKB 区块链上构建应用时，快速验证其开发环境是否配置正确。
该项目的核心目标是：通过自动化检测常见环境问题，降低新开发者的上手门槛。
在进入 CKB 生态时，开发者通常需要配置多个组件：
- CKB 节点或 RPC 端点
- Indexer 服务
- 配置文件
- 本地开发依赖
配置错误或连接问题常常导致开发者花费大量时间排查问题，从而降低开发效率。
CKB Dev Doctor 提供一个简单的命令行工具，用于自动执行诊断并生成清晰的报告，帮助开发者判断其环境是否准备就绪。
工具范围清晰且符合 Spark Program 要求：
- 开发环境诊断
- RPC 和 Indexer 连通性检查
- 配置验证
- 基础开发流程检测
- 人类可读报告 + JSON 报告
目标用户：
- CKB 开发者
- Hackathon 参与者
- 新入门开发者
- 需要验证开发环境的团队
该项目属于开发者工具原型，而非基础设施或协议级项目。
6.7 可执行诊断与修复建议
每个诊断在 WARN 或 FAIL 时都会提供可执行的修复建议。
不仅显示状态，还会提供：
- 问题可能原因
- 具体解决步骤
- 对应命令或配置修复方式
示例：
FAIL RPC endpoint unreachable
可能原因：
- CKB 节点未运行
- RPC 端口配置错误
- 网络连接问题
建议修复：
- 运行
ckb run - 检查 RPC 端口（默认 8114）
- 检查配置文件
该机制显著提升工具在开发者 onboarding 过程中的实用价值。
修复建议将以英文静态定义，同时通过文档和结构化输出提供可选中文支持。
AI 模式不依赖任何外部 API，仅提供结构化 JSON 和提示模板，供开发者使用任意 AI 工具进行分析。
6.8 AI 友好输出模式
CLI 提供可选 AI 模式：
输出内容包括：
- 结构化 JSON 诊断结果
- 预定义 prompt 模板
示例：
{
“summary”: { “pass”: 4, “warn”: 1, “fail”: 0 },
“checks”: […],
“prompt”: “You are a CKB expert. Analyze this diagnostic report and provide step-by-step fixes.”
}
9. 当前状态与资助范围
当前项目已具备可运行的 CLI 原型。
资助将用于扩展诊断能力并增加 CKB 专属检测逻辑。
9.1 当前状态
当前支持基础诊断：
- Node.js 环境检测
- 配置文件检测
- RPC 连通性
- Indexer 连通性
- 基础工作流程验证
9.2 最终交付（资助后）
新增 CKB 专属诊断：
- RPC 方法能力检测
- Indexer 数据一致性验证
- 交易查询检测
- Cell 模型交互验证
- 开发流程模拟
每项检测均包含：
- 明确 PASS/FAIL 逻辑
- 问题原因说明
- 可执行修复建议
修复建议能力
每个诊断都会提供清晰的修复路径。
示例：
FAIL RPC endpoint unreachable
可能原因：
- 节点未运行
- 端口错误
- 网络问题
建议修复：
- 运行
ckb run - 检查端口（默认 8114）
- 检查配置
该能力将工具从简单检测提升为开发者辅助工具。
12. AI 辅助开发体验
该项目支持 AI 友好的开发体验：
- 提供结构化 JSON 输出
- 提供 prompt 模板
- 支持
-ai模式
开发者可以：
- 快速理解问题
- 使用 AI 获取解决方案
- 减少排错时间
该方式不会替代文档，而是增强开发体验。