Spark Program | ckb-joyid-failure-explainer

Crackdevs · June 26, 2026, 6:41am

1. Project Overview / 项目概述

Project name: ckb-joyid-failure-explainer

Applicant: Crackdevs

Website:

One-sentence overview:
ckb-joyid-failure-explainer is a lightweight open-source CLI and npm package that helps CKB developers interpret JoyID/CCC transaction failure artifacts, especially failures related to JoyID lock-script error codes, SubKey/CoTA requirements, witness data, cell deps, and transaction-size changes after signing.

Project positioning:
Developer tooling / npm package / CLI diagnostic tool for CKB wallet-integration debugging.

Core output:
A TypeScript-based CLI and library that accepts saved CKB transaction artifacts, saved error output, or before/after signing transaction files and returns a clear diagnostic report with likely cause, evidence found, suggested fix, and limitations.

Example command:

npx ckb-joyid-failure-explainer explain \
  --tx ./tx.json \
  --error ./error.txt \
  --profile joyid

Example output:

ERROR JOYID_ERROR_14_SUBKEY_PROOF_FAILED

Likely cause:
The transaction appears to hit a JoyID SubKey/CoTA verification path, but the provided artifacts suggest that the required SubKey unlock material or CoTA cell dependency may be missing or incorrectly ordered.

Suggested fix:
Check that the SubKey unlock entry is appended to the witness and that the CoTA cell is placed first in cellDeps for the JoyID SubKey flow.

This tool does not build, sign, dry-run, broadcast, or validate general CKB transactions. It only explains JoyID/CCC-related failure artifacts after a transaction has already failed or been captured.

2. Team Profile / 团队简介

Applicant: Crackdevs

Crackdevs is a builder collective focused on developer tooling and core infrastructure. The team builds and maintains CLIs, SDKs, templates, IDE extensions, deployment workflows, and other glue code that makes blockchain development less painful.

Primary contact email: [email protected]

Core team

Ayomide Ojutalayo — Project Lead
Ayomide is a developer engineer with experience building developer tooling and blockchain-focused software. He will lead the technical execution of the CLI runner, rule engine, fixture pack, adapter interface, and repository delivery.

Aje Damilola — Documentation & QA Engineer
Aje is a full-stack software developer with experience across Node.js, JavaScript/TypeScript, React, Electron, PHP/Laravel, Flutter, AdonisJS, PostgreSQL, and MongoDB. He will support fixture documentation, QA review, test coverage, report validation, and maintenance documentation.

Ifedimeji Omoniyi — Technical Product Manager
Ifedimeji is a technical product manager with experience across developer tooling, protocols, and infrastructure. He will coordinate delivery, milestone tracking, scope control, reviewer communication, and final handoff.

Prior CKB work:
Crackdevs has not completed a prior CKB grant. This proposal is scoped as a small first CKB contribution focused on one narrow developer tooling problem, with clear outputs that can be verified by running the package and fixture tests.

3. Project Background / 项目背景

CKB dApp development increasingly depends on wallet-integrated transaction flows. Developers using CCC and JoyID may build a transaction, request wallet signing, and then receive a failed dry-run, debug, or script error output.

The failure can be difficult to interpret because it may involve CKB-specific transaction structure, including witnesses, WitnessArgs.lock, cell deps, lock scripts, transaction size, fee rate, and JoyID-specific SubKey/CoTA requirements.

The specific scenario this project targets is:

A developer builds a CKB transaction for a JoyID/CCC flow.
The transaction is signed or prepared for signing.
The transaction fails during dry-run, debug, or submission.
The developer receives a low-level error or transaction artifact.
The developer needs to understand whether the likely cause is a JoyID error code, missing SubKey unlock material, CoTA cell-dep ordering, witness formatting, or transaction-size changes after signing.

This is not a generic CKB setup problem and not a request for another broad transaction builder. It is a narrow post-failure explanation tool for one CKB wallet-integration workflow.

