@zkproofport-app/sdk 0.1.2-beta.1

package/dist/qrcode.d.ts

@@ -0,0 +1,120 @@
+/**
+ * QR Code utilities for ZKProofport SDK
+ */
+import type { ProofRequest, QRCodeOptions } from './types';
+/**
+ * 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" />
+ * ```
+ */
+export declare function generateQRCodeDataUrl(requestOrUrl: ProofRequest | string, options?: QRCodeOptions, scheme?: string): Promise<string>;
+/**
+ * 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);
+ * ```
+ */
+export declare function generateQRCodeSVG(requestOrUrl: ProofRequest | string, options?: QRCodeOptions, scheme?: string): Promise<string>;
+/**
+ * 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} />;
+ * ```
+ */
+export declare function generateQRCodeToCanvas(canvas: HTMLCanvasElement, requestOrUrl: ProofRequest | string, options?: QRCodeOptions, scheme?: string): Promise<void>;
+/**
+ * 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 }
+ * ```
+ */
+export declare function estimateQRDataSize(requestOrUrl: ProofRequest | string, scheme?: string): {
+    size: number;
+    withinLimit: boolean;
+};

package/dist/types.d.ts

@@ -0,0 +1,434 @@
+/**
+ * ZKProofport SDK Types
+ */
+/**
+ * Supported zero-knowledge circuit types.
+ * Uses canonical circuit names matching Nargo.toml circuit definitions.
+ *
+ * @example
+ * ```typescript
+ * const circuit: CircuitType = 'coinbase_attestation';
+ * ```
+ */
+export type CircuitType = 'coinbase_attestation' | 'coinbase_country_attestation';
+/**
+ * Proof request lifecycle status.
+ *
+ * - `pending`: Request sent to mobile app, awaiting proof generation
+ * - `completed`: Proof successfully generated and returned
+ * - `error`: Proof generation failed
+ * - `cancelled`: Request cancelled by user
+ */
+export type ProofRequestStatus = 'pending' | 'completed' | 'error' | 'cancelled';
+/**
+ * Input parameters for Coinbase KYC attestation circuit.
+ *
+ * This circuit proves a user has completed Coinbase KYC verification
+ * without revealing their identity or Coinbase account details.
+ *
+ * @property userAddress - Ethereum address to prove ownership of (optional, app will connect wallet if not provided)
+ * @property rawTransaction - Raw attestation transaction data (optional, app can fetch from Etherscan)
+ * @property scope - Application-specific identifier for proof uniqueness (e.g., dapp domain)
+ *
+ * @example
+ * ```typescript
+ * const inputs: CoinbaseKycInputs = {
+ *   userAddress: '0x1234...', // Optional
+ *   scope: 'myapp.com'
+ * };
+ * ```
+ */
+export interface CoinbaseKycInputs {
+    userAddress?: string;
+    rawTransaction?: string;
+    scope: string;
+}
+/**
+ * Input parameters for Coinbase Country attestation circuit.
+ *
+ * This circuit proves a user's country based on Coinbase verification,
+ * supporting both inclusion (user IS from countries) and exclusion (user is NOT from countries) checks.
+ *
+ * @property userAddress - Ethereum address to prove ownership of (optional)
+ * @property rawTransaction - Raw attestation transaction data (optional)
+ * @property countryList - List of ISO 3166-1 alpha-2 country codes (e.g., ['US', 'KR']) (required)
+ * @property isIncluded - If true, proves user IS from countries; if false, proves user is NOT from countries (required)
+ * @property scope - Application-specific identifier for proof uniqueness
+ *
+ * @example
+ * ```typescript
+ * // Prove user is from US or KR
+ * const inputs: CoinbaseCountryInputs = {
+ *   countryList: ['US', 'KR'],
+ *   isIncluded: true,
+ *   scope: 'myapp.com'
+ * };
+ * ```
+ */
+export interface CoinbaseCountryInputs {
+    userAddress?: string;
+    rawTransaction?: string;
+    countryList: string[];
+    isIncluded: boolean;
+    scope: string;
+}
+/**
+ * Empty input type for circuits that retrieve all data from the mobile app.
+ * Used when SDK doesn't need to provide any circuit-specific parameters.
+ */
+export interface EmptyInputs {
+}
+/**
+ * Union type of all circuit-specific input types.
+ * Each circuit type has a corresponding input interface.
+ */
+export type CircuitInputs = CoinbaseKycInputs | CoinbaseCountryInputs | EmptyInputs;
+/**
+ * Zero-knowledge proof request sent to mobile app via deep link.
+ *
+ * This structure is serialized into a deep link URL that opens the ZKProofport mobile app.
+ * The app generates the proof and sends the result to the callbackUrl.
+ *
+ * @example
+ * ```typescript
+ * const request: ProofRequest = {
+ *   requestId: 'req_123',
+ *   circuit: 'coinbase_attestation',
+ *   inputs: { scope: 'myapp.com' },
+ *   dappName: 'My DApp',
+ *   createdAt: Date.now(),
+ *   expiresAt: Date.now() + 600000 // 10 minutes
+ * };
+ * ```
+ */
+export interface ProofRequest {
+    /** Unique request identifier (used to match request with response) */
+    requestId: string;
+    /** Circuit type to use for proof generation */
+    circuit: CircuitType;
+    /** Circuit-specific input parameters */
+    inputs: CircuitInputs;
+    /** @internal URL where mobile app will POST the proof response (set by relay server internally, never by SDK users) */
+    callbackUrl?: string;
+    /** Optional: Custom message to display to user in mobile app */
+    message?: string;
+    /** Optional: DApp name displayed in mobile app UI */
+    dappName?: string;
+    /** Optional: DApp icon URL displayed in mobile app UI */
+    dappIcon?: string;
+    /** Unix timestamp (ms) when request was created */
+    createdAt: number;
+    /** Optional: Unix timestamp (ms) when request expires */
+    expiresAt?: number;
+}
+/**
+ * Zero-knowledge proof response received from mobile app.
+ *
+ * This structure is returned via the callbackUrl after the mobile app generates the proof.
+ * For successful proofs, includes the proof data and public inputs needed for on-chain verification.
+ *
+ * @example
+ * ```typescript
+ * const response: ProofResponse = {
+ *   requestId: 'req_123',
+ *   circuit: 'coinbase_attestation',
+ *   status: 'completed',
+ *   proof: '0x1234...',
+ *   publicInputs: ['0xabcd...', '0xef01...'],
+ *   numPublicInputs: 2,
+ *   verifierAddress: '0x5678...',
+ *   chainId: 84532,
+ *   nullifier: '0x9abc...',
+ *   timestamp: Date.now()
+ * };
+ * ```
+ */
+export interface ProofResponse {
+    /** Original request ID (matches ProofRequest.requestId) */
+    requestId: string;
+    /** Circuit type used for proof generation */
+    circuit: CircuitType;
+    /** Request status (completed, error, cancelled) */
+    status: ProofRequestStatus;
+    /** Proof data as hex string (present if status is completed) */
+    proof?: string;
+    /** Public inputs as array of hex strings (present if status is completed) */
+    publicInputs?: string[];
+    /** Number of public inputs (used for verification) */
+    numPublicInputs?: number;
+    /** Error message (present if status is error) */
+    error?: string;
+    /** Unix timestamp (ms) when proof was generated */
+    timestamp?: number;
+    /** Verifier contract address on target chain (provided by mobile app) */
+    verifierAddress?: string;
+    /** Chain ID where verifier contract is deployed (provided by mobile app) */
+    chainId?: number;
+    /** Nullifier for proof uniqueness (prevents double-use, derived from scope) */
+    nullifier?: string;
+}
+/**
+ * Parsed and formatted proof data ready for on-chain verification.
+ *
+ * Internal representation used by the SDK to prepare proof data
+ * for smart contract verification calls.
+ */
+export interface ParsedProof {
+    /** Proof bytes as hex string with 0x prefix */
+    proofHex: string;
+    /** Public inputs as array of hex strings with 0x prefix */
+    publicInputsHex: string[];
+    /** Number of public inputs (must match circuit specification) */
+    numPublicInputs: number;
+}
+/**
+ * QR code generation options for deep link encoding.
+ *
+ * Controls the appearance and error correction level of generated QR codes.
+ * Higher error correction allows for more damage tolerance but requires larger QR codes.
+ *
+ * @example
+ * ```typescript
+ * const options: QRCodeOptions = {
+ *   width: 512,
+ *   errorCorrectionLevel: 'M',
+ *   darkColor: '#000000',
+ *   lightColor: '#ffffff'
+ * };
+ * ```
+ */
+export interface QRCodeOptions {
+    /** QR code width in pixels (default: 300) */
+    width?: number;
+    /** Error correction level: L (7%), M (15%), Q (25%), H (30%) (default: M) */
+    errorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H';
+    /** Margin around QR code in module units (default: 4) */
+    margin?: number;
+    /** Foreground color as hex string (default: #000000) */
+    darkColor?: string;
+    /** Background color as hex string (default: #ffffff) */
+    lightColor?: string;
+}
+/**
+ * Verifier smart contract configuration.
+ *
+ * Contains the address and ABI for a circuit's verifier contract on a specific chain.
+ * Each circuit has its own verifier contract that validates proofs on-chain.
+ */
+export interface VerifierContract {
+    /** Verifier contract address (checksummed) */
+    address: string;
+    /** Chain ID where contract is deployed (e.g., 84532 for Base Sepolia) */
+    chainId: number;
+    /** Contract ABI for verify function (ethers v6 format) */
+    abi: string[];
+}
+/**
+ * ZKProofport SDK configuration options.
+ *
+ * Allows customization of deep link scheme, default callback URL,
+ * and verifier contract addresses.
+ *
+ * @example
+ * ```typescript
+ * // Recommended: use environment preset
+ * const sdk = ProofportSDK.create('production');
+ *
+ * // Or custom config:
+ * const config: ProofportConfig = {
+ *   relayUrl: 'https://relay.zkproofport.app',
+ *   verifiers: {
+ *     coinbase_attestation: {
+ *       address: '0x1234...',
+ *       chainId: 84532,
+ *       abi: VERIFIER_ABI
+ *     }
+ *   }
+ * };
+ * const sdk = new ProofportSDK(config);
+ * ```
+ */
+/**
+ * SDK environment preset names.
+ * Used with `ProofportSDK.create('production')` for zero-config initialization.
+ *
+ * - `production` — relay.zkproofport.app
+ * - `staging` — stg-relay.zkproofport.app
+ * - `local` — localhost:4001
+ */
+export type SDKEnvironment = 'production' | 'staging' | 'local';
+export interface ProofportConfig {
+    /** Deep link URL scheme (default: 'zkproofport') */
+    scheme?: string;
+    /** Relay server URL (e.g., 'https://relay.zkproofport.app'). Required for relay features. */
+    relayUrl?: string;
+    /** Custom verifier contract addresses per circuit type (overrides defaults) */
+    verifiers?: Partial<Record<CircuitType, VerifierContract>>;
+    /** Nullifier registry contract config. Required for checkNullifier() and getNullifierDetails(). */
+    nullifierRegistry?: {
+        /** Registry contract address */
+        address: string;
+        /** Chain ID where registry is deployed */
+        chainId: number;
+    };
+}
+/**
+ * Parsed deep link URL components.
+ *
+ * Internal representation of a deep link URL broken into its constituent parts.
+ * Used for deep link generation and parsing.
+ */
+export interface DeepLinkComponents {
+    /** URL scheme (e.g., 'zkproofport') */
+    scheme: string;
+    /** URL host (e.g., 'proof-request') */
+    host: string;
+    /** URL path (e.g., '/verify') */
+    path: string;
+    /** Query parameters as key-value pairs */
+    params: Record<string, string>;
+}
+/**
+ * Nullifier verification status returned by smart contract.
+ *
+ * Mirrors the NullifierVerifyStatus enum in the ZKProofportNullifierRegistry contract.
+ * Indicates the result of verifying and registering a proof's nullifier on-chain.
+ *
+ * - `verified_and_registered`: Proof verified and nullifier registered successfully
+ * - `already_registered`: Proof verified but nullifier was already used (duplicate)
+ * - `expired_and_reregistered`: Previous nullifier expired, new one registered
+ * - `verification_failed`: Proof verification failed (invalid proof)
+ * - `circuit_not_found`: Circuit not registered in the registry
+ */
+export type NullifierVerifyStatus = 'verified_and_registered' | 'already_registered' | 'expired_and_reregistered' | 'verification_failed' | 'circuit_not_found';
+/**
+ * On-chain nullifier record from smart contract storage.
+ *
+ * Contains information about a registered nullifier retrieved from
+ * the ZKProofportNullifierRegistry contract.
+ *
+ * @example
+ * ```typescript
+ * const record: NullifierRecord = {
+ *   registeredAt: 1707234567,
+ *   scope: '0xabcd...',
+ *   circuitId: '0x1234...'
+ * };
+ * ```
+ */
+export interface NullifierRecord {
+    /** Unix timestamp (seconds) when nullifier was registered */
+    registeredAt: number;
+    /** Scope bytes32 (application identifier) */
+    scope: string;
+    /** Circuit ID bytes32 (circuit identifier) */
+    circuitId: string;
+}
+/**
+ * ZKProofportNullifierRegistry smart contract configuration.
+ *
+ * Contains the address and ABI for the nullifier registry contract,
+ * which tracks used nullifiers to prevent proof replay attacks.
+ *
+ * @example
+ * ```typescript
+ * const registryConfig: NullifierRegistryConfig = {
+ *   address: '0x5678...',
+ *   chainId: 84532,
+ *   abi: ZKPROOFPORT_NULLIFIER_REGISTRY_ABI
+ * };
+ * ```
+ */
+export interface NullifierRegistryConfig {
+    /** Registry contract address (checksummed) */
+    address: string;
+    /** Chain ID where registry is deployed */
+    chainId: number;
+    /** Contract ABI (ethers v6 format) */
+    abi: string[];
+}
+/**
+ * Client credentials for API authentication.
+ *
+ * Used to authenticate with the ZKProofport API server and obtain
+ * a JWT token for making authenticated requests to the relay server.
+ *
+ * @example
+ * ```typescript
+ * const credentials: AuthCredentials = {
+ *   clientId: 'your-client-id',
+ *   apiKey: 'your-api-key'
+ * };
+ * ```
+ */
+export interface AuthCredentials {
+    /** Client ID identifying the application */
+    clientId: string;
+    /** API key for authentication */
+    apiKey: string;
+}
+/**
+ * JWT authentication token received from the API server.
+ *
+ * Contains the JWT token and metadata about the authenticated session,
+ * including tier information, expiration time, and associated identifiers.
+ *
+ * @example
+ * ```typescript
+ * const auth: AuthToken = {
+ *   token: 'eyJhbGc...',
+ *   clientId: 'your-client-id',
+ *   dappId: 'app-123',
+ *   tier: 'plan1',
+ *   expiresIn: 3600,
+ *   expiresAt: 1707234567890
+ * };
+ * ```
+ */
+export interface AuthToken {
+    /** JWT token for authenticating relay requests */
+    token: string;
+    /** Client ID that the token was issued for */
+    clientId: string;
+    /** DApp ID associated with this client */
+    dappId: string;
+    /** Service tier (free, credit, plan1, plan2) */
+    tier: string;
+    /** Token lifetime in seconds (typically 3600 = 1 hour) */
+    expiresIn: number;
+    /** Unix timestamp (ms) when the token expires */
+    expiresAt: number;
+}
+/**
+ * Result from creating a proof request via relay.
+ * Contains relay-issued requestId, deep link, and poll URL.
+ */
+export interface RelayProofRequest {
+    /** Relay-issued unique request ID (UUID format) */
+    requestId: string;
+    /** Deep link URL to open ZKProofport app (built by relay) */
+    deepLink: string;
+    /** Relay status: pending, completed, failed */
+    status: string;
+    /** Relative poll URL for checking proof status (e.g., /api/v1/proof/{requestId}) */
+    pollUrl: string;
+}
+/**
+ * Proof result retrieved from relay polling.
+ */
+export interface RelayProofResult {
+    requestId: string;
+    status: 'pending' | 'completed' | 'failed';
+    deepLink?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    /** Present when status is 'completed' */
+    proof?: string;
+    publicInputs?: string[];
+    verifierAddress?: string;
+    chainId?: number;
+    nullifier?: string;
+    circuit?: string;
+    /** Present when status is 'failed' */
+    error?: string;
+}