@cheny56/zk-kyc-did 1.0.0

package/client/kyc-client.js

@@ -0,0 +1,243 @@
+/**
+ * KYC/DID Client SDK
+ * 
+ * High-level client for interacting with credential verification contracts
+ * and generating ZK proofs for credential predicates.
+ */
+
+const { ethers } = require('ethers');
+const { 
+    VerifiableCredential, 
+    CredentialWallet,
+    Predicate,
+    PredicateOp,
+    generateProofInputs,
+    preparePublicInputs,
+} = require('../lib');
+
+// Try to import snarkjs (optional for demo mode)
+let snarkjs = null;
+try {
+    snarkjs = require('snarkjs');
+} catch (e) {
+    console.warn('snarkjs not available - running in demo mode');
+}
+
+/**
+ * KYC Client for credential verification
+ */
+class KYCClient {
+    /**
+     * @param {Object} options
+     * @param {object} options.provider Ethers provider
+     * @param {object} options.signer Ethers signer
+     * @param {string} options.verifierAddress CredentialVerifier contract address
+     * @param {string} [options.proveKeysDir] Directory containing proving keys
+     * @param {boolean} [options.demoMode] Skip proof generation (for testing)
+     */
+    constructor(options) {
+        this.provider = options.provider;
+        this.signer = options.signer;
+        this.verifierAddress = options.verifierAddress;
+        this.proveKeysDir = options.proveKeysDir || './keys';
+        this.demoMode = options.demoMode || !snarkjs;
+        
+        this.contract = null;
+        this.wallet = null;
+    }
+    
+    /**
+     * Initialize the client
+     * @param {CredentialWallet} [wallet] Optional credential wallet
+     */
+    async init(wallet = null) {
+        if (wallet) {
+            this.wallet = wallet;
+        } else {
+            this.wallet = new CredentialWallet();
+            await this.wallet.init();
+        }
+        
+        // Initialize credential library
+        await require('../lib').init();
+        
+        console.log('KYC Client initialized');
+        console.log(`  Demo mode: ${this.demoMode}`);
+        console.log(`  Subject DID: ${this.wallet.subjectDID}`);
+        
+        return this;
+    }
+    
+    /**
+     * Set the verifier contract instance
+     * @param {object} contract Ethers contract instance
+     */
+    setContract(contract) {
+        this.contract = contract;
+    }
+    
+    /**
+     * Create a credential (issuer side)
+     * @param {Object} options
+     * @param {string} options.subjectDID Subject's DID
+     * @param {Object} options.claims Claims object
+     * @param {string} [options.type] Credential type
+     * @param {bigint} issuerPrivateKey Issuer's private key
+     * @returns {Promise<VerifiableCredential>}
+     */
+    async createCredential(options, issuerPrivateKey) {
+        const credential = new VerifiableCredential({
+            issuer: this.signer.address, // Or issuer's DID
+            subject: options.subjectDID,
+            claims: options.claims,
+            type: options.type || 'KYC',
+        });
+        
+        await credential.init();
+        credential.sign(BigInt(issuerPrivateKey));
+        
+        return credential;
+    }
+    
+    /**
+     * Add a credential to wallet
+     * @param {VerifiableCredential} credential
+     */
+    addCredential(credential) {
+        this.wallet.addCredential(credential);
+    }
+    
+    /**
+     * Generate a ZK proof for credential predicates
+     * @param {string} credentialId Credential ID
+     * @param {Predicate[]} predicates Predicates to prove
+     * @returns {Promise<Object>} { proof, publicInputs }
+     */
+    async generateProof(credentialId, predicates) {
+        const credential = this.wallet.getCredential(credentialId);
+        if (!credential) {
+            throw new Error(`Credential ${credentialId} not found`);
+        }
+        
+        // Check credential not expired
+        if (credential.isExpired()) {
+            throw new Error('Credential has expired');
+        }
+        
+        // Generate proof inputs
+        const privateInputs = await generateProofInputs(credential, predicates);
+        const publicInputs = preparePublicInputs(predicates, credential.issuer);
+        
+        // Generate ZK proof (or skip in demo mode)
+        let proof = null;
+        if (!this.demoMode) {
+            proof = await this._generateZKProof(privateInputs, publicInputs);
+        }
+        
+        return {
+            proof,
+            publicInputs,
+            credentialRoot: this._computeCredentialRoot(credential),
+        };
+    }
+    
+    /**
+     * Verify a credential on-chain
+     * @param {Object} proofData Proof data from generateProof
+     * @returns {Promise<{tx: object, verified: boolean}>}
+     */
+    async verifyOnChain(proofData) {
+        if (!this.contract) {
+            throw new Error('Contract not set. Call setContract() first.');
+        }
+        
+        if (this.demoMode) {
+            // Skip proof verification in demo mode
+            const tx = await this.contract.verifyCredentialBasic(
+                BigInt(proofData.publicInputs.issuerPublicKey),
+                proofData.credentialRoot
+            );
+            return { verified: await tx, tx: null };
+        }
+        
+        // Format proof for contract
+        const formattedProof = this._formatProof(proofData.proof);
+        
+        // Call contract
+        const tx = await this.contract.verifyCredential(
+            formattedProof.pA,
+            formattedProof.pB,
+            formattedProof.pC,
+            BigInt(proofData.publicInputs.issuerPublicKey),
+            BigInt(proofData.publicInputs.predicateCommitments || 0),
+            proofData.credentialRoot
+        );
+        
+        await tx.wait();
+        
+        return { verified: true, tx };
+    }
+    
+    /**
+     * Check if an issuer is trusted
+     * @param {string} issuerAddress Issuer address
+     * @returns {Promise<boolean>}
+     */
+    async isIssuerTrusted(issuerAddress) {
+        if (!this.contract) {
+            throw new Error('Contract not set');
+        }
+        return this.contract.trustedIssuers(issuerAddress);
+    }
+    
+    /**
+     * Get wallet
+     * @returns {CredentialWallet}
+     */
+    getWallet() {
+        return this.wallet;
+    }
+    
+    // ============================================
+    // Private methods
+    // ============================================
+    
+    async _generateZKProof(privateInputs, publicInputs) {
+        if (!snarkjs) throw new Error('snarkjs not available');
+        
+        // This would use the actual circuit
+        // For now, return a placeholder structure
+        const { proof, publicSignals } = await snarkjs.groth16.fullProve(
+            privateInputs,
+            `${this.proveKeysDir}/credential-proof_js/credential-proof.wasm`,
+            `${this.proveKeysDir}/credential-proof_final.zkey`
+        );
+        
+        return { proof, publicSignals };
+    }
+    
+    _formatProof(proof) {
+        if (!proof) return null;
+        
+        return {
+            pA: [proof.pi_a[0], proof.pi_a[1]],
+            pB: [
+                [proof.pi_b[0][1], proof.pi_b[0][0]],
+                [proof.pi_b[1][1], proof.pi_b[1][0]],
+            ],
+            pC: [proof.pi_c[0], proof.pi_c[1]],
+        };
+    }
+    
+    _computeCredentialRoot(credential) {
+        const { poseidonHash } = require('../lib');
+        const commitments = Object.values(credential.claimCommitments).sort();
+        return poseidonHash([...commitments, BigInt(credential.issuer)]);
+    }
+}
+
+module.exports = {
+    KYCClient,
+    Predicate,
+    PredicateOp,
+};

