Verifiable Credentials on Bitcoin: Architecture and Implementation Patterns

Jul 3, 2026

Verifiable Credentials on Bitcoin: Architecture and Implementation Patterns

Introduction

Verifiable Credentials (VCs) carry the claims of decentralized identity. DIDs give the identifiers, and VCs carry the claims: for example, a university degree, a professional license, proof of employment, or KYC status. If the issuer and the holder use Bitcoin-anchored DIDs, DID resolution gets the security properties of Bitcoin. Other parts of the trust chain, such as key management and status lists, do not get these properties. The VC model works with any DID method.

The Verifiable Credential Model

The VC Data Model 2.0 defines five roles: issuer, holder, subject, verifier, and verifiable data registry (Ecosystem Overview). This post uses the three roles that exchange credentials:

  • Issuer: An entity that makes claims about a subject and signs them cryptographically. Examples: universities, employers, and government agencies.
  • Holder: An entity that stores credentials and presents them when necessary. The holder is often, but not always, the subject of the credential (holder). A holder is usually a person or an organization.
  • Verifier: An entity that receives a credential presentation and checks its validity.

In this post, Bitcoin is part of the verifiable data registry, because it anchors the DIDs of the issuer and the holder.

The important difference from traditional systems is that the verifier does not need to contact the issuer to check the signature. The signature is self-contained. The verifier checks it against a public key in the DID document of the issuer.

Anatomy of a Verifiable Credential

A VC is a JSON (or JSON-LD) document with a specific structure:

{
  "@context": ["https://www.w3.org/2018/credentials/v1"],
  "type": ["VerifiableCredential", "ProfessionalLicense"],
  "issuer": "did:ion:EiA3...",
  "issuanceDate": "2026-03-16T00:00:00Z",
  "credentialSubject": {
    "id": "did:ion:EiD7...",
    "licenseType": "Software Engineering",
    "jurisdiction": "US-TX"
  },
  "proof": {
    "type": "JsonWebSignature2020",
    "created": "2026-03-16T00:00:00Z",
    "verificationMethod": "did:ion:EiA3...#key-1",
    "jws": "eyJhbGciOi..."
  }
}

The proof section contains a digital signature over the credential content. The key for this signature is in the DID document of the issuer, and the verifier gets it through DID resolution.

Note: This example uses the conventions of VC Data Model 1.1: the https://www.w3.org/2018/credentials/v1 context, issuanceDate, and a JsonWebSignature2020 proof with the signature in a jws member. VC Data Model 2.0 became a W3C Recommendation on 15 May 2025. It uses the https://www.w3.org/ns/credentials/v2 context, and it replaces issuanceDate with validFrom (Validity Period). It secures a credential with an embedded DataIntegrityProof or with the enveloped VC-JOSE-COSE form (VC Data Model 2.0, section 4.12). The W3C VC Working Group discontinued the JsonWebSignature2020 work in 2024 (Discontinued Draft).

Issuance Flow with Bitcoin-Anchored DIDs

  1. Issuer setup: The issuer makes a DID that is anchored to Bitcoin. Its DID document lists the public keys that can sign credentials.
  2. Subject identification: The holder presents their own DID to the issuer, through the verification process that the issuer requires.
  3. Credential creation: The issuer makes the VC. It puts the DID of the holder and the related claims in credentialSubject.
  4. Signature: The issuer signs the credential with a private key. The public key for that private key is in the DID document of the issuer.
  5. Delivery: The issuer sends the signed credential to the holder. The holder stores it in a credential wallet.

ION was a widely known Bitcoin-anchored DID method. Microsoft Entra Verified ID supported ION only in preview, until December 2023, and now tells users how to move to did:web (Microsoft Learn). did:btcr2 is an alternative that anchors directly to Bitcoin, and its authors continue to develop it. Its specification states: "This specification is still under active development and may be subject to breaking changes" (did:btcr2 specification). Before you choose a method, compare its maturity, tools, and resolution requirements.

Verification Flow

  1. Presentation: The holder makes a Verifiable Presentation (VP) that contains one or more VCs. The holder signs the VP with the private key of their own DID.
  2. DID resolution: The verifier resolves the DID of the issuer to get the public keys of the issuer. The resolution process depends on the DID method. For example, did:ion uses Bitcoin and the Sidetree network, and did:btcr2 uses Bitcoin and sidecar data or CAS.
  3. Signature check: The verifier checks the signature of the credential against the resolved public key of the issuer.
  4. Status check: If the credential has a credentialStatus entry (Status), the verifier checks it. This check shows if the issuer revoked the credential.
  5. Trust decision: The verifier decides if it trusts the issuer for this type of claim (Trust Model).

For the signature check, the verifier does not contact the servers of the issuer. It resolves the DID of the issuer instead. Revocation is the exception: a status check (step 4) usually gets a status list from a URL that the issuer publishes.

For Sidetree-based methods such as ION, the Bitcoin transaction anchors only an Anchor String. The Anchor String is an operation count and the content identifier of a batch index file (Sidetree specification). The operation data for the DID documents is off-chain, in content-addressable storage (IPFS). A resolver must get and replay that off-chain data. The Sidetree specification also describes caveats of this model, such as late publishing.

Implementation Patterns

Credential Wallet Architecture

A holder wallet must be able to:

  • Manage many DIDs and key pairs
  • Store credentials securely (encrypted at rest)
  • Make presentations with selective disclosure
  • Process credential refresh and revocation notices

Revocation Strategies

Two common approaches for Bitcoin-anchored systems are:

  • Status lists: The issuer publishes a bitstring status list. Each position in the list is for one credential. For the revocation purpose, a 1 bit means that the issuer revoked the credential. The list is itself a credential (BitstringStatusListCredential) with its own proof, and the issuer serves it at a URL (BitstringStatusListCredential). The integrity of the list does not depend on Bitcoin. An issuer can also anchor a hash of the list to Bitcoin as an extra check, but the standard does not define this step.
  • Expiration: The issuer gives short-lived credentials with a validUntil value (Validity Period) and issues them again at intervals. This approach removes the need for a status list, but the issuer must issue credentials again often.

Selective Disclosure

A verification does not always need the full credential. Methods such as SD-JWT (Selective Disclosure for JSON Web Tokens, RFC 9901, November 2025) let holders show only specific fields. For example, if the issuer includes an "over 21" claim, the holder can disclose only that claim. The holder then does not show their birth date or name.

Conclusion

Verifiable Credentials make DIDs into practical tools. If you anchor DIDs to Bitcoin, DID resolution does not depend on a central registry. Status lists and other services can still depend on infrastructure that the issuer operates. The VC model works with any DID method, and the choice of anchor layer depends on the use case.

The core W3C VC Data Model is a stable Recommendation. The W3C interoperability report lists implementations from several organizations. The mechanisms that secure credentials and the tools for DID methods continue to change. The challenges that remain are the user experience of key management, revocation at scale, and interoperability between ecosystems.

Jintek LLC