Setting Up Verifiable Credentials on Blockchain

Verifiable Credentials (VCs) are a W3C standard for digital credentials that are tamper-evident and cryptographically verifiable. When anchored on a blockchain, they become on-chain verifiable credentials, providing a decentralized, trust-minimized system for identity and attestations. Unlike traditional certificates, VCs allow the holder to prove specific claims—like being over 18 or holding a degree—without revealing their entire identity or relying on a central issuer's server. The core components are the Issuer (creates the credential), the Holder (stores and presents it), and the Verifier (checks its validity).

To set up a basic on-chain VC system, you need a decentralized identifier (DID) for each actor. A DID is a unique URI that points to a DID Document containing public keys and service endpoints. For blockchain-based DIDs, you can use methods like did:ethr or did:polygonid. The issuer creates a signed credential, which is a JSON-LD or JWT-formatted document containing the claims, metadata, and a cryptographic proof. This credential is then issued to the holder's digital wallet. The immutable proof of issuance—often just the DID and a timestamp—can be recorded on-chain for public verification, while the sensitive credential data remains off-chain with the holder.

A common implementation uses the EIP-712 standard for structured data signing on Ethereum. An issuer's smart contract can create a credential by signing a hash of the credential data. Here's a simplified Solidity example for recording an issuance proof:

solidityCopy
function issueCredential(
    address holderDid,
    bytes32 credentialHash,
    uint256 expiry
) public onlyIssuer {
    credentials[holderDid] = Credential({
        hash: credentialHash,
        issuer: msg.sender,
        issuedAt: block.timestamp,
        expiresAt: expiry,
        revoked: false
    });
    emit CredentialIssued(holderDid, credentialHash);
}

The credentialHash is a keccak256 hash of the VC's core claims, allowing the verifier to check its integrity against the on-chain record without storing private data.

For verification, a holder presents a Verifiable Presentation. This is a wrapper, often a JWT, that contains the selective disclosures the holder consents to share and a proof signed by their DID's private key. The verifier's process is multi-step: 1) Check the presentation's cryptographic signature from the holder. 2) Resolve the issuer's DID from the blockchain to fetch their current public key. 3) Verify the issuer's signature on the embedded credential. 4) Query the issuer's on-chain smart contract to confirm the credential hash exists and is not revoked or expired. Libraries like Veramo or SpruceID's Kepler streamline this process.

Key considerations for production systems include revocation. On-chain registries, like a simple mapping of credential hashes to boolean states in a smart contract, allow issuers to revoke credentials instantly. Selective disclosure is achieved through zero-knowledge proofs (ZKPs), enabling holders to prove a claim (e.g., "age > 21") without revealing their birthdate. Gas costs for on-chain operations can be mitigated by using layer-2 solutions like Polygon or zkSync, or by batching updates to a merkle root stored on-chain, as used by protocols like Semaphore.

Use cases are expanding beyond KYC. In DeFi, VCs can enable under-collateralized lending by proving creditworthiness without exposing full history. DAOs use them for proof-of-personhood and voting rights. Developers should audit their credential schemas, manage private key security for holders via MPC wallets, and ensure compliance with regional data laws, as the credential subject is always the data controller. The future is interoperable, with projects like DIF's Universal Resolver working to connect different DID methods and VC formats across chains.

Before writing any code, you must understand the core components of a verifiable credential system. A VC is a tamper-evident digital credential with a cryptographic proof, typically a digital signature. The ecosystem involves three key roles: the issuer (who creates the credential), the holder (who receives and stores it), and the verifier (who requests and validates it). These components interact using decentralized identifiers (DIDs) as the foundational identity layer, allowing entities to be identified without a central registry.

You will need a development environment capable of handling cryptographic operations and interacting with a blockchain. Essential tools include Node.js (v18 or later) and a package manager like npm or yarn. For blockchain interaction, you'll need a library such as ethers.js (for Ethereum-compatible chains) or viem. To manage DIDs and VCs, we recommend using established libraries like did-jwt-vc by SpruceID for JWT-based credentials or Veramo as a more comprehensive agent framework. Start by initializing a new project and installing these core dependencies.

The next step is to configure a DID method. DIDs are the root identifiers for issuers and holders. For development, you can use a simple did:key method, which generates a DID directly from a public key. For production, you might choose a blockchain-anchored method like did:ethr (on Ethereum) or did:polygonid. Use your chosen library to generate a DID document and its associated private key, which must be stored securely, often using a Key Management System (KMS) or a hardware wallet for production-grade security.

