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

package/dist/tokens.js

@@ -17,23 +17,44 @@ import { base, pulsechain } from 'viem/chains';
 import { chains } from './chain.js';
 import { createChainTransport } from './transports.js';
 /**
- * Pre-configured public clients for supported chains.
- * Used for read-only blockchain interactions (balances, contract reads).
+ * Public clients for supported chains, built on first use.
+ *
+ * **Built lazily on purpose.** These were once constructed at module scope,
+ * which made merely importing this module open network connections.
+ * {@link createChainTransport} returns a rank-enabled `fallback` for any chain
+ * with more than one configured endpoint, and viem starts that ranking poller
+ * as soon as the client exists — a repeating 60-second timer that fires
+ * `eth_blockNumber` at every endpoint in the list.
+ *
+ * Two costs came out of that. Any short-lived process importing this module
+ * could no longer exit: the timers and sockets kept the event loop alive, which
+ * is why three `node --test` files hung for their full timeout with every
+ * assertion passing. And any consumer that imports `@provex/utils` without ever
+ * touching a chain still generated RPC traffic forever — against endpoints this
+ * repo elsewhere takes care not to send avoidable requests to.
+ *
+ * Nothing observable changes for a caller that does use a client: the instance
+ * is memoised, so the ranking poller still starts exactly once per chain.
  *
  * @internal
  */
