@provex/utils 1.0.16 → 1.2.4

package/dist/payment.d.ts

@@ -0,0 +1,481 @@
+/**
+ * @fileoverview Payment provider definitions and utilities for Provex protocol.
+ *
+ * This module is the single source of truth for all supported payment methods,
+ * including their contract IDs, icons, risk levels, and tier requirements.
+ *
+ * @remarks
+ * **Supported Payment Providers:**
+ * - US: Venmo, Zelle (Chase/BoFA/Citi), CashApp, PayPal, Chime
+ * - International: Revolut, Wise, Monzo, N26, Alipay, MercadoPago, RBC
+ *
+ * **Provider Identification:**
+ * - V2: Per-provider verifier contract addresses
+ * - V3: keccak256(providerKey) as bytes32 payment method ID
+ *
+ * **Risk Levels (Base chain only):**
+ * - Low risk (Revolut, Wise, Monzo, MercadoPago): 5x cap multiplier, no cooldown
+ * - Medium risk (Zelle): 1.5x cap multiplier, cooldown applies
+ * - High risk (Venmo, CashApp): 1x cap multiplier, cooldown applies
+ * - Highest risk (PayPal): 0.75x cap multiplier, requires Peer Plus tier
+ *
+ * @see {@link reputation} for tier system
+ * @see {@link currencies} for supported currencies per provider
+ */
+import { type Hex } from "viem";
+/** Returns true if a provider should be hidden from user-facing flows. */
+export declare function isProviderDisabled(key: string, configDisabled?: boolean): boolean;
+import type { TokenInfo } from "./tokens.js";
+import type { ConversionRateInfo, ProviderRates } from "./conversionRates.js";
+import { type Currency } from "./currencies.js";
+import { ChainId } from "./chain.js";
+/**
+ * Generate a contract ID (keccak256 hash) for a provider key.
+ * Used to identify payment methods on-chain (e.g., 'venmo' → bytes32).
+ *
+ * @param key - The provider key (e.g., 'venmo', 'zelle')
+ * @returns The contract ID as a hex string
+ */
+export declare const providerKeyToContractId: (key: string) => `0x${string}`;
+/**
+ * Compute the payeeDetailsHash for a plaintext payment identifier.
+ * This is the on-chain hash stored in deposit verifier records.
+ *
+ * The depositor passes this hash when creating a deposit. Buyers look it up
+ * via an API (or custom storage) to get the plaintext back.
+ *
+ * Uses `keccak256(utf8bytes(identifier))` — matches the contract and API convention.
+ *
+ * @param identifier - Plaintext payment ID (e.g., '@myvenmo', 'user@email.com', '+1234567890')
+ * @returns The payeeDetailsHash as a hex string
+ *
+ * @example
+ * ```ts
+ * import { computePayeeDetailsHash } from '@provex/utils/payment'
+ *
+ * const hash = computePayeeDetailsHash('@myvenmo')
+ * // Use in createDeposit({ paymentMethodData: [{ payeeDetails: hash, ... }] })
+ * ```
+ */
+export declare const computePayeeDetailsHash: (identifier: string) => Hex;
+/**
+ * Payment providers, including manual
+ */
+export declare const providers: {
+    readonly VENMO: "venmo";
+    readonly ZELLE: "zelle";
+    readonly CASHAPP: "cashapp";
+    readonly REVOLUT: "revolut";
+    readonly WISE: "wise";
+    readonly MERCADOPAGO: "mercadopago";
+    readonly MANUAL: "manual";
+    readonly PAYPAL: "paypal";
+    readonly MONZO: "monzo";
+    readonly N26: "n26";
+    readonly ALIPAY: "alipay";
+    readonly CHIME: "chime";
+    readonly ROYALBANKCANADA: "royalbankcanada";
+    readonly IDFC: "idfc";
+};
+export type ProviderKey = typeof providers[keyof typeof providers];
+/** Distinct keys for payment sub-providers (currently only used by Zelle) */
+export declare const subProviders: {
+    readonly CHASE: "zelle-chase";
+    readonly BANK_OF_AMERICA: "zelle-bofa";
+    readonly CITI: "zelle-citi";
+};
+/** Sub-provider key (providers within providers) */
+export type SubProviderKey = typeof subProviders[keyof typeof subProviders];
+/**
+ * Extension platform keys - the platform identifiers used by the PeerAuth extension.
+ * For Zelle sub-providers, these are the bank names without the 'zelle-' prefix.
+ * Must match the folder names in @zkp2p/providers package.
+ */
+export declare const extensionPlatforms: {
+    readonly CHASE: "chase";
+    readonly BOFA: "bankofamerica";
+    readonly CITI: "citi";
+};
+/** Extension platform key type */
+export type ExtensionPlatformKey = typeof extensionPlatforms[keyof typeof extensionPlatforms];
+/** Action type for a provider */
+export type ProviderKeyActionType = 'transfer' | 'send';
+/** Validatable provider key */
+export type ValidatableProviderKey = Exclude<ProviderKey, typeof providers.MANUAL>;
+/** Transparent platforms */
+export type TransparentPlatforms = typeof providers.ZELLE;
+/** Platform key (includes extension platform keys for type safety) */
+export type PlatformKey = Exclude<ValidatableProviderKey, TransparentPlatforms> | SubProviderKey | ExtensionPlatformKey;
+/** Action type */
+export type ActionType = `${ProviderKeyActionType}_${ProviderKey}`;
+/**
+ * Platform risk levels for the reputation system (Base chain only)
+ * Determines cap multipliers and cooldown enforcement
+ */
+export type PlatformRiskLevel = 'low' | 'medium' | 'high' | 'highest';
+/**
+ * Universal taker tier names for the reputation system.
+ * Use this const instead of string literals wherever a tier is referenced.
+ */
+export declare const tiers: {
+    readonly PEASANT: "peasant";
+    readonly NEUTRAL: "neutral";
+    readonly PLUS: "plus";
+    readonly PRO: "pro";
+    readonly PLATINUM: "platinum";
+    /** Manually assigned VIP tier — cannot be reached via volume alone */
+    readonly PRESIDENT: "president";
+};
+export type TakerTier = typeof tiers[keyof typeof tiers];
+/** Valid peer tier names */
+export type PeerTier = 'peer_peasant' | 'peer' | 'peer_plus' | 'peer_pro' | 'peer_platinum' | 'peer_president';
+/**
+ * Mapping from universal tier names to peer-specific tier names
+ */
+export declare const tierToPeerTier: Record<TakerTier, PeerTier>;
+/**
+ * Mapping from peer tier names to universal tier names
+ */
+export declare const peerTierToTier: Record<PeerTier, TakerTier>;
+/**
+ * Convert a peer tier name to universal tier name
+ * @param peerTier - peer tier name (e.g., 'peer_peasant')
+ * @returns Universal tier name
+ * @throws Error if peerTier is not a valid peer tier
+ */
+export declare function fromPeerTier(peerTier: PeerTier): TakerTier;
+/** Provider key to validation key */
+export declare const providerKeyToValidationKey: Record<ValidatableProviderKey, string>;
+/** Validation key */
+export type ValidationKey = typeof providerKeyToValidationKey[keyof typeof providerKeyToValidationKey];
+/** Limits for a payment method */
+export type Limits = {
+    min: number;
+};
+/** Send link options */
+export type SendLinkOptions = {
+    username: string;
+    amount: bigint;
+    subProvider?: SubProviderKey;
+    qrCode?: boolean;
+};
+/** Send link */
+export type SendLink = (options: SendLinkOptions) => string | null;
+/** Payment sub-provider config */
+export type PaymentSubProviderConfig = {
+    key: SubProviderKey;
+    name: string;
+    icon?: string;
+    color?: string;
+    usernameType?: string;
+    v2Verifiers: (chain: ChainId) => Hex[];
+    sendLink: SendLink;
+    paymentMethod: number;
+    /**
+     * Platform key used by the PeerAuth extension for this sub-provider.
+     * For Zelle sub-providers, this is the bank name without the 'zelle-' prefix.
+     * e.g., 'zelle-chase' -> 'chase', 'zelle-bofa' -> 'bofa'
+     */
+    extensionPlatform: ExtensionPlatformKey;
+};
+/** Payment config */
+export type PaymentConfig = {
+    icon: string;
+    key: ProviderKey;
+    name: string;
+    color: string;
+    /**
+     * Optional color to use specifically for charts, distinct from brand color if needed
+     */
+    chartColor?: string;
+    /**
+     * Optional chart color overrides for light/dark themes
+     */
+    chartColorLight?: string;
+    chartColorDark?: string;
+    /**
+     * Optional background color for the icon (useful for dark icons that need contrast)
+     */
+    backgroundColor?: string;
+    usernameType: string;
+    validationKey: ValidationKey | null;
+    /**
+     * V2 verifier contract addresses (legacy, for backward compatibility)
+     */
+    v2Verifiers: string[];
+    limits: Limits;
+    /**
+     * Contract ID (keccak256 hash of the provider key) for V3 indexer lookups
+     * This is the primary identifier for payment methods in V3
+     */
+    contractId: Hex;
+    /**
+     * Set of sub-provider keys that this payment method supports. Empty when none.
+     */
+    subProviders: Set<PaymentSubProviderConfig>;
+    list: Hex[];
+    sendLink?: SendLink;
+    /**
+     * Risk level for reputation system (Base only)
+     * Determines cap multiplier and cooldown enforcement
+     */
+    riskLevel?: PlatformRiskLevel;
+    /**
+     * Cap multiplier for reputation system
+     * Applied to base tier cap to get effective cap
+     */
+    capMultiplier?: number;
+    /**
+     * Whether cooldown applies to this platform
+     */
+    hasCooldown?: boolean;
+    /**
+     * Whether the extension sends transaction amounts in cents (integer, e.g. 5000 for $50).
+     * When true, divide by 100 before displaying amounts to the user.
+     */
+    amountInCents?: boolean;
+    /**
+     * Minimum tier required to access (null = no restriction)
+     */
+    minimumTier?: TakerTier | null;
+    /**
+     * Whether this payment method requires manual approval from the peer.xyz
+     * backend before deposits become visible to buyers.
+     * Approval is handled by peer.xyz — use approvalFormUrl to direct makers.
+     */
+    depositRequiresApproval?: boolean;
+    /**
+     * URL of the approval form to direct makers to when depositRequiresApproval is true.
+     */
+    approvalFormUrl?: string;
+    /**
+     * When true, this provider is hidden from user-facing flows (provider
+     * selection, deposit creation, buy flows). The config still exists for
+     * dev/testing — set VITE_ENABLE_PAYPAL=true to override in dev.
+     */
+    disabled?: boolean;
+};
+/** Validation deposit data payment identifier */
+export type ValidationDepositDataPaymentIdentifier = Partial<{
+    [key in Exclude<ValidationKey, null>]: string;
+}>;
+/** Validation deposit data */
+export type ValidationDepositData = ValidationDepositDataPaymentIdentifier & {
+    telegramUsername: string;
+};
+/** Data encoding for zelle urls */
+export declare const dataEncoding: (data: string) => string;
+/** Default Zelle send link */
+export declare const defaultZelleSendLink: (options: SendLinkOptions) => string | null;
+/** Global configuration for all supported sub-providers. Other modules can import this directly. */
+export declare const subProviderConfigs: Partial<Record<ProviderKey, Record<SubProviderKey, PaymentSubProviderConfig>>>;
+/** Payment method icon mappings */
+export declare const providerConfigs: (chainId: ChainId) => Record<ProviderKey, PaymentConfig>;
+/**
+ * Default platform risk configuration for providers not explicitly configured
+ * Assumes medium risk as a safe default
+ */
+export declare const DEFAULT_PLATFORM_RISK: {
+    riskLevel: PlatformRiskLevel;
+    capMultiplier: number;
+    hasCooldown: boolean;
+    minimumTier: TakerTier | null;
+};
+/**
+ * Platform risk configuration interface
+ */
+export interface PlatformRiskConfig {
+    riskLevel: PlatformRiskLevel;
+    capMultiplier: number;
+    hasCooldown: boolean;
+    minimumTier: TakerTier | null;
+}
+/**
+ * Get the risk configuration for a payment platform
+ * @param chainId - The chain ID
+ * @param providerKey - The provider key
+ * @returns Platform risk configuration
+ */
+export declare function getPlatformRisk(chainId: ChainId, providerKey: ProviderKey): PlatformRiskConfig;
+/**
+ * Payment verifier to key map
+ * Includes both main providers and flattened sub-providers
+ */
+export declare const paymentVerifierToKey: (chainId: ChainId | null) => Map<string, ProviderKey>;
+/**
+ * Provider contractId to config map (reverse lookup by keccak256 hash)
+ * Includes both main providers and flattened sub-providers with their own contract IDs
+ * Note: Keys are stored as lowercase for case-insensitive lookup
+ */
+export declare const providerByContractId: (chainId: ChainId) => Map<`0x${string}`, PaymentConfig>;
+/**
+ * Get provider config by contractId (keccak256 hash)
+ * Supports both main providers and sub-providers (e.g., zelle-chase, zelle-bofa, zelle-citi)
+ * @param chainId - The chain ID
+ * @param contractId - The contract ID (keccak256 hash) to lookup
+ * @returns PaymentConfig or null if not found
+ */
+export declare const getProviderByContractId: (chainId: ChainId, contractId: Hex) => PaymentConfig | null;
+/**
+ * Get provider name by contractId (keccak256 hash)
+ * Supports both main providers and sub-providers
+ * @param chainId - The chain ID
+ * @param contractId - The contract ID (keccak256 hash) to lookup
+ * @returns Provider name or the contract ID if not found
+ */
+export declare const getProviderNameByContractId: (chainId: ChainId, contractId: Hex) => string;
+/** Provider key to V2 verifiers map (legacy, for backward compatibility) */
+export declare const providerKeyToVerifiersMap: (chainId: ChainId) => Map<ProviderKey, `0x${string}`[]>;
+/** Provider key to verifiers */
+export declare const providerKeyToVerifiers: (chainId: ChainId, providerKey: ProviderKey) => Hex[] | null;
+/** Verifier gets key */
+export declare const verifierGetsKey: (chainId: ChainId | null, verifierAddress: string) => ProviderKey;
+/**
+ * Utility function to get payment method icon
+ * @param key - The provider key (main provider or sub-provider like 'zelle-chase')
+ * @returns The icon string used for iconify
+ */
+export declare const getPaymentIcon: (chainId: ChainId | null, key: ProviderKey) => string;
+/**
+ * Utility function to get payment method configuration by verifier address
+ * @param verifierAddress - The verifier address
+ * @returns The payment method configuration
+ */
+export declare const getPaymentMethodConfig: (chainId: ChainId | null, verifierAddress: string) => PaymentConfig | null;
+/**
+ * Utility function to get payment method minimum limit by verifier address
+ * @param key - The provider key
+ * @returns The minimum limit
+ */
+export declare const getPaymentMethodMinimum: (chainId: ChainId | null, key: ProviderKey) => number;
+/**
+ * Utility function to get payment method name by verifier address or provider key
+ * Handles both main providers and sub-providers (e.g., 'zelle-chase')
+ */
+export declare const getPaymentMethodName: (chainId: ChainId | null, verifierAddress: string | ProviderKey) => string;
+/**
+ * Calculate effective minimum amount (higher of user minimum or payment provider minimum)
+ * @param userMinAmountWei - The user minimum amount
+ * @param tokenInfo - The token info
+ * @param providerRates - The provider rates
+ * @returns The effective minimum amount
+ */
+export declare function calculateEffectiveMinimum(chainId: ChainId, userMinAmountWei: string | bigint, tokenInfo: TokenInfo, providerRates?: ProviderRates<ConversionRateInfo>): {
+    userMinAmountWei: bigint;
+    providerMinAmountWei: bigint;
+    effectiveMinAmountWei: bigint;
+    formattedEffectiveMin: string;
+};
+/**
+ * Helper function to get payment provider minimum limit (returns decimal number for config)
+ * @param key - The provider key
+ * @returns The minimum limit
+ */
+export declare function getPaymentProviderMinimum(chainId: ChainId, key: ProviderKey): number;
+/**
+ * External/unregistered payment methods that are known but not in providerConfigs.
+ * These are payment methods registered by external parties (e.g., other protocols).
+ * Maps payment method ID to metadata to prevent error logging.
+ */
+export declare const externalPaymentMethods: Record<Hex, {
+    name: string;
+    originTxHash: Hex;
+    chainId: ChainId;
+    description?: string;
+}>;
+/**
+ * Check if a payment method is an external/unregistered payment method
+ * @param paymentMethodId - The payment method ID
+ * @returns True if the payment method is external, false otherwise
+ */
+export declare const isExternalPaymentMethod: (paymentMethodId: Hex) => boolean;
+/**
+ * Get external payment method info
+ * @param paymentMethodId - The payment method ID
+ * @returns The external payment method info or undefined
+ */
+export declare const getExternalPaymentMethod: (paymentMethodId: Hex) => {
+    name: string;
+    originTxHash: Hex;
+    chainId: ChainId;
+    description?: string;
+};
+/**
+ * Check if a payment method is known (either in providerConfigs or external)
+ * @param chainId - The chain ID
+ * @param verifierAddress - The verifier address
+ * @returns True if the payment method is known, false otherwise
+ */
+export declare const isPaymentMethodKnown: (chainId: ChainId | null, verifierAddress: string) => boolean;
+/**
+ * Check if a payment method ID is known (either in providerConfigs or external)
+ * @param chainId - The chain ID
+ * @param paymentMethodId - The payment method ID
+ * @param verifierAddress - Optional verifier address for checking providerConfigs
+ * @returns True if the payment method is known, false otherwise
+ */
+export declare const isPaymentMethodIdKnown: (chainId: ChainId | null, paymentMethodId: Hex, verifierAddress?: string) => boolean;
+/**
+ * Get all payment methods including sub-providers
+ * @param includeSubProviders - Whether to include sub-providers as separate entries (default: false)
+ * @returns All payment methods
+ */
+export declare const getAllPaymentMethods: (chainId: ChainId, includeSubProviders?: boolean) => ProviderKey[];
+/**
+ * Get all verifiable payment methods including sub-providers
+ * @param includeSubProviders - Whether to include sub-providers as separate entries (default: false)
+ * @returns All verifiable payment methods
+ */
+export declare const verifiablePaymentMethods: (chainId: ChainId, includeSubProviders?: boolean) => ProviderKey[];
+/**
+ * Get supported currencies for a payment provider.
+ * Returns only the currencies that are in the provider's supported list.
+ *
+ * @param config - The payment provider configuration
+ * @returns Array of Currency objects supported by this provider
+ *
+ * @example
+ * ```ts
+ * const zelle = providerConfigs(base.id).zelle
+ * const currencies = getCurrenciesForProvider(zelle)
+ * // Returns [Currency(USD)] - Zelle only supports USD
+ *
+ * const revolut = providerConfigs(base.id).revolut
+ * const currencies = getCurrenciesForProvider(revolut)
+ * // Returns [Currency(USD), Currency(EUR), Currency(GBP), ...] - Revolut supports many
+ * ```
+ */
+export declare function getCurrenciesForProvider(config: PaymentConfig): Currency[];
+/**
+ * Check if a provider key is a sub-provider (e.g., 'zelle-chase', 'zelle-bofa')
+ * @param key - The provider key to check
+ * @returns True if the key is a sub-provider
+ */
+export declare function isSubProviderKey(key: string): key is SubProviderKey;
+/**
+ * Get the parent provider key for a sub-provider.
+ * Returns null if the key is not a sub-provider.
+ * @param key - The sub-provider key (e.g., 'zelle-chase')
+ * @returns The parent provider key (e.g., 'zelle') or null
+ */
+export declare function getParentProviderKey(key: string): ProviderKey | null;
+/**
+ * Get the extension platform key for a provider or sub-provider.
+ * For sub-providers like 'zelle-chase', returns the extensionPlatform from config (e.g., 'chase').
+ * For main providers, returns the provider key itself.
+ * @param key - The provider or sub-provider key
+ * @returns The platform key to use with the PeerAuth extension
+ */
+export declare function getExtensionPlatform(key: ProviderKey | SubProviderKey): PlatformKey;
+/**
+ * Get icon and color info for both parent and sub-provider.
+ * Returns array of icon configs: [parent, subProvider] for sub-providers, [provider] for main providers.
+ * @param chainId - The chain ID for config lookup
+ * @param key - The provider or sub-provider key
+ * @returns Array of icon configs with icon string and optional color
+ */
+export declare function getProviderIconStack(chainId: ChainId, key: ProviderKey | SubProviderKey): Array<{
+    icon: string;
+    color?: string;
+    name: string;
+}>;