noah-avalanche-sdk 0.1.2

package/src/hooks/useUser.ts

@@ -0,0 +1,331 @@
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { useMemo, useState, useEffect } from 'react';
+import type { Signer } from 'ethers';
+import { UserClient, type Credential as UserCredential } from '../user/UserClient';
+import type { Requirements, TransactionResult, ZKProof } from '../utils/types';
+
+/**
+ * Configuration options for useUser hook
+ */
+export interface UseUserOptions {
+  /** User's wallet address */
+  userAddress?: string;
+  /** Protocol address to check requirements/access for */
+  protocolAddress?: string;
+  /** Credential hash to check validity for */
+  credentialHash?: string;
+  /** Whether to enable automatic refetching */
+  enabled?: boolean;
+  /** React Query configuration options */
+  queryOptions?: {
+    refetchInterval?: number;
+    staleTime?: number;
+  };
+}
+
+/**
+ * Credential structure (re-exported from UserClient for convenience)
+ */
+export type Credential = UserCredential;
+
+/**
+ * Return type for useUser hook
+ */
+export interface UseUserReturn {
+  // User client instance
+  user: UserClient | null;
+
+  // Read operations
+  protocolRequirements: Requirements | undefined;
+  isLoadingRequirements: boolean;
+  requirementsError: Error | null;
+  refetchRequirements: () => void;
+
+  // Credential validation
+  isCredentialValid: boolean | undefined;
+  isLoadingCredential: boolean;
+  credentialError: Error | null;
+  refetchCredential: () => void;
+
+  // Write operations (mutations)
+  checkCredentialValidity: {
+    mutate: (credentialHash: string) => void;
+    mutateAsync: (credentialHash: string) => Promise<boolean>;
+    isLoading: boolean;
+    error: Error | null;
+    reset: () => void;
+  };
+
+  generateProof: {
+    mutate: (params: {
+      credential: Credential;
+      requirements: Requirements & { protocolAddress: string };
+    }) => void;
+    mutateAsync: (params: {
+      credential: Credential;
+      requirements: Requirements & { protocolAddress: string };
+    }) => Promise<{
+      proof: ZKProof;
+      publicSignals: string[];
+      nullifier: string;
+      packedFlags: number;
+      credentialHash: string;
+      success: boolean;
+    }>;
+    isLoading: boolean;
+    error: Error | null;
+    reset: () => void;
+  };
+
+  verifyAndGrantAccess: {
+    mutate: (params: {
+      proof: ZKProof;
+      publicSignals: string[];
+      nullifier: string;
+      packedFlags: number;
+      credentialHash: string;
+      protocolAddress?: string;
+      userAddress?: string;
+    }) => void;
+    mutateAsync: (params: {
+      proof: ZKProof;
+      publicSignals: string[];
+      nullifier: string;
+      packedFlags: number;
+      credentialHash: string;
+      protocolAddress?: string;
+      userAddress?: string;
+    }) => Promise<TransactionResult>;
+    isLoading: boolean;
+    error: Error | null;
+    reset: () => void;
+  };
+}
+
+/**
+ * React hook for user operations
+ * 
+ * Provides easy access to user-related functionality including:
+ * - Getting protocol requirements
+ * - Checking credential validity
+ * - Generating ZK proofs
+ * - Verifying proofs and granting access to protocols
+ * 
+ * @param signer - Ethers signer instance (from wallet)
+ * @param options - Configuration options
+ * @returns Hook return object with user operations
+ * 
+ * @example
+ * ```tsx
+ * import { useUser } from '@noah-protocol/sdk/hooks';
+ * import { useSigner, useAccount } from 'wagmi';
+ * 
+ * function UserDashboard() {
+ *   const { data: signer } = useSigner();
+ *   const { address } = useAccount();
+ *   const { 
+ *     protocolRequirements,
+ *     generateProof,
+ *     verifyAndGrantAccess,
+ *     hasAccess
+ *   } = useUser(signer, {
+ *     userAddress: address,
+ *     protocolAddress: '0x...',
+ *     apiBaseUrl: 'https://api.noah.xyz'
+ *   });
+ * 
+ *   const handleGenerateProof = async () => {
+ *     const result = await generateProof.mutateAsync({
+ *       credential: {
+ *         actualAge: 25,
+ *         actualJurisdiction: 'US',
+ *         actualAccredited: true,
+ *         credentialHash: '0x...'
+ *       },
+ *       requirements: protocolRequirements!
+ *     });
+ *     
+ *     await verifyAndGrantAccess.mutateAsync({
+ *       ...result,
+ *       credentialHash: '0x...',
+ *       protocolAddress: '0x...'
+ *     });
+ *   };
+ * 
+ *   return (
+ *     <div>
+ *       {hasAccess ? (
+ *         <p>You have access!</p>
+ *       ) : (
+ *         <button onClick={handleGenerateProof}>
+ *           Request Access
+ *         </button>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useUser(
+  signer: Signer | null | undefined,
+  options: UseUserOptions = {}
+): UseUserReturn {
+  const {
+    userAddress,
+    protocolAddress,
+    credentialHash,
+    enabled = true,
+    queryOptions = {},
+  } = options;
+
+  const queryClient = useQueryClient();
+
+  // Create user client instance
+  const user = useMemo(() => {
+    if (!signer) return null;
+    try {
+      return new UserClient(signer);
+    } catch (error) {
+      console.warn('UserClient not available:', error);
+      return null;
+    }
+  }, [signer]);
+
+  // Note: userAddress is used directly in queries below
+
+  // Query: Get protocol requirements
+  const {
+    data: protocolRequirements,
+    isLoading: isLoadingRequirements,
+    error: requirementsError,
+    refetch: refetchRequirements,
+  } = useQuery({
+    queryKey: ['user', 'protocol-requirements', protocolAddress],
+    queryFn: async () => {
+      if (!user || !protocolAddress) {
+        throw new Error('User client or protocol address not available');
+      }
+      return user.getProtocolRequirements(protocolAddress);
+    },
+    enabled: enabled && !!user && !!protocolAddress,
+    ...queryOptions,
+  });
+
+  // Note: To check user access, use the useProtocol hook instead
+  // This is because access checking is a protocol-level operation
+
+  // Query: Check credential validity
+  const {
+    data: isCredentialValid,
+    isLoading: isLoadingCredential,
+    error: credentialError,
+    refetch: refetchCredential,
+  } = useQuery({
+    queryKey: ['user', 'credential-validity', credentialHash],
+    queryFn: async () => {
+      if (!user || !credentialHash) {
+        throw new Error('User client or credential hash not available');
+      }
+      return user.checkCredentialValidity(credentialHash);
+    },
+    enabled: enabled && !!user && !!credentialHash,
+    ...queryOptions,
+  });
+
+  // Mutation: Check credential validity
+  const checkCredentialValidityMutation = useMutation({
+    mutationFn: async (credentialHash: string) => {
+      if (!user) {
+        throw new Error('User client not available');
+      }
+      return user.checkCredentialValidity(credentialHash);
+    },
+  });
+
+  // Mutation: Generate proof
+  const generateProofMutation = useMutation({
+    mutationFn: async (params: {
+      credential: Credential;
+      requirements: Requirements & { protocolAddress: string };
+    }) => {
+      if (!user) {
+        throw new Error('User client not available');
+      }
+      return user.generateProof(params.credential, params.requirements);
+    },
+  });
+
+  // Mutation: Verify and grant access
+  const verifyAndGrantAccessMutation = useMutation({
+    mutationFn: async (params: {
+      proof: ZKProof;
+      publicSignals: string[];
+      nullifier: string;
+      packedFlags: number;
+      credentialHash: string;
+      protocolAddress?: string;
+      userAddress?: string;
+    }) => {
+      if (!user) {
+        throw new Error('User client not available');
+      }
+      // UserClient.verifyAndGrantAccess expects a ProofResult object
+      return user.verifyAndGrantAccess(
+        {
+          proof: params.proof,
+          publicSignals: params.publicSignals,
+          nullifier: params.nullifier,
+          packedFlags: params.packedFlags,
+          credentialHash: params.credentialHash,
+          success: true,
+        },
+        params.protocolAddress,
+        params.userAddress
+      );
+    },
+    onSuccess: () => {
+      // Invalidate and refetch access status
+      queryClient.invalidateQueries({
+        queryKey: ['user', 'access'],
+      });
+    },
+  });
+
+  return {
+    user,
+    protocolRequirements,
+    isLoadingRequirements,
+    requirementsError: requirementsError as Error | null,
+    refetchRequirements: () => {
+      refetchRequirements();
+    },
+    isCredentialValid,
+    isLoadingCredential,
+    credentialError: credentialError as Error | null,
+    refetchCredential: () => {
+      refetchCredential();
+    },
+    checkCredentialValidity: {
+      mutate: checkCredentialValidityMutation.mutate,
+      mutateAsync: checkCredentialValidityMutation.mutateAsync,
+      isLoading: checkCredentialValidityMutation.isPending,
+      error: checkCredentialValidityMutation.error as Error | null,
+      reset: checkCredentialValidityMutation.reset,
+    },
+    generateProof: {
+      mutate: generateProofMutation.mutate,
+      mutateAsync: generateProofMutation.mutateAsync,
+      isLoading: generateProofMutation.isPending,
+      error: generateProofMutation.error as Error | null,
+      reset: generateProofMutation.reset,
+    },
+    verifyAndGrantAccess: {
+      mutate: verifyAndGrantAccessMutation.mutate,
+      mutateAsync: verifyAndGrantAccessMutation.mutateAsync,
+      isLoading: verifyAndGrantAccessMutation.isPending,
+      error: verifyAndGrantAccessMutation.error as Error | null,
+      reset: verifyAndGrantAccessMutation.reset,
+    },
+  };
+}
+

package/src/index.ts

@@ -0,0 +1,80 @@
+/**
+ * NOAH Protocol SDK
+ * 
+ * TypeScript/JavaScript SDK for integrating NOAH's privacy-preserving KYC functionality
+ * into DeFi protocols and applications.
+ */
+
+// Core exports
+export { NoahSDK, NoahError, NoahValidationError, NoahProverError } from './core/NoahSDK.js';
+export { ContractClient } from './core/ContractClient.js';
+export { APIClient } from './core/APIClient.js';
+export { WalletAdapter } from './core/WalletAdapter.js';
+export type { WalletAdapterConfig, WalletState, WalletType } from './core/WalletAdapter.js';
+
+// Protocol exports
+export { ProtocolClient } from './protocol/ProtocolClient.js';
+export { RequirementsManager } from './protocol/RequirementsManager.js';
+
+// User exports
+export { UserClient } from './user/UserClient.js';
+export { ProofGenerator } from './user/ProofGenerator.js';
+export type { Credential, ProofResult, UserClientConfig } from './user/UserClient.js';
+
+// Issuer exports
+export { IssuerClient } from './issuer/IssuerClient.js';
+
+// Utilities
+export {
+  jurisdictionStringToHash,
+  jurisdictionStringsToHashes,
+  parseJurisdictions,
+} from './utils/jurisdiction.js';
+
+export {
+  generateCredentialHash,
+  isValidCredentialHash,
+  isValidAddress,
+  toChecksumAddress,
+} from './utils/credentials.js';
+
+export {
+  parseTD3,
+  validateCheckDigit,
+} from './utils/mrz.js';
+export type { MRZData } from './utils/mrz.js';
+
+export { OCRExtractor } from './utils/ocr.js';
+export type { OCROutput } from './utils/ocr.js';
+
+export { IdentityManager } from './utils/identity.js';
+export type { IdentityProfile } from './utils/identity.js';
+
+// Type exports
+export type {
+  ContractAddresses,
+  Requirements,
+  IssuerInfo,
+  Proof,
+  ZKProof,
+  TransactionResult,
+  ContractClientConfig,
+  ProtocolClientConfig,
+  SetRequirementsParams,
+  VerifyUserAccessParams,
+  CredentialIssuedEvent,
+  AccessGrantedEvent,
+  EventCallback,
+  ContractEventPayload,
+  CredentialData,
+  CredentialHashResult,
+} from './utils/types.js';
+
+// API Client types
+export type {
+  APIClientConfig,
+  ProofGenerationData,
+  ProofGenerationResult,
+  AccessStatus,
+  CredentialStatus,
+} from './core/APIClient.js';

