zkMe Credential System
System Overview
The Credential System is a decentralized, privacy-preserving credential issuance and verification infrastructure built on zero-knowledge proof (ZKP) technology. It is designed to address the challenges of identity verification and data protection, while providing a high degree of auditability, accountability, and operational clarity, making it suitable for enterprises and institutions with stringent compliance and security requirements.
The system enables trusted entities (Issuers) to issue standardized digital credentials to individuals or organizations (Holders). Holders can then present cryptographic proofs of these credentials to third parties (Verifiers) without revealing the underlying sensitive data. This is achieved through zero-knowledge proofs, which allow specific claims to be verified in a secure and privacy-preserving manner.
By combining standardized credential formats, well-defined issuance and verification workflows, and decentralized storage, the Credential System provides a secure, efficient, and scalable identity management solution that preserves user privacy while remaining compatible with regulatory and audit requirements.
Problem & Solution
In traditional digital ecosystems, identity and credential verification are centralized, leading to data silos, privacy risks, and high operational overhead for compliance. Users are forced to over-share personal data, and institutions bear the full burden of securing that data.
The Credential System solves this by creating a trust triangle between Issuers, Holders, and Verifiers, anchored by a blockchain. It replaces the need for direct data sharing with cryptographic proof, enabling use cases that were previously impractical due to privacy and security concerns.
Use Cases
The system is designed for a variety of use cases where verifiable, privacy-preserving claims are critical:
Compliance & KYC
zkMe issues a zkKYC credential. The user can prove their KYC status to a new service without re-submitting documents, and the service can audit the verification without seeing the user’s PII.
Finance & Credit
zkMe issues a Credit credential containing credit-related attributes. The user can prove that they meet a required credit condition during a loan application, without revealing their exact credit score or full financial history.
Design Goals & Principles
The architecture is guided by principles designed to meet the needs:
Privacy-by-Design & Data Minimization: The system is architected so that the Holder never reveals raw data to the Verifier. Only the proof of a specific claim is shared.
Auditability without Exposure: All significant state changes are recorded on-chain, providing an immutable audit trail. Auditors can verify the integrity of the system without accessing sensitive user data.
User Sovereignty: Holders have exclusive control over their credentials and private keys. Data is stored in an encrypted, user-controlled environment.
Interoperability & Standards Alignment: The system utilizes the W3C Verifiable Credentials (VC) Data Model, ensuring compatibility with emerging digital identity standards.
Operational Clarity & Liability Containment: By establishing clear, cryptographically enforced boundaries, the system contains liability. Each party is only responsible for its defined role, reducing systemic risk.
Core Roles & Responsibility Boundaries
The system defines three primary roles and their explicit responsibilities, creating clear accountability boundaries.
Issuer
Can: Issue and revoke credentials. Define credential schemas.
Cannot: By design, zkMe has no access to a Holder’s other credentials or proofs.
Accountable for: The authenticity and accuracy of the claims it attests to.
All issued credential schemas (on-chain).
All credential revocations (on-chain).
The Issuer’s public key and identity.
Holder
Can: Own, use, and manage credentials; present proofs derived from them.
Cannot: Create or modify credentials. Forge proofs for claims they don’t possess.
Accountable for: Securely owning and managing their credentials via their account or address, and exercising control over the use and presentation of proofs.
The history of their on-chain Merkle Root updates.
The integrity of their Claim Tree (provable via ZKP).
Verifier
Can: Define verification policies (queries), request proofs, and verify them.
Cannot: See any data beyond the proof result (true/false). Access the Holder’s credentials.
Accountable for: The business logic executed after a successful verification.
The Challenge used for a verification session.
The verification result (if logged by the Verifier).
On-chain verification transactions.
System Architecture
Layer 1: Presentation Layer Provides user-facing interfaces for credential management and interaction.
User Account (SSI Wallet): The Holder's primary interface for managing credentials, keys, and generating proofs. This is an external third-party component (Self-Sovereign Identity Wallet) integrated through standard interfaces. The wallet manages:
Private key storage and management
Local encrypted credential storage
Proof generation and submission
UI Components: Dashboards and SDKs for Issuers and Verifiers:
Issuer Widget SDK: Embedded SDK for integrating credential issuance into Issuer applications
Issuer Dashboard: Management interface for Issuers to monitor and manage issued credentials
Verifier Widget SDK: Embedded SDK for integrating credential verification into Verifier applications
Verifier Dashboard: Management interface for Verifiers to configure verification policies and review results
Layer 2: Application Layer Contains business logic for credential operations and user interactions.
Holder Credential Management: Manages user credentials, including credential display, status updates, and on-chain record management.
Issuer Application: Handles the operational processes for issuing credentials.
Verifier Application: Handles the operational processes for verifying credentials.
Layer 3: Storage and Database Layer Manages data persistence for both encrypted credentials and system metadata.
Decentralized Storage (dStorage): Decentralized storage for users' encrypted data, credentials, and threshold keys.
Local or Centralized Database: Stores non-sensitive data such as schemas and queries.
Layer 4: Blockchain Layer Serves as the immutable trust anchor for the entire system, ensuring auditability and non-repudiation.
State Contracts (VC State Smart Contract): Manages VC state and Merkle Tree root updates, credential metadata on-chain, MTP (Merkle Tree Proof) root management, and revocation status tracking.
Target Chain Smart Contract: Enables cross-chain credential verification, credential state relay to other chains, and multi-chain credential support.
Cross-Chain Message Contract: Facilitates cross-chain communication and message passing, state synchronization across chains, and cross-chain ZKP verification result relay.
Credential Data Model
The system uses a data model compliant with the W3C Verifiable Credentials standard, extended for ZK operations.
Schema Definition
A Schema defines the data structure template for credentials, specifying the fields, data types, and constraints of the claims.
Creation: Issuers define a JSON Schema for each credential type, specifying the fields, data types, and constraints of the claims.
Storage: Schemas are stored in a centralized database and referenced by a unique identifier.
Example Schema (Proof-of-Citizenship (PoC) Credential):
Verifiable Credential Structure
A Verifiable Credential (VC) is a JSON-LD object that contains both standard metadata fields and claim data. The claim data within credentialSubject follows the structure defined by the referenced Schema, populated with specific user information and signed by the Issuer.
@context
Defines the vocabulary used.
id
A unique URI for the credential.
type
Specifies the object type.
issuer
The DID of the Issuer.
issuanceDate
ISO 8601 timestamp of issuance.
expirationDate
Optional ISO 8601 timestamp of expiration.
credentialSubject
Contains the claims about the Holder.
credentialSchema
A link to the schema definition.
credentialStatus
A link to check revocation status on-chain.
proof
The Issuer’s digital signature.
Claim Tree & Commitment Model
To ensure privacy and efficiency, the Holder does not store credentials directly on-chain. Instead, they commit to their set of credentials using a cryptographic accumulator known as a Claim Tree.
Structure: The Claim Tree is a Sparse Merkle Tree (SMT). This data structure allows for efficient proof of membership (proving a credential exists in the set) and non-membership.
Leaf Format: Each leaf in the tree corresponds to a single credential. The leaf value is a Poseidon hash of the credential’s core data, serialized into a set of numeric fields.
Root Commitment: The Merkle Root of the SMT is a 32-byte value that acts as a compact, cryptographic commitment to the Holder’s entire set of credentials. This root is the only piece of data the Holder needs to anchor on-chain.
Updates: When a Holder receives a new credential, they add its hash as a new leaf, recalculate the Merkle Root, and submit this new root to the on-chain State Contract. This is a low-cost transaction that updates their state without revealing any credential details.
Membership Proof: To prove ownership of a credential during verification, the Holder generates a Merkle proof, which is a list of sibling hashes needed to reconstruct the path from the credential’s leaf to the on-chain root. This proof is verified inside the ZK circuit.
Credential Lifecycle Management
The system provides a complete, auditable lifecycle for every credential.
Issuance Flow
The issuance flow establishes the credential’s origin and binds it to the Holder.
Verification Flow
The verification flow is the core privacy-preserving interaction. It encompasses three key components: the Verifier's query definition, the Holder's proof generation with security mechanisms, and the on-chain verification process.
Verifier Query Model
Verifiers define their requirements using a simple JSON-based query language. The query specifies the credential schema to check and the conditions the claims must satisfy.
This query-based approach allows Verifiers to express complex conditions without requiring the Holder to reveal raw data. The ZK circuit then generates a proof that satisfies these conditions.
Replay Attack Protection
To prevent proofs from being replayed in different contexts, the system implements a Challenge-Response mechanism:
Challenge Generation: The Verifier generates a unique, random Challenge (nonce) for each verification session.
Challenge Inclusion: This Challenge is included as a public input to the ZK proof.
Proof Binding: The ZK circuit proves that the Holder signed the Challenge, cryptographically binding the proof to the specific verification session. This prevents the proof from being replayed in a different context or at a different time.
Revocation Flow
Revocation is critical for invalidating credentials before they expire. The system supports two modes.
Issuer-Side Revocation: The Issuer adds the credential's ID to the State Contract. This is a public irreversible action that invalidates the credential for all Holders.
User-Side Revocation: The Holder removes the credential from their local Claim Tree and updates their Merkle Root. This is a private action that only affects the Holder.
Revocation Verification (ClaimNonRevState Check): During verification, the system performs a multi-layer revocation check:
On-Chain State Contract Check: The Verification Contract queries the State Contract to confirm the credential ID is not revoked.
Expiration Check: The system verifies the credential has not expired.
ZK Proof Generation: If all checks pass, the ZK circuit generates the proof with revocation and expiration constraints.
Expiration Flow
Expiration is a passive, time-based invalidation mechanism enforced at multiple layers.
Enforcement: Expiration is checked at three layers:
by the Holder’s wallet before proof generation,
cryptographically within the ZK circuit, and
optionally by the Verifier’s backend.
Verification After Expiration: Any attempt to generate a proof with an expired credential will fail at one of these layers, making verification impossible.
Cryptographic & Trust Assumptions
This section documents the cryptographic primitives and trust assumptions required for a security review.
ZK Proving System
Groth16 zk-SNARK
Requires a one-time, per-circuit trusted setup (Powers of Tau). The circuits themselves are open source and auditable.
Digital Signatures
BJJSignature (EdDSA over BabyJubJub curve)
Used by Issuers to sign credentials. ZK-friendly signature scheme that can be efficiently verified inside circuits. Assumes the Issuer securely manages their private key.
Hash Functions
Poseidon
A ZK-friendly hash function used for Merkle Tree commitments and other in-circuit hashing.
Key Management
Hierarchical Deterministic (HD) Wallets
Holders are responsible for securing their seed phrase. The system itself is non-custodial.
Circuit Correctness
The ZK circuits must correctly implement the verification logic.
The circuits are the core of the trust model and should be the focus of any cryptographic audit.
Threat Model Scope: The threat model assumes the underlying blockchain is secure and that users maintain control of their private keys. It focuses on preventing invalid credentials, forged proofs, and data leakage within the system itself.
Last updated