With a DID established, you can now create your first verifiable credential. A VC is a JSON object conforming to the W3C Verifiable Credentials Data Model. It contains metadata (issuer, issuance date), credential subject data, and a proof section. You will use your library to sign this JSON structure with the issuer's private key, creating a Verifiable Presentation for sharing. The following is a conceptual example of a credential's structure before signing.

Finally, set up a minimal verification service. A verifier's job is to receive a presentation, check the cryptographic proof (signature), verify the issuer's DID on the blockchain or a resolver, and ensure the credential has not been revoked (often by checking a revocation registry like a smart contract or a credential status list). Start by writing a simple function that takes a presented VC, resolves the issuer's DID document, fetches the public key, and validates the signature using your library's built-in methods.

Verifiable Credentials (VCs) are digital, cryptographically secure attestations that enable trust without central authorities. Their implementation on blockchain relies on three core components: Decentralized Identifiers (DIDs) for the issuer and holder, schemas to define the credential's data structure, and smart contracts to manage the credential's lifecycle and revocation status. This architecture ensures credentials are tamper-proof, privacy-preserving, and interoperable across different systems.

A Decentralized Identifier (DID) is a self-owned, globally unique identifier not tied to a central registry. It is typically represented as a URI (e.g., did:ethr:0xabc123...). The DID is associated with a DID Document stored on a blockchain or other decentralized network, which contains public keys and service endpoints. This allows the credential issuer to cryptographically sign credentials and the holder to prove control of their identity without revealing personal information. Popular DID methods include did:ethr for Ethereum and did:web for web domains.

A credential schema defines the structure and data types of the claims within a VC. It acts as a template, specifying fields like firstName, degreeType, or issueDate. Schemas are often published as JSON documents, and their hash or URI is referenced within the credential. Using a schema ensures all credentials of a certain type (e.g., a university diploma) have a consistent format, enabling automated verification. Schemas can be stored on-chain for immutability or referenced via decentralized storage solutions like IPFS.

Smart contracts automate the rules and state management for VCs. A primary function is maintaining a revocation registry, often as an on-chain bitmap or merkle tree, allowing issuers to revoke credentials without exposing private data. Contracts can also enforce issuance logic, manage schema registries, and facilitate selective disclosure proofs. For example, an issuer contract might only mint a credential if the caller holds a specific NFT, embedding complex business logic directly into the trust system.

Here is a simplified example of issuing a VC using Ethereum and the EIP-712 standard for typed structured data signing, which provides a human-readable format for signatures:

solidityCopy
// Pseudocode for signing a credential off-chain
struct Credential {
    string @context;
    string type;
    address issuer;
    address holder;
    uint256 issuanceDate;
    string credentialSchema;
    bytes32 claimsHash; // Hash of the credential data
}
bytes32 digest = hashTypedDataV4(Credential, credentialData);
Signature sig = sign(digest, issuerPrivateKey);
// The signed credential and signature are sent to the holder.

When designing a VC system, key decisions include choosing a DID method compatible with your blockchain, defining granular schemas for flexibility, and determining which components require on-chain persistence versus off-chain storage for cost and privacy. Best practices involve using established libraries like Veramo or Trinsic for agent management, anchoring only minimal proofs (like revocation status) on-chain, and ensuring your schemas align with W3C standards for maximum interoperability across the decentralized identity ecosystem.

A Decentralized Identifier (DID) is a globally unique, cryptographically verifiable identifier controlled by its subject (e.g., a user, organization, or device). Unlike traditional usernames, a DID is not issued by a central authority. Instead, it is registered on a public ledger, like Ethereum or Polygon, using a smart contract known as a DID Registry. This contract maps a DID string (e.g., did:ethr:0x1234...) to its associated DID Document, which contains public keys, service endpoints, and verification methods essential for proving control.

For this guide, we will use the ERC-1056 (Ethr-DID) standard, a widely adopted, non-upgradeable registry contract. Deploying it creates a permanent, immutable ledger for DID operations. You can deploy it to any EVM-compatible network. Using a testnet like Sepolia or Mumbai is recommended for initial development. The contract's source code and deployment instructions are available on the uPort project's GitHub repository.

To deploy, you need a development environment like Hardhat or Foundry, and test ETH for gas fees. The core deployment script is straightforward. Here is a simplified Hardhat example:

javascriptCopy
// deploy.js
const hre = require("hardhat");
async function main() {
  const EtherDIDRegistry = await hre.ethers.getContractFactory("EthereumDIDRegistry");
  const registry = await EtherDIDRegistry.deploy();
  await registry.deployed();
  console.log("DID Registry deployed to:", registry.address);
}

Run npx hardhat run scripts/deploy.js --network sepolia. Save the contract address; it is the single source of truth for all DIDs in your system.

After deployment, the registry contract exposes key methods for the DID lifecycle: createDID() for initial registration, addVerificationMethod() to attach new public keys, revokeVerificationMethod() for key rotation, and setAttribute() to add service endpoints. All operations require a valid transaction signed by the DID controller's private key, ensuring only the owner can modify their identity. This establishes a self-sovereign model where users have full control without intermediaries.

The deployed registry's address becomes the core parameter for any client-side DID library, such as ethr-did or did-jwt. These libraries interact with the contract to create and resolve DIDs, forming the basis for issuing and verifying W3C Verifiable Credentials. With the registry live, you have built the foundational layer. The next step is to use this registry to create individual DIDs and their corresponding DID Documents.

Verifiable Credentials (VCs) are a W3C standard for digital credentials that are cryptographically secure, privacy-respecting, and machine-verifiable. A VC is a tamper-evident credential with a cryptographically signed claim, such as a university degree or professional license. The core components are the issuer (e.g., a university), the holder (the user), and the verifier (e.g., an employer). Unlike traditional digital certificates, VCs are designed to be user-centric, allowing the holder to store them in a digital wallet and present them selectively without relying on a central issuer for every verification. This model is foundational for self-sovereign identity (SSI).

The technical stack for blockchain-based VCs relies on Decentralized Identifiers (DIDs) and Verifiable Data Registries (VDRs). A DID is a unique, persistent identifier not tied to a central registry, often stored on a blockchain. A DID Document, which contains public keys and service endpoints, is resolved from the DID. The blockchain acts as the VDR, providing a decentralized, immutable root of trust for these documents. For example, the Sovrin Network uses a permissioned blockchain for its ledger, while Ethereum is commonly used for public, permissionless implementations via smart contracts that manage DID registries.

To issue a VC, an issuer creates a JSON-LD or JWT-based credential, signs it with their private key, and associates it with the holder's DID. A simple credential structure in JSON-LD might include issuer, issuanceDate, credentialSubject (the holder's DID and claims), and a proof section with the signature. The signature is typically created using linked data proofs like Ed25519Signature2020 or JsonWebSignature2020. The signed credential is then delivered to the holder's wallet. The blockchain is not used to store the credential itself, which preserves privacy, but to anchor the issuer's and holder's DIDs, making their public keys discoverable and trustworthy.

