Spark Program | CKB Developer Onboarding Guide

DAOs & Funding Spark Program
, ,
1

CKB Developer Onboarding Guide

Lightweight onboarding and developer setup guide for CKB builders

1. Project Overview

CKB Developer Onboarding Guide is a structured, documentation-first onboarding resource designed to help developers successfully set up and start building on the Nervos CKB blockchain from zero.

The project focuses on reducing onboarding friction by providing a clear, step-by-step guide covering environment setup, configuration, first interactions, and troubleshooting.

Many developers entering the CKB ecosystem must configure multiple components such as:

  • Node.js and development tools
  • CKB node
  • RPC endpoints
  • Indexer services
  • configuration files

Misconfiguration or missing dependencies frequently lead to confusion and slow onboarding.

Unlike CLI-based tools, this guide is immediately accessible without requiring any pre-installed tooling, directly addressing the bootstrapping limitation.

The project focuses on:

  • step-by-step onboarding
  • environment setup guidance
  • RPC and indexer configuration
  • troubleshooting and remediation
  • first working developer workflow
  • AI-assisted debugging usage

Target users:

  • new developers onboarding to CKB
  • hackathon participants
  • early-stage builders

The project is a documentation and onboarding resource, not a software tool.

A successful onboarding is defined as the developer being able to execute a valid RPC request and receive a correct response from the CKB network.

This guide does not replace official documentation, but provides a structured, beginner-first path that consolidates fragmented onboarding steps.

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
  • Experience building tooling across Cardano, Solana, Fuel, Starknet, Aptos, and Sui

Previous work includes:

  • developer onboarding tooling
  • validation frameworks
  • SDK integrations
  • CLI developer tools

This background directly supports the creation of structured onboarding and troubleshooting content.

3. Technical Architecture and Interaction Flow

The project is designed as a documentation-first system, not a CLI tool.

Core components:

Documentation Structure

A structured onboarding guide organized into logical modules.

Content Modules

Step-by-step instructions, examples, and troubleshooting scenarios.

Troubleshooting Matrix

A structured mapping of issues → causes → solutions.

AI-Assisted Layer

Optional structured prompts and examples for AI-assisted debugging.

3.1 Developer Interaction Flow

  1. Developer accesses the onboarding guide.
  2. Follows step-by-step setup instructions.
  3. Configures environment (Node.js, CKB node, RPC, indexer).
  4. Executes first working interaction (RPC call or query).
  5. Uses troubleshooting sections if issues occur.
  6. Optionally uses AI-assisted prompts for debugging.

3.2 Core Modules

The guide will include:

Prerequisites

  • system requirements
  • Node.js installation
  • required tools

Environment Setup

  • installing dependencies
  • verifying environment

CKB Node Setup

  • installing and running node
  • verifying node status

RPC and Indexer Setup

  • configuration steps
  • connectivity validation

Configuration Setup

  • example config files
  • validation steps

First Developer Workflow

  • first RPC call
  • querying data
  • basic interaction with CKB

Common Errors and Remediation

  • categorized issues
  • causes and fixes

Troubleshooting Matrix

  • issue → cause → solution

AI-Assisted Debugging

  • structured prompts
  • how to use AI tools effectively

Quick Start Path

  • minimal steps to first success without local node
  • use of public RPC endpoint
  • copy-paste commands
  • expected output examples

CKB Mental Model

  • high-level architecture overview (node, RPC, indexer)
  • explanation of how components interact
  • basic explanation of the cell model

Common Misconceptions

  • RPC working does not mean indexer is working
  • node sync state affects query results
  • incorrect network configuration leads to silent failures

4. Project Milestones (5 Weeks)

Milestone 1 (Weeks 1-2)

  • define structure
  • create prerequisites and setup sections
  • draft node and RPC setup

Deliverables:

  • initial documentation structure
  • environment setup guide

Milestone 2 (Weeks 3-4)

  • develop troubleshooting sections
  • create remediation content
  • build first workflow guide
  • add AI-assisted debugging section

Deliverables:

  • troubleshooting matrix
  • remediation guide
  • workflow examples

Milestone 3 (Week 5)

  • finalize documentation
  • translate to Chinese
  • publish repository

Deliverables:

  • full guide (EN + CN)
  • public repository

5. Budget: $1,000

Total requested budget: $1,000

Payment structure:

  • 50% in CKB
  • 50% in USD-denominated stable asset (e.g. USDI equivalent)

Allocation:

  • research and writing - $700
  • bilingual translation - $200
  • docs and publishing - $100

6. Core Deliverables

6.1 Documentation Repository

A public GitHub repository containing:

  • full onboarding guide
  • structured modules
  • troubleshooting content

6.2 Bilingual Guide

  • English version
  • Chinese translation

6.3 Troubleshooting Matrix

  • structured issue mapping
  • quick lookup format

6.4 Example Configurations

  • ready-to-use examples
  • validation steps

6.5 Known Limitations

  • focused on onboarding, not advanced topics
  • does not replace full documentation
  • no automation tools included

6.6 Remediation Guidance

Each issue includes:

  • explanation of cause
  • step-by-step fix
  • example commands with expected outputs

Example:

FAIL RPC endpoint unreachable

Possible causes:

  • node not running
  • incorrect port
  • network issue

Suggested fix:

  • run ckb run
  • verify port (8114)
  • check configuration

6.7 AI-Friendly Support

The guide includes:

  • structured prompts
  • troubleshooting examples
  • AI usage instructions

No external AI integration is required.

7. Relevance to the CKB Ecosystem

This project improves onboarding by:

  • reducing setup friction
  • providing structured guidance
  • enabling faster first success
  • supporting AI-assisted workflows

The guide reduces trial-and-error during onboarding and provides deterministic steps toward a successful initial setup.

8. How to Verify

The deliverables can be verified using the following criteria:

  • All commands in the Quick Start Path can be executed on the CKB testnet and produce the outputs described in the guide

  • A developer with no prior CKB experience can follow the guide and successfully perform a first RPC call

  • Each entry in the Troubleshooting Matrix includes:

    • root cause
    • fix steps
    • reproducible commands

  • Configuration examples (RPC, indexer) are tested and confirmed to work

  • The guide is publicly accessible and structured according to the defined modules

9. Current State vs Funded Work

Current State

  • Prerequisites Module
    High-level outline defined; installation steps and commands not yet documented or validated

  • Quick Start Path
    Flow structure defined; commands identified but not tested on CKB testnet

  • Troubleshooting Matrix
    Common issue categories identified; no documented solutions or reproducible examples

  • Common Misconceptions
    Key topics identified; explanations and examples not yet written

  • Configuration Setup (RPC, Indexer)
    Structure planned; configuration examples not yet validated in real environment

Final State at Project Completion

  • Prerequisites Module
    Complete setup guide including:

    • verified installation steps
    • tested commands
    • expected outputs for each step

  • Quick Start Path
    Step-by-step onboarding flow where:

    • all commands are tested on CKB testnet
    • expected outputs are documented
    • a developer with no prior CKB experience can complete their first RPC call within 30 minutes

  • Troubleshooting Matrix
    Covers common onboarding issues across key categories:

    • root cause explanation
    • step-by-step resolution
    • reproducible commands
    • expected outputs

  • Common Misconceptions
    Documented explanations for common developer mistakes, including:

    • incorrect assumptions
    • why they occur
    • correct approach with examples

  • Configuration Setup (RPC, Indexer)
    Fully validated configuration examples including:

    • working RPC endpoints
    • indexer setup
    • tested configuration files
    • example requests and responses

10. CKB-Specific Relevance

The guide focuses on:

  • CKB node setup
  • RPC interaction
  • indexer usage
  • cell model basics
  • development workflow

11. Web5 Alignment

Supports:

  • open infrastructure
  • developer accessibility
  • decentralized ecosystem growth

12. AI-Assisted Developer Experience

The guide enhances AI usage by:

  • providing structured context
  • enabling better prompts
  • improving troubleshooting accuracy

CKB 开发者入门指南

面向 CKB 开发者的轻量级入门与环境搭建指南

1. 项目概述

CKB 开发者入门指南 是一个以文档为核心的结构化入门资源，旨在帮助开发者从零开始完成 Nervos CKB 区块链的环境搭建并顺利开始开发。

该项目通过提供清晰的分步骤指导，降低开发者在环境配置、初始交互和问题排查过程中的复杂性。

进入 CKB 生态的开发者通常需要配置多个组件，例如：

  • Node.js 和开发工具
  • CKB 节点
  • RPC 端点
  • Indexer 服务
  • 配置文件

配置错误或依赖缺失通常会导致困惑并延缓上手过程。

与 CLI 工具不同，该指南无需任何预安装环境即可访问，从根本上解决了启动依赖（bootstrapping）问题。

本项目重点包括：

  • 分步骤入门流程
  • 环境配置指导
  • RPC 与 Indexer 配置
  • 故障排查与修复
  • 第一个可运行的开发流程
  • AI 辅助调试使用方法

目标用户：

  • 新加入 CKB 的开发者
  • 黑客松参与者
  • 早期阶段构建者

本项目是一个文档与入门资源，而非软件工具。

成功的入门定义为：开发者能够执行一个有效的 RPC 请求，并从 CKB 网络获得正确响应。