-const clients = {
-    [base.id]: createPublicClient({
+const createClient = {
+    [base.id]: () => createPublicClient({
         chain: base,
         transport: createChainTransport(base.id),
     }),
-    [pulsechain.id]: createPublicClient({
+    [pulsechain.id]: () => createPublicClient({
         chain: pulsechain,
         transport: createChainTransport(pulsechain.id),
     }),
 };
+const clients = new Map();
 /**
  * Get a public client for a given chain.
+ *
+ * The client is created on the first call for that chain and reused after.
+ * Callers that never invoke this open no connections at all.
+ *
  * @param chain - The viem chain object
  * @returns A viem public client instance for the chain
  * @throws Error if chain is undefined or not configured
@@ -42,10 +63,18 @@ export const publicClient = (chain) => {
     if (!chain || !chain.id) {
         throw new Error('Chain parameter is required and must have an id property');
     }
-    const client = clients[chain.id];
-    if (!client) {
-        throw new Error(`No client configured for chainId ${chain.id}. Supported chains: ${Object.keys(clients).join(', ')}`);
+    const chainId = chain.id;
+    const cached = clients.get(chainId);
+    if (cached)
+        return cached;
+    // Keyed off the configured constructors rather than the caller's chain
+    // object, so a client is only ever built for a chain this package supports.
+    const construct = createClient[chainId];
+    if (!construct) {
+        throw new Error(`No client configured for chainId ${chain.id}. Supported chains: ${Object.keys(createClient).join(', ')}`);
     }
+    const client = construct();
+    clients.set(chainId, client);
     return client;
 };
 /**

package/dist/tokens.test.js

@@ -55,6 +55,17 @@ describe('tokens', () => {
             assert.ok(client, 'Client should exist');
             assert.ok(client.readContract, 'Client should have readContract method');
         });
+        it('returns the same instance for a chain, rather than a new client each call', () => {
+            // Memoisation is not a micro-optimisation here. Each client owns a
+            // transport, and a ranked one owns a poller viem gives no way to stop —
+            // so a fresh client per call would leak one more every time. Callers
+            // reach for `publicClient(chain)` inline (see the tx-flight hooks, which
+            // call it on every poll tick), so "one client per chain, ever" is the
+            // contract this has to keep.
+            assert.strictEqual(publicClient(base), publicClient(base));
+            assert.strictEqual(publicClient(pulsechain), publicClient(pulsechain));
+            assert.notStrictEqual(publicClient(base), publicClient(pulsechain));
+        });
         it('should throw for undefined chain', () => {
             assert.throws(() => publicClient(undefined), { message: 'Chain parameter is required and must have an id property' });
         });

package/dist/transports.d.ts

@@ -16,17 +16,72 @@
  */
 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[]>>;
+/**
+ * Parse a comma-separated RPC URL list into an ordered array of valid URLs.
+ *
+ * This is the single parser for every comma-separated RPC env in the repo —
+ * the browser's `VITE_RPC_URLS_<chainId>` and the server's `BASE_RPC_URL` /
+ * `PULSECHAIN_RPC_URL` all share this shape, matching the `PONDER_RPC_URL_*`
+ * convention the indexer already uses.
+ *
+ * @param raw - Raw env value. Missing, blank, and all-invalid inputs yield `[]`
+ * so callers can treat the result as a priority-ordered prefix without
+ * null-checking.
+ * @returns Ordered array of trimmed, validated URL strings.
+ *
+ * @example
+ * ```ts
+ * parseRpcUrlList('https://a.example, https://b.example')
+ * // ['https://a.example', 'https://b.example']
+ * ```
+ */
+export declare const parseRpcUrlList: (raw: string | undefined | null) => string[];
+/**
+ * How {@link createChainTransport} distributes traffic across the resolved
+ * URL list.
+ *
+ * - `ranked` — viem's latency-based load balancing. The fastest healthy
+ *   endpoint serves traffic. Correct for browsers, where the goal is the
+ *   snappiest response and every endpoint is equally cheap.
+ * - `ordered` — strict priority. Entry #1 serves every request and later
+ *   entries are touched only when the ones before them error. Correct when
+ *   later entries are metered (a paid provider held in reserve), because
+ *   ranking would otherwise route traffic *to* the fast paid endpoint and
+ *   defeat the reason it was placed second.
+ */
+export type ChainTransportStrategy = 'ranked' | 'ordered';
 /**
  * Options accepted by {@link createChainTransport}.
  */
@@ -36,6 +91,14 @@ interface CreateChainTransportOptions {
      * and the chain default. Typically parsed from a `VITE_RPC_URLS_*` env.
      */
     userUrls?: readonly string[];
+    /**
+     * Traffic-distribution strategy. Defaults per environment — see
+     * {@link defaultStrategy}: `ranked` in a browser, preserving the
+     * latency-optimised behaviour every browser call-site relies on, and
+     * `ordered` in Node, where ranking's unstoppable poller would keep the
+     * process alive forever and buy a short-lived process nothing.
+     */
+    strategy?: ChainTransportStrategy;
 }
 /**
  * Resolve the ordered RPC URL list for a chain: caller overrides, then the
@@ -45,11 +108,17 @@ interface CreateChainTransportOptions {
  * @param chainId - The chain ID to resolve URLs for. Must resolve via
  * {@link chainIdToChain}.
  * @param options - Optional caller-supplied overrides.
- * @returns Priority-ordered list of valid RPC URLs (always non-empty,
- * because the chain default is always present).
+ * @returns Priority-ordered, de-duplicated list of valid RPC URLs (always
+ * non-empty, because the chain default is always present).
  *
  * @throws Error if `chainId` has no entry in `chainIdToChain` — fail fast at
  * the boundary rather than silently building an empty list.
+ *
+ * @remarks
+ * Duplicates are collapsed keeping first position. A caller that names the
+ * chain default explicitly — e.g. `BASE_RPC_URL="https://mainnet.base.org,…"`
+ * to pin it as primary — would otherwise get that URL twice, once from the
+ * override list and once from the always-appended chain default.
  */
 export declare const resolveChainRpcUrls: (chainId: ChainId, options?: CreateChainTransportOptions) => string[];
 /**
@@ -58,9 +127,10 @@ export declare const resolveChainRpcUrls: (chainId: ChainId, options?: CreateCha
  *
  * @param chainId - The chain ID to build a transport for. Must resolve via
  * {@link chainIdToChain}.
- * @param options - Optional caller-supplied overrides.
- * @returns A viem `fallback` transport with `rank: true` for latency-based
- * load balancing and `retryCount: 2` per underlying transport.
+ * @param options - Optional caller-supplied overrides and strategy.
+ * @returns A viem `fallback` transport — rank-enabled under the default
+ * `ranked` strategy, strict-priority under `ordered` — with `retryCount: 2`
+ * per underlying transport.
  *
  * @throws Error if `chainId` has no entry in `chainIdToChain` — fail fast at
  * boundary rather than silently falling through to an empty transport list.
@@ -70,6 +140,14 @@ export declare const resolveChainRpcUrls: (chainId: ChainId, options?: CreateCha
  * const transport = createChainTransport(369, { userUrls: ['https://my-rpc'] })
  * const client = createPublicClient({ chain: pulsechain, transport })
  * ```
+ *
+ * @example Hold a metered provider in reserve behind a free primary.
+ * ```ts
+ * const transport = createChainTransport(8453, {
+ *   userUrls: parseRpcUrlList(process.env.BASE_RPC_URL),
+ *   strategy: 'ordered',
+ * })
+ * ```
  */
 export declare const createChainTransport: (chainId: ChainId, options?: CreateChainTransportOptions) => Transport;
 export {};

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,15 +51,91 @@ 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: [],
 };
+/**
+ * Validate a candidate URL string with the `URL` constructor.
+ *
+ * @param candidate - Trimmed URL string to validate.
+ * @returns True if `new URL(candidate)` succeeds.
+ */
+const isValidUrl = (candidate) => {
+    if (!candidate)
+        return false;
+    try {
+        // eslint-disable-next-line no-new
+        new URL(candidate);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Parse a comma-separated RPC URL list into an ordered array of valid URLs.
+ *
+ * This is the single parser for every comma-separated RPC env in the repo —
+ * the browser's `VITE_RPC_URLS_<chainId>` and the server's `BASE_RPC_URL` /
+ * `PULSECHAIN_RPC_URL` all share this shape, matching the `PONDER_RPC_URL_*`
+ * convention the indexer already uses.
+ *
+ * @param raw - Raw env value. Missing, blank, and all-invalid inputs yield `[]`
+ * so callers can treat the result as a priority-ordered prefix without
+ * null-checking.
+ * @returns Ordered array of trimmed, validated URL strings.
+ *
+ * @example
+ * ```ts
+ * parseRpcUrlList('https://a.example, https://b.example')
+ * // ['https://a.example', 'https://b.example']
+ * ```
+ */
+export const parseRpcUrlList = (raw) => {
+    if (typeof raw !== 'string' || raw.trim() === '')
+        return [];
+    return raw
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(isValidUrl);
+};
+/**
+ * The strategy to use when the caller does not name one.
+ *
+ * `ranked` in a browser, `ordered` everywhere else.
+ *
+ * **Why the environment decides.** viem's ranking is a long-lived-client
+ * optimisation: it starts a self-recursive `setTimeout` loop that pings every
+ * endpoint forever, and it exposes no way to stop it — `rankTransports` takes
+ * no abort signal and the client has no teardown. In a browser that is exactly
+ * right; the page owns the client for its lifetime and gets the fastest healthy
+ * endpoint for free.
+ *
+ * In Node the same loop means the process can never exit on its own. A one-shot
+ * script that reads one value hangs at the end of its work, and a test file that
+ * so much as constructs a client hangs for its full timeout with every
+ * assertion passing. `packages/scripts/src/lookup-hash.ts` already carries a
+ * hand-added `process.exit(0)` for precisely this.
+ *
+ * Ranking buys a short-lived process nothing anyway — there is no traffic to
+ * optimise over — while `ordered` gives it the same fallback coverage with
+ * strict priority and no timer. Callers that genuinely want ranking outside a
+ * browser (a long-running Node service) can still pass `strategy: 'ranked'`
+ * explicitly.
+ */
+const defaultStrategy = () => typeof window === 'undefined' ? 'ordered' : 'ranked';
 /**
  * Resolve the ordered RPC URL list for a chain: caller overrides, then the
  * curated fallback list, then the viem chain default. Exposed for testing
@@ -53,11 +144,17 @@ export const FALLBACK_RPC_URLS = {
  * @param chainId - The chain ID to resolve URLs for. Must resolve via
  * {@link chainIdToChain}.
  * @param options - Optional caller-supplied overrides.
- * @returns Priority-ordered list of valid RPC URLs (always non-empty,
- * because the chain default is always present).
+ * @returns Priority-ordered, de-duplicated list of valid RPC URLs (always
+ * non-empty, because the chain default is always present).
  *
  * @throws Error if `chainId` has no entry in `chainIdToChain` — fail fast at
  * the boundary rather than silently building an empty list.
+ *
+ * @remarks
+ * Duplicates are collapsed keeping first position. A caller that names the
+ * chain default explicitly — e.g. `BASE_RPC_URL="https://mainnet.base.org,…"`
+ * to pin it as primary — would otherwise get that URL twice, once from the
+ * override list and once from the always-appended chain default.
  */
 export const resolveChainRpcUrls = (chainId, options = {}) => {
     const chain = chainIdToChain.get(chainId);
@@ -67,7 +164,8 @@ export const resolveChainRpcUrls = (chainId, options = {}) => {
     const userUrls = options.userUrls ?? [];
     const curatedFallbacks = FALLBACK_RPC_URLS[chainId] ?? [];
     const defaultUrl = chain.rpcUrls.default.http[0];
-    return [...userUrls, ...curatedFallbacks, defaultUrl].filter((url) => Boolean(url));
+    const ordered = [...userUrls, ...curatedFallbacks, defaultUrl].filter((url) => Boolean(url));
+    return [...new Set(ordered)];
 };
 /**
  * Build a viem transport for the given chain, layering caller overrides on top
@@ -75,9 +173,10 @@ export const resolveChainRpcUrls = (chainId, options = {}) => {
  *
  * @param chainId - The chain ID to build a transport for. Must resolve via
  * {@link chainIdToChain}.
- * @param options - Optional caller-supplied overrides.
- * @returns A viem `fallback` transport with `rank: true` for latency-based
- * load balancing and `retryCount: 2` per underlying transport.
+ * @param options - Optional caller-supplied overrides and strategy.
+ * @returns A viem `fallback` transport — rank-enabled under the default
+ * `ranked` strategy, strict-priority under `ordered` — with `retryCount: 2`
+ * per underlying transport.
  *
  * @throws Error if `chainId` has no entry in `chainIdToChain` — fail fast at
  * boundary rather than silently falling through to an empty transport list.
@@ -87,6 +186,14 @@ export const resolveChainRpcUrls = (chainId, options = {}) => {
  * const transport = createChainTransport(369, { userUrls: ['https://my-rpc'] })
  * const client = createPublicClient({ chain: pulsechain, transport })
  * ```
+ *
+ * @example Hold a metered provider in reserve behind a free primary.
+ * ```ts
+ * const transport = createChainTransport(8453, {
+ *   userUrls: parseRpcUrlList(process.env.BASE_RPC_URL),
+ *   strategy: 'ordered',
+ * })
+ * ```
  */
 export const createChainTransport = (chainId, options = {}) => {
     const urls = resolveChainRpcUrls(chainId, options);
@@ -102,6 +209,15 @@ export const createChainTransport = (chainId, options = {}) => {
     if (transports.length <= 1) {
         return transports[0];
     }
+    // Ordered strategy: strict priority, no ranking. Entry #1 absorbs every
+    // request and later entries are reached only when the ones before them
+    // error. Ranking is not merely unnecessary here — it is actively wrong when
+    // a later entry is metered, because ranking optimises for latency and a paid
+    // endpoint is usually the fastest one in the list, so it would steer traffic
+    // onto exactly the endpoint the ordering was written to protect.
+    if ((options.strategy ?? defaultStrategy()) === 'ordered') {
+        return fallback(transports);
+    }
     // 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

package/dist/transports.test.js

@@ -1,20 +1,73 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
 import { base, pulsechain } from 'viem/chains';
-import { createChainTransport, 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.
+ *
+ * Only safe for the `ordered` strategy: instantiating a ranked transport
+ * starts viem's background ranking poll loop, which would leave a live timer
+ * behind for the duration of the test run.
+ */
+const dialledUrls = (transport) => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const instance = transport({});
+    if (instance.config.type === 'http')
+        return [instance.value.url];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return instance.value.transports.map((t) => t.value?.url);
+};
 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], []);
         });
     });
+    describe('parseRpcUrlList', () => {
+        it('returns an empty list for unset, blank, and whitespace-only input', () => {
+            assert.deepEqual(parseRpcUrlList(undefined), []);
+            assert.deepEqual(parseRpcUrlList(null), []);
+            assert.deepEqual(parseRpcUrlList(''), []);
+            assert.deepEqual(parseRpcUrlList('   '), []);
+        });
+        it('preserves author-supplied order — position encodes priority', () => {
+            assert.deepEqual(parseRpcUrlList('https://first.example,https://second.example'), ['https://first.example', 'https://second.example']);
+        });
+        it('trims padding so a human-formatted env list is not silently rejected', () => {
+            assert.deepEqual(parseRpcUrlList(' https://a.example ,  https://b.example  '), ['https://a.example', 'https://b.example']);
+        });
+        it('drops malformed entries instead of handing them to the transport layer', () => {
+            assert.deepEqual(parseRpcUrlList('not-a-url, https://good.example, also bad'), ['https://good.example']);
+        });
+        it('returns an empty list when every entry is malformed, so callers fall through to defaults', () => {
+            assert.deepEqual(parseRpcUrlList('nope, also-nope'), []);
+        });
+    });
     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],
             ]);
