@zkp2p/sdk 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,435 @@
+import { D as DepositWithRelations, I as IntentEntity, V as ValidatePayeeDetailsRequest, a as ValidatePayeeDetailsResponse, P as PostDepositDetailsRequest, b as PostDepositDetailsResponse, G as GetPayeeDetailsRequest, c as GetPayeeDetailsResponse, d as GetTakerTierRequest, e as GetTakerTierResponse, f as PaymentMethodCatalog, T as TxOverrides } from './Zkp2pClient-CODjD_Kf.js';
+export { A as ActionCallback, t as ApiDeposit, H as ApiIntentStatus, k as CancelIntentParams, i as CreateDepositConversionRate, C as CreateDepositParams, aq as Currency, ay as CurrencyData, ax as CurrencyType, aI as Deposit, aK as DepositCurrency, a1 as DepositIntentStatistics, w as DepositStatus, u as DepositVerifier, v as DepositVerifierCurrency, $ as DepositVerifierData, aH as DepositView, q as FiatResponse, F as FulfillIntentParams, z as GetDepositByIdRequest, B as GetDepositByIdResponse, O as GetIntentByHashRequest, U as GetIntentByHashResponse, L as GetIntentsByDepositRequest, M as GetIntentsByDepositResponse, x as GetOwnerDepositsRequest, y as GetOwnerDepositsResponse, J as GetOwnerIntentsRequest, K as GetOwnerIntentsResponse, a7 as IndexerClient, ak as IndexerDeploymentEnv, ab as IndexerDeposit, ag as IndexerDepositFilter, aj as IndexerDepositOrderDirection, ai as IndexerDepositOrderField, ah as IndexerDepositPagination, ad as IndexerDepositPaymentMethod, a9 as IndexerDepositService, an as IndexerFulfillmentAndPaymentResponse, al as IndexerFulfillmentRecord, ac as IndexerIntentFulfilled, af as IndexerIntentStatus, ae as IndexerMethodCurrency, am as IndexerPaymentVerifiedRecord, E as Intent, aL as IntentView, N as NearbyQuote, s as NearbySuggestions, Z as OfframpClient, _ as OnchainCurrency, aM as OnchainIntent, a0 as OrderStats, ao as PAYMENT_PLATFORMS, aJ as PaymentMethodData, ap as PaymentPlatformType, a5 as PlatformLimit, a6 as PlatformRiskLevel, p as QuoteFeesResponse, o as QuoteIntentResponse, Q as QuoteRequest, l as QuoteResponse, m as QuoteResponseObject, n as QuoteSingleResponse, R as Range, X as RegisterPayeeDetailsRequest, Y as RegisterPayeeDetailsResponse, j as ReleaseFundsToPayerParams, aC as RuntimeEnv, S as SignalIntentParams, a2 as TakerTier, a4 as TakerTierLevel, a3 as TakerTierStats, h as TimeoutConfig, r as TokenResponse, W as WithdrawDepositParams, Z as Zkp2pClient, g as Zkp2pClientOptions, ar as currencyInfo, a8 as defaultIndexerEndpoint, aF as enrichPvDepositView, aG as enrichPvIntentView, aa as fetchIndexerFulfillmentAndPayment, az as getContracts, au as getCurrencyCodeFromHash, at as getCurrencyInfoFromCountryCode, as as getCurrencyInfoFromHash, aB as getGatingServiceAddress, aA as getPaymentMethodsCatalog, av as isSupportedCurrencyHash, aw as mapConversionRatesToOnchainMinRate, aD as parseDepositView, aE as parseIntentView } from './Zkp2pClient-CODjD_Kf.js';
+import { Abi } from 'abitype';
+import { Hex, WalletClient, Hash } from 'viem';
+
+interface EscrowRange {
+    min: bigint;
+    max: bigint;
+}
+interface EscrowDeposit {
+    depositor: string;
+    token: string;
+    depositAmount: bigint;
+    intentAmountRange: EscrowRange;
+    acceptingIntents: boolean;
+    remainingDepositAmount: bigint;
+    outstandingIntentAmount: bigint;
+    intentHashes: string[];
+}
+interface EscrowCurrency {
+    code: string;
+    conversionRate: bigint;
+}
+interface EscrowDepositVerifierData {
+    intentGatingService: string;
+    payeeDetails: string;
+    data: string;
+    paymentData?: {
+        [key: string]: string;
+    };
+    paymentMethod?: string;
+}
+interface EscrowVerifierDataView {
+    verifier: string;
+    verificationData: EscrowDepositVerifierData;
+    currencies: EscrowCurrency[];
+}
+interface EscrowDepositView {
+    depositId: bigint;
+    deposit: EscrowDeposit;
+    verifiers: EscrowVerifierDataView[];
+}
+interface EscrowIntent {
+    owner: string;
+    to: string;
+    depositId: bigint;
+    amount: bigint;
+    timestamp: bigint;
+    paymentVerifier: string;
+    fiatCurrency: string;
+    conversionRate: bigint;
+    paymentData?: {
+        [key: string]: string;
+    };
+    paymentMethod?: string;
+}
+interface EscrowIntentView {
+    intentHash: string;
+    intent: EscrowIntent;
+    deposit: EscrowDepositView;
+}
+
+declare function createCompositeDepositId(escrowAddress: string, depositId: string | bigint): string;
+declare function convertIndexerDepositToEscrowView(deposit: DepositWithRelations, _chainId: number, _escrowAddress: string): EscrowDepositView;
+declare function convertDepositsForLiquidity(deposits: DepositWithRelations[], chainId: number, escrowAddress: string): EscrowDepositView[];
+declare function convertIndexerIntentsToEscrowViews(intents: IntentEntity[], depositViewsById: Map<string, EscrowDepositView>): EscrowIntentView[];
+
+declare function apiPostDepositDetails(req: PostDepositDetailsRequest, baseApiUrl: string, timeoutMs?: number): Promise<PostDepositDetailsResponse>;
+declare function apiGetPayeeDetails(req: GetPayeeDetailsRequest, apiKey: string, baseApiUrl: string, authToken?: string, timeoutMs?: number): Promise<GetPayeeDetailsResponse>;
+declare function apiValidatePayeeDetails(req: ValidatePayeeDetailsRequest, baseApiUrl: string, timeoutMs?: number): Promise<ValidatePayeeDetailsResponse>;
+/**
+ * Get taker tier information for a specific address.
+ */
+declare function apiGetTakerTier(req: GetTakerTierRequest, apiKey: string | undefined, baseApiUrl: string, authToken?: string, timeoutMs?: number): Promise<GetTakerTierResponse>;
+
+/**
+ * SDK Constants
+ *
+ * This module exports all public constants for the SDK including:
+ * - Payment platforms (Wise, Venmo, Revolut, etc.)
+ * - Currencies (USD, EUR, GBP, etc.)
+ * - Chain IDs and network configuration
+ * - Token metadata
+ *
+ * @module constants
+ */
+
+/**
+ * Supported blockchain chain IDs.
+ *
+ * @example
+ * ```typescript
+ * import { SUPPORTED_CHAIN_IDS } from '@zkp2p/client-sdk';
+ *
+ * const client = new Zkp2pClient({
+ *   chainId: SUPPORTED_CHAIN_IDS.BASE_MAINNET,
+ *   // ...
+ * });
+ * ```
+ */
+declare const SUPPORTED_CHAIN_IDS: {
+    /** Base mainnet (8453) */
+    readonly BASE_MAINNET: 8453;
+    /** Base Sepolia testnet (84532) */
+    readonly BASE_SEPOLIA: 84532;
+    /** Scroll mainnet (534352) */
+    readonly SCROLL_MAINNET: 534352;
+    /** Local Hardhat network (31337) */
+    readonly HARDHAT: 31337;
+};
+/**
+ * Union type of supported chain IDs.
+ */
+type SupportedChainId = typeof SUPPORTED_CHAIN_IDS[keyof typeof SUPPORTED_CHAIN_IDS];
+/**
+ * Metadata for each supported payment platform.
+ *
+ * Includes display names, logos, and the number of proofs required
+ * for payment verification.
+ */
+declare const PLATFORM_METADATA: {
+    readonly venmo: {
+        readonly name: "Venmo";
+        readonly displayName: "Venmo";
+        readonly logo: "💵";
+        readonly requiredProofs: 1;
+    };
+    readonly revolut: {
+        readonly name: "Revolut";
+        readonly displayName: "Revolut";
+        readonly logo: "💳";
+        readonly requiredProofs: 1;
+    };
+    readonly cashapp: {
+        readonly name: "CashApp";
+        readonly displayName: "Cash App";
+        readonly logo: "💸";
+        readonly requiredProofs: 1;
+    };
+    readonly wise: {
+        readonly name: "Wise";
+        readonly displayName: "Wise";
+        readonly logo: "🌍";
+        readonly requiredProofs: 2;
+    };
+    readonly mercadopago: {
+        readonly name: "MercadoPago";
+        readonly displayName: "Mercado Pago";
+        readonly logo: "💰";
+        readonly requiredProofs: 1;
+    };
+    readonly zelle: {
+        readonly name: "Zelle";
+        readonly displayName: "Zelle";
+        readonly logo: "💲";
+        readonly requiredProofs: 1;
+    };
+    readonly paypal: {
+        readonly name: "PayPal";
+        readonly displayName: "PayPal";
+        readonly logo: "💙";
+        readonly requiredProofs: 1;
+    };
+    readonly monzo: {
+        readonly name: "Monzo";
+        readonly displayName: "Monzo";
+        readonly logo: "🏦";
+        readonly requiredProofs: 1;
+    };
+};
+/**
+ * Token metadata for supported tokens.
+ */
+declare const TOKEN_METADATA: {
+    readonly USDC: {
+        readonly symbol: "USDC";
+        readonly decimals: 6;
+        readonly name: "USD Coin";
+    };
+};
+
+/**
+ * Payment method resolution utilities.
+ *
+ * These functions convert between human-readable payment platform names
+ * (e.g., 'wise', 'revolut') and their on-chain bytes32 hashes.
+ *
+ * @module paymentResolution
+ */
+
+type NetworkKey = 'base' | 'base_sepolia';
+type RuntimeEnv = 'production' | 'staging';
+/**
+ * Resolves a payment method hash from a human-readable name.
+ *
+ * First attempts to look up the hash from contracts-v2 payment method maps.
+ * Falls back to keccak256(name) when maps are unavailable.
+ *
+ * **Warning**: The fallback may not match on-chain mappings. Prefer using
+ * `resolvePaymentMethodHashFromCatalog` with an explicit catalog.
+ *
+ * @param nameOrBytes - Payment method name ('wise') or existing bytes32 hash
+ * @param opts.env - Runtime environment ('production' | 'staging')
+ * @param opts.network - Network key ('base' | 'base_sepolia')
+ * @returns bytes32 payment method hash
+ *
+ * @example
+ * ```typescript
+ * const hash = resolvePaymentMethodHash('wise', { env: 'production' });
+ * ```
+ */
+declare function resolvePaymentMethodHash(nameOrBytes: string, opts?: {
+    env?: RuntimeEnv;
+    network?: NetworkKey;
+}): `0x${string}`;
+/**
+ * Encodes a fiat currency code into bytes32 format (ASCII right-padded).
+ *
+ * If the input is already a hex string (0x-prefixed), it's normalized to bytes32.
+ * Otherwise, the currency code is converted to uppercase ASCII bytes32.
+ *
+ * @param codeOrBytes - Currency code ('USD') or existing bytes32 hash
+ * @returns bytes32 encoded currency
+ *
+ * @example
+ * ```typescript
+ * const bytes = resolveFiatCurrencyBytes32('USD');
+ * // Returns: 0x5553440000000000000000000000000000000000000000000000000000000000
+ * ```
+ */
+declare function resolveFiatCurrencyBytes32(codeOrBytes: string): `0x${string}`;
+/**
+ * Resolves a payment method hash from a provided catalog.
+ *
+ * This is the recommended method for resolving payment methods as it uses
+ * the exact catalog from `getPaymentMethodsCatalog()`, ensuring consistency
+ * with on-chain registrations.
+ *
+ * @param processorName - Payment platform name ('wise', 'revolut', etc.)
+ * @param catalog - Payment method catalog from `getPaymentMethodsCatalog()`
+ * @returns bytes32 payment method hash
+ * @throws Error with available processors if not found
+ *
+ * @example
+ * ```typescript
+ * import { getPaymentMethodsCatalog, resolvePaymentMethodHashFromCatalog } from '@zkp2p/client-sdk';
+ *
+ * const catalog = getPaymentMethodsCatalog(8453, 'production');
+ * const hash = resolvePaymentMethodHashFromCatalog('wise', catalog);
+ * ```
+ */
+declare function resolvePaymentMethodHashFromCatalog(processorName: string, catalog: Record<string, {
+    paymentMethodHash: `0x${string}`;
+    currencies?: `0x${string}`[];
+}>): `0x${string}`;
+/**
+ * Reverse-lookup: converts a payment method hash back to its name.
+ *
+ * @param hash - The payment method hash (bytes32)
+ * @param catalog - Payment method catalog from `getPaymentMethodsCatalog()`
+ * @returns Payment platform name (e.g., 'wise') or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const name = resolvePaymentMethodNameFromHash('0x...', catalog);
+ * console.log(name); // "wise"
+ * ```
+ */
+declare function resolvePaymentMethodNameFromHash(hash: string, catalog: PaymentMethodCatalog): string | undefined;
+
+/**
+ * Ensure a value is 32 bytes hex (0x + 64 nibbles). If ascii, keccak256 by default when hash=true.
+ */
+declare function ensureBytes32(value: string, { hashIfAscii }?: {
+    hashIfAscii?: boolean;
+}): `0x${string}`;
+/**
+ * Encode ASCII (<=32 chars) left-aligned, right-padded with zeros to 32 bytes.
+ */
+declare function asciiToBytes32(value: string): `0x${string}`;
+
+/**
+ * Base Builder Code for ZKP2P app (registered with Base).
+ * This is ALWAYS included as the last code in attribution and cannot be overridden.
+ */
+declare const BASE_BUILDER_CODE = "bc_nbn6qkni";
+/**
+ * ZKP2P iOS app referrer code - pass via txOverrides.referrer
+ */
+declare const ZKP2P_IOS_REFERRER = "zkp2p-ios";
+/**
+ * ZKP2P Android app referrer code - pass via txOverrides.referrer
+ */
+declare const ZKP2P_ANDROID_REFERRER = "zkp2p-android";
+/**
+ * Generate the ERC-8021 attribution data suffix for transactions.
+ *
+ * The Base builder code (bc_nbn6qkni) is ALWAYS appended last and cannot be overridden.
+ * Custom referrer codes are prepended before the base builder code.
+ *
+ * @param referrer - Optional referrer code(s) to prepend before the base builder code.
+ *                   Can be a single string or array of strings.
+ *                   These will appear BEFORE the base builder code in the attribution.
+ * @returns Hex-encoded attribution suffix
+ */
+declare function getAttributionDataSuffix(referrer?: string | string[]): Hex;
+/**
+ * Append attribution data suffix to existing calldata
+ *
+ * @param calldata - Original transaction calldata
+ * @param referrer - Optional referrer code(s) to prepend before the base builder code
+ * @returns Calldata with attribution suffix appended
+ */
+declare function appendAttributionToCalldata(calldata: Hex, referrer?: string | string[]): Hex;
+/**
+ * Request parameters for sendTransactionWithAttribution
+ */
+interface AttributionRequest {
+    address: `0x${string}`;
+    abi: Abi;
+    functionName: string;
+    args?: readonly unknown[];
+    value?: bigint;
+}
+type OverrideFields = Omit<TxOverrides, 'referrer'>;
+/**
+ * Send a contract transaction with ERC-8021 attribution.
+ *
+ * 1. Encodes the function call data using encodeFunctionData
+ * 2. Appends the attribution suffix
+ * 3. Sends via sendTransaction (wallet estimates gas automatically)
+ *
+ * @param walletClient - The viem wallet client
+ * @param request - The request with abi, functionName, args, address, value
+ * @param referrer - Optional referrer code(s) from txOverrides.referrer
+ * @param overrides - Optional transaction overrides (gas, nonce, etc.)
+ * @returns Transaction hash
+ */
+declare function sendTransactionWithAttribution(walletClient: WalletClient, request: AttributionRequest, referrer?: string | string[], overrides?: OverrideFields): Promise<Hash>;
+
+type LogLevel = 'error' | 'info' | 'debug';
+declare function setLogLevel(level: LogLevel): void;
+declare const logger: {
+    debug: (...args: any[]) => void;
+    info: (...args: any[]) => void;
+    warn: (...args: any[]) => void;
+    error: (...args: any[]) => void;
+};
+
+/**
+ * Error codes for categorizing SDK errors.
+ */
+declare enum ErrorCode {
+    /** Input validation failed */
+    VALIDATION = "VALIDATION",
+    /** Network/RPC error */
+    NETWORK = "NETWORK",
+    /** API request failed */
+    API = "API",
+    /** Smart contract error */
+    CONTRACT = "CONTRACT",
+    /** Unknown/uncategorized error */
+    UNKNOWN = "UNKNOWN"
+}
+/**
+ * Base error class for all SDK errors.
+ *
+ * All SDK-specific errors extend this class, making it easy to catch
+ * and handle SDK errors uniformly.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.createDeposit(...);
+ * } catch (error) {
+ *   if (error instanceof ZKP2PError) {
+ *     console.log('SDK Error:', error.code, error.message);
+ *     console.log('Details:', error.details);
+ *   }
+ * }
+ * ```
+ */
+declare class ZKP2PError extends Error {
+    /** Error category code */
+    code: ErrorCode;
+    /** Additional error details (varies by error type) */
+    details?: unknown;
+    /** Field that caused the error (for validation errors) */
+    field?: string;
+    constructor(message: string, code?: ErrorCode, details?: unknown, field?: string);
+}
+/**
+ * Thrown when input validation fails.
+ *
+ * @example
+ * ```typescript
+ * throw new ValidationError('Amount must be positive', 'amount');
+ * ```
+ */
+declare class ValidationError extends ZKP2PError {
+    constructor(message: string, field?: string, details?: unknown);
+}
+/**
+ * Thrown when a network or RPC request fails.
+ */
+declare class NetworkError extends ZKP2PError {
+    constructor(message: string, details?: unknown);
+}
+/**
+ * Thrown when an API request fails.
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof APIError) {
+ *     console.log('HTTP Status:', error.status);
+ *   }
+ * }
+ * ```
+ */
+declare class APIError extends ZKP2PError {
+    /** HTTP status code (if applicable) */
+    status?: number;
+    constructor(message: string, status?: number, details?: unknown);
+}
+/**
+ * Thrown when a smart contract call fails.
+ *
+ * Check the `details` property for the underlying viem error.
+ */
+declare class ContractError extends ZKP2PError {
+    constructor(message: string, details?: unknown);
+}
+
+export { APIError, BASE_BUILDER_CODE, ContractError, ErrorCode, type EscrowDepositView, type EscrowIntentView, GetPayeeDetailsRequest, GetPayeeDetailsResponse, GetTakerTierRequest, GetTakerTierResponse, DepositWithRelations as IndexerDepositWithRelations, IntentEntity as IndexerIntent, type LogLevel, NetworkError, PLATFORM_METADATA, PaymentMethodCatalog, PostDepositDetailsRequest, PostDepositDetailsResponse, SUPPORTED_CHAIN_IDS, type SupportedChainId, TOKEN_METADATA, TxOverrides, ValidatePayeeDetailsRequest, ValidatePayeeDetailsResponse, ValidationError, ZKP2PError, ZKP2P_ANDROID_REFERRER, ZKP2P_IOS_REFERRER, apiGetPayeeDetails, apiGetTakerTier, apiPostDepositDetails, apiValidatePayeeDetails, appendAttributionToCalldata, asciiToBytes32, convertDepositsForLiquidity, convertIndexerDepositToEscrowView, convertIndexerIntentsToEscrowViews, createCompositeDepositId, ensureBytes32, getAttributionDataSuffix, logger, resolveFiatCurrencyBytes32, resolvePaymentMethodHash, resolvePaymentMethodHashFromCatalog, resolvePaymentMethodNameFromHash, sendTransactionWithAttribution, setLogLevel };