@provex/utils 1.0.16

package/README.md

@@ -0,0 +1,287 @@
+# @provex/utils
+
+Shared utility functions, types, and constants for the provex ecosystem. This package provides core business logic for currency operations, payment processing, token management, and blockchain interactions.
+
+## Installation
+
+```bash
+npm install @provex/utils
+```
+
+## Overview
+
+The utils package is the foundation of the provex system, providing:
+
+- **Currency Management** - Support for multiple fiat currencies with automatic contract ID generation
+- **Payment Provider Integration** - Configuration and utilities for various payment platforms
+- **Token Management** - Blockchain token utilities and amount calculations
+- **Conversion Rate Handling** - Exchange rate processing and currency conversions
+- **Time & Formatting Utilities** - Date/time formatting and number display utilities
+- **Smart Contract Integration** - Contract addresses and blockchain utilities
+
+## Usage
+
+### Currency Operations
+
+```typescript
+import {
+  getCurrencyInfo,
+  Currency,
+  formatCurrencyAmount,
+  SUPPORTED_CURRENCIES
+} from '@provex/utils/currencies'
+
+// Get currency information
+const usdInfo = getCurrencyInfo('USD')
+console.log(usdInfo.symbol) // '$'
+console.log(usdInfo.decimals) // 2
+
+// Create new currency
+const customCurrency = new Currency('GBP', '£', 'British Pound', 2)
+
+// Format currency amounts
+const formatted = formatCurrencyAmount(1234.56, 'USD') // '$1,234.56'
+
+// Check supported currencies
+console.log(Object.keys(SUPPORTED_CURRENCIES)) // ['USD', 'EUR', 'GBP', ...]
+```
+
+### Payment Provider Configuration
+
+```typescript
+import {
+  providers,
+  subProviders,
+  providerKeyToValidationKey
+} from '@provex/utils/payment'
+
+// Available providers
+console.log(providers.VENMO) // 'venmo'
+console.log(providers.ZELLE) // 'zelle'
+
+// Sub-providers (for Zelle banking partners)
+console.log(subProviders.CHASE) // 'chase'
+
+// Validation keys for each provider
+console.log(providerKeyToValidationKey.venmo) // 'venmoUsername'
+```
+
+### Token Management
+
+```typescript
+import {
+  allTokensInfo,
+  tokenByAddress,
+} from '@provex/utils/tokens'
+
+// Get token info
+const usdc = allTokensInfo.BASE.USDC
+console.log(usdc.decimals) // 6
+
+// Find token by address
+const token = tokenByAddress('0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913')
+```
+
+### Conversion Rate Processing
+
+```typescript
+import {
+  processConversionRates,
+  convertTokenInputToCurrency,
+  convertCurrencyToTokenOutput,
+  getPrimaryConversionRate
+} from '@provex/utils/conversionRates'
+
+// Process conversion rate events
+const providerRates = processConversionRates({
+  events: conversionRateEvents,
+  sortOrder: 'desc'
+})
+
+// Convert token amount to currency
+const currencyAmount = convertTokenInputToCurrency({
+  token: { decimals: 6 },
+  amountOutInt: parseUnits('100', 6), // 100 USDC
+  rate: parseUnits('1', 18) // 1:1 rate
+})
+
+// Convert currency to token output
+const tokenAmount = convertCurrencyToTokenOutput({
+  token: { decimals: 6 },
+  currencyAmountInt: parseUnits('100', 2), // $100
+  rate: parseUnits('1', 18)
+})
+```
+
+### Time and Formatting Utilities
+
+```typescript
+import {
+  formatTimestamp,
+  formatDuration,
+  interval,
+  sleep
+} from '@provex/utils/time'
+import {
+  formatUnits,
+  addThousandsSeparator,
+  parseUnits
+} from '@provex/utils/units'
+
+// Format timestamps
+const timeAgo = formatTimestamp(Date.now() - interval.hour) // '1h ago'
+
+// Format durations
+const duration = formatDuration({
+  from: new Date('2023-01-01'),
+  to: new Date('2023-01-02')
+}) // '1 day'
+
+// Format numbers with separators
+const formatted = addThousandsSeparator('1234567') // '1,234,567'
+
+// Format token amounts
+const displayAmount = formatUnits(parseUnits('1234.56', 6), {
+  decimals: 6,
+  truncateDecimals: 2
+}) // '1,234.56'
+
+// Sleep utility
+await sleep(1000) // Wait 1 second
+```
+
+### Smart Contract Integration
+
+```typescript
+import { contracts } from '@provex/utils/contracts'
+
+// Contract addresses
+console.log(contracts.usdc) // USDC token contract
+console.log(contracts.escrow) // Main escrow contract
+console.log(contracts.venmoReclaimVerifier) // Venmo proof verifier
+console.log(contracts.zelleBaseVerifier) // Zelle proof verifier
+```
+
+### Intent Management
+
+```typescript
+import type { IntentStruct } from '@provex/utils/intent'
+
+const intent: IntentStruct = {
+  owner: '0x...',           // Intent creator
+  to: '0x...',             // Payment recipient
+  depositId: 123n,         // Associated deposit
+  amount: parseUnits('100', 6), // Payment amount
+  timestamp: BigInt(Date.now() / 1000), // Creation time
+  paymentVerifier: '0x...', // Verifier contract
+  fiatCurrency: '0x...',   // Currency identifier
+  conversionRate: parseUnits('1', 6) // Exchange rate
+}
+```
+
+## Available Modules
+
+### Core Modules
+
+| Module | Purpose | Key Functions |
+|--------|---------|---------------|
+| `currencies` | Currency management | `getCurrencyInfo`, `formatCurrencyAmount`, `Currency` class |
+| `payment` | Provider configuration | Provider constants, validation utilities |
+| `tokens` | Token operations | `tokenByAddress`, amount comparisons |
+| `conversionRates` | Rate processing | `processConversionRates`, conversion utilities |
+| `time` | Time formatting | `formatTimestamp`, `formatDuration`, `sleep` |
+| `units` | Number formatting | `formatUnits`, `addThousandsSeparator` |
+| `contracts` | Smart contracts | Contract address constants |
+| `intent` | Intent structures | TypeScript interfaces |
+
+### Utility Modules
+
+| Module | Purpose | Key Functions |
+|--------|---------|---------------|
+| `sort` | Sorting utilities | `orderedSort`, `orderedSortThenById` |
+| `profit` | Profit calculations | `calculateProfit`, `calculateProfits` |
+| `participants` | User identification | `generateParticipantId` |
+| `input` | Input processing | `adjustLowestDecimal` |
+| `json` | JSON handling | `jsonSerializer`, `mapBigIntFields` |
+| `chain` | Blockchain utilities | `getExplorerUrl`, chain configurations |
+
+## Supported Currencies
+
+The package supports the following fiat currencies:
+
+- **USD** (US Dollar) - $
+- **EUR** (Euro) - €
+- **GBP** (British Pound) - £
+- **CAD** (Canadian Dollar) - C$
+- **AUD** (Australian Dollar) - A$
+- **JPY** (Japanese Yen) - ¥
+- **CHF** (Swiss Franc) - Fr
+- **CNY** (Chinese Yuan) - ¥
+- **INR** (Indian Rupee) - ₹
+- **BRL** (Brazilian Real) - R$
+- **MXN** (Mexican Peso) - $
+- **ARS** (Argentine Peso) - $
+
+## Supported Payment Providers
+
+- **Venmo** (`venmo`)
+- **Zelle** (`zelle`) with sub-providers:
+  - Chase (`chase`)
+  - Bank of America (`bank_of_america`)
+  - Citi (`citi`)
+- **CashApp** (`cashapp`)
+- **Revolut** (`revolut`)
+- **Wise** (`wise`)
+- **MercadoPago** (`mercadopago`)
+- **Manual** (`manual`)
+
+## Smart Contract Addresses
+
+The package includes contract addresses for:
+
+- **Token Contracts**: USDC
+- **Core Contracts**: Escrow, Relay Bridge
+- **Verifier Contracts**: Individual verifiers for each payment provider
+- **Service Contracts**: Gating service, witness signers
+
+## TypeScript Support
+
+All modules are fully typed with TypeScript interfaces and types exported for use in your applications:
+
+```typescript
+import type {
+  CurrencyInfo,
+  TokenInfo,
+  IntentStruct,
+  ConversionRateInfo,
+  ProviderKey,
+  SortDirection
+} from '@provex/utils'
+```
+
+## Build System
+
+The package uses TypeScript compilation and ES modules:
+
+```bash
+npm run build  # Compile TypeScript to JavaScript
+```
+
+## Dependencies
+
+- **viem** - Ethereum utilities for address handling and encoding
+- Built-in JSON data for country and currency information
+
+## Contributing
+
+When adding new utilities:
+
+1. Create focused modules for specific functionality
+2. Export functions through the main index file
+3. Include TypeScript types and interfaces
+4. Follow the existing naming conventions
+5. Add comprehensive JSDoc comments
+
+## License
+
+ISC License