本指南不会替代官方文档，而是提供一个面向初学者的结构化路径，将分散的信息整合为统一的入门流程。

2. 团队信息

Milan Matejic，GitHub: @Mateja3m

独立软件工程师，专注于开发者工具、SDK 开发以及 Web3 生态的开源基础设施。

相关经验包括：

  • 在 Intersect Member Area（Cardano 生态）贡献超过 2 年
  • 发布了 18 个 npm 包，专注于开发者工具和 CLI 工具
  • 在 Cardano、Solana、Fuel、Starknet、Aptos 和 Sui 等生态中开发工具

过往工作包括：

  • 开发者入门工具
  • 验证框架
  • SDK 集成
  • CLI 开发工具

这些经验直接支持结构化入门与故障排查内容的构建。

3. 技术结构与交互流程

本项目采用文档优先（documentation-first）架构，而非 CLI 工具。

核心组件：

文档结构

按逻辑模块组织的结构化入门指南

内容模块

包含分步骤说明、示例和故障排查场景

故障排查矩阵

问题 → 原因 → 解决方案 的结构化映射

AI 辅助层

提供结构化提示与 AI 调试示例

3.1 开发者交互流程

  1. 开发者访问入门指南
  2. 按步骤完成环境配置
  3. 配置环境（Node.js、CKB 节点、RPC、Indexer）
  4. 执行第一个成功的交互（RPC 请求或查询）
  5. 出现问题时使用排查指南
  6. 可选使用 AI 提示进行调试

3.2 核心模块

指南将包括：

前置条件

  • 系统要求
  • Node.js 安装
  • 必需工具

环境配置

  • 安装依赖
  • 验证环境

CKB 节点配置

  • 节点安装与运行
  • 状态验证

RPC 与 Indexer 配置

  • 配置步骤
  • 连通性验证

配置文件设置

  • 示例配置
  • 验证步骤

第一个开发流程

  • 第一个 RPC 请求
  • 数据查询
  • 基础交互

常见错误与修复

  • 分类问题
  • 原因与解决方法

故障排查矩阵

  • 问题 → 原因 → 解决方案

AI 辅助调试

  • 结构化提示
  • AI 使用方法

快速启动路径

  • 无需本地节点的最小步骤
  • 使用公共 RPC
  • 可复制粘贴的命令
  • 预期输出示例

CKB 心智模型

  • 高层架构说明（节点、RPC、Indexer）
  • 组件交互方式
  • Cell 模型基础说明

常见误区

  • RPC 正常不代表 Indexer 正常
  • 节点同步状态影响查询结果
  • 错误网络配置会导致静默失败

4. 项目里程碑（5 周）

里程碑 1（第 1–2 周）

  • 定义结构
  • 编写前置条件与环境配置
  • 初步节点与 RPC 文档

交付内容：

  • 初始文档结构
  • 环境配置指南

里程碑 2（第 3–4 周）

  • 完成故障排查模块
  • 编写修复指南
  • 完成首个开发流程
  • 添加 AI 调试部分

交付内容：

  • 故障排查矩阵
  • 修复指南
  • 工作流程示例

里程碑 3（第 5 周）

  • 完成文档
  • 翻译为中文
  • 发布仓库

交付内容：

  • 完整指南（中英文）
  • 公共仓库

5. 预算：$1,000

总预算：$1,000

支付方式：

  • 50% CKB
  • 50% 稳定资产（如 USDI 等）

预算分配：

  • 研究与撰写：$700
  • 双语翻译：$200
  • 文档整理与发布：$100

6. 核心交付

6.1 文档仓库

包含：

  • 完整指南
  • 模块结构
  • 故障排查内容

6.2 双语指南

  • 英文版本
  • 中文版本

6.3 故障排查矩阵

  • 结构化问题映射
  • 快速查询

6.4 示例配置

  • 可直接使用的配置
  • 验证步骤

6.5 已知限制

  • 仅聚焦入门，不覆盖高级内容
  • 不替代官方文档
  • 不包含自动化工具

6.6 修复指导

每个问题包含：

  • 原因说明
  • 分步骤解决方法
  • 带预期输出的命令

示例：

RPC 端点不可达

可能原因：

  • 节点未运行
  • 端口错误
  • 网络问题

解决方法：

  • 运行 ckb run
  • 检查端口（8114）
  • 检查配置

6.7 AI 支持

包括：

  • 结构化提示
  • 故障排查示例
  • AI 使用方法

无需集成外部 AI

7. 与 CKB 生态的相关性

本项目通过以下方式改进入门体验：

  • 降低配置难度
  • 提供结构化指导
  • 加快首次成功
  • 支持 AI 调试流程

该指南减少试错过程，并提供确定性的入门路径。

8. 验证方式

交付成果可通过以下标准进行验证：

  • 快速入门路径（Quick Start Path）中的所有命令均可在 CKB 测试网上执行，并产生与文档描述一致的输出

  • 无任何 CKB 经验的开发者可以按照指南成功完成首次 RPC 调用

  • 故障排查矩阵（Troubleshooting Matrix）中的每个条目均包含：

    • 根本原因说明
    • 修复步骤
    • 可复现的命令

  • 配置示例（RPC、Indexer）已测试并确认可正常运行

  • 指南已公开发布，并按照既定模块结构组织

9. 当前状态与资助内容

当前状态

  • 前置条件模块（Prerequisites Module）
    已定义高层结构；安装步骤和相关命令尚未编写或验证

  • 快速入门路径（Quick Start Path）
    流程结构已确定；相关命令已识别，但尚未在 CKB 测试网上验证

  • 故障排查矩阵（Troubleshooting Matrix）
    常见问题类别已识别；尚未提供解决方案或可复现示例

  • 常见误区（Common Misconceptions）
    关键主题已确定；解释和示例尚未编写

  • 配置设置（RPC、Indexer）
    结构已规划；配置示例尚未在真实环境中验证

项目完成时的最终状态

  • 前置条件模块（Prerequisites Module）
    完整的环境搭建指南，包括：

    • 已验证的安装步骤
    • 已测试的命令
    • 每一步的预期输出

  • 快速入门路径（Quick Start Path）
    分步骤的上手流程，包括：

    • 所有命令已在 CKB 测试网上验证
    • 所有步骤均提供预期输出说明
    • 无任何 CKB 经验的开发者可在 30 分钟内完成首次 RPC 调用

  • 故障排查矩阵（Troubleshooting Matrix）
    覆盖关键类别中的常见上手问题，包括：

    • 问题根因说明
    • 分步骤解决方案
    • 可复现的命令示例
    • 预期输出

  • 常见误区（Common Misconceptions）
    针对开发者常见错误提供说明，包括：

    • 错误认知
    • 产生原因
    • 正确方法及示例

  • 配置设置（RPC、Indexer）
    完整验证的配置示例，包括：

    • 可用的 RPC 端点
    • indexer 配置
    • 已测试的配置文件
    • 示例请求与响应

10. CKB 相关性

重点包括：

  • 节点配置
  • RPC 使用
  • Indexer 使用
  • Cell 模型
  • 开发流程

11. Web5 对齐

支持：

  • 开放基础设施
  • 开发者可访问性
  • 去中心化生态增长

12. AI 开发体验

通过以下方式增强 AI 使用：

  • 提供结构化上下文
  • 提供更优提示
  • 提高调试准确性

3 Likes
CKB Ecosystem Biweekly Update
Spark Program Q2 2026: What the Ecosystem Is Building
2

Hi @Mateja3m,

Glad to see your new proposal. The content direction looks good, and the module design in Section 3.2 shows good research (Quick Start Path with public RPC, Common Misconceptions, Troubleshooting Matrix, etc.).

Before bringing it to the committee, I’d suggest improving Sections 8 and 9 using the same approach that worked well in your previous proposal.

Section 9 (Current State vs Funded Work)

Right now it reads: “research completed, structure defined” vs “full guide creation.” This is too general for the committee to evaluate the scope.

You already have a detailed module list in Section 3.2. I’d suggest restructuring Section 9 around those modules, for example:

Current state:

  • Prerequisites module: outline completed, content not yet written
  • Quick Start Path: structure defined, commands not yet tested
  • Troubleshooting Matrix: issue categories identified, solutions not yet drafted
  • etc…

Final state at project closure:

  • Prerequisites module: complete guide with verified commands and expected outputs
  • Quick Start Path: a developer with no CKB experience can complete first RPC call within 30 minutes following the guide
  • Troubleshooting Matrix: covers X categories, each with cause/solution/example commands
  • …

This way the committee can see exactly what each module delivers and what “done” looks like.

Section 8 (How to Verify)

The current four lines are goals, not verification steps. For a documentation project, verification could focus on the deliverables themselves being checkable, for example:

  • Every command in the Quick Start Path can be executed against CKB testnet and produces the output documented in the guide
  • Every entry in the Troubleshooting Matrix includes cause, fix steps, and example commands that are reproducible
  • etc…

These two changes will make the proposal much easier for the committee to evaluate.

Looking forward to your revision!

很高兴看到新提案。内容方向很好，3.2 节的模块设计能看出做了认真的调研（Quick Start Path 用公共 RPC、Common Misconceptions、Troubleshooting Matrix 等）。

在提交委员会评审之前，建议用上一版提案中效果很好的方法来改进第 8 节和第 9 节。