package/contracts/CredentialVerifier.sol

@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+/**
+ * @title CredentialVerifier
+ * @notice Verifies ZK proofs for credential predicates
+ * @dev Uses external ZK verifier contract (generated by snarkjs)
+ */
+contract CredentialVerifier {
+    // Verifier contract address (set in constructor)
+    address public verifier;
+    
+    // Issuer registry (trusted issuers)
+    mapping(address => bool) public trustedIssuers;
+    
+    // Events
+    event CredentialVerified(
+        address indexed verifier,
+        address indexed issuer,
+        bytes32 indexed credentialRoot,
+        uint256 timestamp
+    );
+    
+    event IssuerAdded(address indexed issuer);
+    event IssuerRemoved(address indexed issuer);
+    
+    /**
+     * @notice Deploy verifier contract
+     * @param _verifier Address of ZK verifier contract
+     */
+    constructor(address _verifier) {
+        verifier = _verifier;
+    }
+    
+    /**
+     * @notice Add a trusted issuer (admin only)
+     * @param issuer Issuer's public key or address
+     */
+    function addTrustedIssuer(address issuer) external {
+        // In production, add access control
+        trustedIssuers[issuer] = true;
+        emit IssuerAdded(issuer);
+    }
+    
+    /**
+     * @notice Remove a trusted issuer
+     * @param issuer Issuer to remove
+     */
+    function removeTrustedIssuer(address issuer) external {
+        trustedIssuers[issuer] = false;
+        emit IssuerRemoved(issuer);
+    }
+    
+    /**
+     * @notice Verify a credential predicate proof
+     * @param proof ZK proof
+     * @param issuerPublicKey Issuer's public key
+     * @param predicateCommitments Hash of predicates
+     * @param credentialRoot Root commitment of credential
+     * @return True if proof is valid
+     */
+    function verifyCredential(
+        uint256[2] calldata proofA,
+        uint256[2][2] calldata proofB,
+        uint256[2] calldata proofC,
+        uint256 issuerPublicKey,
+        uint256 predicateCommitments,
+        uint256 credentialRoot
+    ) external view returns (bool) {
+        // Check issuer is trusted
+        require(trustedIssuers[address(uint160(issuerPublicKey))], "Issuer not trusted");
+        
+        // Prepare public inputs
+        uint256[3] memory publicInputs = [
+            issuerPublicKey,
+            predicateCommitments,
+            credentialRoot
+        ];
+        
+        // Call verifier contract
+        (bool success, bytes memory result) = verifier.staticcall(
+            abi.encodeWithSignature(
+                "verifyProof(uint256[2],uint256[2][2],uint256[2],uint256[])",
+                proofA,
+                proofB,
+                proofC,
+                publicInputs
+            )
+        );
+        
+        if (!success) return false;
+        
+        bool verified = abi.decode(result, (bool));
+        
+        if (verified) {
+            emit CredentialVerified(
+                msg.sender,
+                address(uint160(issuerPublicKey)),
+                bytes32(credentialRoot),
+                block.timestamp
+            );
+        }
+        
+        return verified;
+    }
+    
+    /**
+     * @notice Verify credential without proof (for testing)
+     * @param issuerPublicKey Issuer's public key
+     * @param credentialRoot Credential root
+     * @return True if issuer is trusted
+     */
+    function verifyCredentialBasic(
+        uint256 issuerPublicKey,
+        uint256 credentialRoot
+    ) external view returns (bool) {
+        return trustedIssuers[address(uint160(issuerPublicKey))];
+    }
+}