Verification is a multi-step process. When a holder presents a VC, the verifier must: 1) Resolve the issuer's DID from the blockchain VDR to fetch their current public key. 2) Check the credential's cryptographic proof against that public key. 3) Validate the credential status (e.g., ensure it hasn't been revoked). Revocation can be handled on-chain via a smart contract maintaining a revocation registry, or off-chain using accumulators. The verifier performs these checks without contacting the issuer directly, enabling offline and scalable verification. This decentralized verification is the key advantage over traditional PKI systems.

For developers, libraries like Veramo (TypeScript/JavaScript) and Aries Framework JavaScript provide essential tooling. Below is a simplified example using Veramo to create and verify a credential:

typescriptCopy
import { createAgent } from '@veramo/core';
import { CredentialPlugin } from '@veramo/credential-w3c';
// 1. Create agent with a DID resolver and key management
const agent = createAgent({ plugins: [new CredentialPlugin()] });
// 2. Issue a credential
const verifiableCredential = await agent.createVerifiableCredential({
  credential: {
    issuer: { id: 'did:ethr:0x123...' },
    credentialSubject: {
      id: 'did:ethr:0x456...',
      degree: { type: 'BachelorDegree', name: 'Computer Science' }
    }
  },
  proofFormat: 'jwt'
});
// 3. Verify the credential
const verificationResult = await agent.verifyCredential({
  credential: verifiableCredential
});

Key considerations for production systems include privacy (avoiding on-chain PII, using zero-knowledge proofs), revocation scalability, and interoperability across different DID methods and VDRs. Use cases extend from KYC/AML compliance and academic credentials to supply chain provenance and employment history. By leveraging blockchain as a neutral trust layer for DIDs, developers can build systems that return control of identity data to users while providing verifiers with cryptographically assured trust, moving beyond centralized identity providers.

The Credential Issuance Contract is the central authority in your system, responsible for minting Verifiable Credentials as non-transferable tokens (often Soulbound Tokens or SBTs). You'll typically write this in Solidity for Ethereum-compatible chains or in a language like Move for Aptos/Sui. The contract must define the credential schema, manage an allowlist of authorized issuers, and emit events for off-chain indexers. A critical function is issueCredential(address recipient, bytes32 credentialHash), which mints a token to the recipient's address, storing the credential's cryptographic hash on-chain as immutable proof.

For security, the contract should implement access control, often using OpenZeppelin's Ownable or AccessControl libraries, to ensure only approved issuer addresses can call the mint function. You must also decide on the token standard: ERC-721 for unique credentials, ERC-1155 for batch issuance, or a custom ERC-5484 for SBTs. The credential metadata (like name, issuanceDate, expiry) is usually stored off-chain (e.g., on IPFS or Arweave) with its content identifier (CID) or hash stored in the token's URI or within the contract state.

Here's a simplified Solidity snippet for an SBT-style issuer contract using ERC-721:

solidityCopy
// SPDX-License-Identifier: MIT
import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
import "@openzeppelin/contracts/access/Ownable.sol";
contract CredentialIssuer is ERC721, Ownable {
    mapping(address => bool) public authorizedIssuers;
    uint256 private _tokenIdCounter;
    event CredentialIssued(address indexed to, uint256 tokenId, string tokenURI);
    function issueCredential(address recipient, string memory tokenURI) external onlyAuthorized {
        uint256 tokenId = _tokenIdCounter++;
        _safeMint(recipient, tokenId);
        _setTokenURI(tokenId, tokenURI); // Stores off-chain metadata link
        emit CredentialIssued(recipient, tokenId, tokenURI);
    }
    modifier onlyAuthorized() { require(authorizedIssuers[msg.sender], "Not authorized"); _; }
}

After writing the contract, you must compile and deploy it to your chosen network (e.g., Ethereum Sepolia, Polygon Mumbai, or a zkEVM chain). Use development frameworks like Hardhat or Foundry. Hardhat is excellent for testing with scripts like npx hardhat run scripts/deploy.js --network mumbai. Ensure you verify the contract source code on block explorers like Etherscan or Polygonscan to establish transparency and allow anyone to audit the issuance logic. The deployment address becomes the canonical issuer DID for your credential system.

The final step is to integrate the contract with your backend issuance service. Your server (from Step 2) will call the contract's issueCredential function via a Web3 library like ethers.js or viem, signing the transaction with the issuer's private wallet. This creates a permanent, tamper-proof record on the blockchain. The emitted CredentialIssued event allows indexers (like The Graph) to track all credentials minted, enabling efficient querying for verifiers without scanning the entire chain.

Selective disclosure is the core privacy feature of verifiable credentials. It allows a credential holder to prove a specific claim—like being over 21 years old—without revealing their exact birth date, passport number, or any other extraneous data stored in the credential. This is achieved using zero-knowledge proofs (ZKPs), cryptographic protocols that enable one party (the prover) to convince another (the verifier) that a statement is true without conveying any information beyond the validity of the statement itself. In the context of blockchain-based credentials, ZKPs ensure user data remains off-chain and private, while the proof of its validity is verified on-chain.

To implement this, you typically work with a ZK-SNARK or ZK-STARK circuit. The credential data (the witness) is used as a private input to this circuit. The public input and the circuit's logic encode the specific claim to be proven. For example, a circuit could be programmed to output true only if a privately inputted birthdate is more than 21 years ago from a public currentDate. Libraries like Circom or SnarkJS are commonly used to write and compile these circuits. The output is a proving key (used to generate proofs) and a verification key (used to verify them), often represented as verifier smart contracts.

Here is a simplified conceptual flow using a Solidity verifier and an off-chain prover:

1. Credential Issuance: An issuer signs a credential containing user attributes (e.g., {"dob": "1990-01-01", "country": "US"}) and provides it to the user off-chain.
2. Proof Generation: The user, acting as the prover, runs their credential data through the pre-compiled ZK circuit. They generate a proof (e.g., zkProof) that attests to the statement "dob < currentDate - 21 years".
3. On-Chain Verification: The user submits only the zkProof and the necessary public inputs (like the currentDate and the issuer's public key) to a verifier contract. The contract, using the embedded verification key, checks the proof's validity without ever seeing the dob.

This process decouples data from verification, minimizing on-chain footprint and maximizing privacy.

For developers, key considerations include choosing the right proving system (ZK-SNARKs require a trusted setup but have small proof sizes, while ZK-STARKs are trustless but generate larger proofs), managing circuit complexity and gas costs for on-chain verification, and securely handling the off-chain witness data. Frameworks like Sismo's Hydra-S2, Semaphore, or Polygon ID's Issuer Node abstract much of this complexity, providing SDKs for integrating selective disclosure into applications. The end result is a user experience where authentication or authorization can occur based on verified attributes, with the underlying personal data never leaving the user's device.

The verification flow is the process where a verifier checks the validity of a presented credential. This involves several cryptographic checks: verifying the digital signature from the issuer to ensure the credential hasn't been tampered with, checking the credential's status (e.g., on a revocation registry) to confirm it's still valid, and ensuring the credential schema matches expectations. For blockchain-based credentials, this often means querying the relevant smart contract or decentralized identifier (DID) registry. Tools like the W3C Verifiable Credentials Data Model provide the standard framework for these operations.

The presentation flow is initiated by the holder. Using a wallet or agent, the holder creates a Verifiable Presentation—a wrapper for one or more Verifiable Credentials. Crucially, the holder can use Selective Disclosure (e.g., via BBS+ signatures) to reveal only specific attributes from a credential, preserving privacy. For example, a user could prove they are over 18 from a driver's license credential without revealing their exact birth date or address. The presentation is then sent to the verifier, typically via a QR code scan or a direct challenge-response protocol.

A common implementation uses a challenge-response mechanism to prevent replay attacks. The verifier generates a unique, time-bound nonce (a random number used once) and sends it as a challenge to the holder. The holder must sign the presentation, including this nonce, with their private key. This holder binding proof demonstrates that the presenter actually controls the DID to which the credential was issued, a critical security step. Libraries like veramo or aries-framework-javascript provide built-in methods for handling these complex interactions.

Here's a simplified code example for a verifier checking a presentation using the Veramo SDK:

javascriptCopy
const result = await agent.verifyPresentation({
  presentation: verifiablePresentation, // The presented VP
  challenge: 'a1b2c3d4-e5f6-7890', // The nonce sent in the challenge
  domain: 'example-verifier.com', // Verifier's domain for context
});

if (result.verified) {
  // Checks passed: signature, status, schema, and challenge.
  const credentialSubject = result.presentation.verifiableCredential[0].credentialSubject;
  console.log('Verified attribute:', credentialSubject.degreeType);
}

For production systems, you must also design the user experience. This includes creating clear interfaces in your application for verifiers to request credentials (specifying the required credential type and fields) and for holders to review and consent to sharing their data. Integrating with wallet protocols like WACI or OpenID4VC can streamline this cross-application communication. The final architecture establishes a cryptographically secure, privacy-respecting flow for trustless verification.

Implementing verifiable credentials (VCs) in production requires careful planning beyond the technical setup. Key operational decisions include choosing a decentralized identifier (DID) method suited to your use case—such as did:ethr for Ethereum or did:key for simplicity—and selecting a verifiable data registry. For public, permissionless attestations, an L1 like Ethereum or a low-cost L2 like Polygon is ideal. For private consortiums, a private Ethereum network or a dedicated chain using a framework like Hyperledger Besu may be appropriate. You must also design your credential schema with privacy in mind, minimizing the on-chain footprint to identifiers and hashes while storing sensitive claim data off-chain.

Security and user experience are paramount. Always use cryptographic libraries like @veramo/core or daf-core instead of rolling your own signing logic. For the holder's wallet, integrate with established solutions such as MetaMask Snaps for VCs or SpruceID's Sign-In with Ethereum toolkit to manage private keys and presentations securely. Thoroughly audit your smart contracts for the Verification Registry and Revocation Registry, as these are critical trust anchors. Consider gas optimization techniques, like using EIP-712 typed structured data for signatures and batching revocation updates, to keep costs predictable for issuers and verifiers.

To continue your development, explore these resources. The W3C Verifiable Credentials Data Model is the foundational specification. For Ethereum-centric development, the Veramo Framework provides a modular toolkit for creating and managing DIDs, VCs, and VP. The Decentralized Identity Foundation (DIF) hosts working groups and specifications for interoperability. To see complete examples, examine the source code for projects like Civic's Passport or Ontology's DID and VC implementation. Finally, join communities in the DIF Discord or W3C VC Working Group to stay updated on evolving standards and best practices in decentralized identity.