@provex/utils 1.11.0 → 2.0.0

package/dist/payment.providerLists.test.js

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Tests for the deployment switches that hide or force-show a
+ * payment rail.
+ *
+ * `DISABLED_PROVIDERS` and `ENABLED_PROVIDERS` are read once, on the first call,
+ * and cached in module state. Each test file runs in its own process, so this
+ * file sets both variables before any call and observes one fixed deployment:
+ *
+ * - disabled: `PayPal` and `zelle` (mixed case and padded, as a human writes it)
+ * - enabled: `venmo` and `paypal`
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { pulsechain } from 'viem/chains';
+import { findLegacySubProviderAttachments, isProviderDisabled, providerKeyToContractId, subProviders, } from './payment.js';
+process.env.DISABLED_PROVIDERS = 'PayPal, zelle';
+process.env.ENABLED_PROVIDERS = 'venmo,paypal';
+describe('isProviderDisabled', () => {
+    it('hides a rail named in the disabled list, whatever the registry says', () => {
+        assert.equal(isProviderDisabled('zelle', false), true);
+        assert.equal(isProviderDisabled('ZELLE'), true);
+    });
+    it('lets the disabled list win when a rail is in both lists', () => {
+        assert.equal(isProviderDisabled('paypal'), true);
+    });
+    it('shows a rail named in the enabled list even when the registry disables it', () => {
+        assert.equal(isProviderDisabled('venmo', true), false);
+    });
+    it('follows the registry field for a rail in neither list', () => {
+        assert.equal(isProviderDisabled('wise'), false);
+        assert.equal(isProviderDisabled('wise', true), true);
+    });
+});
+describe('findLegacySubProviderAttachments with a disabled rail', () => {
+    it('does not warn about a rail the deployment has switched off', () => {
+        // A maker cannot act on a warning about a rail they cannot attach here.
+        const bankIds = new Set(Object.values(subProviders).map((key) => providerKeyToContractId(key).toLowerCase()));
+        assert.deepEqual(findLegacySubProviderAttachments({ chainId: pulsechain.id, attachedPaymentMethodIds: bankIds }), []);
+    });
+});

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

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Tests for where each payment rail sends the buyer.
+ *
+ * A send link is the buyer's only route from "I must pay" to the rail's own
+ * payment screen. A wrong host sends money intent to the wrong place, so each
+ * rail is pinned to its exact destination, in both the app-link (QR) and the
+ * web form.
+ */
+export {};

package/dist/payment.sendLinks.test.js

