Documentation

Issue and claim participation badges on CKB. Built for events.

Use ckb-pop-kit to model participation scopes, issue signed claims, verify eligibility, and mint non-transferable badges on Nervos CKB. Physical events are one flow. Online hackathons, async programs, and community campaigns are all first-class issuance flows.

Get started Integration guide npm package

Package ckb-pop-kit

Latest published 0.2.0

Reference flows QR + claim

Contracts 2

Install

Start with the kit, then decide how much of CKB PoP you want to run.

Install the kit when you want the protocol primitives inside your own product. Run the backend when you want the full CKB PoP server-side surface for claims, QR verification, badge observation, and manifest discovery.

Package install

npm install ckb-pop-kit

Import the kit

import {
  createReferenceCkbPresenceModule,
  buildSignedClaimMessage,
  encodeSignedClaimToken,
  parseSignedClaimToken,
} from 'ckb-pop-kit'

const pop = createReferenceCkbPresenceModule()

Backend setup

cd scripts
cargo run

CKB_NETWORK=testnet
CKB_RPC_URL=https://testnet.ckb.dev/rpc
DATABASE_URL=sqlite:./ckb_pop.db?mode=rwc
ALLOWED_ORIGINS=https://your-app.example

Use the backend when you want the complete CKB PoP server-side flow. If you already run your own backend, wire the kit into that stack and keep the same proof, claim, and badge model.

Flows

Different proof rituals, one badge model.

The contracts still enforce one badge per (scope_id, address). What changes is how a user proves they earned it.

verify-qr.ts

Integrations

Wire this into your app without giving up self-custody.

The intended integration model is: your app decides eligibility, your backend signs the claim, participant still signs the actual mint. Below are the practical patterns you need.

Hackathon completion flow

What the integration must do

Backend API

Backend routes your app can call

GET/api/module/manifest

Discover proof drivers, artifact drivers, policy extensions, runtime HRP, and reference routes.

POST/api/events/create

Create a participation scope in the backend.

POST/api/claims/issue

Issue a signed claim token for an eligible participant. This is useful when completion is decided by your backend before the participant signs the mint.

Issue request

{
  "event_id": "hack-2026",
  "recipient_address": "ckt1winner...",
  "proof_driver": "signed-claim",
  "proof_ref": "submission-42",
  "issuer_address": "ckt1organizer...",
  "issuer_signature": "0x..."
}

POST/api/claims/verify

Verify a signed claim token before the participant mints the badge.

Verify request

{
  "claim_token": "...",
  "address": "ckt1winner..."
}

GET/api/badges/observe

Observe minted badges by address using the backend cache and chain sync logic.

Contracts

Minimal on-chain facts. Generic off-chain semantics.

The contracts do not interpret “attendance,” “hackathon,” or “course completion.” They only enforce ownership, uniqueness, and immutability around a scope id and a recipient.

DOB Badge metadata

{
  "protocol": "ckb-pop",
  "version": "1",
  "scope_id": "hack-2026",
  "scope_kind": "hackathon",
  "participation_mode": "online",
  "issuer": "ckt1...",
  "proof_hash": "0x..."
}

Scope Anchor metadata

{
  "scope_id": "hack-2026",
  "scope_kind": "hackathon",
  "creator": "ckt1...",
  "metadata_hash": "0x..."
}

Reference surfaces

The app frontend demonstrates the same system.

Verify

Physical QR-based proof flow for in-person participation.

Claim

Online claim-token flow for hackathons, programs, and async completions.

Create

Reference organizer UI for creating scopes and anchors.

Integrate

Manifest-backed capability discovery for external builders.