第 9 节（当前状态 vs 资助范围）

目前的写法是“research completed, structure defined”对“full guide creation”，太笼统了，委员会无法评估具体范围。

你在 3.2 节已经有了详细的模块列表。建议围绕这些模块来重组第 9 节，例如：

当前状态：

  • Prerequisites 模块：大纲已完成，内容未写
  • Quick Start Path：结构已定，命令未经测试
  • Troubleshooting Matrix：问题分类已确定，解决方案未起草
  • …

结项时的最终状态：

  • Prerequisites 模块：完整指南，命令已验证，附有预期输出
  • Quick Start Path：没有 CKB 经验的开发者照着走，能在30分钟内完成第一次 RPC 调用
  • Troubleshooting Matrix：覆盖 X 个问题类别，每个都有原因/解决方案/示例命令
  • …

这样委员会就能清楚看到每个模块交付什么、什么算完成。

第 8 节（验收方式）

目前的四句话是项目目标，不是验收步骤。文档项目的验收应该关注交付物本身是否可检查，例如：

  • Quick Start Path 中的每条命令都能在 CKB testnet 上实际执行，产出与文档描述一致的结果
  • Troubleshooting Matrix 中的每个条目都包含原因、修复步骤和可复现的示例命令
  • 。。。

这两个调整会让委员会评估起来顺畅很多。

期待您的修改！

3 Likes
3

Hi @zz_tovarishch

Thank you for the detailed and very helpful feedback.

I’ve updated Sections 8 and 9 to make the scope and deliverables more explicit and aligned with the module structure from Section 3.2.

Thanks again

Hi @zz_tovarishch，

感谢您提供的详细且非常有帮助的反馈。

我已经更新了第 8 节和第 9 节，使项目范围和交付内容更加清晰，并与第 3.2 节的模块结构保持一致。

再次感谢

3 Likes
4

Hi @Mateja3m ,

Thank you for the updates to Sections 8 and 9. Before moving into formal committee review, there are two follow-up questions we’d like you to address:

  1. CKB development experience

For documentation projects, first-hand knowledge of real development workflows is critical to ensuring the guide’s accuracy and usefulness. Therefore the committee would like to know whether you have practical development experience on CKB. If your CKB experience is limited, please state that candidly — we are willing to share relevant experience with you.

  1. Confirmation of content scope

As a supplement to the first point, the current module list focuses on environment setup, node/RPC/Indexer configuration, and basic RPC calls. The committee would like to know whether the guide will also cover subsequent practical development topics, such as:

  • Contract development (for example, writing, compiling, and deploying a simple on-chain script)
  • CCC SDK integration (for example, using the CCC SDK to construct, sign, and submit transactions)
  • Configuration checks beyond basic connectivity (for example, verifying that the development environment fully meets the requirements for contract deployment)

If any part of this content is intentionally excluded from the current scope, please state that explicitly so the committee can assess whether the guidelines cover enough to support a meaningful onboarding experience.

Looking forward to your reply.

嗨 @Mateja3m ，

感谢你对第 8 和第 9 节的更新。在进入正式委员会评审之前，有两个跟进问题希望你能补充：

1. CKB 开发经验

对于文档类项目而言，对真实开发流程的第一手了解对确保指南的准确性和实用性至关重要。因此委员会希望能了解你是否具备 CKB 的实际开发经验，如果你的 CKB 经验有限，请坦诚说明，我们愿意与你分享相关经验。

2. 内容覆盖范围确认

作为第一点的补充，目前的模块列表聚焦于环境搭建、节点/RPC/Indexer 配置和基础 RPC 调用。委员会希望了解指南是否还会涵盖后续实际开发内容，比如：

  • 合约开发（例如编写、编译和部署一个简单的链上脚本）
  • CCC SDK 集成（例如使用 CCC SDK 进行交易构建、签名和提交）
  • 超越基础连通性的配置检查（例如验证开发环境是否完全具备合约部署条件）

如果其中部分内容有意不在本次范围内，请明确说明，以便委员会评估指南的覆盖面是否足以支撑一个有意义的入门体验。

期待你的回复。

Best regards，
xingtian
On behalf of the Spark Program Committee

2 Likes
5

Hi @xingtianchunyan

Thank you for the thoughtful follow-up questions.

  1. CKB Development Experience

My direct hands-on experience with CKB is currently at an early stage, and I want to state that transparently.

However, my background is focused on developer onboarding, diagnostics, and tooling across multiple ecosystems (Cardano, Solana, Aptos, Sui, Arbitrum, Flow etc.), where the main challenge is reducing onboarding friction and making first success deterministic.

For this project, I will approach the guide in a practical, validation-first way:

  • all commands and steps will be tested directly on CKB testnet
  • expected outputs will be verified and documented
  • common failure cases will be reproduced and included in the troubleshooting matrix

Additionally, the guide will be closely aligned with official CKB documentation and iteratively validated against real development workflows, ensuring accuracy despite my initial stage of direct CKB experience.

I’m also open to incorporating feedback and best practices from the CKB ecosystem to ensure accuracy.

  1. Confirmation of Content Scope

The current proposal is intentionally focused on onboarding and early-stage developer setup, not full application development.

Included in scope:

  • environment setup
  • node / RPC / indexer configuration
  • first working RPC interaction
  • troubleshooting and remediation
  • common misconceptions and configuration validation

Explicitly out of scope for this phase:

  • contract development (writing, compiling, deploying scripts)
  • CCC SDK integration
  • advanced deployment readiness validation beyond basic environment correctness

This scope is intentionally designed to address the highest-friction part of onboarding, which is environment setup and achieving the first successful interaction.

Based on experience across multiple ecosystems, this stage is where most developers drop off, and improving this step has the highest impact on developer adoption.

The goal of this guide is to reduce time-to-first-success and provide a reliable starting point for new developers.

Once a developer successfully reaches this stage, they can continue with official documentation or more advanced guides.

If needed, this project could be extended in a future phase to cover contract development and SDK usage.

Looking forward to your feedback.

Hi @xingtianchunyan

感谢您提出的这些深入且有价值的后续问题。

  1. CKB 开发经验

我目前在 CKB 上的直接实践经验仍处于早期阶段，这一点我希望坦诚说明。

不过，我的背景主要集中在多个区块链生态（Cardano、Solana、Aptos、Sui、Arbitrum、Flow 等）的开发者入门、诊断工具和开发者工具领域，其中核心问题始终是降低上手门槛，并让开发者能够以确定性的方式完成首次成功。

在本项目中，我将采用以实践验证为核心的方法来构建指南：

  • 所有命令和步骤都会在 CKB 测试网上进行实际验证
  • 所有预期输出都会被确认并记录
  • 常见失败场景会被复现并纳入故障排查矩阵

此外，该指南将严格对齐 CKB 官方文档，并基于真实开发流程进行迭代验证，从而在我当前 CKB 经验阶段的基础上依然保证内容的准确性。

我也非常愿意结合 CKB 社区的反馈和最佳实践，持续优化内容质量。

  1. 内容范围确认

当前提案刻意聚焦于开发者入门和早期环境搭建阶段，而不是完整的应用开发流程。

本阶段包含的内容：

  • 开发环境搭建
  • 节点 / RPC / Indexer 配置
  • 首次可用的 RPC 交互
  • 故障排查与修复指南
  • 常见误区与配置验证

本阶段明确不包含：

  • 合约开发（编写、编译、部署脚本）
  • CCC SDK 集成
  • 超出基础环境正确性验证范围的高级部署检查

该范围是有意设计的，重点解决开发者入门过程中摩擦最大的阶段，即环境搭建和首次成功交互。

根据我在多个生态中的经验，这一阶段是开发者最容易流失的环节，而优化这一过程对开发者增长具有最大影响。

本指南的目标是缩短“首次成功时间”（time-to-first-success），为新开发者提供一个可靠的起点。

一旦开发者完成这一阶段，他们可以继续使用官方文档或更高级的开发指南深入学习。

如有需要，该项目也可以在后续阶段扩展，涵盖合约开发和 SDK 使用等内容。

期待您的进一步反馈。

2 Likes
6

Hi @Mateja3m,

Thank you for giving the committee candid feedback.

Based on your latest feedback, the committee is willing to advance the proposal to the “approval” process and has provided an updated funding offer:

Funding offer: 100 USD (The price and quantity of CKB will be confirmed based on the price on the day you reply accepting the funding)

The main reason is: you have stated that the documents edited within the scope of Spark will only provide basic beginner guidance and will not include any subsequent specific project development assistance.

If you are willing to accept this US$100 grant, please reply to this post to confirm (for example: “I accept the US$100 grant offer”), and at the same time provide:
The CKB address that will receive the funds.

Weekly sync
We want to establish a regular weekly synchronization mechanism, with two options:

Text updates in this thread, posting progress at a fixed time each week, with committee responses and feedback.
A short video call. Please let us know your preference and convenient times.

Proposal Content Locked
After the proposal is approved, we will lock the current version of the proposal post to serve as the reference baseline for subsequent delivery acceptance. This is the standard procedure for all approved Spark projects. If adjustments are needed during development, they can be discussed and recorded during the weekly sync.

Once confirmed, we will immediately initiate the project setup process and proceed with the first disbursement according to Spark’s standard procedures.

