CKB PoP Docs Scope-based participation
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.

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
Dynamic QR proof
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.