How to Architect a Verifiable Credentials Framework for Green Certifications

Verifiable Credentials (VCs) are a W3C standard for creating digital, cryptographically secure attestations. For sustainability, they enable trusted proof of claims like carbon offsets, recycled material content, or energy efficiency. A VC framework consists of three core roles: the Issuer (e.g., a certification body), the Holder (the entity receiving the credential, like a company), and the Verifier (a partner or regulator). The credential itself is a JSON-LD or JWT-signed data package containing the claim, issuer metadata, and proof, which is held in a digital wallet. This structure moves away from siloed, paper-based certificates to interoperable digital proofs.

Architecting this system requires selecting a Decentralized Identifier (DID) method for the issuer. DIDs are self-sovereign identifiers, like did:ethr:0xabc123..., controlled by cryptographic keys, not a central database. The issuer creates a DID Document on a verifiable data registry, typically a blockchain like Ethereum, Polygon, or a dedicated Layer 2. This anchors the issuer's public keys and service endpoints, allowing any verifier to resolve the DID and confirm the credential's origin. Using blockchain here provides global, censorship-resistant availability for the issuer's public keys, establishing cryptographic trust without requiring pre-existing relationships.

The credential issuance flow involves the Holder presenting a DID to the Issuer. The Issuer creates a Verifiable Credential, signing it with their private key. The signed credential, containing the sustainability claim (e.g., "renewableEnergyUsage": "85%"), is delivered to the Holder's wallet. Crucially, the credential is stored off-chain (in the wallet or cloud storage) for privacy and efficiency; only the minimal proof data, like the issuer's DID, needs to be on-chain. The Holder can then present cryptographically verifiable proof without revealing the entire credential using Verifiable Presentations and selective disclosure protocols like BBS+ signatures.

For verification, a relying party (Verifier) receives a Verifiable Presentation from the Holder. The verifier's system performs several checks: 1) Verify the cryptographic signature on the presentation and credential against the Issuer's public key (resolved via their DID), 2) Check the credential's status against a revocation registry (e.g., a smart contract or a verifiable data registry) to ensure it hasn't been revoked, and 3) Validate that the credential schema (the data structure) matches expectations. This entire process can be automated, enabling real-time, trust-minimized verification for supply chain audits or green financing applications.

Implementing this requires specific tooling. For development, consider SDKs like Veramo (TypeScript) or Aries Framework JavaScript. For issuer DID management, services like SpruceID's Kepler or Microsoft Entra Verified ID can be used. A basic credential schema for a carbon credit might be defined using JSON Schema and published to a registry. Smart contracts on chains like Celo or Polygon PoS are often used for gas-efficient DID anchoring and revocation registries, aligning with the sustainability focus of the credentials themselves.

Key architectural decisions include choosing between public-permissionless vs. private-permissioned networks based on the consortium's needs, defining data models for interoperability using schemas from Trust Over IP or GS1, and planning for credential revocation. A successful framework creates an ecosystem where green claims are machine-verifiable, privacy-respecting, and globally interoperable, reducing fraud and administrative overhead in environmental, social, and governance (ESG) reporting.

A robust verifiable credentials (VC) framework for green certifications, such as carbon offsets or renewable energy credits, is built on three foundational layers. The Data Layer handles the raw information: emission calculations, audit reports, and asset metadata, which must be sourced from trusted oracles and IoT devices. The Credential Layer is where this data is cryptographically signed into a W3C-compliant Verifiable Credential by an issuer (e.g., a standards body). Finally, the Presentation & Verification Layer allows holders (companies) to share selective proofs with verifiers (regulators, partners) without revealing the underlying sensitive data, using protocols like Selective Disclosure.

The system's trust model is decentralized. Instead of a single database, trust is anchored in public key infrastructure (PKI) and decentralized identifiers (DIDs). Each participant—issuer, holder, verifier—controls their own DID. The issuer's public key, resolvable via a DID method like did:web or did:ion, is used to verify the credential's signature. This architecture eliminates centralized points of failure and censorship. For high-value certifications, the credential's issuance or revocation status can be anchored to a public blockchain like Ethereum or Polygon using verifiable data registries, providing a global, tamper-proof audit trail.

