- Applicant: Owais (GitHub: owaisdotcom) · Full Stack Software Engineer
- Requested: $1,200 USD, paid 100% in CKB at the official approval snapshot rate
- Duration: 4 weeks, 4 milestones · License: MIT
- Contact: Nervos Talk
- Stack: React, Next.js, Node.js, Express, JWT authentication. This is the same stack as the template and reference dApp.
1. Problem
User onboarding remains a primary bottleneck for consumer dApp adoption on Nervos CKB. Mainstream Web2 users drop off when forced to download wallet browser extensions or safely manage 12-word seed phrases.
While CKB natively supports WebAuthn / Passkey hardware signatures on-chain via ckb-auth, integrating these primitives into a front-end dApp requires extensive low-level engineering:
- Handling raw WebAuthn clientDataJSON and authenticatorData attestation parsing.
- Converting DER-encoded ECDSA P-256 signatures from the authenticator into the witness format the lock script expects.
- Building raw CKB transaction payloads and managing Cell capacity and locks manually.
There is currently no plug-and-play CLI template (similar to create-eth-app or RainbowKit) that lets CKB developers ship passkey-native apps out of the box.
2. Solution
create-ckb-passkey-app is an open-source CLI (npx create-ckb-passkey-app) and TypeScript SDK that scaffolds a Next.js dApp where users sign in and sign CKB transactions with FaceID, TouchID, or a device passkey. No browser extension, no seed phrase. The project uses existing CKB primitives to create a developer-friendly template and a useCKBPasskey React hook.
3. How this differs from existing work
Passkey-style signing already exists in parts of the ecosystem (for example JoyID, and CKB’s CCC SDK). This project does not claim to invent passkey support on CKB. Its gap is developer experience: a self-hosted, wallet-less, scaffoldable starter that a team can fork and own.
| Hosted passkey wallet (e.g. JoyID) | General SDK (e.g. CCC) | This project | |
|---|---|---|---|
| Passkey signing | Yes | Via integrations | Yes |
| Developer owns the auth flow and UI | Limited | Yes | Yes |
| One-command scaffold with working passkey app | No | No | Yes |
| Passkey-specific hook, tests, and docs | No | No | Yes |
Week 1 includes a short written review of existing implementations. Where possible the SDK will build on CCC and the existing on-chain lock script rather than reimplement them, and will document any compatibility with JoyID-created accounts.
4. Deliverables
- CLI: npx create-ckb-passkey-app my-app scaffolds a Next.js/TypeScript project preconfigured for CKB testnet.
- SDK + useCKBPasskey hook: passkey registration, login, session handling, address derivation, and transaction signing.
- Reference dApp: passkey sign-up, balance display, and a live testnet CKB transfer, deployed on Vercel.
- Docs and video: integration guide on GitHub Pages, a security notes page, and a 3-minute walkthrough on Nervos Talk.
5. Technical approach
Browser / device (FaceID, TouchID, Windows Hello, Android biometrics)
│ WebAuthn assertion
▼
useCKBPasskey hook + SDK
• parse clientDataJSON / authenticatorData
• normalize signature to the lock script witness format
• build and sign CKB transactions (CCC where possible)
│
▼
CKB Testnet / Mainnet
• passkey-capable lock script verifies the signature on-chain
Exact lock script, args layout, and witness format will be confirmed against the deployed ckb-auth code in Week 1 and documented in the repo.
6. Security and recovery
Seedless accounts need explicit security thinking, so this is scoped in rather than deferred:
- Challenge handling: the SDK builds the WebAuthn challenge from the transaction hash so a signature cannot be replayed for a different transaction. Origin and RP ID are validated.
- Key custody: private keys never leave the authenticator. The SDK stores only the public key and credential ID.
- Recovery: losing a device can mean losing access. The template documents the options (synced passkeys such as iCloud Keychain or Google Password Manager, registering a second passkey as backup) and ships a working example of adding a backup passkey on testnet if the lock design allows it.
- Scope limit: this is a starter kit, not audited. The README and CLI output will say so and will recommend testnet use and an independent audit before handling significant mainnet funds.
7. Milestones, acceptance criteria, and payment
Per Spark rules, 20% ($240) is pre-released at launch and deducted from the M1 payment. The remainder of each milestone is released on acceptance.
| Milestone | Timeline | Deliverables | How reviewers verify | Payment |
|---|---|---|---|---|
| M1: SDK core | Week 1 | Ecosystem review; WebAuthn parser; signature and witness formatting; testnet integration tests | git clone, npm install, npm run test:testnet passes against a live testnet node; at least 3 testnet transaction hashes posted | 60(300 − $240 advance) |
| M2: Hook and transfers | Week 2 | useCKBPasskey (register, login, sign); address derivation; seedless transfer flow; backup passkey example | Live testnet transfer signed with a passkey, tx hash published; hook has unit tests and typed API docs | $300 |
| M3: CLI and reference dApp | Week 3 | Published create-ckb-passkey-app on NPM; Next.js template; dApp deployed to Vercel | npx create-ckb-passkey-app my-test-app scaffolds and runs; reviewer registers a passkey and sends testnet CKB on iPhone, Android, or desktop via the public URL | $300 |
| M4: Docs, video, closure | Week 4 | Integration guide; security notes; 3-minute video; closure report | Guide live on GitHub Pages; video and report posted on Nervos Talk; fresh-machine setup from the guide works end to end | $300 |
8. Budget (all development time)
| Item | Detail | Est. effort | USD |
|---|---|---|---|
| Core SDK and tests | WebAuthn parsing, witness formatting, tx builders, testnet test suite | ~35 h | $450 |
| CLI, hook, and template | CLI, useCKBPasskey, Next.js UI | ~35 h | $450 |
| Docs, staging, video | Guide, security notes, Vercel hosting (free tier), video | ~20 h | $300 |
| Total | ~90 h | $1,200 |
Testnet use and free-tier hosting mean no costs beyond development time. A line-by-line spending comparison will be included in the closure report.
9. Risks and mitigations
| Risk | Mitigation |
|---|---|
| Overlap with JoyID/CCC is questioned | Week 1 review published; build on CCC where possible; focus on the scaffold, hook, tests, and docs |
| Platform differences in WebAuthn (Safari, Android, Windows) | Test on at least iOS Safari, Android Chrome, and desktop Chrome; document known quirks |
| Lock script witness format differs from assumptions | Confirm against deployed ckb-auth in Week 1 before building the hook |
| 4-week schedule slips | Scope-cut order: video polish first, then backup-passkey example, then second template option. The SDK, hook, CLI, and live transfer are not cut |
| Account loss from lost device | Recovery options documented and demonstrated; explicit unaudited warning shown in CLI output and docs |
10. Value to the Nervos ecosystem
- Accelerates Developer Onboarding: Cuts dApp integration time for WebAuthn/Passkey logins from days of cryptographic assembly down to a single terminal command.
- Demonstrates CKB’s Native Flexibility: Showcases how CKB’s Cell model and custom Lock Scripts natively support hardware cryptographic algorithms without protocol forks.
- Web5 / Mainstream Readiness: Provides the necessary infrastructure for dApp developers to build Web3 applications tailored for Web2 users without seed phrase friction.
11. Open source and reporting commitments
- All code and docs are MIT-licensed on GitHub, with continuous commits.
- Weekly progress updates in this thread and attendance at sync calls.
- Early closure will be requested if all deliverables finish ahead of schedule.
- Closure report: planned vs. actual, key decisions, fund usage, and lessons learned.