Best regards,
Xingtian
Representative of the Spark Project Committee

Hi @Mateja3m，

感谢你给予委员会真实的反馈。

基于你最新的反馈，委员会愿意推进该提案进入“通过”流程，并给出一个更新后的资助报价：

资助报价：100 USD（CKB的价格和数量根据你回复接受资助的当天价格确认）

主要原因是：你已经申明在Spark范围内所编辑的文档内容仅会提供最基础的新手入门指导，而不包含任何后续的具体项目开发帮助。

如果你愿意接受这笔 100 USD 的资助，请在本帖回复确认（例如：“我接受 100 USD 的资助报价”），并同时提供：
接收资金的 CKB 地址。

每周同步
我们希望建立固定的周同步机制，有两种方式：

在本帖进行文字同步，每周固定时间更新进展，委员会回复反馈。
简短的视频通话。 请告知你的偏好和方便的时间。

提案内容锁定
提案获批后，我们会将当前版本的提案帖锁定，作为后续交付验收的参照基准。这是所有 Spark 获批项目的常规流程。如果开发过程中需要调整，可以在每周同步时沟通并记录。

确认后，我们将立即启动立项流程，并按 Spark 的标准机制推进首笔发放。

祝好，
行天
代表星火计划委员会

cc @zz_tovarishch , @Hanssen , @yixiu.ckbfans.bit

1 Like
7

Hi @xingtianchunyan

Thank you for the update and for advancing the proposal.

I accept the US$100 grant offer.

Here is my CKB address for receiving the funds:
ckb1qrgqep8saj8agswr30pls73hra28ry8jlnlc3ejzh3dl2ju7xxpjxqgqqykru82249nys8nqjppugzkhphat2ku5sv43ydw7

For the weekly sync, I prefer text updates in this thread on a fixed weekly schedule.

I have a question regarding the exact project start date.

Looking forward to starting the project.

Best regards,
Milan

你好 @xingtianchunyan

感谢更新并推进该提案。

我接受 100 美元的资助提议。

这是我用于接收资金的 CKB 地址：
ckb1qrgqep8saj8agswr30pls73hra28ry8jlnlc3ejzh3dl2ju7xxpjxqgqqykru82249nys8nqjppugzkhphat2ku5sv43ydw7

关于每周同步，我更倾向于在此线程中进行固定时间的文本更新。

我有一个关于项目具体开始日期的问题.

期待开始该项目。

此致敬礼，
Milan

2 Likes
8

@Mateja3m

For the specific start date, it is generally considered to begin as soon as the proposal is approved.

You only need to state here which day(s) of the week you will provide updates.

If you need more time to prepare, you may also state here that you will postpone the release of the first week’s report (by up to one week).

对于具体的开始日期，一般情况下当提案通过即视为开始。

您只需在此声明每周几进行更新即可。

如果您需要更多准备，也可以在此声明延后（最多一周）发布首周的周报。

2 Likes
9

Hi @xingtianchunyan

Great, I will start working on the project today, there is no need for any delay.

Regarding the reporting day, I believe Sunday is the most suitable. Therefore, I will post a weekly update in this thread every Sunday, including detailed progress aligned with the defined project milestones.

你好 @xingtianchunyan

很好，我将从今天开始进行项目工作，无需任何延迟。

关于汇报时间，我认为星期日是最合适的。因此，我会在每周星期日于此线程中发布进度更新，并根据已确定的项目里程碑提供详细的进展情况。

3 Likes
10

Hi @Mateja3m ,

The multisig wallet for the CKB Developer Onboarding Guide project has been created and funded.

Project wallet multisig address:
ckb1qrg6n7rh4mfltcruh8zjkcdtjmgx7fg2u6yre3ls5fprmvyhdlyzzqtm0sq7c6stp7uek8xhyugy05xreqlf3kcn304e4

Based on the midpoint CKB/USD price on the day you accepted the proposal (0.001483 CKB/USD) and a funding split of 50% CKB + 50% USDI, a total of 33,715 CKB + 50 USDI were funded. The extra CKB is reserved to cover gas fees for project payments.

The first installment (10 USDI + 6,743 CKB, totaling 20%) has been issued:

  1. Transaction hash ( 10 USDI ) :
    0xd629582ce9447337d7341472667d1b72a4109facb08072eab5fef41489869f58

  2. Transaction hash ( 6,743 CKB equivalent to 10 USD ) :
    0xf4b0600801f42dccf8c7c654305c9d13899f4f00ceb46a231ffae2893f9e6738

Looking forward to your update

Best regards
xingtian
On behalf of the Spark Program Committee

Hi @Mateja3m ,

目前 CKB Developer Onboarding Guide 项目的多签钱包已经建立，并已经完成注资。

项目钱包多签地址：ckb1qrg6n7rh4mfltcruh8zjkcdtjmgx7fg2u6yre3ls5fprmvyhdlyzzqtm0sq7c6stp7uek8xhyugy05xreqlf3kcn304e4

根据你接受提案立项当天CKB/USD的中间价格（0.001483 CKB/USD）和50%CKB + 50%USDI 的资助金额比例，共计注资 33,715 CKB + 50 USDI 。多出的部分CKB是为项目打款准备的gas费。

首笔启动资金（10 USDI + 6,743 CKB ，共20%）已经发放：

  1. 交易哈希（10 USDI ）： 0xd629582ce9447337d7341472667d1b72a4109facb08072eab5fef41489869f58

  2. 交易哈希 （6,743 CKB 等值 10 USD）：
    0xf4b0600801f42dccf8c7c654305c9d13899f4f00ceb46a231ffae2893f9e6738

期待你的更新

祝好
行天
代表星火计划委员会

cc @zz_tovarishch , @yixiu.ckbfans.bit , @Hanssen

3 Likes
11

Hi @xingtianchunyan

Week 1 Milestone 1 Progress Report

Status

Week 1 of Milestone 1 has been completed.

This phase focused on establishing the documentation foundation for the CKB Developer Onboarding Guide and validating the earliest onboarding steps in a structured way. The work completed during this period aligns with the project goal of reducing onboarding friction, clarifying setup requirements, and making first success more deterministic for new developers.

Repository And Publication Status

A public GitHub repository has been established for the project:

The repository now contains the initial documentation structure, core Week 1 drafted content, and published validation materials that support later expansion into troubleshooting, remediation, and workflow guidance.

Work Completed

1. Documentation Structure Established

The repository structure for the onboarding guide has been created across all planned core modules. This provides a clear documentation architecture aligned with the project proposal.

Created modules include:

  • project overview

  • prerequisites

  • environment setup

  • quick start

  • CKB node setup

  • RPC setup

  • indexer setup

  • configuration setup

  • first developer workflow

  • common errors and remediation

  • troubleshooting matrix

  • AI-assisted debugging

  • CKB mental model

  • common misconceptions

This satisfies the Milestone 1 requirement to define the initial documentation structure.

2. Core Week 1 Sections Drafted

The following Week 1 sections were fully drafted:

These sections establish:

  • the project purpose

  • onboarding scope

  • prerequisites and local environment expectations

  • a validation-oriented documentation structure

This directly supports the Milestone 1 requirement to create the prerequisites and environment setup sections.

3. Remaining Modules Scaffolded

All later sections were created as structured placeholders rather than filled with unvalidated instructions. This preserves the full guide architecture while keeping unfinished content clearly separated from tested material.

4. Messaging Aligned With Project Positioning

The repository messaging was refined to match the core value of the project more clearly.

The guide is now positioned as:

  • a validated onboarding path

  • a documentation-first execution layer

  • a guide that does not replace official Nervos documentation

  • a resource focused on reducing setup failure, ambiguity, and trial-and-error

This is important because the project’s value is not in rewriting reference commands, but in making execution more reliable for new developers.

5. Documentation Consistency And Repository Hygiene Improved

A cleanup pass was completed to strengthen readability and maintainability:

  • markdown links were converted to relative links

  • the main documents were aligned around a consistent section structure

  • a .gitignore file was added for local artifacts and machine-specific noise

  • an MIT license was added for public repository clarity

These improvements make the repository more suitable for public consumption and future contribution.

Validation Work Completed

6. Validation Framework Added

A dedicated validation layer was created to support systematic testing of real onboarding behavior.

Published validation resources include:

This supports the project’s validation-first approach by creating a repeatable method for capturing:

  • commands tested

  • observed outputs

  • failure cases

  • beginner confusion points

  • possible root causes

  • notes for future troubleshooting and remediation content

7. Environment Validation Completed

Local environment validation was performed and consolidated into published findings:

The validation confirmed the availability of core development tools and also surfaced an early onboarding issue related to DNS / hostname resolution during a basic HTTPS connectivity check.

This is useful because it demonstrates that onboarding friction can occur before CKB-specific tooling is introduced, and that the final guide should address environment-level failures explicitly.

8. Initial CKB Validation Completed

Initial CKB-specific validation was also completed and consolidated into published findings:

This validation included:

  • installation of @offckb/cli

  • local node startup attempts

  • cleanup and repeatability checks

  • a first successful JSON-RPC interaction

  • observation of incorrect HTTP method behavior when RPC access is tested improperly

The most important result is that the project’s success condition was demonstrated during Week 1 validation:

A valid RPC request was executed and a correct response was returned from the CKB environment.

