noah-avalanche-sdk 0.1.2

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "noah-avalanche-sdk",
+  "version": "0.1.2",
+  "description": "Securely verify your identity using Zero-Knowledge Proofs.",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "defi",
+    "kyc",
+    "zk-proof",
+    "privacy",
+    "ethereum",
+    "blockchain"
+  ],
+  "author": "NOAH Protocol",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.6.2",
+    "ethers": "^6.0.0",
+    "tesseract.js": "^5.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "ethers": "^6.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "@tanstack/react-query": {
+      "optional": true
+    }
+  }
+}

package/src/core/APIClient.ts

@@ -0,0 +1,165 @@
+import axios, { type AxiosInstance } from 'axios';
+import type { Proof, Requirements, TransactionResult } from '../utils/types.js';
+
+/**
+ * APIClient configuration
+ */
+export interface APIClientConfig {
+  baseURL?: string;
+  timeout?: number;
+  authToken?: string;
+}
+
+/**
+ * Proof generation data
+ */
+export interface ProofGenerationData {
+  credential: {
+    age: number;
+    jurisdiction: string | number;
+    accredited: number; // 0 or 1
+    credentialHash: string;
+    userAddress?: string;
+  };
+  requirements: Requirements;
+}
+
+/**
+ * Proof generation result
+ */
+export interface ProofGenerationResult {
+  proof: Proof;
+  publicSignals: string[]; // 13 elements
+  credentialHash: string;
+  success: boolean;
+  error?: string;
+}
+
+/**
+ * Access status information
+ */
+export interface AccessStatus {
+  hasAccess: boolean;
+  protocolAddress: string;
+  userAddress: string;
+  credentialHash?: string;
+}
+
+/**
+ * Credential status information
+ */
+export interface CredentialStatus {
+  isValid: boolean;
+  credentialHash: string;
+  isRevoked: boolean;
+  issuer?: string;
+}
+
+/**
+ * APIClient - Handles backend API interactions
+ */
+export class APIClient {
+  private client: AxiosInstance;
+  private authToken: string | null = null;
+
+  constructor(config: APIClientConfig = {}) {
+    this.client = axios.create({
+      baseURL: config.baseURL || 'http://localhost:3000/api/v1',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      timeout: config.timeout || 30000,
+    });
+
+    if (config.authToken) {
+      this.setAuthToken(config.authToken);
+    }
+
+    this.client.interceptors.response.use(
+      (response) => response.data as any,
+      (error) => {
+        const errorMessage = error.response?.data?.error?.message || error.message || 'An error occurred';
+        return Promise.reject(new Error(errorMessage));
+      }
+    );
+  }
+
+  setAuthToken(token: string): void {
+    this.authToken = token;
+  }
+
+  async generateProof(proofData: ProofGenerationData): Promise<ProofGenerationResult> {
+    try {
+      const response = await this.client.post('/proof/generate', proofData) as any;
+      return {
+        proof: response.proof,
+        publicSignals: response.publicSignals || response.publicInputs || [],
+        credentialHash: response.credentialHash || proofData.credential.credentialHash,
+        success: response.success !== false,
+      };
+    } catch (error) {
+      throw new Error(`Failed to generate proof: ${error}`);
+    }
+  }
+
+  async generateAgeProof(data: {
+    mrzData: any;
+    minAge: number;
+    recipientAddress: string;
+  }): Promise<ProofGenerationResult> {
+    return this.generateProof({
+      credential: {
+        age: 0,
+        jurisdiction: "",
+        accredited: 0,
+        credentialHash: "",
+        userAddress: data.recipientAddress
+      },
+      requirements: {
+        minAge: data.minAge,
+        allowedJurisdictions: [],
+        requireAccredited: false
+      }
+    });
+  }
+
+  async getProtocolRequirements(protocolAddress: string): Promise<Requirements> {
+    const response = await this.client.get(`/user/protocol/${protocolAddress}/requirements`) as any;
+    return {
+      minAge: Number(response.minAge),
+      allowedJurisdictions: response.allowedJurisdictions || [],
+      requireAccredited: response.requireAccredited || false,
+      isSet: response.isSet !== false,
+    };
+  }
+
+  async checkAccess(protocolAddress: string, userAddress: string): Promise<AccessStatus> {
+    const response = await this.client.get(`/user/access/${protocolAddress}/${userAddress}`) as any;
+    return {
+      hasAccess: response.hasAccess || false,
+      protocolAddress,
+      userAddress,
+      credentialHash: response.credentialHash,
+    };
+  }
+
+  async registerCredential(credentialHash: string, userAddress: string): Promise<TransactionResult> {
+    const response = await this.client.post('/issuer/credential/register', { credentialHash, userAddress }) as any;
+    return { transactionHash: response.transactionHash, receipt: response.receipt || null };
+  }
+
+  async revokeCredential(credentialHash: string): Promise<TransactionResult> {
+    const response = await this.client.post('/issuer/credential/revoke', { credentialHash }) as any;
+    return { transactionHash: response.transactionHash, receipt: response.receipt || null };
+  }
+
+  async checkCredential(credentialHash: string): Promise<CredentialStatus> {
+    const response = await this.client.get(`/issuer/credential/check/${credentialHash}`) as any;
+    return {
+      isValid: response.isValid || false,
+      credentialHash,
+      isRevoked: response.isRevoked || false,
+      issuer: response.issuer,
+    };
+  }
+}

