@provex/utils 1.9.2 → 1.10.0-rc.20260912192040.fdbb8fc

package/dist/payment.currency.test.js

@@ -0,0 +1,134 @@
+/**
+ * @fileoverview Tests for currency-aware payment-provider selection.
+ *
+ * These exist because the Buy page auto-picked a payment method without ever
+ * consulting the buyer's currency. The volume leaders on every chain are
+ * United States dollar rails (Venmo, Zelle, Cash App), so a buyer who chose
+ * pounds or euros was seeded onto a rail that structurally cannot serve them
+ * and shown an empty order book. Each test below names the behaviour that
+ * failure would break, not just the value it returns.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { pulsechain } from 'viem/chains';
+import { providers, providerSupportsCurrency, selectVolumeDefaultProvider } from './payment.js';
+import { SUPPORTED_CURRENCIES } from './currencies.js';
+// Which providers are verifiable is DEPLOYMENT CONFIGURATION, not a fact about
+// the chain: `DISABLED_PROVIDERS` / `ENABLED_PROVIDERS` override the `disabled`
+// field in the registry, and staging already ships
+// `vite_enabled_providers: "paypal"`. The PayPal cases below passed only
+// because this process happens to inherit neither variable — the same
+// assertions failed the moment they ran under the user-interface test runner,
+// which loads an environment file that enables PayPal.
+//
+// Pin it rather than depend on the ambient value. The disabled list wins over
+// the enabled list, so this holds whatever the environment carries.
+//
+// Must be set before the first call into `payment.ts`, which memoizes both
+// lists on first use. Module scope is early enough; a `before()` hook is not,
+// once another suite in the same process has already called in.
+process.env.DISABLED_PROVIDERS = 'paypal';
+const chainId = pulsechain.id;
+describe('providerSupportsCurrency', () => {
+    it('refuses a United States dollar rail for a pounds buyer', () => {
+        // Venmo lists only the United States dollar. If this ever passes, the
+        // predicate has stopped reading the provider's currency list and the
+        // empty-order-book bug is back.
+        assert.equal(providerSupportsCurrency({
+            providerKey: providers.VENMO,
+            chainId,
+            currency: SUPPORTED_CURRENCIES.GBP,
+        }), false);
+    });
+    it('accepts a United States dollar rail for a dollar buyer', () => {
+        assert.equal(providerSupportsCurrency({
+            providerKey: providers.VENMO,
+            chainId,
+            currency: SUPPORTED_CURRENCIES.USD,
+        }), true);
+    });
+    it('accepts a pounds-only rail for a pounds buyer', () => {
+        // Monzo is pounds-only — the mirror image of the Venmo case, so a
+        // predicate hardcoded to either currency fails one of the two.
+        assert.equal(providerSupportsCurrency({
+            providerKey: providers.MONZO,
+            chainId,
+            currency: SUPPORTED_CURRENCIES.GBP,
+        }), true);
+    });
+    it('refuses a provider this deployment does not offer', () => {
+        // PayPal supports pounds in its own config but is switched off here.
+        // Offering it would seed a provider the buy flow cannot use.
+        assert.equal(providerSupportsCurrency({
+            providerKey: providers.PAYPAL,
+            chainId,
+            currency: SUPPORTED_CURRENCIES.GBP,
+        }), false);
+    });
+});
+describe('selectVolumeDefaultProvider', () => {
+    it('skips higher-volume dollar rails to reach one that serves pounds', () => {
+        // The regression test for the reported bug. Venmo leads on volume, so a
+        // currency-blind ranker returns it and the pounds buyer sees no liquidity.
+        const picked = selectVolumeDefaultProvider({
+            verifiersByVolume: [providers.VENMO, providers.ZELLE, providers.REVOLUT],
+            chainId,
+            currency: SUPPORTED_CURRENCIES.GBP,
+        });
+        assert.equal(picked, providers.REVOLUT);
+    });
+    it('still returns the volume leader for a dollar buyer', () => {
+        // Guards the other direction: the currency filter must not disturb the
+        // existing dollar behaviour, which is the overwhelming majority of traffic.
+        const picked = selectVolumeDefaultProvider({
+            verifiersByVolume: [providers.VENMO, providers.ZELLE, providers.REVOLUT],
+            chainId,
+            currency: SUPPORTED_CURRENCIES.USD,
+        });
+        assert.equal(picked, providers.VENMO);
+    });
+    it('falls back to a capable provider when the volume list has none', () => {
+        // Volume data only ever covers rails that have traded. A pounds buyer
+        // arriving before any pounds volume exists must still land somewhere
+        // usable rather than on the dollar leader.
+        const picked = selectVolumeDefaultProvider({
+            verifiersByVolume: [providers.VENMO, providers.ZELLE, providers.CASHAPP],
+            chainId,
+            currency: SUPPORTED_CURRENCIES.GBP,
+        });
+        // Asserted against a literal set, not against providerSupportsCurrency —
+        // routing the assertion through the same predicate under test lets a
+        // broken predicate satisfy it. Mutation testing caught exactly that.
+        assert.ok(picked !== null && [providers.REVOLUT, providers.WISE, providers.MONZO].includes(picked), `expected a pounds-capable provider, got ${String(picked)}`);
+    });
+    it('finds the sole provider for a single-rail currency', () => {
+        // MercadoPago is the only rail for Argentine pesos, and it never leads on
+        // volume, so a ranker that only reorders the volume list never reaches it.
+        const picked = selectVolumeDefaultProvider({
+            verifiersByVolume: [providers.VENMO, providers.ZELLE],
+            chainId,
+            currency: SUPPORTED_CURRENCIES.ARS,
+        });
+        assert.equal(picked, providers.MERCADOPAGO);
+    });
+    it('returns null when no verifiable provider serves the currency', () => {
+        // Roubles have no verifiable rail on PulseChain. Returning a provider here
+        // would be a lie the caller cannot detect; null lets it decide what to show.
+        const picked = selectVolumeDefaultProvider({
+            verifiersByVolume: [providers.VENMO, providers.ZELLE],
+            chainId,
+            currency: SUPPORTED_CURRENCIES.RUB,
+        });
+        assert.equal(picked, null);
+    });
+    it('ignores a volume entry this deployment does not offer', () => {
+        // Stats come from the indexer and can name a rail that is switched off
+        // here. Such an entry must never win, even when it lists the currency.
+        const picked = selectVolumeDefaultProvider({
+            verifiersByVolume: [providers.PAYPAL, providers.REVOLUT],
+            chainId,
+            currency: SUPPORTED_CURRENCIES.GBP,
+        });
+        assert.equal(picked, providers.REVOLUT);
+    });
+});

package/dist/payment.d.ts

@@ -459,13 +459,25 @@ export declare const getAllPaymentMethods: (chainId: ChainId, includeSubProvider
 export declare const verifiablePaymentMethods: (chainId: ChainId, includeSubProviders?: boolean) => ProviderKey[];
 /**
  * Compute every payment-method id (lowercased, 32-byte keccak hex) that
- * attaching the given parent provider would attempt to register on a deposit.
+ * attaching the given provider would register on a deposit.
  *
- * For a provider with no sub-providers this is just `[providerKeyToContractId(key)]`.
- * For a provider with sub-providers (currently only Zelle), the contract does
- * NOT accept the parent key — the UI fans it out into one row per sub-provider.
- * The returned list mirrors what {@link providerConfigs}-driven submission
- * code (e.g. AddPlatformModal) would put on the wire.
+ * **One id per provider — the rail's own, never a fan-out.** This used to
+ * expand a provider with sub-providers (only Zelle has any) into one id per
+ * bank, mirroring an `addPaymentMethods` call that submitted the same fan-out.
+ * That submission is gone: a Zelle attestation is issued for the rail, so
+ * `AddPlatformModal` now writes `keccak256("zelle")` alone (see
+ * {@link resolveRailProviderKey}). Leaving the expansion here desynchronized
+ * the availability gate from the write in both directions:
+ *
+ * - A deposit already holding `zelle` collided with none of the bank ids, so
+ *   Zelle kept showing as addable and the re-add reverted with
+ *   `PaymentMethodAlreadyExists`.
+ * - A deposit holding only the legacy bank ids collided on all of them, so the
+ *   rail — the one method its intents can actually be fulfilled on — looked
+ *   unavailable, blocking the very migration that repairs the deposit.
+ *
+ * Keeping this to the submitted id fixes both: the gate now answers exactly the
+ * question the contract will ask.
  *
  * Keys are lowercased so callers can compare directly against
  * `Deposit.attachedPaymentMethodIds` without per-call normalization.
@@ -489,12 +501,11 @@ export interface ProviderAvailabilityArgs {
  * it can still be attached to a deposit given the deposit's already-attached
  * payment method id hashes.
  *
- * Important — a parent provider is unavailable if ANY of its candidate hashes
- * (own contractId plus every sub-provider's contractId) is already attached.
- * This matches the contract's atomicity: `addPaymentMethods` submits the full
- * fan-out in one transaction and reverts with `PaymentMethodAlreadyExists`
- * the moment one row collides. A maker who already has Zelle-Chase attached
- * cannot re-add the Zelle parent without colliding on the Chase sub-row.
+ * Important — availability is decided against exactly the id the write would
+ * submit (see {@link getProviderPaymentMethodIds}), which is one id per rail.
+ * A maker holding the legacy `zelle-chase` row therefore still sees Zelle as
+ * addable, and should add it: the rail is the only method its intents can be
+ * fulfilled on, and attaching it is how such a deposit gets repaired.
  *
  * `manual` is always excluded from both lists.
  */