@@ -0,0 +1,91 @@
+/**
+ * @fileoverview Tests for where each payment rail sends the buyer.
+ *
+ * A send link is the buyer's only route from "I must pay" to the rail's own
+ * payment screen. A wrong host sends money intent to the wrong place, so each
+ * rail is pinned to its exact destination, in both the app-link (QR) and the
+ * web form.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { pulsechain } from 'viem/chains';
+import { computePayeeDetailsHash, dataEncoding, defaultZelleSendLink, providerConfigs, providers, subProviderConfigs, subProviders, } from './payment.js';
+import { keccak256, stringToHex } from 'viem';
+const webOptions = { username: 'alice', amount: '12.50' };
+const qrOptions = { ...webOptions, qrCode: true };
+const sendLinkOf = (key) => providerConfigs(pulsechain.id)[key].sendLink;
+describe('computePayeeDetailsHash', () => {
+    it('is the keccak256 of the identifier text, so maker and taker derive the same hash', () => {
+        assert.equal(computePayeeDetailsHash('@myvenmo'), keccak256(stringToHex('@myvenmo')));
+    });
+});
+describe('Zelle send links', () => {
+    it('encodes the username into the enroll URL as a base64 payment payload', () => {
+        const decoded = JSON.parse(atob(dataEncoding('alice@example.com')));
+        assert.deepEqual(decoded, { name: '', action: 'payment', token: 'alice@example.com' });
+    });
+    it('returns no default link without a username, because there is no one to pay', () => {
+        assert.equal(defaultZelleSendLink({ username: '', amount: '1.00' }), null);
+    });
+    it('returns the enroll link for a username', () => {
+        assert.equal(defaultZelleSendLink(webOptions), `https://enroll.zellepay.com/qr-codes?data=${dataEncoding('alice')}`);
+    });
+    it('falls back to the generic enroll link when no bank is chosen', () => {
+        assert.equal(sendLinkOf(providers.ZELLE)(webOptions), defaultZelleSendLink(webOptions));
+    });
+    it('delegates to the chosen bank when a sub-provider is named', () => {
+        const link = sendLinkOf(providers.ZELLE)({ ...webOptions, subProvider: subProviders.CITI });
+        assert.equal(link, 'https://online.citi.com/US/nga/zelle/transfer');
+    });
+    const bankCases = [
+        [subProviders.CHASE, defaultZelleSendLink(qrOptions), 'https://secure.chase.com/web/auth/dashboard#/dashboard/singleDoor/singleDoorController/index'],
+        [subProviders.BANK_OF_AMERICA, 'https://www.bankofamerica.com/movemoney', 'https://www.bankofamerica.com/'],
+        [subProviders.CITI, defaultZelleSendLink(qrOptions), 'https://online.citi.com/US/nga/zelle/transfer'],
+    ];
+    for (const [bank, qrLink, webLink] of bankCases) {
+        it(`${bank}: sends a QR scan to the bank's QR-capable link and a web buyer to its site`, () => {
+            const sendLink = subProviderConfigs.zelle[bank].sendLink;
+            assert.equal(sendLink(qrOptions), qrLink);
+            assert.equal(sendLink(webOptions), webLink);
+        });
+    }
+});
+describe('rail send links', () => {
+    const cases = [
+        [
+            providers.VENMO,
+            'venmo://paycharge?txn=pay&recipients=alice&note=cash&amount=12.50',
+            'https://account.venmo.com/pay?recipients=alice&note=cash&amount=12.50',
+        ],
+        [providers.REVOLUT, 'https://revolut.me/alice', 'https://revolut.me/alice'],
+        [providers.WISE, 'https://wise.com/pay/me/alice', 'https://wise.com/pay/me/alice'],
+        [
+            providers.MERCADOPAGO,
+            'https://www.mercadopago.com.ar/money-out/transfer/',
+            'https://www.mercadopago.com.ar/money-out/transfer/',
+        ],
+        [providers.PAYPAL, 'paypal://', 'https://www.paypal.com/myaccount/transfer/homepage'],
+        [providers.MONZO, 'https://monzo.me/alice', 'https://monzo.me/alice'],
+        [providers.N26, 'number26://', 'https://app.n26.com/'],
+        [providers.ALIPAY, 'alipays://', 'https://www.alipay.com/'],
+        [providers.CHIME, 'https://app.chime.com/link/qr?u=alice', 'https://app.chime.com/login'],
+        [
+            providers.ROYALBANKCANADA,
+            'https://www.rbcroyalbank.com/ways-to-bank/interac-e-transfer.html',
+            'https://www.rbcroyalbank.com/ways-to-bank/interac-e-transfer.html',
+        ],
+        [providers.IDFC, 'https://www.idfcfirstbank.com/', 'https://www.idfcfirstbank.com/'],
+    ];
+    for (const [key, qrLink, webLink] of cases) {
+        it(`${key}: pins the QR and web destinations`, () => {
+            const sendLink = sendLinkOf(key);
+            assert.equal(sendLink(qrOptions), qrLink);
+            assert.equal(sendLink(webOptions), webLink);
+        });
+    }
+    it('Cash App prefixes a bare username with $, and leaves a cashtag alone', () => {
+        const sendLink = sendLinkOf(providers.CASHAPP);
+        assert.equal(sendLink({ username: 'alice', amount: '1.00' }), 'https://cash.app/$alice');
+        assert.equal(sendLink({ username: '$alice', amount: '1.00' }), 'https://cash.app/$alice');
+    });
+});

package/dist/peer-types.d.ts

@@ -2,22 +2,19 @@
  * @fileoverview Peer protocol types for attestation and proof verification.
  *
  * This module defines the type system for the V3 attestation flow, including:
- * - Notarized proofs from the PeerAuth browser extension
- * - Attestation requests/responses from the peer attestation service
+ * - Attestation responses from the peer attestation service
  * - EIP-712 typed data structures for on-chain verification
  * - Payment proof encoding for the UnifiedPaymentVerifier contract
  *
  * @remarks
  * **V3 Attestation Flow:**
- * 1. Buyer generates zkTLS proof via PeerAuth extension (NotarizedProofData)
- * 2. Proof + intent data sent to attestation service (V3AttestationRequest)
- * 3. Service validates and returns EIP-712 signed attestation (V3AttestationResponse)
- * 4. Attestation encoded as paymentProof bytes (encodeV3PaymentProof)
- * 5. Buyer calls fulfillIntent() with encoded proof
+ * 1. Buyer captures the payment through the PeerAuth extension (buyer trusted-execution capture)
+ * 2. Service validates and returns EIP-712 signed attestation (V3AttestationResponse)
+ * 3. Attestation encoded as paymentProof bytes (encodeV3PaymentProof)
+ * 4. Buyer calls fulfillIntent() with encoded proof
  *
  * **Type Aliases:**
  * For cleaner imports, V3-prefixed types have unprefixed aliases:
- * - AttestationOptions = V3AttestationOptions
  * - AttestationResponse = V3AttestationResponse
  * - IntentData = V3IntentData
  *
@@ -110,27 +107,6 @@ export type IntentValidation = {
     };
     depositData: ValidationDepositData;
 };
-/**
- * Notarized proof from PeerAuth extension.
- * This is the zkTLS proof that proves a payment transaction occurred.
- * Mirrors the NotarizedProof type from @provex/extension-react.
- */
-export type NotarizedProofData = {
-    claim: {
-        context: string;
-        epoch: number;
-        identifier: Hex;
-        owner: Hex;
-        parameters: string;
-        provider: string;
-        timestampS: number;
-    };
-    signatures: {
-        attestorAddress: Hex;
-        claimSignature: Record<number, number>;
-        resultSignature: Record<number, number>;
-    };
-};
 /**
  * Intent data required by the peer attestation service.
  * This contains all the on-chain intent parameters needed to verify
@@ -154,43 +130,6 @@ export type V3IntentData = {
     /** Optional timestamp buffer in milliseconds (default: 3000) */
     timestampBufferMs?: string;
 };