package/src/issuer/IssuerClient.ts

@@ -0,0 +1,209 @@
+import type { Signer } from 'ethers';
+import type { TransactionResult, ContractAddresses } from '../utils/types';
+import { ContractClient } from '../core/ContractClient';
+import { APIClient } from '../core/APIClient';
+
+/**
+ * IssuerClient configuration options
+ */
+export interface IssuerClientConfig {
+  apiBaseUrl?: string;
+  contractAddresses?: Partial<ContractAddresses>;
+  rpcUrl?: string;
+}
+
+/**
+ * Credential status information
+ */
+export interface CredentialStatus {
+  isValid: boolean;
+  credentialHash: string;
+  isRevoked: boolean;
+  issuer?: string;
+}
+
+/**
+ * IssuerClient - High-level API for credential issuers
+ * 
+ * Provides a simple interface for issuers to:
+ * - Register credentials on-chain
+ * - Revoke credentials
+ * - Check credential status
+ * 
+ * @example
+ * ```typescript
+ * import { IssuerClient } from '@noah-protocol/sdk';
+ * import { ethers } from 'ethers';
+ * 
+ * const provider = new ethers.BrowserProvider(window.ethereum);
+ * const signer = await provider.getSigner();
+ * const issuer = new IssuerClient(signer, { apiBaseUrl: 'https://api.noah.xyz' });
+ * 
+ * // Register credential
+ * await issuer.registerCredential(credentialHash, userAddress);
+ * 
+ * // Revoke credential
+ * await issuer.revokeCredential(credentialHash);
+ * ```
+ */
+export class IssuerClient {
+  private signer: Signer;
+  private contractClient: ContractClient;
+  private apiClient: APIClient;
+
+  /**
+   * Create a new IssuerClient instance
+   * @param signer - Ethers.js signer from issuer's wallet
+   * @param config - Optional configuration
+   */
+  constructor(signer: Signer, config: IssuerClientConfig = {}) {
+    if (!signer) {
+      throw new Error('Signer is required');
+    }
+
+    this.signer = signer;
+
+    // Initialize ContractClient
+    this.contractClient = new ContractClient({
+      provider: signer.provider || undefined,
+      contractAddresses: config.contractAddresses as ContractAddresses | undefined,
+      rpcUrl: config.rpcUrl,
+    });
+
+    // Initialize APIClient
+    this.apiClient = new APIClient({
+      baseURL: config.apiBaseUrl,
+    });
+  }
+
+  /**
+   * Register a credential on-chain
+   * 
+   * @param credentialHash - The credential hash to register (bytes32)
+   * @param userAddress - The user's wallet address
+   * @param useAPI - If true, use backend API (gasless). If false, use direct contract call.
+   * @returns Promise resolving to transaction result
+   * 
+   * @example
+   * ```typescript
+   * const tx = await issuer.registerCredential('0x1234...', '0x5678...');
+   * console.log('Transaction hash:', tx.transactionHash);
+   * ```
+   */
+  async registerCredential(
+    credentialHash: string,
+    userAddress: string,
+    useAPI: boolean = false
+  ): Promise<TransactionResult> {
+    if (!credentialHash) {
+      throw new Error('Credential hash is required');
+    }
+
+    if (!userAddress) {
+      throw new Error('User address is required');
+    }
+
+    try {
+      if (useAPI) {
+        // Use backend API for gasless transactions
+        return await this.apiClient.registerCredential(credentialHash, userAddress);
+      } else {
+        // Use direct contract call
+        return await this.contractClient.registerCredential(
+          this.signer,
+          credentialHash,
+          userAddress
+        );
+      }
+    } catch (error: any) {
+      throw new Error(
+        `Failed to register credential: ${error.message || 'Unknown error'}`
+      );
+    }
+  }
+
+  /**
+   * Revoke a credential
+   * 
+   * @param credentialHash - The credential hash to revoke (bytes32)
+   * @param useAPI - If true, use backend API (gasless). If false, use direct contract call.
+   * @returns Promise resolving to transaction result
+   * 
+   * @example
+   * ```typescript
+   * const tx = await issuer.revokeCredential('0x1234...');
+   * console.log('Transaction hash:', tx.transactionHash);
+   * ```
+   */
+  async revokeCredential(
+    credentialHash: string,
+    useAPI: boolean = false
+  ): Promise<TransactionResult> {
+    if (!credentialHash) {
+      throw new Error('Credential hash is required');
+    }
+
+    try {
+      if (useAPI) {
+        // Use backend API for gasless transactions
+        return await this.apiClient.revokeCredential(credentialHash);
+      } else {
+        // Use direct contract call
+        return await this.contractClient.revokeCredential(
+          this.signer,
+          credentialHash
+        );
+      }
+    } catch (error: any) {
+      throw new Error(
+        `Failed to revoke credential: ${error.message || 'Unknown error'}`
+      );
+    }
+  }
+
+  /**
+   * Check credential status
+   * 
+   * @param credentialHash - The credential hash to check (bytes32)
+   * @returns Promise resolving to credential status information
+   * 
+   * @example
+   * ```typescript
+   * const status = await issuer.checkCredential('0x1234...');
+   * console.log('Is valid:', status.isValid);
+   * console.log('Is revoked:', status.isRevoked);
+   * ```
+   */
+  async checkCredential(credentialHash: string): Promise<CredentialStatus> {
+    if (!credentialHash) {
+      throw new Error('Credential hash is required');
+    }
+
+    try {
+      // Check on-chain validity
+      const isValid = await this.contractClient.isCredentialValid(credentialHash);
+      
+      // Get additional info from API if available
+      try {
+        const apiStatus = await this.apiClient.checkCredential(credentialHash);
+        return {
+          isValid: apiStatus.isValid && isValid,
+          credentialHash,
+          isRevoked: apiStatus.isRevoked,
+          issuer: apiStatus.issuer,
+        };
+      } catch {
+        // If API fails, return on-chain status
+        return {
+          isValid,
+          credentialHash,
+          isRevoked: !isValid,
+        };
+      }
+    } catch (error: any) {
+      throw new Error(
+        `Failed to check credential: ${error.message || 'Unknown error'}`
+      );
+    }
+  }
+}