@@ -509,6 +520,41 @@ export declare function computeProviderAvailability(args: ProviderAvailabilityAr
  * button).
  */
 export declare function availableProviderConfigs(args: ProviderAvailabilityArgs): PaymentConfig[];
+/**
+ * A deposit that attached bank-level payment methods instead of the rail, and
+ * so holds no method any attestation can satisfy.
+ */
+export interface LegacySubProviderAttachment {
+    /** The rail to attach to make the deposit fulfillable, e.g. `'zelle'`. */
+    rail: ProviderKey;
+    /** The bank-level keys it holds instead, e.g. `['zelle-bofa', 'zelle-chase']`. */
+    attachedSubProviderKeys: SubProviderKey[];
+}
+/**
+ * Find rails this deposit attached at bank level but never at rail level.
+ *
+ * Such a deposit is not degraded — it is **inert**. `fetchMatchableDeposits`
+ * matches the rail id alone, so the deposit appears in no buyer's orderbook,
+ * and `resolveTargetedVerifier` returns null for it. Both were deliberate:
+ * bank-level rows once put these deposits in front of buyers who reserved
+ * funds, paid a real person, and then could not submit.
+ *
+ * The consequence is that the maker gets **no signal at all** — no failed
+ * orders, no complaints, just silence indistinguishable from no demand. Nothing
+ * in the product tells them, which is why this predicate exists: it is the only
+ * way the interface can raise the problem.
+ *
+ * The repair is one transaction. Attaching the rail makes the deposit
+ * matchable, and the bank-level rows are never consulted again on any buyer
+ * path — there is nothing to deactivate. They remain visible only on the
+ * owner's own platform list, which is cosmetic.
+ *
+ * Rails already holding their own id are skipped, as are disabled rails: it
+ * would be wrong to tell a maker to attach a method the chain won't accept.
+ *
+ * @returns One entry per rail needing repair; empty when the deposit is healthy.
+ */
+export declare function findLegacySubProviderAttachments(args: ProviderAvailabilityArgs): LegacySubProviderAttachment[];
 /**
  * Get supported currencies for a payment provider.
  * Returns only the currencies that are in the provider's supported list.
@@ -528,6 +574,68 @@ export declare function availableProviderConfigs(args: ProviderAvailabilityArgs)
  * ```
  */
 export declare function getCurrenciesForProvider(config: PaymentConfig): Currency[];
