@provex/utils 1.0.16 → 1.2.3

package/dist/src/contracts.test.js

@@ -0,0 +1,243 @@
+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';
+describe('contracts', () => {
+    describe('getDefaultVersion', () => {
+        it('returns v3 for Base', async () => {
+            // getDefaultVersion is not exported, but we can test via getContracts behavior
+            // When no version is specified to getLatestContract, it uses the default version
+            const escrow = getLatestContract(base.id, 'escrow');
+            assert.strictEqual(escrow, v3BaseContracts.escrow.at(-1));
+        });
+        it('returns v3 for Pulsechain', async () => {
+            // Pulsechain now uses v3 as default (deployed 2026-01-12)
+            const escrow = getLatestContract(pulsechain.id, 'escrow');
+            assert.strictEqual(escrow, v3PulsechainContracts.escrow.at(-1));
+        });
+    });
+    describe('getContracts', () => {
+        it('returns v2 Base contracts', () => {
+            const result = getContracts('v2', base.id);
+            assert.deepStrictEqual(result, v2BaseContracts);
+        });
+        it('returns v3 Base contracts', () => {
+            const result = getContracts('v3', base.id);
+            assert.deepStrictEqual(result, v3BaseContracts);
+        });
+        it('returns v2 Pulsechain contracts', () => {
+            const result = getContracts('v2', pulsechain.id);
+            assert.deepStrictEqual(result, v2PulsechainContracts);
+        });
+        it('returns v3 Pulsechain contracts', () => {
+            const result = getContracts('v3', pulsechain.id);
+            assert.deepStrictEqual(result, v3PulsechainContracts);
+        });
+    });
+    describe('getLatestContract', () => {
+        it('returns last escrow in v3 Base array', () => {
+            const escrow = getLatestContract(base.id, 'escrow', 'v3');
+            assert.strictEqual(escrow, v3BaseContracts.escrow.at(-1));
+        });
+        it('returns last escrow in v2 Base array', () => {
+            const escrow = getLatestContract(base.id, 'escrow', 'v2');
+            assert.strictEqual(escrow, v2BaseContracts.escrow.at(-1));
+        });
+        it('returns last escrow in v3 Pulsechain array', () => {
+            const escrow = getLatestContract(pulsechain.id, 'escrow', 'v3');
+            assert.strictEqual(escrow, v3PulsechainContracts.escrow.at(-1));
+        });
+        it('returns last escrow in v2 Pulsechain array', () => {
+            const escrow = getLatestContract(pulsechain.id, 'escrow', 'v2');
+            assert.strictEqual(escrow, v2PulsechainContracts.escrow.at(-1));
+        });
+        it('returns usdc address (non-array)', () => {
+            const usdc = getLatestContract(base.id, 'usdc', 'v3');
+            assert.strictEqual(usdc, v3BaseContracts.usdc);
+        });
+        it('returns gatingService address (non-array)', () => {
+            const gating = getLatestContract(base.id, 'gatingService', 'v3');
+            assert.strictEqual(gating, v3BaseContracts.gatingService);
+        });
+        it('returns unifiedPaymentVerifier for v3', () => {
+            const verifier = getLatestContract(base.id, 'unifiedPaymentVerifier', 'v3');
+            assert.strictEqual(verifier, v3BaseContracts.unifiedPaymentVerifier.at(-1));
+        });
+        it('uses default version when not specified', () => {
+            // Both Base and Pulsechain default to v3
+            const baseEscrow = getLatestContract(base.id, 'escrow');
+            assert.strictEqual(baseEscrow, v3BaseContracts.escrow.at(-1));
+            const pulseEscrow = getLatestContract(pulsechain.id, 'escrow');
+            assert.strictEqual(pulseEscrow, v3PulsechainContracts.escrow.at(-1));
+        });
+        it('returns v2 verifiers when explicitly requesting v2', () => {
+            const venmoVerifier = getLatestContract(base.id, 'venmoReclaimVerifier', 'v2');
+            assert.strictEqual(venmoVerifier, v2BaseContracts.venmoReclaimVerifier.at(-1));
+        });
+        it('returns null for v2-only key when requesting v3', () => {
+            // venmoReclaimVerifier exists in v2 but not v3
+            const verifier = getLatestContract(base.id, 'venmoReclaimVerifier', 'v3');
+            assert.strictEqual(verifier, null);
+        });
+        it('returns null for v3-only key when requesting v2', () => {
+            // unifiedPaymentVerifier exists in v3 but not v2
+            const verifier = getLatestContract(base.id, 'unifiedPaymentVerifier', 'v2');
+            assert.strictEqual(verifier, null);
+        });
+    });
+    describe('getAllEscrowContracts', () => {
+        it('returns array of escrow locations', () => {
+            const escrows = getAllEscrowContracts();
+            assert.ok(Array.isArray(escrows));
+            assert.ok(escrows.length >= 4); // v2 Base, v2 Pulse, v3 Base, v3 Pulse
+        });
+        it('each escrow has required fields', () => {
+            const escrows = getAllEscrowContracts();
+            for (const escrow of escrows) {
+                assert.ok(escrow.version, 'escrow should have version');
+                assert.ok(escrow.chainId, 'escrow should have chainId');
+                assert.ok(escrow.escrow, 'escrow should have escrow address');
+                assert.ok(['v2', 'v3'].includes(escrow.version), 'version should be v2 or v3');
+            }
+        });
+        it('includes v2 Base escrow', () => {
+            const escrows = getAllEscrowContracts();
+            const v2BaseEscrow = escrows.find((e) => e.version === 'v2' && e.chainId === base.id);
+            assert.ok(v2BaseEscrow);
+            assert.strictEqual(v2BaseEscrow.escrow, v2BaseContracts.escrow[0]);
+        });
+        it('includes v2 Pulsechain escrow', () => {
+            const escrows = getAllEscrowContracts();
+            const v2PulseEscrow = escrows.find((e) => e.version === 'v2' && e.chainId === pulsechain.id);
+            assert.ok(v2PulseEscrow);
+            assert.strictEqual(v2PulseEscrow.escrow, v2PulsechainContracts.escrow[0]);
+        });
+        it('includes v3 Base escrow', () => {
+            const escrows = getAllEscrowContracts();
+            const v3BaseEscrow = escrows.find((e) => e.version === 'v3' && e.chainId === base.id);
+            assert.ok(v3BaseEscrow);
+            assert.strictEqual(v3BaseEscrow.escrow, v3BaseContracts.escrow[0]);
+        });
+        it('includes v3 Pulsechain escrow', () => {
+            const escrows = getAllEscrowContracts();
+            const v3PulseEscrow = escrows.find((e) => e.version === 'v3' && e.chainId === pulsechain.id);
+            assert.ok(v3PulseEscrow);
+            assert.strictEqual(v3PulseEscrow.escrow, v3PulsechainContracts.escrow[0]);
+        });
+        it('escrow addresses are valid hex', () => {
+            const escrows = getAllEscrowContracts();
+            for (const escrow of escrows) {
+                assert.ok(escrow.escrow.startsWith('0x'), 'escrow should start with 0x');
+                assert.strictEqual(escrow.escrow.length, 42, 'escrow should be 42 chars');
+            }
+        });
+    });
+    describe('contract structure', () => {
+        it('v2 contracts have required verifiers', () => {
+            assert.ok(v2BaseContracts.venmoReclaimVerifier);
+            assert.ok(v2BaseContracts.revolutReclaimVerifier);
+            assert.ok(v2BaseContracts.cashappReclaimVerifier);
+            assert.ok(v2BaseContracts.zelleBaseVerifier);
+        });
+        it('v3 contracts have unifiedPaymentVerifier', () => {
+            assert.ok(v3BaseContracts.unifiedPaymentVerifier);
+            assert.ok(v3PulsechainContracts.unifiedPaymentVerifier);
+        });
+        it('contracts registry has both versions', () => {
+            assert.ok(contracts.v2);
+            assert.ok(contracts.v3);
+        });
+        it('contracts registry has both chains for v2', () => {
+            assert.ok(contracts.v2[base.id]);
+            assert.ok(contracts.v2[pulsechain.id]);
+        });
+        it('contracts registry has both chains for v3', () => {
+            assert.ok(contracts.v3[base.id]);
+            assert.ok(contracts.v3[pulsechain.id]);
+        });
+    });
+    describe('V3_PULSECHAIN_DEPLOYMENT_REFERENCE', () => {
+        it('should have all reference addresses', () => {
+            assert.ok(V3_PULSECHAIN_DEPLOYMENT_REFERENCE.orchestrator);
+            assert.ok(V3_PULSECHAIN_DEPLOYMENT_REFERENCE.paymentVerifierRegistry);
+            assert.ok(V3_PULSECHAIN_DEPLOYMENT_REFERENCE.protocolViewer);
+            assert.ok(V3_PULSECHAIN_DEPLOYMENT_REFERENCE.escrowRegistry);
+        });
+        it('should have valid address formats', () => {
+            assert.ok(V3_PULSECHAIN_DEPLOYMENT_REFERENCE.orchestrator.startsWith('0x'));
+            assert.strictEqual(V3_PULSECHAIN_DEPLOYMENT_REFERENCE.orchestrator.length, 42);
+        });
+    });
+    describe('shortenEscrowAddress', () => {
+        it('should shorten address to first 6 + last 4 chars', () => {
+            const address = '0x1234567890abcdef1234567890abcdef12345678';
+            const shortened = shortenEscrowAddress(address);
+            assert.equal(shortened, '0x1234...5678');
+        });
+        it('should handle real escrow addresses', () => {
+            const escrow = v3BaseContracts.escrow[0];
+            const shortened = shortenEscrowAddress(escrow);
+            assert.ok(shortened.startsWith('0x'));
+            assert.ok(shortened.includes('...'));
+            assert.equal(shortened.length, 13); // 0x + 4 chars + ... + 4 chars
+        });
+    });
+    describe('getEscrowVersion', () => {
+        it('returns v2 for v2 Base escrow', () => {
+            const version = getEscrowVersion(v2BaseContracts.escrow[0], base.id);
+            assert.strictEqual(version, 'v2');
+        });
+        it('returns v3 for v3 Base escrow', () => {
+            const version = getEscrowVersion(v3BaseContracts.escrow[0], base.id);
+            assert.strictEqual(version, 'v3');
+        });
+        it('returns v2 for v2 Pulsechain escrow', () => {
+            const version = getEscrowVersion(v2PulsechainContracts.escrow[0], pulsechain.id);
+            assert.strictEqual(version, 'v2');
+        });
+        it('returns v3 for v3 Pulsechain escrow', () => {
+            const version = getEscrowVersion(v3PulsechainContracts.escrow[0], pulsechain.id);
+            assert.strictEqual(version, 'v3');
+        });
+        it('returns null for unknown escrow address', () => {
+            const version = getEscrowVersion('0x0000000000000000000000000000000000000000', base.id);
+            assert.strictEqual(version, null);
+        });
+        it('handles case-insensitive address matching', () => {
+            const lowerCase = v3BaseContracts.escrow[0].toLowerCase();
+            const version = getEscrowVersion(lowerCase, base.id);
+            assert.strictEqual(version, 'v3');
+        });
+        it('finds escrow without chainId by searching all chains', () => {
+            const version = getEscrowVersion(v3BaseContracts.escrow[0]);
+            assert.strictEqual(version, 'v3');
+        });
+        it('returns null when chainId doesnt match', () => {
+            // v3 Base escrow should not be found if we specify Pulsechain chainId
+            const version = getEscrowVersion(v3BaseContracts.escrow[0], pulsechain.id);
+            assert.strictEqual(version, null);
+        });
+    });
+    describe('isV3Escrow', () => {
+        it('returns true for v3 Base escrow', () => {
+            const result = isV3Escrow(v3BaseContracts.escrow[0], base.id);
+            assert.strictEqual(result, true);
+        });
+        it('returns false for v2 Base escrow', () => {
+            const result = isV3Escrow(v2BaseContracts.escrow[0], base.id);
+            assert.strictEqual(result, false);
+        });
+        it('returns true for v3 Pulsechain escrow', () => {
+            const result = isV3Escrow(v3PulsechainContracts.escrow[0], pulsechain.id);
+            assert.strictEqual(result, true);
+        });
+        it('returns false for v2 Pulsechain escrow', () => {
+            const result = isV3Escrow(v2PulsechainContracts.escrow[0], pulsechain.id);
+            assert.strictEqual(result, false);
+        });
+        it('returns false for unknown escrow', () => {
+            const result = isV3Escrow('0x0000000000000000000000000000000000000000', base.id);
+            assert.strictEqual(result, false);
+        });
+    });
+});