package/dist/scripts/convert-svg.d.ts

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

package/dist/scripts/convert-svg.js

@@ -0,0 +1,17 @@
+import fs from 'fs';
+import path from 'path';
+const __dirname = import.meta.dirname;
+// Read SVG files and convert to TypeScript constants
+const svgDir = path.join(__dirname, '../src/flags');
+const outputFile = path.join(__dirname, '../src/flags.ts');
+const svgFiles = ['usd.svg', 'eur.svg'];
+let output = '// Auto-generated from SVG files\n\n';
+svgFiles.forEach(filename => {
+    const svgPath = path.join(svgDir, filename);
+    const svgContent = fs.readFileSync(svgPath, 'utf8');
+    const cleanSvg = svgContent.replace(/[\r\n]/g, ' ').replace(/\s+/g, ' ').trim();
+    const constName = filename.replace('.svg', '').toUpperCase() + '_FLAG_SVG';
+    output += `export const ${constName} = '${cleanSvg}';\n`;
+});
+fs.writeFileSync(outputFile, output);
+console.log('Generated flags.ts from SVG files');

package/dist/src/chain.d.ts

@@ -0,0 +1,14 @@
+import { type Chain } from 'viem/chains';
+export declare const chains: [Chain, ...Chain[]];
+export declare const chainIds: number[];
+export type ChainId = (typeof chainIds)[number];
+/**
+ * Get the explorer URL for a given chain, type, and hash
+ * @param chain - The chain to get the explorer URL for
+ * @param type - The type of explorer to use (tx or address)
+ * @param hash - The hash to get the explorer URL for
+ * @returns The explorer URL
+ */
+export declare function getExplorerUrl(chain: Chain, type: 'tx' | 'address', hash: string): string;
+export declare const chainIdToChain: Map<number, Chain>;
+export declare const chainIdToTargetBlockTime: Map<number, number>;

