import { Result, ResultAsync } from 'neverthrow'; import { Address } from 'viem'; import { z } from 'zod'; declare class SdkError extends Error { readonly code: TCode; readonly cause?: unknown; readonly context?: Record; constructor(message: string, options: { code: TCode; cause?: unknown; context?: Record; }); } type ZkkycErrorCode = "VALIDATION_ERROR" | "CONTRACT_READ_ERROR" | "ENCODE_ERROR" | "RECLAIM_INIT_FAILED" | "RECLAIM_SESSION_NOT_FOUND" | "RECLAIM_PROOF_GENERATION_FAILED" | "RECLAIM_PROOF_INVALID" | "RECLAIM_POLLING_ABORTED" | "ZK_PASSPORT_INIT_FAILED" | "ZK_PASSPORT_REJECTED" | "ZK_PASSPORT_VERIFICATION_FAILED" | "ZK_PASSPORT_ABORTED" | "SIMPLE_KYC_SESSION_FAILED" | "SIMPLE_KYC_REDEEM_FAILED" | "LIVENESS_SESSION_FAILED" | "LIVENESS_REDEEM_FAILED" | "BVN_ONBOARD_FAILED" | "BVN_SUBMIT_FAILED" | "BVN_OTP_SEND_FAILED" | "BVN_OTP_CONFIRM_FAILED" | "BVN_ATTESTATION_FAILED" | "BVN_SESSION_EXPIRED" | "PEER_DEPENDENCY_MISSING"; declare class ZkkycError extends SdkError { constructor(message: string, options: { code: ZkkycErrorCode; cause?: unknown; context?: Record; }); } interface ZkkycConfig { readonly reputationManagerAddress: Address; } declare const ZodAnonAadharProofParamsSchema: z.ZodObject<{ nullifierSeed: z.ZodBigInt; nullifier: z.ZodBigInt; timestamp: z.ZodBigInt; signal: z.ZodBigInt; revealArray: z.ZodTuple<[z.ZodBigInt, z.ZodBigInt, z.ZodBigInt, z.ZodBigInt], null>; packedGroth16Proof: z.ZodTuple<[z.ZodBigInt, z.ZodBigInt, z.ZodBigInt, z.ZodBigInt, z.ZodBigInt, z.ZodBigInt, z.ZodBigInt, z.ZodBigInt], null>; }, z.core.$strip>; type AnonAadharProofParams = z.infer; declare const ZodSocialVerifyParamsSchema: z.ZodObject<{ _socialName: z.ZodString; proofs: z.ZodArray; signedClaim: z.ZodObject<{ claim: z.ZodObject<{ identifier: z.ZodString; owner: z.ZodString & z.ZodType<`0x${string}`, string, z.core.$ZodTypeInternals<`0x${string}`, string>>; timestampS: z.ZodNumber; epoch: z.ZodNumber; }, z.core.$strip>; signatures: z.ZodArray; }, z.core.$strip>; }, z.core.$strip>>; }, z.core.$strip>; type SocialVerifyParams = z.infer; declare const ZodSolidityVerifierParametersSchema: z.ZodObject<{ version: z.ZodString; proofVerificationData: z.ZodObject<{ vkeyHash: z.ZodString; proof: z.ZodString; publicInputs: z.ZodArray; }, z.core.$strip>; committedInputs: z.ZodString; serviceConfig: z.ZodObject<{ validityPeriodInSeconds: z.ZodNumber; domain: z.ZodString; scope: z.ZodString; devMode: z.ZodBoolean; }, z.core.$strip>; }, z.core.$strip>; type SolidityVerifierParameters = z.infer; declare const ZodZkPassportRegisterParamsSchema: z.ZodObject<{ params: z.ZodObject<{ version: z.ZodString; proofVerificationData: z.ZodObject<{ vkeyHash: z.ZodString; proof: z.ZodString; publicInputs: z.ZodArray; }, z.core.$strip>; committedInputs: z.ZodString; serviceConfig: z.ZodObject<{ validityPeriodInSeconds: z.ZodNumber; domain: z.ZodString; scope: z.ZodString; devMode: z.ZodBoolean; }, z.core.$strip>; }, z.core.$strip>; isIDCard: z.ZodBoolean; }, z.core.$strip>; type ZkPassportRegisterParams = z.infer; declare const ZodSimpleKycSubmitParamsSchema: z.ZodObject<{ nullifier: z.ZodString; limit: z.ZodBigInt; expiry: z.ZodBigInt; signature: z.ZodString; }, z.core.$strip>; type SimpleKycSubmitParams = z.infer; declare const ZodBvnSubmitParamsSchema: z.ZodObject<{ nullifier: z.ZodString; limit: z.ZodBigInt; expiry: z.ZodBigInt; signature: z.ZodString; }, z.core.$strip>; type BvnSubmitParams = z.infer; declare const ZodLivenessSubmitParamsSchema: z.ZodObject<{ nullifier: z.ZodString; limit: z.ZodBigInt; expiry: z.ZodBigInt; signature: z.ZodString; }, z.core.$strip>; type LivenessSubmitParams = z.infer; interface Zkkyc { prepareSocialVerify(params: SocialVerifyParams): Result<{ to: Address; data: `0x${string}`; }, ZkkycError>; prepareSubmitAnonAadharProof(params: AnonAadharProofParams): Result<{ to: Address; data: `0x${string}`; }, ZkkycError>; prepareZkPassportRegister(params: ZkPassportRegisterParams): Result<{ to: Address; data: `0x${string}`; }, ZkkycError>; prepareSubmitKycAttestation(params: SimpleKycSubmitParams): Result<{ to: Address; data: `0x${string}`; }, ZkkycError>; prepareSubmitBvnAttestation(params: BvnSubmitParams): Result<{ to: Address; data: `0x${string}`; }, ZkkycError>; prepareSubmitLivenessAttestation(params: LivenessSubmitParams): Result<{ to: Address; data: `0x${string}`; }, ZkkycError>; } /** * Creates a Zkkyc client that binds a reputation manager address, * exposing write-preparation methods for social verify, Aadhaar, and ZK Passport. */ declare function createZkkyc(config: ZkkycConfig): Zkkyc; type SocialPlatform = "linkedin" | "github" | "x" | "instagram" | "facebook" | "binance"; /** Maps SocialPlatform to the capitalized name the contract expects for _socialName. */ declare const SOCIAL_PLATFORM_NAMES: Record; /** * Single-object params for `createReclaimFlow`. Merges the app-level config * (appId, appSecret, providerIds) with the per-call options (platform, * walletAddress, callbacks, …) into one argument. */ interface ReclaimFlowParams { readonly appId: string; readonly appSecret: string; readonly providerIds: Record; readonly platform: SocialPlatform; readonly walletAddress: Address; /** Base URL for redirect after Reclaim flow. SDK appends ?sessionId={id}&socialPlatform={Name}. */ readonly redirectUrl?: string; /** Resume polling for an existing session (redirect-back case). */ readonly sessionId?: string; /** Description added to Reclaim context. */ readonly contextDescription?: string; /** Called with status updates during the flow. */ readonly onStatus?: (status: ReclaimStatus) => void; /** AbortSignal to cancel polling. */ readonly signal?: AbortSignal; /** Polling interval in ms. Defaults to 5000. */ readonly pollingIntervalMs?: number; } type ReclaimStatus = { type: "session_created"; sessionId: string; requestUrl: string; } | { type: "polling_started"; sessionId: string; } | { type: "proof_received"; } | { type: "proof_transformed"; }; interface ReclaimProofResult { readonly _socialName: string; readonly proofs: readonly { claimInfo: { provider: string; parameters: string; context: string; }; signedClaim: { claim: { identifier: string; owner: string; timestampS: number; epoch: number; }; signatures: string[]; }; }[]; readonly sessionId: string; } interface ReclaimSession { /** The Reclaim session id (empty until known when resuming). */ readonly sessionId: string; /** URL to display as a QR code or open as a deep link. Empty when resuming an existing session. */ readonly requestUrl: string; /** Triggers the in-app Reclaim flow (browser only) and polls until the proof is ready. Call on user action (e.g. button click). */ readonly start: () => ResultAsync; /** Aborts an in-flight polling loop started by `start`. */ readonly abort: () => void; } /** * Single-object params for `createZkPassportFlow`. Merges app-level config * (domain, name, logo, purpose) with per-call options (walletAddress, onStatus). */ interface ZkPassportFlowParams { /** Domain for ZKPassport initialization (e.g. "app.yourproject.com"). Required — no default is provided to avoid impersonating another app. */ readonly domain: string; /** App name shown in ZKPassport UI. Defaults to "ZKPassport". */ readonly name?: string; /** Logo URL shown in ZKPassport UI. */ readonly logo?: string; /** Purpose text shown in ZKPassport UI. Defaults to "Prove your personhood". */ readonly purpose?: string; readonly walletAddress: Address; /** Called with status updates during the flow. */ readonly onStatus?: (status: ZkPassportStatus) => void; } type ZkPassportStatus = { type: "request_created"; url: string; } | { type: "request_received"; } | { type: "generating_proof"; } | { type: "proof_generated"; } | { type: "result_received"; } | { type: "rejected"; }; interface ZkPassportProofResult { readonly params: SolidityVerifierParameters; readonly isIDCard: boolean; } interface ZkPassportSession { /** URL to display as QR code or open as deeplink. */ readonly url: string; /** Resolves when the full flow completes (proof verified). */ readonly result: ResultAsync; /** Aborts the flow. The result promise will reject with ZK_PASSPORT_ABORTED. */ readonly abort: () => void; } /** * Params for `createSimpleKycFlow`. The app opens the hosted simple-kyc wizard, * which runs onboard → passport → liveness → face match/dedup and, on approval, * redirects back to `redirectUrl` with `?code=&state=`. The app * then calls `resumeSimpleKycFlow` to redeem the code for the EIP-712 attestation. */ interface SimpleKycFlowParams { /** * Base URL exposing the browser-facing `/v1/widget/public-sessions` and * `/v1/widget/attestation` endpoints — the `kyc-proxy` in a client-only setup * (e.g. http://localhost:8787). The proxy holds the X-API-Key and forwards to * simple-kyc's key-gated endpoints. */ readonly baseUrl: string; /** The user's EVM wallet — bound into the attestation and credited on-chain. */ readonly walletAddress: Address; /** Tenant slug (one per consuming contract), e.g. "p2p-reputation". */ readonly tenant: string; /** Return URL — pass `${window.location.origin}` so each app self-routes. */ readonly redirectUrl: string; /** * ISO-2 country code (e.g. "IN"). Required — the embedded wizard skips the * country step, so the app must prebind it. Must be one of simple-kyc's * supported markets (IN, NG, BR, MX, CO, AR, VE, ID). */ readonly country: string; /** Opaque state round-tripped back to the app (CSRF/nonce + page to restore). */ readonly state?: string; /** Status callback. */ readonly onStatus?: (status: SimpleKycStatus) => void; } type SimpleKycStatus = { type: "session_created"; widgetUrl: string; } | { type: "redirecting"; widgetUrl: string; }; interface SimpleKycSession { /** The hosted wizard URL to navigate to. */ readonly widgetUrl: string; /** Convenience: navigate the browser to the wizard (no-op outside the browser). */ readonly redirect: () => void; } /** The on-chain-ready attestation, shaped for `prepareSubmitKycAttestation`. */ interface SimpleKycAttestation { readonly nullifier: `0x${string}`; readonly limit: bigint; readonly expiry: bigint; readonly signature: `0x${string}`; /** The opaque unique-human handle (no PII), for app-side bookkeeping. */ readonly identityHash?: string; } /** * Params for `createLivenessFlow`. The app opens the hosted liveness wizard, * which runs onboard → active liveness challenge → face embed → 1:N dedup and, * on approval, redirects back to `redirectUrl` with `?code=&state=`. * The app then calls `resumeLivenessFlow` to redeem the code for the EIP-712 * attestation. * * Identical to `SimpleKycFlowParams` minus `country`: liveness reads no * document, so there is no issuing market to prebind. */ interface LivenessFlowParams { /** * Base URL exposing the browser-facing `/v1/widget/public-sessions` and * `/v1/widget/attestation` endpoints — the liveness proxy in a client-only * setup (e.g. https://liveness-proxy.p2p.cool). The proxy holds the * X-API-Key and forwards to the liveness service's key-gated endpoints. * This is **not** the same host as the passport (`simple-kyc`) proxy. */ readonly baseUrl: string; /** The user's EVM wallet — bound into the attestation and credited on-chain. */ readonly walletAddress: Address; /** Tenant slug (one per consuming contract), e.g. "p2p-reputation-liveness". */ readonly tenant: string; /** Return URL — pass `${window.location.origin}` so each app self-routes. */ readonly redirectUrl: string; /** Opaque state round-tripped back to the app (CSRF/nonce + page to restore). */ readonly state?: string; /** Status callback. */ readonly onStatus?: (status: LivenessStatus) => void; } type LivenessStatus = { type: "session_created"; widgetUrl: string; } | { type: "redirecting"; widgetUrl: string; }; interface LivenessSession { /** The hosted wizard URL to navigate to. */ readonly widgetUrl: string; /** Convenience: navigate the browser to the wizard (no-op outside the browser). */ readonly redirect: () => void; } /** The on-chain-ready attestation, shaped for `prepareSubmitLivenessAttestation`. */ interface LivenessAttestation { readonly nullifier: `0x${string}`; readonly limit: bigint; readonly expiry: bigint; readonly signature: `0x${string}`; /** The opaque unique-human handle (no PII), for app-side bookkeeping. */ readonly identityHash?: string; } /** OTP delivery channels the BVN backend exposes. `alternate_phone` needs a number. */ type BvnOtpMethod = "email" | "phone" | "phone_1" | "alternate_phone"; /** BVN identity scope requested during onboard. */ type BvnScope = "identity" | "bank_accounts"; /** * Shared config for every BVN step. `baseUrl` points at the backend proxy — the * only party holding the Mono secret + the EIP-712 attestor key — using the * `{ ok, data }` envelope. */ interface BvnFlowConfig { /** Backend proxy base URL (e.g. https://ngn-bvn-verify-production.up.railway.app). */ readonly baseUrl: string; /** Tenant slug registered on the backend, mapping to one on-chain contract. */ readonly tenant: string; } /** An active BVN backend session. Carry this between steps. */ interface BvnSession { readonly sessionId: number; readonly sessionToken: string; } /** An available OTP delivery method returned after submitting the BVN. */ interface BvnMethod { readonly method: string; readonly hint?: string; } /** The confirm-OTP decision. `reject` may carry a reason (e.g. "bvn_reused"). */ interface BvnDecision { readonly decision: "approve" | "reject"; readonly reason?: string; } /** The on-chain-ready attestation, shaped for `prepareSubmitBvnAttestation`. */ interface BvnAttestation { readonly nullifier: `0x${string}`; readonly limit: bigint; readonly expiry: bigint; readonly signature: `0x${string}`; /** The wallet the attestation is bound to. */ readonly wallet?: string; } /** Params for `bvnOnboard`. */ interface BvnOnboardParams { /** The user's EVM wallet — bound into the attestation and credited on-chain. */ readonly walletAddress: Address; /** Identity scope. Defaults to "identity". */ readonly scope?: BvnScope; } /** Params for `bvnSendOtp`. */ interface BvnSendOtpParams { readonly method: BvnOtpMethod; /** Required only when `method` is "alternate_phone". */ readonly phoneNumber?: string; } /** The full BVN flow bound to a config — mirrors the `Zkkyc` client shape. */ interface BvnFlow { /** Step 1 — start a session bound to the wallet + tenant. */ onboard(params: BvnOnboardParams): ResultAsync; /** Step 2 — submit the 11-digit BVN, get available OTP methods. */ submitBvn(session: BvnSession, bvn: string): ResultAsync; /** Step 3 — request an OTP over the chosen channel. */ sendOtp(session: BvnSession, params: BvnSendOtpParams): ResultAsync; /** Step 4 — confirm the OTP; returns approve/reject (never any PII). */ confirmOtp(session: BvnSession, otp: string): ResultAsync; /** Step 5 — mint the signed EIP-712 attestation for an approved session. */ getAttestation(session: BvnSession): ResultAsync; /** Optional — the address the tenant contract must trust as its signer. */ getAttestor(): ResultAsync<{ address: string; }, ZkkycError>; } /** * Drives the BVN (Nigerian Bank Verification Number) on-chain attestation flow. * * The SDK talks only to a backend proxy — the single party that holds the Mono * secret + the EIP-712 attestor key. Every response uses the `{ ok, data }` * envelope. On approval, `getAttestation` returns a signed attestation shaped * for `zkkyc.prepareSubmitBvnAttestation`, which the app submits on-chain from * the same wallet. * * Flow: onboard → submitBvn → sendOtp → confirmOtp → getAttestation. */ declare function createBvnFlow(config: BvnFlowConfig): BvnFlow; /** Default Reclaim provider IDs for each social platform. */ declare const DEFAULT_RECLAIM_PROVIDER_IDS: Record; /** ZK Passport app store links. */ declare const ZK_PASSPORT_APP_LINKS: { readonly IOS: "https://apps.apple.com/us/app/zkpassport/id6477371975"; readonly ANDROID: "https://play.google.com/store/apps/details?id=app.zkpassport.zkpassport"; }; /** Reclaim Protocol app store links. */ declare const RECLAIM_APP_LINKS: { readonly ANDROID: "https://play.google.com/store/apps/details?id=org.reclaimprotocol.app"; }; /** Default tenant slug for the P2P reputation contract on the simple-kyc service. */ declare const SIMPLE_KYC_DEFAULT_TENANT = "p2p-reputation"; /** * Default tenant slug for the P2P reputation contract on the **liveness** * service. Distinct registry from simple-kyc's — the two services keep separate * databases, so a slug existing on one says nothing about the other. */ declare const LIVENESS_DEFAULT_TENANT = "p2p-reputation-liveness"; /** OTP delivery channels the BVN backend (Mono) exposes. */ declare const BVN_OTP_METHODS: readonly ["email", "phone", "phone_1", "alternate_phone"]; /** * Starts the hosted liveness wizard flow. Creates a browser-initiable widget * session (no API key in the browser — `baseUrl` points at the liveness proxy, * which injects the key and whose tenant allowlist validates the redirect_uri), * then returns the wizard URL to navigate to. * * The wizard runs onboard → active liveness challenge → face embed → 1:N dedup * and, on approval, redirects back to `redirectUrl` with `?code=&state=`. * Call `resumeLivenessFlow({ baseUrl, code })` on return to fetch the attestation. * * Deliberately separate from `createSimpleKycFlow`: the liveness verifier is a * different service with its own database, its own attestor key and its own * EIP-712 domain (`LivenessVerifier`, vs the passport wizard's `KycVerifier`). * Pointing one flow at the other's base URL yields a signature the contract * rejects. The one API-shape difference is that liveness takes **no `country`** — * it reads no document, so there is no issuing market to prebind. */ declare function createLivenessFlow(params: LivenessFlowParams): ResultAsync; /** * Redeems the one-time `code` from the wizard's redirect for the EIP-712 * attestation. The result feeds straight into `zkkyc.prepareSubmitLivenessAttestation`. * The endpoint returns only the (non-PII, self-verifying) attestation. */ declare function resumeLivenessFlow(args: { baseUrl: string; code: string; }): ResultAsync; /** * Initializes a Reclaim social verification flow and returns a session. `init()` * runs eagerly here, so call this on page load; the returned session's `start()` * triggers the in-app flow and polls for the proof, so call that on user action. */ declare function createReclaimFlow(params: ReclaimFlowParams): ResultAsync; /** * Starts the hosted simple-kyc wizard flow. Creates a browser-initiable widget * session (no API key in the browser — `baseUrl` points at the kyc-proxy, which * injects the key and whose tenant allowlist validates the redirect_uri), then * returns the wizard URL to navigate to. * * The wizard runs passport → liveness → face match/dedup and, on approval, * redirects back to `redirectUrl` with `?code=&state=`. Call * `resumeSimpleKycFlow({ baseUrl, code })` on return to fetch the attestation. */ declare function createSimpleKycFlow(params: SimpleKycFlowParams): ResultAsync; /** * Redeems the one-time `kyc_code` from the wizard's redirect for the EIP-712 * attestation. The result feeds straight into `zkkyc.prepareSubmitKycAttestation`. * The endpoint returns only the (non-PII, self-verifying) attestation. */ declare function resumeSimpleKycFlow(args: { baseUrl: string; code: string; }): ResultAsync; /** Initializes a ZK Passport verification flow and returns a session. */ declare function createZkPassportFlow(params: ZkPassportFlowParams): ResultAsync; export { type AnonAadharProofParams, BVN_OTP_METHODS, type BvnAttestation, type BvnDecision, type BvnFlow, type BvnFlowConfig, type BvnMethod, type BvnOnboardParams, type BvnOtpMethod, type BvnScope, type BvnSendOtpParams, type BvnSession, type BvnSubmitParams, DEFAULT_RECLAIM_PROVIDER_IDS, LIVENESS_DEFAULT_TENANT, type LivenessAttestation, type LivenessFlowParams, type LivenessSession, type LivenessStatus, type LivenessSubmitParams, RECLAIM_APP_LINKS, type ReclaimFlowParams, type ReclaimProofResult, type ReclaimSession, type ReclaimStatus, SIMPLE_KYC_DEFAULT_TENANT, SOCIAL_PLATFORM_NAMES, type SimpleKycAttestation, type SimpleKycFlowParams, type SimpleKycSession, type SimpleKycStatus, type SimpleKycSubmitParams, type SocialPlatform, type SocialVerifyParams, ZK_PASSPORT_APP_LINKS, type ZkPassportFlowParams, type ZkPassportProofResult, type ZkPassportRegisterParams, type ZkPassportSession, type ZkPassportStatus, type Zkkyc, type ZkkycConfig, ZkkycError, type ZkkycErrorCode, createBvnFlow, createLivenessFlow, createReclaimFlow, createSimpleKycFlow, createZkPassportFlow, createZkkyc, resumeLivenessFlow, resumeSimpleKycFlow };