+/**
+ * Verifiable providers on `chainId` whose currency list contains `currency`,
+ * in registry order.
+ *
+ * "Verifiable" and "supports the currency" are two separate gates and both
+ * matter: a rail can list pounds and still be switched off here, and offering
+ * it would seed a rail the buy flow cannot settle on.
+ *
+ * Note that verifiability is DEPLOYMENT CONFIGURATION, not a property of the
+ * chain — `DISABLED_PROVIDERS` / `ENABLED_PROVIDERS` override the registry's
+ * `disabled` field, and staging ships `vite_enabled_providers: "paypal"` while
+ * production does not. Two environments on the same chain legitimately return
+ * different lists. Never hardcode the answer for a named provider.
+ *
+ * An empty `list` means "serves no currency", not "serves every currency".
+ * `manual` is the only provider with an empty list and `verifiablePaymentMethods`
+ * already drops it, so the rule is unobservable today — but it is the rule to
+ * keep, because seeding a buyer onto a rail that declares no currency support
+ * is the bug this function exists to prevent.
+ *
+ * @example
+ * ```ts
+ * currencyCapableProviders(pulsechain.id, SUPPORTED_CURRENCIES.GBP)
+ * // ['revolut', 'wise', 'monzo'] — no Venmo, Zelle or Cash App
+ * ```
+ */
+export declare function currencyCapableProviders(chainId: ChainId, currency: Currency): ProviderKey[];
+/**
+ * Whether a provider can actually serve a buyer paying in `currency` on this
+ * chain — it must be verifiable here AND list the currency.
+ *
+ * @example
+ * ```ts
+ * providerSupportsCurrency({ providerKey: providers.VENMO, chainId: pulsechain.id, currency: SUPPORTED_CURRENCIES.GBP })
+ * // false — Venmo is a United States dollar rail
+ * ```
+ */
+export declare function providerSupportsCurrency(args: {
+    readonly providerKey: ProviderKey;
+    readonly chainId: ChainId;
+    readonly currency: Currency;
+}): boolean;
+/**
+ * Pick a default payment method for a buyer paying in `currency`, preferring
+ * the highest-volume rail that can actually serve them.
+ *
+ * `verifiersByVolume` is the monthly-volume ranking, highest first. The volume
+ * leaders are United States dollar rails on every chain, so ranking without
+ * the currency gate seeds a pounds or euro buyer onto a rail that lists only
+ * dollars and shows them an empty order book. Falls back to the first capable
+ * provider in registry order when no ranked rail qualifies — volume data only
+ * covers rails that have already traded, which a new currency has not.
+ *
+ * @returns The chosen provider, or `null` when no verifiable provider on this
+ *   chain serves the currency at all. Null rather than an arbitrary provider,
+ *   so the caller can tell "nothing can serve this" from a real choice.
+ */
+export declare function selectVolumeDefaultProvider(args: {
+    readonly verifiersByVolume: readonly ProviderKey[];
+    readonly chainId: ChainId;
+    readonly currency: Currency;
+}): ProviderKey | null;
 /**
  * Check if a provider key is a sub-provider (e.g., 'zelle-chase', 'zelle-bofa')
  * @param key - The provider key to check
@@ -541,20 +649,38 @@ export declare function isSubProviderKey(key: string): key is SubProviderKey;
  * @returns The parent provider key (e.g., 'zelle') or null
  */
 export declare function getParentProviderKey(key: string): ProviderKey | null;