package/dist/src/conversionRates.d.ts

@@ -1,3 +1,20 @@
+/**
+ * @fileoverview Conversion rate utilities for fiat-to-crypto exchange calculations.
+ *
+ * This module processes conversion rate events from deposits and provides utilities
+ * for calculating token amounts from fiat amounts and vice versa.
+ *
+ * @remarks
+ * Conversion rates are stored with 18 decimal precision (like ETH).
+ * A rate of 1.0 (1:1 exchange) = 1e18 in the contract.
+ *
+ * Rates are organized by:
+ * - Payment provider (Venmo, Zelle, etc.)
+ * - Fiat currency (USD, EUR, etc.)
+ *
+ * @see {@link currencies} for currency definitions
+ * @see {@link payment} for provider definitions
+ */
 import type { Hex } from 'viem';
 import { Currency } from './currencies.js';
 import { type ProviderKey } from './payment.js';
@@ -5,15 +22,23 @@ import type { SortDirection } from './sort.js';
 import type { TokenInfo } from './tokens.js';
 import type { ChainId } from './chain.js';
 /**
- * Conversion rate info
+ * Information about a single conversion rate configuration.
+ * Represents a rate set by a depositor for a specific payment method and currency.
  */
 export interface ConversionRateInfo {
+    /** Unique ID of the rate update event */
     depositConversionRateUpdatedId: string;
+    /** Currency contract ID (keccak256 hash) */
     currency: string;
+    /** Payment verifier address or method ID */
     verifier: string;
+    /** Conversion rate as string (18 decimals, e.g., "1000000000000000000" = 1.0) */
     value: string;
+    /** Event order ID for chronological sorting */
     orderId: string;
+    /** Associated deposit ID */
     depositId: string;
+    /** Transaction metadata */
     transaction: {
         hash: string;
         block: {
@@ -22,7 +47,8 @@ export interface ConversionRateInfo {
     };
 }
 /**
- * Conversion rate info with current deposit conversion rate updated
+ * Extended conversion rate info including the current (latest) rate.
+ * Used when processing historical rate changes to track the active rate.
  */
 export interface ConversionRateInfoWithCurrent extends ConversionRateInfo {
     currentDepositConversionRateUpdatedId: string;
@@ -31,13 +57,25 @@ export interface ConversionRateInfoWithCurrent extends ConversionRateInfo {
     };
 }
 /**
- * Provider rates
+ * Nested map structure for organizing rates by provider and currency.
+ * Outer map: provider key -> currency map
+ * Inner map: currency contract ID -> rate info
+ *
+ * @example
+ * ```ts
+ * const rates: ProviderRates<ConversionRateInfo> = new Map([
+ *   ['venmo', new Map([
+ *     ['0x...usd', { value: '1000000000000000000', ... }]
+ *   ])]
+ * ])
+ * ```
  */
 export type ProviderRates<RateInfo> = Map<ProviderKey, Map<Hex, RateInfo>>;
 /**
- * Process conversion rates options
+ * Options for processing conversion rate events into organized maps.
  */
 interface ProcessConversionRatesOptions {
+    /** Chain ID for verifier lookup */
     chainId: ChainId;
     events: ConversionRateInfoWithCurrent[];
     sortOrder?: SortDirection;
@@ -67,7 +105,23 @@ interface ExtractCurrenciesOptions {
     currenciesOnly?: string[];
 }
 /**
- * Process deposit currency added events into organized conversion rates
+ * Process conversion rate events into an organized map by provider and currency.
+ *
+ * @param options - Processing options including events and sorting preferences
+ * @returns Nested map of provider -> currency -> rate info array
+ *
+ * @example
+ * ```ts
+ * const rates = processConversionRates({
+ *   chainId: 8453,
+ *   events: depositCurrencyEvents,
+ *   sortOrder: 'desc',
+ *   includeHistorical: false
+ * })
+ *
+ * // Get Venmo USD rate
+ * const venmoUsd = rates.get('venmo')?.get(USD_CONTRACT_ID)?.[0]
+ * ```
  */
 export declare function processConversionRates(options: ProcessConversionRatesOptions): ProviderRates<ConversionRateInfo[]>;
 /**
@@ -104,7 +158,25 @@ export declare function getPrimaryVerifier(providerRates: ProviderRates<Conversi
  */
 export declare function getPrimaryCurrency(providerRates: ProviderRates<ConversionRateInfo>): string | null;
 /**
- * Convert token input to currency
+ * Convert a token amount to a fiat currency amount using the conversion rate.
+ * Rounds up to the nearest cent (token decimals - 2) for user-friendly display.
+ *
+ * @param params - Conversion parameters
+ * @param params.token - Token info with decimals
+ * @param params.amountOutInt - Token amount as bigint (e.g., 100_000000n for 100 USDC)
+ * @param params.rate - Conversion rate with 18 decimals (1e18 = 1:1)
+ * @returns Fiat amount as bigint with cent-rounding applied
+ *
+ * @example
+ * ```ts
+ * // Convert 100 USDC at 1.05 rate to fiat
+ * const fiat = convertTokenInputToCurrency({
+ *   token: { decimals: 6, ... },
+ *   amountOutInt: 100_000000n,
+ *   rate: 1_050000000000000000n // 1.05
+ * })
+ * // Returns: 105_000000n (rounded to nearest cent)
+ * ```
  */
 export declare const convertTokenInputToCurrency: ({ token, amountOutInt, rate }: {
     token: TokenInfo;
@@ -112,8 +184,27 @@ export declare const convertTokenInputToCurrency: ({ token, amountOutInt, rate }
     rate: bigint;
 }) => bigint;
 /**
- * Convert currency amount to token amount out (inverse of convertTokenInputToCurrency)
- * This accounts for the cent-rounding applied in the original function
+ * Convert a fiat currency amount back to token amount (inverse of convertTokenInputToCurrency).
+ * Accounts for the cent-rounding that was applied during the forward conversion.
+ *
+ * @param params - Conversion parameters
+ * @param params.token - Token info with decimals
+ * @param params.currency - Currency info with decimals
+ * @param params.currencyAmountInt - Fiat amount as bigint
+ * @param params.rate - Conversion rate with 18 decimals (1e18 = 1:1)
+ * @returns Token amount as bigint, floored to smallest token unit
+ *
+ * @example
+ * ```ts
+ * // Convert $105 fiat back to USDC at 1.05 rate
+ * const tokens = convertCurrencyToTokenOutput({
+ *   token: { decimals: 6, ... },
+ *   currency: SUPPORTED_CURRENCIES.USD,
+ *   currencyAmountInt: 105_00n, // $105.00
+ *   rate: 1_050000000000000000n // 1.05
+ * })
+ * // Returns: 100_000000n (100 USDC)
+ * ```
  */
 export declare const convertCurrencyToTokenOutput: ({ token, currency, currencyAmountInt, rate, }: {
     token: TokenInfo;

package/dist/src/conversionRates.js

@@ -1,7 +1,40 @@
+/**
+ * @fileoverview Conversion rate utilities for fiat-to-crypto exchange calculations.
+ *
+ * This module processes conversion rate events from deposits and provides utilities
+ * for calculating token amounts from fiat amounts and vice versa.
+ *
+ * @remarks
+ * Conversion rates are stored with 18 decimal precision (like ETH).
+ * A rate of 1.0 (1:1 exchange) = 1e18 in the contract.
+ *
+ * Rates are organized by:
+ * - Payment provider (Venmo, Zelle, etc.)
+ * - Fiat currency (USD, EUR, etc.)
+ *
+ * @see {@link currencies} for currency definitions
+ * @see {@link payment} for provider definitions
+ */
 import { SUPPORTED_CURRENCIES } from './currencies.js';
 import { verifierGetsKey } from './payment.js';
 /**
- * Process deposit currency added events into organized conversion rates
+ * Process conversion rate events into an organized map by provider and currency.
+ *
+ * @param options - Processing options including events and sorting preferences
+ * @returns Nested map of provider -> currency -> rate info array
+ *
+ * @example
+ * ```ts
+ * const rates = processConversionRates({
+ *   chainId: 8453,
+ *   events: depositCurrencyEvents,
+ *   sortOrder: 'desc',
+ *   includeHistorical: false
+ * })
+ *
+ * // Get Venmo USD rate
+ * const venmoUsd = rates.get('venmo')?.get(USD_CONTRACT_ID)?.[0]
+ * ```
  */
 export function processConversionRates(options) {
     const { events, sortOrder = 'asc', includeHistorical = false, chainId, } = options;
@@ -189,7 +222,25 @@ export function getPrimaryCurrency(providerRates) {
     return primaryRate?.currency || null;
 }
 /**
- * Convert token input to currency
+ * Convert a token amount to a fiat currency amount using the conversion rate.
+ * Rounds up to the nearest cent (token decimals - 2) for user-friendly display.
+ *
+ * @param params - Conversion parameters
+ * @param params.token - Token info with decimals
+ * @param params.amountOutInt - Token amount as bigint (e.g., 100_000000n for 100 USDC)
+ * @param params.rate - Conversion rate with 18 decimals (1e18 = 1:1)
+ * @returns Fiat amount as bigint with cent-rounding applied
+ *
+ * @example
+ * ```ts
+ * // Convert 100 USDC at 1.05 rate to fiat
+ * const fiat = convertTokenInputToCurrency({
+ *   token: { decimals: 6, ... },
+ *   amountOutInt: 100_000000n,
+ *   rate: 1_050000000000000000n // 1.05
+ * })
+ * // Returns: 105_000000n (rounded to nearest cent)
+ * ```
  */
 export const convertTokenInputToCurrency = ({ token, amountOutInt, rate }) => {
     const oneCent = 10n ** BigInt(token.decimals - 2);
@@ -201,8 +252,27 @@ export const convertTokenInputToCurrency = ({ token, amountOutInt, rate }) => {
     return finalAmountInInt;
 };
 /**
- * Convert currency amount to token amount out (inverse of convertTokenInputToCurrency)
- * This accounts for the cent-rounding applied in the original function
+ * Convert a fiat currency amount back to token amount (inverse of convertTokenInputToCurrency).
+ * Accounts for the cent-rounding that was applied during the forward conversion.
+ *
+ * @param params - Conversion parameters
+ * @param params.token - Token info with decimals
+ * @param params.currency - Currency info with decimals
+ * @param params.currencyAmountInt - Fiat amount as bigint
+ * @param params.rate - Conversion rate with 18 decimals (1e18 = 1:1)
+ * @returns Token amount as bigint, floored to smallest token unit
+ *
+ * @example
+ * ```ts
+ * // Convert $105 fiat back to USDC at 1.05 rate
+ * const tokens = convertCurrencyToTokenOutput({
+ *   token: { decimals: 6, ... },
+ *   currency: SUPPORTED_CURRENCIES.USD,
+ *   currencyAmountInt: 105_00n, // $105.00
+ *   rate: 1_050000000000000000n // 1.05
+ * })
+ * // Returns: 100_000000n (100 USDC)
+ * ```
  */
 export const convertCurrencyToTokenOutput = ({ token, currency, currencyAmountInt, rate, }) => {
     const smallestUnit = 10n ** BigInt(token.decimals - currency.decimals);

package/dist/src/conversionRates.test.d.ts

@@ -0,0 +1 @@
+export {};