In addition, the validation surfaced several meaningful beginner friction points, including:

  • first-run startup behavior that initially appears to fail before recovering

  • missing-binary messaging that can be misread as a hard failure

  • warning-style logs that may be more alarming than necessary

  • local port ambiguity during node and RPC usage

  • confusion caused by testing RPC endpoints with the wrong HTTP method

9. Repeatability Confirmed

A repeat node startup pass was completed successfully after cleanup. This confirmed that:

  • the startup flow is reproducible

  • first-run binary download behavior is a one-time event

  • subsequent runs are cleaner and easier to interpret

This improves confidence in the validity of the onboarding flow and provides useful input for future troubleshooting guidance.

Outcome Against Week 1 Scope

Week 1 successfully delivered:

  • initial documentation structure

  • drafted prerequisites and environment setup sections

  • public repository setup

  • validation framework

  • real onboarding validation evidence

  • early documented findings for future troubleshooting and remediation work

Conclusion

Week 1 of Milestone 1 is complete.

The project now has a public repository, a structured documentation foundation, drafted core onboarding sections, and published validation findings based on real testing. This establishes a credible base for the next phase of work, where node setup, RPC setup, troubleshooting, remediation guidance, and first workflow content can be expanded with stronger validation coverage.

你好 @xingtianchunyan

第1周里程碑1进展报告

状态

里程碑1的第1周已完成。

本阶段的重点是为 CKB Developer Onboarding Guide 建立文档基础，并以结构化方式验证最早期的入门步骤。本阶段已完成的工作与项目目标保持一致，即降低入门摩擦、澄清环境配置要求，并让新开发者获得首次成功的过程更加可预测、更加确定。

仓库与发布状态

项目的公开 GitHub 仓库已建立：

该仓库目前已经包含初始文档结构、第1周核心草稿内容，以及已发布的验证材料，这些内容将支持后续扩展到故障排查、修复指导和开发流程说明。

已完成工作

1. 已建立文档结构

入门指南的仓库结构已经按照所有计划中的核心模块完成搭建。这为项目提供了一个清晰的文档架构，并与项目提案中的模块化设计保持一致。

已创建的模块包括：

  • 项目概览

  • 前置条件

  • 环境配置

  • 快速开始

  • CKB 节点配置

  • RPC 配置

  • Indexer 配置

  • 配置文件设置

  • 第一个开发者工作流

  • 常见错误与修复

  • 故障排查矩阵

  • AI 辅助调试

  • CKB 心智模型

  • 常见误区

这满足了里程碑1中“定义初始文档结构”的要求。

2. 已完成第1周核心章节草稿

以下第1周范围内的章节已完整起草：

这些章节建立了：

  • 项目目的

  • 入门范围

  • 前置条件与本地环境要求

  • 面向验证的文档结构

这直接支持了里程碑1中“创建前置条件与环境配置章节”的要求。

3. 其余模块已完成脚手架搭建

所有后续章节都以结构化占位内容的形式创建，而不是提前填入未经验证的说明。这样既保留了完整指南的整体架构，也确保未完成内容与已验证内容清晰区分。

4. 已将项目定位信息调整到位

仓库中的项目表述已被优化，以更清晰地体现项目的核心价值。

该指南当前被定位为：

  • 一个经过验证的入门路径

  • 一个文档优先的执行层

  • 一个不替代 Nervos 官方文档的指南

  • 一个专注于减少配置失败、歧义和反复试错的资源

这一点很重要，因为项目的价值不在于重写参考命令，而在于让新开发者的执行过程更加可靠。

5. 已提升文档一致性与仓库整洁度

已完成一次清理和统一工作，以提升可读性和可维护性：

  • Markdown 链接已转换为相对路径

  • 主要文档已统一为一致的章节结构

  • 已添加 .gitignore 文件，用于忽略本地产物和机器相关噪音文件

  • 已添加 MIT 许可证，提升公开仓库的清晰度

这些改进使仓库更适合公开使用，也更适合未来协作。

已完成的验证工作

6. 已建立验证框架

项目已建立专门的验证层，用于系统化测试真实的入门行为。

已发布的验证资源包括：

这一部分通过创建可重复的方法来支持项目的 validation-first 方法，包括记录：

  • 已测试的命令

  • 实际观察到的输出

  • 失败情况

  • 初学者的困惑点

  • 可能的根本原因

  • 可用于后续故障排查与修复内容的备注

7. 已完成环境验证

本地环境验证已完成，并整理为已发布的结论文件：

该验证确认了核心开发工具的可用性，同时也暴露出一个早期入门问题：在基础 HTTPS 连通性检查中出现了 DNS / 主机名解析相关问题。

这一点很有价值，因为它表明入门摩擦可能在引入 CKB 专用工具之前就已经出现，因此最终指南需要明确覆盖环境层面的失败情况。

8. 已完成初始 CKB 验证

初始 CKB 相关验证也已完成，并整理为已发布的结论文件：

本次验证包括：

  • 安装 @offckb/cli

  • 本地节点启动尝试

  • 清理与可重复性检查

  • 第一次成功的 JSON-RPC 交互

  • 观察在错误 HTTP 方法下访问 RPC 时的行为

其中最重要的结果是：项目定义的成功条件已经在第1周验证中得到证明：

已成功执行一次有效的 RPC 请求，并从 CKB 环境中获得正确响应。

此外，本次验证还暴露出若干对初学者非常重要的摩擦点，包括：

  • 首次启动行为在恢复前看起来像失败

  • 缺失二进制文件的提示容易被误读为硬错误

  • 警告风格日志可能显得比实际更严重

  • 节点与 RPC 使用中的本地端口歧义

  • 使用错误的 HTTP 方法测试 RPC 端点所造成的困惑

9. 已确认可重复性

在执行清理后，又成功完成了一次重复的节点启动验证。这确认了：

  • 启动流程是可重复的

  • 首次运行时的二进制下载行为属于一次性事件

  • 后续运行会更干净，也更容易理解

这提高了对该入门流程有效性的信心，也为未来的故障排查指导提供了有用输入。

与第1周范围的对应结果

第1周已成功交付：

  • 初始文档结构

  • 已起草的前置条件与环境配置章节

  • 公开仓库搭建

  • 验证框架

  • 真实的入门验证证据

  • 可用于后续故障排查与修复工作的早期结论

结论

里程碑1的第1周已完成。

项目目前已经具备公开仓库、结构化文档基础、已起草的核心入门章节，以及基于真实测试整理出的验证结论。这为下一阶段工作建立了可信基础，在下一阶段中，节点配置、RPC 配置、故障排查、修复指导以及第一个开发流程内容都可以在更强的验证覆盖下继续扩展。

2 Likes
CKB Ecosystem Biweekly Update
12

Hi @Mateja3m,

Great to see your first-week update.

A few additional notes here:

Funding is handled through Spark’s on-demand flexible application mechanism. If you have funding needs mid-term, you can apply after completing a project phase.

After the committee receives your application, it will enter the review stage, and once approved it will promptly issue the corresponding funds.

Best wishes,
Xingtian
On behalf of the Spark Project Committee

嗨 @Mateja3m，

很高兴看到你的首周更新。

在这里补充几句：

资金方面是按 Spark 的按需灵活申请机制进行的，如果你在中期有资金方面的需要可以在阶段性工作完成后提出申请。

委员会在收到你的申请后将进入审核阶段，审核通过后会将及时发放相应的预算。

祝好，
行天
代表星火计划委员会

1 Like
13

Hi @xingtianchunyan,

Thanks for the clarification.

Understood - I will submit a funding request after completing the milestone, with clear proof of progress. Once reviewed and approved, the funds will be issued.

I’ll continue working and posting weekly updates as planned.

Best regards,
Milan

Hi @xingtianchunyan,

感谢您的说明。

我已理解——在完成阶段性里程碑后，我会提交资金申请，并提供清晰的进展证明。申请经过审核并获批后，资金将会发放。

我会继续按计划推进项目，并每周发布进展更新。

此致，
Milan

3 Likes
14

Hi @xingtianchunyan, below you can find the progress report for Milestone 1, week 2

Week 2 Milestone 1 Progress Report

Status

Milestone 1 has been completed.

This phase focused on finishing the remaining Milestone 1 onboarding documents, replacing placeholder-only setup sections with validated guidance, and extending the validation evidence behind the local CKB node and RPC flow. The work completed during this period strengthens the project goal of reducing beginner ambiguity and making the path to first successful RPC interaction more explicit and repeatable.

Repository And Publication Status

The repository structure established in Week 1 remains in place, and the Week 2 work was completed in the local repository workspace.

During this run:

  • no GitHub push was performed

  • no pull request was opened

  • no git commit was created

  • no remote configuration was changed

This is important because the Week 2 work was intended to refine Milestone 1 content locally before any later publication or review step.

Work Completed

1. Remaining Milestone 1 Setup Sections Completed

The previously placeholder-only Milestone 1 setup sections were expanded into beginner-oriented, validation-first documentation.

Completed or substantially completed sections include:

  • 03 Quick Start

  • 04 CKB Node Setup

  • 05 RPC Setup

  • 07 Configuration Setup

These sections now provide:

  • a shortest validated path to first RPC success

  • explicit step-by-step node startup guidance

  • RPC request and response interpretation for beginners

  • minimal configuration awareness without speculative file-edit instructions