Key prerequisites include establishing the trust triangle roles. The Issuer must be a recognized authority (e.g., Verra, Gold Standard) with a secure key management system. The Holder (a project developer) needs a digital wallet capable of storing VCs, such as SpruceID's Credible or Trinsic's ecosystem. The Verifier (a corporate buyer) requires a verification service SDK. All parties must agree on a credential schema defining the data structure (e.g., CarbonCreditV1) published to a schema registry like the Ethereum Attestation Service or Cheqd Network to ensure interoperability.

For the technical implementation, you will need to choose a SDK or library for VC operations. Popular options include Veramo (TypeScript), Aries Framework JavaScript (AFJ), or SpruceID's SDKs. These handle core tasks: creating DIDs, signing credentials, and generating zero-knowledge proofs. A typical architecture involves an issuer backend service that pulls data from internal systems, creates VCs using the SDK, and optionally writes a revocation status to a ledger. The credential is then delivered to the holder's wallet via a QR code or direct push notification.

Scalability and privacy are critical. Batch issuing thousands of carbon credits requires efficient BBS+ signatures for selective disclosure or zk-SNARKs for complex proof logic. The architecture should support off-chain credential storage (e.g., in the holder's wallet) with on-chain verification anchors to avoid bloating the blockchain. Furthermore, designing for cross-chain verification is increasingly important, allowing a credential issued on one network to be verified on another, facilitated by protocols like IBC or CCIP for trustless state attestation.

The W3C Verifiable Credentials (VC) Data Model provides a standard format for creating cryptographically secure, privacy-preserving digital credentials. For green certifications—like carbon offset validation, renewable energy credits, or sustainable supply chain provenance—this model structures a credential as a JSON-LD document containing claims (e.g., "Company X offset 1000 tons of CO2 in 2024"), metadata about the issuer, and proof mechanisms. The core components are the issuer, holder, and credentialSubject. Decentralized Identifiers (DIDs) are the foundational identity layer, giving each participant—issuer, holder, and verifier—a self-sovereign identifier (e.g., did:ethr:0xabc...) controlled via cryptographic keys, eliminating reliance on centralized databases.

Architecting the framework begins with defining the credential schema. This JSON schema specifies the exact structure of the data for your green claim. For a renewable energy certificate, your schema might define required fields like energySource (e.g., "solar"), megawattHoursGenerated, generationPeriod, and certificationBody. Using a DID as the issuer identifier in the schema (issuer.id) ensures the credential's origin is cryptographically verifiable. The credential is then signed by the issuer's private key, creating a digital signature embedded in the proof field. This signature binds the data to the issuer's DID, making the credential tamper-evident and authentic.

The holder—often the entity earning the certification—stores the VC in a digital wallet. Crucially, the wallet must support the chosen DID method (like did:ethr for Ethereum) and the VC data model. When a verifier (e.g., a regulator or a B2B partner) requests proof of the green claim, the holder does not send the raw credential. Instead, they create a Verifiable Presentation. This is a new signed package that can contain one or more VCs, and importantly, allows for selective disclosure. The holder can prove they have a valid carbon offset credential without revealing the exact tonnage, preserving commercial privacy while proving compliance.

For implementation, developers can use libraries like veramo (JavaScript/TypeScript) or aries-framework-javascript. Below is a simplified example of issuing a VC for a carbon offset using Veramo's core interfaces.

typescriptCopy
import { createAgent } from '@veramo/core';
import { CredentialPlugin } from '@veramo/credential-wdl';
// ... other plugin imports

// 1. Create an agent with a DID resolver and key management
const agent = createAgent({
  plugins: [
    new CredentialPlugin(),
    // ... configure DID provider (e.g., did:ethr) and key manager
  ],
});

// 2. Define the credential payload according to your schema
const verifiableCredential = await agent.createVerifiableCredential({
  credential: {
    issuer: { id: 'did:ethr:0xissuerAddress' },
    credentialSubject: {
      id: 'did:ethr:0xholderAddress',
      carbonOffsetTonnes: 1000,
      standard: 'Verra VCS',
      vintageYear: 2024
    },
  },
  proofFormat: 'jwt', // or 'lds'
});
// `verifiableCredential` is now a signed JWT containing the VC

Key architectural decisions involve choosing proof formats and DID methods. JWT proofs are compact and widely supported, while JSON-LD Signatures (LDS) with Data Integrity proofs are more expressive for complex schemas. For public verification, a DID method like did:ethr anchors the issuer's public key to a blockchain, allowing any verifier to resolve the DID and check the signature. For higher privacy, did:key or did:jwk can be used. The system must also include a VC Status mechanism, such as a revocation registry (e.g., using Ethereum smart contracts), to invalidate certifications if an issuer discovers erroneous data or fraud.

Successful deployment requires integrating with existing registries like Verra or Gold Standard. The VC framework does not replace these authoritative bodies but provides a standardized, interoperable digital wrapper for their certifications. The verifier's role is automated through verification policies that check the credential's signature, issuer DID, schema conformance, revocation status, and expiration. This architecture creates a trust triangle where issuers sign claims, holders control their data, and verifiers get cryptographically assured proofs, enabling scalable, automated, and fraud-resistant green credentialing systems for ESG reporting and regulatory compliance.

An issuer service is a secure backend application responsible for the credential lifecycle. Its primary functions are to generate W3C-compliant Verifiable Credentials, sign them with the issuer's cryptographic keys (like Ed25519 or secp256k1), and publish the corresponding Decentralized Identifiers (DIDs) and public keys to a verifiable data registry, such as the Ethereum blockchain or ION network. This establishes the trust anchor for all credentials you issue.

Start by defining your credential schema. This JSON-LD or JSON Schema document structures the data within your green credential, specifying required fields like carbonOffsetAmount, certificationStandard (e.g., Verra VCS), issuanceDate, and expirationDate. Publish this schema to a persistent, immutable storage layer like IPFS or a blockchain to ensure verifiers can reference it. A schema registry like the Ethereum Attestation Service can be used for on-chain schemas.

Next, implement the core issuance logic. Using a library like did-jwt-vc (JavaScript/TypeScript) or verifiable-credentials (Python), your service must create a VC JSON object, sign it, and produce a JWT or JSON-LD proof. The code snippet below shows a simplified issuance flow:

javascriptCopy
const vc = await createVerifiableCredential({
  issuer: 'did:ethr:0x123...',
  credentialSubject: {
    id: 'did:example:holder',
    carbonOffsetTonnes: 150,
    projectId: 'VCS-1234'
  },
  issuanceDate: new Date().toISOString(),
  expirationDate: '2025-12-31T23:59:59Z'
});
const vcJwt = await createVerifiablePresentationJwt(vc, issuerSigner);

Key management is critical. The issuer's private key must be stored securely, preferably in a hardware security module (HSM) or a cloud KMS like AWS KMS or Azure Key Vault. Never embed private keys in source code. Your service should also manage DID Document updates, ensuring the public key in the document matches the signing key and is resolvable by verifiers via a universal resolver.

Finally, design the API endpoints for your service. Essential endpoints include POST /api/issue (to create a credential), GET /api/credentials/{id} (to fetch a VC status), and GET /api/.well-known/did.json (for DID resolution). Implement robust authentication (e.g., OAuth2 tokens) for the issuance endpoint to ensure only authorized entities can request credentials. Use HTTPS and standard HTTP status codes.

With the issuer service running, you have established the trusted source for your green credentials. The next step is to build the verifier service that will check these credentials' validity, signatures, and revocation status on-chain.

A holder wallet is a software application that allows an entity (like a company or individual) to manage their Decentralized Identifiers (DIDs), cryptographic keys, and Verifiable Credentials (VCs). Unlike a traditional cryptocurrency wallet, its primary function is identity and attestation management. For our green certification framework, a corporate entity would use this wallet to receive, store, and later present credentials like a CarbonCreditAudit to a verifier. The foundational standard for building such wallets is the W3C DID Core specification.

The first technical task is generating a DID and its associated cryptographic keys. We'll use the did:key method for simplicity and self-sovereignty. The following Node.js code snippet uses the @digitalbazaar/did-method-key and crypto-ld libraries to create a new DID with an Ed25519 key pair, which is ideal for signing VCs. This key pair is the core of the holder's digital signature capability.

javascriptCopy
import { Ed25519VerificationKey2020 } from '@digitalbazaar/ed25519-verification-key-2020';
import { driver } from '@digitalbazaar/did-method-key';
const didKeyDriver = driver();

async function createHolderDid() {
  const keyPair = await Ed25519VerificationKey2020.generate();
  const { didDocument, keyPairs } = await didKeyDriver.fromKeyPair({ keyPair });
  
  console.log('Holder DID:', didDocument.id);
  console.log('Public Key (Base58):', keyPair.publicKeyMultibase);
  // Securely store the private key
  return { didDocument, keyPairs };
}

With the DID created, the wallet must implement secure key storage. The private key material should never be exposed to the frontend or stored in plaintext. Best practices include using hardware security modules (HSMs), secure enclaves on mobile devices, or encrypted keystores with strong passphrases. The wallet's interface should provide methods to: - Receive a VC: Accept and validate a signed credential from an issuer. - Store VCs: Maintain an encrypted local store or reference to decentralized storage like IPFS. - Create a Verifiable Presentation (VP): Select specific credentials, add a proof, and present them to a verifier. This architecture ensures the holder maintains control over their data, sharing only what is necessary via presentations.

The final core capability is generating a Verifiable Presentation. A VP is a wrapper for one or more VCs, cryptographically signed by the holder to prove possession and control. It can also include a challenge and domain from the verifier to prevent replay attacks. Using the jsonld-signatures suite, the wallet can create a VP as shown in the conceptual code below. This VP is what the verifier's system will ultimately validate to grant access or confirm status.

javascriptCopy
import { vc } from '@digitalbazaar/vc';
// Assuming `holderKeyPair` is the securely accessed signing key
// and `carbonCreditCredential` is the VC received from the issuer.

const verifiablePresentation = await vc.createPresentation({
  verifiableCredential: [carbonCreditCredential],
  holder: holderDidDocument.id
});

const signedPresentation = await vc.signPresentation({
  presentation: verifiablePresentation,
  suite: new Ed25519Signature2020({ key: holderKeyPair }),
  challenge: 'verifier-supplied-nonce-123', // Anti-replay
  domain: 'green-verifier.example.com'
});
// `signedPresentation` is now ready to be sent to the verifier.

For production systems, consider integrating with existing wallet standards to improve interoperability. The W3C Verifiable Credentials API draft defines a standard browser interface, while DIDComm enables secure, private messaging between wallets for credential exchange. The holder wallet is not an island; it must be designed to interact seamlessly with issuers (from Step 1) and verifiers (Step 3), forming the user-centric pillar of the trust triangle in a verifiable credentials ecosystem.

The verifier service is a backend application responsible for evaluating credential presentations. Its primary function is to execute a verification policy—a set of programmable rules defining what constitutes a valid credential for a specific use case. For a green certification, this policy might check that the credential: is issued by a trusted entity (the issuer's DID), contains specific claims (e.g., "carbonOffsetTons" > 100), uses an accepted credential schema, and has a valid cryptographic proof (like a BBS+ signature). The service does not need a blockchain connection for every verification, as it validates the proof against the issuer's public DID, which can be resolved from a decentralized ledger like Ethereum or ION.

A robust verifier service architecture typically involves three key stages. First, Presentation Reception: The service exposes an API endpoint (e.g., /api/verify) to accept a Verifiable Presentation (VP). This VP is a wrapper, often a JSON-LD or JWT, containing the holder's Verifiable Credential (VC) and a proof demonstrating they control the credential. Second, Policy Evaluation: The service's core logic parses the VP, resolves the issuer's DID Document to fetch their public key, and verifies the cryptographic signatures. It then checks the credential's claims against the business logic defined in the verification policy. Third, Result & Action: The service returns a clear result (valid/invalid) and can trigger downstream actions, such as granting API access, minting a soulbound token (SBT) on-chain as proof of verification, or logging the event for audit.

Here is a simplified code example using the @veramo framework to verify a credential presentation. This snippet focuses on the core verification call after receiving a VP string.

javascriptCopy
import { createAgent } from '@veramo/core';
import { CredentialPlugin } from '@veramo/credential-w3c';
import { DIDResolverPlugin } from '@veramo/did-resolver';
import { getResolver } from 'web-did-resolver';

// 1. Create a Veramo agent with necessary plugins
const agent = createAgent({
  plugins: [
    new DIDResolverPlugin({
      resolver: getResolver(), // Configures resolver for DIDs
    }),
    new CredentialPlugin(),
  ],
});

// 2. Function to verify a received Verifiable Presentation
async function verifyPresentation(vpString) {
  try {
    const verificationResult = await agent.verifyPresentation({
      presentation: vpString, // The VP JWT or JSON-LD
      fetchRemoteContexts: true, // Fetches linked JSON-LD contexts
    });

    // 3. Check the result and apply business logic
    if (verificationResult.verified) {
      console.log('VP Verified. Claims:', verificationResult.presentation.verifiableCredential);
      // Your logic here: grant access, mint token, etc.
      return { verified: true, claims: verificationResult.presentation.verifiableCredential };
    } else {
      console.error('VP Failed:', verificationResult.error);
      return { verified: false, error: verificationResult.error };
    }
  } catch (error) {
    console.error('Verification process error:', error);
    return { verified: false, error: error.message };
  }
}

For production systems, you must extend this basic verification with your domain-specific policy. Using a framework like Veramo, you can create a custom plugin to check credential credentialSubject fields. For instance, after the cryptographic check passes, your policy logic would inspect the claims: if (credential.credentialSubject.carbonOffsetTons < 500) { throw new Error('Insufficient offset'); }. Furthermore, the verifier should check the credential's issuanceDate and expirationDate and validate the status by querying the issuer's status list (e.g., a bitstring on IPFS) to ensure it hasn't been revoked.

Finally, consider the trust architecture. The verifier must maintain a trusted list of issuer DIDs or a decentralized trust registry. It should also produce an immutable audit trail. A common pattern is for the verifier service to emit an on-chain event or mint a non-transferable Soulbound Token (SBT) to the holder's wallet address upon successful verification. This on-chain record, perhaps on a low-cost chain like Polygon or Base, serves as a public, tamper-proof log of the verification event, which can be referenced by other systems without repeating the full credential check.

A revocation registry is essential for maintaining trust in a verifiable credentials (VC) system. It allows an issuer, like a green standards body, to revoke a credential if the underlying claim becomes invalid—for example, if a certified building fails a subsequent emissions audit. While the credential itself remains a signed JSON Web Token (JWT) or W3C Verifiable Credential stored off-chain, its revocation status is checked against an on-chain registry. This decouples the credential data from its status check, preserving privacy while leveraging blockchain for tamper-proof status tracking.

For Ethereum-compatible chains, a common implementation is the ERC-3668: CCIP Read standard, which enables off-chain lookups. A simpler, more direct approach uses a basic smart contract that maps a unique credential identifier (a credentialId hash) to a boolean revocation status. Below is a foundational Solidity contract example for a GreenCertRevocationRegistry:

solidityCopy
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

contract GreenCertRevocationRegistry {
    address public owner;
    mapping(bytes32 => bool) private _revoked;

    event CredentialRevoked(bytes32 indexed credentialId, address indexed issuer);
    event CredentialReinstated(bytes32 indexed credentialId, address indexed issuer);

    constructor() {
        owner = msg.sender;
    }

    function revokeCredential(bytes32 credentialId) external onlyOwner {
        _revoked[credentialId] = true;
        emit CredentialRevoked(credentialId, msg.sender);
    }

    function reinstateCredential(bytes32 credentialId) external onlyOwner {
        _revoked[credentialId] = false;
        emit CredentialReinstated(credentialId, msg.sender);
    }

    function isRevoked(bytes32 credentialId) external view returns (bool) {
        return _revoked[credentialId];
    }

    modifier onlyOwner() {
        require(msg.sender == owner, "Not authorized");
        _;
    }
}

The credentialId is typically a bytes32 hash of a unique identifier from the VC, ensuring no personal data is stored on-chain.

To integrate this registry, the verifier's process must include an on-chain status check. When a prover presents a green certification VC, the verifier extracts the credentialId and the registry contract address (both embedded in the VC's proof). The verifier then calls the registry's isRevoked(credentialId) view function. A return value of true means the credential is invalid, regardless of its cryptographic signature. This check is fast, cheap (as it's a read-only call), and provides a definitive status anchored to blockchain consensus. For systems requiring more complex revocation logic—like time-based expiry or bulk operations—consider using established frameworks like Ethereum Attestation Service (EAS) or Veramo's revocation plugins.