package/src/core/ContractClient.ts

@@ -0,0 +1,266 @@
+import {
+  ethers,
+  BrowserProvider,
+  JsonRpcProvider,
+  type Provider,
+  type Signer,
+  type Contract,
+  type ContractTransactionResponse,
+  type Eip1193Provider
+} from 'ethers';
+import type {
+  ContractAddresses,
+  Requirements,
+  IssuerInfo,
+  Proof,
+  ZKProof,
+  TransactionResult,
+  ContractClientConfig,
+  EventCallback
+} from '../utils/types.js';
+
+/**
+ * Contract ABIs (synchronized with production contracts)
+ */
+const CREDENTIAL_REGISTRY_ABI = [
+  'function isCredentialValid(bytes32 credentialHash) view returns (bool)',
+  'function credentials(bytes32) view returns (bool)',
+  'function revokedCredentials(bytes32) view returns (bool)',
+  'function trustedIssuers(address) view returns (bool)',
+  'function issuerNames(address) view returns (string)',
+  'function credentialIssuers(bytes32) view returns (address)',
+  'function nullifierOwners(bytes32) view returns (address)',
+  'function userToCredential(address) view returns (bytes32)',
+  'function registerCredential(bytes32 credentialHash, address user)',
+  'function registerNullifier(bytes32 nullifier, bytes32 credentialHash, address user)',
+  'function revokeCredential(bytes32 credentialHash)',
+  'function hasRole(bytes32 role, address account) view returns (bool)',
+  'event CredentialIssued(address indexed user, bytes32 indexed credentialHash, address indexed issuer, uint256 timestamp)',
+  'event CredentialRevoked(bytes32 indexed credentialHash, address indexed issuer, uint256 timestamp)',
+  'event NullifierRegistered(bytes32 indexed nullifier, bytes32 indexed credentialHash, address indexed user)',
+] as const;
+
+const PROTOCOL_ACCESS_CONTROL_ABI = [
+  'function hasAccess(address protocol, address user) view returns (bool)',
+  'function checkAccess(address user) view returns (bool)',
+  'function protocolRequirements(address) view returns (uint256 minAge, bool requireAccredited, bool isSet)',
+  'function userCredentials(address protocol, address user) view returns (bytes32)',
+  'function setRequirements(uint256 minAge, uint256[] memory allowedJurisdictions, bool requireAccredited)',
+  'function verifyAndGrantAccess(uint[2] a, uint[2][2] b, uint[2] c, uint[28] publicSignals, bytes32 credentialHash, address user)',
+  'event AccessGranted(address indexed user, address indexed protocol, bytes32 indexed credentialHash, uint256 timestamp)',
+  'event AccessRevoked(address indexed user, address indexed protocol, uint256 timestamp)',
+  'event RequirementsSet(address indexed protocol, uint256 minAge, uint256[] allowedJurisdictions, bool requireAccredited)',
+] as const;
+
+/**
+ * Contract Client Service
+ * Handles direct smart contract interactions for read and write operations
+ */
+export class ContractClient {
+  private provider: Provider | null = null;
+  private credentialRegistry: Contract | null = null;
+  private protocolAccessControl: Contract | null = null;
+  private contractAddresses: ContractAddresses;
+  private rpcUrl: string;
+
+  /**
+   * Create a new ContractClient instance
+   * @param config - Configuration options including provider, contract addresses, and RPC URL
+   */
+  constructor(config?: ContractClientConfig) {
+    this.contractAddresses = config?.contractAddresses || {
+      CredentialRegistry: '0x8E4B7e3f9F3C55DA50aB587168f1d8A011FC8e95',
+      ZKVerifier: '0x48392A1bE10b5687c06be11152675215dff14512',
+      ProtocolAccessControl: '0xb92f19431617F5B34bFDCb06E3a80533939DD71b',
+    };
+
+    this.rpcUrl = config?.rpcUrl || 'https://avax-fuji.g.alchemy.com/v2/gu3D3rKyivv6bhmb3UbyUSYxThLz7C_c';
+
+    if (config?.provider) {
+      this.initialize(config.provider);
+    }
+  }
+
+  /**
+   * Initialize provider and contracts with robust support for various provider types
+   * @param inputProvider - EIP-1193 provider (window.ethereum), Ethers Provider, or custom
+   */
+  initialize(inputProvider?: any): void {
+    if (!inputProvider) {
+      this.provider = new JsonRpcProvider(this.rpcUrl);
+    } else if (inputProvider.request) {
+      // It's an EIP-1193 provider (MetaMask, etc.)
+      this.provider = new BrowserProvider(inputProvider as Eip1193Provider);
+    } else {
+      // Assume it's already an ethers-compatible provider
+      this.provider = inputProvider as Provider;
+    }
+
+    this.credentialRegistry = new ethers.Contract(
+      this.contractAddresses.CredentialRegistry,
+      CREDENTIAL_REGISTRY_ABI,
+      this.provider
+    );
+    this.protocolAccessControl = new ethers.Contract(
+      this.contractAddresses.ProtocolAccessControl,
+      PROTOCOL_ACCESS_CONTROL_ABI,
+      this.provider
+    );
+  }
+
+  /**
+   * Pre-flight validation for proof inputs
+   */
+  validateProofInput(publicSignals: (string | number)[]): void {
+    if (!publicSignals || publicSignals.length < 28) {
+      throw new Error(`Invalid public signals length: expected 28, got ${publicSignals?.length || 0}`);
+    }
+    // Check isValid bit
+    if (publicSignals[25] != "1" && publicSignals[25] != 1) {
+      throw new Error("ZK Proof internal validation failed (isValid signal is not 1)");
+    }
+  }
+
+  async isCredentialValid(credentialHash: string): Promise<boolean> {
+    if (!this.credentialRegistry) this.initialize();
+    try {
+      return await this.credentialRegistry!.isCredentialValid(credentialHash);
+    } catch (error) {
+      throw new Error(`Failed to check credential validity: ${error}`);
+    }
+  }
+
+  async isNullifierUsed(nullifier: string): Promise<boolean> {
+    if (!this.credentialRegistry) this.initialize();
+    try {
+      const owner = await this.credentialRegistry!.nullifierOwners(nullifier);
+      return owner !== ethers.ZeroAddress;
+    } catch (error) {
+      throw new Error(`Failed to check nullifier status: ${error}`);
+    }
+  }
+
+  async getCredentialByUser(userAddress: string): Promise<string> {
+    if (!this.credentialRegistry) this.initialize();
+    try {
+      return await this.credentialRegistry!.userToCredential(userAddress);
+    } catch (error) {
+      throw new Error(`Failed to get credential by user: ${error}`);
+    }
+  }
+
+  async hasAccess(protocolAddress: string, userAddress: string): Promise<boolean> {
+    if (!this.protocolAccessControl) this.initialize();
+    try {
+      return await this.protocolAccessControl!.hasAccess(protocolAddress, userAddress);
+    } catch (error) {
+      throw new Error(`Failed to check access: ${error}`);
+    }
+  }
+
+  async getRequirements(protocolAddress: string): Promise<Requirements> {
+    if (!this.protocolAccessControl) this.initialize();
+    try {
+      const [minAge, requireAccredited, isSet] =
+        await this.protocolAccessControl!.protocolRequirements(protocolAddress);
+
+      return {
+        minAge: Number(minAge),
+        allowedJurisdictions: [],
+        requireAccredited,
+        isSet,
+      };
+    } catch (error) {
+      throw new Error(`Failed to get protocol requirements: ${error}`);
+    }
+  }
+
+  async getUserCredential(protocolAddress: string, userAddress: string): Promise<string> {
+    if (!this.protocolAccessControl) this.initialize();
+    try {
+      return await this.protocolAccessControl!.userCredentials(protocolAddress, userAddress);
+    } catch (error) {
+      throw new Error(`Failed to get user credential: ${error}`);
+    }
+  }
+
+  async registerCredential(
+    signer: Signer,
+    credentialHash: string,
+    userAddress: string
+  ): Promise<TransactionResult> {
+    if (!signer) throw new Error('Signer is required');
+    const contract = new ethers.Contract(this.contractAddresses.CredentialRegistry, CREDENTIAL_REGISTRY_ABI, signer);
+    try {
+      const tx = await contract.registerCredential(credentialHash, userAddress) as ContractTransactionResponse;
+      const receipt = await tx.wait();
+      return { transactionHash: tx.hash, receipt };
+    } catch (error) {
+      throw new Error(`Failed to register credential: ${error}`);
+    }
+  }
+
+  async revokeCredential(
+    signer: Signer,
+    credentialHash: string
+  ): Promise<TransactionResult> {
+    if (!signer) throw new Error('Signer is required');
+    const contract = new ethers.Contract(this.contractAddresses.CredentialRegistry, CREDENTIAL_REGISTRY_ABI, signer);
+    try {
+      const tx = await contract.revokeCredential(credentialHash) as ContractTransactionResponse;
+      const receipt = await tx.wait();
+      return { transactionHash: tx.hash, receipt };
+    } catch (error) {
+      throw new Error(`Failed to revoke credential: ${error}`);
+    }
+  }
+
+  async verifyAndGrantAccess(
+    signer: Signer,
+    proof: Proof | ZKProof,
+    publicSignals: (string | number)[],
+    credentialHash: string,
+    userAddress: string
+  ): Promise<TransactionResult> {
+    if (!signer) throw new Error('Signer is required to verify and grant access');
+
+    // Pre-flight check
+    this.validateProofInput(publicSignals);
+
+    const accessControl = new ethers.Contract(
+      this.contractAddresses.ProtocolAccessControl,
+      PROTOCOL_ACCESS_CONTROL_ABI,
+      signer
+    );
+
+    const a: [bigint, bigint] = [BigInt(proof.a[0]), BigInt(proof.a[1])];
+    const b: [[bigint, bigint], [bigint, bigint]] = [
+      [BigInt(proof.b[0][0]), BigInt(proof.b[0][1])],
+      [BigInt(proof.b[1][0]), BigInt(proof.b[1][1])]
+    ];
+    const c: [bigint, bigint] = [BigInt(proof.c[0]), BigInt(proof.c[1])];
+
+    const publicSignalsArray = publicSignals.slice(0, 28).map(s => BigInt(s));
+
+    try {
+      const tx = await accessControl.verifyAndGrantAccess(
+        a, b, c,
+        publicSignalsArray,
+        credentialHash,
+        userAddress
+      ) as ContractTransactionResponse;
+
+      const receipt = await tx.wait();
+      if (!receipt) throw new Error('Transaction failed: No receipt returned');
+
+      return {
+        transactionHash: tx.hash,
+        receipt,
+      };
+    } catch (error) {
+      throw new Error(`Contract verification failed: ${error}`);
+    }
+  }
+
+  getProvider(): Provider | null { return this.provider; }
+}