This directly supports the Milestone 1 requirement to help a developer reach first successful RPC interaction through a documentation-first onboarding flow.

2. Milestone 1 Navigation And Scope Messaging Refined

The top-level project messaging was updated so the repository no longer describes the completed Milestone 1 setup sections as placeholders.

Updated files include:

  • README.md

  • 00 Overview

  • 02 Environment Setup

These updates improved:

  • document sequencing

  • scope clarity

  • internal cross-references

  • the distinction between completed Milestone 1 content and later placeholder sections

3. Validation-First Boundaries Strengthened

The Week 2 documentation pass preserved the rule that the guide should not guess commands, paths, ports, or behaviors that were not validated locally.

As part of this cleanup:

  • validated commands were kept explicit

  • speculative configuration editing was not introduced

  • endpoint ambiguity was documented instead of hidden

  • later scope was left as placeholders rather than filled with weak guidance

This keeps the guide aligned with the project’s positioning as a complement to official Nervos documentation rather than a replacement for it.

4. Placeholder Milestone Labels Added

Later placeholder sections were updated so TODO: VALIDATE markers now include a milestone label where the planned sequencing is already clear.

Updated placeholder sections include:

  • 06 Indexer Setup: Milestone 2

  • 08 First Developer Workflow: Milestone 2

  • 09 Common Errors and Remediation: Milestone 2

  • 10 Troubleshooting Matrix: Milestone 2

  • 11 AI-Assisted Debugging: Milestone 3

  • 12 CKB Mental Model: Milestone 3

  • 13 Common Misconceptions: Milestone 3

This improves planning clarity by showing which unfinished sections belong to later milestones instead of leaving all later work under one undifferentiated validation marker.

Validation Work Completed

5. Environment Connectivity Validation Refined

The Week 1 connectivity failure around https://example.com was revisited and clarified through a more meaningful real-URL test.

Published findings updated in Week 2 include:

  • Environment Validation Findings

The updated validation now shows:

  • repeated example.com hostname resolution failure in the local environment

  • successful HTTPS header retrieval from https://google.com

  • evidence that target selection matters when using a simple connectivity check

This is useful because it prevents the guide from incorrectly treating one failed hostname test as proof that all network-dependent onboarding is blocked.

6. Node And RPC Validation Expanded Significantly

The local CKB node and RPC evidence base was expanded through multiple additional validation passes.

Published findings updated in Week 2 include:

  • CKB Node And RPC Validation Findings

The expanded validation covered:

  • repeated offckb node startup after initial installation

  • repeated successful JSON-RPC responses from localhost:8114

  • successful JSON-RPC responses from 127.0.0.1:28114

  • wrong-method behavior on both endpoints

  • HTTP 200 OK confirmation for JSON-RPC POST requests

  • local process inspection with lsof

  • custom --binary-path startup using the discovered local CKB binary

  • confirmation that the devnet path exists after initialization

This strengthens confidence that the Milestone 1 onboarding path is not a one-off success case.

7. Local Endpoint Relationship Clarified

Week 2 validation materially improved the explanation of local endpoint behavior.

The observed local evidence now shows:

  • ckb listening on port 8114

  • node listening on port 28114

  • valid JSON-RPC POST responses from both endpoints

This does not fully document the internal implementation details, but it is strong enough for beginner-facing onboarding guidance. It supports the practical explanation that 28114 behaves like a Node.js / OffCKB proxy layer while 8114 behaves like the underlying ckb RPC listener.

8. Binary Path And Devnet Path Validation Added

Week 2 also validated filesystem-level details that were previously only partially understood.

The local validation now confirms:

  • the installed CKB binary can be discovered at runtime rather than guessed

  • the binary version can be checked directly from that path

  • offckb node -b <actual-binary-path> works on the validation machine

  • the devnet directory appears after initialization and contains real configuration and data paths

This improves the quality of the configuration guidance while still avoiding unsafe or speculative edit instructions.

9. Milestone 1 Scope Boundaries Confirmed

Week 2 also confirmed that some sections should remain intentionally incomplete at the end of Milestone 1.

The validated scope decision is that Milestone 1 now covers:

  • prerequisites

  • environment setup

  • quick start

  • CKB node setup

  • RPC setup

  • minimal configuration awareness

The following remain intentionally outside the completed Milestone 1 scope:

  • indexer setup details

  • first full developer workflow

  • remediation and troubleshooting matrix content

  • AI-assisted debugging guidance

  • broader conceptual materials such as mental models and misconceptions

This keeps the milestone focused on onboarding and first success rather than expanding prematurely into later-phase documentation.

Outcome Against Week 2 Scope

Week 2 successfully delivered:

  • completed Milestone 1 setup documents for quick start, node setup, RPC setup, and configuration setup

  • stronger internal consistency across the main onboarding docs

  • updated validation findings based on repeat local testing

  • clearer explanation of local RPC endpoint behavior

  • milestone labels for later placeholder sections

  • a stronger basis for declaring Milestone 1 substantially complete

第2周里程碑1进展报告

状态

里程碑1已完成。

本阶段重点是完成里程碑1剩余的入门文档，将仅占位的设置部分替换为经过验证的指导，并扩展本地 CKB 节点和 RPC 流程的验证依据。本阶段完成的工作进一步强化了项目目标，即减少新手的不确定性，使首次成功进行 RPC 交互的路径更加清晰和可复现。

仓库与发布状态

第1周建立的仓库结构保持不变，第2周的工作在本地仓库环境中完成。

在此期间：

  • 未进行 GitHub 推送
  • 未创建 Pull Request
  • 未创建 git 提交
  • 未更改远程配置

这一点很重要，因为第2周的工作目标是在本地完善里程碑1内容，以便后续再进行发布或评审。

已完成工作

1. 完成里程碑1剩余设置部分

此前仅为占位的里程碑1设置部分已扩展为面向初学者、以验证为优先的文档。

已完成或基本完成的部分包括：

  • 03 快速开始
  • 04 CKB 节点设置
  • 05 RPC 设置
  • 07 配置设置

这些部分现在提供：

  • 达到首次 RPC 成功的最短验证路径
  • 明确的逐步节点启动指导
  • 面向初学者的 RPC 请求与响应解释
  • 最小化配置认知（避免推测性文件修改指引）

这直接支持了里程碑1的目标，即通过以文档为核心的入门流程帮助开发者实现首次成功的 RPC 交互。

2. 优化里程碑1导航与范围说明

更新了顶层项目说明，使仓库不再将已完成的里程碑1部分描述为占位内容。

更新文件包括：

  • README.md
  • 00 概览
  • 02 环境设置

这些更新提升了：

  • 文档结构顺序
  • 范围清晰度
  • 内部交叉引用
  • 已完成内容与后续占位内容的区分

3. 强化“验证优先”的边界

第2周的文档完善过程中，始终遵循不猜测未验证内容的原则。

具体包括：

  • 保留明确验证过的命令
  • 不引入推测性的配置修改
  • 明确记录端点不确定性
  • 后续内容保持占位而非填充不可靠信息

这使文档继续作为官方 Nervos 文档的补充，而非替代。

4. 添加里程碑标签到占位部分

后续占位部分新增了里程碑标签，用于明确规划顺序。

更新包括：

  • 06 Indexer 设置：里程碑2
  • 08 首个开发工作流：里程碑2
  • 09 常见错误与修复：里程碑2
  • 10 故障排查矩阵：里程碑2
  • 11 AI 辅助调试：里程碑3
  • 12 CKB 心智模型：里程碑3
  • 13 常见误解：里程碑3

这提升了规划清晰度。

验证工作

5. 优化环境连接验证

第1周中 https://example.com 的失败测试已被重新分析，并通过更有意义的真实 URL 测试进行验证。

更新结果包括：

  • 本地环境中 example.com 解析失败
  • 成功获取 https://google.com HTTPS 响应头
  • 证明测试目标选择会影响结果

这避免了错误地将单一失败当作整体网络问题。

6. 扩展节点与 RPC 验证

对本地 CKB 节点与 RPC 进行了多轮验证。

新增验证包括：

  • 多次执行 offckb node 启动
  • 从 localhost:8114 获取成功响应
  • 从 127.0.0.1:28114 获取成功响应
  • 错误方法测试行为
  • JSON-RPC POST 返回 HTTP 200
  • 使用 lsof 检查进程
  • 使用 --binary-path 启动
  • 验证 devnet 路径存在

增强了稳定性信心。

7. 明确本地端点关系

验证结果显示：

  • ckb 监听端口 8114
  • node 监听端口 28114
  • 两者均可返回有效 JSON-RPC

可解释为：

  • 28114：Node.js / OffCKB 代理层
  • 8114：底层 CKB RPC

8. 验证二进制路径与 devnet

确认：

  • 可动态发现 CKB 二进制路径
  • 可直接检查版本
  • offckb node -b <路径> 可用
  • 初始化后生成 devnet 目录

9. 确认里程碑范围边界

里程碑1覆盖：

  • 前置条件
  • 环境设置
  • 快速开始
  • 节点设置
  • RPC 设置
  • 基础配置

不包含：

  • Indexer 设置
  • 完整开发流程
  • 故障排查矩阵
  • AI 调试
  • 概念性内容

第2周成果总结

