Spark Program | CKB Developer Onboarding Guide

English
,
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