+/**
+ * Collapse a sub-provider key to the rail it belongs to.
+ *
+ * A sub-provider names a bank the buyer captures from — it is a routing detail
+ * of the capture step, not an identity of its own. Everything keyed by rail
+ * rather than by bank MUST collapse through here:
+ *
+ * - **The on-chain payment method.** A Zelle attestation is issued for the
+ *   rail: every bank template in `@zkp2p/providers` declares
+ *   `metadata.platform: "zelle"`, and the enclave verify route is
+ *   `zelle/transfer_zelle_{bank}` — the bank rides in the ACTION type, never
+ *   the platform. So `keccak256("zelle")` is the only payment method a Zelle
+ *   payment can ever satisfy. Deposits that attached `zelle-chase` and friends
+ *   accept intents no attestation can fulfil.
+ * - **Off-chain maker records.** Makers register once at rail level, so a
+ *   lookup keyed by `(provider, payeeDetailsHash)` misses the row unless the
+ *   bank is collapsed away. Skipping this in verify-intent once produced a 400
+ *   "maker contact could not be verified" for every buy on such a deposit.
+ *
+ * Non-sub-provider keys pass through unchanged, so this is safe to apply
+ * unconditionally.
+ *
+ * @param key - Provider or sub-provider key, e.g. `'zelle-chase'`.
+ * @returns The rail key, e.g. `'zelle'`.
+ */
+export declare function resolveRailProviderKey(key: string): string;
 /**
  * Canonicalize a provider key for off-chain maker-record lookups.
  *
- * Makers register once at the parent provider level (e.g. `zelle`) and the
- * deposit's on-chain `paymentMethodId` is fanned out to sub-providers
- * (`zelle-chase`, `zelle-bofa`, …). Every off-chain lookup keyed by
- * `(provider, payeeDetailsHash)` MUST collapse the sub-provider back to
- * its parent or it will miss the row.
- *
- * Use this anywhere you'd otherwise inline the
- * `isSubProviderKey(k) ? getParentProviderKey(k) : k` ternary so the
- * normalization can't drift between call sites — verify-intent regressed
- * by skipping it and produced 400 "maker contact could not be verified"
- * for every buy on a sub-provider deposit.
+ * @deprecated Prefer {@link resolveRailProviderKey}, which names the concept
+ * both call-site families share. Retained because the off-chain lookup sites
+ * read better with an API-flavoured name.
  */
 export declare function resolveApiProviderKey(key: string): string;
 /**

package/dist/payment.js

@@ -1087,35 +1087,42 @@ export const verifiablePaymentMethods = (chainId, includeSubProviders = false) =
 };
 /**
  * Compute every payment-method id (lowercased, 32-byte keccak hex) that
- * attaching the given parent provider would attempt to register on a deposit.
+ * attaching the given provider would register on a deposit.
  *
- * For a provider with no sub-providers this is just `[providerKeyToContractId(key)]`.
- * For a provider with sub-providers (currently only Zelle), the contract does
- * NOT accept the parent key — the UI fans it out into one row per sub-provider.
- * The returned list mirrors what {@link providerConfigs}-driven submission
- * code (e.g. AddPlatformModal) would put on the wire.
+ * **One id per provider — the rail's own, never a fan-out.** This used to
+ * expand a provider with sub-providers (only Zelle has any) into one id per
+ * bank, mirroring an `addPaymentMethods` call that submitted the same fan-out.
+ * That submission is gone: a Zelle attestation is issued for the rail, so
+ * `AddPlatformModal` now writes `keccak256("zelle")` alone (see
+ * {@link resolveRailProviderKey}). Leaving the expansion here desynchronized
+ * the availability gate from the write in both directions:
+ *
+ * - A deposit already holding `zelle` collided with none of the bank ids, so
+ *   Zelle kept showing as addable and the re-add reverted with
+ *   `PaymentMethodAlreadyExists`.
+ * - A deposit holding only the legacy bank ids collided on all of them, so the
+ *   rail — the one method its intents can actually be fulfilled on — looked
+ *   unavailable, blocking the very migration that repairs the deposit.
+ *
+ * Keeping this to the submitted id fixes both: the gate now answers exactly the
+ * question the contract will ask.
  *
  * Keys are lowercased so callers can compare directly against
  * `Deposit.attachedPaymentMethodIds` without per-call normalization.
  */
 export function getProviderPaymentMethodIds(config) {
-    const subProviders = config.subProviders;
-    if (subProviders && subProviders.size > 0) {
-        return Array.from(subProviders).map(sub => providerKeyToContractId(sub.key).toLowerCase());
-    }
-    return [providerKeyToContractId(config.key).toLowerCase()];
+    return [providerKeyToContractId(resolveRailProviderKey(config.key)).toLowerCase()];
 }
 /**
  * Decide, for every non-manual non-disabled provider on `chainId`, whether
  * it can still be attached to a deposit given the deposit's already-attached
  * payment method id hashes.
  *
- * Important — a parent provider is unavailable if ANY of its candidate hashes
- * (own contractId plus every sub-provider's contractId) is already attached.
- * This matches the contract's atomicity: `addPaymentMethods` submits the full
- * fan-out in one transaction and reverts with `PaymentMethodAlreadyExists`
- * the moment one row collides. A maker who already has Zelle-Chase attached
- * cannot re-add the Zelle parent without colliding on the Chase sub-row.
+ * Important — availability is decided against exactly the id the write would
+ * submit (see {@link getProviderPaymentMethodIds}), which is one id per rail.
+ * A maker holding the legacy `zelle-chase` row therefore still sees Zelle as
+ * addable, and should add it: the rail is the only method its intents can be
+ * fulfilled on, and attaching it is how such a deposit gets repaired.
  *
  * `manual` is always excluded from both lists.
  */
