@provex/utils 1.0.16 → 1.2.3

package/dist/src/payment.js

@@ -1,8 +1,113 @@
-import { getAddress, parseUnits, zeroAddress } from "viem";
+/**
+ * @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 { getAddress, parseUnits, zeroAddress, keccak256, stringToHex, isAddress } from "viem";
+/**
+ * Read an env var from Vite (browser) or Node, returning empty string if not set.
+ */
+function readEnv(name) {
+    const viteVal = typeof import.meta !== 'undefined'
+        ? import.meta.env?.[`VITE_${name}`]
+        : undefined;
+    const nodeVal = typeof process !== 'undefined'
+        ? process.env?.[name] ?? process.env?.[`VITE_${name}`]
+        : undefined;
+    return viteVal ?? nodeVal ?? '';
+}
+/**
+ * Parse a comma-separated list of provider keys from an env var.
+ *
+ * VITE_DISABLED_PROVIDERS / DISABLED_PROVIDERS — providers to hide (takes precedence).
+ * VITE_ENABLED_PROVIDERS / ENABLED_PROVIDERS — providers to force-show (overrides `disabled: true` in config).
+ *
+ * Examples:
+ *   VITE_DISABLED_PROVIDERS=paypal,n26        → hides PayPal and N26
+ *   VITE_ENABLED_PROVIDERS=paypal             → shows PayPal even if config has disabled:true
+ *   (both set: disabled list wins)
+ *
+ * If neither is set, falls back to the `disabled` field on the config.
+ */
+let _disabledSet = null;
+let _enabledSet = null;
+function parseProviderLists() {
+    if (_disabledSet !== null)
+        return;
+    const disabled = readEnv('DISABLED_PROVIDERS').toLowerCase().split(',').map(s => s.trim()).filter(Boolean);
+    const enabled = readEnv('ENABLED_PROVIDERS').toLowerCase().split(',').map(s => s.trim()).filter(Boolean);
+    _disabledSet = new Set(disabled);
+    _enabledSet = new Set(enabled);
+}
+/** Returns true if a provider should be hidden from user-facing flows. */
+export function isProviderDisabled(key, configDisabled) {
+    parseProviderLists();
+    const k = key.toLowerCase();
+    // Explicit disable list takes priority
+    if (_disabledSet.has(k))
+        return true;
+    // Explicit enable list overrides config
+    if (_enabledSet.has(k))
+        return false;
+    // Fall back to config field
+    return configDisabled ?? false;
+}
 import { base, pulsechain } from "viem/chains";
-import { contractsByChainId, getContracts } from "./contracts.js";
+import { contracts } from "./contracts.js";
 import { formatUnits } from "./units.js";
 import { SUPPORTED_CURRENCIES } from "./currencies.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 const providerKeyToContractId = (key) => {
+    return keccak256(stringToHex(key));
+};
+/**
+ * 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 const computePayeeDetailsHash = (identifier) => {
+    return keccak256(stringToHex(identifier));
+};
 /**
  * Payment providers, including manual
  */
