noah-clarity 0.1.0

package/README.md

@@ -0,0 +1,49 @@
+# Noah-v2 SDK
+
+TypeScript/JavaScript SDK for integrating Noah-v2 KYC system into Stacks protocols.
+
+## Installation
+
+```bash
+npm install noah-clarity
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { NoahSDK } from 'noah-clarity';
+
+const sdk = new NoahSDK(
+  {
+    kycRegistryAddress: 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.kyc-registry',
+    attesterRegistryAddress: 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.attester-registry',
+    network: 'testnet',
+  },
+  {
+    appName: 'Your Protocol',
+  }
+);
+```
+
+### Check KYC Status
+
+```typescript
+const hasKYC = await sdk.contract.hasKYC(userAddress);
+if (hasKYC.hasKYC) {
+  // User has KYC
+}
+```
+
+### Require KYC for Protocol Access
+
+```typescript
+const isValid = await sdk.contract.isKYCValid(userAddress);
+if (!isValid) {
+  throw new Error('KYC required');
+}
+```
+
+Examples and integration patterns will be available when the SDK is fully implemented.
+

package/dist/config.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Configuration loader for contract addresses
+ */
+export interface ContractAddresses {
+    network: string;
+    deployer: string;
+    contracts: {
+        'attester-registry': string;
+        'attester-registry-trait': string;
+        'kyc-registry': string;
+        'revocation': string;
+    };
+    deployment_date?: string;
+    description?: string;
+}
+/**
+ * Default testnet contract addresses (deployed)
+ */
+export declare const TESTNET_CONTRACTS: ContractAddresses;
+/**
+ * Load contract addresses from JSON file or use defaults
+ * In browser environments, this can load from a static JSON file
+ * In Node.js, can use fs to read the JSON file
+ */
+export declare function loadContractAddresses(network?: 'testnet' | 'mainnet' | 'devnet'): ContractAddresses;
+/**
+ * Create SDK config from contract addresses
+ */
+export declare function createSDKConfig(addresses: ContractAddresses, options?: {
+    proverServiceUrl?: string;
+    attesterServiceUrl?: string;
+}): {
+    kycRegistryAddress: string;
+    attesterRegistryAddress: string;
+    network: "testnet" | "mainnet" | "devnet";
+    proverServiceUrl: string;
+    attesterServiceUrl: string;
+};

package/dist/config.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * Configuration loader for contract addresses
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TESTNET_CONTRACTS = void 0;
+exports.loadContractAddresses = loadContractAddresses;
+exports.createSDKConfig = createSDKConfig;
+/**
+ * Default testnet contract addresses (deployed)
+ */
+exports.TESTNET_CONTRACTS = {
+    network: 'testnet',
+    deployer: 'STVAH96MR73TP2FZG2W4X220MEB4NEMJHPMVYQNS',
+    contracts: {
+        'attester-registry': 'STVAH96MR73TP2FZG2W4X220MEB4NEMJHPMVYQNS.attester-registry',
+        'attester-registry-trait': 'STVAH96MR73TP2FZG2W4X220MEB4NEMJHPMVYQNS.attester-registry-trait',
+        'kyc-registry': 'STVAH96MR73TP2FZG2W4X220MEB4NEMJHPMVYQNS.kyc-registry',
+        'revocation': 'STVAH96MR73TP2FZG2W4X220MEB4NEMJHPMVYQNS.revocation',
+    },
+    deployment_date: '2025-01-17',
+    description: 'Deployed contract addresses for Noah-v2 KYC Registry system on Stacks Testnet',
+};
+/**
+ * Load contract addresses from JSON file or use defaults
+ * In browser environments, this can load from a static JSON file
+ * In Node.js, can use fs to read the JSON file
+ */
+function loadContractAddresses(network = 'testnet') {
+    // For now, return hardcoded testnet addresses
+    // In production, you might want to:
+    // 1. Load from a JSON file
+    // 2. Fetch from a registry/API
+    // 3. Use environment variables
+    if (network === 'testnet') {
+        return exports.TESTNET_CONTRACTS;
+    }
+    // TODO: Add mainnet addresses when deployed
+    throw new Error(`Contract addresses for ${network} not yet configured`);
+}
+/**
+ * Create SDK config from contract addresses
+ */
+function createSDKConfig(addresses, options) {
+    return {
+        kycRegistryAddress: addresses.contracts['kyc-registry'],
+        attesterRegistryAddress: addresses.contracts['attester-registry'],
+        network: addresses.network,
+        proverServiceUrl: options?.proverServiceUrl || 'http://localhost:8080',
+        attesterServiceUrl: options?.attesterServiceUrl || 'http://localhost:8081',
+    };
+}

