Repository: Akane-CN/spark-verify
Requested funding: $1,000, paid in CKB
Timeline: 6 weeks
1. Project overview
Spark Verify is an open source command-line tool and a small verify.toml format for CKB projects.
A project author describes a local devnet flow and the results that should be observed, such as whether a transaction commits or is rejected, which Cells exist after the run, whether a balance changed as expected, and how many CKB-VM cycles a script used. A reviewer runs one command and receives a pass/fail result with a structured evidence report.
The goal is to make the “How to Verify” section of a CKB project easier to run and repeat. Spark Verify will use the existing CKB development stack rather than replace it.
2. Team profile
Applicant and maintainer: Akane
- GitHub: Akane-CN
- Nervos Talk: Akane
- Email: [email protected]
3. Project background
CKB projects already have good tools for individual layers:
- OffCKB provides a local development chain, development accounts, and script deployment.
- CCC builds and signs CKB transactions.
- ckb-debugger reports script errors and cycle usage.
- ckb-testtool supports script-level tests.
The final acceptance check is still different for every project. Reviewers often have to follow repository-specific instructions, run several commands in the correct order, inspect RPC responses, and decide whether the observed result matches the project’s claims. These instructions become harder to repeat when tool versions or setup details change.
Spark Verify addresses this acceptance layer. It gives project authors a small CKB-specific vocabulary for declaring observable results and gives reviewers a consistent way to run those checks.
4. Solution
A participating project adds a verify.toml file and, where necessary, a small script that builds a signed CKB transaction.
Spark Verify will:
- validate the manifest;
- start a fresh local OffCKB devnet with pinned tool versions;
- run the project’s declared steps;
- submit transaction artifacts and record committed or rejected results;
- check Cells, balances, script errors, and cycle limits; and
- produce a JSON report and a readable terminal summary.
The first version will support local development chains only. It will not use testnet or mainnet private keys. Repository commands remain trusted project code, so the documentation will tell reviewers to run the tool only in an isolated environment without production secrets.
5. Technical approach
The CLI will be written in TypeScript and run with Bun. The repository will pin the Bun version and commit its Bun lockfile. The finished CLI will be published as an installable command-line package.
The implementation will include:
- strict TOML parsing and runtime schema validation;
- exact Bun, CKB, OffCKB, and ckb-debugger version checks;
- OffCKB startup, readiness checks, development accounts, script resolution, and cleanup;
- runner-owned submission of signed CCC-compatible transactions;
- assertions for transaction status, script error groups, cycle limits, live Cells, capacity, Cell data, CKB balances, and UDT-compatible balances;
- JSON reports containing the observed results and relevant environment information; and
- a GitHub Action example for repositories that want to run the same checks in CI.
The report will distinguish the observed outcome from the environment used to produce it. This makes version or repository changes visible without claiming that arbitrary project code is formally deterministic.
6. Execution plan
Weeks 1-2: manifest and execution core
- finalize the v0.1 manifest fields and schema;
- implement manifest validation;
- start and stop a pinned OffCKB environment;
- execute project commands and submit signed transactions; and
- cover both committed and script-rejected transaction examples.
Weeks 3-4: assertions and evidence reports
- implement transaction, script-error, cycle, Cell, and balance checks;
- produce JSON and terminal reports;
- record repository, toolchain, genesis, and deployed-script information; and
- add valid, invalid, passing, and failing test fixtures.
Week 5: CI and project example
- publish a GitHub Action example;
- adapt one CKB project to
verify.toml; and - test clean-checkout verification on Ubuntu and macOS.
Week 6: release and documentation
- publish the CLI package and tagged v0.1 specification;
- complete the author guide and security notes;
- record a short end-to-end demo; and
- publish the Spark completion and budget report.
7. Required funding and breakdown
Total requested: $1,000, paid in CKB.
- Manifest, schema, and initial execution work: $200
- OffCKB execution adapter and transaction protocol: $300
- Assertion engine and failure reporting: $250
- Evidence report and GitHub Action: $150
- Project example, release documentation, and demo: $100
No funding is requested for hosting or a web interface.
8. Deliverables and verification
Deliverables:
- A versioned
verify.tomlv0.1 specification and machine-readable schema. - A published Bun-based
spark-verifyCLI package. - Conformance fixtures covering valid, invalid, passing, failing, committed, and rejected cases.
- JSON evidence reports and readable terminal output.
- A GitHub Action example.
- A toy CKB example and one adapted CKB project.
- Documentation, a demo, and a completion report.
A reviewer will be able to verify the release from a clean checkout:
git clone https://github.com/Akane-CN/spark-verify.git
cd spark-verify
bun install --frozen-lockfile
bun test
bun run build
bun run verify:release
The release check will demonstrate:
- a successful transaction and matching Cell or balance result;
- an intentionally failing claim with an expected-versus-observed diff;
- a script-rejected transaction with its error evidence;
- repeated runs with comparable reports; and
- a visible failure or warning when the declared tool versions do not match.