成功交付：

  • 完整的里程碑1核心文档
  • 更一致的文档结构
  • 更新的验证数据
  • 更清晰的 RPC 行为说明
  • 明确的后续里程碑规划
4 Likes
15

Hello @xingtianchunyan, here is the report for Week 1 (overall week 3) Milestone 2

Week 1 Milestone 2 Progress Report

Status

Milestone 1 has been completed.

Milestone 2 has started, and the Week 1 scope has been completed in the local repository workspace.

Work Completed

1. First CKB-Specific Overview Layer Added

The existing document at docs/03-quick-start.md was repurposed to fit the current repository structure and now works as the first CKB-specific overview layer.

This section now explains:

  • what CKB is

  • what Nervos is

  • what role a CKB node plays

  • what RPC is

  • why a developer may use a local node or a public RPC endpoint

  • what the guide currently covers and does not yet cover

This was done without creating duplicate files or breaking the Milestone 1 document ordering.

2. CKB Node Setup Guidance Expanded

The existing document at docs/04-ckb-node-setup.md was expanded from a narrower setup page into a more practical onboarding decision guide.

The updated section now covers:

  • when a local node is needed

  • when a public or shared RPC endpoint may be enough

  • the repository-validated local setup path

  • high-level preparation before local node work

  • common beginner mistakes

  • a verification checklist

Where the repository does not already contain validated evidence for exact broader setup instructions, the page now marks those areas for later verification against official CKB documentation.

3. RPC Basics Documentation Added In The Existing RPC Section

The existing document at docs/05-rpc-setup.md was expanded and reframed as an RPC basics page while keeping the current file structure intact.

The updated section now explains:

  • what RPC means

  • why RPC matters in CKB development

  • the difference between local RPC and public RPC

  • the health-check concept used during onboarding

  • what a successful response means

  • what failure usually means

4. Local Checkpoint Guidance Folded Into The Existing Milestone 2 Flow

Instead of creating a new top-level numbered document, the local-check guidance was kept inside the existing Milestone 2 documentation flow so the repository structure remained unchanged.

This checkpoint guidance now emphasizes:

  • confirming that the basic local tools still work

  • confirming that terminal handling is no longer a blocker

  • confirming that the node or RPC path is still reachable

  • confirming that the developer knows which endpoint actually worked

  • confirming that official documentation should still be used whenever the repository marks a detail for later verification

  • confirming that a beginner can classify common early failure types before assuming the node is broken

This keeps the Milestone 2 readiness checks practical without creating an unplanned structural change in the docs directory.

5. README Scope Messaging Updated For Milestone 2

The top-level README was updated so the repository no longer reads as if only Milestone 1 exists.

The updated wording now makes it clear that:

  • Milestone 1 remains the completed documentation foundation

  • Milestone 2 has started

  • the first Milestone 2 additions are CKB-specific setup, RPC basics, and local verification guidance

  • later sections are still placeholders unless validated

This improves project-state clarity without claiming that Milestone 2 is complete.

6. Commands For Week 1 Milestone 2 Were Kept Explicit

The Week 1 Milestone 2 documentation includes the following exact commands where repository validation already existed:

  • npm install -g @offckb/cli

  • offckb --help

  • offckb node

  • offckb clean

  • Example local RPC validation command (tested against local CKB node)

The documentation did not add new exact commands in areas that are still marked for later verification.

Remaining Scope For Week 2 Of Milestone 2

The second week of Milestone 2 should focus on completing the remaining planned CKB-specific content modules that are still placeholders.

The next sections to complete are:

  • docs/06-indexer-setup.md

  • docs/08-first-developer-workflow.md

  • docs/09-common-errors-and-remediation.md

  • docs/10-troubleshooting-matrix.md

  • docs/11-ai-assisted-debugging.md

  • docs/12-ckb-mental-model.md

  • docs/13-common-misconceptions.md

  • docs/13-common-misconceptions.md

3 Likes
CKB Ecosystem Biweekly Update
CKB Ecosystem Biweekly Update
16

Hi @xingtianchunyan

Based on the progress and work completed so far, I would like to submit a mid-term funding request.

If there is any problem, please let me know.

Requested amount: 40$ equivalent
Payment preference: 50% CKB/50% USDI

Best regards,
Milan

1 Like
17

@Mateja3m 你好，感谢你持续更新进展。

委员会根据当前已呈现内容进行审阅后认为：目前的交付物质量不满足中期拨付的验收预期，因此本次中期资金申请暂时不予批准。

主要原因（请你优先处理这些问题，而不是继续扩写篇幅）：

  1. 存在较多“无意义/低信息密度”的内容：过多的内容对新用户并不会有更多实际帮助，反而增加阅读负担。
  2. 结构不够清晰：缺少明确的“最短路径（quick start）→ 分支路径 → 常见问题回跳”的信息架构，新用户难以按步骤完成并判断是否做对。
  3. 对新用户不够友好：关键步骤缺少明确的通过/失败标准与可复现证据；部分内容更像工作记录而非面向读者的可操作指南。

为便于你快速改到可验收状态，建议你至少补齐/重做以下三件事（写清楚并可复核）：

  • 重建目录与导航：把内容收敛成“新手最短可成功路径”，并明确每一节的读者前置条件、预期结果、失败时去哪里排查。
  • 删减无效内容、提升信息密度：每个段落都应能回答“读者下一步怎么做、怎么判断成功”。
  • 补足 How to Verify：把验证写成“照着做即可”的 checklist（环境、步骤、预期输出、证据位置），并确保读者能低成本复现。

你完成上述结构性修订后，可以在本帖回复 @ 我并说明“哪些章节已重构、删了哪些内容、验证证据放在哪里”，委员会会再进行复审。

祝好
行天
代表 Spark Program 委员会

2 Likes
18

Hello @xingtianchunyan,

Thank you for your extensive feedback.

After a few days of restructuring my documentation regarding this project, I changed it according to feedback. Previous findings were used to create the new project’s files.

Changed

The docs navigation was restructured and is now in the structure:

Quick Start → Branching Paths → Troubleshooting Matrix → FAQ → How to Verify

That’s the general structural change; besides that, inside files are also changed:

  • README.md now shows only the required beginner path and success signals.

  • docs/quick-start.md is the shortest path using public RPC first.

  • docs/branching-paths.md separates the guide into Path A public RPC, Path B local node, and Path C full local check.

  • docs/troubleshooting-matrix.md maps common failures to cause, fix, verification command, and related section.

  • docs/faq.md gives short answers and points readers back to the right guide section.

  • docs/how-to-verify.md provides the reproducible checklist: environment, steps, expected output, pass/fail criteria, and evidence location.

All the previous stuff is not deleted, but it’s just moved to folders inside the project’s structure.

  • Removed milestone/status wording from the main path.

  • Removed the old numbered document sequence from the README.

  • Moved longer background, concept, and support pages into docs/reference/, which is not pushed to github.

  • Kept validation material in docs/validation/ as evidence only, not as the reader-facing guide.

  • Preserved previous reports in docs/reports/.

Verification Evidence files can be found as follows:

  • docs/validation/environment-validation-findings.md

  • docs/validation/ckb-node-and-rpc-validation-findings.md

  • docs/how-to-verify.md

  • validation-logs/2026-05-11-how-to-verify-rerun.md

Fresh reruns can be recorded in:

  • validation-logs/ using docs/validation/validation-log-template.md

If something else is needed, please reach out to me.

Milan

1 Like
19

星火计划：终止对 CKB Developer Onboarding Guide 项目的资助

星火计划致力于支持社区开发者和创新项目。我们始终以透明、公正和负责任的态度管理每一笔资助。经过委员会的慎重评估，我们遗憾地宣布，对 CKB Developer Onboarding Guide 项目的资助已正式终止。

项目基本信息

  • 项目名称：CKB Developer Onboarding Guide
  • 开发者/团队：Milan Matejic（@Mateja3m）
  • 项目简介（提案内容）：

CKB Developer Onboarding Guide 是一个以文档为核心的结构化入门资源，旨在帮助开发者从零开始完成 Nervos CKB 区块链的环境搭建并顺利开始开发。项目重点包括：分步骤入门流程、环境配置指导、RPC 与 Indexer 配置、故障排查与修复矩阵、第一个可运行的开发流程、AI 辅助调试，以及中英双语版本。

  • 项目讨论与详情主要链接：Spark Program | CKB Developer Onboarding Guide - Nervos Talk
  • 代码仓库：GitHub - Mateja3m/ckb-developer-onboarding-guide

终止决定及原因

申请人在项目执行期间提交了中期资助申请，声称已完成 M1（第 1–2 周）及 M2 第 1 周的工作内容。委员会依据提案基线，对申请人自述已完成的交付物进行了审核，发现即便仅围绕其声称完成的内容评估，交付质量仍未达到提案承诺的基本标准——初级用户看到目前的文档后仍然无法确定自己是否能够成功运行节点或进行项目开发，机器输出的大量日志也缺乏简明扼要的指导。

具体情况梳理

1. 中期资助审核阶段（5/9 委员会反馈）

