Setting Up a Decentralized Identity Provider for AML Checks

Decentralized Identity (DID) systems offer a privacy-preserving alternative to traditional AML/KYC checks by shifting control of personal data to the user. Instead of repeatedly submitting sensitive documents like passports, users can obtain verifiable credentials from a trusted issuer (e.g., a regulated entity). These credentials are cryptographically signed statements stored in a user-controlled digital wallet. For an AML check, the service provider requests not the raw data, but a zero-knowledge proof that the user meets specific criteria, such as being over 18 and not on a sanctions list, without revealing the underlying details.

The core technical components for building this system are the W3C DID and Verifiable Credentials (VC) data models. A DID is a unique identifier (e.g., did:ethr:0xabc123...) anchored to a blockchain, acting as the user's cryptographic root of trust. The Verifiable Credentials Data Model defines how claims about that DID (like "country of residence" or "KYC status") are issued as tamper-evident JSON-LD or JWT documents. Protocols like DIDComm or OpenID Connect for Verifiable Credentials (OIDC4VC) standardize how these credentials are presented. For developers, libraries such as did-jwt-vc (JavaScript) or ssi-sdk (Go) provide essential tools for creating and verifying these structures.

A practical implementation involves three main actors: the Issuer (a licensed KYC provider), the Holder (the end-user with a wallet), and the Verifier (the platform needing AML assurance). The flow begins with the user undergoing a one-time KYC process with the Issuer, who creates a signed VC containing the verified attributes. When interacting with a Verifier's dApp, the user receives a Presentation Request specifying the required claims and proof type. The user's wallet uses a Selective Disclosure protocol to generate a Verifiable Presentation, proving they satisfy the policy—for instance, by demonstrating their accredited investor status is valid and unrevoked without showing their net worth.

For on-chain integration, smart contracts can verify proofs submitted by users. Projects like Sismo use zero-knowledge proofs to create reusable, anonymous "badges" derived from credentials. A verifier contract would include a function like verifyAMLProof(bytes memory proof, bytes32 policyId) that checks a ZK-SNARK proof against a public policy. Off-chain, verifiers can use public revocation registries (often implemented as smart contract state or verifiable data registries) to check if an issuer has revoked a credential without learning which user holds it, a crucial feature for maintaining compliance.

Key considerations for production systems include choosing the right DID method (e.g., did:ethr for Ethereum, did:key for simplicity), managing credential revocation via status lists or accumulators, and ensuring interoperability across wallets and verifiers. Regulatory compliance requires that the Issuer is a Trust Anchor under relevant frameworks like eIDAS. By implementing this architecture, developers can build applications that satisfy AML Travel Rule requirements and Sanctions Screening through cryptographic proofs, significantly reducing data liability and improving user privacy compared to centralized data silos.

You must have a working understanding of core Web3 concepts. This includes familiarity with public-key cryptography and digital signatures, which underpin decentralized identity (DID) and verifiable credentials. You should also be comfortable with smart contract development and interaction, as on-chain registries are often used for DID resolution. A basic grasp of decentralized identifiers (DIDs) and the W3C Verifiable Credentials data model is crucial for structuring identity data compliantly.

For development, you will need Node.js (v18 or later) and npm/yarn installed. Essential libraries include did-resolver and web3 or ethers.js for blockchain interaction. If you plan to use a specific DID method, install its resolver library (e.g., ethr-did-resolver for Ethereum). For managing cryptographic keys and signing verifiable presentations, a library like @veramo/core provides a comprehensive framework. Set up a local Ethereum testnet (like Ganache) or connect to a testnet (Sepolia, Goerli) for deployment and testing.

You will need to choose and configure a DID Method. This defines how your DIDs are created, resolved, updated, and deactivated on a specific blockchain or network. For example, did:ethr is commonly used on Ethereum. You must decide on the storage layer for verifiable credentials—options include IPFS for decentralized storage or your own secure, encrypted database. Finally, ensure you have a wallet (like MetaMask) with testnet ETH to pay for transaction gas fees during development and testing phases.