@@ -16,13 +121,76 @@ export const providers = {
     MANUAL: 'manual',
     PAYPAL: 'paypal',
     MONZO: 'monzo',
+    N26: 'n26',
+    ALIPAY: 'alipay',
+    CHIME: 'chime',
+    ROYALBANKCANADA: 'royalbankcanada',
+    IDFC: 'idfc',
 };
 /** Distinct keys for payment sub-providers (currently only used by Zelle) */
 export const subProviders = {
+    CHASE: 'zelle-chase',
+    BANK_OF_AMERICA: 'zelle-bofa',
+    CITI: 'zelle-citi',
+};
+/**
+ * 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 const extensionPlatforms = {
     CHASE: 'chase',
-    BANK_OF_AMERICA: 'bank_of_america',
+    BOFA: 'bankofamerica',
     CITI: 'citi',
 };
+/**
+ * Universal taker tier names for the reputation system.
+ * Use this const instead of string literals wherever a tier is referenced.
+ */
+export const tiers = {
+    PEASANT: 'peasant',
+    NEUTRAL: 'neutral',
+    PLUS: 'plus',
+    PRO: 'pro',
+    PLATINUM: 'platinum',
+    /** Manually assigned VIP tier — cannot be reached via volume alone */
+    PRESIDENT: 'president',
+};
+/**
+ * Mapping from universal tier names to peer-specific tier names
+ */
+export const tierToPeerTier = {
+    [tiers.PEASANT]: 'peer_peasant',
+    [tiers.NEUTRAL]: 'peer',
+    [tiers.PLUS]: 'peer_plus',
+    [tiers.PRO]: 'peer_pro',
+    [tiers.PLATINUM]: 'peer_platinum',
+    [tiers.PRESIDENT]: 'peer_president',
+};
+/**
+ * Mapping from peer tier names to universal tier names
+ */
+export const peerTierToTier = {
+    peer_peasant: tiers.PEASANT,
+    peer: tiers.NEUTRAL,
+    peer_plus: tiers.PLUS,
+    peer_pro: tiers.PRO,
+    peer_platinum: tiers.PLATINUM,
+    peer_president: tiers.PRESIDENT,
+};
+/**
+ * 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 function fromPeerTier(peerTier) {
+    const tier = peerTierToTier[peerTier];
+    if (!tier) {
+        throw new Error(`Invalid peer tier: ${peerTier}`);
+    }
+    return tier;
+}
 /** Provider key to validation key */
 export const providerKeyToValidationKey = {
     venmo: 'venmoUsername',
@@ -33,6 +201,11 @@ export const providerKeyToValidationKey = {
     mercadopago: 'cvu',
     paypal: 'paypalEmail',
     monzo: 'monzoMeUsername',
+    n26: 'n26Email',
+    alipay: 'alipayId',
+    chime: 'chimesign',
+    royalbankcanada: 'interacEmail',
+    idfc: 'idfcAccountNumber',
 };
 /** Data encoding for zelle urls */
 export const dataEncoding = (data) => {
@@ -48,25 +221,28 @@ export const defaultZelleSendLink = (options) => (!options.username ? null
 /** Global configuration for all supported sub-providers. Other modules can import this directly. */
 export const subProviderConfigs = {
     zelle: {
-        chase: {
+        'zelle-chase': {
             paymentMethod: 0,
             key: subProviders.CHASE,
             name: 'Chase',
             icon: 'simple-icons:chase',
-            verifiers: (chain) => getContracts(chain).zelleChaseReclaimVerifier,
+            extensionPlatform: extensionPlatforms.CHASE,
+            v2Verifiers: (chain) => contracts.v2[chain].zelleChaseReclaimVerifier,
             sendLink: (opts) => {
                 if (opts.qrCode) {
                     return defaultZelleSendLink(opts);
                 }
+                // return 'https://secure.chase.com/web/auth/dashboard#/dashboard/singleDoor/payments/activity;params=qp,sentactivity'
                 return 'https://secure.chase.com/web/auth/dashboard#/dashboard/singleDoor/singleDoorController/index';
             },
         },
-        bank_of_america: {
+        'zelle-bofa': {
             paymentMethod: 1,
             key: subProviders.BANK_OF_AMERICA,
             name: 'Bank of America',
             icon: 'simple-icons:bankofamerica',
-            verifiers: (chain) => getContracts(chain).zelleBoAReclaimVerifier,
+            extensionPlatform: extensionPlatforms.BOFA,
+            v2Verifiers: (chain) => contracts.v2[chain].zelleBoAReclaimVerifier,
             sendLink: (opts) => {
                 if (opts.qrCode) {
                     return `https://www.bankofamerica.com/movemoney`;
@@ -74,12 +250,13 @@ export const subProviderConfigs = {
                 return 'https://www.bankofamerica.com/';
             },
         },
-        citi: {
+        'zelle-citi': {
             paymentMethod: 2,
             key: subProviders.CITI,
             name: 'Citi',
             icon: 'arcticons:citi-mobile',
-            verifiers: (chain) => getContracts(chain).zelleCitiReclaimVerifier,
+            extensionPlatform: extensionPlatforms.CITI,
+            v2Verifiers: (chain) => contracts.v2[chain].zelleCitiReclaimVerifier,
             sendLink: (opts) => {
                 if (opts.qrCode) {
                     return defaultZelleSendLink(opts);
@@ -91,16 +268,37 @@ export const subProviderConfigs = {
 };
 /** Payment method icon mappings */
 export const providerConfigs = (chainId) => {
-    const contracts = getContracts(chainId);
+    const v2Contracts = contracts.v2[chainId];
+    const v3Contracts = contracts.v3[chainId];
+    /**
+     * Get v2 verifier addresses for a payment method.
+     * Prioritizes v2-specific verifiers over v3 unified verifier.
+     * This ensures v2 historical data is correctly categorized even on chains with both v2 and v3 contracts.
+     */
+    const getV2Verifiers = (verifierKey) => {
+        // First check if v2 contracts have specific verifiers for this method
+        if (v2Contracts && verifierKey in v2Contracts) {
+            const value = v2Contracts[verifierKey];
+            return (Array.isArray(value) ? value : []);
+        }
+        // Fall back to v3 unified verifier (for v3-only chains or v3-only payment methods)
+        if (v3Contracts && 'unifiedPaymentVerifier' in v3Contracts) {
+            return v3Contracts.unifiedPaymentVerifier || [];
+        }
+        return [];
+    };
     return {
         venmo: {
             key: providers.VENMO,
+            contractId: providerKeyToContractId(providers.VENMO),
             icon: 'ion:logo-venmo',
             name: 'Venmo',
             usernameType: 'Venmo Username',
             validationKey: providerKeyToValidationKey.venmo,
             color: 'rgb(0, 116, 222)',
-            verifiers: contracts.venmoReclaimVerifier,
+            chartColorLight: '#0074de',
+            chartColorDark: '#4da5ff',
+            v2Verifiers: getV2Verifiers('venmoReclaimVerifier'),
             limits: {
                 min: 1.0,
             },
@@ -114,22 +312,26 @@ export const providerConfigs = (chainId) => {
             list: [
                 SUPPORTED_CURRENCIES.USD.contractId,
             ],
+            // High risk - 1x multiplier, has cooldown
+            riskLevel: 'high',
+            capMultiplier: 1,
+            hasCooldown: true,
+            minimumTier: null,
         },
         zelle: {
             key: providers.ZELLE,
+            contractId: providerKeyToContractId(providers.ZELLE),
             icon: 'simple-icons:zelle',
             name: 'Zelle',
             color: '#6d1fd4',
             usernameType: 'Zelle Email',
             validationKey: providerKeyToValidationKey.zelle,
-            verifiers: contracts.zelleBaseVerifier,
+            v2Verifiers: getV2Verifiers('zelleBaseVerifier'),
             limits: {
                 min: 1.0,
             },
             subProviders: new Set([
-                subProviderConfigs.zelle[subProviders.CHASE],
-                subProviderConfigs.zelle[subProviders.BANK_OF_AMERICA],
-                subProviderConfigs.zelle[subProviders.CITI],
+                ...Object.values(subProviderConfigs.zelle),
             ]),
             // Delegate to sub-provider specific link when provided, otherwise fall back to generic QR URL
             sendLink: (options) => {
@@ -141,15 +343,23 @@ export const providerConfigs = (chainId) => {
             list: [
                 SUPPORTED_CURRENCIES.USD.contractId,
             ],
+            // Medium risk - 1.5x multiplier, has cooldown
+            riskLevel: 'medium',
+            capMultiplier: 1.5,
+            hasCooldown: true,
+            minimumTier: null,
         },
         cashapp: {
             key: providers.CASHAPP,
+            contractId: providerKeyToContractId(providers.CASHAPP),
             icon: 'simple-icons:cashapp',
             name: 'Cash App',
             color: 'rgba(0,224,19,1.0)',
+            chartColorLight: '#00e013',
+            chartColorDark: '#4dff6a',
             usernameType: 'CashTag',
             validationKey: providerKeyToValidationKey.cashapp,
-            verifiers: contracts.cashappReclaimVerifier,
+            v2Verifiers: getV2Verifiers('cashappReclaimVerifier'),
             limits: {
                 min: 1.0,
             },
@@ -161,15 +371,25 @@ export const providerConfigs = (chainId) => {
                 const u = options.username.startsWith('$') ? options.username : `$${options.username}`;
                 return `https://cash.app/qr/${u}?size=288&margin=0`;
             },
+            // High risk - 1x multiplier, has cooldown
+            riskLevel: 'high',
+            capMultiplier: 1,
+            hasCooldown: true,
+            minimumTier: null,
         },
         revolut: {
             key: providers.REVOLUT,
+            contractId: providerKeyToContractId(providers.REVOLUT),
             icon: 'simple-icons:revolut',
             name: 'Revolut',
             color: '#191c1f',
+            // Chart-friendly color to ensure distinction in stacked bar palette
+            chartColorLight: '#8b5cf6',
+            chartColorDark: '#c4b5fd',
+            backgroundColor: '#ffffff',
             usernameType: 'RevTag',
             validationKey: providerKeyToValidationKey.revolut,
-            verifiers: contracts.revolutReclaimVerifier,
+            v2Verifiers: getV2Verifiers('revolutReclaimVerifier'),
             limits: {
                 min: 1.0,
             },
@@ -179,29 +399,45 @@ export const providerConfigs = (chainId) => {
                 SUPPORTED_CURRENCIES.USD.contractId,
                 SUPPORTED_CURRENCIES.EUR.contractId,
                 SUPPORTED_CURRENCIES.GBP.contractId,
+                SUPPORTED_CURRENCIES.SGD.contractId,
+                SUPPORTED_CURRENCIES.NZD.contractId,
                 SUPPORTED_CURRENCIES.AUD.contractId,
                 SUPPORTED_CURRENCIES.CAD.contractId,
                 SUPPORTED_CURRENCIES.HKD.contractId,
                 SUPPORTED_CURRENCIES.MXN.contractId,
-                SUPPORTED_CURRENCIES.NZD.contractId,
-                SUPPORTED_CURRENCIES.PLN.contractId,
                 SUPPORTED_CURRENCIES.SAR.contractId,
-                SUPPORTED_CURRENCIES.SGD.contractId,
-                SUPPORTED_CURRENCIES.ZAR.contractId,
-                SUPPORTED_CURRENCIES.CHF.contractId,
+                SUPPORTED_CURRENCIES.AED.contractId,
                 SUPPORTED_CURRENCIES.THB.contractId,
                 SUPPORTED_CURRENCIES.TRY.contractId,
-                SUPPORTED_CURRENCIES.AED.contractId,
+                SUPPORTED_CURRENCIES.PLN.contractId,
+                SUPPORTED_CURRENCIES.CHF.contractId,
+                SUPPORTED_CURRENCIES.ZAR.contractId,
+                SUPPORTED_CURRENCIES.JPY.contractId,
+                SUPPORTED_CURRENCIES.CZK.contractId,
+                SUPPORTED_CURRENCIES.CNY.contractId,
+                SUPPORTED_CURRENCIES.DKK.contractId,
+                SUPPORTED_CURRENCIES.HUF.contractId,
+                SUPPORTED_CURRENCIES.NOK.contractId,
+                SUPPORTED_CURRENCIES.RON.contractId,
+                SUPPORTED_CURRENCIES.SEK.contractId,
             ],
+            // Low risk - 5x multiplier, no cooldown
+            riskLevel: 'low',
+            capMultiplier: 5,
+            hasCooldown: false,
+            minimumTier: null,
+            // Revolut sends amounts as integer cents (e.g. 5000 for $50.00)
+            amountInCents: true,
         },
         wise: {
             key: providers.WISE,
+            contractId: providerKeyToContractId(providers.WISE),
             icon: 'simple-icons:wise',
             name: 'Wise',
             color: '#9fe870',
             usernameType: 'WiseTag',
             validationKey: providerKeyToValidationKey.wise,
-            verifiers: contracts.wiseReclaimVerifier,
+            v2Verifiers: getV2Verifiers('wiseReclaimVerifier'),
             limits: {
                 min: 1.0,
             },
@@ -209,38 +445,54 @@ export const providerConfigs = (chainId) => {
             sendLink: (options) => `https://wise.com/pay/me/${options.username}`,
             list: [
                 SUPPORTED_CURRENCIES.USD.contractId,
+                SUPPORTED_CURRENCIES.CNY.contractId,
                 SUPPORTED_CURRENCIES.EUR.contractId,
                 SUPPORTED_CURRENCIES.GBP.contractId,
                 SUPPORTED_CURRENCIES.AUD.contractId,
+                SUPPORTED_CURRENCIES.NZD.contractId,
                 SUPPORTED_CURRENCIES.CAD.contractId,
-                SUPPORTED_CURRENCIES.CNY.contractId,
-                SUPPORTED_CURRENCIES.HKD.contractId,
-                SUPPORTED_CURRENCIES.IDR.contractId,
+                SUPPORTED_CURRENCIES.AED.contractId,
+                SUPPORTED_CURRENCIES.CHF.contractId,
+                SUPPORTED_CURRENCIES.ZAR.contractId,
+                SUPPORTED_CURRENCIES.SGD.contractId,
                 SUPPORTED_CURRENCIES.ILS.contractId,
+                SUPPORTED_CURRENCIES.HKD.contractId,
                 SUPPORTED_CURRENCIES.JPY.contractId,
+                SUPPORTED_CURRENCIES.PLN.contractId,
+                SUPPORTED_CURRENCIES.TRY.contractId,
+                SUPPORTED_CURRENCIES.IDR.contractId,
                 SUPPORTED_CURRENCIES.KES.contractId,
                 SUPPORTED_CURRENCIES.MYR.contractId,
                 SUPPORTED_CURRENCIES.MXN.contractId,
-                SUPPORTED_CURRENCIES.NZD.contractId,
-                SUPPORTED_CURRENCIES.PLN.contractId,
-                SUPPORTED_CURRENCIES.SGD.contractId,
-                SUPPORTED_CURRENCIES.ZAR.contractId,
-                SUPPORTED_CURRENCIES.CHF.contractId,
                 SUPPORTED_CURRENCIES.THB.contractId,
-                SUPPORTED_CURRENCIES.TRY.contractId,
-                SUPPORTED_CURRENCIES.UGX.contractId,
-                SUPPORTED_CURRENCIES.AED.contractId,
                 SUPPORTED_CURRENCIES.VND.contractId,
+                SUPPORTED_CURRENCIES.UGX.contractId,
+                SUPPORTED_CURRENCIES.CZK.contractId,
+                SUPPORTED_CURRENCIES.DKK.contractId,
+                SUPPORTED_CURRENCIES.HUF.contractId,
+                SUPPORTED_CURRENCIES.INR.contractId,
+                SUPPORTED_CURRENCIES.NOK.contractId,
+                SUPPORTED_CURRENCIES.PHP.contractId,
+                SUPPORTED_CURRENCIES.RON.contractId,
+                SUPPORTED_CURRENCIES.SEK.contractId,
             ],
+            // Low risk - 5x multiplier, no cooldown
+            riskLevel: 'low',
+            capMultiplier: 5,
+            hasCooldown: false,
+            minimumTier: null,
+            depositRequiresApproval: true,
+            approvalFormUrl: 'https://forms.gle/9N36Wd4iKS8PwLyFA',
         },
         mercadopago: {
             key: providers.MERCADOPAGO,
+            contractId: providerKeyToContractId(providers.MERCADOPAGO),
             icon: 'simple-icons:mercadopago',
             name: 'Mercado Pago',
             usernameType: 'Mercado Pago / Bank CVU',
             color: '#ffe600',
             validationKey: providerKeyToValidationKey.mercadopago,
-            verifiers: contracts.mercadopagoReclaimVerifier,
+            v2Verifiers: getV2Verifiers('mercadopagoReclaimVerifier'),
             limits: {
                 min: 1.0,
             },
@@ -249,19 +501,26 @@ export const providerConfigs = (chainId) => {
             list: [
                 SUPPORTED_CURRENCIES.ARS.contractId,
             ],
+            // Low risk - instant settlement, no chargebacks (per peer.xyz docs)
+            riskLevel: 'low',
+            capMultiplier: 5,
+            hasCooldown: false,
+            minimumTier: null,
         },
         paypal: {
             key: providers.PAYPAL,
+            contractId: providerKeyToContractId(providers.PAYPAL),
             icon: 'simple-icons:paypal',
             name: 'PayPal',
             usernameType: 'PayPal Email',
             validationKey: providerKeyToValidationKey.paypal,
-            verifiers: contracts.paypalReclaimVerifier,
+            v2Verifiers: getV2Verifiers('paypalReclaimVerifier'),
             limits: {
                 min: 1.0,
             },
             subProviders: new Set(),
             color: '#0070BA',
+            chartColor: '#f59e0b',
             sendLink: (options) => {
                 if (options.qrCode) {
                     return `paypal://`;
@@ -277,14 +536,20 @@ export const providerConfigs = (chainId) => {
                 SUPPORTED_CURRENCIES.CAD.contractId,
                 SUPPORTED_CURRENCIES.SGD.contractId,
             ],
+            riskLevel: 'highest',
+            capMultiplier: 0.75,
+            hasCooldown: true,
+            minimumTier: tiers.PLUS,
+            disabled: true,
         },
         monzo: {
             key: providers.MONZO,
+            contractId: providerKeyToContractId(providers.MONZO),
             icon: 'simple-icons:monzo',
             name: 'Monzo',
             usernameType: 'Monzo Me Username',
             validationKey: providerKeyToValidationKey.monzo,
-            verifiers: contracts.monzoReclaimVerifier,
+            v2Verifiers: getV2Verifiers('monzoReclaimVerifier'),
             limits: {
                 min: 1.0,
             },
@@ -294,35 +559,281 @@ export const providerConfigs = (chainId) => {
                 SUPPORTED_CURRENCIES.GBP.contractId,
             ],
             color: '#FC427B',
+            // Low risk - instant settlement, no chargebacks (per peer.xyz docs)
+            riskLevel: 'low',
+            capMultiplier: 5,
+            hasCooldown: false,
+            minimumTier: null,
+        },
+        n26: {
+            key: providers.N26,
+            contractId: providerKeyToContractId(providers.N26),
+            icon: 'simple-icons:n26',
+            name: 'N26',
+            usernameType: 'N26 Email',
+            validationKey: providerKeyToValidationKey.n26,
+            v2Verifiers: [],
+            limits: {
+                min: 1.0,
+            },
+            subProviders: new Set(),
+            sendLink: (options) => {
+                if (options.qrCode) {
+                    return 'number26://';
+                }
+                return 'https://app.n26.com/';
+            },
+            list: [
+                SUPPORTED_CURRENCIES.EUR.contractId,
+            ],
+            color: '#088177',
+            riskLevel: 'medium',
+            capMultiplier: 1,
+            hasCooldown: true,
+            minimumTier: null,
+            disabled: true,
+        },
+        alipay: {
+            key: providers.ALIPAY,
+            contractId: providerKeyToContractId(providers.ALIPAY),
+            icon: 'simple-icons:alipay',
+            name: 'Alipay',
+            usernameType: 'Alipay ID',
+            validationKey: providerKeyToValidationKey.alipay,
+            v2Verifiers: [],
+            limits: {
+                min: 1.0,
+            },
+            subProviders: new Set(),
+            sendLink: (options) => {
+                if (options.qrCode) {
+                    return 'alipays://';
+                }
+                return 'https://www.alipay.com/';
+            },
+            list: [
+                SUPPORTED_CURRENCIES.CNY.contractId,
+            ],
+            color: '#1677FF',
+            riskLevel: 'medium',
+            capMultiplier: 1,
+            hasCooldown: true,
+            minimumTier: null,
+            depositRequiresApproval: true,
+            approvalFormUrl: 'https://forms.gle/9N36Wd4iKS8PwLyFA?hl=zh-CN',
+            disabled: true,
+        },
+        chime: {
+            key: providers.CHIME,
+            contractId: providerKeyToContractId(providers.CHIME),
+            icon: 'arcticons:chime',
+            name: 'Chime',
+            usernameType: '$ChimeSign',
+            validationKey: providerKeyToValidationKey.chime,
+            v2Verifiers: [],
+            limits: {
+                min: 0.1,
+            },
+            subProviders: new Set(),
+            sendLink: (options) => {
+                if (options.qrCode) {
+                    return `https://app.chime.com/link/qr?u=${options.username}`;
+                }
+                return 'https://app.chime.com/login';
+            },
+            list: [
+                SUPPORTED_CURRENCIES.USD.contractId,
+            ],
+            color: '#1EC677',
+            riskLevel: 'medium',
+            capMultiplier: 1,
+            hasCooldown: true,
+            minimumTier: null,
+            disabled: true,
+        },
+        royalbankcanada: {
+            key: providers.ROYALBANKCANADA,
+            contractId: providerKeyToContractId(providers.ROYALBANKCANADA),
+            icon: 'arcticons:rbcmobile',
+            name: 'Royal Bank of Canada',
+            usernameType: 'Interac Email',
+            validationKey: providerKeyToValidationKey.royalbankcanada,
+            v2Verifiers: [],
+            limits: {
+                min: 1.0,
+            },
+            subProviders: new Set(),
+            sendLink: () => 'https://www.rbcroyalbank.com/ways-to-bank/interac-e-transfer.html',
+            list: [
+                SUPPORTED_CURRENCIES.CAD.contractId,
+            ],
+            color: '#4A5568',
+            riskLevel: 'medium',
+            capMultiplier: 1,
+            hasCooldown: true,
+            minimumTier: null,
+            disabled: true,
+        },
+        idfc: {
+            key: providers.IDFC,
+            contractId: providerKeyToContractId(providers.IDFC),
+            icon: 'mdi:bank',
+            name: 'IDFC Bank',
+            usernameType: 'IDFC Account Number',
+            validationKey: providerKeyToValidationKey.idfc,
+            v2Verifiers: [],
+            limits: {
+                min: 1.0,
+            },
+            subProviders: new Set(),
+            sendLink: () => 'https://www.idfcfirstbank.com/',
+            list: [
+                SUPPORTED_CURRENCIES.INR.contractId,
+            ],
+            color: '#2D3748',
+            riskLevel: 'medium',
+            capMultiplier: 1,
+            hasCooldown: true,
+            minimumTier: null,
+            disabled: true,
         },
         manual: {
             key: providers.MANUAL,
+            contractId: providerKeyToContractId(providers.MANUAL),
             icon: 'mdi:help-circle',
-            name: 'Manual Release',
+            name: 'Manual',
             color: 'gray',
             usernameType: '',
             validationKey: null,
-            verifiers: [zeroAddress],
+            v2Verifiers: [zeroAddress],
             limits: {
                 min: 0.0,
             },
             subProviders: new Set(),
             list: [],
+            // Manual verification - no reputation restrictions
+            riskLevel: 'low',
+            capMultiplier: 5,
+            hasCooldown: false,
+            minimumTier: null,
         },
     };
 };
-/** Payment verifier to key map */
-export const paymentVerifierToKey = (chainId) => (new Map(Object.values(chainId ? [chainId] : [...contractsByChainId.keys()]).flatMap(chainId => (Object.values(providerConfigs(chainId)).flatMap(config => {
-    return config.verifiers.map(verifier => [getAddress(verifier), config.key]);
-})))));
-/** Provider key to verifiers map */
-export const providerKeyToVerifiersMap = (chainId) => (new Map(Object.entries(providerConfigs(chainId)).map(([key, config]) => [key, config.verifiers])));
+/**
+ * Default platform risk configuration for providers not explicitly configured
+ * Assumes medium risk as a safe default
+ */
+export const DEFAULT_PLATFORM_RISK = {
+    riskLevel: 'medium',
+    capMultiplier: 1,
+    hasCooldown: true,
+    minimumTier: null,
+};
+/**
+ * Get the risk configuration for a payment platform
+ * @param chainId - The chain ID
+ * @param providerKey - The provider key
+ * @returns Platform risk configuration
+ */
+export function getPlatformRisk(chainId, providerKey) {
+    const config = providerConfigs(chainId)[providerKey];
+    return {
+        riskLevel: config?.riskLevel ?? DEFAULT_PLATFORM_RISK.riskLevel,
+        capMultiplier: config?.capMultiplier ?? DEFAULT_PLATFORM_RISK.capMultiplier,
+        hasCooldown: config?.hasCooldown ?? DEFAULT_PLATFORM_RISK.hasCooldown,
+        minimumTier: config?.minimumTier ?? DEFAULT_PLATFORM_RISK.minimumTier,
+    };
+}
+/**
+ * Payment verifier to key map
+ * Includes both main providers and flattened sub-providers
+ */
+export const paymentVerifierToKey = (chainId) => {
+    const chainIds = chainId ? [chainId] : Object.keys(contracts.v2).map(Number);
+    const entries = chainIds.flatMap(cId => Object.values(providerConfigs(cId)).flatMap(config => [
+        // Main provider: V2 verifier addresses -> key
+        ...config.v2Verifiers.map(verifier => [getAddress(verifier), config.key]),
+        // Main provider: contract ID -> key
+        [config.contractId.toLowerCase(), config.key],
+        // Sub-providers
+        ...Array.from(config.subProviders).flatMap(subProvider => [
+            ...subProvider.v2Verifiers(cId).map(verifier => [getAddress(verifier), subProvider.key]),
+            [providerKeyToContractId(subProvider.key).toLowerCase(), subProvider.key]
+        ])
+    ]));
+    return new Map(entries);
+};
+/**
+ * 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 const providerByContractId = (chainId) => {
+    const configs = Object.values(providerConfigs(chainId));
+    const entries = [
+        // Main providers
+        ...configs.map(config => [config.contractId.toLowerCase(), config]),
+        // Sub-providers with synthetic configs
+        ...configs.flatMap(config => Array.from(config.subProviders).map(subProvider => {
+            const contractId = providerKeyToContractId(subProvider.key).toLowerCase();
+            const subConfig = {
+                ...config,
+                key: subProvider.key,
+                contractId: providerKeyToContractId(subProvider.key),
+                name: subProvider.name,
+                icon: subProvider.icon || config.icon,
+                color: subProvider.color || config.color,
+                usernameType: subProvider.usernameType || config.usernameType,
+                v2Verifiers: subProvider.v2Verifiers(chainId),
+                subProviders: new Set(),
+            };
+            return [contractId, subConfig];
+        }))
+    ];
+    return new Map(entries);
+};
+/**
+ * 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 const getProviderByContractId = (chainId, contractId) => {
+    const normalizedId = contractId.toLowerCase();
+    return providerByContractId(chainId).get(normalizedId) ?? 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 const getProviderNameByContractId = (chainId, contractId) => {
+    return getProviderByContractId(chainId, contractId)?.name ?? contractId;
+};
+/** Provider key to V2 verifiers map (legacy, for backward compatibility) */
+export const providerKeyToVerifiersMap = (chainId) => (new Map(Object.entries(providerConfigs(chainId)).map(([key, config]) => [key, config.v2Verifiers])));
 /** Provider key to verifiers */
 export const providerKeyToVerifiers = (chainId, providerKey) => {
     return providerKeyToVerifiersMap(chainId).get(providerKey) ?? null;
 };
 /** Verifier gets key */
 export const verifierGetsKey = (chainId, verifierAddress) => {
+    // If this is a 32-byte hash (66 chars including 0x), look it up directly in the map
+    if (verifierAddress?.length === 66) {
+        const key = paymentVerifierToKey(chainId).get(verifierAddress.toLowerCase());
+        if (key)
+            return key;
+        // Fallback: try looking it up via contractId
+        const contractProvider = getProviderByContractId(chainId ?? base.id, verifierAddress);
+        if (contractProvider) {
+            return contractProvider.key;
+        }
+        return providers.MANUAL;
+    }
+    // Otherwise treat it as an address
     try {
         return paymentVerifierToKey(chainId).get(getAddress(verifierAddress)) ?? providers.MANUAL;
     }
@@ -332,12 +843,21 @@ export const verifierGetsKey = (chainId, verifierAddress) => {
 };
 /**
  * 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 const getPaymentIcon = (chainId, key) => {
     const config = providerConfigs(chainId ?? pulsechain.id);
-    return config[key]?.icon || config[providers.MANUAL].icon;
+    // Check main providers first
+    if (config[key]?.icon) {
+        return config[key].icon;
+    }
+    // Check sub-providers directly (e.g., 'zelle-chase', 'zelle-bofa', 'zelle-citi')
+    const zelleSubConfig = subProviderConfigs.zelle?.[key];
+    if (zelleSubConfig?.icon) {
+        return zelleSubConfig.icon;
+    }
+    return config[providers.MANUAL].icon;
 };
 /**
  * Utility function to get payment method configuration by verifier address
@@ -345,7 +865,16 @@ export const getPaymentIcon = (chainId, key) => {
  * @returns The payment method configuration
  */
 export const getPaymentMethodConfig = (chainId, verifierAddress) => {
-    return (chainId ? [chainId] : [...contractsByChainId.keys()]).reduce((result, chainId) => (result ?? Object.values(providerConfigs(chainId)).reduce((r, config) => (r ?? (config.verifiers.includes(getAddress(verifierAddress)) ? config : null)), result)), null);
+    // When verifierAddress is a payment-method hash (bytes32), compare via contractId
+    if (!isAddress(verifierAddress)) {
+        if (verifierAddress.length === 66) {
+            return getProviderByContractId(chainId ?? base.id, verifierAddress);
+        }
+        return null;
+    }
+    const normalized = getAddress(verifierAddress);
+    const chainIdsToCheck = chainId ? [chainId] : [...Object.keys(contracts.v2).map((id) => Number(id))];
+    return chainIdsToCheck.reduce((result, chain) => (result ?? Object.values(providerConfigs(chain)).reduce((r, config) => (r ?? (config.v2Verifiers.some((addr) => getAddress(addr) === normalized) ? config : null)), result)), null);
 };
 /**
  * Utility function to get payment method minimum limit by verifier address
@@ -357,7 +886,8 @@ export const getPaymentMethodMinimum = (chainId, key) => {
     return config?.limits?.min ?? 0;
 };
 /**
- * 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 const getPaymentMethodName = (chainId, verifierAddress) => {
     const providerKey = verifierAddress;
@@ -365,7 +895,23 @@ export const getPaymentMethodName = (chainId, verifierAddress) => {
     if (providerConfig) {
         return providerConfig.name;
     }
-    const config = providerConfigs(chainId ?? base.id)[verifierAddress] ?? getPaymentMethodConfig(chainId ?? base.id, verifierAddress);
+    // Check sub-providers directly (e.g., 'zelle-chase', 'zelle-bofa', 'zelle-citi')
+    // Sub-providers are nested under their parent provider key (e.g., subProviderConfigs.zelle['zelle-chase'])
+    const zelleSubConfig = subProviderConfigs.zelle?.[providerKey];
+    if (zelleSubConfig?.name) {
+        return zelleSubConfig.name;
+    }
+    if (typeof verifierAddress === 'string' && verifierAddress.length === 66) {
+        const contractProvider = getProviderByContractId(chainId ?? base.id, verifierAddress);
+        if (contractProvider) {
+            return contractProvider.name;
+        }
+        return 'Unknown';
+    }
+    const config = providerConfigs(chainId ?? base.id)[verifierAddress]
+        ?? (typeof verifierAddress === 'string' && verifierAddress.length === 42
+            ? getPaymentMethodConfig(chainId ?? base.id, verifierAddress)
+            : null);
     return config?.name || 'Unknown';
 };
 /**
@@ -415,7 +961,37 @@ export function getPaymentProviderMinimum(chainId, key) {
     return getPaymentMethodMinimum(chainId, key) ?? 0;
 }
 /**
- * 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 const externalPaymentMethods = {
+    // Pendle - registered on Base
+    '0x5908bb0c9b87763ac6171d4104847667e7f02b4c47b574fe890c1f439ed128bb': {
+        name: 'pendle',
+        originTxHash: '0x3ba1e1ae196ff5e29e09b934966e25faa34b7ec7edc371e6ef275916a9ce1f39',
+        chainId: 8453,
+        description: 'Pendle Finance payment method',
+    },
+};
+/**
+ * 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 const isExternalPaymentMethod = (paymentMethodId) => {
+    return paymentMethodId in externalPaymentMethods;
+};
+/**
+ * Get external payment method info
+ * @param paymentMethodId - The payment method ID
+ * @returns The external payment method info or undefined
+ */
+export const getExternalPaymentMethod = (paymentMethodId) => {
+    return externalPaymentMethods[paymentMethodId];
+};
+/**
+ * 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
@@ -424,16 +1000,150 @@ export const isPaymentMethodKnown = (chainId, verifierAddress) => {
     return !!getPaymentMethodConfig(chainId, verifierAddress);
 };
 /**
- * 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 const isPaymentMethodIdKnown = (chainId, paymentMethodId, verifierAddress) => {
+    // Check if it's an external payment method first
+    if (isExternalPaymentMethod(paymentMethodId)) {
+        return true;
+    }
+    // Fall back to checking providerConfigs if verifierAddress is provided
+    if (verifierAddress) {
+        return isPaymentMethodKnown(chainId, verifierAddress);
+    }
+    return false;
+};
+/**
+ * Get all payment methods including sub-providers
+ * @param includeSubProviders - Whether to include sub-providers as separate entries (default: false)
  * @returns All payment methods
  */
-export const getAllPaymentMethods = (chainId) => {
-    return Object.keys(providerConfigs(chainId));
+export const getAllPaymentMethods = (chainId, includeSubProviders = false) => {
+    const configs = providerConfigs(chainId);
+    const mainProviders = Object.keys(configs)
+        .filter(key => !isProviderDisabled(key, configs[key].disabled));
+    if (!includeSubProviders) {
+        return mainProviders;
+    }
+    const allProviders = [...mainProviders];
+    for (const key of mainProviders) {
+        const config = configs[key];
+        if (config.subProviders.size > 0) {
+            config.subProviders.forEach(subProvider => {
+                allProviders.push(subProvider.key);
+            });
+        }
+    }
+    return allProviders;
 };
 /**
- * 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 const verifiablePaymentMethods = (chainId) => {
-    return getAllPaymentMethods(chainId).filter(key => key !== providers.MANUAL);
+export const verifiablePaymentMethods = (chainId, includeSubProviders = false) => {
+    return getAllPaymentMethods(chainId, includeSubProviders).filter(key => key !== providers.MANUAL);
 };
+/**
+ * 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 function getCurrenciesForProvider(config) {
+    const supportedIds = new Set(config.list);
+    return Object.values(SUPPORTED_CURRENCIES).filter((currency) => supportedIds.has(currency.contractId));
+}
+/** Set of all sub-provider keys for fast lookup */
+const subProviderKeySet = new Set(Object.values(subProviders));
+/** Set of all main provider keys for fast lookup */
+const providerKeySet = new Set(Object.values(providers));
+/**
+ * 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 function isSubProviderKey(key) {
+    return subProviderKeySet.has(key);
+}
+/**
+ * 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 function getParentProviderKey(key) {
+    if (!isSubProviderKey(key)) {
+        return null;
+    }
+    // Sub-provider keys follow the pattern '{parent}-{subName}'
+    const parentKey = key.split('-')[0];
+    if (parentKey && providerKeySet.has(parentKey)) {
+        return parentKey;
+    }
+    return 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 function getExtensionPlatform(key) {
+    const parentKey = getParentProviderKey(key);
+    if (parentKey) {
+        // It's a sub-provider - look up the extensionPlatform from config
+        const subConfig = subProviderConfigs[parentKey]?.[key];
+        if (subConfig?.extensionPlatform) {
+            return subConfig.extensionPlatform;
+        }
+    }
+    // Main provider - use the key as the platform
+    return key;
+}
+/**
+ * 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 function getProviderIconStack(chainId, key) {
+    const configs = providerConfigs(chainId);
+    // Check if this is a sub-provider
+    const parentKey = getParentProviderKey(key);
+    if (parentKey) {
+        const parentConfig = configs[parentKey];
+        const subConfig = subProviderConfigs[parentKey]?.[key];
+        if (parentConfig && subConfig) {
+            return [
+                { icon: parentConfig.icon, color: parentConfig.color, name: parentConfig.name },
+                { icon: subConfig.icon ?? parentConfig.icon, color: subConfig.color ?? parentConfig.color, name: subConfig.name },
+            ];
+        }
+    }
+    // Main provider - return single icon
+    const config = configs[key];
+    if (config) {
+        return [{ icon: config.icon, color: config.color, name: config.name }];
+    }
+    // Fallback to manual
+    return [{ icon: configs.manual.icon, color: configs.manual.color, name: 'Unknown' }];
+}