The project is useful because JoyID documents CKB-specific failure causes and error codes, while local CKB development tools can produce transaction and debug artifacts. This tool turns those artifacts into clearer next steps for developers.

4. Solution / 解决方案

ckb-joyid-failure-explainer will provide a small CLI and npm library for explaining JoyID/CCC transaction failure artifacts.

The tool will support three core workflows.

A. Explain a saved error output

ckb-joyid-failure-explainer explain \
  --error ./error.txt \
  --profile joyid

This reads a saved dry-run, debug, or script error output and maps known JoyID-related errors to a structured explanation.

B. Explain a transaction plus error output

ckb-joyid-failure-explainer explain \
  --tx ./tx.json \
  --error ./error.txt \
  --profile joyid

This combines the error output with available transaction evidence, such as witnesses and cell deps, and reports what can or cannot be verified from the provided data.

C. Compare before/after signing artifacts

ckb-joyid-failure-explainer compare \
  --before ./before-signing.json \
  --after ./after-signing.json \
  --resolved-inputs ./resolved-inputs.json \
  --profile joyid

This helps identify whether the transaction size changed after signing. If resolved input data is provided, the tool can estimate whether the effective fee rate may have changed. If resolved input data is missing, the tool will report a size-change warning without claiming full fee verification.

Differentiation from existing tools

This project does not replace CCC, JoyID SDK, OffCKB, ckb-cli, ckb-debugger, or CellKit-style transaction tooling.

The difference is:

CCC helps developers build wallet-connected CKB apps.
JoyID SDK helps with JoyID wallet interactions.
OffCKB helps developers run and debug CKB transactions.
ckb-debugger helps inspect script execution.
CellKit-style tooling focuses on reusable transaction action flows.

ckb-joyid-failure-explainer only explains JoyID/CCC-specific failure artifacts after the developer already has a failed transaction, saved error output, or before/after signing artifact.

5. Technical Approach / 技术方案

Tech stack

TypeScript
Node.js
npm package
CLI entrypoint
Vitest for fixture tests and snapshots
JSON report output for CI and issue reports

Core modules

Input Adapter
  - error text parser
  - raw transaction JSON reader
  - before/after signing artifact reader
  - optional resolved metadata reader

JoyID Rule Engine
  - JoyID error-code explanations
  - SubKey/CoTA checklist
  - witness evidence checks
  - signing-size comparison checks

Reporter
  - human-readable terminal output
  - JSON output

Fixture Pack
  - broken examples
  - neutral examples
  - expected report snapshots

MVP diagnostic rules

The MVP will include explanations for documented JoyID CKB smart-contract errors, including:

public key hash mismatch;
invalid witness length;
invalid unlock mode;
Secp256r1 verification failure;
missing WebAuthn challenge;
invalid CoTA SMT root;
failed SubKey SMT proof;
CoTA cell lock mismatch.

The tool will also include a SubKey/CoTA checklist that looks for available evidence around:

whether the error points to a SubKey/CoTA failure;
whether cell-dep metadata was provided;
whether CoTA-related metadata appears missing or incorrectly ordered;
whether witness data is present for the relevant input group;
whether the tool lacks enough metadata to make a stronger claim.

Technical limitations

The tool will not claim to fully validate a CKB transaction from incomplete JSON.

When metadata is missing, it will say so clearly:

WARN METADATA_REQUIRED

The provided transaction JSON does not include enough resolved input or cell-dep metadata to confirm this condition.

What can be confirmed:
- JoyID error code was detected in the error output.

What should be provided for stronger diagnosis:
- resolved input cells
- resolved cell deps
- local debug output or transaction dump

This keeps the tool useful without overstating what can be proven from partial artifacts.

6. Execution Plan / To-Do List / 执行计划

Estimated duration: 1 week after approval