A decentralized identity provider for AML checks shifts the paradigm from centralized KYC databases to user-controlled, portable credentials. The core components are Decentralized Identifiers (DIDs) and Verifiable Credentials (VCs). A DID is a unique, self-sovereign identifier (e.g., did:ethr:0xabc123) stored on a blockchain like Ethereum or Polygon. The AML attestation—such as a proof of identity and risk score—is issued as a VC by a trusted entity (a Verifier) and cryptographically signed. The user stores this VC in their digital wallet (the Holder), presenting it to service providers (the Relying Parties) who can verify its authenticity without contacting the original issuer.

The system architecture typically follows the W3C Verifiable Credentials data model and integrates several key layers. The Identity Layer uses protocols like did:ethr or did:key for DID creation and management. The Credential Layer handles the issuance and verification logic, often implemented using libraries like veramo or ssi-sdk. The Storage Layer is decentralized, with VCs stored off-chain in the user's wallet or on solutions like Ceramic or IPFS, while only the essential proofs are referenced on-chain. The Compliance Gateway is a critical on-chain or off-chain component where Verifiers (e.g., regulated entities) can issue credentials against an updated AML list.

For developers, setting up a basic issuer node involves initializing a Veramo agent. Below is a simplified example of issuing a VC with an AML status claim using TypeScript and Veramo.

typescriptCopy
import { createAgent } from '@veramo/core';
import { CredentialIssuer } from '@veramo/credential-w3c';
// Agent setup with DID resolver and key management
const agent = createAgent({
  plugins: [new CredentialIssuer()],
});
// Issue a credential
const vc = await agent.createVerifiableCredential({
  credential: {
    issuer: { id: 'did:ethr:0xissuer' },
    credentialSubject: {
      id: 'did:ethr:0xuser',
      amlStatus: 'low_risk',
      lastChecked: '2024-01-15',
    },
  },
  proofFormat: 'jwt',
});

This code creates a signed JWT credential that asserts the subject's AML status.

Integrating with real-world AML data sources requires a secure Oracle or API Gateway. This component listens to updates from traditional compliance providers like Chainalysis or Elliptic. When a risk status changes, the oracle triggers a smart contract function that updates a Revocation Registry (e.g., an Ethereum smart contract maintaining a revocation list) or allows an authorized issuer to update a credential's status. Relying parties must check this registry during verification. This hybrid approach connects off-chain AML intelligence to on-chain verifiability, maintaining privacy by not exposing personal data on-chain while ensuring credentials reflect current compliance states.

Key design considerations for production systems include selective disclosure using Zero-Knowledge Proofs (ZKPs) via protocols like iden3 or Spartan, allowing users to prove they are "low risk" without revealing their full identity. Credential revocation must be efficient; using Ethereum's EIP-5539 (Revocation Bitmap) or Sidetree-based methods can avoid costly on-chain transactions. Furthermore, the architecture must account for gas costs for DID operations, often mitigated by using Layer 2 solutions like Polygon or zkSync. Auditing the credential issuance and verification logic is as critical as auditing smart contracts, as the entire system's trust hinges on their correctness.

Ultimately, this architecture enables a more efficient and privacy-preserving compliance flow. Users maintain control of their data, businesses reduce liability and storage costs associated with KYC data, and regulators can audit attestation trails via immutable logs. The future evolution points towards portable reputation and cross-chain identity, where a single AML credential from one chain can be trustlessly verified on another, facilitated by interoperability protocols like IBC or LayerZero.

A Decentralized Identifier (DID) is a foundational component for issuing verifiable credentials. It acts as a cryptographically secure, self-sovereign identity for your organization on a public ledger, such as a blockchain. For Anti-Money Laundering (AML) checks, the issuer DID represents the trusted authority—like a financial institution or compliance service—that creates and signs the credentials attesting to a user's verified status. This step moves away from centralized, siloed identity systems to a portable, interoperable standard defined by the W3C.

To create your issuer DID, you will generate a DID Document containing your public keys, service endpoints, and verification methods. This document is then anchored to a chosen blockchain network, creating a permanent, tamper-proof record. For Ethereum-based systems, a common method is using the did:ethr method, where the DID is derived directly from an Ethereum account (e.g., did:ethr:0x...). Other popular methods include did:key for simple key pairs and did:web for domains. The choice depends on your required trust model and infrastructure.

