@provex/utils 1.9.2-rc.20260722211737.69a2b06 → 1.9.2-rc.20260723142825.d415ded

package/dist/payment.d.ts

@@ -542,19 +542,37 @@ export declare function isSubProviderKey(key: string): key is SubProviderKey;
  */
 export declare function getParentProviderKey(key: string): ProviderKey | null;
 /**
- * Canonicalize a provider key for off-chain maker-record lookups.
+ * 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.
  *
- * 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.
+ * @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.
  *
- * 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

@@ -1200,25 +1200,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.
+ *
+ * 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.
  *
- * 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.
+ * Non-sub-provider keys pass through unchanged, so this is safe to apply
+ * unconditionally.
  *
- * 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.
+ * @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.test.js

@@ -2,7 +2,7 @@ import { describe, it, test } from 'node:test';
 import assert from 'node:assert/strict';
 import { base } from 'viem/chains';
 import { getAddress } from 'viem';
-import { providerConfigs, getCurrenciesForProvider, providers, verifierGetsKey, providerKeyToContractId, resolveApiProviderKey, getProviderPaymentMethodIds, computeProviderAvailability, availableProviderConfigs, subProviders, isDayResolutionRail } from './payment.js';
+import { providerConfigs, getCurrenciesForProvider, providers, verifierGetsKey, providerKeyToContractId, resolveApiProviderKey, resolveRailProviderKey, getProviderPaymentMethodIds, computeProviderAvailability, availableProviderConfigs, subProviders, isDayResolutionRail } from './payment.js';
 import { paymentVerifierToKey, providerByContractId, getProviderByContractId, getProviderNameByContractId, providerKeyToVerifiers, providerKeyToVerifiersMap, getPaymentMethodConfig, getPaymentMethodName, getPaymentMethodMinimum, getPaymentProviderMinimum, calculateEffectiveMinimum, isPaymentMethodKnown, isPaymentMethodIdKnown, isExternalPaymentMethod, getExternalPaymentMethod, externalPaymentMethods, getExtensionPlatform, getParentProviderKey, isSubProviderKey, providerRequiresMetadataIndex, getProviderIconStack, getPaymentIcon, getPlatformRisk, fromPeerTier, tierToPeerTier, tiers, getAllPaymentMethods, verifiablePaymentMethods, } from './payment.js';
 import { getDefaultToken } from './tokens.js';
 import { SUPPORTED_CURRENCIES } from './currencies.js';
@@ -206,6 +206,38 @@ describe('resolveApiProviderKey', () => {
         assert.equal(resolveApiProviderKey('unknown-sub'), 'unknown-sub');
     });
 });
+/**
+ * Tests for resolveRailProviderKey — the same collapse, applied to the
+ * ON-CHAIN payment method. A Zelle attestation is issued for the rail: every
+ * bank template declares `metadata.platform: "zelle"` and the enclave verify
+ * route is `zelle/transfer_zelle_{bank}`, so the bank never reaches the
+ * payment method. Deposits that attached bank-level methods accepted intents
+ * that no attestation could fulfil — they sat until they expired.
+ */
+describe('resolveRailProviderKey', () => {
+    it('collapses every Zelle bank to the rail', () => {
+        // The full set, not a sample: one bank left un-collapsed is one bank whose
+        // deposits silently strand every intent signalled against them.
+        for (const bank of Object.values(subProviders)) {
+            assert.equal(resolveRailProviderKey(bank), providers.ZELLE);
+        }
+    });
+    it('leaves rails that have no banks untouched', () => {
+        assert.equal(resolveRailProviderKey(providers.VENMO), 'venmo');
+        assert.equal(resolveRailProviderKey(providers.CASHAPP), 'cashapp');
+        assert.equal(resolveRailProviderKey(providers.ZELLE), 'zelle');
+    });
+    it('is idempotent, so applying it twice cannot drift', () => {
+        // Call sites apply it at the write boundary; a second application (say a
+        // caller that already normalized) must be a no-op.
+        assert.equal(resolveRailProviderKey(resolveRailProviderKey('zelle-chase')), resolveRailProviderKey('zelle-chase'));
+    });
+    it('maps the rail key to the payment method id registered on-chain', () => {
+        // Pins the migration target: keccak256("zelle"). If this changes, deposits
+        // would be attaching a method the registry does not route.
+        assert.equal(providerKeyToContractId(resolveRailProviderKey('zelle-bofa')), '0xf752c7d19698ecb0bb8988abf9b9a53a4c3657f3bc8850a6fb59fdf3e3ce8cd3');
+    });
+});
 /**
  * Tests for providerConfigs - payment provider configuration
  */