package/dist/src/chain.js

@@ -0,0 +1,18 @@
+import { base, pulsechain } from 'viem/chains';
+export const chains = [pulsechain, base];
+export const chainIds = chains.map((chain) => chain.id);
+/**
+ * Get the explorer URL for a given chain, type, and hash
+ * @param chain - The chain to get the explorer URL for
+ * @param type - The type of explorer to use (tx or address)
+ * @param hash - The hash to get the explorer URL for
+ * @returns The explorer URL
+ */
+export function getExplorerUrl(chain, type, hash) {
+    return `${chain.blockExplorers?.default.url}/${type}/${hash}`;
+}
+export const chainIdToChain = new Map(chains.map((chain) => [chain.id, chain]));
+export const chainIdToTargetBlockTime = new Map([
+    [369, 10_000],
+    [8453, 2_000],
+]);

package/dist/src/contracts.d.ts

@@ -0,0 +1,30 @@
+import { type Hex } from 'viem';
+import type { ChainId } from './chain.js';
+/**
+ * Contracts for the app
+ */
+export type Contracts = {
+    gatingService: Hex;
+    usdc: Hex;
+    escrow: Hex[];
+    venmoReclaimVerifier: Hex[];
+    revolutReclaimVerifier: Hex[];
+    cashappReclaimVerifier: Hex[];
+    wiseReclaimVerifier: Hex[];
+    mercadopagoReclaimVerifier: Hex[];
+    zelleBaseVerifier: Hex[];
+    zelleBoAReclaimVerifier: Hex[];
+    zelleChaseReclaimVerifier: Hex[];
+    zelleCitiReclaimVerifier: Hex[];
+    paypalReclaimVerifier: Hex[];
+    monzoReclaimVerifier: Hex[];
+};
+export declare const reclaimSigners: {
+    readonly zkp2pWitnessSigner: "0x0636c417755E3ae25C6c166D181c0607F4C572A3";
+    readonly reclaimWitnessSigner: "0x244897572368eadf65bfbc5aec98d8e5443a9072";
+};
+export declare const baseContracts: Contracts;
+export declare const pulsechainContracts: Contracts;
+export declare const contractsByChainId: Map<number, Contracts>;
+export declare const getContracts: (chainId: ChainId) => Contracts | null;
+export declare const getLatestContract: (chainId: ChainId, key: keyof Contracts) => `0x${string}` | null;

package/dist/src/contracts.js