-/**
- * V3 attestation request sent to the peer attestation service.
- * The service validates Reclaim proofs and returns an EIP-712 signed attestation.
- *
- * Endpoint: POST /verify/{platform}/{action_type}
- * Example: POST /verify/chase/transfer_zelle
- */
-export type V3AttestationRequest = {
-    /** Type of proof being submitted */
-    proofType: 'reclaim';
-    /** JSON stringified array of Reclaim proofs */
-    proof: string;
-    /** Chain ID (e.g., 8453 for Base) */
-    chainId: number;
-    /** UnifiedPaymentVerifier contract address */
-    verifyingContract: Hex;
-    /** Intent data from on-chain signalIntent */
-    intent: V3IntentData;
-};
-/**
- * Options passed to the v3 getAttestation API.
- * These are transformed into V3AttestationRequest format.
- */
-export type V3AttestationOptions = {
-    /** Platform for the attestation service path (e.g., 'chase') */
-    platform: string;
-    /** Action type for the attestation service path (e.g., 'transfer_zelle') */
-    actionType: string;
-    /** Chain ID */
-    chainId: number;
-    /** UnifiedPaymentVerifier contract address */
-    verifyingContract: Hex;
-    /** Array of Reclaim proofs from PeerAuth */
-    proofs: NotarizedProofData[];
-    /** Intent data from on-chain intent */
-    intent: V3IntentData;
-};
 /**
  * EIP-712 typed data specification from attestation service.
  */
