@zkproofport-app/sdk 0.1.2-beta.1

package/dist/constants.d.ts

@@ -0,0 +1,223 @@
+/**
+ * ZKProofport SDK Constants
+ */
+import type { CircuitType, SDKEnvironment } from './types';
+/**
+ * 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'
+ * ```
+ */
+export declare const RELAY_URLS: Record<SDKEnvironment, string>;
+/**
+ * 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?...
+ * ```
+ */
+export declare 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}`;
+ * ```
+ */
+export declare const DEEP_LINK_HOSTS: {
+    /** Host for proof requests sent to mobile app */
+    readonly PROOF_REQUEST: "proof-request";
+    /** Host for proof responses returned from mobile app */
+    readonly PROOF_RESPONSE: "proof-response";
+};
+/**
+ * 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
+ * ```
+ */
+export declare const CIRCUIT_METADATA: Record<CircuitType, {
+    name: string;
+    description: string;
+    publicInputsCount: number;
+    publicInputNames: string[];
+}>;
+/**
+ * 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);
+ * ```
+ */
+export declare const VERIFIER_ABI: string[];
+/**
+ * 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]);
+ * ```
+ */
+export declare const RPC_ENDPOINTS: Record<number, string>;
+/**
+ * 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
+ * };
+ * ```
+ */
+export declare const DEFAULT_REQUEST_EXPIRY_MS: number;
+/**
+ * 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');
+ * }
+ * ```
+ */
+export declare const MAX_QR_DATA_SIZE = 2953;
+/**
+ * Coinbase Attestation circuit public input layout (byte offsets).
+ * Defines the byte positions of each field in the flattened public inputs array.
+ *
+ * Public inputs are packed as bytes32 values:
+ * - signal_hash: bytes 0-31
+ * - merkle_root: bytes 32-63
+ * - scope: bytes 64-95
+ * - nullifier: bytes 96-127
+ *
+ * @example
+ * ```typescript
+ * const publicInputs = response.publicInputs;
+ * const signalHash = publicInputs.slice(
+ *   COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT.SIGNAL_HASH_START,
+ *   COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT.SIGNAL_HASH_END + 1
+ * );
+ * ```
+ */
+export declare const COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT: {
+    readonly SIGNAL_HASH_START: 0;
+    readonly SIGNAL_HASH_END: 31;
+    readonly MERKLE_ROOT_START: 32;
+    readonly MERKLE_ROOT_END: 63;
+    readonly SCOPE_START: 64;
+    readonly SCOPE_END: 95;
+    readonly NULLIFIER_START: 96;
+    readonly NULLIFIER_END: 127;
+};
+/**
+ * Coinbase Country Attestation circuit public input layout (byte offsets).
+ * Defines the byte positions of each field in the flattened public inputs array.
+ *
+ * Public inputs are packed as bytes32 values:
+ * - signal_hash: bytes 0-31
+ * - merkle_root: bytes 32-63
+ * - country_list: bytes 64-83 (20 bytes for 10 countries)
+ * - country_list_length: byte 84
+ * - is_included: byte 85
+ * - scope: bytes 86-117
+ * - nullifier: bytes 118-149
+ *
+ * @example
+ * ```typescript
+ * const publicInputs = response.publicInputs;
+ * const countryList = publicInputs.slice(
+ *   COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT.COUNTRY_LIST_START,
+ *   COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT.COUNTRY_LIST_END + 1
+ * );
+ * ```
+ */
+export declare const COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT: {
+    readonly SIGNAL_HASH_START: 0;
+    readonly SIGNAL_HASH_END: 31;
+    readonly MERKLE_ROOT_START: 32;
+    readonly MERKLE_ROOT_END: 63;
+    readonly COUNTRY_LIST_START: 64;
+    readonly COUNTRY_LIST_END: 83;
+    readonly COUNTRY_LIST_LENGTH: 84;
+    readonly IS_INCLUDED: 85;
+    readonly SCOPE_START: 86;
+    readonly SCOPE_END: 117;
+    readonly NULLIFIER_START: 118;
+    readonly NULLIFIER_END: 149;
+};
+/**
+ * V1 NullifierRegistry contract ABI (DEPRECATED).
+ *
+ * This is the legacy nullifier registry interface.
+ * Use ZKPROOFPORT_NULLIFIER_REGISTRY_ABI for new integrations.
+ *
+ * @deprecated Use ZKPROOFPORT_NULLIFIER_REGISTRY_ABI instead. This is the V1 NullifierRegistry ABI.
+ */
+export declare const NULLIFIER_REGISTRY_ABI: string[];
+/**
+ * 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);
+ * ```
+ */
+export declare const ZKPROOFPORT_NULLIFIER_REGISTRY_ABI: string[];