This is proposed as a one-week delivery sprint because the scope is intentionally small: one CLI, one npm package, one JoyID-focused rule set, fixture tests, documentation, and a short demo. The project does not include a backend service, web dashboard, live infrastructure, wallet UI, transaction builder, or broad CKB validation framework.

Week 1 — Implementation, testing, packaging, and handoff

Day 1 — Repository setup and rule schema

Create the public GitHub repository.
Set up TypeScript, CLI entrypoint, package structure, and test framework.
Define report schema and rule IDs.
Create fixture folder structure.
Implement the first error-text parser.

Day 2 — JoyID error-code explainer

Implement JoyID error-code explanation rules.
Add human-readable terminal output.
Add JSON output mode.
Add tests for the first rule group.

Day 3 — Transaction artifact support

Add --tx input support.
Parse transaction fields needed for evidence reporting.
Add witness and cell-dep evidence checks where metadata allows.
Add metadata-required warnings for incomplete artifacts.

Day 4 — SubKey/CoTA checklist and compare command

Add SubKey/CoTA diagnostic checklist.
Add compare command for before/after signing artifacts.
Detect transaction-size changes after signing.
Show fee-rate estimate only when resolved input metadata is provided.

Day 5 — Fixture tests and examples

Add broken and neutral fixtures.
Add expected output snapshots.
Add demo commands:
- npm run demo:joyid-error-7
- npm run demo:subkey-cota
- npm run demo:signing-size-change
Run full test suite and fix issues.

Day 6 — Documentation and npm packaging

Complete README.
Add English quick-start.
Add Chinese quick-start.
Add “What this tool does and does not do.”
Add verification commands and expected outputs.
Prepare npm package release.

Day 7 — Final review and completion report

Publish npm package.
Record a short demo video or GIF.
Final QA review.
Publish final Spark completion update with repository link, npm package link, demo, and verification commands.

Milestone output

npm install
npm test
npm run demo:joyid-error-7
npm run demo:subkey-cota
npm run demo:signing-size-change

Expected result:

All fixture tests passed.
JoyID error-code reports matched expected snapshots.
SubKey/CoTA reports matched expected snapshots.
Signing-size comparison reports matched expected snapshots.

7. Required Funding & Funding Breakdown / 所需资金与资金分配明细

Requested amount

$1,000

This is scoped as a standard Spark mini-grant. The project is a small CLI/npm package with no hosted backend, no dashboard, no private partner dependency, and no institutional adoption requirement before it becomes useful.

Funding breakdown

Category	Work covered	Amount
CLI and rule engine implementation	TypeScript CLI, command structure, JoyID rule engine, report generation	$350
Transaction artifact and compare support	`--tx` support, before/after signing comparison, metadata-aware warnings	$250
Fixtures and tests	Broken/neutral fixtures, expected output snapshots, Vitest test coverage	$200
Documentation, packaging, and handoff	README, Chinese quick-start, npm release, demo video/GIF, final report	$200
Total	One-week MVP delivery	$1,000

8. Deliverables + How to Verify / 交付物 + 验证方式

Deliverables

Public GitHub repository under Crackdevs or a project-owned organization.
Open-source license: MIT or Apache-2.0.
TypeScript CLI package.
Published npm package.
explain command for error and transaction artifacts.
compare command for before/after signing artifacts.
JoyID error-code explanation rules.
SubKey/CoTA diagnostic checklist.
Metadata-required warnings for incomplete artifacts.
JSON report output.
Fixture tests and expected output snapshots.
English README.
Chinese quick-start section.
Short demo video or GIF.

Verification requirements

Baseline verification will not require a live CKB node. Reviewers should be able to verify the package using Node.js, npm, and the included fixtures.

Verification step 1 — Clone and install

git clone [repo]
cd ckb-joyid-failure-explainer
npm install

Expected result:

Dependencies installed successfully.

Verification step 2 — Run tests

npm test

Expected result:

All fixture tests passed.
JoyID error-code reports matched expected snapshots.
SubKey/CoTA reports matched expected snapshots.
Signing-size comparison reports matched expected snapshots.

Verification step 3 — Run JoyID error explanation demo

npm run demo:joyid-error-7

Expected output:

ERROR JOYID_ERROR_7_WITNESS_LENGTH_INVALID

Likely cause:
The JoyID lock script reported invalid witness length.

Suggested fix:
Check the WitnessArgs.lock value and ensure the transaction witness was not mutated after signing.

Verification step 4 — Run SubKey/CoTA checklist demo

npm run demo:subkey-cota

Expected output:

ERROR JOYID_ERROR_14_SUBKEY_PROOF_FAILED

Likely cause:
The transaction appears to hit a JoyID SubKey/CoTA verification path.

Checklist:
- Confirm that the SubKey unlock entry was appended to the witness.
- Confirm that the CoTA cell is placed first in cellDeps.
- Provide resolved metadata for stronger diagnosis.

Verification step 5 — Run before/after signing comparison

npm run demo:signing-size-change

Expected output:

WARN CKB_SIGNING_SIZE_CHANGED

The transaction size changed after signing.

Fee-rate note:
A fee-rate estimate is shown only if resolved input capacity metadata is provided.

Verification step 6 — Verify JSON output

npx ckb-joyid-failure-explainer explain \
  --error ./examples/joyid-error-14/error.txt \
  --profile joyid \
  --json

Expected output:

{
  "status": "error",
  "profile": "joyid",
  "ruleId": "JOYID_ERROR_14_SUBKEY_PROOF_FAILED",
  "severity": "error"
}

9. Current State vs. Funded Work / 当前状态 vs. 资助范围

Current state

The current state is research and scoped proposal design.

Completed so far:

reviewed the Spark mini-grant format and scope;
identified JoyID/CCC transaction failure explanation as the target problem;
checked overlap risk with existing CKB tools;
defined the MVP scope, deliverables, and verification commands.

No implementation has started yet. There is no prototype or npm package at the time of submission.

Funded work

Spark funding will cover the first implementation of the tool:

public repository setup;
TypeScript CLI;
JoyID diagnostic rules;
fixture pack;
JSON report mode;
before/after signing comparison;
npm package publication;
documentation;
Chinese quick-start section;
demo video/GIF;
final completion report.

Boundary

This proposal is not requesting funding for research only. The research and proposal scoping are already done. The funded work is the implementation and release of a small open-source developer tool.

10. CKB Alignment / CKB 契合度

This project is directly aligned with CKB because it focuses on transaction failure modes that come from CKB-specific architecture and wallet integration.

The tool is built around:

CKB witnesses;
WitnessArgs.lock;
lock-script error output;
cell deps;
JoyID CKB smart-contract errors;
SubKey/CoTA requirements;
CCC/JoyID wallet integration;
transaction-size changes after signing.

This is not a generic Web3 log parser. The first supported profile is specifically for JoyID-related CKB transaction failures.

The project fits Spark’s mini-grant size because it is narrow, testable, open-source, and does not require a backend service or partner adoption. The committee can verify the work by installing the package, running tests, and checking the expected diagnostic outputs from included fixtures.

Out of scope

This project will not include:

transaction building;
wallet UI;
signing;
private key handling;
transaction broadcasting;
generic transaction validation;
generic CKB environment diagnostics;
dashboard;
backend service;
indexer;
Fiber tooling;
Spore/DOB tooling.

The scope is intentionally limited to JoyID/CCC post-failure explanation so the project can be delivered quickly and verified with simple commands.

Final note

Crackdevs is applying for this Spark mini-grant to make one small but practical contribution to CKB developer tooling: a focused failure explainer that turns JoyID/CCC transaction artifacts into clearer next steps for developers.

The intended result is not a broad debugging platform. It is a lightweight tool that can be installed, tested, and improved by the community.