@@ -303,14 +242,6 @@ export type SignedAttestation = {
  * @returns ABI-encoded bytes to pass as paymentProof in fulfillIntent
  */
 export declare function encodeV3PaymentProof(attestation: V3AttestationResponseObject): Hex;
-/**
- * Extracts the Reclaim attestor address from the attestation proofInput.
- * This is needed for the verificationData field in fulfillIntent.
- *
- * @param attestation - The V3AttestationResponseObject from the attestation service
- * @returns The Reclaim attestor address as Hex, or null if not found
- */
-export declare function extractReclaimAttestorAddress(attestation: V3AttestationResponseObject): Hex | null;
 /**
  * Extracts the nullifier from a V3 attestation response.
  *
@@ -326,10 +257,6 @@ export declare function extractReclaimAttestorAddress(attestation: V3Attestation
  * @returns The derived nullifier as Hex, or null if extraction fails
  */
 export declare function extractNullifier(attestation: V3AttestationResponseObject): Hex | null;
-/** @alias V3AttestationOptions */
-export type AttestationOptions = V3AttestationOptions;
-/** @alias V3AttestationRequest */
-export type AttestationRequest = V3AttestationRequest;
 /** @alias V3AttestationResponse */
 export type AttestationResponse = V3AttestationResponse;
 /** @alias V3AttestationResponseObject */

package/dist/peer-types.js

@@ -2,22 +2,19 @@
  * @fileoverview Peer protocol types for attestation and proof verification.
  *
  * This module defines the type system for the V3 attestation flow, including:
- * - Notarized proofs from the PeerAuth browser extension
- * - Attestation requests/responses from the peer attestation service
+ * - Attestation responses from the peer attestation service
  * - EIP-712 typed data structures for on-chain verification
  * - Payment proof encoding for the UnifiedPaymentVerifier contract
  *
  * @remarks
  * **V3 Attestation Flow:**
- * 1. Buyer generates zkTLS proof via PeerAuth extension (NotarizedProofData)
- * 2. Proof + intent data sent to attestation service (V3AttestationRequest)
- * 3. Service validates and returns EIP-712 signed attestation (V3AttestationResponse)
- * 4. Attestation encoded as paymentProof bytes (encodeV3PaymentProof)
- * 5. Buyer calls fulfillIntent() with encoded proof
+ * 1. Buyer captures the payment through the PeerAuth extension (buyer trusted-execution capture)
+ * 2. Service validates and returns EIP-712 signed attestation (V3AttestationResponse)
+ * 3. Attestation encoded as paymentProof bytes (encodeV3PaymentProof)
+ * 4. Buyer calls fulfillIntent() with encoded proof
  *
  * **Type Aliases:**
  * For cleaner imports, V3-prefixed types have unprefixed aliases:
- * - AttestationOptions = V3AttestationOptions
  * - AttestationResponse = V3AttestationResponse
  * - IntentData = V3IntentData
  *
@@ -91,29 +88,6 @@ export function encodeV3PaymentProof(attestation) {
         }
     ]);
 }
