@provex/utils 1.6.2 → 1.7.0-rc.20260522201545.020a3eb

package/dist/reputation.js

@@ -9,22 +9,27 @@
  * - **Platform risk configs**: Multipliers and cooldown flags from payment.ts
  *
  * @remarks
- * These limits only apply to Base chain deposits using the peer gating service.
- * Pulsechain deposits do not have reputation-based restrictions.
+ * Reputation is now scored from PulseChain volume only — Base data is no
+ * longer aggregated. The taker cap still varies by tier; PulseChain is the
+ * only chain that produces taker-tier-influencing volume.
  *
- * Tier progression (by fulfilled volume in USD):
- * - Peer Peasant: $0+ → $100 cap, 12h cooldown
- * - Peer: $500+ → $250 cap, 6h cooldown
- * - Peer Plus: $2,000+ → $1,000 cap, no cooldown
- * - Peer Pro: $10,000+ → $2,500 cap, no cooldown
- * - Peer Platinum: $25,000+ → $5,000 cap, no cooldown
- * - Peer President: Manually assigned VIP → unlimited cap, no cooldown, bypasses all locks
+ * Tier progression (by CUMULATIVE / lifetime fulfilled volume in USD).
+ * Thresholds mirror peer.xyz's published ladder
+ * (https://docs.peer.xyz/guides/for-buyers/reputation#the-five-tiers).
+ * Volume is NOT windowed — it accumulates over the user's lifetime, so
+ * a user only ever moves UP the ladder, never back down for inactivity:
+ * - Entry:    $0+       → $100 cap,   12h cooldown
+ * - Neutral:  $500+     → $250 cap,   6h cooldown
+ * - Plus:     $2,000+   → $1,000 cap, no cooldown
+ * - Pro:      $10,000+  → $2,500 cap, no cooldown
+ * - Platinum: $25,000+  → $5,000 cap, no cooldown
+ * - VIP:      Manually assigned → unlimited cap, no cooldown, bypasses all locks
  *
  * Platform multipliers modify the base cap:
  * - Low risk (Revolut, Wise, Monzo, MercadoPago): 5x multiplier, no cooldown
  * - Medium risk (Zelle): 1.5x multiplier
  * - High risk (Venmo, CashApp): 1x multiplier
- * - Highest risk (PayPal): 0.75x multiplier, requires Peer Plus tier
+ * - Highest risk (PayPal): 0.75x multiplier, requires Plus tier or higher
  *
  * @see {@link payment} for platform risk configurations
  */
@@ -35,47 +40,52 @@ import { tiers, getPlatformRisk, } from './payment.js';
  * Maps universal tier names to their configuration.
  *
  * @remarks
- * Tier names in the codebase use short universal names (peasant, neutral, plus, pro, platinum, president)
- * while the UI displays the peer brand names (Peer Peasant, Peer, Peer Plus, etc.)
+ * Internal tier keys (peasant / neutral / plus / pro / platinum / president)
+ * are stable data identifiers and DO NOT change — the indexer, the contract
+ * gating service, and persisted user state all key on them. The `name` field
+ * below is the user-facing display name; we use a neutral progression ladder
+ * (Entry / Neutral / Plus / Pro / Platinum / VIP) rather than peer.xyz's
+ * brand voice ("Peer Peasant" etc.), which is theirs and reads as gentle
+ * hazing of low-volume users — not the tone Provex wants.
  */
 export const TAKER_TIERS = {
     [tiers.PEASANT]: {
-        name: 'Peer Peasant',
+        name: 'Entry',
         volumeThreshold: 0,
         baseCap: 100,
         cooldownHours: 12,
         volumeRangeDisplay: '$0 - $500',
     },
     [tiers.NEUTRAL]: {
-        name: 'Peer',
+        name: 'Neutral',
         volumeThreshold: 500,
         baseCap: 250,
         cooldownHours: 6,
         volumeRangeDisplay: '$500 - $2k',
     },
     [tiers.PLUS]: {
-        name: 'Peer Plus',
+        name: 'Plus',
         volumeThreshold: 2000,
         baseCap: 1000,
         cooldownHours: 0,
         volumeRangeDisplay: '$2k - $10k',
     },
     [tiers.PRO]: {
-        name: 'Peer Pro',
+        name: 'Pro',
         volumeThreshold: 10000,
         baseCap: 2500,
         cooldownHours: 0,
         volumeRangeDisplay: '$10k - $25k',
     },
     [tiers.PLATINUM]: {
-        name: 'Peer Platinum',
+        name: 'Platinum',
         volumeThreshold: 25000,
         baseCap: 5000,
         cooldownHours: 0,
         volumeRangeDisplay: '$25k+',
     },
     [tiers.PRESIDENT]: {
-        name: 'Peer President',
+        name: 'VIP',
         volumeThreshold: Infinity, // Manually assigned — cannot be reached via volume
         baseCap: 0, // 0 = no cap (VIP limits)
         cooldownHours: 0,
@@ -94,25 +104,46 @@ export const TIER_ORDER = [
  * Matches peer.xyz's TR() function behaviour.
  *
  * @example
- * getVolumeRangeDisplay('pro')    // "$10k - $25k"
+ * getVolumeRangeDisplay('pro')    // "$5k - $10k"
  * getVolumeRangeDisplay('president') // "VIP"
  */
 export function getVolumeRangeDisplay(tier) {
     return TAKER_TIERS[tier].volumeRangeDisplay;
 }
 /**
- * Calculate the effective cap for a tier and platform combination.
- * Derives from tier base cap and platform risk multiplier.
+ * Sentinel cap value used in place of `Infinity` (which has no bigint
+ * representation) to signal "no upper limit" — president tier on every
+ * platform. Equal to `2n ** 256n - 1n` (max uint256); no realistic
+ * token amount can exceed it, so the standard `amount > cap` comparison
+ * naturally short-circuits to false for unlimited users.
+ *
+ * Callers that render the cap as a string MUST check for this sentinel
+ * before formatting — `Number(UNLIMITED_CAP_BASE_UNITS)` overflows to
+ * `Infinity` but `.toLocaleString()` on the bigint prints a 78-digit
+ * number that is not useful in a UI.
+ */
+export const UNLIMITED_CAP_BASE_UNITS = 2n ** 256n - 1n;
+/**
+ * Calculate the effective cap for a tier and platform combination, in
+ * token base units (scaled by `decimals`). Designed so the caller can
+ * compare directly against a token amount it already holds as a bigint
+ * — no rebasing from USD floats on the consumer side.
+ *
+ * Assumes the token trades 1:1 with USD (USDC, USDT, DAI). When we add
+ * a non-stablecoin token this function needs a price feed or the caller
+ * needs to convert before comparing.
  *
  * @param tier - The user's current tier
  * @param providerKey - The payment platform
- * @returns Effective cap in USD, null if platform is locked for this tier,
- *          or Infinity if the user is president (no cap).
+ * @param decimals - Token decimals (USDC = 6, an 18-decimal stable = 18)
+ * @returns Effective cap in token base units, or:
+ *   - `null` — platform is locked at this tier
+ *   - `UNLIMITED_CAP_BASE_UNITS` — president tier (no cap enforcement)
  */
-export function getEffectiveCap({ tier, providerKey, }) {
+export function getEffectiveCap({ tier, providerKey, decimals, }) {
     // President bypasses all caps and locks
     if (tier === tiers.PRESIDENT)
-        return Infinity;
+        return UNLIMITED_CAP_BASE_UNITS;
     const tierConfig = TAKER_TIERS[tier];
     const platformRisk = getPlatformRisk(base.id, providerKey);
     // Check if platform is locked for this tier
@@ -123,7 +154,25 @@ export function getEffectiveCap({ tier, providerKey, }) {
             return null; // Platform locked
         }
     }
-    return Math.floor(tierConfig.baseCap * platformRisk.capMultiplier);
+    // Compute the USD cap first (still uses the integer-USD ladder), then
+    // scale up by 10^decimals into token base units. Math.floor on the
+    // USD product matches the legacy display where a $375.50 cap shows as
+    // $375 — keep the rounding identical to avoid silent enforcement drift.
+    const capUsd = Math.floor(tierConfig.baseCap * platformRisk.capMultiplier);
+    return BigInt(capUsd) * (10n ** BigInt(decimals));
+}
+/**
+ * Companion display helper — converts the base-units cap back into a
+ * USD number for `toLocaleString()`-style formatting. Returns `null`
+ * for locked and `Infinity` for unlimited, mirroring the legacy
+ * `getEffectiveCap` return shape so display code stays simple.
+ */
+export function getEffectiveCapDisplayUsd(cap, decimals) {
+    if (cap === null)
+        return null;
+    if (cap === UNLIMITED_CAP_BASE_UNITS)
+        return Infinity;
+    return Number(cap) / 10 ** decimals;
 }
 /**
  * Get the cooldown duration for a tier and platform.

package/dist/reputation.test.js

@@ -1,16 +1,29 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { TAKER_TIERS, TIER_ORDER, getTierFromVolume, getEffectiveCap, getCooldownHours, getVolumeRangeDisplay, formatCooldown, formatCap, } from './reputation.js';
+import { TAKER_TIERS, TIER_ORDER, getTierFromVolume, getEffectiveCap, getEffectiveCapDisplayUsd, UNLIMITED_CAP_BASE_UNITS, getCooldownHours, getVolumeRangeDisplay, formatCooldown, formatCap, } from './reputation.js';
 import { tiers } from './payment.js';
+// USDC convention — 6 decimals, the existing on-chain token. Tests below
+// also cover an 18-decimal stable to lock in the scaling behavior the
+// future non-USDC rollout will rely on.
+const USDC = 6;
+const STABLE18 = 18;
 describe('TAKER_TIERS', () => {
     it('should have correct tier names', () => {
-        assert.equal(TAKER_TIERS.peasant.name, 'Peer Peasant');
-        assert.equal(TAKER_TIERS.neutral.name, 'Peer');
-        assert.equal(TAKER_TIERS.plus.name, 'Peer Plus');
-        assert.equal(TAKER_TIERS.pro.name, 'Peer Pro');
-        assert.equal(TAKER_TIERS.platinum.name, 'Peer Platinum');
+        // Display names use a neutral progression ladder, NOT peer.xyz brand
+        // voice. Internal tier keys (peasant/neutral/plus/pro/platinum) are
+        // unchanged — those are stable data identifiers consumed by the
+        // indexer and the contract gating service.
+        assert.equal(TAKER_TIERS.peasant.name, 'Entry');
+        assert.equal(TAKER_TIERS.neutral.name, 'Neutral');
+        assert.equal(TAKER_TIERS.plus.name, 'Plus');
+        assert.equal(TAKER_TIERS.pro.name, 'Pro');
+        assert.equal(TAKER_TIERS.platinum.name, 'Platinum');
     });
     it('should have correct volume thresholds', () => {
+        // Cumulative / lifetime fulfilled volume — mirrors peer.xyz's
+        // published ladder ($0 / $500 / $2k / $10k / $25k). Locked here so
+        // any drift surfaces immediately; the JSDoc on TAKER_TIERS cites
+        // the upstream source.
         assert.equal(TAKER_TIERS.peasant.volumeThreshold, 0);
         assert.equal(TAKER_TIERS.neutral.volumeThreshold, 500);
         assert.equal(TAKER_TIERS.plus.volumeThreshold, 2000);
@@ -88,25 +101,60 @@ describe('getTierFromVolume', () => {
         assert.notEqual(getTierFromVolume(1_000_000_000), tiers.PRESIDENT);
     });
 });
-describe('getEffectiveCap', () => {
-    it('should calculate effective cap with multiplier', () => {
-        // Peasant ($100 base) with Revolut (5x) = $500
-        assert.equal(getEffectiveCap({ tier: 'peasant', providerKey: 'revolut' }), 500);
-        // Neutral ($250 base) with Zelle (1.5x) = $375
-        assert.equal(getEffectiveCap({ tier: 'neutral', providerKey: 'zelle' }), 375);
-        // Plus ($1000 base) with Venmo (1x) = $1000
-        assert.equal(getEffectiveCap({ tier: 'plus', providerKey: 'venmo' }), 1000);
-    });
-    it('should calculate effective cap for low-risk platforms (5x)', () => {
-        // Peasant ($100 base) with Monzo (5x) = $500
-        assert.equal(getEffectiveCap({ tier: 'peasant', providerKey: 'monzo' }), 500);
-        // Neutral ($250 base) with MercadoPago (5x) = $1250
-        assert.equal(getEffectiveCap({ tier: 'neutral', providerKey: 'mercadopago' }), 1250);
-    });
-    // PayPal tests removed — provider disabled until maker liquidity is established
-    it('should return Infinity for president on all platforms (VIP — no cap)', () => {
-        assert.equal(getEffectiveCap({ tier: tiers.PRESIDENT, providerKey: 'venmo' }), Infinity);
-        assert.equal(getEffectiveCap({ tier: tiers.PRESIDENT, providerKey: 'revolut' }), Infinity);
+describe('getEffectiveCap (USDC base units)', () => {
+    it('returns the cap in USDC base units (6 decimals)', () => {
+        // Peasant ($100 base) with Revolut (5x) = $500 = 500_000_000n base units
+        assert.equal(getEffectiveCap({ tier: 'peasant', providerKey: 'revolut', decimals: USDC }), 500000000n);
+        // Neutral ($250 base) with Zelle (1.5x) = $375 = 375_000_000n
+        assert.equal(getEffectiveCap({ tier: 'neutral', providerKey: 'zelle', decimals: USDC }), 375000000n);
+        // Plus ($1000 base) with Venmo (1x) = $1000 = 1_000_000_000n
+        assert.equal(getEffectiveCap({ tier: 'plus', providerKey: 'venmo', decimals: USDC }), 1000000000n);
+    });
+    it('returns the cap for low-risk platforms (5x multiplier)', () => {
+        // Peasant ($100) × Monzo (5x) = $500
+        assert.equal(getEffectiveCap({ tier: 'peasant', providerKey: 'monzo', decimals: USDC }), 500000000n);
+        // Neutral ($250) × MercadoPago (5x) = $1250
+        assert.equal(getEffectiveCap({ tier: 'neutral', providerKey: 'mercadopago', decimals: USDC }), 1250000000n);
+    });
+    it('scales correctly for an 18-decimal token (future non-USDC rollout)', () => {
+        // Same $500 cap, but in 18-decimal base units: 500 * 10^18
+        assert.equal(getEffectiveCap({ tier: 'peasant', providerKey: 'revolut', decimals: STABLE18 }), 500n * 10n ** 18n);
+        // Plus $1000 cap in 18-decimal base units
+        assert.equal(getEffectiveCap({ tier: 'plus', providerKey: 'venmo', decimals: STABLE18 }), 1000n * 10n ** 18n);
+    });
+    it('returns UNLIMITED_CAP_BASE_UNITS for president on every platform', () => {
+        // President bypasses the cap on every platform, regardless of decimals
+        assert.equal(getEffectiveCap({ tier: tiers.PRESIDENT, providerKey: 'venmo', decimals: USDC }), UNLIMITED_CAP_BASE_UNITS);
+        assert.equal(getEffectiveCap({ tier: tiers.PRESIDENT, providerKey: 'revolut', decimals: STABLE18 }), UNLIMITED_CAP_BASE_UNITS);
+    });
+    it('returns null when the platform is locked at this tier', () => {
+        // PayPal carries `minimumTier: PLUS` in the production config, so
+        // peasant and neutral tiers should see it as locked. PayPal is
+        // currently disabled at the deposit-liquidity layer (no makers),
+        // but the gating logic must still treat it as locked for low tiers
+        // so the rule stays enforced if it comes back online.
+        assert.equal(getEffectiveCap({ tier: 'peasant', providerKey: 'paypal', decimals: USDC }), null);
+        assert.equal(getEffectiveCap({ tier: 'neutral', providerKey: 'paypal', decimals: USDC }), null);
+    });
+    it('unlocks the cap once the user reaches the platform minimum tier', () => {
+        // Plus tier matches PayPal's minimumTier — cap should compute as a
+        // bigint, not null. $1000 base * 0.75 multiplier = $750
+        assert.equal(getEffectiveCap({ tier: 'plus', providerKey: 'paypal', decimals: USDC }), 750000000n);
+    });
+});
+describe('getEffectiveCapDisplayUsd', () => {
+    it('returns null for a locked platform', () => {
+        assert.equal(getEffectiveCapDisplayUsd(null, USDC), null);
+    });
+    it('returns Infinity for the unlimited sentinel', () => {
+        assert.equal(getEffectiveCapDisplayUsd(UNLIMITED_CAP_BASE_UNITS, USDC), Infinity);
+    });
+    it('round-trips a USDC base-units cap back to USD dollars', () => {
+        // 500_000_000n base units at 6 decimals = $500
+        assert.equal(getEffectiveCapDisplayUsd(500000000n, USDC), 500);
+    });
+    it('round-trips an 18-decimal base-units cap back to USD dollars', () => {
+        assert.equal(getEffectiveCapDisplayUsd(500n * 10n ** 18n, STABLE18), 500);
     });
 });
 describe('getCooldownHours', () => {

package/dist/transports.js

@@ -16,6 +16,21 @@
  */
 import { fallback, http } from 'viem';
 import { chainIdToChain } from './chain.js';
+// 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 = {};
+let _rpcLastWindow = Date.now();
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const _isDebug = () => typeof window !== 'undefined' && window.__RPC_DEBUG === true;
+const _rpcLog = (method) => {
+    if (!_isDebug())
+        return;
+    _rpcCounts[method] = (_rpcCounts[method] ?? 0) + 1;
+    const now = Date.now();
+    const total = Object.values(_rpcCounts).reduce((a, b) => a + b, 0);
+    const elapsed = ((now - _rpcLastWindow) / 1000).toFixed(1);
+    console.debug(`[RPC] ${method} | ${total} calls in ${elapsed}s | window: ${JSON.stringify(_rpcCounts)}`);
+};
 /**
  * Provex-curated fallback RPC URLs per chain, applied after caller overrides
  * but before the viem chain default.
@@ -75,24 +90,31 @@ export const resolveChainRpcUrls = (chainId, options = {}) => {
  */
 export const createChainTransport = (chainId, options = {}) => {
     const urls = resolveChainRpcUrls(chainId, options);
-    const transports = urls.map((url) => http(url));
-    // Rank-probing is what makes idle pages chatty: viem pings every transport
-    // every `interval` ms to score latency. Defaults are interval=10s,
-    // sampleCount=10 — applied per chain per transport, that's ~12 idle calls
-    // per minute on a 2-RPC chain before any user action.
-    //
-    // Two cuts:
-    //   1. Single-transport chains get rank disabled entirely. There's nothing
-    //      to rank against, so probing is pure waste.
-    //   2. Multi-transport chains get a 60s interval + 3-sample window. Slower
-    //      than viem's default but still tight enough that a hung primary
-    //      shifts traffic within a couple of minutes, which is the right grain
-    //      for the browser-side latency model.
+    const transports = urls.map((url) => http(url, {
+        retryCount: 2,
+        onFetchRequest: (req) => {
+            void req.clone().json().then((body) => _rpcLog(body.method ?? '?')).catch(() => { });
+        },
+    }));
+    // Single-URL chains: return the transport directly. fallback([single]) adds
+    // overhead with no benefit — there's nothing to fall back to, and retryCount
+    // is already set on the http() call above.
     if (transports.length <= 1) {
-        return fallback(transports, { retryCount: 2 });
+        return transports[0];
     }
+    // Multi-URL chains: rank-enabled fallback so the fastest healthy endpoint
+    // serves traffic. Custom ping uses eth_blockNumber instead of viem's default
+    // net_listening — measures actual query latency (not just TCP round-trip) and
+    // avoids noisy net_listening entries in server access logs.
+    //
+    // interval=60s: one probe cycle per minute is plenty for browser clients; the
+    // primary RPC only shifts after it's been slow for a full minute, which is the
+    // right grain for a latency model (not a health check).
     return fallback(transports, {
-        rank: { interval: 60_000, sampleCount: 3 },
-        retryCount: 2,
+        rank: {
+            interval: 60_000,
+            sampleCount: 3,
+            ping: (t) => t.transport.request({ method: 'eth_blockNumber', params: [] }),
+        },
     });
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@provex/utils",
-  "version": "1.6.2",
+  "version": "1.7.0-rc.20260522201545.020a3eb",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -108,6 +108,10 @@
     "./transports": {
       "import": "./dist/transports.js",
       "types": "./dist/transports.d.ts"
+    },
+    "./consent": {
+      "import": "./dist/consent.js",
+      "types": "./dist/consent.d.ts"
     }
   },
   "scripts": {
@@ -118,10 +122,11 @@
   },
   "keywords": [],
   "author": "",
-  "license": "ISC",
-  "description": "",
+  "license": "MIT",
+  "description": "Shared types, chain configuration, and utilities for the Provex protocol",
   "files": [
     "dist",
+    "skills",
     "README.md"
   ],
   "dependencies": {

package/skills/utils-integration/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: utils-integration
+description: Use when integrating `@provex/utils` — when looking up Provex contract addresses by chain, formatting fiat currencies, converting between token amounts and currency amounts, sorting deposits/intents, computing maker/taker profits, hashing payee identifiers, serializing bigints across JSON boundaries, or resolving payment provider keys to validation keys. Covers the subpath-import pattern, the bigint-only-no-intermediate-Number arithmetic rule, the JSON bigint round-trip convention, and where chain/currency/provider/token registries live.
+---
+
+# `@provex/utils` Integration
+
+Shared types, registries, and pure utilities for the Provex protocol. No React, no viem clients, no async dependencies — everything here is sync and tree-shakeable via subpath imports.
+
+## Subpath imports — pay only for what you use
+
+The package exposes ~20 subpaths. Always import from the specific subpath, not the root, so bundlers can tree-shake aggressively.
+
+```ts
+import { contracts } from '@provex/utils/contracts'
+import { Currency, getCurrencyInfo, formatCurrencyAmount } from '@provex/utils/currencies'
+import { providers, providerKeyToValidationKey } from '@provex/utils/payment'
+import { tokenByAddress, allTokensInfo } from '@provex/utils/tokens'
+import { formatUnits, parseUnits, addThousandsSeparator } from '@provex/utils/units'
+import { formatTimestamp, formatDuration, interval, sleep } from '@provex/utils/time'
+import { processConversionRates, convertTokenInputToCurrency } from '@provex/utils/conversionRates'
+import { jsonSerializer, mapBigIntFields } from '@provex/utils/json'
+import { getExplorerUrl } from '@provex/utils/chain'
+```
+
+Root `@provex/utils` re-exports everything but defeats tree-shaking. Prefer subpath imports.
+
+## BigInt-only arithmetic (non-negotiable)
+
+All fee/wei/rate/percentile math must stay `bigint` end-to-end. Use `Number()` exactly once — at the leaf where you hand a value to CSS/render. **Never** introduce intermediate `Number()` coercions.
+
+```ts
+// ✅ correct
+const total = amountInt + (amountInt * feeBps) / 10000n
+const displayed = Number(formatUnits(total, { decimals: 6, truncateDecimals: 2 }))
+
+// ❌ wrong — intermediate Number() loses precision on large values
+const total = Number(amountInt) + Number(amountInt * feeBps / 10000n)
+```
+
+`formatUnits` and `parseUnits` are the canonical bigint ↔ string converters. They never go through `Number`.
+
+## JSON round-trip for bigints
+
+Any time bigints cross a JSON boundary (localStorage, fetch body, postMessage), use the package's serializer pair:
+
+```ts
+import { jsonSerializer } from '@provex/utils/json'
+
+// Serialize
+const blob = JSON.stringify({ amount: 1_000_000n }, jsonSerializer.replacer)
+// → '{"amount":"bigint:1000000"}'
+
+// Deserialize
+const parsed = JSON.parse(blob, jsonSerializer.reviver)
+// → { amount: 1000000n }
+```
+
+The tagged-string convention (`bigint:<dec>`) survives `JSON.stringify` / `JSON.parse` round-trips without losing precision. Anything custom should follow this exact shape so other Provex packages can interop.
+
+## Chain and contract lookups
+
+```ts
+import { contracts } from '@provex/utils/contracts'
+
+contracts.escrow[369]              // V3 Escrow on PulseChain
+contracts.orchestrator[369]        // V3 Orchestrator on PulseChain
+contracts.usdc[369]                // USDC token on PulseChain
+contracts.venmoReclaimVerifier[369]
+```
+
+The contracts map is keyed by chain ID. PulseChain (`369`) is the primary deployment; Base (`8453`) is peer-trade only.
+
+```ts
+import { chainIds } from '@provex/utils/chain'
+
+chainIds        // [369, 8453, ...] — protocol-supported set, for STATIC registration
+```
+
+> **Two-layer chain model.** `chainIds` is the **protocol-supported** set (every chain the SDK can address). The **deployment-enabled** set (the chains an app actually trades on) is separate and app-defined. Background loops (oracles, trackers, polling) MUST consume the deployment layer — iterating `chainIds` will boot lazy ChainSources for chains your app isn't trading on and burn RPC credits.
+
+## Currency formatting
+
+```ts
+import { getCurrencyInfo, formatCurrencyAmount, Currency } from '@provex/utils/currencies'
+
+const usd = getCurrencyInfo('USD')          // { symbol: '$', decimals: 2, ... }
+formatCurrencyAmount(1234.56, 'USD')        // '$1,234.56'
+formatCurrencyAmount(1234.56, 'EUR')        // '€1,234.56'
+
+// Custom currency (rare — most callers use the SUPPORTED_CURRENCIES registry)
+const gbp = new Currency('GBP', '£', 'British Pound', 2)
+```
+
+Supported codes: USD, EUR, GBP, CAD, AUD, JPY, CHF, CNY, INR, BRL, MXN, ARS (plus a few more — see `SUPPORTED_CURRENCIES`).
+
+## Token amount conversions
+
+```ts
+import { convertTokenInputToCurrency, convertCurrencyToTokenOutput } from '@provex/utils/conversionRates'
+import { parseUnits } from '@provex/utils/units'
+
+// Token → fiat (e.g. "100 USDC at 1.05 USD/USDC")
+const fiatAmount = convertTokenInputToCurrency({
+  token: { decimals: 6 },
+  amountOutInt: parseUnits('100', 6),
+  rate: parseUnits('1.05', 18),
+})
+
+// Fiat → token
+const tokenAmount = convertCurrencyToTokenOutput({
+  token: { decimals: 6 },
+  currencyAmountInt: parseUnits('100', 2),  // $100
+  rate: parseUnits('1.05', 18),
+})
+```
+
+Rate decimals are **18** by convention across the protocol — don't change them.
+
+## Payment providers
+
+```ts
+import { providers, subProviders, providerKeyToValidationKey } from '@provex/utils/payment'
+
+providers.VENMO                                 // 'venmo'
+providers.ZELLE                                 // 'zelle'
+subProviders.CHASE                              // 'chase' (Zelle banking partner)
+providerKeyToValidationKey.venmo                // 'venmoUsername'
+providerKeyToValidationKey.zelle                // 'zelleUsername'
+```
+
+Always source provider keys and validation keys from this registry — don't hardcode strings. The keys are used in deposit creation, intent signaling, and indexer queries; drift between sites creates silent matching failures.
+
+## Time and duration helpers
+
+```ts
+import { interval, formatTimestamp, formatDuration, sleep } from '@provex/utils/time'
+
+interval.second   // 1000
+interval.minute   // 60 * 1000
+interval.hour     // 60 * 60 * 1000
+interval.day      // 24 * 60 * 60 * 1000
+
+formatTimestamp(Date.now() - interval.hour)     // '1h ago'
+formatDuration({ from: t0, to: t1 })            // '1 day'
+
+await sleep(1000)
+```
+
+## Common pitfalls
+
+- **Don't hardcode contract addresses.** Always go through `@provex/utils/contracts` so the v2/v3 distinction stays correct.
+- **Don't conflate `chainIds` with deployment-enabled chains.** See the two-layer note above.
+- **Don't introduce `Number()` mid-pipeline.** Single coercion at the leaf only.
+- **Don't `JSON.stringify` raw bigints.** Use `jsonSerializer.replacer`.
+
+## When NOT to import from this package
+
+- **You need React hooks** → use `@provex/react`.
+- **You need a viem client wrapper** → build one with viem directly; this package is sync-only.
+- **You need indexer queries** → use `@provex/indexer-client`.