package/contracts/interfaces/IVerifier.sol

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+/**
+ * @title IVerifier
+ * @notice Interface for ZK proof verifiers generated by snarkjs
+ */
+interface IVerifier {
+    /**
+     * @notice Verify a Groth16 proof
+     * @param _pA First element of proof
+     * @param _pB Second element of proof (2x2 matrix)
+     * @param _pC Third element of proof
+     * @param _pubSignals Public inputs to the circuit
+     * @return True if proof is valid
+     */
+    function verifyProof(
+        uint256[2] calldata _pA,
+        uint256[2][2] calldata _pB,
+        uint256[2] calldata _pC,
+        uint256[] calldata _pubSignals
+    ) external view returns (bool);
+}

package/examples/create-credential.js

@@ -0,0 +1,141 @@
+/**
+ * Create Credential Example
+ * 
+ * Demonstrates how a KYC provider issues a credential to a user.
+ * 
+ * Run: node examples/create-credential.js
+ */
+
+const { VerifiableCredential, CredentialWallet, init } = require('../lib');
+
+async function main() {
+    console.log('='.repeat(70));
+    console.log('  ZK KYC/DID - Create Credential Example');
+    console.log('='.repeat(70));
+    console.log();
+    
+    // Initialize library
+    await init();
+    
+    // ========================================
+    // Step 1: User creates wallet
+    // ========================================
+    console.log('STEP 1: User Creates Wallet');
+    console.log('-'.repeat(70));
+    
+    const userWallet = new CredentialWallet();
+    await userWallet.init();
+    
+    console.log(`   User DID: ${userWallet.subjectDID}`);
+    console.log(`   (length: ${userWallet.subjectDID.length})`);
+    console.log();
+    
+    // ========================================
+    // Step 2: KYC Provider issues credential
+    // ========================================
+    console.log('STEP 2: KYC Provider Issues Credential');
+    console.log('-'.repeat(70));
+    
+    // Simulate KYC provider
+    const kycProviderPrivateKey = 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdefn;
+    const kycProviderPublicKey = '0x' + kycProviderPrivateKey.toString(16);
+    
+    // User's KYC data (this would come from actual KYC process)
+    const kycData = {
+        age: 25,
+        country: 'US',
+        documentType: 'passport',
+        documentNumber: 'P123456', // This will be hidden in commitments
+        verified: true,
+        tier: 2, // KYC tier level
+    };
+    
+    console.log('   KYC Data (will be hidden in credential):');
+    for (const [key, value] of Object.entries(kycData)) {
+        console.log(`      ${key}: ${value}`);
+    }
+    console.log();
+    
+    // Create credential
+    const credential = new VerifiableCredential({
+        issuer: kycProviderPublicKey,
+        subject: userWallet.subjectDID,
+        claims: kycData,
+        type: 'KYC',
+        expirationDate: Date.now() + 365 * 24 * 60 * 60 * 1000, // 1 year
+    });
+    
+    await credential.init();
+    credential.sign(kycProviderPrivateKey);
+    
+    console.log('   Credential Created:');
+    console.log(`      ID: ${credential.id}`);
+    console.log(`      Type: ${credential.type}`);
+    console.log(`      Issuer: ${credential.issuer.slice(0, 30)}...`);
+    console.log(`      Subject: ${credential.subject}`);
+    console.log(`      Issued: ${new Date(credential.issuedAt).toISOString()}`);
+    console.log(`      Expires: ${new Date(credential.expirationDate).toISOString()}`);
+    console.log();
+    
+    // ========================================
+    // Step 3: Show commitments (public data)
+    // ========================================
+    console.log('STEP 3: Credential Commitments (Public)');
+    console.log('-'.repeat(70));
+    
+    const commitments = credential.getAllCommitments();
+    console.log('   Commitments (visible on-chain, but values hidden):');
+    for (const [key, commitment] of Object.entries(commitments)) {
+        console.log(`      ${key}: ${commitment.slice(0, 30)}... (len: ${commitment.length})`);
+    }
+    console.log();
+    
+    // ========================================
+    // Step 4: User stores credential
+    // ========================================
+    console.log('STEP 4: User Stores Credential');
+    console.log('-'.repeat(70));
+    
+    userWallet.addCredential(credential);
+    
+    console.log(`   Credential added to wallet`);
+    console.log(`   Total credentials: ${userWallet.getAllCredentials().length}`);
+    console.log();
+    
+    // ========================================
+    // Step 5: Verify signature
+    // ========================================
+    console.log('STEP 5: Verify Credential Signature');
+    console.log('-'.repeat(70));
+    
+    const isValid = credential.verifySignature(BigInt(kycProviderPublicKey));
+    console.log(`   Signature valid: ${isValid}`);
+    console.log(`   Expired: ${credential.isExpired()}`);
+    console.log();
+    
+    // ========================================
+    // Step 6: Export for backup
+    // ========================================
+    console.log('STEP 6: Export Credential (for backup)');
+    console.log('-'.repeat(70));
+    
+    const exported = credential.toJSON();
+    const exportedStr = JSON.stringify(exported);
+    console.log(`   Exported size: ${exportedStr.length} bytes`);
+    console.log(`   Note: Actual claim values are NOT in export (privacy!)`);
+    console.log(`   User must store claims separately if needed`);
+    console.log();
+    
+    console.log('='.repeat(70));
+    console.log('  SUCCESS! Credential created and stored.');
+    console.log('='.repeat(70));
+    console.log();
+    console.log('Next steps:');
+    console.log('  1. Run: node examples/generate-proof.js');
+    console.log('  2. Run: node examples/verify-credential.js');
+}
+
+main().catch(err => {
+    console.error('Error:', err);
+    process.exit(1);
+});