package/dist/deeplink.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Deep Link utilities for ZKProofport SDK
+ */
+import type { ProofRequest, ProofResponse, DeepLinkComponents } from './types';
+/**
+ * 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"
+ * ```
+ */
+export declare function generateRequestId(): string;
+/**
+ * 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"
+ * ```
+ */
+export declare function encodeData(data: object): string;
+/**
+ * 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"
+ * ```
+ */
+export declare function decodeData<T>(encoded: string): T;
+/**
+ * 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..."
+ * ```
+ */
+export declare function buildProofRequestUrl(request: ProofRequest, scheme?: string): string;
+/**
+ * Builds a callback URL with proof response data as query parameters.
+ *
+ * Appends proof response fields to the provided callback URL. For completed proofs,
+ * includes proof data, public inputs, and nullifier. For errors, includes error message.
+ *
+ * @internal Used by the mobile app to construct callback URLs — not intended for SDK consumers.
+ *
+ * @param callbackUrl - Base callback URL (from the original proof request)
+ * @param response - Proof response containing status and optional proof data
+ * @returns Complete callback URL with proof response as query parameters
+ */
+export declare function buildCallbackUrl(callbackUrl: string, response: ProofResponse): string;
+/**
+ * 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"
+ * }
+ * ```
+ */
+export declare function parseProofRequestUrl(url: string): ProofRequest | 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..."
+ * }
+ * ```
+ */
+export declare function parseProofResponseUrl(url: string): ProofResponse | null;
+/**
+ * Parses a deep link URL into its component parts.
+ *
+ * Breaks down a custom scheme URL into scheme, host, path, and query parameters.
+ * Useful for routing and handling different types of deep links.
+ *
+ * @param url - Custom scheme URL to parse (e.g., "zkproofport://proof-request?data=...")
+ * @returns Object containing scheme, host, path, and params, or null if invalid
+ *
+ * @example
+ * ```typescript
+ * const url = "zkproofport://proof-request/verify?data=abc123";
+ * const components = parseDeepLink(url);
+ * // {
+ * //   scheme: "zkproofport",
+ * //   host: "proof-request",
+ * //   path: "/verify",
+ * //   params: { data: "abc123" }
+ * // }
+ * ```
+ */
+export declare function parseDeepLink(url: string): DeepLinkComponents | 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)
+ * ```
+ */
+export declare function isProofportDeepLink(url: string, scheme?: string): boolean;
+/**
+ * @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
+ */
+export declare function validateProofRequest(request: ProofRequest): {
+    valid: boolean;
+    error?: string;
+};

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * ZKProofport SDK
+ *
+ * SDK for requesting ZK proofs from the ZKProofport mobile app
+ *
+ * @example
+ * ```typescript
+ * import { ProofportSDK } from '@zkproofport-app/sdk';
+ *
+ * // Initialize with environment preset
+ * const sdk = ProofportSDK.create('production');
+ *
+ * // 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
+ * const qr = await sdk.generateQRCode(relay.deepLink);
+ *
+ * // Wait for proof
+ * const result = await sdk.waitForProof(relay.requestId);
+ * ```
+ */
+export { ProofportSDK, default } from './ProofportSDK';
+export type { CircuitType, ProofRequestStatus, CoinbaseKycInputs, CoinbaseCountryInputs, CircuitInputs, ProofRequest, ProofResponse, QRCodeOptions, VerifierContract, ProofportConfig, AuthCredentials, AuthToken, RelayProofRequest, RelayProofResult, SDKEnvironment, } from './types';