Key architectural decisions involve gas costs and scalability. Issuing a revocation transaction (revokeCredential) requires gas, so issuers must budget for these operations. For high-volume systems, layer-2 solutions like Polygon, Arbitrum, or Base are recommended to reduce costs. Additionally, the choice between a per-issuer registry (one contract per issuing authority) and a shared registry (one contract for many issuers) impacts upgradeability and control. A shared registry can be more gas-efficient for verifiers checking multiple issuer types but requires a more complex permissioning system, such as using OpenZeppelin's AccessControl.

Finally, this on-chain component must be reflected in your overall VC data model. The VC's proof section should include a revocationRegistry field pointing to the contract address and the credentialId. This allows any standard verifier to automatically know where and how to check the status. By completing this integration, you establish a robust, decentralized mechanism for credential lifecycle management, ensuring that your green certification framework remains credible and responsive to real-world changes in sustainability status.

You now have the architectural blueprint: a system anchored by a decentralized identifier (DID) for the issuer, verifiable credentials (VCs) encoded in W3C-compliant JSON-LD, and verifiable presentations (VPs) secured by BBS+ signatures for selective disclosure. The next phase is implementation. Start by deploying a smart contract on a suitable blockchain (like Ethereum, Polygon, or a dedicated L2) to manage your issuer DID and public key registry. Use libraries such as did-jwt-vc or vc-js to handle the creation and signing of credentials. For developers, a practical next step is to generate a test credential for a mock carbon offset project using a simple Node.js script that follows the data models we've discussed.

After establishing the core issuance and verification flow, focus on the user experience and system integration. Build or integrate a holder wallet—this could be a mobile app using Veramo or a web-based custodial solution. Ensure your verification portal can parse VPs, check the credential status against the revocation registry (e.g., using a smart contract or the Iden3 Reverse Hashmap), and validate the cryptographic proof. It's crucial to conduct a security audit of the entire stack, particularly the smart contracts managing DIDs and revocation, and the key management procedures for the issuer.

Looking ahead, consider how to scale and interoperate. Explore integrating with existing trust registries like the Ethereum Attestation Service (EAS) or trusted-setup.pse.dev to enhance credential discoverability and issuer legitimacy. Plan for schema evolution: how will your credential data model adapt to new regulatory standards like the EU's Corporate Sustainability Reporting Directive (CSRD)? Finally, engage with the broader ecosystem by contributing to working groups at the Decentralized Identity Foundation (DIF) or W3C Credentials Community Group to ensure your framework remains compatible with evolving standards and best practices in the verifiable credentials landscape.