@@ -0,0 +1,64 @@
+import { getAddress } from 'viem';
+import { base, pulsechain } from 'viem/chains';
+export const reclaimSigners = {
+    zkp2pWitnessSigner: '0x0636c417755E3ae25C6c166D181c0607F4C572A3',
+    reclaimWitnessSigner: '0x244897572368eadf65bfbc5aec98d8e5443a9072',
+};
+export const baseContracts = {
+    gatingService: getAddress('0x396D31055Db28C0C6f36e8b36f18FE7227248a97'),
+    usdc: getAddress('0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'),
+    escrow: [getAddress('0xCA38607D85E8F6294Dc10728669605E6664C2D70')],
+    venmoReclaimVerifier: [getAddress('0x9a733B55a875D0DB4915c6B36350b24F8AB99dF5')],
+    revolutReclaimVerifier: [getAddress('0xAA5A1B62B01781E789C900d616300717CD9A41aB')],
+    cashappReclaimVerifier: [getAddress('0x76D33A33068D86016B806dF02376dDBb23Dd3703')],
+    wiseReclaimVerifier: [getAddress('0xFF0149799631D7A5bdE2e7eA9b306c42b3d9a9ca')],
+    mercadopagoReclaimVerifier: [
+        // getAddress('0x00d003c73eab8feaec04bab976235915fe7641e3'),
+        getAddress('0xf2AC5be14F32Cbe6A613CFF8931d95460D6c33A3'),
+    ],
+    zelleBaseVerifier: [
+        // getAddress('0x1783f040783c0827fb64d128ece548d9b3613ad5'),
+        getAddress('0x431a078A5029146aAB239c768A615CD484519aF7'),
+    ],
+    zelleChaseReclaimVerifier: [getAddress('0xBcD7C6BBcA5869fBefe3E322263EE1090221D7A9')],
+    zelleBoAReclaimVerifier: [getAddress('0x809c7A20A2dbBB3210fC73Dd7C01Cd7Fa70C195F')],
+    zelleCitiReclaimVerifier: [getAddress('0x3128badc46dbe2e37bdd2d64f33fb3b3a639570e')],
+    paypalReclaimVerifier: [getAddress('0x03d17E9371C858072E171276979f6B44571C5DeA')],
+    monzoReclaimVerifier: [getAddress('0x0dE46433bD251027f73eD8f28E01eF05DA36a2E0')],
+};
+export const pulsechainContracts = {
+    gatingService: getAddress('0x4Bd6364FCC4D8A537aBfee33B16E959794fDf9Cf'),
+    usdc: getAddress('0x15D38573d2feeb82e7ad5187aB8c1D52810B1f07'),
+    escrow: [getAddress('0x2932E08BFD212Ef0732257bDd6463BF55E9b97d7')],
+    cashappReclaimVerifier: [getAddress('0x9224433D6AD9a5A774ca74Ca33c01747FA710A9d')],
+    mercadopagoReclaimVerifier: [getAddress('0xc4D0cf4DF12e329f9c951d1D9BB815da6138850A')],
+    monzoReclaimVerifier: [getAddress('0xBde2c79c1897459e66C0fdF6764EED0c6839C878')],
+    nullifierRegistry: [getAddress('0x471D3c6C9E32CE2556d0117aC161Aa82AEac17d8')],
+    paypalReclaimVerifier: [getAddress('0x1DdBfd39a141C5A2329d849CADa6a83404E0Ce4F')],
+    revolutReclaimVerifier: [getAddress('0x8234AA463C8B94778f58eA0bFEfcBAC3683341A9')],
+    venmoReclaimVerifier: [getAddress('0x0Dd524dA03f610480aF3F433B411b6016cFBDeab')],
+    wiseReclaimVerifier: [getAddress('0x7B72d7CfAfDfD397E2460c933e84D16dc121845a')],
+    zelleBaseVerifier: [getAddress('0x539566771f9c38c6038aafc1946bf11af9cdb201')],
+    zelleBoAReclaimVerifier: [getAddress('0x506a746b8228F9f9d4522105b973Dc7223A64EAC')],
+    zelleChaseReclaimVerifier: [getAddress('0xB0aA0a58959465bBCf0eCbD62A84B743A5435c99')],
+    zelleCitiReclaimVerifier: [getAddress('0x5624E479924eBFb25B51F36e3FDaE605dADb448b')],
+};
+export const contractsByChainId = new Map([
+    [base.id, baseContracts],
+    [pulsechain.id, pulsechainContracts],
+]);
+export const getContracts = (chainId) => {
+    return contractsByChainId.get(chainId) ?? null;
+};
+export const getLatestContract = (chainId, key) => {
+    const contracts = getContracts(chainId);
+    if (!contracts)
+        return null;
+    const target = contracts[key];
+    if (!target)
+        return null;
+    if (Array.isArray(target)) {
+        return target[target.length - 1] ?? null;
+    }
+    return target;
+};