@@ -26,13 +79,24 @@ 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],
             ]);
         });
+        it('collapses a duplicate when the caller names the chain default explicitly', () => {
+            // Pinning the free public endpoint as primary is the whole point of the
+            // ordered strategy; it must not cost a second, redundant transport.
+            const urls = resolveChainRpcUrls(8453, {
+                userUrls: [base.rpcUrls.default.http[0], 'https://metered.example'],
+            });
+            assert.deepEqual(urls, [base.rpcUrls.default.http[0], 'https://metered.example']);
+        });
         it('throws for unknown chain ID rather than silently returning a single URL', () => {
             assert.throws(() => resolveChainRpcUrls(99999), /no chain definition for chainId 99999/);
         });
@@ -49,5 +113,67 @@ describe('transports', () => {
         it('throws for unknown chain ID via resolveChainRpcUrls', () => {
             assert.throws(() => createChainTransport(99999), /no chain definition for chainId 99999/);
         });
+        it('keeps a metered reserve in second position under the ordered strategy', () => {
+            // Regression guard for the cost bug this strategy exists to prevent:
+            // ranking picks the *fastest* endpoint, and a paid provider is usually
+            // the fastest in the list, so a ranked transport would steer traffic
+            // onto exactly the endpoint the ordering was written to protect.
+            const transport = createChainTransport(8453, {
+                userUrls: [base.rpcUrls.default.http[0], 'https://metered.example'],
+                strategy: 'ordered',
+            });
+            assert.deepEqual(dialledUrls(transport), [
+                base.rpcUrls.default.http[0],
+                'https://metered.example',
+            ]);
+        });
+        it('skips the fallback wrapper when only one endpoint survives resolution', () => {
+            const transport = createChainTransport(8453, {
+                userUrls: [base.rpcUrls.default.http[0]],
+                strategy: 'ordered',
+            });
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            assert.equal(transport({}).config.type, 'http');
+        });
+        it('ignores malformed overrides end-to-end rather than dialling them', () => {
+            const transport = createChainTransport(8453, {
+                userUrls: parseRpcUrlList('garbage, https://metered.example'),
+                strategy: 'ordered',
+            });
+            assert.ok(!dialledUrls(transport).includes('garbage'));
+        });
+    });
+});
+describe('process liveness — the ranking poller has no off switch', () => {
+    // viem's `rankTransports` is a self-recursive `setTimeout` loop with no abort
+    // signal and no teardown on the client, so once it starts, a Node process can
+    // never exit on its own. These run in a subprocess for that exact reason: a
+    // ranked client built in *this* process would wedge the test runner itself,
+    // which is the bug being guarded against.
+    const buildsAndExits = (strategy, timeoutMs) => {
+        const source = [
+            "import { createPublicClient } from 'viem'",
+            "import { pulsechain } from 'viem/chains'",
+            "import { createChainTransport } from './src/transports.js'",
+            `createPublicClient({ chain: pulsechain, transport: createChainTransport(369${strategy ? `, { strategy: '${strategy}' }` : ''}) })`,
+        ].join('\n');
+        const result = spawnSync(process.execPath, ['--import', 'tsx', '--input-type=module', '--eval', source], { cwd: process.cwd(), timeout: timeoutMs, encoding: 'utf8' });
+        // `signal` is non-null when the timeout killed it — i.e. it never exited.
+        return result.signal === null && result.status === 0;
+    };
+    it('exits after building a multi-endpoint transport', () => {
+        // PulseChain resolves to more than one URL, which is the case that used to
+        // get a ranked fallback. A process doing nothing but building this client
+        // must still terminate; when it did not, three test files hung for their
+        // full timeout with every assertion passing, and
+        // `packages/scripts/src/lookup-hash.ts` grew a hand-added `process.exit(0)`.
+        assert.equal(buildsAndExits(undefined, 30_000), true, 'building a default transport left the process alive');
+    });
+    it('does not exit when ranking is explicitly requested', () => {
+        // The counterweight. Without this, the assertion above would still pass if
+        // ranking had simply been deleted, and it would pass vacuously if the
+        // subprocess never ran the code at all. Ranking stays available for a
+        // long-lived service that wants it — the default just is not it.
+        assert.equal(buildsAndExits('ranked', 10_000), false, 'a ranked transport should keep the process alive — the default is the fix, not the removal');
     });
 });