-/**
- * Extracts the Reclaim attestor address from the attestation proofInput.
- * This is needed for the verificationData field in fulfillIntent.
- *
- * @param attestation - The V3AttestationResponseObject from the attestation service
- * @returns The Reclaim attestor address as Hex, or null if not found
- */
-export function extractReclaimAttestorAddress(attestation) {
-    try {
-        const proofInput = JSON.parse(attestation.proofInput);
-        const proofs = JSON.parse(proofInput.proof);
-        if (Array.isArray(proofs) && proofs.length > 0) {
-            const attestorAddress = proofs[0]?.signatures?.attestorAddress;
-            if (attestorAddress && typeof attestorAddress === 'string') {
-                return attestorAddress;
-            }
-        }
-        return null;
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * Extracts the nullifier from a V3 attestation response.
  *

package/dist/peer-types.test.js

@@ -1,7 +1,7 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import { decodeAbiParameters, encodeAbiParameters, keccak256, parseAbiParameters } from 'viem';
-import { encodeV3PaymentProof, extractNullifier, extractReclaimAttestorAddress, } from './peer-types.js';
+import { encodeV3PaymentProof, extractNullifier, } from './peer-types.js';
 /**
  * Where the expected values come from, so these tests can fail:
  * - REAL_ATTESTATION is a live Chase/Zelle response captured from the zkp2p
@@ -146,33 +146,3 @@ describe('extractNullifier', () => {
         assert.equal(extractNullifier({ ...REAL_ATTESTATION, encodedPaymentDetails: '0x' }), null);
     });
 });
-describe('extractReclaimAttestorAddress', () => {
-    const withProofs = (proofs) => ({
-        ...REAL_ATTESTATION,
-        proofInput: JSON.stringify({ proofType: 'reclaim', proof: JSON.stringify(proofs) }),
-    });
-    it('reads the attestor address of the live proof', () => {
-        assert.equal(extractReclaimAttestorAddress(REAL_ATTESTATION), '0x0636c417755e3ae25c6c166d181c0607f4c572a3');
-    });
-    it('reads the first proof only', () => {
-        const attestation = withProofs([
-            { signatures: { attestorAddress: '0x00000000000000000000000000000000000000f1' } },
-            { signatures: { attestorAddress: '0x00000000000000000000000000000000000000f2' } },
-        ]);
-        assert.equal(extractReclaimAttestorAddress(attestation), '0x00000000000000000000000000000000000000f1');
-    });
-    it('returns null when there are no proofs', () => {
-        assert.equal(extractReclaimAttestorAddress(withProofs([])), null);
-        assert.equal(extractReclaimAttestorAddress(withProofs({ not: 'an array' })), null);
-    });
-    it('returns null when the signatures or the address are missing or not a string', () => {
-        assert.equal(extractReclaimAttestorAddress(withProofs([{}])), null);
-        assert.equal(extractReclaimAttestorAddress(withProofs([{ signatures: {} }])), null);
-        assert.equal(extractReclaimAttestorAddress(withProofs([{ signatures: { attestorAddress: 5 } }])), null);
-        assert.equal(extractReclaimAttestorAddress(withProofs([{ signatures: { attestorAddress: '' } }])), null);
-    });
-    it('returns null for malformed JSON at either level', () => {
-        assert.equal(extractReclaimAttestorAddress({ ...REAL_ATTESTATION, proofInput: 'not json' }), null);
-        assert.equal(extractReclaimAttestorAddress({ ...REAL_ATTESTATION, proofInput: JSON.stringify({ proof: 'not json' }) }), null);
-    });
-});

package/dist/profit.d.ts

@@ -30,6 +30,14 @@ export interface ProfitCalculationInput {
         currency: string;
     };
 }
+/**
+ * Scale a base-unit amount by a difference in decimals.
+ *
+ * @param amount - Amount in base units.
+ * @param decimalDiff - Target decimals minus source decimals.
+ * @returns The amount rescaled to the target decimals.
+ */
+export declare const scaleByDecimalDifference: (amount: bigint, decimalDiff: number) => bigint;
 /**
  * Calculate the profit of an intent fulfilled event
  * @param param0.amount - The fiat amount in currency base units (e.g., cents for USD)

package/dist/profit.js

@@ -11,6 +11,21 @@
  */
 import { getCurrencyByContractId } from "./currencies.js";
 import { getDefaultToken } from "./tokens.js";
+/**
+ * Scale a base-unit amount by a difference in decimals.
+ *
+ * @param amount - Amount in base units.
+ * @param decimalDiff - Target decimals minus source decimals.
+ * @returns The amount rescaled to the target decimals.
+ */
+export const scaleByDecimalDifference = (amount, decimalDiff) => {
+    // A negative difference does not occur today (fiat has at most 2 decimals,
+    // the settlement token 6), but a future low-decimal token must still scale.
+    if (decimalDiff < 0) {
+        return amount / 10n ** BigInt(-decimalDiff);
+    }
+    return amount * 10n ** BigInt(decimalDiff);
+};
 /**
  * Calculate the profit of an intent fulfilled event
  * @param param0.amount - The fiat amount in currency base units (e.g., cents for USD)
@@ -33,9 +48,7 @@ export const calculateProfit = ({ amount: amountInput, conversionRate, chainId,
     // e.g., $100 USD (10000 in 2 decimals) -> 100000000 in 6 decimals for USDC
     // e.g., €100 EUR (10000 in 2 decimals) -> 100000000 in 6 decimals for USDC
     const decimalDiff = inputTokenInfo.decimals - currency.decimals;
-    const amountScaled = decimalDiff >= 0
-        ? amount * 10n ** BigInt(decimalDiff)
-        : amount / 10n ** BigInt(-decimalDiff);
+    const amountScaled = scaleByDecimalDifference(amount, decimalDiff);
     // Profit = what we received - what we expected for 1:1 fiat:token exchange
     // Note: This is most meaningful for USD where $1 ≈ 1 USDC
     // For other currencies, this shows the mathematical difference assuming 1:1

package/dist/profit.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 { calculateProfit, calculateProfits } from './profit.js';
+import { calculateProfit, calculateProfits, scaleByDecimalDifference } from './profit.js';
 import { SUPPORTED_CURRENCIES } from './currencies.js';
 describe('profit', () => {
     // Constants for testing
@@ -312,4 +312,15 @@ describe('profit', () => {
             assert.equal(result.profit, 10000000n);
         });
     });
+    describe('scaleByDecimalDifference', () => {
+        it('multiplies when the target has more decimals, so cents become USDC base units', () => {
+            assert.equal(scaleByDecimalDifference(10000n, 4), 100000000n);
+        });
+        it('divides when the target has fewer decimals, so a low-decimal token is not inflated', () => {
+            assert.equal(scaleByDecimalDifference(100000000n, -4), 10000n);
+        });
+        it('leaves the amount unchanged when decimals match', () => {
+            assert.equal(scaleByDecimalDifference(12345n, 0), 12345n);
+        });
+    });
 });

package/dist/reputation.js

@@ -241,13 +241,11 @@ export function formatCap(cap) {
  * (its threshold is `null`).
  */
 export function getTierFromVolume(volumeBaseUnits) {
-    // Iterate from platinum down (exclude president — manual assignment only)
-    const volumeTiers = TIER_ORDER.filter(t => t !== tiers.PRESIDENT);
-    for (let i = volumeTiers.length - 1; i >= 0; i--) {
-        const tier = volumeTiers[i];
+    // Iterate from the top tier down. `null` is the manual-assignment marker
+    // (PRESIDENT) — skipped, since volume alone can never reach it.
+    for (let i = TIER_ORDER.length - 1; i >= 0; i--) {
+        const tier = TIER_ORDER[i];
         const threshold = TAKER_TIERS[tier].volumeThreshold;
-        // `null` is the manual-assignment marker (PRESIDENT) — already
-        // filtered out above, defensive check kept for type narrowing.
         if (threshold === null)
             continue;
         if (volumeBaseUnits >= threshold) {

package/dist/reputation.test.js

@@ -289,3 +289,11 @@ describe('isOverOrderCap: base unit boundaries', () => {
         assert.equal(isOverOrderCap({ orderTokenAmount: UNLIMITED_CAP_BASE_UNITS + 1n, cap: UNLIMITED_CAP_BASE_UNITS }), true);
     });
 });
+describe('getTierFromVolume: volume below every threshold', () => {
+    it('falls back to peasant for a negative volume instead of returning undefined', () => {
+        assert.equal(getTierFromVolume(-1n), 'peasant');
+    });
+    it('never returns president, whose threshold is null (manual assignment only)', () => {
+        assert.notEqual(getTierFromVolume(10n ** 30n), 'president');
+    });
+});

package/dist/time.test.js

@@ -112,11 +112,32 @@ describe('time', () => {
             const result = sleep(1);
             assert.ok(result instanceof Promise);
         });
-        it('should resolve immediately for 0ms', async () => {
-            const start = Date.now();
-            await sleep(0);
-            const elapsed = Date.now() - start;
-            assert.ok(elapsed < 10, `Expected less than 10ms, got ${elapsed}ms`);
+        /**
+         * Lets resolved promises run their callbacks. setImmediate is not mocked,
+         * so this returns even when sleep is wrong, and the assertion then fails
+         * instead of the test hanging.
+         */
+        const flushPendingCallbacks = () => new Promise((resolve) => { setImmediate(resolve); });
+        // Mocked timers, not the wall clock: a loaded machine made the old
+        // "under 10ms" check fail even though sleep itself was correct.
+        it('resolves on the zero-delay tick for 0ms', async (context) => {
+            context.mock.timers.enable({ apis: ['setTimeout'] });
+            let resolved = false;
+            void sleep(0).then(() => { resolved = true; });
+            context.mock.timers.tick(0);
+            await flushPendingCallbacks();
+            assert.equal(resolved, true);
+        });
+        it('does not resolve before its delay has passed', async (context) => {
+            context.mock.timers.enable({ apis: ['setTimeout'] });
+            let resolved = false;
+            void sleep(50).then(() => { resolved = true; });
+            context.mock.timers.tick(49);
+            await flushPendingCallbacks();
+            assert.equal(resolved, false);
+            context.mock.timers.tick(1);
+            await flushPendingCallbacks();
+            assert.equal(resolved, true);
         });
     });
     describe('formatAbsoluteTimestamp', () => {

package/dist/tokens.d.ts

@@ -8370,9 +8370,9 @@ declare const createClient: {
             blockTag?: import("viem").BlockTag | undefined;
             nonce?: string | undefined | undefined;
             address?: `0x${string}` | undefined;
+            time?: Date | undefined;
             domain?: string | undefined | undefined;
             scheme?: string | undefined | undefined;
-            time?: Date | undefined;
             message: string;
             signature: import("viem").Hex;
         }) => Promise<boolean>;
@@ -15069,9 +15069,9 @@ declare const createClient: {
             blockTag?: import("viem").BlockTag | undefined;
             nonce?: string | undefined | undefined;
             address?: `0x${string}` | undefined;
+            time?: Date | undefined;
             domain?: string | undefined | undefined;
             scheme?: string | undefined | undefined;
-            time?: Date | undefined;
             message: string;
             signature: import("viem").Hex;
         }) => Promise<boolean>;

package/dist/transports.d.ts

@@ -31,6 +31,32 @@ import { type ChainId } from './chain.js';
  * `eth_*` methods.
  */
 export declare const VALVE_CITY_PULSECHAIN_RPC = "https://one.valve.city/rpc/vk_demo/evm/369";
+/**
+ * Count one outgoing JSON-RPC request for the debug log.
+ *
+ * Reads the method from a clone, so the real request body stays unread. A body
+ * that is not JSON is ignored: a debug counter must never fail a request.
+ *
+ * @param req - The request viem is about to send.
+ */
+export declare const logRpcRequest: (req: Request) => void;
+/**
+ * Latency probe for ranked transports: one `eth_blockNumber` call.
+ *
+ * It measures real query latency, not just the TCP round trip, and avoids the
+ * noisy `net_listening` entries viem's default probe leaves in server logs.
+ *
+ * @param transport - The transport instance viem is ranking.
+ * @returns The block number response, which viem times and discards.
+ */
+export declare const pingBlockNumber: (transport: {
+    transport: {
+        request: (args: {
+            method: string;
+            params: unknown[];
+        }) => Promise<unknown>;
+    };
+}) => Promise<unknown>;
 /**
  * Provex-curated fallback RPC URLs per chain, applied after caller overrides
  * but before the viem chain default.
@@ -47,7 +73,7 @@ export declare const VALVE_CITY_PULSECHAIN_RPC = "https://one.valve.city/rpc/vk_
  * - Base (8453): no built-in fallback — Base's default endpoint is reliable
  *   and neither operator runs a Base RPC.
  */
-export declare const FALLBACK_RPC_URLS: Partial<Record<ChainId, readonly string[]>>;
+export declare const FALLBACK_RPC_URLS: Record<ChainId, readonly string[]>;
 /**
  * Parse a comma-separated RPC URL list into an ordered array of valid URLs.
  *
@@ -82,6 +108,31 @@ export declare const parseRpcUrlList: (raw: string | undefined | null) => string
  *   defeat the reason it was placed second.
  */
 export type ChainTransportStrategy = 'ranked' | 'ordered';
+/**
+ * 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.
+ */
+export declare const defaultChainTransportStrategy: () => ChainTransportStrategy;
 /**
  * Options accepted by {@link createChainTransport}.
  */
@@ -93,7 +144,7 @@ interface CreateChainTransportOptions {
     userUrls?: readonly string[];
     /**
      * Traffic-distribution strategy. Defaults per environment — see
-     * {@link defaultStrategy}: `ranked` in a browser, preserving the
+     * {@link defaultChainTransportStrategy}: `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.

package/dist/transports.debug.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Tests for the RPC call counter, the ranking probe and the
+ * environment-dependent default strategy.
+ *
+ * The counter exists so a developer can open a browser console, set
+ * `window.__RPC_DEBUG = true`, and see which JSON-RPC methods a page is
+ * hammering. It must stay silent otherwise and must never fail a request.
+ */
+export {};