@provex/utils 1.11.0 → 2.0.0

package/dist/conversionRates.test.js

@@ -56,6 +56,13 @@ describe('conversionRates', () => {
             assert.ok(usdRates, 'Should have USD rates');
             assert.equal(usdRates.length, 1);
         });
+        it('keeps an event whose rate value is missing, with an empty value, instead of dropping the deposit', () => {
+            const events = [
+                createMockEvent({ currentDepositConversionRateUpdated: { value: null } }),
+            ];
+            const result = processConversionRates({ chainId: base.id, events });
+            assert.equal(result.get('venmo')?.get(USD_CONTRACT_ID)?.[0]?.value, '');
+        });
         it('should skip events without currentDepositConversionRateUpdated', () => {
             const events = [
                 createMockEvent({ currentDepositConversionRateUpdated: undefined }),
@@ -327,6 +334,17 @@ describe('conversionRates', () => {
             const result = getPrimaryConversionRate(new Map());
             assert.equal(result, null);
         });
+        it('skips a provider that holds no rates and finds one under a later provider', () => {
+            const eurRate = createMockEvent({ currency: EUR_CONTRACT_ID });
+            const providerRates = new Map([
+                ['venmo', new Map()],
+                ['zelle', new Map([[EUR_CONTRACT_ID, eurRate]])],
+            ]);
+            assert.equal(getPrimaryConversionRate(providerRates)?.currency, EUR_CONTRACT_ID);
+        });
+        it('returns null when every provider holds no rates', () => {
+            assert.equal(getPrimaryConversionRate(new Map([['venmo', new Map()]])), null);
+        });
         it('should prioritize USD over other currencies', () => {
             const usdRate = createMockEvent({ currency: USD_CONTRACT_ID });
             const eurRate = createMockEvent({ currency: EUR_CONTRACT_ID });

package/dist/currencies.d.ts

@@ -113,6 +113,12 @@ export declare class Currency implements CurrencyInfo {
  * @param currencyCode - The currency code
  */
 export declare function generateCurrencyId(currencyCode: string): string;
+/**
+ * Get the flag for a country
+ * @param countryCode - The country code
+ * @returns The flag image path
+ */
+export declare const flagFromCountries: (countryCode: string) => string;
 /**
  * Registry of all supported fiat currencies.
  *

package/dist/currencies.js

@@ -132,7 +132,7 @@ export function generateCurrencyId(currencyCode) {
  * @param countryCode - The country code
  * @returns The flag image path
  */
-const flagFromCountries = (countryCode) => {
+export const flagFromCountries = (countryCode) => {
     return countries.find((country) => country.code === countryCode)?.flag ?? '';
 };
 /**

package/dist/currencies.test.js

@@ -1,6 +1,6 @@
-import { describe, it } from 'node:test';
+import { describe, it, mock } from 'node:test';
 import assert from 'node:assert/strict';
-import { SUPPORTED_CURRENCIES, getCurrencyInfo, getCurrencyByContractId, getCurrencyNameByContractId, getAllSupportedCurrencies, isSupportedCurrency, formatCurrencyAmount, tickerToContractId, generateCurrencyId, formatDefaultRate, formatCurrencyTotal, formatTokenTotal, Currency, } from './currencies.js';
+import { SUPPORTED_CURRENCIES, getCurrencyInfo, getCurrencyByContractId, getCurrencyNameByContractId, getAllSupportedCurrencies, isSupportedCurrency, formatCurrencyAmount, tickerToContractId, generateCurrencyId, formatDefaultRate, formatCurrencyTotal, formatTokenTotal, flagFromCountries, Currency, } from './currencies.js';
 describe('currencies', () => {
     describe('SUPPORTED_CURRENCIES', () => {
         it('should have exactly 36 supported currencies', () => {
@@ -459,3 +459,30 @@ describe('currencies', () => {
         });
     });
 });
+describe('flagFromCountries', () => {
+    it('returns the flag of a known country code', () => {
+        assert.equal(flagFromCountries('GBP'), SUPPORTED_CURRENCIES.GBP.flag);
+    });
+    it('returns an empty string for an unknown code, so a currency without a flag still renders', () => {
+        assert.equal(flagFromCountries('NOT-A-CODE'), '');
+    });
+    it('leaves no supported currency without a flag', () => {
+        for (const currency of Object.values(SUPPORTED_CURRENCIES)) {
+            assert.ok(currency.flag, `${currency.ticker} has no flag`);
+        }
+    });
+});
+describe('formatCurrencyTotal: an unexpected Intl failure', () => {
+    it('rethrows an error that is not the unknown-ticker RangeError, so real faults are not hidden', () => {
+        const unseenCurrency = { ...SUPPORTED_CURRENCIES.USD, ticker: 'ZZZ', symbol: 'Z' };
+        mock.method(Intl, 'NumberFormat', () => {
+            throw new TypeError('boom');
+        });
+        try {
+            assert.throws(() => formatCurrencyTotal({ amount: 100n, currency: unseenCurrency, locale: 'fr-FR' }), TypeError);
+        }
+        finally {
+            mock.restoreAll();
+        }
+    });
+});

package/dist/fees.js

@@ -144,9 +144,6 @@ export function normalizeFeePrecision(rawFee) {
  * @internal
  */
 function formatFromNumber(percentage) {
-    if (percentage === 0) {
-        return '0%';
-    }
     if (Number.isInteger(percentage)) {
         return `${percentage}%`;
     }

package/dist/gating.test.js

@@ -14,7 +14,7 @@
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import { keccak256, toHex } from 'viem';
-import { buildGatingDigest, hashReferralFees, } from './gating.js';
+import { buildGatingDigest, hashReferralFees, signGatingApproval, } from './gating.js';
 // Shared inputs used to generate every golden vector below.
 const ORCHESTRATOR = '0x888888359E981B5225CA48fbCdCeff702FC3b888';
 const ESCROW = '0x777777779d229cdF3110e9de47943791c26300Ef';
@@ -104,3 +104,18 @@ test('v3 digest omits caller + referral hash and differs from v4', () => {
     const v4 = buildGatingDigest({ ...commonV4, referralFees: [] });
     assert.notEqual(v3, v4);
 });
+test('signGatingApproval hands the signer the raw digest, so the contract recovers the same hash', async () => {
+    const input = { ...commonV4, referralFees: [] };
+    const received = [];
+    const signature = await signGatingApproval({
+        signer: {
+            signMessage: async ({ message }) => {
+                received.push(message.raw);
+                return '0xabcd';
+            },
+        },
+        digest: input,
+    });
+    assert.deepEqual(received, [buildGatingDigest(input)]);
+    assert.equal(signature, '0xabcd');
+});

package/dist/ids.test.js

@@ -604,4 +604,52 @@ describe('ids', () => {
             }, /Unknown chainId|Hex length/);
         });
     });
+    describe('orderId.order.parse: unknown chain', () => {
+        it('rejects an id whose chain is not supported rather than returning a chain the app cannot serve', () => {
+            const id = orderId.order.serialize({
+                timestamp: 1000n,
+                chainId: 8453n,
+                transactionIndex: 5n,
+                logIndex: 3n,
+                name: 'deposit_received',
+            });
+            // Overwrite the final 4 bytes (chain id) with an unsupported chain.
+            const unsupported = `${id.slice(0, -8)}0000270f`;
+            assert.throws(() => orderId.order.parse(unsupported), /Unknown chainId parsed from order id: 9999/);
+        });
+        it('leaves the name undefined for an event type id that has no registered name', () => {
+            const id = orderId.order.serialize({
+                timestamp: 1000n,
+                chainId: 8453n,
+                transactionIndex: 5n,
+                logIndex: 3n,
+                name: 'deposit_received',
+            });
+            // The event type is the single byte after timestamp (8) and tx index (4).
+            const offset = 2 + (8 + 4) * 2;
+            const unnamed = `${id.slice(0, offset)}ff${id.slice(offset + 2)}`;
+            const parsed = orderId.order.parse(unnamed);
+            assert.equal(parsed.eventTypeId, 255);
+            assert.equal(parsed.name, undefined);
+        });
+    });
+    describe('orderId.stat.parse', () => {
+        const stat = {
+            type: 'hour',
+            event: 'deposit',
+            currency: '0x1234567890123456789012345678901234567890123456789012345678901234',
+            token: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+            verifier: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
+            version: 'v2',
+        };
+        it('recovers the hour-bucketed timestamp and the chain from a serialized stat id', () => {
+            const id = orderId.stat.serialize({ ...stat, timestamp: 3700n, chainId: 8453n });
+            assert.deepEqual(orderId.stat.parse(id), { timestamp: 3600n, chainId: 8453 });
+        });
+        it('rejects an id whose chain is not supported', () => {
+            const id = orderId.stat.serialize({ ...stat, timestamp: 3700n, chainId: 8453n });
+            const unsupported = `${id.slice(0, -8)}0000270f`;
+            assert.throws(() => orderId.stat.parse(unsupported), /Unknown chainId parsed from stat id: 9999/);
+        });
+    });
 });

package/dist/payment.d.ts

@@ -23,6 +23,21 @@
  * @see {@link currencies} for supported currencies per provider
  */
 import { type Hex } from "viem";
+/**
+ * Pick a value from the Vite (browser) and Node environments.
+ *
+ * Vite wins over Node. Within Node, the bare name wins over its `VITE_` twin.
+ *
+ * @param params.name - Variable name without the `VITE_` prefix.
+ * @param params.viteEnv - `import.meta.env`, or undefined outside Vite.
+ * @param params.nodeEnv - `process.env`, or undefined outside Node.
+ * @returns The value, or an empty string when none is set.
+ */
+export declare function readEnvFrom({ name, viteEnv, nodeEnv, }: {
+    name: string;
+    viteEnv?: Record<string, string | undefined>;
+    nodeEnv?: Record<string, string | undefined>;
+}): string;
 /** 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";
@@ -299,6 +314,41 @@ export declare const dataEncoding: (data: string) => string;
 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>>>;
+/**
+ * Verifier addresses for one payment method on one chain.
+ *
+ * Prefers the v2-specific verifier, so v2 history stays correctly categorized
+ * on chains that also run v3. Falls back to the v3 unified verifier for v3-only
+ * chains and v3-only payment methods.
+ *
+ * @param params.verifierKey - Key of the v2 verifier, such as `venmoReclaimVerifier`.
+ * @param params.v2Contracts - The chain's v2 contract set, if any.
+ * @param params.v3Contracts - The chain's v3 contract set, if any.
+ * @returns Verifier addresses; empty when neither generation names one.
+ */
+export declare function resolveVerifierAddresses({ verifierKey, v2Contracts, v3Contracts, }: {
+    verifierKey: string;
+    v2Contracts?: Partial<Record<string, unknown>>;
+    v3Contracts?: {
+        unifiedPaymentVerifier?: readonly string[];
+    };
+}): string[];
+/**
+ * The icon, color and username label a sub-provider shows. Each falls back to
+ * the parent rail's value when the sub-provider does not set its own.
+ *
+ * @param params.subProvider - The sub-provider config.
+ * @param params.parent - The parent rail's config.
+ * @returns The resolved icon, color and username label.
+ */
+export declare function inheritSubProviderLook({ subProvider, parent, }: {
+    subProvider: Pick<PaymentSubProviderConfig, 'icon' | 'color' | 'usernameType'>;
+    parent: Pick<PaymentConfig, 'icon' | 'color' | 'usernameType'>;
+}): {
+    icon: string;
+    color: string;
+    usernameType: string;
+};
 /** Payment method icon mappings */
 export declare const providerConfigs: (chainId: ChainId) => Record<ProviderKey, PaymentConfig>;
 /**

package/dist/payment.js

@@ -27,13 +27,26 @@ import { getAddress, parseUnits, zeroAddress, keccak256, stringToHex, isAddress
  * 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 ?? '';
+    return readEnvFrom({
+        name,
+        viteEnv: import.meta.env,
+        nodeEnv: globalThis.process?.env,
+    });
+}
+/**
+ * Pick a value from the Vite (browser) and Node environments.
+ *
+ * Vite wins over Node. Within Node, the bare name wins over its `VITE_` twin.
+ *
+ * @param params.name - Variable name without the `VITE_` prefix.
+ * @param params.viteEnv - `import.meta.env`, or undefined outside Vite.
+ * @param params.nodeEnv - `process.env`, or undefined outside Node.
+ * @returns The value, or an empty string when none is set.
+ */
+export function readEnvFrom({ name, viteEnv, nodeEnv, }) {
+    const viteValue = viteEnv?.[`VITE_${name}`];
+    const nodeValue = nodeEnv?.[name] ?? nodeEnv?.[`VITE_${name}`];
+    return viteValue ?? nodeValue ?? '';
 }
 /**
  * Parse a comma-separated list of provider keys from an env var.
@@ -287,6 +300,40 @@ export const subProviderConfigs = {
         },
     },
 };
+/**
+ * Verifier addresses for one payment method on one chain.
+ *
+ * Prefers the v2-specific verifier, so v2 history stays correctly categorized
+ * on chains that also run v3. Falls back to the v3 unified verifier for v3-only
+ * chains and v3-only payment methods.
+ *
+ * @param params.verifierKey - Key of the v2 verifier, such as `venmoReclaimVerifier`.
+ * @param params.v2Contracts - The chain's v2 contract set, if any.
+ * @param params.v3Contracts - The chain's v3 contract set, if any.
+ * @returns Verifier addresses; empty when neither generation names one.
+ */
+export function resolveVerifierAddresses({ verifierKey, v2Contracts, v3Contracts, }) {
+    if (v2Contracts && verifierKey in v2Contracts) {
+        const value = v2Contracts[verifierKey];
+        return Array.isArray(value) ? value : [];
+    }
+    return [...(v3Contracts?.unifiedPaymentVerifier ?? [])];
+}
+/**
+ * The icon, color and username label a sub-provider shows. Each falls back to
+ * the parent rail's value when the sub-provider does not set its own.
+ *
+ * @param params.subProvider - The sub-provider config.
+ * @param params.parent - The parent rail's config.
+ * @returns The resolved icon, color and username label.
+ */
+export function inheritSubProviderLook({ subProvider, parent, }) {
+    return {
+        icon: subProvider.icon || parent.icon,
+        color: subProvider.color || parent.color,
+        usernameType: subProvider.usernameType || parent.usernameType,
+    };
+}
 /** Payment method icon mappings */
 export const providerConfigs = (chainId) => {
     const v2Contracts = contracts.v2[chainId];
@@ -296,18 +343,7 @@ export const providerConfigs = (chainId) => {
      * 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 [];
-    };
+    const getV2Verifiers = (verifierKey) => resolveVerifierAddresses({ verifierKey, v2Contracts, v3Contracts });
     return {
         venmo: {
             key: providers.VENMO,
@@ -821,9 +857,7 @@ export const providerByContractId = (chainId) => {
                 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,
+                ...inheritSubProviderLook({ subProvider, parent: config }),
                 v2Verifiers: subProvider.v2Verifiers(chainId),
                 subProviders: new Set(),
             };
@@ -864,14 +898,8 @@ 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;
+        // The map holds every provider and sub-provider contract id, so a miss is unknown.
+        return key ?? providers.MANUAL;
     }
     // Otherwise treat it as an address
     try {
@@ -941,7 +969,7 @@ export const getPaymentMethodName = (chainId, verifierAddress) => {
     if (zelleSubConfig?.name) {
         return zelleSubConfig.name;
     }
-    if (typeof verifierAddress === 'string' && verifierAddress.length === 66) {
+    if (verifierAddress.length === 66) {
         const contractProvider = getProviderByContractId(chainId ?? base.id, verifierAddress);
         if (contractProvider) {
             return contractProvider.name;
@@ -949,7 +977,7 @@ export const getPaymentMethodName = (chainId, verifierAddress) => {
         return 'Unknown';
     }
     const config = providerConfigs(chainId ?? base.id)[verifierAddress]
-        ?? (typeof verifierAddress === 'string' && verifierAddress.length === 42
+        ?? (verifierAddress.length === 42
             ? getPaymentMethodConfig(chainId ?? base.id, verifierAddress)
             : null);
     return config?.name || 'Unknown';
@@ -998,7 +1026,7 @@ export function calculateEffectiveMinimum(chainId, userMinAmountWei, tokenInfo,
  * @returns The minimum limit
  */
 export function getPaymentProviderMinimum(chainId, key) {
-    return getPaymentMethodMinimum(chainId, key) ?? 0;
+    return getPaymentMethodMinimum(chainId, key);
 }
 /**
  * External/unregistered payment methods that are known but not in providerConfigs.
@@ -1253,7 +1281,7 @@ export function getCurrenciesForProvider(config) {
  */
 export function currencyCapableProviders(chainId, currency) {
     const configs = providerConfigs(chainId);
-    return verifiablePaymentMethods(chainId).filter((key) => configs[key]?.list.includes(currency.contractId) ?? false);
+    return verifiablePaymentMethods(chainId).filter((key) => configs[key].list.includes(currency.contractId));
 }
 /**
  * Whether a provider can actually serve a buyer paying in `currency` on this
@@ -1292,12 +1320,10 @@ export function selectVolumeDefaultProvider(args) {
         if (capableKeys.has(key))
             return key;
     }
-    return capable[0] ?? null;
+    return capable[0];
 }
 /** 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
@@ -1317,11 +1343,8 @@ export function getParentProviderKey(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;
+    // Every sub-provider's parent is a provider key (pinned by a test).
+    return key.split('-')[0];
 }
 /**
  * Collapse a sub-provider key to the rail it belongs to.
@@ -1349,8 +1372,6 @@ export function getParentProviderKey(key) {
  * @returns The rail key, e.g. `'zelle'`.
  */
 export function resolveRailProviderKey(key) {
-    if (!isSubProviderKey(key))
-        return key;
     return getParentProviderKey(key) ?? key;
 }
 /**
@@ -1420,14 +1441,14 @@ export function getProviderIconStack(chainId, key) {
     // Check if this is a sub-provider
     const parentKey = getParentProviderKey(key);
     if (parentKey) {
+        // A sub-provider key always has a parent config and its own entry.
         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 },
-            ];
-        }
+        const subConfig = subProviderConfigs[parentKey][key];
+        const { icon, color } = inheritSubProviderLook({ subProvider: subConfig, parent: parentConfig });
+        return [
+            { icon: parentConfig.icon, color: parentConfig.color, name: parentConfig.name },
+            { icon, color, name: subConfig.name },
+        ];
     }
     // Main provider - return single icon
     const config = configs[key];

package/dist/payment.lookup.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Tests for payment lookups by key, hash and address, and for
+ * the pure helpers that resolve verifiers, environment values and sub-provider looks.
+ */
+export {};

package/dist/payment.lookup.test.js

@@ -0,0 +1,169 @@
+/**
+ * @fileoverview Tests for payment lookups by key, hash and address, and for
+ * the pure helpers that resolve verifiers, environment values and sub-provider looks.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { base, pulsechain } from 'viem/chains';
+import { getParentProviderKey, getPaymentMethodConfig, getPaymentMethodMinimum, getPaymentMethodName, getPaymentProviderMinimum, getProviderIconStack, inheritSubProviderLook, providerConfigs, providerKeyToContractId, providers, readEnvFrom, resolveVerifierAddresses, subProviders, verifierGetsKey, } from './payment.js';
+const A = '0x1111111111111111111111111111111111111111';
+const B = '0x2222222222222222222222222222222222222222';
+describe('readEnvFrom', () => {
+    it('prefers the Vite value over Node, because the browser build is the deployed one', () => {
+        const value = readEnvFrom({
+            name: 'X',
+            viteEnv: { VITE_X: 'vite' },
+            nodeEnv: { X: 'node' },
+        });
+        assert.equal(value, 'vite');
+    });
+    it('prefers the bare Node name over its VITE_ twin', () => {
+        assert.equal(readEnvFrom({ name: 'X', nodeEnv: { X: 'bare', VITE_X: 'twin' } }), 'bare');
+    });
+    it('falls back to the VITE_ twin in Node', () => {
+        assert.equal(readEnvFrom({ name: 'X', nodeEnv: { VITE_X: 'twin' } }), 'twin');
+    });
+    it('returns an empty string when nothing is set or no environment exists', () => {
+        assert.equal(readEnvFrom({ name: 'X', viteEnv: {}, nodeEnv: {} }), '');
+        assert.equal(readEnvFrom({ name: 'X' }), '');
+    });
+});
+describe('resolveVerifierAddresses', () => {
+    it('returns the v2-specific verifiers when the v2 set names the method', () => {
+        const result = resolveVerifierAddresses({
+            verifierKey: 'venmoReclaimVerifier',
+            v2Contracts: { venmoReclaimVerifier: [A] },
+            v3Contracts: { unifiedPaymentVerifier: [B] },
+        });
+        assert.deepEqual(result, [A]);
+    });
+    it('returns nothing, not the v3 verifier, when the v2 entry is not a list', () => {
+        // A v2 key that holds a single address (like `usdc`) is not a verifier list.
+        // Falling to v3 there would mislabel v2 history as v3.
+        const result = resolveVerifierAddresses({
+            verifierKey: 'usdc',
+            v2Contracts: { usdc: A },
+            v3Contracts: { unifiedPaymentVerifier: [B] },
+        });
+        assert.deepEqual(result, []);
+    });
+    it('falls back to the v3 unified verifier when v2 does not name the method', () => {
+        const result = resolveVerifierAddresses({
+            verifierKey: 'paypalReclaimVerifier',
+            v2Contracts: { venmoReclaimVerifier: [A] },
+            v3Contracts: { unifiedPaymentVerifier: [B] },
+        });
+        assert.deepEqual(result, [B]);
+    });
+    it('falls back to the v3 unified verifier on a chain with no v2 set', () => {
+        assert.deepEqual(resolveVerifierAddresses({ verifierKey: 'k', v3Contracts: { unifiedPaymentVerifier: [B] } }), [B]);
+    });
+    it('returns an empty list when neither generation names a verifier', () => {
+        assert.deepEqual(resolveVerifierAddresses({ verifierKey: 'k' }), []);
+        assert.deepEqual(resolveVerifierAddresses({ verifierKey: 'k', v3Contracts: {} }), []);
+    });
+});
+describe('inheritSubProviderLook', () => {
+    const parent = { icon: 'parent-icon', color: 'parent-color', usernameType: 'Parent Label' };
+    it('uses the sub-provider values when it sets them', () => {
+        const look = inheritSubProviderLook({
+            subProvider: { icon: 'sub-icon', color: 'sub-color', usernameType: 'Sub Label' },
+            parent,
+        });
+        assert.deepEqual(look, { icon: 'sub-icon', color: 'sub-color', usernameType: 'Sub Label' });
+    });
+    it('inherits each value from the parent rail when the sub-provider omits it', () => {
+        assert.deepEqual(inheritSubProviderLook({ subProvider: {}, parent }), parent);
+    });
+});
+describe('getParentProviderKey', () => {
+    it('names a real rail for every sub-provider, so the rail can always be looked up', () => {
+        const railKeys = new Set(Object.values(providers));
+        for (const subProviderKey of Object.values(subProviders)) {
+            const parent = getParentProviderKey(subProviderKey);
+            assert.ok(parent !== null && railKeys.has(parent), `${subProviderKey} has no parent rail`);
+        }
+    });
+    it('returns null for a key that is not a sub-provider', () => {
+        assert.equal(getParentProviderKey('venmo'), null);
+        assert.equal(getParentProviderKey('zelle-unknown'), null);
+    });
+});
+describe('getProviderIconStack', () => {
+    it('stacks the parent rail icon under the bank icon for a sub-provider', () => {
+        const configs = providerConfigs(base.id);
+        const stack = getProviderIconStack(base.id, subProviders.CHASE);
+        assert.equal(stack.length, 2);
+        assert.equal(stack[0].icon, configs.zelle.icon);
+        assert.equal(stack[1].name, 'Chase');
+        assert.equal(stack[1].icon, 'simple-icons:chase');
+        // Chase sets no color of its own, so it takes the rail's.
+        assert.equal(stack[1].color, configs.zelle.color);
+    });
+    it('returns a single entry for a main rail', () => {
+        const stack = getProviderIconStack(base.id, providers.VENMO);
+        assert.equal(stack.length, 1);
+        assert.equal(stack[0].name, 'Venmo');
+    });
+    it('names an unrecognised key Unknown, with the manual icon, instead of throwing', () => {
+        const stack = getProviderIconStack(base.id, 'nonsense');
+        assert.deepEqual(stack, [
+            { icon: providerConfigs(base.id).manual.icon, color: providerConfigs(base.id).manual.color, name: 'Unknown' },
+        ]);
+    });
+});
+describe('minimum limits', () => {
+    it('reads the minimum for a provider on the default chain when no chain is given', () => {
+        assert.equal(getPaymentMethodMinimum(null, providers.VENMO), providerConfigs(base.id).venmo.limits.min);
+    });
+    it('returns the same minimum through the provider-level helper', () => {
+        assert.equal(getPaymentProviderMinimum(pulsechain.id, providers.VENMO), getPaymentMethodMinimum(pulsechain.id, providers.VENMO));
+    });
+    it('returns zero for an unknown provider rather than NaN', () => {
+        assert.equal(getPaymentMethodMinimum(base.id, 'nonsense'), 0);
+    });
+});
+describe('lookup by payment-method hash', () => {
+    const zelleChaseHash = providerKeyToContractId(subProviders.CHASE);
+    const unknownHash = `0x${'ab'.repeat(32)}`;
+    it('verifierGetsKey resolves a sub-provider hash through the contract id map', () => {
+        assert.equal(verifierGetsKey(base.id, zelleChaseHash), subProviders.CHASE);
+    });
+    it('verifierGetsKey defaults to the base chain when none is given', () => {
+        assert.equal(verifierGetsKey(null, providerKeyToContractId(providers.VENMO)), providers.VENMO);
+    });
+    it('getPaymentMethodConfig returns the config for a known hash and null for an unknown one', () => {
+        assert.equal(getPaymentMethodConfig(base.id, providerKeyToContractId(providers.WISE))?.key, providers.WISE);
+        assert.equal(getPaymentMethodConfig(null, providerKeyToContractId(providers.WISE))?.key, providers.WISE);
+        assert.equal(getPaymentMethodConfig(base.id, unknownHash), null);
+    });
+    it('getPaymentMethodConfig returns null for text that is neither an address nor a hash', () => {
+        assert.equal(getPaymentMethodConfig(base.id, 'venmo'), null);
+    });
+    it('getPaymentMethodConfig finds a v2 verifier address on every chain when none is given', () => {
+        const venmoVerifier = providerConfigs(base.id).venmo.v2Verifiers[0];
+        assert.equal(getPaymentMethodConfig(null, venmoVerifier)?.key, providers.VENMO);
+    });
+    it('getPaymentMethodName names a hash, falls back to Unknown for a strange one', () => {
+        assert.equal(getPaymentMethodName(base.id, zelleChaseHash), 'Chase');
+        assert.equal(getPaymentMethodName(base.id, unknownHash), 'Unknown');
+    });
+    it('getPaymentMethodName searches the default chain for every kind of input when none is given', () => {
+        const venmoVerifier = providerConfigs(base.id).venmo.v2Verifiers[0];
+        assert.equal(getPaymentMethodName(null, zelleChaseHash), 'Chase');
+        assert.equal(getPaymentMethodName(null, venmoVerifier), 'Venmo');
+        assert.equal(getPaymentMethodName(null, 'nonsense'), 'Unknown');
+    });
+    it('getPaymentMethodName names a provider key, on the default chain when none is given', () => {
+        assert.equal(getPaymentMethodName(null, providers.VENMO), 'Venmo');
+    });
+    it('getPaymentMethodName names a sub-provider key', () => {
+        assert.equal(getPaymentMethodName(base.id, subProviders.CITI), 'Citi');
+    });
+    it('getPaymentMethodName names a verifier address, and says Unknown for a stranger', () => {
+        const venmoVerifier = providerConfigs(base.id).venmo.v2Verifiers[0];
+        assert.equal(getPaymentMethodName(base.id, venmoVerifier), 'Venmo');
+        assert.equal(getPaymentMethodName(base.id, '0x0000000000000000000000000000000000000dEaD'.slice(0, 42)), 'Unknown');
+        assert.equal(getPaymentMethodName(base.id, 'nonsense'), 'Unknown');
+    });
+});

package/dist/payment.providerLists.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Tests for the deployment switches that hide or force-show a
+ * payment rail.
+ *
+ * `DISABLED_PROVIDERS` and `ENABLED_PROVIDERS` are read once, on the first call,
+ * and cached in module state. Each test file runs in its own process, so this
+ * file sets both variables before any call and observes one fixed deployment:
+ *
+ * - disabled: `PayPal` and `zelle` (mixed case and padded, as a human writes it)
+ * - enabled: `venmo` and `paypal`
+ */
+export {};