package/src/core/NoahSDK.ts

@@ -0,0 +1,123 @@
+import { ContractClient } from './ContractClient.js';
+import { APIClient, type APIClientConfig } from './APIClient.js';
+import { OCRExtractor } from '../utils/ocr.js';
+import { parseTD3, type MRZData } from '../utils/mrz.js';
+import type {
+    ContractClientConfig,
+    Proof,
+    TransactionResult,
+    Requirements
+} from '../utils/types.js';
+import type { Signer } from 'ethers';
+
+export class NoahError extends Error {
+    constructor(public message: string, public code: string) {
+        super(message);
+        this.name = 'NoahError';
+    }
+}
+
+export class NoahValidationError extends NoahError {
+    constructor(message: string) {
+        super(message, 'VALIDATION_ERROR');
+    }
+}
+
+export class NoahProverError extends NoahError {
+    constructor(message: string) {
+        super(message, 'PROVER_ERROR');
+    }
+}
+
+/**
+ * NoahSDK - Main entry point for the Noah Protocol
+ */
+export class NoahSDK {
+    public contracts: ContractClient;
+    public api: APIClient;
+    private ocrExtractor: OCRExtractor;
+
+    constructor(config?: ContractClientConfig & APIClientConfig) {
+        this.contracts = new ContractClient(config);
+        this.api = new APIClient(config);
+        this.ocrExtractor = new OCRExtractor();
+    }
+
+    /**
+     * Extract identity data from a document image
+     * @param image - File or URL of the passport image
+     */
+    public async extractPassportData(image: File | string | Blob): Promise<MRZData> {
+        const { mrzLines } = await this.ocrExtractor.extractMRZ(image);
+
+        if (mrzLines.length < 2) {
+            throw new NoahValidationError('Could not detect MRZ lines in the image. Please ensure the bottom part of the passport is clearly visible.');
+        }
+
+        // We assume the last two lines are the TD3 MRZ lines
+        const line1 = mrzLines[mrzLines.length - 2];
+        const line2 = mrzLines[mrzLines.length - 1];
+
+        try {
+            return parseTD3(line1, line2);
+        } catch (error) {
+            throw new NoahValidationError(`Failed to parse MRZ: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+
+    /**
+     * Initialize the SDK with a provider
+     */
+    public init(provider: any): void {
+        this.contracts.initialize(provider);
+    }
+
+    /**
+     * High-level method to prove age and grant access in one go
+     */
+    public async proveAndGrant(
+        signer: Signer,
+        protocolAddress: string,
+        mrzData: any,
+        targetAge: number
+    ): Promise<TransactionResult> {
+        try {
+            // 1. Pre-flight check requirements
+            const requirements = await this.contracts.getRequirements(protocolAddress);
+            if (requirements.minAge > targetAge) {
+                throw new NoahValidationError(`Protocol requires age ${requirements.minAge}, but target age is ${targetAge}`);
+            }
+
+            // 2. Generate Proof via API/Prover
+            const userAddress = await signer.getAddress();
+            const proofResult = await this.api.generateAgeProof({
+                mrzData,
+                minAge: targetAge,
+                recipientAddress: userAddress
+            });
+
+            if (!proofResult.success) {
+                throw new NoahProverError(proofResult.error || 'Unknown prover error');
+            }
+
+            // 3. Submit to Chain
+            return await this.contracts.verifyAndGrantAccess(
+                signer,
+                proofResult.proof,
+                proofResult.publicSignals,
+                proofResult.credentialHash,
+                userAddress
+            );
+        } catch (error) {
+            if (error instanceof NoahError) throw error;
+            throw new NoahError(error instanceof Error ? error.message : 'Unknown error', 'INTERNAL_ERROR');
+        }
+    }
+
+    /**
+     * Get protocol requirements via contract client
+     */
+    public async getProtocolRequirements(protocolAddress: string): Promise<Requirements> {
+        return this.contracts.getRequirements(protocolAddress);
+    }
+}