@provex/utils 1.9.1 → 1.9.2-rc.20260702180200.fd5d003

package/dist/consent.test.js

@@ -65,6 +65,21 @@ describe('formatRelative', () => {
     it('returns empty string for empty input', () => {
         assert.equal(formatRelative('', now), '');
     });
+    it('returns empty string for an unparseable timestamp', () => {
+        // A stored `acceptedAt` could be corrupted by a manual localStorage
+        // edit or a botched migration. `new Date('garbage').getTime()` is
+        // NaN — without the guard this would render "NaNs ago" in the audit
+        // row. Degrade to empty instead, matching the empty-input handling.
+        assert.equal(formatRelative('not-a-date', now), '');
+    });
+    it('clamps future timestamps to "just now"', () => {
+        // A clock skew between the user's device and the acceptance source
+        // can produce an acceptedAt in the future. The JSDoc commits to
+        // clamping these to "just now" rather than emitting a negative
+        // duration; the Math.max(0, …) floor is what enforces it.
+        const future = new Date(T0 + 60_000).toISOString();
+        assert.equal(formatRelative(future, now), 'just now');
+    });
 });
 describe('readConsent', () => {
     it('returns {} when the storage key is unset', () => {
@@ -94,6 +109,15 @@ describe('readConsent', () => {
         // Server-side render path: no localStorage available.
         assert.deepEqual(readConsent('k', null), {});
     });
+    it('falls back to ambient storage and degrades to {} off-browser', () => {
+        // Omitting the storage argument exercises the default-parameter
+        // path, which calls ambientStorage(). Under the Node test runner
+        // there is no globalThis.localStorage, so ambientStorage() returns
+        // null and readConsent degrades to {} — the same safe result the
+        // SSR / private-mode paths produce. This pins that the module never
+        // throws when used without an explicit storage handle.
+        assert.deepEqual(readConsent('unset-key'), {});
+    });
 });
 describe('sectionStatus', () => {
     it('returns "unread" when no stored entry exists', () => {

package/dist/contracts.d.ts

@@ -62,7 +62,7 @@ export declare const v3BaseContracts: V3Contracts;
  * V3 contracts deployed to Pulsechain (Chain ID 369)
  * Deployed: 2026-01-12
  * Deployer: 0xC3c7e05D1BA19563693D891e5c38f0FC988A5d11
- * MultiSig: 0x948eB6D3A08BEb29Dc1D08d09753862573A94122
+ * Protocol fee recipient (EOA, not a multisig): 0x948eB6D3A08BEb29Dc1D08d09753862573A94122
  */
 export declare const v3PulsechainContracts: V3Contracts;
 /**
@@ -192,15 +192,54 @@ export declare function shortenEscrowAddress(escrow: Hex): string;
 export declare function getEscrowVersion(escrowAddress: Hex, chainId?: ChainId): Version | null;
 /**
  * Check if an escrow address is a V3 contract.
- * Convenience function for feature gating V3-only functionality.
+ *
+ * @deprecated Returns true for **exactly** v3, so it silently excludes every
+ * newer orchestrator-based generation (v4+). For feature gates that mean
+ * "modern orchestrator escrow vs the legacy v2 monolith", use
+ * {@link supportsOrchestratorEscrow} instead. Only keep using this where a
+ * call site genuinely needs to single out v3 and nothing newer.
  *
  * @param escrowAddress - The escrow contract address
  * @param chainId - The chain ID
  * @returns true if the escrow is V3, false otherwise
+ */
+export declare function isV3Escrow(escrowAddress: Hex, chainId: ChainId): boolean;
+/**
+ * Whether a generation is an orchestrator-based escrow (v3 or newer) rather
+ * than the legacy v2 monolith.
+ *
+ * Use this to gate features that exist on every modern generation — add /
+ * remove funds, retain-on-empty, delegate, accepting-intents toggles, intent
+ * pruning, owner management panels. Because it is defined as "not v2" rather
+ * than "is v3", new generations (v4+) light up automatically without editing
+ * each call site.
+ *
+ * @param version - The escrow version, or null when the address is unknown
+ * @returns true for v3 and every newer generation; false for v2 and null
  *
  * @example
- * // Gate V3-only features in UI
- * const showRetainToggle = isV3Escrow(deposit.escrow, deposit.chainId) && isOwner
+ * const supportsOrchestrator = supportsOrchestrator(deposit.version)
+ * const showRetainToggle = supportsOrchestrator && isOwner
  */
-export declare function isV3Escrow(escrowAddress: Hex, chainId: ChainId): boolean;
+export declare function supportsOrchestrator(version: Version | null): boolean;
+/**
+ * Address-based convenience over {@link supportsOrchestrator}: resolve the
+ * escrow's generation from its address, then test the capability. This is the
+ * v4-safe replacement for {@link isV3Escrow} at feature-gate call sites.
+ *
+ * @param escrowAddress - The escrow contract address
+ * @param chainId - The chain ID
+ * @returns true if the escrow is v3 or a newer orchestrator generation
+ *
+ * @example
+ * // Gate orchestrator-only features in UI (v3 and v4 both pass)
+ * const showRetainToggle = supportsOrchestratorEscrow(deposit.escrow, deposit.chainId) && isOwner
+ */
+export declare function supportsOrchestratorEscrow(escrowAddress: Hex, chainId: ChainId): boolean;
+/** MessageBus contract addresses — placeholder until deployed */
+export declare const messageBus: {
+    readonly 943: "0x0000000000000000000000000000000000000000";
+    readonly 369: "0x0000000000000000000000000000000000000000";
+    readonly 8453: "0x0000000000000000000000000000000000000000";
+};
 export {};

package/dist/contracts.js

@@ -83,7 +83,7 @@ export const v3BaseContracts = {
  * V3 contracts deployed to Pulsechain (Chain ID 369)
  * Deployed: 2026-01-12
  * Deployer: 0xC3c7e05D1BA19563693D891e5c38f0FC988A5d11
- * MultiSig: 0x948eB6D3A08BEb29Dc1D08d09753862573A94122
+ * Protocol fee recipient (EOA, not a multisig): 0x948eB6D3A08BEb29Dc1D08d09753862573A94122
  */
 export const v3PulsechainContracts = {
     usdc: getAddress('0x15D38573d2feeb82e7ad5187aB8c1D52810B1f07'),
@@ -277,16 +277,59 @@ export function getEscrowVersion(escrowAddress, chainId) {
 }
 /**
  * Check if an escrow address is a V3 contract.
- * Convenience function for feature gating V3-only functionality.
+ *
+ * @deprecated Returns true for **exactly** v3, so it silently excludes every
+ * newer orchestrator-based generation (v4+). For feature gates that mean
+ * "modern orchestrator escrow vs the legacy v2 monolith", use
+ * {@link supportsOrchestratorEscrow} instead. Only keep using this where a
+ * call site genuinely needs to single out v3 and nothing newer.
  *
  * @param escrowAddress - The escrow contract address
  * @param chainId - The chain ID
  * @returns true if the escrow is V3, false otherwise
- *
- * @example
- * // Gate V3-only features in UI
- * const showRetainToggle = isV3Escrow(deposit.escrow, deposit.chainId) && isOwner
  */
 export function isV3Escrow(escrowAddress, chainId) {
     return getEscrowVersion(escrowAddress, chainId) === 'v3';
 }
+/**
+ * Whether a generation is an orchestrator-based escrow (v3 or newer) rather
+ * than the legacy v2 monolith.
+ *
+ * Use this to gate features that exist on every modern generation — add /
+ * remove funds, retain-on-empty, delegate, accepting-intents toggles, intent
+ * pruning, owner management panels. Because it is defined as "not v2" rather
+ * than "is v3", new generations (v4+) light up automatically without editing
+ * each call site.
+ *
+ * @param version - The escrow version, or null when the address is unknown
+ * @returns true for v3 and every newer generation; false for v2 and null
+ *
+ * @example
+ * const supportsOrchestrator = supportsOrchestrator(deposit.version)
+ * const showRetainToggle = supportsOrchestrator && isOwner
+ */
+export function supportsOrchestrator(version) {
+    return version !== null && version !== 'v2';
+}
+/**
+ * Address-based convenience over {@link supportsOrchestrator}: resolve the
+ * escrow's generation from its address, then test the capability. This is the
+ * v4-safe replacement for {@link isV3Escrow} at feature-gate call sites.
+ *
+ * @param escrowAddress - The escrow contract address
+ * @param chainId - The chain ID
+ * @returns true if the escrow is v3 or a newer orchestrator generation
+ *
+ * @example
+ * // Gate orchestrator-only features in UI (v3 and v4 both pass)
+ * const showRetainToggle = supportsOrchestratorEscrow(deposit.escrow, deposit.chainId) && isOwner
+ */
+export function supportsOrchestratorEscrow(escrowAddress, chainId) {
+    return supportsOrchestrator(getEscrowVersion(escrowAddress, chainId));
+}
+/** MessageBus contract addresses — placeholder until deployed */
+export const messageBus = {
+    943: "0x0000000000000000000000000000000000000000",
+    369: "0x0000000000000000000000000000000000000000",
+    8453: "0x0000000000000000000000000000000000000000",
+};

package/dist/contracts.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 { getContracts, getLatestContract, getAllEscrowContracts, shortenEscrowAddress, getEscrowVersion, isV3Escrow, v2BaseContracts, v3BaseContracts, v2PulsechainContracts, v3PulsechainContracts, V3_PULSECHAIN_DEPLOYMENT_REFERENCE, contracts, } from './contracts.js';
+import { getContracts, getLatestContract, getAllEscrowContracts, getAllV3EscrowContracts, shortenEscrowAddress, getEscrowVersion, isV3Escrow, supportsOrchestrator, supportsOrchestratorEscrow, v2BaseContracts, v3BaseContracts, v2PulsechainContracts, v3PulsechainContracts, V3_PULSECHAIN_DEPLOYMENT_REFERENCE, contracts, } from './contracts.js';
 describe('contracts', () => {
     describe('getDefaultVersion', () => {
         it('returns v3 for Base', async () => {
@@ -132,6 +132,30 @@ describe('contracts', () => {
             }
         });
     });
+    describe('getAllV3EscrowContracts', () => {
+        // This list drives cross-chain nullifier checking — a V2 escrow
+        // leaking into it would have the dedup logic look for double-spends
+        // in the wrong contract set, so the V3-only filter is correctness-
+        // critical, not cosmetic.
+        it('returns only v3 escrow locations', () => {
+            const v3Escrows = getAllV3EscrowContracts();
+            assert.ok(v3Escrows.length > 0);
+            for (const location of v3Escrows) {
+                assert.strictEqual(location.version, 'v3');
+            }
+        });
+        it('excludes every v2 escrow that getAllEscrowContracts reports', () => {
+            // The filtered set must equal exactly the v3 subset of the full
+            // set — no v2 leakage, no v3 omissions.
+            const expectedV3Count = getAllEscrowContracts().filter((location) => location.version === 'v3').length;
+            assert.strictEqual(getAllV3EscrowContracts().length, expectedV3Count);
+        });
+        it('includes both the Base and Pulsechain v3 escrows', () => {
+            const v3Escrows = getAllV3EscrowContracts();
+            assert.ok(v3Escrows.some((location) => location.chainId === base.id));
+            assert.ok(v3Escrows.some((location) => location.chainId === pulsechain.id));
+        });
+    });
     describe('contract structure', () => {
         it('v2 contracts have required verifiers', () => {
             assert.ok(v2BaseContracts.venmoReclaimVerifier);
@@ -240,4 +264,33 @@ describe('contracts', () => {
             assert.strictEqual(result, false);
         });
     });
+    describe('supportsOrchestrator', () => {
+        it('returns true for v3', () => {
+            assert.strictEqual(supportsOrchestrator('v3'), true);
+        });
+        it('returns false for the legacy v2 monolith', () => {
+            assert.strictEqual(supportsOrchestrator('v2'), false);
+        });
+        it('returns false for an unknown (null) version', () => {
+            assert.strictEqual(supportsOrchestrator(null), false);
+        });
+        it('admits future orchestrator generations, unlike an exact-v3 check', () => {
+            // The predicate is defined as "not v2", so a newer generation (v4+)
+            // must pass — that is the entire reason it exists instead of a
+            // `version === 'v3'` comparison. If anyone reimplements it as an
+            // exact-v3 check, this assertion fails and flags the regression.
+            assert.strictEqual(supportsOrchestrator('v4'), true);
+        });
+    });
+    describe('supportsOrchestratorEscrow', () => {
+        it('returns true for a v3 escrow address', () => {
+            assert.strictEqual(supportsOrchestratorEscrow(v3BaseContracts.escrow[0], base.id), true);
+        });
+        it('returns false for a v2 escrow address', () => {
+            assert.strictEqual(supportsOrchestratorEscrow(v2BaseContracts.escrow[0], base.id), false);
+        });
+        it('returns false for an unknown escrow address', () => {
+            assert.strictEqual(supportsOrchestratorEscrow('0x0000000000000000000000000000000000000000', base.id), false);
+        });
+    });
 });

package/dist/fees.test.js

@@ -138,6 +138,31 @@ describe('normalizeFeePrecision', () => {
             assert.equal(result.percentage, '100%');
         });
     });
+    describe('precision-detection boundary', () => {
+        // The heuristic switches at PRECISION_DETECTION_THRESHOLD (1,000,000).
+        // This is the money-critical decision: misclassifying the precision
+        // scales the fee by 1e14. Pin both sides of the exact boundary so a
+        // change to the threshold or comparison operator surfaces.
+        it('treats a value exactly at the threshold as basis points', () => {
+            // 1,000,000 is NOT greater than the threshold (strict `>`), so it
+            // stays in the basis-points branch and is returned unscaled.
+            const result = normalizeFeePrecision(1000000n);
+            assert.equal(result.precision, 'bps');
+            assert.equal(result.normalizedBps, 1000000n);
+        });
+        it('treats one unit above the threshold as 18-decimal precision', () => {
+            // 1,000,001 crosses into the 18-decimal branch. Because the value
+            // is a negligible fraction of 1e18, the basis-points normalization
+            // floors to 0 — a real consequence of the heuristic at its edge.
+            // note: a genuine basis-points fee just above 1,000,000 (≈10000%)
+            // would be silently normalized to 0 bps here. Not a concern for
+            // real fees (always well under 100%), but pinned so the boundary
+            // behavior is explicit rather than accidental.
+            const result = normalizeFeePrecision(1000001n);
+            assert.equal(result.precision, '18decimals');
+            assert.equal(result.normalizedBps, 0n);
+        });
+    });
 });
 describe('calculateTotalFees', () => {
     it('should sum multiple fees', () => {

package/dist/input.test.js

@@ -83,6 +83,19 @@ describe('adjustLowestDecimal', () => {
             assert.equal(result, '0.123456789012345679');
         });
     });
+    describe('leading-dot input (no whole part)', () => {
+        // A paste or autofill can yield ".5" with an empty integer part.
+        // The split produces whole === '', so after the bigint math the
+        // reconstructed whole part slices to an empty string and the
+        // `|| '0'` fallback supplies the missing zero. Without it the result
+        // would be ".6" (or throw on BigInt('')). Pin the normalization.
+        it('normalizes a missing integer part to a leading zero on increment', () => {
+            assert.equal(adjustLowestDecimal('.5', 1), '0.6');
+        });
+        it('normalizes a missing integer part to a leading zero on decrement', () => {
+            assert.equal(adjustLowestDecimal('.5', -1), '0.4');
+        });
+    });
     describe('large whole-number values', () => {
         it('handles values larger than Number.MAX_SAFE_INTEGER via bigint', () => {
             // 2^53 = 9007199254740992 — anything above this loses precision

package/dist/payment.test.js

@@ -1,7 +1,10 @@
 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 { 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';
 describe('getCurrenciesForProvider', () => {
     const configs = providerConfigs(base.id);
@@ -515,3 +518,504 @@ describe('computeProviderAvailability', () => {
         }
     });
 });
+/**
+ * Tests for {@link paymentVerifierToKey} — the reverse index that maps every
+ * on-chain identifier (V2 verifier address OR V3 keccak contract id, plus the
+ * same for sub-providers) back to the provider key. This is the lookup that
+ * decides which verifier a settled payment was proven against. A wrong entry
+ * here routes a buyer's proof to the wrong rail.
+ */
+describe('paymentVerifierToKey', () => {
+    // Base V2 venmo verifier address (from contracts.ts v2BaseContracts).
+    const venmoBaseVerifier = getAddress('0x9a733B55a875D0DB4915c6B36350b24F8AB99dF5');
+    // Base V2 zelle-chase sub-provider verifier address.
+    const zelleChaseBaseVerifier = getAddress('0xBcD7C6BBcA5869fBefe3E322263EE1090221D7A9');
+    it('maps a V2 verifier address (checksummed) to its provider key', () => {
+        // Address keys are stored checksummed (getAddress) in the map; a settled
+        // V2 deposit carries the verifier address, and this is how the UI decides
+        // it was a Venmo payment.
+        const map = paymentVerifierToKey(base.id);
+        assert.equal(map.get(venmoBaseVerifier), 'venmo');
+    });
+    it('maps a V3 keccak contract id (lowercased) to its provider key', () => {
+        // V3 deposits carry the bytes32 keccak(providerKey); contract-id keys are
+        // stored lowercased so callers compare without re-normalizing.
+        const map = paymentVerifierToKey(base.id);
+        const venmoContractId = providerKeyToContractId('venmo').toLowerCase();
+        assert.equal(map.get(venmoContractId), 'venmo');
+    });
+    it('maps a sub-provider verifier address to the SUB key, not the parent', () => {
+        // Sub-providers are flattened into the same map. A Zelle-Chase proof must
+        // resolve to 'zelle-chase' (so the bank-specific timing window applies),
+        // never collapse to the 'zelle' parent at this layer.
+        const map = paymentVerifierToKey(base.id);
+        assert.equal(map.get(zelleChaseBaseVerifier), 'zelle-chase');
+    });
+    it('maps a sub-provider contract id to the sub key', () => {
+        const map = paymentVerifierToKey(base.id);
+        const chaseContractId = providerKeyToContractId('zelle-chase').toLowerCase();
+        assert.equal(map.get(chaseContractId), 'zelle-chase');
+    });
+    it('with null chainId aggregates every supported chain into one map', () => {
+        // Passing null walks all v2 chains. Both the Base AND the Pulsechain venmo
+        // verifier addresses must resolve — the cross-chain transaction list relies
+        // on a single chain-agnostic lookup.
+        const map = paymentVerifierToKey(null);
+        const venmoPulseVerifier = getAddress('0x0Dd524dA03f610480aF3F433B411b6016cFBDeab');
+        assert.equal(map.get(venmoBaseVerifier), 'venmo');
+        assert.equal(map.get(venmoPulseVerifier), 'venmo');
+    });
+    it('returns undefined for an address that is not a registered verifier', () => {
+        const map = paymentVerifierToKey(base.id);
+        assert.equal(map.get(getAddress('0x0000000000000000000000000000000000000001')), undefined);
+    });
+});
+/**
+ * Tests for {@link providerByContractId} / {@link getProviderByContractId} /
+ * {@link getProviderNameByContractId} — keccak-hash → config reverse lookup,
+ * including the synthetic configs minted for sub-providers.
+ */
+describe('getProviderByContractId', () => {
+    const venmoContractId = providerKeyToContractId('venmo');
+    const chaseContractId = providerKeyToContractId('zelle-chase');
+    it('resolves a main-provider contract id to its config', () => {
+        const config = getProviderByContractId(base.id, venmoContractId);
+        assert.equal(config?.key, 'venmo');
+        assert.equal(config?.name, 'Venmo');
+    });
+    it('resolves a sub-provider contract id to a synthetic config with the sub name', () => {
+        // Sub-providers get a synthetic PaymentConfig: parent fields cloned, but
+        // key/name/contractId/icon overridden to the sub. Confirms the override,
+        // not just a parent passthrough.
+        const config = getProviderByContractId(base.id, chaseContractId);
+        assert.equal(config?.key, 'zelle-chase');
+        assert.equal(config?.name, 'Chase');
+        assert.equal(config?.subProviders.size, 0, 'synthetic sub config must not re-nest sub-providers');
+    });
+    it('is case-insensitive on the contract id', () => {
+        // Indexer rows may arrive checksum-cased or upper-cased; the lookup
+        // lowercases before indexing, so an upper-cased id must still resolve.
+        const upper = venmoContractId.toUpperCase().replace('0X', '0x');
+        assert.equal(getProviderByContractId(base.id, upper)?.key, 'venmo');
+    });
+    it('returns null for an unknown contract id', () => {
+        const unknown = '0x0000000000000000000000000000000000000000000000000000000000000001';
+        assert.equal(getProviderByContractId(base.id, unknown), null);
+    });
+    it('getProviderNameByContractId returns the name for a known id', () => {
+        assert.equal(getProviderNameByContractId(base.id, venmoContractId), 'Venmo');
+    });
+    it('getProviderNameByContractId echoes the raw contract id back when unknown', () => {
+        // Documented fallback: no config → return the id itself (so the UI shows
+        // *something* rather than a crash or empty string).
+        const unknown = '0x0000000000000000000000000000000000000000000000000000000000000002';
+        assert.equal(getProviderNameByContractId(base.id, unknown), unknown);
+    });
+    it('providerByContractId map contains both main and sub entries keyed lowercased', () => {
+        const map = providerByContractId(base.id);
+        assert.equal(map.get(venmoContractId.toLowerCase())?.key, 'venmo');
+        assert.equal(map.get(chaseContractId.toLowerCase())?.key, 'zelle-chase');
+    });
+});
+/**
+ * Tests for {@link providerKeyToVerifiers} / {@link providerKeyToVerifiersMap} —
+ * the forward map from a provider key to its V2 verifier contract addresses.
+ */
+describe('providerKeyToVerifiers', () => {
+    it('returns the V2 verifier addresses for a configured provider', () => {
+        const verifiers = providerKeyToVerifiers(base.id, 'venmo');
+        assert.ok(verifiers, 'venmo must have verifiers on Base');
+        assert.ok(verifiers.some(v => getAddress(v) === getAddress('0x9a733B55a875D0DB4915c6B36350b24F8AB99dF5')), 'venmo verifier list must contain the Base venmo verifier address');
+    });
+    it('round-trips: every verifier it returns maps back to the same key', () => {
+        // Forward (key→addresses) and reverse (address→key) indices must agree, or
+        // a proof verified against an address would be attributed to a different
+        // provider than the deposit advertised.
+        const verifiers = providerKeyToVerifiers(base.id, 'venmo') ?? [];
+        for (const verifier of verifiers) {
+            assert.equal(verifierGetsKey(base.id, verifier), 'venmo', `verifier ${verifier} should map back to venmo`);
+        }
+    });
+    it('returns null for a key that is not a top-level provider config (e.g. a sub-provider)', () => {
+        // The map is built from providerConfigs keys only; 'zelle-chase' is a
+        // sub-provider and is NOT a top-level key, so the lookup misses → null.
+        assert.equal(providerKeyToVerifiers(base.id, 'zelle-chase'), null);
+    });
+    it('providerKeyToVerifiersMap returns the exact v2Verifiers array of each config', () => {
+        const map = providerKeyToVerifiersMap(base.id);
+        const config = providerConfigs(base.id).venmo;
+        assert.deepEqual(map.get('venmo'), config.v2Verifiers);
+    });
+    it('manual maps to the zero address (its only "verifier")', () => {
+        const verifiers = providerKeyToVerifiers(base.id, 'manual');
+        assert.deepEqual(verifiers, ['0x0000000000000000000000000000000000000000']);
+    });
+});
+/**
+ * Tests for {@link getPaymentMethodConfig} — resolve a config from EITHER a
+ * 20-byte verifier address (V2) OR a 32-byte payment-method hash (V3), with a
+ * null-chain "search every chain" path.
+ */
+describe('getPaymentMethodConfig', () => {
+    const venmoBaseVerifier = '0x9a733B55a875D0DB4915c6B36350b24F8AB99dF5';
+    it('resolves a 20-byte V2 verifier address to its config', () => {
+        assert.equal(getPaymentMethodConfig(base.id, venmoBaseVerifier)?.key, 'venmo');
+    });
+    it('resolves a 32-byte V3 payment-method hash to its config', () => {
+        const venmoHash = providerKeyToContractId('venmo');
+        assert.equal(getPaymentMethodConfig(base.id, venmoHash)?.key, 'venmo');
+    });
+    it('with null chainId searches every chain for a V2 verifier address', () => {
+        // The Pulsechain venmo verifier is unknown to Base, so this only resolves
+        // because null fans the search out across all chains.
+        const venmoPulseVerifier = '0x0Dd524dA03f610480aF3F433B411b6016cFBDeab';
+        assert.equal(getPaymentMethodConfig(null, venmoPulseVerifier)?.key, 'venmo');
+    });
+    it('returns null for an unknown verifier address', () => {
+        assert.equal(getPaymentMethodConfig(base.id, '0x0000000000000000000000000000000000000001'), null);
+    });
+    it('returns null for a string that is neither a 20-byte address nor a 32-byte hash', () => {
+        // Guard: a 10-char "0xdeadbeef" is not an address and not length 66, so
+        // there is nothing to look up.
+        assert.equal(getPaymentMethodConfig(base.id, '0xdeadbeef'), null);
+    });
+});
+/**
+ * Tests for {@link getPaymentMethodName} — name resolution from a provider key,
+ * a sub-provider key, a V3 hash, or a V2 address.
+ */
+describe('getPaymentMethodName', () => {
+    it('returns the display name for a main provider key', () => {
+        assert.equal(getPaymentMethodName(base.id, 'cashapp'), 'Cash App');
+    });
+    it('returns the bank name for a sub-provider key', () => {
+        assert.equal(getPaymentMethodName(base.id, 'zelle-bofa'), 'Bank of America');
+    });
+    it('resolves a V3 payment-method hash to the provider name', () => {
+        const revolutHash = providerKeyToContractId('revolut');
+        assert.equal(getPaymentMethodName(base.id, revolutHash), 'Revolut');
+    });
+    it('resolves a V2 verifier address to the provider name', () => {
+        assert.equal(getPaymentMethodName(base.id, '0x9a733B55a875D0DB4915c6B36350b24F8AB99dF5'), 'Venmo');
+    });
+    it('returns "Unknown" for an unrecognised 32-byte hash', () => {
+        const unknown = '0x0000000000000000000000000000000000000000000000000000000000000003';
+        assert.equal(getPaymentMethodName(base.id, unknown), 'Unknown');
+    });
+    it('returns "Unknown" for an unrecognised verifier address', () => {
+        assert.equal(getPaymentMethodName(base.id, '0x0000000000000000000000000000000000000001'), 'Unknown');
+    });
+});
+/**
+ * Tests for the minimum-amount helpers: {@link getPaymentMethodMinimum},
+ * {@link getPaymentProviderMinimum}, {@link calculateEffectiveMinimum}.
+ * A wrong minimum lets a buyer attempt an order the rail will reject.
+ */
+describe('payment minimums', () => {
+    it('getPaymentMethodMinimum returns the configured per-provider minimum', () => {
+        assert.equal(getPaymentMethodMinimum(base.id, 'venmo'), 1.0);
+    });
+    it('getPaymentMethodMinimum reflects Chime\'s lower 0.1 minimum (per-provider override)', () => {
+        // Chime is the one provider configured below 1.0; this guards the value
+        // actually flowing through rather than a hard-coded default.
+        assert.equal(getPaymentMethodMinimum(base.id, 'chime'), 0.1);
+    });
+    it('getPaymentMethodMinimum returns 0 for the manual sentinel', () => {
+        assert.equal(getPaymentMethodMinimum(base.id, 'manual'), 0.0);
+    });
+    it('getPaymentMethodMinimum returns 0 for an unknown provider key', () => {
+        assert.equal(getPaymentMethodMinimum(base.id, 'nonexistent'), 0);
+    });
+    it('getPaymentMethodMinimum defaults to Base config when chainId is null', () => {
+        assert.equal(getPaymentMethodMinimum(null, 'venmo'), 1.0);
+    });
+    it('getPaymentProviderMinimum is a thin wrapper over getPaymentMethodMinimum', () => {
+        assert.equal(getPaymentProviderMinimum(base.id, 'venmo'), getPaymentMethodMinimum(base.id, 'venmo'));
+        assert.equal(getPaymentProviderMinimum(base.id, 'chime'), 0.1);
+    });
+    describe('calculateEffectiveMinimum', () => {
+        const token = getDefaultToken(base.id); // USDC, 6 decimals
+        const ratesFor = (keys) => new Map(keys.map(key => [key, new Map()]));
+        it('uses the user minimum when it exceeds every provider minimum', () => {
+            // User asks for a $5 floor; venmo's rail floor is $1. The effective floor
+            // is the higher of the two = $5 (5_000000 base units at 6 decimals).
+            const result = calculateEffectiveMinimum(base.id, 5000000n, token, ratesFor(['venmo']));
+            assert.equal(result.userMinAmountWei, 5000000n);
+            assert.equal(result.providerMinAmountWei, 1000000n);
+            assert.equal(result.effectiveMinAmountWei, 5000000n);
+            assert.equal(result.formattedEffectiveMin, '5');
+        });
+        it('raises the floor to the provider minimum when the user minimum is lower', () => {
+            // User floor $0; venmo rail floor $1 wins.
+            const result = calculateEffectiveMinimum(base.id, 0n, token, ratesFor(['venmo']));
+            assert.equal(result.providerMinAmountWei, 1000000n);
+            assert.equal(result.effectiveMinAmountWei, 1000000n);
+            assert.equal(result.formattedEffectiveMin, '1');
+        });
+        it('takes the HIGHEST provider minimum across multiple providers', () => {
+            // Chime ($0.1) + Venmo ($1) → the provider floor is the max ($1), not the
+            // first, the min, or a sum. This is the branch that protects against a
+            // mixed-rail deposit being floored too low for one of its rails.
+            const result = calculateEffectiveMinimum(base.id, 0n, token, ratesFor(['chime', 'venmo']));
+            assert.equal(result.providerMinAmountWei, 1000000n);
+        });
+        it('treats the provider minimum as zero when no provider rates are supplied', () => {
+            // Without rates there is no rail floor to enforce; only the user floor
+            // applies.
+            const result = calculateEffectiveMinimum(base.id, 2000000n, token, undefined);
+            assert.equal(result.providerMinAmountWei, 0n);
+            assert.equal(result.effectiveMinAmountWei, 2000000n);
+        });
+        it('accepts the user minimum as a decimal string and parses it to bigint', () => {
+            // Callers pass either bigint or string; the string path must BigInt()
+            // cleanly and not drift.
+            const result = calculateEffectiveMinimum(base.id, '3000000', token, ratesFor(['venmo']));
+            assert.equal(result.userMinAmountWei, 3000000n);
+            assert.equal(result.effectiveMinAmountWei, 3000000n);
+        });
+    });
+});
+/**
+ * Tests for the "is this payment method known?" predicates. These gate whether
+ * the UI logs an error for an unrecognised method or silently treats it as a
+ * known external integration.
+ */
+describe('payment method known predicates', () => {
+    const pendleId = '0x5908bb0c9b87763ac6171d4104847667e7f02b4c47b574fe890c1f439ed128bb';
+    const venmoBaseVerifier = '0x9a733B55a875D0DB4915c6B36350b24F8AB99dF5';
+    it('isExternalPaymentMethod is true for a registered external id (Pendle)', () => {
+        assert.equal(isExternalPaymentMethod(pendleId), true);
+    });
+    it('isExternalPaymentMethod is false for an id not in the external registry', () => {
+        assert.equal(isExternalPaymentMethod('0x0000000000000000000000000000000000000000000000000000000000000009'), false);
+    });
+    it('getExternalPaymentMethod returns the metadata for a known external id', () => {
+        const meta = getExternalPaymentMethod(pendleId);
+        assert.equal(meta?.name, 'pendle');
+        assert.equal(meta?.chainId, 8453);
+    });
+    it('getExternalPaymentMethod returns undefined for an unknown id', () => {
+        assert.equal(getExternalPaymentMethod('0x0000000000000000000000000000000000000000000000000000000000000009'), undefined);
+    });
+    it('externalPaymentMethods registry keys round-trip through isExternalPaymentMethod', () => {
+        // Every key in the registry must be reported external — the predicate and
+        // the registry are the same source of truth.
+        for (const id of Object.keys(externalPaymentMethods)) {
+            assert.equal(isExternalPaymentMethod(id), true);
+        }
+    });
+    it('isPaymentMethodKnown is true for a registered V2 verifier address', () => {
+        assert.equal(isPaymentMethodKnown(base.id, venmoBaseVerifier), true);
+    });
+    it('isPaymentMethodKnown is false for an unregistered verifier address', () => {
+        assert.equal(isPaymentMethodKnown(base.id, '0x0000000000000000000000000000000000000001'), false);
+    });
+    it('isPaymentMethodIdKnown short-circuits true for an external id without a verifier address', () => {
+        assert.equal(isPaymentMethodIdKnown(base.id, pendleId), true);
+    });
+    it('isPaymentMethodIdKnown is false for an unknown id with no verifier address to fall back on', () => {
+        assert.equal(isPaymentMethodIdKnown(base.id, '0x0000000000000000000000000000000000000000000000000000000000000009'), false);
+    });
+    it('isPaymentMethodIdKnown falls back to the verifier address when the id is not external', () => {
+        // Unknown id, but the accompanying verifier address is a real Venmo
+        // verifier → known via providerConfigs.
+        const unknownId = '0x0000000000000000000000000000000000000000000000000000000000000009';
+        assert.equal(isPaymentMethodIdKnown(base.id, unknownId, venmoBaseVerifier), true);
+    });
+});
+/**
+ * Tests for sub-provider identity helpers: {@link isSubProviderKey},
+ * {@link getParentProviderKey}, {@link getExtensionPlatform}. Sub-providers
+ * (the Zelle banks) must collapse correctly to parents for maker lookups but
+ * fan out to bank-specific extension platforms for proof capture.
+ */
+describe('sub-provider identity helpers', () => {
+    it('isSubProviderKey is true for a Zelle sub key', () => {
+        assert.equal(isSubProviderKey('zelle-chase'), true);
+    });
+    it('isSubProviderKey is false for the Zelle parent key', () => {
+        // The parent is NOT a sub-provider — collapsing it would be wrong.
+        assert.equal(isSubProviderKey('zelle'), false);
+    });
+    it('isSubProviderKey is false for an unrelated main provider', () => {
+        assert.equal(isSubProviderKey('venmo'), false);
+    });
+    it('getParentProviderKey returns the parent for a sub-provider', () => {
+        assert.equal(getParentProviderKey('zelle-chase'), 'zelle');
+        assert.equal(getParentProviderKey('zelle-bofa'), 'zelle');
+    });
+    it('getParentProviderKey returns null for a non-sub-provider key', () => {
+        assert.equal(getParentProviderKey('venmo'), null);
+    });
+    it('getParentProviderKey returns null for an unknown dashed key', () => {
+        // Defensive: a 'foo-bar' shape that is not a registered sub-provider must
+        // not be treated as having a parent.
+        assert.equal(getParentProviderKey('foo-bar'), null);
+    });
+    it('getExtensionPlatform maps each Zelle sub to its bank-specific extension folder', () => {
+        // The extension folder name differs from the sub key ('zelle-bofa' →
+        // 'bankofamerica'); sending the wrong folder makes the extension fail to
+        // capture the proof.
+        assert.equal(getExtensionPlatform('zelle-chase'), 'chase');
+        assert.equal(getExtensionPlatform('zelle-bofa'), 'bankofamerica');
+        assert.equal(getExtensionPlatform('zelle-citi'), 'citi');
+    });
+    it('getExtensionPlatform returns the key itself for a main provider', () => {
+        assert.equal(getExtensionPlatform('venmo'), 'venmo');
+        assert.equal(getExtensionPlatform('revolut'), 'revolut');
+    });
+});
+/**
+ * Tests for {@link providerRequiresMetadataIndex} — the per-provider gate for
+ * whether a Buyer TEE proof must carry the metadata `index`. Sending it to a
+ * provider that does not expect it (or omitting it for one that does) makes the
+ * enclave reject the capture, so this must be exact per the zkp2p 0.6.0 spec.
+ */
+describe('providerRequiresMetadataIndex', () => {
+    it('requires the index for Venmo, Cash App, Revolut, and Zelle', () => {
+        assert.equal(providerRequiresMetadataIndex('venmo'), true);
+        assert.equal(providerRequiresMetadataIndex('cashapp'), true);
+        assert.equal(providerRequiresMetadataIndex('revolut'), true);
+        assert.equal(providerRequiresMetadataIndex('zelle'), true);
+    });
+    it('requires the index for a Zelle sub-bank via its parent prefix', () => {
+        // Keyed on the parent: every 'zelle-*' sub qualifies because its parent is
+        // Zelle.
+        assert.equal(providerRequiresMetadataIndex('zelle-chase'), true);
+        assert.equal(providerRequiresMetadataIndex('zelle-citi'), true);
+    });
+    it('OMITS the index for Wise, PayPal, and Monzo', () => {
+        assert.equal(providerRequiresMetadataIndex('wise'), false);
+        assert.equal(providerRequiresMetadataIndex('paypal'), false);
+        assert.equal(providerRequiresMetadataIndex('monzo'), false);
+    });
+});
+/**
+ * Tests for the icon helpers: {@link getProviderIconStack} (parent+sub stack)
+ * and {@link getPaymentIcon} (single iconify string).
+ */
+describe('provider icon helpers', () => {
+    it('getProviderIconStack returns a single entry for a main provider', () => {
+        const stack = getProviderIconStack(base.id, 'venmo');
+        assert.equal(stack.length, 1);
+        assert.equal(stack[0].icon, 'ion:logo-venmo');
+        assert.equal(stack[0].name, 'Venmo');
+    });
+    it('getProviderIconStack returns [parent, sub] for a sub-provider', () => {
+        // The UI badges the parent brand behind the bank glyph, so both must be
+        // present and ordered parent-first.
+        const stack = getProviderIconStack(base.id, 'zelle-chase');
+        assert.equal(stack.length, 2);
+        assert.equal(stack[0].name, 'Zelle');
+        assert.equal(stack[0].icon, 'simple-icons:zelle');
+        assert.equal(stack[1].name, 'Chase');
+        assert.equal(stack[1].icon, 'simple-icons:chase');
+    });
+    it('getProviderIconStack falls back to the manual icon for an unknown key', () => {
+        const stack = getProviderIconStack(base.id, 'nonexistent');
+        assert.equal(stack.length, 1);
+        assert.equal(stack[0].icon, 'mdi:help-circle');
+        assert.equal(stack[0].name, 'Unknown');
+    });
+    it('getPaymentIcon returns the iconify string for a main provider', () => {
+        assert.equal(getPaymentIcon(base.id, 'venmo'), 'ion:logo-venmo');
+    });
+    it('getPaymentIcon resolves a sub-provider icon directly', () => {
+        assert.equal(getPaymentIcon(base.id, 'zelle-chase'), 'simple-icons:chase');
+    });
+    it('getPaymentIcon falls back to the manual icon for an unknown key', () => {
+        assert.equal(getPaymentIcon(base.id, 'nonexistent'), 'mdi:help-circle');
+    });
+    it('getPaymentIcon tolerates a null chainId (defaults to Pulsechain config)', () => {
+        assert.equal(getPaymentIcon(null, 'venmo'), 'ion:logo-venmo');
+    });
+});
+/**
+ * Tests for {@link getPlatformRisk} — the reputation cap/cooldown config per
+ * provider, with a documented medium-risk default for unknown providers.
+ */
+describe('getPlatformRisk', () => {
+    it('returns the high-risk profile for Venmo (1x cap, cooldown)', () => {
+        const risk = getPlatformRisk(base.id, 'venmo');
+        assert.equal(risk.riskLevel, 'high');
+        assert.equal(risk.capMultiplier, 1);
+        assert.equal(risk.hasCooldown, true);
+        assert.equal(risk.minimumTier, null);
+    });
+    it('returns the low-risk profile for Revolut (5x cap, no cooldown)', () => {
+        const risk = getPlatformRisk(base.id, 'revolut');
+        assert.equal(risk.riskLevel, 'low');
+        assert.equal(risk.capMultiplier, 5);
+        assert.equal(risk.hasCooldown, false);
+    });
+    it('falls back to the medium-risk default for an unknown provider', () => {
+        // Unknown provider → DEFAULT_PLATFORM_RISK (medium, 1x, cooldown). This is
+        // the safe-by-default branch: an unrecognised rail must not get a generous
+        // cap.
+        const risk = getPlatformRisk(base.id, 'nonexistent');
+        assert.equal(risk.riskLevel, 'medium');
+        assert.equal(risk.capMultiplier, 1);
+        assert.equal(risk.hasCooldown, true);
+        assert.equal(risk.minimumTier, null);
+    });
+});
+/**
+ * Tests for {@link fromPeerTier} — the peer-tier-name → universal-tier-name
+ * map. A broken entry mis-tiers a taker, changing their caps and cooldowns.
+ */
+describe('fromPeerTier', () => {
+    it('maps the peer peasant name to the neutral-zero tier', () => {
+        assert.equal(fromPeerTier('peer_peasant'), 'peasant');
+    });
+    it('maps the bare "peer" name to the neutral tier', () => {
+        // 'peer' (no suffix) is the neutral tier, NOT peasant — an easy off-by-one
+        // in the naming scheme.
+        assert.equal(fromPeerTier('peer'), 'neutral');
+    });
+    it('throws on an invalid peer tier name', () => {
+        assert.throws(() => fromPeerTier('not_a_tier'), /Invalid peer tier/);
+    });
+    it('round-trips with tierToPeerTier for every universal tier', () => {
+        // The two maps must be exact inverses, or a tier that survives one
+        // conversion would be corrupted by the other.
+        for (const tier of Object.values(tiers)) {
+            assert.equal(fromPeerTier(tierToPeerTier[tier]), tier);
+        }
+    });
+});
+/**
+ * Tests for {@link getAllPaymentMethods} / {@link verifiablePaymentMethods} —
+ * the lists that populate provider pickers. Disabled providers must be hidden;
+ * manual must be present in the full list but absent from the verifiable one.
+ */
+describe('getAllPaymentMethods and verifiablePaymentMethods', () => {
+    it('includes enabled providers and excludes config-disabled ones', () => {
+        const methods = getAllPaymentMethods(base.id);
+        assert.ok(methods.includes('venmo'), 'venmo (enabled) should be listed');
+        assert.ok(methods.includes('revolut'), 'revolut (enabled) should be listed');
+        assert.ok(!methods.includes('paypal'), 'paypal (disabled:true) must be hidden');
+        assert.ok(!methods.includes('n26'), 'n26 (disabled:true) must be hidden');
+    });
+    it('includes the manual sentinel in the full list', () => {
+        assert.ok(getAllPaymentMethods(base.id).includes('manual'));
+    });
+    it('does NOT include sub-providers unless explicitly requested', () => {
+        assert.ok(!getAllPaymentMethods(base.id).includes('zelle-chase'));
+    });
+    it('includes Zelle sub-providers when includeSubProviders is true', () => {
+        const methods = getAllPaymentMethods(base.id, true);
+        assert.ok(methods.includes('zelle-chase'));
+        assert.ok(methods.includes('zelle-bofa'));
+        assert.ok(methods.includes('zelle-citi'));
+    });
+    it('verifiablePaymentMethods drops manual but keeps real providers', () => {
+        const methods = verifiablePaymentMethods(base.id);
+        assert.ok(!methods.includes('manual'), 'manual is not verifiable');
+        assert.ok(methods.includes('venmo'));
+    });
+    it('verifiablePaymentMethods still fans out sub-providers when requested, minus manual', () => {
+        const methods = verifiablePaymentMethods(base.id, true);
+        assert.ok(methods.includes('zelle-chase'));
+        assert.ok(!methods.includes('manual'));
+    });
+});

package/dist/reputation.test.js

@@ -197,11 +197,29 @@ describe('formatCooldown', () => {
         assert.equal(formatCooldown(6), '6h cooldown');
         assert.equal(formatCooldown(12), '12h cooldown');
     });
+    it('renders sub-hour durations in minutes', () => {
+        // The `hours < 1` branch converts the fractional hour to whole
+        // minutes. No tier currently configures a sub-hour cooldown, but
+        // formatCooldown is a standalone formatter the JSDoc documents as
+        // producing "30m cooldown" — pin it so a future fractional tier
+        // (or a per-platform override) doesn't silently render "0.5h".
+        assert.equal(formatCooldown(0.5), '30m cooldown');
+        assert.equal(formatCooldown(0.25), '15m cooldown');
+    });
 });
 describe('formatCap', () => {
     it('should format null as "Locked"', () => {
         assert.equal(formatCap(null), 'Locked');
     });
+    it('formats the unlimited sentinel as "No limit"', () => {
+        // getEffectiveCapDisplayUsd returns Infinity for president, which
+        // flows straight into formatCap. Without this branch a VIP would
+        // see "$Infinity max". This is the display end of the
+        // UNLIMITED_CAP_BASE_UNITS path, so it is a reachable production
+        // state, not a defensive guard.
+        assert.equal(formatCap(Infinity), 'No limit');
+        assert.equal(formatCap(getEffectiveCapDisplayUsd(UNLIMITED_CAP_BASE_UNITS, USDC)), 'No limit');
+    });
     it('should format cap with dollar sign', () => {
         assert.equal(formatCap(100), '$100 max');
         assert.equal(formatCap(1000), '$1,000 max');

package/dist/units.test.js

@@ -320,6 +320,18 @@ describe('formatAmount', () => {
     it('should return null for null amount', () => {
         assert.equal(formatAmount(mockToken, null), null);
     });
+    it('uses fewer decimals once the integer part reaches double digits', () => {
+        // formatAmount widens precision only for single-digit amounts
+        // (integerDigits < 10) so small differences stay visible. At ten or
+        // more whole units it falls back to baseDecimals — for a 6-decimal
+        // token that is min(6 - 4, 8) = 2 places. 12.000000 → "12.00",
+        // not "12.0000". This is the false side of the integerDigits ternary.
+        assert.equal(formatAmount(mockToken, 12000000n), '12.00');
+        // 1234.56789 truncates to the same 2 base decimals (and gains a
+        // thousands separator), confirming the wide-precision branch is not
+        // taken for large amounts.
+        assert.equal(formatAmount(mockToken, 1234567890n), '1,234.56');
+    });
     it('should allow overriding options', () => {
         const result = formatAmount(mockToken, 1234567n, { truncateDecimals: 4 });
         assert.ok(result);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@provex/utils",
-  "version": "1.9.1",
+  "version": "1.9.2-rc.20260702180200.fd5d003",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -129,9 +129,6 @@
     "skills",
     "README.md"
   ],
-  "dependencies": {
-    "@zkp2p/providers": "github:zkp2p/providers#7751475b73b533b342d8518628578b33ea191a19"
-  },
   "peerDependencies": {
     "viem": "^2.0.0"
   },