@provex/utils 1.0.16 → 1.2.3

package/dist/src/payment.d.ts

@@ -1,7 +1,63 @@
+/**
+ * @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
  */
@@ -15,26 +71,79 @@ export declare const providers: {
     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: "chase";
-    readonly BANK_OF_AMERICA: "bank_of_america";
-    readonly CITI: "citi";
+    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 */
-export type PlatformKey = Exclude<ValidatableProviderKey, TransparentPlatforms> | SubProviderKey;
+/** 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 */
@@ -59,9 +168,15 @@ export type PaymentSubProviderConfig = {
     icon?: string;
     color?: string;
     usernameType?: string;
-    verifiers: (chain: ChainId) => Hex[];
+    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 = {
@@ -69,16 +184,76 @@ export type PaymentConfig = {
     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;
-    verifiers: string[];
+    /**
+     * 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<{
@@ -96,9 +271,60 @@ export declare const defaultZelleSendLink: (options: SendLinkOptions) => string
 export declare const subProviderConfigs: Partial<Record<ProviderKey, Record<SubProviderKey, PaymentSubProviderConfig>>>;
 /** Payment method icon mappings */
 export declare const providerConfigs: (chainId: ChainId) => Record<ProviderKey, PaymentConfig>;
-/** Payment verifier to key map */
+/**
+ * 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 key to verifiers map */
+/**
+ * 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;
@@ -106,7 +332,7 @@ export declare const providerKeyToVerifiers: (chainId: ChainId, providerKey: Pro
 export declare const verifierGetsKey: (chainId: ChainId | null, verifierAddress: string) => ProviderKey;
 /**
  * Utility function to get payment method icon
- * @param key - The provider key
+ * @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;
@@ -123,7 +349,8 @@ export declare const getPaymentMethodConfig: (chainId: ChainId | null, verifierA
  */
 export declare const getPaymentMethodMinimum: (chainId: ChainId | null, key: ProviderKey) => number;
 /**
- * Utility function to get payment method name by verifier address
+ * 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;
 /**
@@ -146,19 +373,109 @@ export declare function calculateEffectiveMinimum(chainId: ChainId, userMinAmoun
  */
 export declare function getPaymentProviderMinimum(chainId: ChainId, key: ProviderKey): number;
 /**
- * Check if a payment method is known
+ * 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;
 /**
- * Get all payment methods
+ * 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) => ProviderKey[];
+export declare const getAllPaymentMethods: (chainId: ChainId, includeSubProviders?: boolean) => ProviderKey[];
 /**
- * Get all verifiable payment methods
+ * 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) => ProviderKey[];
+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;
+}>;