package/dist/src/conversionRates.d.ts

@@ -0,0 +1,124 @@
+import type { Hex } from 'viem';
+import { Currency } from './currencies.js';
+import { type ProviderKey } from './payment.js';
+import type { SortDirection } from './sort.js';
+import type { TokenInfo } from './tokens.js';
+import type { ChainId } from './chain.js';
+/**
+ * Conversion rate info
+ */
+export interface ConversionRateInfo {
+    depositConversionRateUpdatedId: string;
+    currency: string;
+    verifier: string;
+    value: string;
+    orderId: string;
+    depositId: string;
+    transaction: {
+        hash: string;
+        block: {
+            timestamp: string;
+        };
+    };
+}
+/**
+ * Conversion rate info with current deposit conversion rate updated
+ */
+export interface ConversionRateInfoWithCurrent extends ConversionRateInfo {
+    currentDepositConversionRateUpdatedId: string;
+    currentDepositConversionRateUpdated: {
+        value: string;
+    };
+}
+/**
+ * Provider rates
+ */
+export type ProviderRates<RateInfo> = Map<ProviderKey, Map<Hex, RateInfo>>;
+/**
+ * Process conversion rates options
+ */
+interface ProcessConversionRatesOptions {
+    chainId: ChainId;
+    events: ConversionRateInfoWithCurrent[];
+    sortOrder?: SortDirection;
+    includeHistorical?: boolean;
+}
+/**
+ * Get conversion rate options
+ */
+interface GetConversionRateOptions {
+    events: ConversionRateInfoWithCurrent[];
+    currency: Hex;
+    verifier: string;
+    chainId: ChainId;
+    includeHistory?: boolean;
+    fallbackRate?: {
+        currency: string;
+        value: string;
+        verifier: string;
+    } | null;
+}
+/**
+ * Extract currencies options
+ */
+interface ExtractCurrenciesOptions {
+    providerRates: ProviderRates<ConversionRateInfo[]>;
+    providersOnly?: ProviderKey[];
+    currenciesOnly?: string[];
+}
+/**
+ * Process deposit currency added events into organized conversion rates
+ */
+export declare function processConversionRates(options: ProcessConversionRatesOptions): ProviderRates<ConversionRateInfo[]>;
+/**
+ * Get conversion rate for a specific currency and verifier combination
+ */
+export declare function getConversionRate(options: GetConversionRateOptions): ConversionRateInfo | ConversionRateInfo[] | null;
+/**
+ * Extract unique currencies from processed provider rates
+ */
+export declare function extractCurrencies(options: ExtractCurrenciesOptions): string[];
+/**
+ * Get the latest conversion rate across all providers for a currency
+ */
+export declare function getLatestRateForCurrency(options: {
+    providerRates: ProviderRates<ConversionRateInfo>;
+    currency: Hex;
+    preferredProvider?: ProviderKey;
+}): ConversionRateInfo | null;
+/**
+ * Get the primary conversion rate from processed provider rates
+ * Returns the first available rate, prioritizing by provider order
+ */
+export declare function getPrimaryConversionRate(providerRates: ProviderRates<ConversionRateInfo>): ConversionRateInfo | null;
+/**
+ * Get primary conversion rate for a specific currency across all providers
+ */
+export declare function getPrimaryRateForCurrency(providerRates: ProviderRates<ConversionRateInfo>, currency: Hex): ConversionRateInfo | null;
+/**
+ * Get the primary verifier (payment provider) from conversion rates
+ */
+export declare function getPrimaryVerifier(providerRates: ProviderRates<ConversionRateInfo>): string | null;
+/**
+ * Get the primary currency from conversion rates
+ */
+export declare function getPrimaryCurrency(providerRates: ProviderRates<ConversionRateInfo>): string | null;
+/**
+ * Convert token input to currency
+ */
+export declare const convertTokenInputToCurrency: ({ token, amountOutInt, rate }: {
+    token: TokenInfo;
+    amountOutInt: bigint;
+    rate: bigint;
+}) => bigint;
+/**
+ * Convert currency amount to token amount out (inverse of convertTokenInputToCurrency)
+ * This accounts for the cent-rounding applied in the original function
+ */
+export declare const convertCurrencyToTokenOutput: ({ token, currency, currencyAmountInt, rate, }: {
+    token: TokenInfo;
+    currency: Currency;
+    currencyAmountInt: bigint;
+    rate: bigint;
+}) => bigint;
+export {};