You will need a secure key management strategy. The private key associated with your DID is used to sign all credentials you issue; its compromise invalidates your entire trust framework. For production systems, consider using hardware security modules (HSMs) or cloud-based key management services like AWS KMS or Azure Key Vault. For development and testing, you can use libraries like ethr-did or did-jwt to generate a key pair and register the DID on a testnet, such as Sepolia or Goerli.

Here is a basic example using the ethr-did library to create a DID on an Ethereum testnet. First, install the required packages: npm install ethr-did ethr-did-resolver. Then, you can generate a DID from a new Ethereum key pair and register it on-chain. The registration transaction publishes your DID Document, making it resolvable by any verifier in the ecosystem.

After your DID is registered, you must configure a DID Resolver. This is a service or library that can fetch your DID Document from the blockchain when a verifier needs to check the signature on a credential you issued. For did:ethr, you would use the ethr-did-resolver configured with a JSON-RPC provider like Infura or Alchemy. This setup completes the core identity layer, enabling you to proceed to the next step: defining the credential schema for your AML attestations.

A Decentralized Identity Provider (DID Provider) acts as a bridge between a user's self-sovereign identity and compliance requirements. Instead of storing sensitive data on-chain, it issues verifiable credentials (VCs) that attest to a user's status after passing AML/KYC checks. Providers like SpruceID, Veramo, or Ethereum Attestation Service (EAS) enable this. Your application's smart contract or backend can then verify these credentials to gate access to specific functions, such as token minting or high-value transfers, without handling raw user data.

Integration typically involves a three-step flow. First, your frontend redirects the user to the DID provider's verification service (e.g., using Sign-In with Ethereum). The provider performs the necessary checks, which may include screening against sanctions lists (like OFAC) or validating government ID. Upon success, it issues a cryptographically signed attestation to the user's wallet. This attestation is a VC stored in the user's identity wallet (e.g., MetaMask Snaps, Disco.xyz), not on your servers.

Your application's backend or smart contract must then verify this credential. For on-chain verification, you can use a registry contract from your DID provider. For example, with Ethereum Attestation Service, you would call a function like verifyAttestation(attestationUID) to check its validity and schema. Off-chain, a service like Veramo can verify the credential's signature and check its status against a revocation registry. This separation ensures user privacy while providing the necessary proof of compliance.

Key technical considerations include selecting the attestation schema (what data is attested), managing credential revocation (if a user fails a later check), and determining verification gas costs for on-chain checks. For high-throughput applications, consider using zero-knowledge proofs (ZKPs) of credential ownership via protocols like Sismo or Polygon ID to reduce on-chain footprint. Always design your integration to be modular, allowing you to switch providers or update compliance rules as regulations evolve.

With the user's verified identity data from Step 2, the issuer now creates a structured Verifiable Credential. This is a JSON-LD or JWT document containing the user's claims (e.g., "amlStatus": "clear", "kycLevel": 2, "issuanceDate") and critical metadata. The credential is cryptographically bound to the issuer's Decentralized Identifier (DID) using the issuer field, and to the user's DID via the credentialSubject.id field. This structure ensures the credential's authenticity and subject are unambiguous on the ledger.

The credential must be digitally signed to become verifiable. Using the issuer's private key associated with its DID (e.g., from the did:ethr:0x... method on Ethereum), you generate a cryptographic signature over the credential data. For a JWT VC, this creates a compact vc-jwt string. For JSON-LD VCs, a Linked Data Proof (like Ed25519Signature2020) is embedded. This signature is the proof that your authorized identity provider issued this specific credential and that its contents have not been altered.

Finally, the signed VC is transmitted to the user's wallet. This is typically done via a secure callback URL or a direct wallet interaction protocol like DIDComm or CHAPI (Credential Handler API). The user's wallet receives and stores the VC in its secure storage. Crucially, the credential itself is not stored on-chain; only the issuer's DID Document and the associated public key for verification are anchored to the blockchain. This preserves user privacy while enabling anyone to cryptographically verify the credential's origin and integrity.

After successful verification, the credential must be issued in a standardized, portable format. The dominant standard for this is the W3C Verifiable Credential (VC). A VC is a tamper-evident credential with cryptographic proof, such as a digital signature from your issuer DID. The credential's payload contains the verified claims (e.g., "amlStatus": "verified", "level": "basic", "issuanceDate": "2024-01-15") and metadata specifying the credential type, issuer, and subject (the user's DID).

