@zkproofport-app/sdk 0.1.2-beta.1

package/dist/index.js

@@ -0,0 +1,2364 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var QRCode = require('qrcode');
+var ethers = require('ethers');
+
+/**
+ * ZKProofport SDK Constants
+ */
+/**
+ * Pre-configured relay server URLs for each environment.
+ * Used by `ProofportSDK.create('production')` for zero-config initialization.
+ *
+ * @example
+ * ```typescript
+ * const sdk = ProofportSDK.create('production');
+ * // Uses RELAY_URLS.production = 'https://relay.zkproofport.app'
+ * ```
+ */
+const RELAY_URLS = {
+    production: 'https://relay.zkproofport.app',
+    staging: 'https://stg-relay.zkproofport.app',
+    local: 'http://localhost:4001',
+};
+/**
+ * Default deep link URL scheme for ZKProofport mobile app.
+ * Used to construct deep link URLs that open the mobile app.
+ *
+ * @example
+ * ```typescript
+ * const deepLink = `${DEFAULT_SCHEME}://proof-request?...`;
+ * // Results in: zkproofport://proof-request?...
+ * ```
+ */
+const DEFAULT_SCHEME = 'zkproofport';
+/**
+ * Deep link URL hosts for different proof request flows.
+ * Used as the host component in deep link URLs.
+ *
+ * @example
+ * ```typescript
+ * const requestUrl = `zkproofport://${DEEP_LINK_HOSTS.PROOF_REQUEST}`;
+ * const responseUrl = `zkproofport://${DEEP_LINK_HOSTS.PROOF_RESPONSE}`;
+ * ```
+ */
+const DEEP_LINK_HOSTS = {
+    /** Host for proof requests sent to mobile app */
+    PROOF_REQUEST: 'proof-request'};
+/**
+ * Circuit metadata containing display names, descriptions, and public input specifications.
+ * Each circuit has a defined number and layout of public inputs that must match
+ * the Noir circuit definition.
+ *
+ * @example
+ * ```typescript
+ * const metadata = CIRCUIT_METADATA['coinbase_attestation'];
+ * console.log(metadata.name); // "Coinbase KYC"
+ * console.log(metadata.publicInputsCount); // 2
+ * ```
+ */
+const CIRCUIT_METADATA = {
+    coinbase_attestation: {
+        name: 'Coinbase KYC',
+        description: 'Prove Coinbase identity verification',
+        publicInputsCount: 2,
+        publicInputNames: ['signal_hash', 'signer_list_merkle_root'],
+    },
+    coinbase_country_attestation: {
+        name: 'Coinbase Country',
+        description: 'Prove Coinbase country verification',
+        publicInputsCount: 14,
+        publicInputNames: ['signal_hash', 'signer_list_merkle_root', 'country_list', 'country_list_length', 'is_included'],
+    },
+};
+/**
+ * Standard verifier contract ABI shared across all Barretenberg-generated verifiers.
+ * This ABI defines the interface for calling the verify function on deployed verifier contracts.
+ *
+ * Uses ethers v6 human-readable ABI format.
+ *
+ * @example
+ * ```typescript
+ * import { Contract } from 'ethers';
+ *
+ * const verifier = new Contract(verifierAddress, VERIFIER_ABI, provider);
+ * const isValid = await verifier.verify(proofBytes, publicInputs);
+ * ```
+ */
+const VERIFIER_ABI = [
+    'function verify(bytes calldata _proof, bytes32[] calldata _publicInputs) external view returns (bool)',
+];
+/**
+ * Public RPC endpoint URLs for supported blockchain networks.
+ * Used as fallback when no custom provider is supplied.
+ *
+ * Supported networks:
+ * - 84532: Base Sepolia (testnet)
+ * - 8453: Base Mainnet (production)
+ *
+ * @example
+ * ```typescript
+ * import { JsonRpcProvider } from 'ethers';
+ *
+ * const provider = new JsonRpcProvider(RPC_ENDPOINTS[84532]);
+ * ```
+ */
+const RPC_ENDPOINTS = {
+    84532: 'https://sepolia.base.org', // Base Sepolia
+    8453: 'https://mainnet.base.org', // Base Mainnet
+};
+/**
+ * Default proof request expiration time in milliseconds.
+ * Requests older than this are considered expired and should not be processed.
+ *
+ * Default: 10 minutes (600,000 ms)
+ *
+ * @example
+ * ```typescript
+ * const request: ProofRequest = {
+ *   // ...
+ *   createdAt: Date.now(),
+ *   expiresAt: Date.now() + DEFAULT_REQUEST_EXPIRY_MS
+ * };
+ * ```
+ */
+const DEFAULT_REQUEST_EXPIRY_MS = 10 * 60 * 1000;
+/**
+ * Maximum data size (in bytes) that can be encoded in a QR code.
+ * Based on QR Code Version 40 with L (Low) error correction level.
+ *
+ * Requests exceeding this size should use alternative methods (HTTP, WebSocket).
+ *
+ * @example
+ * ```typescript
+ * const deepLinkUrl = generateDeepLink(request);
+ * if (deepLinkUrl.length > MAX_QR_DATA_SIZE) {
+ *   console.warn('Request too large for QR code');
+ * }
+ * ```
+ */
+const MAX_QR_DATA_SIZE = 2953; // Version 40 with L error correction
+/**
+ * ZKProofportNullifierRegistry contract ABI (V2).
+ *
+ * This is the current nullifier registry interface with relayer-only registration.
+ * Public view functions allow checking nullifier status and verifying proofs without registration.
+ *
+ * Key functions:
+ * - `isNullifierRegistered`: Check if a nullifier has been used
+ * - `getNullifierInfo`: Get registration details for a nullifier
+ * - `verifyOnly`: Verify a proof without registering the nullifier
+ *
+ * Note: Registration functions (verifyAndRegister) are relayer-only and not exposed in this ABI.
+ *
+ * @example
+ * ```typescript
+ * import { Contract } from 'ethers';
+ *
+ * const registry = new Contract(
+ *   registryAddress,
+ *   ZKPROOFPORT_NULLIFIER_REGISTRY_ABI,
+ *   provider
+ * );
+ *
+ * const isUsed = await registry.isNullifierRegistered(nullifier);
+ * ```
+ */
+const ZKPROOFPORT_NULLIFIER_REGISTRY_ABI = [
+    'function isNullifierRegistered(bytes32 _nullifier) external view returns (bool)',
+    'function getNullifierInfo(bytes32 _nullifier) external view returns (uint64 registeredAt, bytes32 scope, bytes32 circuitId)',
+    'function verifyOnly(bytes32 _circuitId, bytes calldata _proof, bytes32[] calldata _publicInputs) external view returns (bool)',
+    'event NullifierRegistered(bytes32 indexed nullifier, bytes32 indexed scope, bytes32 indexed circuitId)',
+];
+
+var constants = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    CIRCUIT_METADATA: CIRCUIT_METADATA,
+    DEEP_LINK_HOSTS: DEEP_LINK_HOSTS,
+    DEFAULT_REQUEST_EXPIRY_MS: DEFAULT_REQUEST_EXPIRY_MS,
+    DEFAULT_SCHEME: DEFAULT_SCHEME,
+    MAX_QR_DATA_SIZE: MAX_QR_DATA_SIZE,
+    RELAY_URLS: RELAY_URLS,
+    RPC_ENDPOINTS: RPC_ENDPOINTS,
+    VERIFIER_ABI: VERIFIER_ABI,
+    ZKPROOFPORT_NULLIFIER_REGISTRY_ABI: ZKPROOFPORT_NULLIFIER_REGISTRY_ABI
+});
+
+/**
+ * Deep Link utilities for ZKProofport SDK
+ */
+/**
+ * Generates a unique request ID for proof requests.
+ *
+ * Creates an ID by combining a base36-encoded timestamp with a random string,
+ * prefixed with "req-". This ensures uniqueness across concurrent requests.
+ *
+ * @returns A unique string identifier in the format "req-{timestamp}-{random}"
+ *
+ * @example
+ * ```typescript
+ * const id = generateRequestId();
+ * // "req-lh8k3f2g-a9b7c4d2"
+ * ```
+ */
+function generateRequestId() {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2, 10);
+    return `req-${timestamp}-${random}`;
+}
+/**
+ * Encodes an object into a URL-safe base64url string with UTF-8 support.
+ *
+ * Converts the input object to JSON, then encodes it using base64url format
+ * (RFC 4648 §5) which replaces '+' with '-', '/' with '_', and removes padding.
+ * Works in both browser and Node.js environments.
+ *
+ * @param data - The object to encode (will be JSON stringified)
+ * @returns Base64url-encoded string safe for URL parameters
+ *
+ * @example
+ * ```typescript
+ * const encoded = encodeData({ circuit: 'coinbase_attestation', requestId: 'req-123' });
+ * // "eyJjaXJjdWl0IjoiY29pbmJhc2VfYXR0ZXN0YXRpb24iLCJyZXF1ZXN0SWQiOiJyZXEtMTIzIn0"
+ * ```
+ */
+function encodeData(data) {
+    const json = JSON.stringify(data);
+    // Use base64url encoding (URL-safe) with UTF-8 support
+    if (typeof btoa === 'function') {
+        // Browser: UTF-8 encode first, then base64
+        const utf8Encoded = encodeURIComponent(json).replace(/%([0-9A-F]{2})/g, (_, p1) => String.fromCharCode(parseInt(p1, 16)));
+        return btoa(utf8Encoded)
+            .replace(/\+/g, '-')
+            .replace(/\//g, '_')
+            .replace(/=+$/, '');
+    }
+    // Node.js environment
+    return Buffer.from(json, 'utf-8')
+        .toString('base64')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/, '');
+}
+/**
+ * Decodes a base64url-encoded string back into a typed object.
+ *
+ * Reverses the encoding process by converting base64url to standard base64,
+ * decoding it, and parsing the resulting JSON. Handles UTF-8 correctly in
+ * both browser and Node.js environments.
+ *
+ * @typeParam T - The expected type of the decoded object
+ * @param encoded - Base64url-encoded string (from encodeData)
+ * @returns Decoded and parsed object of type T
+ *
+ * @throws {SyntaxError} If the decoded string is not valid JSON
+ *
+ * @example
+ * ```typescript
+ * const request = decodeData<ProofRequest>(encodedString);
+ * console.log(request.circuit); // "coinbase_attestation"
+ * ```
+ */
+function decodeData(encoded) {
+    // Restore base64 padding
+    let base64 = encoded.replace(/-/g, '+').replace(/_/g, '/');
+    while (base64.length % 4) {
+        base64 += '=';
+    }
+    let json;
+    if (typeof atob === 'function') {
+        // Browser: decode base64, then UTF-8 decode
+        const decoded = atob(base64);
+        json = decodeURIComponent(decoded.split('').map(c => '%' + ('00' + c.charCodeAt(0).toString(16)).slice(-2)).join(''));
+    }
+    else {
+        json = Buffer.from(base64, 'base64').toString('utf-8');
+    }
+    return JSON.parse(json);
+}
+/**
+ * Builds a deep link URL for a proof request.
+ *
+ * Encodes the proof request and constructs a deep link URL that can be opened
+ * by the ZKProofport mobile app. The URL format is:
+ * `{scheme}://proof-request?data={encodedRequest}`
+ *
+ * @param request - The proof request to encode in the deep link
+ * @param scheme - Custom URL scheme (defaults to "zkproofport")
+ * @returns Complete deep link URL ready to be opened or embedded in a QR code
+ *
+ * @example
+ * ```typescript
+ * const request: ProofRequest = {
+ *   requestId: generateRequestId(),
+ *   circuit: 'coinbase_attestation',
+ *   inputs: { scope: 'myapp.com' },
+ *   createdAt: Date.now()
+ * };
+ * const url = buildProofRequestUrl(request);
+ * // "zkproofport://proof-request?data=eyJyZXF1ZXN0SWQi..."
+ * ```
+ */
+function buildProofRequestUrl(request, scheme = DEFAULT_SCHEME) {
+    const encodedRequest = encodeData(request);
+    return `${scheme}://${DEEP_LINK_HOSTS.PROOF_REQUEST}?data=${encodedRequest}`;
+}
+/**
+ * Parses a proof request from a deep link URL.
+ *
+ * Extracts and decodes the proof request data from a ZKProofport deep link URL.
+ * Returns null if the URL is invalid or missing required parameters.
+ *
+ * @param url - Deep link URL (e.g., "zkproofport://proof-request?data=...")
+ * @returns Decoded ProofRequest object, or null if parsing fails
+ *
+ * @example
+ * ```typescript
+ * const url = "zkproofport://proof-request?data=eyJyZXF1ZXN0SWQi...";
+ * const request = parseProofRequestUrl(url);
+ * if (request) {
+ *   console.log(request.circuit); // "coinbase_attestation"
+ * }
+ * ```
+ */
+function parseProofRequestUrl(url) {
+    try {
+        const urlObj = new URL(url);
+        const data = urlObj.searchParams.get('data');
+        if (!data) {
+            return null;
+        }
+        return decodeData(data);
+    }
+    catch (error) {
+        console.error('Failed to parse proof request URL:', error);
+        return null;
+    }
+}
+/**
+ * Parses a proof response from a callback URL.
+ *
+ * Extracts proof response data from query parameters in a callback URL.
+ * Handles both successful proof completions and error responses.
+ * Returns null if required parameters (requestId, status) are missing.
+ *
+ * @param url - Callback URL with proof response query parameters
+ * @returns Decoded ProofResponse object, or null if parsing fails
+ *
+ * @example
+ * ```typescript
+ * const callbackUrl = "https://example.com/callback?requestId=req-123&status=completed&proof=0x...";
+ * const response = parseProofResponseUrl(callbackUrl);
+ * if (response && response.status === 'completed') {
+ *   console.log(response.proof); // "0x..."
+ * }
+ * ```
+ */
+function parseProofResponseUrl(url) {
+    try {
+        const urlObj = new URL(url);
+        const requestId = urlObj.searchParams.get('requestId');
+        const status = urlObj.searchParams.get('status');
+        if (!requestId || !status) {
+            return null;
+        }
+        const response = {
+            requestId,
+            circuit: urlObj.searchParams.get('circuit') || 'coinbase_attestation',
+            status,
+        };
+        if (status === 'completed') {
+            response.proof = urlObj.searchParams.get('proof') || undefined;
+            const publicInputsStr = urlObj.searchParams.get('publicInputs');
+            if (publicInputsStr) {
+                response.publicInputs = publicInputsStr.split(',');
+            }
+            const numPublicInputs = urlObj.searchParams.get('numPublicInputs');
+            if (numPublicInputs) {
+                response.numPublicInputs = parseInt(numPublicInputs, 10);
+            }
+            const timestamp = urlObj.searchParams.get('timestamp');
+            if (timestamp) {
+                response.timestamp = parseInt(timestamp, 10);
+            }
+            response.nullifier = urlObj.searchParams.get('nullifier') || undefined;
+        }
+        else if (status === 'error') {
+            response.error = urlObj.searchParams.get('error') || undefined;
+        }
+        return response;
+    }
+    catch (error) {
+        console.error('Failed to parse proof response URL:', error);
+        return null;
+    }
+}
+/**
+ * Checks if a URL is a valid ZKProofport deep link.
+ *
+ * Performs a case-insensitive check to see if the URL starts with the
+ * ZKProofport scheme. Does not validate the URL structure beyond the scheme.
+ *
+ * @param url - URL to check
+ * @param scheme - Expected URL scheme (defaults to "zkproofport")
+ * @returns True if the URL starts with the specified scheme
+ *
+ * @example
+ * ```typescript
+ * isProofportDeepLink("zkproofport://proof-request?data=..."); // true
+ * isProofportDeepLink("https://example.com"); // false
+ * isProofportDeepLink("ZKPROOFPORT://proof-request"); // true (case-insensitive)
+ * ```
+ */
+function isProofportDeepLink(url, scheme = DEFAULT_SCHEME) {
+    return url.toLowerCase().startsWith(`${scheme.toLowerCase()}://`);
+}
+/**
+ * @internal
+ * Validates a proof request for completeness and correctness.
+ *
+ * Performs comprehensive validation including:
+ * - Required fields (requestId, circuit, callbackUrl)
+ * - Circuit type validity (must be a supported circuit)
+ * - Circuit-specific input validation (e.g., userAddress format, countryList structure)
+ * - Expiration check (if expiresAt is provided)
+ *
+ * Note: userAddress is optional for both circuits - the mobile app will prompt
+ * for wallet connection if not provided.
+ *
+ * @param request - Proof request to validate
+ * @returns Validation result with `valid` flag and optional `error` message
+ */
+function validateProofRequest(request) {
+    if (!request.requestId) {
+        return { valid: false, error: 'Missing requestId' };
+    }
+    if (!request.circuit) {
+        return { valid: false, error: 'Missing circuit type' };
+    }
+    if (!['coinbase_attestation', 'coinbase_country_attestation'].includes(request.circuit)) {
+        return { valid: false, error: `Invalid circuit type: ${request.circuit}` };
+    }
+    if (!request.callbackUrl) {
+        return { valid: false, error: 'Missing callbackUrl' };
+    }
+    // Validate circuit-specific inputs
+    if (request.circuit === 'coinbase_attestation') {
+        // Coinbase KYC: userAddress is optional - app will connect wallet if not provided
+        const inputs = request.inputs;
+        if (inputs.userAddress && !/^0x[a-fA-F0-9]{40}$/.test(inputs.userAddress)) {
+            return { valid: false, error: 'Invalid userAddress format' };
+        }
+        // If userAddress is not provided, app will prompt wallet connection - this is valid
+    }
+    else if (request.circuit === 'coinbase_country_attestation') {
+        const inputs = request.inputs;
+        if (inputs.userAddress && !/^0x[a-fA-F0-9]{40}$/.test(inputs.userAddress)) {
+            return { valid: false, error: 'Invalid userAddress format' };
+        }
+        if (!inputs.countryList || !Array.isArray(inputs.countryList) || inputs.countryList.length === 0) {
+            return { valid: false, error: 'countryList is required and must be a non-empty array' };
+        }
+        if (!inputs.countryList.every(c => typeof c === 'string')) {
+            return { valid: false, error: 'countryList must contain only strings' };
+        }
+        if (typeof inputs.isIncluded !== 'boolean') {
+            return { valid: false, error: 'isIncluded is required and must be a boolean' };
+        }
+    }
+    // Check expiry
+    if (request.expiresAt && Date.now() > request.expiresAt) {
+        return { valid: false, error: 'Request has expired' };
+    }
+    return { valid: true };
+}
+
+/**
+ * QR Code utilities for ZKProofport SDK
+ */
+/**
+ * Default QR code options
+ */
+const DEFAULT_QR_OPTIONS = {
+    width: 300,
+    errorCorrectionLevel: 'M',
+    margin: 2,
+    darkColor: '#000000',
+    lightColor: '#ffffff',
+};
+/**
+ * Generates a QR code as a base64-encoded PNG data URL.
+ *
+ * Creates a scannable QR code image from a proof request or deep link URL.
+ * The returned data URL can be used directly in HTML img src attributes.
+ * Validates that the encoded data doesn't exceed the maximum QR code size.
+ *
+ * @param requestOrUrl - Proof request object or pre-built deep link URL
+ * @param options - QR code appearance options (width, colors, error correction)
+ * @param scheme - Custom URL scheme (only used if requestOrUrl is a ProofRequest)
+ * @returns Promise resolving to base64 PNG data URL (e.g., "data:image/png;base64,...")
+ *
+ * @throws {Error} If the URL exceeds MAX_QR_DATA_SIZE (2953 bytes)
+ *
+ * @example
+ * ```typescript
+ * const request: ProofRequest = {
+ *   requestId: generateRequestId(),
+ *   circuit: 'coinbase_attestation',
+ *   inputs: { scope: 'myapp.com' },
+ *   createdAt: Date.now()
+ * };
+ *
+ * const dataUrl = await generateQRCodeDataUrl(request, {
+ *   width: 400,
+ *   darkColor: '#000000',
+ *   lightColor: '#ffffff'
+ * });
+ *
+ * // Use in HTML: <img src={dataUrl} alt="Scan to prove" />
+ * ```
+ */
+async function generateQRCodeDataUrl(requestOrUrl, options = {}, scheme = DEFAULT_SCHEME) {
+    const url = typeof requestOrUrl === 'string'
+        ? requestOrUrl
+        : buildProofRequestUrl(requestOrUrl, scheme);
+    // Check data size
+    if (url.length > MAX_QR_DATA_SIZE) {
+        throw new Error(`QR code data too large (${url.length} bytes). Maximum is ${MAX_QR_DATA_SIZE} bytes.`);
+    }
+    const mergedOptions = { ...DEFAULT_QR_OPTIONS, ...options };
+    return QRCode.toDataURL(url, {
+        width: mergedOptions.width,
+        errorCorrectionLevel: mergedOptions.errorCorrectionLevel,
+        margin: mergedOptions.margin,
+        color: {
+            dark: mergedOptions.darkColor,
+            light: mergedOptions.lightColor,
+        },
+    });
+}
+/**
+ * Generates a QR code as an SVG string.
+ *
+ * Creates a scalable vector graphics QR code that can be embedded directly in HTML
+ * or saved to a file. SVG QR codes scale perfectly at any size and have smaller
+ * file sizes than raster formats.
+ *
+ * @param requestOrUrl - Proof request object or pre-built deep link URL
+ * @param options - QR code appearance options (width, colors, error correction)
+ * @param scheme - Custom URL scheme (only used if requestOrUrl is a ProofRequest)
+ * @returns Promise resolving to SVG markup string
+ *
+ * @throws {Error} If the URL exceeds MAX_QR_DATA_SIZE (2953 bytes)
+ *
+ * @example
+ * ```typescript
+ * const request: ProofRequest = { ... };
+ * const svg = await generateQRCodeSVG(request, { width: 300 });
+ *
+ * // Embed directly: <div dangerouslySetInnerHTML={{ __html: svg }} />
+ * // Or save to file: fs.writeFileSync('qr.svg', svg);
+ * ```
+ */
+async function generateQRCodeSVG(requestOrUrl, options = {}, scheme = DEFAULT_SCHEME) {
+    const url = typeof requestOrUrl === 'string'
+        ? requestOrUrl
+        : buildProofRequestUrl(requestOrUrl, scheme);
+    if (url.length > MAX_QR_DATA_SIZE) {
+        throw new Error(`QR code data too large (${url.length} bytes). Maximum is ${MAX_QR_DATA_SIZE} bytes.`);
+    }
+    const mergedOptions = { ...DEFAULT_QR_OPTIONS, ...options };
+    return QRCode.toString(url, {
+        type: 'svg',
+        width: mergedOptions.width,
+        errorCorrectionLevel: mergedOptions.errorCorrectionLevel,
+        margin: mergedOptions.margin,
+        color: {
+            dark: mergedOptions.darkColor,
+            light: mergedOptions.lightColor,
+        },
+    });
+}
+/**
+ * Renders a QR code directly to an HTML canvas element.
+ *
+ * Browser-only function that draws a QR code onto an existing canvas element.
+ * Useful for interactive applications or when you need direct canvas manipulation.
+ * The canvas dimensions will be set automatically based on the width option.
+ *
+ * @param canvas - HTML canvas element to render to (must exist in DOM)
+ * @param requestOrUrl - Proof request object or pre-built deep link URL
+ * @param options - QR code appearance options (width, colors, error correction)
+ * @param scheme - Custom URL scheme (only used if requestOrUrl is a ProofRequest)
+ * @returns Promise that resolves when rendering is complete
+ *
+ * @throws {Error} If the URL exceeds MAX_QR_DATA_SIZE (2953 bytes)
+ * @throws {Error} If canvas is not a valid HTMLCanvasElement (browser only)
+ *
+ * @example
+ * ```typescript
+ * // In a React component:
+ * const canvasRef = useRef<HTMLCanvasElement>(null);
+ *
+ * useEffect(() => {
+ *   if (canvasRef.current) {
+ *     generateQRCodeToCanvas(canvasRef.current, request, { width: 400 });
+ *   }
+ * }, [request]);
+ *
+ * return <canvas ref={canvasRef} />;
+ * ```
+ */
+async function generateQRCodeToCanvas(canvas, requestOrUrl, options = {}, scheme = DEFAULT_SCHEME) {
+    const url = typeof requestOrUrl === 'string'
+        ? requestOrUrl
+        : buildProofRequestUrl(requestOrUrl, scheme);
+    if (url.length > MAX_QR_DATA_SIZE) {
+        throw new Error(`QR code data too large (${url.length} bytes). Maximum is ${MAX_QR_DATA_SIZE} bytes.`);
+    }
+    const mergedOptions = { ...DEFAULT_QR_OPTIONS, ...options };
+    await QRCode.toCanvas(canvas, url, {
+        width: mergedOptions.width,
+        errorCorrectionLevel: mergedOptions.errorCorrectionLevel,
+        margin: mergedOptions.margin,
+        color: {
+            dark: mergedOptions.darkColor,
+            light: mergedOptions.lightColor,
+        },
+    });
+}
+/**
+ * Estimates the byte size of a QR code's encoded data.
+ *
+ * Calculates the size of the deep link URL that will be encoded in the QR code,
+ * and checks if it's within the maximum supported size (2953 bytes for QR version 40
+ * with medium error correction). Use this before generating QR codes to avoid errors.
+ *
+ * @param requestOrUrl - Proof request object or pre-built deep link URL
+ * @param scheme - Custom URL scheme (only used if requestOrUrl is a ProofRequest)
+ * @returns Object with `size` in bytes and `withinLimit` boolean flag
+ *
+ * @example
+ * ```typescript
+ * const request: ProofRequest = { ... };
+ * const { size, withinLimit } = estimateQRDataSize(request);
+ *
+ * if (!withinLimit) {
+ *   console.error(`QR code too large: ${size} bytes (max 2953)`);
+ *   // Consider reducing request data or splitting into multiple QR codes
+ * }
+ *
+ * // Example output: { size: 384, withinLimit: true }
+ * ```
+ */
+function estimateQRDataSize(requestOrUrl, scheme = DEFAULT_SCHEME) {
+    const url = typeof requestOrUrl === 'string'
+        ? requestOrUrl
+        : buildProofRequestUrl(requestOrUrl, scheme);
+    return {
+        size: url.length,
+        withinLimit: url.length <= MAX_QR_DATA_SIZE,
+    };
+}
+
+/**
+ * On-chain verification utilities for ZKProofport SDK
+ *
+ * Compatible with both ethers v5 and v6.
+ */
+// ethers v5/v6 compatibility shims
+const _ethers = ethers.ethers;
+/** @internal ethers v5/v6 compatibility shim */
+function hexZeroPad(value, length) {
+    // v6: ethers.zeroPadValue, v5: ethers.utils.hexZeroPad
+    if (typeof _ethers.zeroPadValue === 'function')
+        return _ethers.zeroPadValue(value, length);
+    if (_ethers.utils?.hexZeroPad)
+        return _ethers.utils.hexZeroPad(value, length);
+    // manual fallback
+    const hex = value.startsWith('0x') ? value.slice(2) : value;
+    return '0x' + hex.padStart(length * 2, '0');
+}
+/** @internal ethers v5/v6 compatibility shim */
+function createJsonRpcProvider(url) {
+    // v6: ethers.JsonRpcProvider, v5: ethers.providers.JsonRpcProvider
+    if (typeof _ethers.JsonRpcProvider === 'function')
+        return new _ethers.JsonRpcProvider(url);
+    if (_ethers.providers?.JsonRpcProvider)
+        return new _ethers.providers.JsonRpcProvider(url);
+    throw new Error('No JsonRpcProvider found in ethers');
+}
+/**
+ * @internal Resolve verifier from SDK config or proof response.
+ * SDK config (customVerifier) takes priority over response-provided verifier.
+ */
+function resolveVerifier(customVerifier, responseVerifier) {
+    if (customVerifier)
+        return customVerifier;
+    if (responseVerifier?.verifierAddress) {
+        return {
+            address: responseVerifier.verifierAddress,
+            chainId: responseVerifier.chainId ?? 0,
+            abi: VERIFIER_ABI,
+        };
+    }
+    return null;
+}
+/**
+ * Get verifier contract instance for interacting with on-chain verifier contracts.
+ *
+ * @param providerOrSigner - ethers.js Provider or Signer instance (v5 or v6 compatible)
+ * @param verifier - Verifier contract configuration containing address and ABI
+ * @returns ethers.Contract instance connected to the verifier
+ *
+ * @example
+ * ```typescript
+ * const provider = new ethers.JsonRpcProvider(rpcUrl);
+ * const contract = getVerifierContract(provider, {
+ *   address: '0x...',
+ *   chainId: 11155111,
+ *   abi: VERIFIER_ABI
+ * });
+ * ```
+ */
+function getVerifierContract(providerOrSigner, verifier) {
+    return new ethers.ethers.Contract(verifier.address, verifier.abi, providerOrSigner);
+}
+/**
+ * Get default JSON-RPC provider for a chain using pre-configured RPC endpoints.
+ *
+ * @param chainId - The chain ID (e.g., 11155111 for Sepolia, 84532 for Base Sepolia)
+ * @returns ethers.JsonRpcProvider instance for the specified chain
+ * @throws Error if no RPC endpoint is configured for the chain
+ *
+ * @example
+ * ```typescript
+ * const provider = getDefaultProvider(11155111); // Sepolia
+ * ```
+ */
+function getDefaultProvider(chainId) {
+    const rpcUrl = RPC_ENDPOINTS[chainId];
+    if (!rpcUrl) {
+        throw new Error(`No RPC endpoint configured for chain ${chainId}`);
+    }
+    return createJsonRpcProvider(rpcUrl);
+}
+/**
+ * Verify a zero-knowledge proof on-chain by calling the verifier smart contract.
+ *
+ * This function resolves the verifier contract from SDK config or proof response,
+ * connects to the blockchain, and calls the verify() method with the proof and public inputs.
+ *
+ * @param circuit - The canonical circuit identifier (e.g., "coinbase_attestation")
+ * @param parsedProof - Parsed proof object containing proofHex and publicInputsHex
+ * @param providerOrSigner - Optional ethers.js Provider or Signer instance. If not provided, uses default RPC for the chain
+ * @param customVerifier - Optional custom verifier contract config (takes priority over responseVerifier)
+ * @param responseVerifier - Optional verifier info from proof generation response
+ * @returns Promise resolving to verification result with valid flag and optional error message
+ *
+ * @example
+ * ```typescript
+ * const parsed = parseProofForOnChain(proof, publicInputs, numPublicInputs);
+ * const result = await verifyProofOnChain(
+ *   'coinbase_attestation',
+ *   parsed,
+ *   provider,
+ *   { address: '0x...', chainId: 11155111, abi: VERIFIER_ABI }
+ * );
+ *
+ * if (result.valid) {
+ *   console.log('Proof is valid!');
+ * } else {
+ *   console.error('Verification failed:', result.error);
+ * }
+ * ```
+ */
+async function verifyProofOnChain(circuit, parsedProof, providerOrSigner, customVerifier, responseVerifier) {
+    const verifier = resolveVerifier(customVerifier, responseVerifier);
+    if (!verifier) {
+        return {
+            valid: false,
+            error: 'No verifier address provided. Configure via SDK or ensure proof response includes verifierAddress.',
+        };
+    }
+    const provider = providerOrSigner || (verifier.chainId > 0 ? getDefaultProvider(verifier.chainId) : null);
+    if (!provider) {
+        return {
+            valid: false,
+            error: 'No provider available. Provide a provider or ensure chainId is set for RPC lookup.',
+        };
+    }
+    const contract = getVerifierContract(provider, verifier);
+    try {
+        const isValid = await contract.verify(parsedProof.proofHex, parsedProof.publicInputsHex);
+        return { valid: isValid };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return { valid: false, error: errorMessage };
+    }
+}
+/** @internal Ensure a hex string has the 0x prefix */
+function ensureHexPrefix(hex) {
+    return hex.startsWith('0x') ? hex : `0x${hex}`;
+}
+/**
+ * Parse proof response into format suitable for on-chain verification.
+ *
+ * Converts proof and public inputs from relay response format to the format
+ * expected by Solidity verifier contracts. Public inputs are zero-padded to
+ * 32 bytes (bytes32) to match Solidity's bytes32[] type.
+ *
+ * @param proof - Proof bytes as hex string (with or without 0x prefix)
+ * @param publicInputs - Array of public input values as hex strings
+ * @param numPublicInputs - Number of public inputs (for validation)
+ * @returns Parsed proof object ready for on-chain verification
+ *
+ * @example
+ * ```typescript
+ * const parsed = parseProofForOnChain(
+ *   '0x1a2b3c...',
+ *   ['0x01', '0x02', '0x03'],
+ *   3
+ * );
+ *
+ * // parsed.proofHex: '0x1a2b3c...'
+ * // parsed.publicInputsHex: ['0x0000...01', '0x0000...02', '0x0000...03']
+ * ```
+ */
+function parseProofForOnChain(proof, publicInputs, numPublicInputs) {
+    const proofHex = ensureHexPrefix(proof);
+    const publicInputsHex = publicInputs.map((input) => {
+        return hexZeroPad(ensureHexPrefix(input), 32);
+    });
+    return {
+        proofHex,
+        publicInputsHex,
+        numPublicInputs,
+    };
+}
+/** @internal Require a verifier or throw with a helpful message */
+function requireVerifier(circuit, verifier) {
+    if (!verifier) {
+        throw new Error(`No verifier configured for circuit '${circuit}'. Configure via SDK verifiers option.`);
+    }
+    return verifier;
+}
+/**
+ * Get verifier contract address for a circuit.
+ *
+ * @param circuit - The canonical circuit identifier (e.g., "coinbase_attestation")
+ * @param customVerifier - Optional custom verifier contract config
+ * @returns Verifier contract address as hex string
+ * @throws Error if no verifier is configured for the circuit
+ *
+ * @example
+ * ```typescript
+ * const address = getVerifierAddress('coinbase_attestation', verifierConfig);
+ * console.log(address); // '0x1234...'
+ * ```
+ */
+function getVerifierAddress(circuit, customVerifier) {
+    return requireVerifier(circuit, customVerifier).address;
+}
+/**
+ * Get chain ID for a circuit's verifier contract.
+ *
+ * @param circuit - The canonical circuit identifier (e.g., "coinbase_attestation")
+ * @param customVerifier - Optional custom verifier contract config
+ * @returns Chain ID number (e.g., 11155111 for Sepolia, 84532 for Base Sepolia)
+ * @throws Error if no verifier is configured for the circuit
+ *
+ * @example
+ * ```typescript
+ * const chainId = getVerifierChainId('coinbase_attestation', verifierConfig);
+ * console.log(chainId); // 11155111
+ * ```
+ */
+function getVerifierChainId(circuit, customVerifier) {
+    return requireVerifier(circuit, customVerifier).chainId;
+}
+/**
+ * Extract scope value from public inputs array.
+ *
+ * The scope is a bytes32 value encoded across 32 consecutive field elements
+ * in the public inputs. The exact position depends on the circuit type.
+ *
+ * @param publicInputsHex - Array of public input hex strings (zero-padded to 32 bytes)
+ * @param circuit - Optional circuit identifier to determine field positions
+ * @returns Reconstructed scope as hex string with 0x prefix, or null if inputs are insufficient
+ *
+ * @example
+ * ```typescript
+ * const scope = extractScopeFromPublicInputs(publicInputsHex, 'coinbase_attestation');
+ * console.log(scope); // '0x7a6b70726f6f66706f72742e636f6d...'
+ * ```
+ */
+function extractScopeFromPublicInputs(publicInputsHex, circuit) {
+    let start, end;
+    if (circuit === 'coinbase_country_attestation') {
+        start = 86;
+        end = 117;
+    }
+    else {
+        start = 64;
+        end = 95;
+    }
+    if (publicInputsHex.length <= end)
+        return null;
+    const scopeFields = publicInputsHex.slice(start, end + 1);
+    return reconstructBytes32FromFields(scopeFields);
+}
+/**
+ * Extract nullifier value from public inputs array.
+ *
+ * The nullifier is a bytes32 value encoded across 32 consecutive field elements
+ * in the public inputs. The exact position depends on the circuit type.
+ * Nullifiers are used for duplicate proof detection and must be unique per user+scope.
+ *
+ * @param publicInputsHex - Array of public input hex strings (zero-padded to 32 bytes)
+ * @param circuit - Optional circuit identifier to determine field positions
+ * @returns Reconstructed nullifier as hex string with 0x prefix, or null if inputs are insufficient
+ *
+ * @example
+ * ```typescript
+ * const nullifier = extractNullifierFromPublicInputs(publicInputsHex, 'coinbase_attestation');
+ * console.log(nullifier); // '0xabcd1234...'
+ *
+ * // Check if nullifier is already registered
+ * const isRegistered = await isNullifierRegistered(nullifier, registryAddress, provider);
+ * ```
+ */
+function extractNullifierFromPublicInputs(publicInputsHex, circuit) {
+    let start, end;
+    if (circuit === 'coinbase_country_attestation') {
+        start = 118;
+        end = 149;
+    }
+    else {
+        start = 96;
+        end = 127;
+    }
+    if (publicInputsHex.length <= end)
+        return null;
+    const nullifierFields = publicInputsHex.slice(start, end + 1);
+    return reconstructBytes32FromFields(nullifierFields);
+}
+/** @internal Reconstruct a bytes32 value from 32 individual field elements */
+function reconstructBytes32FromFields(fields) {
+    if (fields.length !== 32) {
+        throw new Error(`Expected 32 fields, got ${fields.length}`);
+    }
+    const bytes = fields.map(f => {
+        const byte = BigInt(f) & 0xffn;
+        return byte.toString(16).padStart(2, '0');
+    }).join('');
+    return '0x' + bytes;
+}
+/**
+ * Check if a nullifier is already registered on-chain in the ZKProofport nullifier registry.
+ *
+ * This function queries the on-chain nullifier registry contract to determine if a nullifier
+ * has been used before. This is used to prevent duplicate proof submissions from the same user
+ * for the same scope.
+ *
+ * @param nullifier - The nullifier hash as hex string with 0x prefix
+ * @param registryAddress - ZKProofportNullifierRegistry contract address
+ * @param provider - ethers.js Provider instance (v5 or v6 compatible)
+ * @returns Promise resolving to true if nullifier is registered, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const nullifier = extractNullifierFromPublicInputs(publicInputsHex, circuit);
+ * const isRegistered = await isNullifierRegistered(
+ *   nullifier,
+ *   '0x...',
+ *   provider
+ * );
+ *
+ * if (isRegistered) {
+ *   console.log('This nullifier has already been used');
+ * }
+ * ```
+ */
+async function isNullifierRegistered(nullifier, registryAddress, provider) {
+    const { ZKPROOFPORT_NULLIFIER_REGISTRY_ABI } = await Promise.resolve().then(function () { return constants; });
+    const contract = new ethers.ethers.Contract(registryAddress, ZKPROOFPORT_NULLIFIER_REGISTRY_ABI, provider);
+    try {
+        return await contract.isNullifierRegistered(nullifier);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get detailed information about a registered nullifier from the on-chain registry.
+ *
+ * This function retrieves the registration timestamp, scope, and circuit ID for a nullifier
+ * that has been registered on-chain. This metadata is useful for auditing and analytics.
+ *
+ * @param nullifier - The nullifier hash as hex string with 0x prefix
+ * @param registryAddress - ZKProofportNullifierRegistry contract address
+ * @param provider - ethers.js Provider instance (v5 or v6 compatible)
+ * @returns Promise resolving to nullifier info object, or null if not registered
+ *
+ * @example
+ * ```typescript
+ * const info = await getNullifierInfo(nullifier, registryAddress, provider);
+ *
+ * if (info) {
+ *   console.log('Registered at:', new Date(info.registeredAt * 1000));
+ *   console.log('Scope:', info.scope);
+ *   console.log('Circuit:', info.circuitId);
+ * } else {
+ *   console.log('Nullifier not registered');
+ * }
+ * ```
+ */
+async function getNullifierInfo(nullifier, registryAddress, provider) {
+    const { ZKPROOFPORT_NULLIFIER_REGISTRY_ABI } = await Promise.resolve().then(function () { return constants; });
+    const contract = new ethers.ethers.Contract(registryAddress, ZKPROOFPORT_NULLIFIER_REGISTRY_ABI, provider);
+    try {
+        const [registeredAt, scope, circuitId] = await contract.getNullifierInfo(nullifier);
+        if (BigInt(registeredAt) === 0n)
+            return null;
+        return {
+            registeredAt: Number(registeredAt),
+            scope: scope,
+            circuitId: circuitId,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+
+/**
+ * Proofport SDK - Main class
+ */
+/**
+ * Main SDK class for interacting with the ZKProofport mobile app.
+ *
+ * Provides methods for creating proof requests, generating QR codes and deep links,
+ * verifying proofs on-chain, and handling proof responses from the mobile app.
+ *
+ * @example
+ * ```typescript
+ * import { ProofportSDK } from '@zkproofport-app/sdk';
+ *
+ * // Initialize SDK (uses production relay by default)
+ * const sdk = ProofportSDK.create();
+ *
+ * // Authenticate
+ * await sdk.login({ clientId: 'your-id', apiKey: 'your-key' });
+ *
+ * // Create proof request via relay
+ * const relay = await sdk.createRelayRequest('coinbase_attestation', {
+ *   scope: 'myapp.com'
+ * });
+ *
+ * // Generate QR code for desktop users
+ * const qrDataUrl = await sdk.generateQRCode(relay.deepLink);
+ *
+ * // Wait for proof via WebSocket (primary) or polling (fallback)
+ * const result = await sdk.waitForProof(relay.requestId);
+ * if (result.status === 'completed') {
+ *   console.log('Proof received:', result.proof);
+ * }
+ * ```
+ */
+class ProofportSDK {
+    /**
+     * Creates a new ProofportSDK instance.
+     *
+     * For most use cases, prefer the static factory with environment presets:
+     * ```typescript
+     * const sdk = ProofportSDK.create('production');
+     * ```
+     *
+     * @param config - SDK configuration options
+     * @param config.scheme - Custom deep link scheme (default: 'zkproofport')
+     * @param config.relayUrl - Relay server URL (required for relay features)
+     * @param config.verifiers - Custom verifier contract addresses per circuit
+     *
+     * @example
+     * ```typescript
+     * const sdk = new ProofportSDK({
+     *   relayUrl: 'https://relay.zkproofport.app',
+     *   verifiers: {
+     *     coinbase_attestation: {
+     *       verifierAddress: '0x...',
+     *       chainId: 1
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    constructor(config = {}) {
+        this.pendingRequests = new Map();
+        this.authToken = null;
+        this.socket = null;
+        this.config = {
+            scheme: config.scheme || DEFAULT_SCHEME,
+            verifiers: config.verifiers || {},
+        };
+        this.relayUrl = config.relayUrl || '';
+        this.nullifierRegistry = config.nullifierRegistry;
+    }
+    // ============ Request Creation ============
+    /**
+     * @internal
+     * Creates a Coinbase KYC verification proof request.
+     *
+     * Generates a proof request for verifying Coinbase KYC status without revealing
+     * the actual attestation data. The proof confirms the user has passed Coinbase KYC
+     * while maintaining privacy through zero-knowledge proofs.
+     *
+     * @param inputs - Circuit inputs for Coinbase KYC
+     * @param inputs.scope - Application-specific scope (e.g., domain name)
+     * @param options - Request configuration options
+  
+     * @param options.message - Custom message to display to user
+     * @param options.dappName - Application name shown in ZKProofport app
+     * @param options.dappIcon - Application icon URL shown in ZKProofport app
+     * @param options.expiresInMs - Request expiration time in milliseconds (default: 10 minutes)
+     *
+     * @returns ProofRequest object with unique requestId and all request details
+     *
+     * @throws Error if scope is not provided
+     *
+     * @example
+     * ```typescript
+     * const request = sdk.createCoinbaseKycRequest({
+     *   scope: 'myapp.com'
+     * }, {
+     *   dappName: 'My DApp',
+     *   message: 'Verify your KYC status to access this feature'
+     * });
+     *
+     * const deepLink = sdk.getDeepLinkUrl(request);
+     * ```
+     */
+    createCoinbaseKycRequest(inputs, options = {}) {
+        if (!inputs.scope) {
+            throw new Error('scope is required for coinbase_attestation circuit');
+        }
+        const request = {
+            requestId: generateRequestId(),
+            circuit: 'coinbase_attestation',
+            inputs,
+            message: options.message,
+            dappName: options.dappName,
+            dappIcon: options.dappIcon,
+            createdAt: Date.now(),
+            expiresAt: Date.now() + (options.expiresInMs || DEFAULT_REQUEST_EXPIRY_MS),
+        };
+        this.pendingRequests.set(request.requestId, request);
+        return request;
+    }
+    /**
+     * @internal
+     * Creates a Coinbase Country attestation proof request.
+     *
+     * Generates a proof request for verifying country eligibility through Coinbase
+     * attestation without revealing the actual country data. The proof confirms the
+     * user's country status while maintaining privacy through zero-knowledge proofs.
+     *
+     * @param inputs - Circuit inputs for Coinbase Country attestation
+     * @param inputs.scope - Application-specific scope (e.g., domain name)
+     * @param options - Request configuration options
+  
+     * @param options.message - Custom message to display to user
+     * @param options.dappName - Application name shown in ZKProofport app
+     * @param options.dappIcon - Application icon URL shown in ZKProofport app
+     * @param options.expiresInMs - Request expiration time in milliseconds (default: 10 minutes)
+     *
+     * @returns ProofRequest object with unique requestId and all request details
+     *
+     * @throws Error if scope is not provided
+     *
+     * @example
+     * ```typescript
+     * const request = sdk.createCoinbaseCountryRequest({
+     *   scope: 'myapp.com'
+     * }, {
+     *   dappName: 'My DApp',
+     *   message: 'Verify your country eligibility'
+     * });
+     * ```
+     */
+    createCoinbaseCountryRequest(inputs, options = {}) {
+        if (!inputs.scope) {
+            throw new Error('scope is required for coinbase_country_attestation circuit');
+        }
+        if (!inputs.countryList || !Array.isArray(inputs.countryList) || inputs.countryList.length === 0) {
+            throw new Error('countryList is required for coinbase_country_attestation circuit');
+        }
+        if (typeof inputs.isIncluded !== 'boolean') {
+            throw new Error('isIncluded is required for coinbase_country_attestation circuit');
+        }
+        const request = {
+            requestId: generateRequestId(),
+            circuit: 'coinbase_country_attestation',
+            inputs,
+            message: options.message,
+            dappName: options.dappName,
+            dappIcon: options.dappIcon,
+            createdAt: Date.now(),
+            expiresAt: Date.now() + (options.expiresInMs || DEFAULT_REQUEST_EXPIRY_MS),
+        };
+        this.pendingRequests.set(request.requestId, request);
+        return request;
+    }
+    /**
+     * @internal
+     * Creates a generic proof request for any supported circuit type.
+     *
+     * Routes to the appropriate circuit-specific request creation method based on
+     * the circuit type. Use this for dynamic circuit selection or when the circuit
+     * type is determined at runtime.
+     *
+     * @param circuit - Circuit type identifier ('coinbase_attestation' | 'coinbase_country_attestation')
+     * @param inputs - Circuit-specific inputs
+     * @param options - Request configuration options
+  
+     * @param options.message - Custom message to display to user
+     * @param options.dappName - Application name shown in ZKProofport app
+     * @param options.dappIcon - Application icon URL shown in ZKProofport app
+     * @param options.expiresInMs - Request expiration time in milliseconds (default: 15 minutes)
+     *
+     * @returns ProofRequest object with unique requestId and all request details
+     *
+     * @throws Error if required inputs are missing for the specified circuit
+     *
+     * @example
+     * ```typescript
+     * const circuitType = userSelection; // Dynamic selection
+     * const request = sdk.createProofRequest(
+     *   circuitType,
+     *   { scope: 'myapp.com' },
+     *   { dappName: 'My DApp' }
+     * );
+     * ```
+     */
+    createProofRequest(circuit, inputs, options = {}) {
+        if (circuit === 'coinbase_country_attestation') {
+            return this.createCoinbaseCountryRequest(inputs, options);
+        }
+        else {
+            return this.createCoinbaseKycRequest(inputs, options);
+        }
+    }
+    // ============ Deep Link Generation ============
+    /**
+     * @internal
+     * Generates a deep link URL for a proof request.
+     *
+     * Creates a zkproofport:// URL that opens the ZKProofport mobile app with the
+     * specified proof request. The URL contains all request details encoded as query
+     * parameters.
+     *
+     * @param request - ProofRequest object to encode as deep link
+     *
+     * @returns Deep link URL string (e.g., 'zkproofport://proof?requestId=...')
+     *
+     * @example
+     * ```typescript
+     * const request = sdk.createCoinbaseKycRequest({ scope: 'myapp.com' });
+     * const url = sdk.getDeepLinkUrl(request);
+     * // url: 'zkproofport://proof?requestId=abc123&circuit=coinbase_attestation&...'
+     * ```
+     */
+    getDeepLinkUrl(request) {
+        return buildProofRequestUrl(request, this.config.scheme);
+    }
+    /**
+     * @internal
+     * Opens the ZKProofport mobile app with a proof request.
+     *
+     * Redirects the browser to the deep link URL, which opens the ZKProofport app
+     * if installed. Only works in mobile browser environments. For desktop, use
+     * requestProof() to display a QR code instead.
+     *
+     * @param request - ProofRequest object to send to the app
+     *
+     * @example
+     * ```typescript
+     * const request = sdk.createCoinbaseKycRequest({ scope: 'myapp.com' });
+     * if (ProofportSDK.isMobile()) {
+     *   sdk.openProofRequest(request); // Opens app directly
+     * }
+     * ```
+     */
+    openProofRequest(request) {
+        const url = this.getDeepLinkUrl(request);
+        window.location.href = url;
+    }
+    /**
+     * @internal
+     * Requests a proof with automatic platform detection.
+     *
+     * Detects whether the user is on mobile or desktop and automatically chooses
+     * the appropriate flow:
+     * - Mobile: Opens the deep link directly to launch the ZKProofport app
+     * - Desktop: Generates a QR code data URL for the user to scan
+     *
+     * @param request - ProofRequest object to send
+     * @param qrOptions - QR code generation options (size, colors, logo) for desktop
+     *
+     * @returns Object containing deep link URL, optional QR code data URL, and platform detection result
+     *
+     * @example
+     * ```typescript
+     * const request = sdk.createCoinbaseKycRequest({ scope: 'myapp.com' });
+     * const result = await sdk.requestProof(request);
+     *
+     * if (result.mobile) {
+     *   console.log('Opening app directly');
+     * } else {
+     *   // Display QR code for desktop users
+     *   document.getElementById('qr').src = result.qrDataUrl;
+     * }
+     * ```
+     */
+    async requestProof(request, qrOptions) {
+        const deepLink = this.getDeepLinkUrl(request);
+        const mobile = ProofportSDK.isMobile();
+        if (mobile) {
+            window.location.href = deepLink;
+            return { deepLink, mobile: true };
+        }
+        const qrDataUrl = await this.generateQRCode(request, qrOptions);
+        return { deepLink, qrDataUrl, mobile: false };
+    }
+    // ============ QR Code Generation ============
+    /**
+     * Generates a QR code as a data URL for a proof request.
+     *
+     * Creates a PNG image data URL that can be directly set as an img src attribute.
+     * Suitable for embedding QR codes in web pages for desktop users to scan with
+     * their mobile device.
+     *
+     * @param requestOrUrl - ProofRequest object or deep link URL string
+     * @param options - QR code customization options
+     * @param options.size - QR code size in pixels (default: 256)
+     * @param options.margin - Quiet zone margin in modules (default: 4)
+     * @param options.darkColor - Color for dark modules (default: '#000000')
+     * @param options.lightColor - Color for light modules (default: '#ffffff')
+     * @param options.logoUrl - Optional center logo image URL
+     * @param options.logoSize - Logo size as fraction of QR code (default: 0.2)
+     *
+     * @returns Promise resolving to PNG data URL (e.g., 'data:image/png;base64,...')
+     *
+     * @example
+     * ```typescript
+     * const request = sdk.createCoinbaseKycRequest({ scope: 'myapp.com' });
+     * const qrUrl = await sdk.generateQRCode(request, {
+     *   size: 400,
+     *   darkColor: '#1a1a1a',
+     *   logoUrl: 'https://myapp.com/logo.png'
+     * });
+     * document.getElementById('qr-image').src = qrUrl;
+     * ```
+     */
+    async generateQRCode(requestOrUrl, options) {
+        return generateQRCodeDataUrl(requestOrUrl, options, this.config.scheme);
+    }
+    /**
+     * Generates a QR code as an SVG string for a proof request.
+     *
+     * Creates a scalable vector graphics representation of the QR code, ideal for
+     * high-resolution displays or when vector format is preferred over raster images.
+     *
+     * @param requestOrUrl - ProofRequest object or deep link URL string
+     * @param options - QR code customization options
+     * @param options.size - QR code size in pixels (default: 256)
+     * @param options.margin - Quiet zone margin in modules (default: 4)
+     * @param options.darkColor - Color for dark modules (default: '#000000')
+     * @param options.lightColor - Color for light modules (default: '#ffffff')
+     *
+     * @returns Promise resolving to SVG string
+     *
+     * @example
+     * ```typescript
+     * const request = sdk.createCoinbaseKycRequest({ scope: 'myapp.com' });
+     * const svgString = await sdk.generateQRCodeSVG(request);
+     * document.getElementById('qr-container').innerHTML = svgString;
+     * ```
+     */
+    async generateQRCodeSVG(requestOrUrl, options) {
+        return generateQRCodeSVG(requestOrUrl, options, this.config.scheme);
+    }
+    /**
+     * Renders a QR code directly to an HTML canvas element.
+     *
+     * Draws the QR code onto the provided canvas element, useful for custom
+     * rendering workflows or when you need direct canvas manipulation.
+     *
+     * @param canvas - HTML canvas element to render to
+     * @param requestOrUrl - ProofRequest object or deep link URL string
+     * @param options - QR code customization options
+     * @param options.size - QR code size in pixels (default: 256)
+     * @param options.margin - Quiet zone margin in modules (default: 4)
+     * @param options.darkColor - Color for dark modules (default: '#000000')
+     * @param options.lightColor - Color for light modules (default: '#ffffff')
+     *
+     * @returns Promise that resolves when rendering is complete
+     *
+     * @example
+     * ```typescript
+     * const canvas = document.getElementById('qr-canvas') as HTMLCanvasElement;
+     * const request = sdk.createCoinbaseKycRequest({ scope: 'myapp.com' });
+     * await sdk.renderQRCodeToCanvas(canvas, request, { size: 400 });
+     * ```
+     */
+    async renderQRCodeToCanvas(canvas, requestOrUrl, options) {
+        return generateQRCodeToCanvas(canvas, requestOrUrl, options, this.config.scheme);
+    }
+    /**
+     * Checks if a proof request fits within QR code size limits.
+     *
+     * Estimates the encoded data size and validates it against QR code capacity limits.
+     * Useful for validating requests before generating QR codes, especially when
+     * including large custom messages or metadata.
+     *
+     * @param requestOrUrl - ProofRequest object or deep link URL string
+     *
+     * @returns Object with size in bytes and whether it fits within limits
+     *
+     * @example
+     * ```typescript
+     * const request = sdk.createCoinbaseKycRequest({ scope: 'myapp.com' });
+     * const check = sdk.checkQRCodeSize(request);
+     * if (!check.withinLimit) {
+     *   console.warn(`Request too large: ${check.size} bytes`);
+     * }
+     * ```
+     */
+    checkQRCodeSize(requestOrUrl) {
+        return estimateQRDataSize(requestOrUrl, this.config.scheme);
+    }
+    // ============ Response Handling ============
+    /**
+     * @internal
+     * Parses a proof response from a callback URL.
+     *
+     * Extracts and decodes proof response data from the callback URL query parameters
+     * after the user completes proof generation in the ZKProofport app. The app
+     * redirects to your callback URL with the proof data encoded as query parameters.
+     *
+     * @param url - Callback URL containing proof response data
+     *
+     * @returns ProofResponse object with status, proof data, and public inputs, or null if invalid
+     *
+     * @example
+     * ```typescript
+     * // In your callback endpoint handler
+     * app.get('/callback', (req, res) => {
+     *   const callbackUrl = req.url;
+     *   const response = sdk.parseResponse(callbackUrl);
+     *
+     *   if (response?.status === 'completed') {
+     *     console.log('Proof received:', response.proof);
+     *     console.log('Public inputs:', response.publicInputs);
+     *   } else if (response?.status === 'rejected') {
+     *     console.log('User rejected the request');
+     *   }
+     * });
+     * ```
+     */
+    parseResponse(url) {
+        return parseProofResponseUrl(url);
+    }
+    /**
+     * @internal
+     * Checks if a URL is a ZKProofport proof response callback.
+     *
+     * Validates whether the given URL contains the required query parameters for a
+     * proof response. Useful for filtering and routing callback requests.
+     *
+     * @param url - URL to check
+     *
+     * @returns True if the URL appears to be a ZKProofport response callback
+     *
+     * @example
+     * ```typescript
+     * app.get('/callback', (req, res) => {
+     *   const fullUrl = `${req.protocol}://${req.get('host')}${req.originalUrl}`;
+     *   if (sdk.isProofportResponse(fullUrl)) {
+     *     const response = sdk.parseResponse(fullUrl);
+     *     // Handle proof response
+     *   }
+     * });
+     * ```
+     */
+    isProofportResponse(url) {
+        try {
+            const urlObj = new URL(url);
+            return urlObj.searchParams.has('requestId') && urlObj.searchParams.has('status');
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * @internal
+     * Retrieves a pending proof request by its ID.
+     *
+     * Looks up a previously created proof request from the SDK's internal cache.
+     * Useful for validating callback responses and maintaining request state.
+     *
+     * @param requestId - Unique request identifier
+     *
+     * @returns ProofRequest object if found, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * app.get('/callback', (req, res) => {
+     *   const response = sdk.parseResponse(req.url);
+     *   const originalRequest = sdk.getPendingRequest(response.requestId);
+     *
+     *   if (originalRequest) {
+     *     console.log('Original request:', originalRequest);
+     *     sdk.clearPendingRequest(response.requestId);
+     *   }
+     * });
+     * ```
+     */
+    getPendingRequest(requestId) {
+        return this.pendingRequests.get(requestId);
+    }
+    /**
+     * @internal
+     * Clears a pending proof request from the internal cache.
+     *
+     * Removes a proof request from the SDK's pending requests map. Should be called
+     * after successfully processing a proof response to prevent memory leaks.
+     *
+     * @param requestId - Unique request identifier to remove
+     *
+     * @example
+     * ```typescript
+     * app.get('/callback', (req, res) => {
+     *   const response = sdk.parseResponse(req.url);
+     *   if (response?.status === 'completed') {
+     *     // Process proof...
+     *     sdk.clearPendingRequest(response.requestId);
+     *   }
+     * });
+     * ```
+     */
+    clearPendingRequest(requestId) {
+        this.pendingRequests.delete(requestId);
+    }
+    // ============ Verification ============
+    /**
+     * Verifies a zero-knowledge proof on-chain using the deployed verifier contract.
+     *
+     * Calls the Solidity verifier contract to cryptographically verify the proof's
+     * validity. This ensures the proof was generated correctly and the public inputs
+     * match the claimed values.
+     *
+     * @param circuit - Circuit type identifier
+     * @param proof - Hex-encoded proof string from the ZKProofport app
+     * @param publicInputs - Array of hex-encoded public input strings
+     * @param providerOrSigner - ethers v6 Provider or Signer (defaults to base mainnet public RPC)
+     *
+     * @returns Promise resolving to verification result with valid boolean and optional error message
+     *
+     * @example
+     * ```typescript
+     * import { ethers } from 'ethers';
+     *
+     * const response = sdk.parseResponse(callbackUrl);
+     * if (response?.status === 'completed') {
+     *   const provider = new ethers.JsonRpcProvider('https://mainnet.base.org');
+     *   const result = await sdk.verifyOnChain(
+     *     response.circuit,
+     *     response.proof,
+     *     response.publicInputs,
+     *     provider
+     *   );
+     *
+     *   if (result.valid) {
+     *     console.log('Proof verified on-chain!');
+     *   } else {
+     *     console.error('Verification failed:', result.error);
+     *   }
+     * }
+     * ```
+     */
+    async verifyOnChain(circuit, proof, publicInputs, providerOrSigner) {
+        const parsedProof = parseProofForOnChain(proof, publicInputs, publicInputs.length);
+        const customVerifier = this.config.verifiers[circuit];
+        return verifyProofOnChain(circuit, parsedProof, providerOrSigner, customVerifier);
+    }
+    /**
+     * Verifies a proof response on-chain using the deployed verifier contract.
+     *
+     * Convenience method that extracts proof data from a ProofResponse object and
+     * verifies it on-chain. Automatically handles incomplete or rejected responses.
+     *
+     * @param response - ProofResponse object from parseResponse()
+     * @param providerOrSigner - ethers v6 Provider or Signer (defaults to base mainnet public RPC)
+     *
+     * @returns Promise resolving to verification result with valid boolean and optional error message
+     *
+     * @example
+     * ```typescript
+     * import { ethers } from 'ethers';
+     *
+     * app.get('/callback', async (req, res) => {
+     *   const response = sdk.parseResponse(req.url);
+     *
+     *   if (response?.status === 'completed') {
+     *     const provider = new ethers.JsonRpcProvider('https://mainnet.base.org');
+     *     const result = await sdk.verifyResponseOnChain(response, provider);
+     *
+     *     if (result.valid) {
+     *       // Grant access to user
+     *       res.json({ success: true, verified: true });
+     *     } else {
+     *       res.status(400).json({ error: result.error });
+     *     }
+     *   } else {
+     *     res.status(400).json({ error: 'Proof generation failed or rejected' });
+     *   }
+     * });
+     * ```
+     */
+    async verifyResponseOnChain(response, providerOrSigner) {
+        if (response.status !== 'completed' || !response.proof || !response.publicInputs) {
+            return { valid: false, error: 'Invalid or incomplete response' };
+        }
+        const parsedProof = parseProofForOnChain(response.proof, response.publicInputs, response.publicInputs.length);
+        const customVerifier = this.config.verifiers[response.circuit];
+        const responseVerifier = {
+            verifierAddress: response.verifierAddress,
+            chainId: response.chainId,
+        };
+        return verifyProofOnChain(response.circuit, parsedProof, providerOrSigner, customVerifier, responseVerifier);
+    }
+    // ============ Utility Methods ============
+    /**
+     * Gets the deployed verifier contract address for a circuit.
+     *
+     * Returns the Ethereum address of the Solidity verifier contract for the
+     * specified circuit. Uses custom verifier if configured, otherwise returns
+     * the default deployed address.
+     *
+     * @param circuit - Circuit type identifier
+     *
+     * @returns Ethereum address of the verifier contract (0x...)
+     *
+     * @example
+     * ```typescript
+     * const address = sdk.getVerifierAddress('coinbase_attestation');
+     * console.log('Verifier deployed at:', address);
+     * ```
+     */
+    getVerifierAddress(circuit) {
+        const customVerifier = this.config.verifiers[circuit];
+        return getVerifierAddress(circuit, customVerifier);
+    }
+    /**
+     * Gets the blockchain chain ID where the verifier contract is deployed.
+     *
+     * Returns the EIP-155 chain ID for the network where the verifier contract
+     * is deployed. Uses custom verifier if configured, otherwise returns the
+     * default chain ID (Base mainnet: 8453).
+     *
+     * @param circuit - Circuit type identifier
+     *
+     * @returns Chain ID number (e.g., 8453 for Base mainnet)
+     *
+     * @example
+     * ```typescript
+     * const chainId = sdk.getVerifierChainId('coinbase_attestation');
+     * console.log('Verifier on chain:', chainId); // 8453 (Base mainnet)
+     * ```
+     */
+    getVerifierChainId(circuit) {
+        const customVerifier = this.config.verifiers[circuit];
+        return getVerifierChainId(circuit, customVerifier);
+    }
+    /**
+     * Gets metadata for a specific circuit type.
+     *
+     * Returns circuit metadata including display name, description, required inputs,
+     * and other configuration details.
+     *
+     * @param circuit - Circuit type identifier
+     *
+     * @returns Circuit metadata object with name, description, and configuration
+     *
+     * @example
+     * ```typescript
+     * const metadata = sdk.getCircuitMetadata('coinbase_attestation');
+     * console.log('Circuit name:', metadata.name);
+     * console.log('Description:', metadata.description);
+     * ```
+     */
+    getCircuitMetadata(circuit) {
+        return CIRCUIT_METADATA[circuit];
+    }
+    /**
+     * Gets all supported circuit types.
+     *
+     * Returns an array of all circuit type identifiers that are currently supported
+     * by the SDK and ZKProofport app.
+     *
+     * @returns Array of supported circuit type identifiers
+     *
+     * @example
+     * ```typescript
+     * const circuits = sdk.getSupportedCircuits();
+     * console.log('Supported circuits:', circuits);
+     * // ['coinbase_attestation', 'coinbase_country_attestation']
+     * ```
+     */
+    getSupportedCircuits() {
+        return Object.keys(CIRCUIT_METADATA);
+    }
+    /**
+     * @internal
+     * Validates a proof request for completeness and correctness.
+     *
+     * Checks that the proof request contains all required fields and that the
+     * circuit-specific inputs are valid. Useful for catching configuration errors
+     * before generating QR codes or sending requests to users.
+     *
+     * @param request - ProofRequest object to validate
+     *
+     * @returns Validation result with valid boolean and optional error message
+     *
+     * @example
+     * ```typescript
+     * const request = sdk.createCoinbaseKycRequest({ scope: 'myapp.com' });
+     * const validation = sdk.validateRequest(request);
+     *
+     * if (!validation.valid) {
+     *   console.error('Invalid request:', validation.error);
+     * }
+     * ```
+     */
+    validateRequest(request) {
+        return validateProofRequest(request);
+    }
+    /**
+     * @internal
+     * Checks if a URL is a ZKProofport deep link.
+     *
+     * Validates whether the given URL uses the ZKProofport deep link scheme
+     * (zkproofport:// by default) and has the correct format for a proof request.
+     *
+     * @param url - URL string to check
+     *
+     * @returns True if the URL is a valid ZKProofport deep link
+     *
+     * @example
+     * ```typescript
+     * const url = 'zkproofport://proof?requestId=abc123&circuit=coinbase_attestation';
+     * if (sdk.isProofportDeepLink(url)) {
+     *   const request = sdk.parseDeepLink(url);
+     *   console.log('Parsed request:', request);
+     * }
+     * ```
+     */
+    isProofportDeepLink(url) {
+        return isProofportDeepLink(url, this.config.scheme);
+    }
+    /**
+     * @internal
+     * Parses a proof request from a deep link URL.
+     *
+     * Extracts and decodes the proof request data from a zkproofport:// deep link URL.
+     * Useful for handling deep link navigation in web applications or validating
+     * deep link URLs before displaying QR codes.
+     *
+     * @param url - ZKProofport deep link URL string
+     *
+     * @returns ProofRequest object with all request details, or null if invalid
+     *
+     * @example
+     * ```typescript
+     * const deepLink = 'zkproofport://proof?requestId=abc123&circuit=coinbase_attestation&...';
+     * const request = sdk.parseDeepLink(deepLink);
+     *
+     * if (request) {
+     *   console.log('Request ID:', request.requestId);
+     *   console.log('Circuit:', request.circuit);
+     * }
+     * ```
+     */
+    parseDeepLink(url) {
+        return parseProofRequestUrl(url);
+    }
+    // ============ Static Factory ============
+    /**
+     * Creates a new ProofportSDK instance with environment preset or custom config.
+     * Defaults to `'production'` if no argument is provided.
+     *
+     * **Recommended usage** — use the default production relay:
+     * ```typescript
+     * const sdk = ProofportSDK.create();
+     * ```
+     *
+     * Environment presets:
+     * - `'production'` — relay.zkproofport.app (default)
+     * - `'staging'` — stg-relay.zkproofport.app
+     * - `'local'` — localhost:4001
+     *
+     * @param envOrConfig - Environment name or custom SDK configuration
+     *
+     * @returns New ProofportSDK instance
+     *
+     * @example
+     * ```typescript
+     * // Environment preset (recommended)
+     * const sdk = ProofportSDK.create(); // production (default)
+     * const sdk = ProofportSDK.create('staging');
+     *
+     * // Custom config
+     * const sdk = ProofportSDK.create({
+     *   relayUrl: 'https://my-custom-relay.example.com',
+     * });
+     * ```
+     */
+    static create(envOrConfig) {
+        if (typeof envOrConfig === 'undefined') {
+            return new ProofportSDK({ relayUrl: RELAY_URLS.production });
+        }
+        if (typeof envOrConfig === 'string') {
+            const relayUrl = RELAY_URLS[envOrConfig];
+            if (!relayUrl) {
+                throw new Error(`Unknown environment: ${envOrConfig}. Use 'production', 'staging', or 'local'.`);
+            }
+            return new ProofportSDK({ relayUrl });
+        }
+        return new ProofportSDK(envOrConfig);
+    }
+    /**
+     * Detects if the code is running on a mobile device.
+     *
+     * Uses user agent detection to determine if the current environment is a mobile
+     * browser. This helps the SDK automatically choose between direct deep link
+     * navigation (mobile) and QR code display (desktop).
+     *
+     * @returns True if running on a mobile device (iOS, Android, etc.)
+     *
+     * @example
+     * ```typescript
+     * if (ProofportSDK.isMobile()) {
+     *   // Open deep link directly
+     *   sdk.openProofRequest(request);
+     * } else {
+     *   // Show QR code
+     *   const qr = await sdk.generateQRCode(request);
+     *   displayQRCode(qr);
+     * }
+     * ```
+     */
+    static isMobile() {
+        if (typeof navigator === 'undefined')
+            return false;
+        return /Android|iPhone|iPad|iPod|webOS|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);
+    }
+    /**
+     * Authenticates with ZKProofport using client credentials via the relay server.
+     *
+     * Exchanges a client_id and api_key pair for a short-lived JWT token
+     * that can be used to authenticate relay requests.
+     *
+     * @param credentials - Client ID and API key
+     * @param relayUrl - Relay server URL (e.g., 'https://relay.zkproofport.app')
+     * @returns Promise resolving to AuthToken with JWT token and metadata
+     * @throws Error if authentication fails
+     *
+     * @example
+     * ```typescript
+     * const auth = await ProofportSDK.authenticate(
+     *   { clientId: 'your-client-id', apiKey: 'your-api-key' },
+     *   'https://relay.zkproofport.app'
+     * );
+     * console.log('Token:', auth.token);
+     * console.log('Expires in:', auth.expiresIn, 'seconds');
+     * ```
+     */
+    static async authenticate(credentials, relayUrl) {
+        if (!credentials.clientId || !credentials.apiKey) {
+            throw new Error('clientId and apiKey are required');
+        }
+        if (!relayUrl) {
+            throw new Error('relayUrl is required');
+        }
+        const response = await fetch(`${relayUrl}/api/v1/auth/token`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                client_id: credentials.clientId,
+                api_key: credentials.apiKey,
+            }),
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: `HTTP ${response.status}` }));
+            throw new Error(error.error || `Authentication failed: HTTP ${response.status}`);
+        }
+        const data = await response.json();
+        return {
+            token: data.token,
+            clientId: data.client_id,
+            dappId: data.dapp_id,
+            tier: data.tier,
+            expiresIn: data.expires_in,
+            expiresAt: Date.now() + (data.expires_in * 1000),
+        };
+    }
+    /**
+     * Checks if an auth token is still valid (not expired).
+     *
+     * @param auth - AuthToken to check
+     * @returns True if the token has not expired
+     *
+     * @example
+     * ```typescript
+     * if (!ProofportSDK.isTokenValid(auth)) {
+     *   auth = await ProofportSDK.authenticate(credentials, relayUrl);
+     * }
+     * ```
+     */
+    static isTokenValid(auth) {
+        return Date.now() < auth.expiresAt - 30000; // 30s buffer
+    }
+    // ============ Relay Integration ============
+    /**
+     * Authenticates with ZKProofport and stores the token for relay requests.
+     *
+     * Instance method that authenticates via the relay server and stores
+     * the JWT token internally, so subsequent relay requests are automatically authenticated.
+     *
+     * @param credentials - Client ID and API key
+     * @returns Promise resolving to AuthToken
+     * @throws Error if authentication fails or relayUrl is not configured
+     *
+     * @example
+     * ```typescript
+     * const sdk = ProofportSDK.create('production');
+     *
+     * await sdk.login({ clientId: 'your-id', apiKey: 'your-key' });
+     * // SDK is now authenticated for relay requests
+     * ```
+     */
+    async login(credentials) {
+        if (!this.relayUrl) {
+            throw new Error('relayUrl is required for authentication. Use ProofportSDK.create(\'production\') or set relayUrl in config.');
+        }
+        this.authToken = await ProofportSDK.authenticate(credentials, this.relayUrl);
+        return this.authToken;
+    }
+    /**
+     * Logs out by clearing the stored authentication token.
+     */
+    logout() {
+        this.authToken = null;
+    }
+    /**
+     * Returns whether the SDK instance is currently authenticated with a valid token.
+     */
+    isAuthenticated() {
+        return this.authToken !== null && ProofportSDK.isTokenValid(this.authToken);
+    }
+    /**
+     * Returns the current auth token, or null if not authenticated.
+     */
+    getAuthToken() {
+        return this.authToken;
+    }
+    /**
+     * Creates a proof request through the relay server.
+     *
+     * This is the recommended way to create proof requests. The relay server:
+     * - Issues a server-side requestId (validated by the mobile app)
+     * - Tracks request status in Redis
+     * - Handles credit deduction and tier enforcement
+     * - Builds the deep link with relay callback URL
+     *
+     * @param circuit - Circuit type identifier
+     * @param inputs - Circuit-specific inputs
+     * @param options - Request options (message, dappName, dappIcon, nonce)
+     * @returns Promise resolving to RelayProofRequest with requestId, deepLink, pollUrl
+     * @throws Error if not authenticated or relay request fails
+     *
+     * @example
+     * ```typescript
+     * const sdk = ProofportSDK.create();
+     * await sdk.login({ clientId: 'id', apiKey: 'key' });
+     *
+     * const relay = await sdk.createRelayRequest('coinbase_attestation', {
+     *   scope: 'myapp.com'
+     * }, { dappName: 'My DApp' });
+     *
+     * // Generate QR code from relay deep link
+     * const qr = await sdk.generateQRCode(relay.deepLink);
+     *
+     * // Wait for proof (WebSocket primary, polling fallback)
+     * const result = await sdk.waitForProof(relay.requestId);
+     * ```
+     */
+    async createRelayRequest(circuit, inputs, options = {}) {
+        if (!this.authToken || !ProofportSDK.isTokenValid(this.authToken)) {
+            throw new Error('Not authenticated. Call login() first.');
+        }
+        if (!this.relayUrl) {
+            throw new Error('relayUrl is required. Set it in ProofportSDK config.');
+        }
+        const body = {
+            circuitId: circuit,
+            inputs,
+        };
+        if (options.message)
+            body.message = options.message;
+        if (options.dappName)
+            body.dappName = options.dappName;
+        if (options.dappIcon)
+            body.dappIcon = options.dappIcon;
+        if (options.nonce)
+            body.nonce = options.nonce;
+        const response = await fetch(`${this.relayUrl}/api/v1/proof/request`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.authToken.token}`,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: `HTTP ${response.status}` }));
+            throw new Error(error.error || `Relay request failed: HTTP ${response.status}`);
+        }
+        return await response.json();
+    }
+    /**
+     * Polls the relay for proof result status.
+     *
+     * @param requestId - The relay-issued request ID
+     * @returns Promise resolving to RelayProofResult
+     * @throws Error if relay URL not configured or request not found
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.pollResult(relay.requestId);
+     * if (result.status === 'completed') {
+     *   console.log('Proof:', result.proof);
+     *   console.log('Public inputs:', result.publicInputs);
+     * }
+     * ```
+     */
+    async pollResult(requestId) {
+        if (!this.relayUrl) {
+            throw new Error('relayUrl is required. Set it in ProofportSDK config.');
+        }
+        const response = await fetch(`${this.relayUrl}/api/v1/proof/${requestId}`);
+        if (!response.ok) {
+            if (response.status === 404) {
+                throw new Error('Request not found or expired');
+            }
+            const error = await response.json().catch(() => ({ error: `HTTP ${response.status}` }));
+            throw new Error(error.error || `Poll failed: HTTP ${response.status}`);
+        }
+        return await response.json();
+    }
+    /**
+     * Polls the relay until proof is completed or failed, with configurable interval and timeout.
+     *
+     * @param requestId - The relay-issued request ID
+     * @param options - Polling options
+     * @param options.intervalMs - Polling interval in milliseconds (default: 2000)
+     * @param options.timeoutMs - Maximum polling time in milliseconds (default: 300000 = 5 min)
+     * @param options.onStatusChange - Callback when status changes
+     * @returns Promise resolving to final RelayProofResult
+     * @throws Error if timeout or relay error
+     */
+    async waitForResult(requestId, options = {}) {
+        const interval = options.intervalMs || 2000;
+        const timeout = options.timeoutMs || 300000;
+        const startTime = Date.now();
+        let lastStatus = '';
+        while (Date.now() - startTime < timeout) {
+            const result = await this.pollResult(requestId);
+            if (result.status !== lastStatus) {
+                lastStatus = result.status;
+                options.onStatusChange?.(result);
+            }
+            if (result.status === 'completed' || result.status === 'failed') {
+                return result;
+            }
+            await new Promise(resolve => setTimeout(resolve, interval));
+        }
+        throw new Error(`Polling timed out after ${timeout}ms`);
+    }
+    /**
+     * Subscribes to real-time proof status updates via Socket.IO.
+     *
+     * This is the recommended way to receive proof results. Uses WebSocket
+     * connection for instant delivery instead of polling.
+     *
+     * Requires `socket.io-client` package: `npm install socket.io-client`
+     *
+     * @param requestId - The relay-issued request ID to subscribe to
+     * @param callbacks - Event callbacks for status changes and results
+     * @param callbacks.onStatus - Called on status updates (pending, generating)
+     * @param callbacks.onResult - Called when proof is completed or failed
+     * @param callbacks.onError - Called on errors
+     * @returns Unsubscribe function to clean up the connection
+     * @throws Error if not authenticated, relayUrl not set, or socket.io-client not installed
+     *
+     * @example
+     * ```typescript
+     * const relay = await sdk.createRelayRequest('coinbase_attestation', { scope: 'myapp.com' });
+     * const qr = await sdk.generateQRCode(relay.deepLink);
+     *
+     * const unsubscribe = await sdk.subscribe(relay.requestId, {
+     *   onResult: (result) => {
+     *     if (result.status === 'completed') {
+     *       console.log('Proof received!', result.proof);
+     *     }
+     *   },
+     *   onError: (error) => console.error('Error:', error),
+     * });
+     *
+     * // Later: clean up
+     * unsubscribe();
+     * ```
+     */
+    async subscribe(requestId, callbacks) {
+        if (!this.authToken || !ProofportSDK.isTokenValid(this.authToken)) {
+            throw new Error('Not authenticated. Call login() first.');
+        }
+        if (!this.relayUrl) {
+            throw new Error('relayUrl is required. Set it in ProofportSDK config.');
+        }
+        let ioConnect;
+        try {
+            const mod = await import('socket.io-client');
+            ioConnect = mod.io ?? mod.connect ?? mod.default;
+        }
+        catch {
+            throw new Error('socket.io-client is required for real-time updates. Install it: npm install socket.io-client');
+        }
+        if (typeof ioConnect !== 'function') {
+            throw new Error('Failed to load socket.io-client: io function not found');
+        }
+        // Connect to relay /proof namespace
+        const socket = ioConnect(`${this.relayUrl}/proof`, {
+            path: '/socket.io',
+            auth: { token: this.authToken.token },
+            transports: ['websocket', 'polling'],
+        });
+        this.socket = socket;
+        // Subscribe to the request room
+        socket.on('connect', () => {
+            socket.emit('proof:subscribe', { requestId });
+        });
+        // Handle connection errors (e.g. rejected by relay middleware)
+        socket.on('connect_error', (err) => {
+            console.error(`[ProofportSDK] Socket.IO connect_error for requestId=${requestId}: ${err.message}`);
+            callbacks.onError?.({ error: err.message, requestId });
+        });
+        // Listen for events
+        if (callbacks.onStatus) {
+            socket.on('proof:status', callbacks.onStatus);
+        }
+        if (callbacks.onResult) {
+            socket.on('proof:result', callbacks.onResult);
+        }
+        if (callbacks.onError) {
+            socket.on('proof:error', callbacks.onError);
+        }
+        // Return unsubscribe function
+        return () => {
+            socket.off('proof:status');
+            socket.off('proof:result');
+            socket.off('proof:error');
+            socket.disconnect();
+            if (this.socket === socket) {
+                this.socket = null;
+            }
+        };
+    }
+    /**
+     * Waits for a proof result using Socket.IO (primary) with polling fallback.
+     *
+     * Tries Socket.IO first for real-time delivery. If socket.io-client is not
+     * installed or connection fails, automatically falls back to HTTP polling.
+     *
+     * @param requestId - The relay-issued request ID
+     * @param options - Configuration options
+     * @param options.timeoutMs - Maximum wait time in ms (default: 300000 = 5 min)
+     * @param options.onStatusChange - Callback for status updates
+     * @returns Promise resolving to final RelayProofResult
+     */
+    async waitForProof(requestId, options = {}) {
+        const timeout = options.timeoutMs || 300000;
+        // Try Socket.IO first
+        if (this.authToken && ProofportSDK.isTokenValid(this.authToken) && this.relayUrl) {
+            try {
+                return await new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => {
+                        unsubscribePromise?.then(fn => fn());
+                        reject(new Error(`Waiting for proof timed out after ${timeout}ms`));
+                    }, timeout);
+                    const unsubscribePromise = this.subscribe(requestId, {
+                        onStatus: (data) => {
+                            options.onStatusChange?.(data);
+                        },
+                        onResult: (result) => {
+                            clearTimeout(timer);
+                            unsubscribePromise?.then(fn => fn());
+                            resolve(result);
+                        },
+                        onError: (error) => {
+                            clearTimeout(timer);
+                            unsubscribePromise?.then(fn => fn());
+                            reject(new Error(error.error));
+                        },
+                    });
+                });
+            }
+            catch (err) {
+                // Re-throw timeout — that's a real failure the caller should handle
+                if (err.message?.includes('timed out')) {
+                    throw err;
+                }
+                // socket.io-client missing or connection failed → fall back to polling silently
+                console.warn('Socket.IO unavailable, falling back to HTTP polling:', err.message);
+            }
+        }
+        // Fallback: HTTP polling
+        return this.waitForResult(requestId, {
+            timeoutMs: timeout,
+            onStatusChange: options.onStatusChange,
+        });
+    }
+    /**
+     * Disconnects the Socket.IO connection if active.
+     */
+    disconnect() {
+        if (this.socket) {
+            this.socket.disconnect();
+            this.socket = null;
+        }
+    }
+    // ============ Nullifier Utilities ============
+    /**
+     * Extracts the nullifier from proof public inputs.
+     *
+     * The nullifier is a bytes32 value derived from the user's address and scope,
+     * used to prevent duplicate proof submissions. Each user+scope combination
+     * produces a unique nullifier.
+     *
+     * @param publicInputs - Array of public input hex strings from proof response
+     * @param circuit - Circuit type to determine field positions
+     * @returns Nullifier as hex string (0x...), or null if inputs are insufficient
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.waitForProof(relay.requestId);
+     * if (result.status === 'completed') {
+     *   const nullifier = sdk.extractNullifier(result.publicInputs, result.circuit);
+     *   console.log('Nullifier:', nullifier);
+     * }
+     * ```
+     */
+    extractNullifier(publicInputs, circuit) {
+        return extractNullifierFromPublicInputs(publicInputs, circuit);
+    }
+    /**
+     * Extracts the scope from proof public inputs.
+     *
+     * The scope is an application-specific identifier (e.g., domain name) encoded
+     * as bytes32 in the proof's public inputs.
+     *
+     * @param publicInputs - Array of public input hex strings from proof response
+     * @param circuit - Circuit type to determine field positions
+     * @returns Scope as hex string (0x...), or null if inputs are insufficient
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.waitForProof(relay.requestId);
+     * if (result.status === 'completed') {
+     *   const scope = sdk.extractScope(result.publicInputs, result.circuit);
+     *   console.log('Scope:', scope);
+     * }
+     * ```
+     */
+    extractScope(publicInputs, circuit) {
+        return extractScopeFromPublicInputs(publicInputs, circuit);
+    }
+    /**
+     * Checks if a nullifier is already registered on-chain.
+     *
+     * Queries the ZKProofportNullifierRegistry contract to determine if the
+     * nullifier has been used before. Used to prevent duplicate proof submissions.
+     *
+     * Requires `nullifierRegistry` in SDK config.
+     *
+     * @param nullifier - Nullifier hex string from extractNullifier()
+     * @param provider - Optional ethers provider (defaults to public RPC for configured chain)
+     * @returns True if nullifier is already registered
+     * @throws Error if nullifierRegistry is not configured
+     *
+     * @example
+     * ```typescript
+     * const sdk = ProofportSDK.create({
+     *   relayUrl: 'https://relay.zkproofport.app',
+     *   nullifierRegistry: { address: '0x...', chainId: 8453 }
+     * });
+     *
+     * const nullifier = sdk.extractNullifier(publicInputs, circuit);
+     * const isDuplicate = await sdk.checkNullifier(nullifier);
+     * ```
+     */
+    async checkNullifier(nullifier, provider) {
+        if (!this.nullifierRegistry) {
+            throw new Error('nullifierRegistry is required. Set it in ProofportSDK config.');
+        }
+        const p = provider || getDefaultProvider(this.nullifierRegistry.chainId);
+        return isNullifierRegistered(nullifier, this.nullifierRegistry.address, p);
+    }
+    /**
+     * Gets detailed information about a registered nullifier from on-chain registry.
+     *
+     * Retrieves the registration timestamp, scope, and circuit ID for a nullifier.
+     * Returns null if the nullifier is not registered.
+     *
+     * Requires `nullifierRegistry` in SDK config.
+     *
+     * @param nullifier - Nullifier hex string from extractNullifier()
+     * @param provider - Optional ethers provider (defaults to public RPC for configured chain)
+     * @returns Nullifier info or null if not registered
+     * @throws Error if nullifierRegistry is not configured
+     *
+     * @example
+     * ```typescript
+     * const info = await sdk.getNullifierDetails(nullifier);
+     * if (info) {
+     *   console.log('Registered at:', new Date(info.registeredAt * 1000));
+     *   console.log('Circuit:', info.circuitId);
+     * }
+     * ```
+     */
+    async getNullifierDetails(nullifier, provider) {
+        if (!this.nullifierRegistry) {
+            throw new Error('nullifierRegistry is required. Set it in ProofportSDK config.');
+        }
+        const p = provider || getDefaultProvider(this.nullifierRegistry.chainId);
+        return getNullifierInfo(nullifier, this.nullifierRegistry.address, p);
+    }
+}
+
+exports.ProofportSDK = ProofportSDK;
+exports.default = ProofportSDK;
+//# sourceMappingURL=index.js.map