申请人提交中期资助申请后，委员会对已提交内容进行了审核，发现三个主要问题并明确要求改进：

  • 结构混乱：文档缺乏清晰的 Quick Start → 进阶路径 → 故障排查的逻辑主线，初级用户无法快速找到所需内容。
  • 信息密度不足：大量内容是框架性描述（如 “validation framework aligned”），缺乏可执行的实际命令、预期输出和可复现步骤。
  • How to Verify 缺失：文档未提供明确的 PASS/FAIL 检查清单，读者无法自行判断是否成功完成了环境搭建。

委员会据此拒绝了中期支付申请，并给出具体改进要求。

2. 申请人重构响应（5/12–5/14）

申请人接受反馈后进行了仓库重构。委员会认可以下改进：

  • 结构改进：Quick Start → Branching Paths → Troubleshooting → FAQ → How to Verify 的主路径趋于清晰。
  • 验证标准：PASS/FAIL 标准已加入 how-to-verify.md。
  • 信息密度：去掉了此前大量框架性官话，内容更聚焦。

但重构过程中暴露了新的问题：

  • 重构移除了此前的交付证据：5/12 的 commit 0592d8f（“Stop tracking report and reference docs”）将所有 docs/reports/ 和 docs/reference/ 移出 git 跟踪；5/13 的 commit e05a59b 将 validation-logs/ 加入 .gitignore。申请人声称文件"只是移动了位置，并未删除"，但这些内容在 GitHub 上已不可见，委员会的可验收基线被实质性缩小。这与"提案锁定，按基线验收"的程序要求存在冲突。
  • 重构后内容体量显著不足：仓库仅剩 README + docs/ 下 5 个主文档 + 6 个 validation 文件，实际内容约 15 KB。

3. 委员会对申请人自述已完成内容的复核

考虑到申请人一直在为中期资助申请调整交付物，委员会对于尚未到期的里程碑（M2 后半及 M3）的完成情况不予置评，仅围绕申请人自述已完成的内容进行逐项核实。核实结果如下：

申请人声称已完成的内容 委员会核实结果
Prerequisites + Environment Setup ✓ 已在 quick-start.md 和 how-to-verify.md 中体现
Quick Start Path（公共 RPC，首次成功） △ quick-start.md 存在，但声称 10–15 分钟可完成，仅在申请人自己的 Mac 上测过，未经第三方环境验证
CKB Node Setup + RPC Setup △ 未按提案设为独立章节，仅作为 branching-paths.md 中 Path B/C 的各一个 RPC 调用出现
Indexer Setup △ 仅 Path C 一个 get_indexer_tip 调用，远未达到独立章节的深度
Troubleshooting Matrix △ 仅 7 类症状，每类约 5 行；缺少提案 Section 8 要求的 expected output / reproducible command 成对结构
公开仓库 + MIT License ✓

核心问题：

  1. 初级用户仍无法获得有效指导：这是委员会评审的核心结论。目前的文档既不能让初级用户判断自己是否能成功运行节点，也不能在用户遇到大量机器日志输出时提供简明扼要的方向指引。作为一个定位于"面向无 CKB 经验开发者"的入门指南，这一根本性不足直接构成了交付不达标的判定依据。
  2. Troubleshooting Matrix 过于薄弱：仅 7 个症状条目，与提案 Section 8 承诺的"each entry includes root cause, fix steps, reproducible commands, expected outputs"有明显差距。这正是委员会在 5/9 反馈中要求的"How to Verify 要写成 checklist"的精神——申请人在 how-to-verify.md 上做到了，但 troubleshooting 部分仍未补齐。
  3. 未进行第三方复现验证：所有验证证据均来自申请人自己的开发机器（/Users/milanmatejic/...），contributor 列表仅有申请人一人。提案承诺"无 CKB 经验的开发者照着走即可"，但从未进行任何独立的第三方可复现性测试。对文档类项目而言，独立可复现性是衡量交付质量的基本前提。
  4. 周报与 commit 历史存在不一致：4/26 的 W2M1 周报明确写道"no GitHub push was performed, no git commit was created"，但 commit 历史显示 4/24（commit 87fa5a3）已 push 了 W2M1 相关内容。

委员会的最终决议

根据《星火计划小额资助方案》"3.3 完成政策"的相关规定：

  • 连续较长时间无实质性进展且无合理原因
  • 项目方向完全偏离原申请目标 / 资金使用严重偏离项目计划，且未经 Committee 批准

委员会认定，CKB Developer Onboarding Guide 项目在结构重组方面展现了一定的响应态度，委员会对此予以认可。但经复核，申请人自述已完成的内容在质量和实用性上仍未达到提案承诺的基本标准：初级用户无法从现有文档中获得可操作的有效指导；Troubleshooting Matrix 条目偏少且缺乏规范结构；所有内容仅在申请人单一环境下测试，未经任何独立第三方验证。委员会在中期审核中已明确指出问题并给予改进机会，申请人在结构层面有所响应，但内容的实质性质量问题并未得到根本解决。继续资助已无法保障原定生态价值实现，也不符合星火计划对项目基本可用性与交付一致性的要求。为维护计划的公信力与资源分配效率，最终遗憾地决定终止对该项目的资助支持。

资金处理情况

  • 已发放资金：
    • 首笔资助（20%）：10 USDI + 6,743 CKB
      • 交易哈希（10 USDI）：0xd629582ce9447337d7341472667d1b72a4109facb08072eab5fef41489869f58
      • 交易哈希（6,743 CKB）：0xf4b0600801f42dccf8c7c654305c9d13899f4f00ceb46a231ffae2893f9e6738
  • 剩余资金：不再发放，将从项目多签钱包退回 Spark Program 主钱包。

致社区

星火计划的核心原则是透明与负责。我们对 CKB Developer Onboarding Guide 项目提出的"为初级开发者提供结构化入门路径"这一出发点表示认可，也肯定申请人在接收反馈后进行结构重组的积极态度。但遗憾的是，在中期资助审核中，申请人自述已完成的内容经逐项核实后仍未达到提案基线的质量要求。此次终止决定是基于中期审核过程中的充分事实核查、多轮反馈沟通记录以及提案基线对照做出的，旨在保护社区资源并维护计划的可持续性。

我们鼓励开发者在项目执行中保持与委员会的紧密沟通，对技术瓶颈及时求助并接受建议。文档类项目尤其需要确保内容的独立可复现性——这不仅是验收标准，也是此类项目真正服务社区的基础。我们也欢迎有志于开发者入门方向的贡献者重新整理方案、以更稳健的方式再次申请。

星火计划将继续秉持"低门槛、快节奏、真支持"的理念，欢迎更多务实、可落地的创新项目加入。我们相信，通过更扎实的执行与协作，社区将诞生更多真正可靠的成果。

如对本决定有任何疑问，可在 Nervos Network Discord 的 Spark Program 频道或本帖下留言，委员会将及时回应。

2026-05-20

行天

代表星火计划委员会

6 Likes
CKB Ecosystem Biweekly Update
20

Thank you for the detailed review and for the time the committee invested in evaluating the project.

First, I want to make clear that I respect the committee’s decision. My response should not be understood as an attack on the committee, the Spark Program, or any individual reviewer. I understand that the decision was made on behalf of the committee, and I appreciate the opportunity I was given to work on this proposal and receive feedback during the process.

I would still like to add a few clarifications for the public record.

After the 5/9 mid-term feedback, I understood the committee’s main concern to be that the repository had too much low-density material, unclear navigation, and not enough direct beginner-facing verification. In response, I restructured the repository around the path the committee requested: Quick Start → Branching Paths → Troubleshooting Matrix → FAQ → How to Verify.

The public repository was narrowed after 5/12, but this was not deletion of work or abandonment of the proposal. It was a direct response to the committee’s feedback requesting a shorter, clearer, higher-density beginner path. The removed materials were not deleted; they were moved out of the reader-facing GitHub path in order to avoid the exact issue the committee identified: excessive low-density content and work-log-style material. If the committee required those materials to remain publicly verifiable as baseline evidence, that requirement was not clear to me during the restructuring feedback.

Regarding the mid-term funding request: I did submit it, but my intention was not to claim that the entire project was finished. I understood weekly and mid-term communication as part of the expected process, especially since the committee itself emphasized regular communication during execution. My report, after restructuring the project, was meant as a progress checkpoint and a request for review, not as a statement that every proposal item had already been fully completed.

I also want to clarify that funding was never the primary motivation for this project. I accepted the reduced $100 grant because I cared more about the potential value of the onboarding guide for the CKB community than about personal financial benefit. The goal was to contribute something useful for new developers and to improve it through feedback.

On the issue of third-party reproducibility: I acknowledge that no independent third-party test had been completed at the time of review. However, I did not understand this to be an explicit requirement in the original proposal. If it had been requested clearly during the process, I believe it could have been arranged with the community or committee support. I agree that independent reproduction would make the guide stronger, and I have now added a reviewer-facing reproducibility checklist to make such testing easier.

Following the committee’s feedback and termination notice, I have also updated the repository further. The repo now restores public visibility for proposal-related reference materials and validation evidence, expands the Troubleshooting Matrix with reproducible commands and expected outputs, adds a third-party reproducibility checklist, and includes a Chinese guide section.

Again, I respect the committee’s final decision. My intention here is only to clarify that the restructuring was done in good faith and in response to committee guidance, not as an attempt to remove deliverables or narrow the baseline unfairly. I appreciate the feedback received during the process and hope the updated repository can still be useful to the community.

7 Likes