package/dist/transports.d.ts

@@ -16,15 +16,36 @@
  */
 import { type Transport } from 'viem';
 import { type ChainId } from './chain.js';
+/**
+ * valve.city PulseChain endpoint — one URL fronting a load-balanced node pool.
+ *
+ * `vk_demo` is the PUBLIC, RATE-LIMITED demo key. It is the right default for
+ * local development and for anyone building against this package without
+ * credentials, but a keyed endpoint (`https://one.valve.city/rpc/<key>/evm/369`)
+ * belongs in front of production traffic — a shared demo key is a shared rate
+ * limit. Override per-deployment via the `VITE_RPC_URLS_369` env (caller
+ * overrides are tried ahead of this list) rather than editing this constant.
+ *
+ * Kept in sync with `DEFAULT_MSGBOARD_ENDPOINT` in @provex/onramp, which points
+ * at the same host: one keyed valve.city endpoint serves both `msgboard_*` and
+ * `eth_*` methods.
+ */
+export declare const VALVE_CITY_PULSECHAIN_RPC = "https://one.valve.city/rpc/vk_demo/evm/369";
 /**
  * Provex-curated fallback RPC URLs per chain, applied after caller overrides
  * but before the viem chain default.
  *
  * @remarks
- * - Pulsechain (369): g4mm4 operates a public PulseChain RPC that is more
- *   reliable from browsers than the official `rpc.pulsechain.com`.
+ * - Pulsechain (369): valve.city is listed first — it load balances across a
+ *   pool of PulseChain nodes behind one endpoint, so it absorbs a single node
+ *   going slow or stale without the client noticing. g4mm4 is retained behind
+ *   it as an independent operator: valve.city's internal balancing cannot help
+ *   if the endpoint ITSELF is unreachable, so a second operator is what makes
+ *   this list a real fallback rather than one host with extra steps.
+ *   Order is a hint, not a guarantee — {@link createChainTransport} ranks by
+ *   measured latency, so the fastest healthy endpoint serves traffic either way.
  * - Base (8453): no built-in fallback — Base's default endpoint is reliable
- *   and g4mm4 does not operate a Base RPC.
+ *   and neither operator runs a Base RPC.
  */
 export declare const FALLBACK_RPC_URLS: Partial<Record<ChainId, readonly string[]>>;
 /**

package/dist/transports.js

@@ -16,6 +16,21 @@
  */
 import { fallback, http } from 'viem';
 import { chainIdToChain } from './chain.js';
+/**
+ * valve.city PulseChain endpoint — one URL fronting a load-balanced node pool.
+ *
+ * `vk_demo` is the PUBLIC, RATE-LIMITED demo key. It is the right default for
+ * local development and for anyone building against this package without
+ * credentials, but a keyed endpoint (`https://one.valve.city/rpc/<key>/evm/369`)
+ * belongs in front of production traffic — a shared demo key is a shared rate
+ * limit. Override per-deployment via the `VITE_RPC_URLS_369` env (caller
+ * overrides are tried ahead of this list) rather than editing this constant.
+ *
+ * Kept in sync with `DEFAULT_MSGBOARD_ENDPOINT` in @provex/onramp, which points
+ * at the same host: one keyed valve.city endpoint serves both `msgboard_*` and
+ * `eth_*` methods.
+ */
+export const VALVE_CITY_PULSECHAIN_RPC = 'https://one.valve.city/rpc/vk_demo/evm/369';
 // Per-method call counter. Enabled at runtime by setting window.__RPC_DEBUG = true
 // in the browser console (works in pre-built dist — no Vite env injection needed).
 const _rpcCounts = {};