@@ -1148,6 +1155,51 @@ export function computeProviderAvailability(args) {
 export function availableProviderConfigs(args) {
     return computeProviderAvailability(args).available;
 }
+/**
+ * Find rails this deposit attached at bank level but never at rail level.
+ *
+ * Such a deposit is not degraded — it is **inert**. `fetchMatchableDeposits`
+ * matches the rail id alone, so the deposit appears in no buyer's orderbook,
+ * and `resolveTargetedVerifier` returns null for it. Both were deliberate:
+ * bank-level rows once put these deposits in front of buyers who reserved
+ * funds, paid a real person, and then could not submit.
+ *
+ * The consequence is that the maker gets **no signal at all** — no failed
+ * orders, no complaints, just silence indistinguishable from no demand. Nothing
+ * in the product tells them, which is why this predicate exists: it is the only
+ * way the interface can raise the problem.
+ *
+ * The repair is one transaction. Attaching the rail makes the deposit
+ * matchable, and the bank-level rows are never consulted again on any buyer
+ * path — there is nothing to deactivate. They remain visible only on the
+ * owner's own platform list, which is cosmetic.
+ *
+ * Rails already holding their own id are skipped, as are disabled rails: it
+ * would be wrong to tell a maker to attach a method the chain won't accept.
+ *
+ * @returns One entry per rail needing repair; empty when the deposit is healthy.
+ */
+export function findLegacySubProviderAttachments(args) {
+    const configs = providerConfigs(args.chainId);
+    const out = [];
+    for (const config of Object.values(configs)) {
+        const subConfigs = subProviderConfigs[config.key];
+        if (!subConfigs)
+            continue;
+        if (isProviderDisabled(config.key, config.disabled))
+            continue;
+        // Already holds the rail — whatever else it carries, it is fulfillable.
+        if (args.attachedPaymentMethodIds.has(providerKeyToContractId(config.key).toLowerCase()))
+            continue;
+        const attachedSubProviderKeys = Object.keys(subConfigs)
+            .filter(key => args.attachedPaymentMethodIds.has(providerKeyToContractId(key).toLowerCase()))
+            .sort();
+        if (attachedSubProviderKeys.length === 0)
+            continue;
+        out.push({ rail: config.key, attachedSubProviderKeys });
+    }
+    return out;
+}
 /**
  * Get supported currencies for a payment provider.
  * Returns only the currencies that are in the provider's supported list.
@@ -1170,6 +1222,75 @@ export function getCurrenciesForProvider(config) {
     const supportedIds = new Set(config.list);
     return Object.values(SUPPORTED_CURRENCIES).filter((currency) => supportedIds.has(currency.contractId));
 }
+/**
+ * Verifiable providers on `chainId` whose currency list contains `currency`,
+ * in registry order.
+ *
+ * "Verifiable" and "supports the currency" are two separate gates and both
+ * matter: a rail can list pounds and still be switched off here, and offering
+ * it would seed a rail the buy flow cannot settle on.
+ *
+ * Note that verifiability is DEPLOYMENT CONFIGURATION, not a property of the
+ * chain — `DISABLED_PROVIDERS` / `ENABLED_PROVIDERS` override the registry's
+ * `disabled` field, and staging ships `vite_enabled_providers: "paypal"` while
+ * production does not. Two environments on the same chain legitimately return
+ * different lists. Never hardcode the answer for a named provider.
+ *
+ * An empty `list` means "serves no currency", not "serves every currency".
+ * `manual` is the only provider with an empty list and `verifiablePaymentMethods`
+ * already drops it, so the rule is unobservable today — but it is the rule to
+ * keep, because seeding a buyer onto a rail that declares no currency support
+ * is the bug this function exists to prevent.
+ *
+ * @example
+ * ```ts
+ * currencyCapableProviders(pulsechain.id, SUPPORTED_CURRENCIES.GBP)
+ * // ['revolut', 'wise', 'monzo'] — no Venmo, Zelle or Cash App
+ * ```
+ */
+export function currencyCapableProviders(chainId, currency) {
+    const configs = providerConfigs(chainId);
+    return verifiablePaymentMethods(chainId).filter((key) => configs[key]?.list.includes(currency.contractId) ?? false);
+}
+/**
+ * Whether a provider can actually serve a buyer paying in `currency` on this
+ * chain — it must be verifiable here AND list the currency.
+ *
+ * @example
+ * ```ts
+ * providerSupportsCurrency({ providerKey: providers.VENMO, chainId: pulsechain.id, currency: SUPPORTED_CURRENCIES.GBP })
+ * // false — Venmo is a United States dollar rail
+ * ```
+ */
+export function providerSupportsCurrency(args) {
+    return currencyCapableProviders(args.chainId, args.currency).includes(args.providerKey);
+}
+/**
+ * Pick a default payment method for a buyer paying in `currency`, preferring
+ * the highest-volume rail that can actually serve them.
+ *
+ * `verifiersByVolume` is the monthly-volume ranking, highest first. The volume
+ * leaders are United States dollar rails on every chain, so ranking without
+ * the currency gate seeds a pounds or euro buyer onto a rail that lists only
+ * dollars and shows them an empty order book. Falls back to the first capable
+ * provider in registry order when no ranked rail qualifies — volume data only
+ * covers rails that have already traded, which a new currency has not.
+ *
+ * @returns The chosen provider, or `null` when no verifiable provider on this
+ *   chain serves the currency at all. Null rather than an arbitrary provider,
+ *   so the caller can tell "nothing can serve this" from a real choice.
+ */
+export function selectVolumeDefaultProvider(args) {
+    const capable = currencyCapableProviders(args.chainId, args.currency);
+    if (capable.length === 0)
+        return null;
+    const capableKeys = new Set(capable);
+    for (const key of args.verifiersByVolume) {
+        if (capableKeys.has(key))
+            return key;
+    }
+    return capable[0] ?? null;
+}
 /** 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 */
@@ -1200,25 +1321,45 @@ export function getParentProviderKey(key) {
     return null;
 }
 /**
- * Canonicalize a provider key for off-chain maker-record lookups.
+ * Collapse a sub-provider key to the rail it belongs to.
  *
- * Makers register once at the parent provider level (e.g. `zelle`) and the
- * deposit's on-chain `paymentMethodId` is fanned out to sub-providers
- * (`zelle-chase`, `zelle-bofa`, …). Every off-chain lookup keyed by
- * `(provider, payeeDetailsHash)` MUST collapse the sub-provider back to
- * its parent or it will miss the row.
+ * A sub-provider names a bank the buyer captures from — it is a routing detail
+ * of the capture step, not an identity of its own. Everything keyed by rail
+ * rather than by bank MUST collapse through here:
  *
- * Use this anywhere you'd otherwise inline the
- * `isSubProviderKey(k) ? getParentProviderKey(k) : k` ternary so the
- * normalization can't drift between call sites — verify-intent regressed
- * by skipping it and produced 400 "maker contact could not be verified"
- * for every buy on a sub-provider deposit.
+ * - **The on-chain payment method.** A Zelle attestation is issued for the
+ *   rail: every bank template in `@zkp2p/providers` declares
+ *   `metadata.platform: "zelle"`, and the enclave verify route is
+ *   `zelle/transfer_zelle_{bank}` — the bank rides in the ACTION type, never
+ *   the platform. So `keccak256("zelle")` is the only payment method a Zelle
+ *   payment can ever satisfy. Deposits that attached `zelle-chase` and friends
+ *   accept intents no attestation can fulfil.
+ * - **Off-chain maker records.** Makers register once at rail level, so a
+ *   lookup keyed by `(provider, payeeDetailsHash)` misses the row unless the
+ *   bank is collapsed away. Skipping this in verify-intent once produced a 400
+ *   "maker contact could not be verified" for every buy on such a deposit.
+ *
+ * Non-sub-provider keys pass through unchanged, so this is safe to apply
+ * unconditionally.
+ *
+ * @param key - Provider or sub-provider key, e.g. `'zelle-chase'`.
+ * @returns The rail key, e.g. `'zelle'`.
  */
-export function resolveApiProviderKey(key) {
+export function resolveRailProviderKey(key) {
     if (!isSubProviderKey(key))
         return key;
     return getParentProviderKey(key) ?? key;
 }
+/**
+ * Canonicalize a provider key for off-chain maker-record lookups.
+ *
+ * @deprecated Prefer {@link resolveRailProviderKey}, which names the concept
+ * both call-site families share. Retained because the off-chain lookup sites
+ * read better with an API-flavoured name.
+ */
+export function resolveApiProviderKey(key) {
+    return resolveRailProviderKey(key);
+}
 /**
  * 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').

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

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview Rail invariants for payment method configuration.
+ *
+ * `payment.test.ts` covers the behaviour of the individual helpers with named
+ * cases. This file states the rule those helpers exist to enforce, as a sweep
+ * over every provider on every chain, so a newly added provider is covered
+ * without anyone remembering to add a case.
+ *
+ * **The rule.** A payment method on-chain is `keccak256(platform)`, where
+ * `platform` is what the zkTLS attestation names — the `metadata.platform` of
+ * the `@zkp2p/providers` template. `UnifiedPaymentVerifier` requires
+ * `snapshot.paymentMethod == intent.paymentMethod`, so a deposit that attaches
+ * anything else accepts intents no attestation can ever satisfy.
+ *
+ * Zelle is the case that taught this: every bank template (Chase, Bank of
+ * America, Citi, and now Wells Fargo, U.S. Bank, and TD) declares
+ * `platform: "zelle"`. The bank rides in the action type, never the platform.
+ * So bank-level keys are a capture-time detail — which website the extension
+ * opens — and must collapse to the rail everywhere the on-chain method is
+ * computed, while staying distinct everywhere the buyer picks a bank.
+ *
+ * The tests below assert both directions, because collapsing too much is its
+ * own bug: it would leave the buyer unable to say which bank they paid from.
+ */
+export {};