package/dist/contract.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Clarity contract interaction helpers
+ */
+import { SDKConfig, KYCStatus, RegisterKYCParams } from './types';
+export declare class KYCContract {
+    private config;
+    private network;
+    constructor(config: SDKConfig);
+    private getNetwork;
+    /**
+     * Register KYC on-chain
+     * @param params Registration parameters
+     * @param privateKey Private key for signing transaction
+     * @returns Transaction ID
+     */
+    registerKYC(params: RegisterKYCParams, privateKey: string): Promise<string>;
+    /**
+     * Check if a user has valid KYC
+     * @param userPrincipal User's Stacks principal
+     * @returns KYC status
+     */
+    hasKYC(userPrincipal: string): Promise<KYCStatus>;
+    /**
+     * Check if KYC is valid
+     * Since KYC records don't expire, this is equivalent to hasKYC
+     * @param userPrincipal User's Stacks principal
+     * @returns true if KYC is valid
+     */
+    isKYCValid(userPrincipal: string): Promise<boolean>;
+    /**
+     * Get KYC details for a user
+     * @param userPrincipal User's Stacks principal
+     * @returns KYC details or null
+     */
+    getKYC(userPrincipal: string): Promise<KYCStatus | null>;
+    /**
+     * Parse contract address from contract identifier (e.g., "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.kyc-registry")
+     */
+    private parseContractAddress;
+}

package/dist/contract.js