@@ -36,13 +51,19 @@ const _rpcLog = (method) => {
  * but before the viem chain default.
  *
  * @remarks
- * - Pulsechain (369): g4mm4 operates a public PulseChain RPC that is more
- *   reliable from browsers than the official `rpc.pulsechain.com`.
+ * - Pulsechain (369): valve.city is listed first — it load balances across a
+ *   pool of PulseChain nodes behind one endpoint, so it absorbs a single node
+ *   going slow or stale without the client noticing. g4mm4 is retained behind
+ *   it as an independent operator: valve.city's internal balancing cannot help
+ *   if the endpoint ITSELF is unreachable, so a second operator is what makes
+ *   this list a real fallback rather than one host with extra steps.
+ *   Order is a hint, not a guarantee — {@link createChainTransport} ranks by
+ *   measured latency, so the fastest healthy endpoint serves traffic either way.
  * - Base (8453): no built-in fallback — Base's default endpoint is reliable
- *   and g4mm4 does not operate a Base RPC.
+ *   and neither operator runs a Base RPC.
  */
 export const FALLBACK_RPC_URLS = {
-    369: ['https://rpc-pulsechain.g4mm4.io'],
+    369: [VALVE_CITY_PULSECHAIN_RPC, 'https://rpc-pulsechain.g4mm4.io'],
     8453: [],
 };
 /**

package/dist/transports.test.js

@@ -1,7 +1,7 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import { base, pulsechain } from 'viem/chains';
-import { createChainTransport, parseRpcUrlList, resolveChainRpcUrls, FALLBACK_RPC_URLS, } from './transports.js';
+import { createChainTransport, parseRpcUrlList, resolveChainRpcUrls, FALLBACK_RPC_URLS, VALVE_CITY_PULSECHAIN_RPC, } from './transports.js';
 /**
  * Read the ordered list of RPC URLs a built transport will actually dial.
  *
@@ -19,10 +19,26 @@ const dialledUrls = (transport) => {
 };
 describe('transports', () => {
     describe('FALLBACK_RPC_URLS', () => {
-        it('lists g4mm4 for PulseChain (369)', () => {
-            assert.deepEqual(FALLBACK_RPC_URLS[369], ['https://rpc-pulsechain.g4mm4.io']);
+        it('lists valve.city ahead of g4mm4 for PulseChain (369)', () => {
+            // valve.city load balances across a node pool, so it leads. g4mm4 stays
+            // behind it as an INDEPENDENT operator: valve.city's internal balancing
+            // cannot save us if that endpoint itself is down, which is the only
+            // failure a fallback list exists to survive.
+            assert.deepEqual(FALLBACK_RPC_URLS[369], [
+                VALVE_CITY_PULSECHAIN_RPC,
+                'https://rpc-pulsechain.g4mm4.io',
+            ]);
+        });
+        it('keeps two independent operators for PulseChain', () => {
+            // Guard against someone "simplifying" the list down to a single host.
+            // One entry means fallback() short-circuits to a bare transport and a
+            // single operator outage takes the app down.
+            const urls = FALLBACK_RPC_URLS[369] ?? [];
+            assert.ok(urls.length >= 2, 'PulseChain must keep a second, independent RPC operator');
+            const hosts = new Set(urls.map((u) => new URL(u).host));
+            assert.equal(hosts.size, urls.length, 'fallback URLs must not share a host');
         });
-        it('has an empty list for Base (8453) — g4mm4 does not run a Base RPC', () => {
+        it('has an empty list for Base (8453) — neither operator runs a Base RPC', () => {
             assert.deepEqual(FALLBACK_RPC_URLS[8453], []);
         });
     });
@@ -47,9 +63,10 @@ describe('transports', () => {
         });
     });
     describe('resolveChainRpcUrls', () => {
-        it('returns g4mm4 then chain default for PulseChain', () => {
+        it('returns valve.city, then g4mm4, then chain default for PulseChain', () => {
             const urls = resolveChainRpcUrls(369);
             assert.deepEqual(urls, [
+                VALVE_CITY_PULSECHAIN_RPC,
                 'https://rpc-pulsechain.g4mm4.io',
                 pulsechain.rpcUrls.default.http[0],
             ]);
@@ -61,9 +78,12 @@ describe('transports', () => {
         it('places caller-supplied userUrls ahead of curated fallbacks and the default', () => {
             const userUrls = ['https://my-private-rpc.example', 'https://another.example'];
             const urls = resolveChainRpcUrls(369, { userUrls });
+            // A deployment-supplied keyed endpoint MUST outrank the shared vk_demo
+            // default — this is how production escapes the demo key's rate limit.
             assert.deepEqual(urls, [
                 'https://my-private-rpc.example',
                 'https://another.example',
+                VALVE_CITY_PULSECHAIN_RPC,
                 'https://rpc-pulsechain.g4mm4.io',
                 pulsechain.rpcUrls.default.http[0],
             ]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@provex/utils",
-  "version": "1.9.2-rc.20260722211737.69a2b06",
+  "version": "1.9.2-rc.20260723142825.d415ded",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",