package/examples/generate-proof.js

@@ -0,0 +1,176 @@
+/**
+ * Generate Proof Example
+ * 
+ * Demonstrates how a user generates a ZK proof to prove credential predicates
+ * without revealing the actual claim values.
+ * 
+ * Run: node examples/generate-proof.js
+ */
+
+const { 
+    CredentialWallet, 
+    Predicate, 
+    PredicateOp,
+    generateProofInputs,
+    preparePublicInputs,
+    init 
+} = require('../lib');
+
+async function main() {
+    console.log('='.repeat(70));
+    console.log('  ZK KYC/DID - Generate Proof Example');
+    console.log('='.repeat(70));
+    console.log();
+    
+    await init();
+    
+    // ========================================
+    // Step 1: Load user's credential
+    // ========================================
+    console.log('STEP 1: Load User Credential');
+    console.log('-'.repeat(70));
+    
+    // In a real scenario, this would be loaded from storage
+    // For demo, we'll create a sample credential
+    const wallet = new CredentialWallet();
+    await wallet.init();
+    
+    // Create a sample KYC credential
+    const { VerifiableCredential } = require('../lib');
+    const credential = new VerifiableCredential({
+        issuer: '0x1234567890abcdef1234567890abcdef12345678',
+        subject: wallet.subjectDID,
+        claims: {
+            age: 25,
+            country: 'US',
+            documentType: 'passport',
+            verified: true,
+            tier: 2,
+        },
+        type: 'KYC',
+    });
+    
+    await credential.init();
+    credential.sign(0xabcdefn); // Simplified signing
+    
+    wallet.addCredential(credential);
+    
+    console.log(`   User DID: ${wallet.subjectDID}`);
+    console.log(`   Credential ID: ${credential.id}`);
+    console.log(`   Claims in credential: ${Object.keys(credential.claims).join(', ')}`);
+    console.log();
+    
+    // ========================================
+    // Step 2: Define predicates to prove
+    // ========================================
+    console.log('STEP 2: Define Predicates to Prove');
+    console.log('-'.repeat(70));
+    
+    // User wants to prove:
+    // 1. They are 18 or older (without revealing exact age)
+    // 2. They are from an allowed country (without revealing which)
+    // 3. They are verified (without revealing other details)
+    
+    const predicates = [
+        new Predicate({
+            claimKey: 'age',
+            op: PredicateOp.GTE,
+            value: 18,
+        }),
+        new Predicate({
+            claimKey: 'country',
+            op: PredicateOp.IN,
+            value: ['US', 'UK', 'CA', 'EU'],
+        }),
+        new Predicate({
+            claimKey: 'verified',
+            op: PredicateOp.EQ,
+            value: true,
+        }),
+    ];
+    
+    console.log('   Predicates to prove:');
+    for (const pred of predicates) {
+        console.log(`      ${pred.claimKey} ${pred.op} ${JSON.stringify(pred.value)}`);
+    }
+    console.log();
+    
+    // Verify predicates are satisfied
+    console.log('   Verifying predicates are satisfied:');
+    for (const pred of predicates) {
+        const claimValue = credential.claims[pred.claimKey];
+        const satisfied = pred.evaluate(claimValue);
+        console.log(`      ${pred.claimKey}: ${claimValue} → ${satisfied ? '✓' : '✗'}`);
+    }
+    console.log();
+    
+    // ========================================
+    // Step 3: Generate proof inputs
+    // ========================================
+    console.log('STEP 3: Generate Proof Inputs');
+    console.log('-'.repeat(70));
+    
+    const privateInputs = await generateProofInputs(credential, predicates);
+    const publicInputs = preparePublicInputs(predicates, credential.issuer);
+    
+    console.log('   Private Inputs (hidden in proof):');
+    console.log(`      Claim values: ${Object.keys(privateInputs.claimValues).join(', ')}`);
+    console.log(`      Blinding factors: ${Object.keys(privateInputs.blindingFactors).join(', ')}`);
+    console.log(`      Signature: ${privateInputs.signature.slice(0, 20)}...`);
+    console.log();
+    
+    console.log('   Public Inputs (visible in proof):');
+    console.log(`      Issuer: ${publicInputs.issuerPublicKey.slice(0, 30)}...`);
+    console.log(`      Predicates: ${publicInputs.predicates.length} predicates`);
+    for (const pred of publicInputs.predicates) {
+        console.log(`         - ${pred.claimKey} ${pred.op} ${JSON.stringify(pred.value)}`);
+    }
+    console.log();
+    
+    // ========================================
+    // Step 4: What the proof proves
+    // ========================================
+    console.log('STEP 4: What the ZK Proof Proves');
+    console.log('-'.repeat(70));
+    
+    console.log('   The proof demonstrates:');
+    console.log('      1. User has a valid credential from the issuer');
+    console.log('      2. Credential signature is valid');
+    console.log('      3. age >= 18 (without revealing actual age)');
+    console.log('      4. country IN [US, UK, CA, EU] (without revealing which)');
+    console.log('      5. verified == true');
+    console.log();
+    console.log('   WITHOUT revealing:');
+    console.log('      - Exact age (could be 18, 25, 50, etc.)');
+    console.log('      - Which country (US, UK, CA, or EU)');
+    console.log('      - Other claims (documentType, tier, etc.)');
+    console.log('      - Blinding factors');
+    console.log('      - Credential signature');
+    console.log();
+    
+    // ========================================
+    // Step 5: Compute credential root
+    // ========================================
+    console.log('STEP 5: Compute Credential Root');
+    console.log('-'.repeat(70));
+    
+    const { poseidonHash } = require('../lib');
+    const commitments = Object.values(credential.claimCommitments).sort();
+    const credentialRoot = poseidonHash([...commitments, BigInt(credential.issuer)]);
+    
+    console.log(`   Credential root: 0x${credentialRoot.toString(16).slice(0, 30)}...`);
+    console.log(`   (This is the public commitment to the credential)`);
+    console.log();
+    
+    console.log('='.repeat(70));
+    console.log('  SUCCESS! Proof inputs generated.');
+    console.log('='.repeat(70));
+    console.log();
+    console.log('Next step: Generate actual ZK proof using snarkjs and verify on-chain');
+    console.log('  Run: node examples/verify-credential.js');
+}
+
+main().catch(err => {
+    console.error('Error:', err);
+    process.exit(1);
+});