@@ -0,0 +1,152 @@
+"use strict";
+/**
+ * Clarity contract interaction helpers
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KYCContract = void 0;
+const transactions_1 = require("@stacks/transactions");
+const network_1 = require("@stacks/network");
+class KYCContract {
+    constructor(config) {
+        this.config = config;
+        this.network = this.getNetwork();
+    }
+    getNetwork() {
+        switch (this.config.network) {
+            case 'mainnet':
+                return new network_1.StacksMainnet();
+            case 'testnet':
+                return new network_1.StacksTestnet();
+            default:
+                return new network_1.StacksTestnet();
+        }
+    }
+    /**
+     * Register KYC on-chain
+     * @param params Registration parameters
+     * @param privateKey Private key for signing transaction
+     * @returns Transaction ID
+     */
+    async registerKYC(params, privateKey) {
+        const senderAddress = (0, transactions_1.getAddressFromPrivateKey)(privateKey, this.network.version);
+        const { address, name } = this.parseContractAddress(this.config.kycRegistryAddress);
+        const functionArgs = [
+            (0, transactions_1.bufferCV)(Buffer.from(params.commitment.replace('0x', ''), 'hex')),
+            (0, transactions_1.bufferCV)(Buffer.from(params.signature.replace('0x', ''), 'hex')),
+            (0, transactions_1.uintCV)(params.attesterId),
+        ];
+        const txOptions = {
+            contractAddress: address,
+            contractName: name,
+            functionName: 'register-kyc',
+            functionArgs,
+            senderKey: privateKey,
+            fee: 1000,
+            network: this.network,
+            anchorMode: transactions_1.AnchorMode.Any,
+            postConditionMode: transactions_1.PostConditionMode.Allow,
+        };
+        try {
+            const transaction = await (0, transactions_1.makeContractCall)(txOptions);
+            const broadcastResponse = await (0, transactions_1.broadcastTransaction)(transaction, this.network);
+            return broadcastResponse.txid;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Transaction failed: ${error.message}`);
+            }
+            throw new Error(`Transaction failed: ${String(error)}`);
+        }
+    }
+    /**
+     * Check if a user has valid KYC
+     * @param userPrincipal User's Stacks principal
+     * @returns KYC status
+     */
+    async hasKYC(userPrincipal) {
+        const { address, name } = this.parseContractAddress(this.config.kycRegistryAddress);
+        try {
+            const result = await (0, transactions_1.callReadOnlyFunction)({
+                contractAddress: address,
+                contractName: name,
+                functionName: 'has-kyc?',
+                functionArgs: [(0, transactions_1.principalCV)(userPrincipal)],
+                network: this.network,
+                senderAddress: address, // Use contract address as sender for read-only calls
+            });
+            const jsonResult = (0, transactions_1.cvToJSON)(result);
+            // Result is (ok bool), so check if it's ok and the value is true
+            if (jsonResult.type === 'responseOk') {
+                const hasKYC = jsonResult.value.value === true;
+                return { hasKYC };
+            }
+            else {
+                return { hasKYC: false };
+            }
+        }
+        catch (error) {
+            console.error('Error checking KYC status:', error);
+            return { hasKYC: false };
+        }
+    }
+    /**
+     * Check if KYC is valid
+     * Since KYC records don't expire, this is equivalent to hasKYC
+     * @param userPrincipal User's Stacks principal
+     * @returns true if KYC is valid
+     */
+    async isKYCValid(userPrincipal) {
+        const status = await this.hasKYC(userPrincipal);
+        return status.hasKYC;
+    }
+    /**
+     * Get KYC details for a user
+     * @param userPrincipal User's Stacks principal
+     * @returns KYC details or null
+     */
+    async getKYC(userPrincipal) {
+        const { address, name } = this.parseContractAddress(this.config.kycRegistryAddress);
+        try {
+            const result = await (0, transactions_1.callReadOnlyFunction)({
+                contractAddress: address,
+                contractName: name,
+                functionName: 'get-kyc',
+                functionArgs: [(0, transactions_1.principalCV)(userPrincipal)],
+                network: this.network,
+                senderAddress: address,
+            });
+            const jsonResult = (0, transactions_1.cvToJSON)(result);
+            // Result is (ok (some kyc-record)) or (ok none)
+            if (jsonResult.type === 'responseOk' && jsonResult.value.type === 'optionalSome') {
+                const record = jsonResult.value.value.value;
+                return {
+                    hasKYC: true,
+                    commitment: record.commitment?.value,
+                    attesterId: record['attester-id']?.value,
+                    registeredAt: record['registered-at']?.value,
+                };
+            }
+            else {
+                return null;
+            }
+        }
+        catch (error) {
+            console.error('Error getting KYC details:', error);
+            return null;
+        }
+    }
+    /**
+     * Parse contract address from contract identifier (e.g., "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.kyc-registry")
+     */
+    parseContractAddress(contractId) {
+        const parts = contractId.split('.');
+        if (parts.length !== 2) {
+            throw new Error(`Invalid contract address format: ${contractId}. Expected format: ADDRESS.contract-name`);
+        }
+        return {
+            address: parts[0],
+            name: parts[1],
+        };
+    }
+}
+exports.KYCContract = KYCContract;

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Noah-v2 SDK
+ * Main entry point for protocol integration
+ */
+export { KYCContract } from './contract';
+export { ProofService } from './proof';
+export { WalletHelper } from './wallet';
+export * from './types';
+import { KYCContract } from './contract';
+import { ProofService } from './proof';
+import { WalletHelper } from './wallet';
+import { SDKConfig, WalletConfig } from './types';
+/**
+ * Main SDK class
+ */
+export declare class NoahSDK {
+    contract: KYCContract;
+    proof: ProofService;
+    wallet: WalletHelper;
+    constructor(config: SDKConfig, walletConfig: WalletConfig);
+    /**
+     * Complete KYC registration flow
+     * 1. Generate proof
+     * 2. Get attestation
+     * 3. Register on-chain
+     */
+    registerKYC(proofRequest: any, privateKey: string): Promise<string>;
+}
+export default NoahSDK;

package/dist/index.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Noah-v2 SDK
+ * Main entry point for protocol integration
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoahSDK = exports.WalletHelper = exports.ProofService = exports.KYCContract = void 0;
+var contract_1 = require("./contract");
+Object.defineProperty(exports, "KYCContract", { enumerable: true, get: function () { return contract_1.KYCContract; } });
+var proof_1 = require("./proof");
+Object.defineProperty(exports, "ProofService", { enumerable: true, get: function () { return proof_1.ProofService; } });
+var wallet_1 = require("./wallet");
+Object.defineProperty(exports, "WalletHelper", { enumerable: true, get: function () { return wallet_1.WalletHelper; } });
+__exportStar(require("./types"), exports);
+const contract_2 = require("./contract");
+const proof_2 = require("./proof");
+const wallet_2 = require("./wallet");
+/**
+ * Main SDK class
+ */
+class NoahSDK {
+    constructor(config, walletConfig) {
+        this.contract = new contract_2.KYCContract(config);
+        this.proof = new proof_2.ProofService(config);
+        this.wallet = new wallet_2.WalletHelper(walletConfig);
+    }
+    /**
+     * Complete KYC registration flow
+     * 1. Generate proof
+     * 2. Get attestation
+     * 3. Register on-chain
+     */
+    async registerKYC(proofRequest, privateKey) {
+        // Step 1: Generate proof
+        const proofResponse = await this.proof.generateProof(proofRequest);
+        if (!proofResponse.success) {
+            throw new Error(`Proof generation failed: ${proofResponse.error}`);
+        }
+        // Step 2: Get attestation
+        const attestationResponse = await this.proof.requestAttestation({
+            commitment: proofResponse.commitment,
+            public_inputs: proofResponse.public_inputs,
+            proof: proofResponse.proof,
+            user_id: '', // Set from user session
+        });
+        if (!attestationResponse.success) {
+            throw new Error(`Attestation failed: ${attestationResponse.error}`);
+        }
+        // Step 3: Register on-chain
+        const txId = await this.contract.registerKYC({
+            commitment: attestationResponse.commitment,
+            signature: attestationResponse.signature,
+            attesterId: attestationResponse.attester_id,
+        }, privateKey);
+        return txId;
+    }
+}
+exports.NoahSDK = NoahSDK;
+// Default export
+exports.default = NoahSDK;

package/dist/proof.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Proof generation and verification utilities
+ */
+import { ProofRequest, ProofResponse, AttestationRequest, AttestationResponse, SDKConfig } from './types';
+export declare class ProofService {
+    private proverServiceUrl;
+    private attesterServiceUrl;
+    constructor(config: SDKConfig);
+    /**
+     * Generate a ZK proof
+     * @param request Proof generation request
+     * @returns Proof response
+     */
+    generateProof(request: ProofRequest): Promise<ProofResponse>;
+    /**
+     * Request an attestation signature from the attester
+     * @param request Attestation request
+     * @returns Attestation response
+     */
+    requestAttestation(request: AttestationRequest): Promise<AttestationResponse>;
+    /**
+     * Verify a proof (off-chain verification)
+     * Note: This is a placeholder - actual verification would use the verification key
+     * @param proof Serialized proof
+     * @param publicInputs Public inputs
+     * @returns true if proof is valid
+     */
+    verifyProof(proof: string, publicInputs: string[]): Promise<boolean>;
+}

package/dist/proof.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * Proof generation and verification utilities
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProofService = void 0;
+class ProofService {
+    constructor(config) {
+        this.proverServiceUrl = config.proverServiceUrl || 'http://localhost:8080';
+        this.attesterServiceUrl = config.attesterServiceUrl || 'http://localhost:8081';
+    }
+    /**
+     * Generate a ZK proof
+     * @param request Proof generation request
+     * @returns Proof response
+     */
+    async generateProof(request) {
+        const response = await fetch(`${this.proverServiceUrl}/proof/generate`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(request),
+        });
+        if (!response.ok) {
+            let errorMessage = response.statusText;
+            try {
+                const errorData = await response.json();
+                errorMessage = errorData.error || errorMessage;
+            }
+            catch {
+                // If response is not JSON, use statusText
+            }
+            throw new Error(`Proof generation failed: ${errorMessage}`);
+        }
+        const data = await response.json();
+        return data;
+    }
+    /**
+     * Request an attestation signature from the attester
+     * @param request Attestation request
+     * @returns Attestation response
+     */
+    async requestAttestation(request) {
+        const response = await fetch(`${this.attesterServiceUrl}/credential/attest`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(request),
+        });
+        if (!response.ok) {
+            let errorMessage = response.statusText;
+            try {
+                const errorData = await response.json();
+                errorMessage = errorData.error || errorMessage;
+            }
+            catch {
+                // If response is not JSON, use statusText
+            }
+            throw new Error(`Attestation failed: ${errorMessage}`);
+        }
+        const data = await response.json();
+        return data;
+    }
+    /**
+     * Verify a proof (off-chain verification)
+     * Note: This is a placeholder - actual verification would use the verification key
+     * @param proof Serialized proof
+     * @param publicInputs Public inputs
+     * @returns true if proof is valid
+     */
+    async verifyProof(proof, publicInputs) {
+        // In production, this would:
+        // 1. Deserialize the proof
+        // 2. Load the verification key
+        // 3. Verify using gnark or similar library
+        // For now, return true as a placeholder
+        return true;
+    }
+}
+exports.ProofService = ProofService;

package/dist/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Type definitions for Noah-v2 SDK
+ */
+export interface KYCStatus {
+    hasKYC: boolean;
+    commitment?: string;
+    attesterId?: number;
+    registeredAt?: number;
+}
+export interface RegisterKYCParams {
+    commitment: string;
+    signature: string;
+    attesterId: number;
+}
+export interface ProofRequest {
+    age: string;
+    jurisdiction: string;
+    is_accredited: string;
+    identity_data: string;
+    nonce: string;
+    min_age: string;
+    allowed_jurisdictions: string[];
+    require_accreditation: string;
+    commitment: string;
+}
+export interface ProofResponse {
+    proof: string;
+    public_inputs: string[];
+    commitment: string;
+    success: boolean;
+    error?: string;
+}
+export interface AttestationRequest {
+    commitment: string;
+    public_inputs: string[];
+    proof: string;
+    user_id: string;
+}
+export interface AttestationResponse {
+    commitment: string;
+    signature: string;
+    attester_id: number;
+    success: boolean;
+    error?: string;
+}
+export interface SDKConfig {
+    kycRegistryAddress: string;
+    attesterRegistryAddress: string;
+    proverServiceUrl?: string;
+    attesterServiceUrl?: string;
+    network?: 'mainnet' | 'testnet' | 'devnet';
+}
+export interface WalletConfig {
+    appName: string;
+    appIcon?: string;
+    redirectPath?: string;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Type definitions for Noah-v2 SDK
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/wallet.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Wallet integration helpers
+ */
+import { UserSession } from '@stacks/connect';
+import { WalletConfig } from './types';
+export declare class WalletHelper {
+    private config;
+    constructor(config: WalletConfig);
+    /**
+     * Get app name
+     */
+    getAppName(): string;
+    /**
+     * Check if user is authenticated
+     */
+    isAuthenticated(session: UserSession | null): boolean;
+    /**
+     * Get user's Stacks address from session
+     */
+    getUserAddress(session: UserSession | null): string | null;
+}

package/dist/wallet.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Wallet integration helpers
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WalletHelper = void 0;
+class WalletHelper {
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Get app name
+     */
+    getAppName() {
+        return this.config.appName;
+    }
+    /**
+     * Check if user is authenticated
+     */
+    isAuthenticated(session) {
+        return session !== null && session.isUserSignedIn();
+    }
+    /**
+     * Get user's Stacks address from session
+     */
+    getUserAddress(session) {
+        if (!this.isAuthenticated(session)) {
+            return null;
+        }
+        const userData = session.loadUserData();
+        return userData.profile.stxAddress.mainnet || userData.profile.stxAddress.testnet;
+    }
+}
+exports.WalletHelper = WalletHelper;

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "noah-clarity",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for Noah-v2 KYC system on Stacks",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "jest",
+    "test:local": "ts-node test-local.ts",
+    "lint": "eslint src --ext .ts"
+  },
+  "keywords": [
+    "stacks",
+    "kyc",
+    "zero-knowledge",
+    "zk-proof",
+    "clarity",
+    "blockchain",
+    "privacy",
+    "identity"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Samuel1-ona/Noah-Clarity.git",
+    "directory": "packages/noah-sdk"
+  },
+  "dependencies": {
+    "@stacks/connect": "^6.0.0",
+    "@stacks/network": "^6.17.0",
+    "@stacks/transactions": "^6.0.0"
+  },
+  "devDependencies": {
+    "@types/bip39": "^2.4.2",
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "bip39": "^3.1.0",
+    "dotenv": "^17.2.3",
+    "ed25519-hd-key": "^1.3.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.0.0"
+  }
+}