Skip to content
HeartBadge docs

C-Protocol

A universal meta-protocol for verifiable claim tokens on Bitcoin. Party-defined proofs, off-chain negotiation, on-demand settlement.

C-Protocol (Covenant Protocol) is a universal, platform-agnostic meta-protocol for creating and exchanging verifiable claim tokens that bind digital assets to specific conditions. HeartBadge uses C-Protocol for attestations, proofs, and the /drop API. This page explains how it works.

Reference: github.com/irl-os/c-protocol

Core principles

  1. Party-defined proofs and conditions. The protocol's integrity rests on conditions and authorities chosen by the covenanting parties. You designate who can attest to what — an event organizer for attendance, a shipping company for delivery, another member for co-presence.
  2. Immutable, on-demand settlement. Covenants are Bitcoin Script programs. Their rules are enforced by the mining network. On-chain settlement is a final state transition, not a requirement for every interaction.
  3. Privacy through off-chain negotiation. Claims are exchanged on private, peer-to-peer channels. Only final settlement transactions hit the public ledger.
  4. Composable and peer-to-peer. Any peer can be an issuer, holder, or verifier. The protocol extends CAT to allow attested assets to integrate into a wider ecosystem.

Architecture layers

Layer Role
Layer 1: Truth Bitcoin protocol — ultimate settlement and state machine
Layer 2: Logic Bitcoin Script — enforcement engine for on-chain settlement
Layer 3: Asset CAT Protocol — standard for representing covenant-governed assets
Layer 4: Attestation Proof Authorities and custody models for verification
Layer 5: Origination Where actions occur and claims are exchanged peer-to-peer

Proof Authorities (PAs)

A Proof Authority is any entity designated by the covenanting parties to attest to real-world state. The protocol is unopinionated about who can be a PA — the trust is entirely defined by the participants.

  • Context-specific. A PA's authority is limited to a specific domain. A shipping company API may be a PA for "proof of delivery" but not "proof of identity."
  • Ephemeral. A PA's authority can be time-bound. For an event, the organizer acts as a PA whose ability to issue valid proofs is only active during the event window.

In HeartBadge:

  • Event PAs attest that a member was present at an event
  • Quest PAs attest that a member completed an objective
  • Member PAs — other members — co-sign mutual presence

Canonical Obligations

The core transferable object is the Canonical Obligation — a signed data structure representing an offer or finalized receipt. This is what peers trade. 

{
  "type": "offer" | "receipt",
  "id": "unique_obligation_id",
  "issuer_pub": "public_key_of_issuer",
  "holder_pub": "public_key_of_current_holder",
  "token_info": { "chain": "BSV", "assetId": "...", "amount": 10000 },
  "condition_expr": "pa_attested:verify_sig(02a4..., 'event_checkin')",
  "expiry": 1757283600,
  "nonce": "random_bytes",
  "signatures": [ "signature_from_issuer" ]
}

The condition_expr field defines unlock requirements:

  • holder_sig — signature from the claim's holder
  • reveal:hash(H) — reveal a secret pre-image
  • time_lock:T — redeemable after time/block T
  • multi_sig:[pubA, pubB] — multiple signatures
  • pa_attested:verify_sig(PA_Key, proof) — PA signature over proof data

Protocol flow

  1. Reserve. An issuer locks an asset using a custody model.
  2. Offer. The issuer creates a signed Canonical Obligation specifying redemption conditions and required PA.
  3. Claim. A holder fulfills the condition_expr (e.g., obtains a signed attestation from the designated PA) and presents proof to the custody layer.
  4. Settle. The custody layer verifies the claim. On success, it either updates an off-chain ledger or executes on-chain settlement.

The /drop API

The /drop API is a stateless interface for creating, funding, claiming, and discovering Drops — self-custodied covenants holding assets and data. Drops are C-Protocol covenants that can be shared offline via NFC, QR, or local mesh.

Covenant types:

  • quick Drop — P2PKH, unlocked by holder signature
  • locked Drop — hashlock, unlocked by secret pre-image
  • timed Drop — time-locked, spendable after block/time
  • bridged Drop — cross-chain, requires bridge authority signature

Key endpoints:

  • POST /api/drop/create — initialize a covenant with optional payload
  • POST /api/drop/fund — submit signed tx to fund the covenant
  • POST /api/drop/claim — unlock the covenant with required proof
  • GET /api/drop/status/{dropId} — retrieve state and payload
  • GET /api/drop/discover — scan local network for nearby Drops

Co-sign attestations

A co-sign is a mutual attestation where two members act as PAs for each other:

  1. Members A and B bump badges (NFC or shared reader)
  2. Both generate a co-sign obligation: "A and B were present at location L at time T"
  3. Both sign with their identity keys
  4. The attestation is recorded — privately or published to messageboxes

Co-signs build trust in the network. A member with diverse co-signs from high-HeartBeat members has strong proof-of-humanity. A member with none has weaker standing.

Security considerations

  • Double-spend monitoring. Peers should run lightweight watcher nodes monitoring backing UTXOs. If a backing asset is spent, dependent off-chain obligations are revoked.
  • Issuer repudiation. Holders can require offers to be co-signed by a trusted quorum or demand script-based, non-custodial models.
  • Claim replay. Claims are single-use via nonces.

Related