To deliver the VC, you must package it into a Verifiable Presentation (VP). A VP is how a holder (the user) presents one or more credentials to a verifier. You will typically create a signed JWT (JSON Web Token) or an LD-Proof (Linked Data Proof) that encapsulates the VC. For example, using the did-jwt-vc library, you can create a signed JWT credential. The user's wallet must be capable of receiving and storing this signed data structure, which is often done via a deep link or a QR code scan that triggers a wallet's credential reception flow.

The delivery mechanism is often a credential offer endpoint in your backend. After generating the signed VC, your API should return it in a format defined by standards like OpenID for Verifiable Credentials (OID4VC) or CHAPI (Credential Handler API). A common pattern is to provide a URL or a QR code that contains a deep link (e.g., mywallet://credential-offer?credential_jwt=<TOKEN>) or to use the window.open() method if the user is in a browser, targeting a registered wallet protocol handler.

The user's wallet (e.g., MetaMask with Snap, Spruce ID, or a native mobile wallet) receives the credential, validates the issuer's signature against the public key in your DID Document, and then stores it securely in the user's local identity hub or data vault. This storage is decentralized; the credential is held client-side, not on your servers. The wallet's UI will typically show the user a new credential is available and ask for confirmation to add it to their collection.

Finally, implement error handling and status confirmation. Your system should track the credential's id and listen for a callback from the wallet (if supported by the protocol) or provide a way for the user to signal successful receipt. This completes the issuance flow, granting the user a self-sovereign credential they can now use to access services requiring AML checks without repeating the verification process.

The Relying Party Verifier is the server-side application that receives the user's Verifiable Credential (VC) and validates it against your business logic. Its primary functions are to parse the VC, verify the cryptographic proof (ensuring it was issued by a trusted Identity Provider), and extract the relevant claims (like KYC/AML status) to make an access decision. This component is typically built as a REST API endpoint, such as /api/verify-credential, which your frontend calls after receiving the credential from the user's wallet.

To verify a credential, you must first check its digital signature. Using a library like did-jwt-vc or veramo, you resolve the issuer's Decentralized Identifier (DID) to fetch their public key from their DID Document. The verification confirms the credential hasn't been tampered with and was genuinely issued by the trusted provider. Next, validate the credential's structure and contents against the W3C Verifiable Credentials Data Model and your expected schema to ensure all required AML-related fields are present and correctly formatted.

A critical check is validating the credential's status. Many issuers use a Status List 2021 credential, a privacy-preserving method where a bit in a public, revocable list indicates validity. Your verifier must fetch this status list credential (referenced in the credentialStatus field) and check the specific index to ensure the user's credential has not been revoked. This step is essential for real-time AML compliance, as it allows issuers to instantly invalidate credentials if a user's risk profile changes.

After successful verification, extract the claims from the credentialSubject. For an AML credential, this typically includes fields like isKYCChecked, amlRiskRating, countryOfResidence, and a timestamp. Your business logic then uses these claims to make an access decision—for instance, allowing transactions only for users with amlRiskRating: "low" and isKYCChecked: true. Log the verification result and the specific claims used for the decision to maintain a compliance audit trail.

Here is a simplified Node.js example using the veramo framework to verify a credential:

javascriptCopy
import { createAgent } from '@veramo/core';
import { CredentialPlugin } from '@veramo/credential-w3c';
// ... configure agent with DID resolver and key manager
const verificationResult = await agent.verifyCredential({
  credential: receivedVerifiableCredential,
});
if (verificationResult.verified) {
  const riskRating = verificationResult.credential.credentialSubject.amlRiskRating;
  // Implement your AML policy logic
}

Finally, integrate this verifier into your application's workflow. The frontend, after obtaining the user's VC, sends it via a POST request to your verification endpoint. The backend verifier processes it and returns a clear response (e.g., { "verified": true, "riskLevel": "low", "accessGranted": true }). Ensure you handle errors gracefully, such as invalid signatures, expired credentials, or network failures when checking status lists. This completes the technical integration for decentralized AML checks.