package/dist/units.d.ts

@@ -60,6 +60,15 @@ export interface FormatRateDisplayOptions {
  * @param options - Parsing options with decimals and optional delimiter
  * @returns BigInt representation of the amount
  *
+ * @remarks
+ * The delimiter is removed, not interpreted, so every comma is assumed to be a
+ * thousands separator. Do NOT use this for a value a maker may have typed with
+ * a comma as the *decimal* separator: `parseUnits('1,5', { decimals: 6 })` is
+ * 15, not 1.5, and it fails silently rather than throwing the way viem's own
+ * `parseUnits` would. Conversion rates go through
+ * {@link rateInput.parseRateInput} instead, which treats a lone comma as a
+ * decimal separator and rejects ambiguous grouping outright.
+ *
  * @example
  * ```ts
  * // Parse USDC amount (6 decimals)

package/dist/units.js

@@ -51,6 +51,15 @@ export function addThousandsSeparator(numberString, delimiter = ',') {
  * @param options - Parsing options with decimals and optional delimiter
  * @returns BigInt representation of the amount
  *
+ * @remarks
+ * The delimiter is removed, not interpreted, so every comma is assumed to be a
+ * thousands separator. Do NOT use this for a value a maker may have typed with
+ * a comma as the *decimal* separator: `parseUnits('1,5', { decimals: 6 })` is
+ * 15, not 1.5, and it fails silently rather than throwing the way viem's own
+ * `parseUnits` would. Conversion rates go through
+ * {@link rateInput.parseRateInput} instead, which treats a lone comma as a
+ * decimal separator and rejects ambiguous grouping outright.
+ *
  * @example
  * ```ts
  * // Parse USDC amount (6 decimals)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@provex/utils",
-  "version": "1.9.2",
+  "version": "1.10.0-rc.20260912192040.fdbb8fc",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -33,6 +33,10 @@
       "import": "./dist/units.js",
       "types": "./dist/units.d.ts"
     },
+    "./rateInput": {
+      "import": "./dist/rateInput.js",
+      "types": "./dist/rateInput.d.ts"
+    },
     "./payment": {
       "import": "./dist/payment.js",
       "types": "./dist/payment.d.ts"