@provex/utils 1.0.16 → 1.2.3

package/dist/src/conversionRates.test.js

@@ -0,0 +1,473 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { base } from 'viem/chains';
+import { processConversionRates, getConversionRate, extractCurrencies, getLatestRateForCurrency, getPrimaryConversionRate, getPrimaryRateForCurrency, getPrimaryVerifier, getPrimaryCurrency, convertTokenInputToCurrency, convertCurrencyToTokenOutput, } from './conversionRates.js';
+import { SUPPORTED_CURRENCIES } from './currencies.js';
+import { v2BaseContracts } from './contracts.js';
+describe('conversionRates', () => {
+    // Test data
+    const USD_CONTRACT_ID = SUPPORTED_CURRENCIES.USD.contractId;
+    const EUR_CONTRACT_ID = SUPPORTED_CURRENCIES.EUR.contractId;
+    // Use actual v2 verifier addresses from contracts
+    const VENMO_VERIFIER = v2BaseContracts.venmoReclaimVerifier[0];
+    const ZELLE_VERIFIER = v2BaseContracts.zelleBaseVerifier[0];
+    const createMockEvent = (overrides = {}) => ({
+        depositConversionRateUpdatedId: 'rate-1',
+        currency: USD_CONTRACT_ID,
+        verifier: VENMO_VERIFIER,
+        value: '1000000000000000000', // 1.0
+        orderId: '0x0001',
+        depositId: 'deposit-1',
+        transaction: {
+            hash: '0xhash1',
+            block: { timestamp: '1700000000' },
+        },
+        currentDepositConversionRateUpdatedId: 'rate-1',
+        currentDepositConversionRateUpdated: {
+            value: '1000000000000000000',
+        },
+        ...overrides,
+    });
+    const MOCK_TOKEN = {
+        address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+        decimals: 6,
+        symbol: 'USDC',
+        name: 'USD Coin',
+        chainId: base.id,
+    };
+    describe('processConversionRates', () => {
+        it('should process empty events array', () => {
+            const result = processConversionRates({
+                chainId: base.id,
+                events: [],
+            });
+            assert.equal(result.size, 0);
+        });
+        it('should process single event', () => {
+            const events = [createMockEvent()];
+            const result = processConversionRates({
+                chainId: base.id,
+                events,
+            });
+            assert.equal(result.size, 1);
+            const venmoRates = result.get('venmo');
+            assert.ok(venmoRates, 'Should have venmo rates');
+            const usdRates = venmoRates.get(USD_CONTRACT_ID);
+            assert.ok(usdRates, 'Should have USD rates');
+            assert.equal(usdRates.length, 1);
+        });
+        it('should skip events without currentDepositConversionRateUpdated', () => {
+            const events = [
+                createMockEvent({ currentDepositConversionRateUpdated: undefined }),
+            ];
+            const result = processConversionRates({
+                chainId: base.id,
+                events,
+            });
+            assert.equal(result.size, 0);
+        });
+        it('should sort events by orderId in ascending order by default', () => {
+            const events = [
+                createMockEvent({ orderId: '0x0002' }),
+                createMockEvent({ orderId: '0x0001' }),
+                createMockEvent({ orderId: '0x0003' }),
+            ];
+            const result = processConversionRates({
+                chainId: base.id,
+                events,
+                includeHistorical: true,
+            });
+            const venmoRates = result.get('venmo')?.get(USD_CONTRACT_ID);
+            assert.ok(venmoRates);
+            assert.equal(venmoRates[0].orderId, '0x0001');
+            assert.equal(venmoRates[1].orderId, '0x0002');
+            assert.equal(venmoRates[2].orderId, '0x0003');
+        });
+        it('should sort events in descending order when specified', () => {
+            const events = [
+                createMockEvent({ orderId: '0x0002' }),
+                createMockEvent({ orderId: '0x0001' }),
+                createMockEvent({ orderId: '0x0003' }),
+            ];
+            const result = processConversionRates({
+                chainId: base.id,
+                events,
+                sortOrder: 'desc',
+                includeHistorical: true,
+            });
+            const venmoRates = result.get('venmo')?.get(USD_CONTRACT_ID);
+            assert.ok(venmoRates);
+            assert.equal(venmoRates[0].orderId, '0x0003');
+        });
+        it('should keep only latest rate when includeHistorical is false', () => {
+            const events = [
+                createMockEvent({
+                    orderId: '0x0001',
+                    currentDepositConversionRateUpdated: { value: '1000000000000000000' },
+                }),
+                createMockEvent({
+                    orderId: '0x0002',
+                    currentDepositConversionRateUpdated: { value: '1050000000000000000' },
+                }),
+            ];
+            const result = processConversionRates({
+                chainId: base.id,
+                events,
+                includeHistorical: false,
+            });
+            const venmoRates = result.get('venmo')?.get(USD_CONTRACT_ID);
+            assert.ok(venmoRates);
+            assert.equal(venmoRates.length, 1);
+            // Should have the latest rate (sorted asc, so last one replaces)
+            assert.equal(venmoRates[0].value, '1050000000000000000');
+        });
+        it('should group rates by provider', () => {
+            const events = [
+                createMockEvent({ verifier: VENMO_VERIFIER }),
+                createMockEvent({ verifier: ZELLE_VERIFIER }),
+            ];
+            const result = processConversionRates({
+                chainId: base.id,
+                events,
+            });
+            assert.ok(result.get('venmo'), 'Should have venmo rates');
+            assert.ok(result.get('zelle'), 'Should have zelle rates');
+        });
+        it('should group rates by currency', () => {
+            const events = [
+                createMockEvent({ currency: USD_CONTRACT_ID }),
+                createMockEvent({ currency: EUR_CONTRACT_ID }),
+            ];
+            const result = processConversionRates({
+                chainId: base.id,
+                events,
+            });
+            const venmoRates = result.get('venmo');
+            assert.ok(venmoRates);
+            assert.ok(venmoRates.get(USD_CONTRACT_ID), 'Should have USD rates');
+            assert.ok(venmoRates.get(EUR_CONTRACT_ID), 'Should have EUR rates');
+        });
+    });
+    describe('getConversionRate', () => {
+        it('should return null for empty events', () => {
+            const result = getConversionRate({
+                events: [],
+                currency: USD_CONTRACT_ID,
+                verifier: VENMO_VERIFIER,
+                chainId: base.id,
+            });
+            assert.equal(result, null);
+        });
+        it('should return rate for matching currency and verifier', () => {
+            const events = [createMockEvent()];
+            const result = getConversionRate({
+                events,
+                currency: USD_CONTRACT_ID,
+                verifier: VENMO_VERIFIER,
+                chainId: base.id,
+            });
+            assert.ok(result, 'Should return a rate');
+            assert.ok(!Array.isArray(result), 'Should return single rate');
+            assert.equal(result.value, '1000000000000000000');
+        });
+        it('should return null for non-matching currency', () => {
+            const events = [createMockEvent({ currency: USD_CONTRACT_ID })];
+            const result = getConversionRate({
+                events,
+                currency: EUR_CONTRACT_ID,
+                verifier: VENMO_VERIFIER,
+                chainId: base.id,
+            });
+            assert.equal(result, null);
+        });
+        it('should return array when includeHistory is true', () => {
+            const events = [
+                createMockEvent({ orderId: '0x0001' }),
+                createMockEvent({ orderId: '0x0002' }),
+            ];
+            const result = getConversionRate({
+                events,
+                currency: USD_CONTRACT_ID,
+                verifier: VENMO_VERIFIER,
+                chainId: base.id,
+                includeHistory: true,
+            });
+            assert.ok(Array.isArray(result), 'Should return array');
+            assert.equal(result.length, 2);
+        });
+        it('should use fallback rate when no matching rate found', () => {
+            const fallbackRate = {
+                currency: USD_CONTRACT_ID,
+                value: '999000000000000000',
+                verifier: VENMO_VERIFIER,
+            };
+            const result = getConversionRate({
+                events: [],
+                currency: USD_CONTRACT_ID,
+                verifier: VENMO_VERIFIER,
+                chainId: base.id,
+                fallbackRate,
+            });
+            assert.ok(result, 'Should return fallback rate');
+            assert.ok(!Array.isArray(result));
+            assert.equal(result.value, '999000000000000000');
+        });
+        it('should not use fallback rate when currency does not match', () => {
+            const fallbackRate = {
+                currency: EUR_CONTRACT_ID,
+                value: '999000000000000000',
+                verifier: VENMO_VERIFIER,
+            };
+            const result = getConversionRate({
+                events: [],
+                currency: USD_CONTRACT_ID,
+                verifier: VENMO_VERIFIER,
+                chainId: base.id,
+                fallbackRate,
+            });
+            assert.equal(result, null);
+        });
+    });
+    describe('extractCurrencies', () => {
+        it('should extract currencies from provider rates', () => {
+            const providerRates = new Map([
+                [
+                    'venmo',
+                    new Map([
+                        [USD_CONTRACT_ID, [createMockEvent()]],
+                        [EUR_CONTRACT_ID, [createMockEvent({ currency: EUR_CONTRACT_ID })]],
+                    ]),
+                ],
+            ]);
+            const currencies = extractCurrencies({ providerRates });
+            assert.equal(currencies.length, 2);
+            assert.ok(currencies.includes(USD_CONTRACT_ID));
+            assert.ok(currencies.includes(EUR_CONTRACT_ID));
+        });
+        it('should filter by providers when specified', () => {
+            const providerRates = new Map([
+                ['venmo', new Map([[USD_CONTRACT_ID, [createMockEvent()]]])],
+                ['zelle', new Map([[EUR_CONTRACT_ID, [createMockEvent({ currency: EUR_CONTRACT_ID })]]])],
+            ]);
+            const currencies = extractCurrencies({
+                providerRates,
+                providersOnly: ['venmo'],
+            });
+            assert.equal(currencies.length, 1);
+            assert.ok(currencies.includes(USD_CONTRACT_ID));
+        });
+        it('should filter by currencies when specified', () => {
+            const providerRates = new Map([
+                [
+                    'venmo',
+                    new Map([
+                        [USD_CONTRACT_ID, [createMockEvent()]],
+                        [EUR_CONTRACT_ID, [createMockEvent({ currency: EUR_CONTRACT_ID })]],
+                    ]),
+                ],
+            ]);
+            const currencies = extractCurrencies({
+                providerRates,
+                currenciesOnly: [USD_CONTRACT_ID],
+            });
+            assert.equal(currencies.length, 1);
+            assert.ok(currencies.includes(USD_CONTRACT_ID));
+        });
+        it('should return empty array for empty provider rates', () => {
+            const currencies = extractCurrencies({ providerRates: new Map() });
+            assert.equal(currencies.length, 0);
+        });
+    });
+    describe('getLatestRateForCurrency', () => {
+        it('should return null for empty provider rates', () => {
+            const result = getLatestRateForCurrency({
+                providerRates: new Map(),
+                currency: USD_CONTRACT_ID,
+            });
+            assert.equal(result, null);
+        });
+        it('should return latest rate by timestamp', () => {
+            const oldRate = createMockEvent({
+                transaction: { hash: '0x1', block: { timestamp: '1700000000' } },
+            });
+            const newRate = createMockEvent({
+                transaction: { hash: '0x2', block: { timestamp: '1700001000' } },
+                verifier: ZELLE_VERIFIER,
+            });
+            const providerRates = new Map([
+                ['venmo', new Map([[USD_CONTRACT_ID, oldRate]])],
+                ['zelle', new Map([[USD_CONTRACT_ID, newRate]])],
+            ]);
+            const result = getLatestRateForCurrency({
+                providerRates,
+                currency: USD_CONTRACT_ID,
+            });
+            assert.ok(result);
+            assert.equal(result.transaction.block.timestamp, '1700001000');
+        });
+        it('should prefer specified provider when timestamps match', () => {
+            const rate = createMockEvent({
+                transaction: { hash: '0x1', block: { timestamp: '1700000000' } },
+            });
+            const providerRates = new Map([
+                ['venmo', new Map([[USD_CONTRACT_ID, rate]])],
+                ['zelle', new Map([[USD_CONTRACT_ID, { ...rate, verifier: ZELLE_VERIFIER }]])],
+            ]);
+            const result = getLatestRateForCurrency({
+                providerRates,
+                currency: USD_CONTRACT_ID,
+                preferredProvider: 'venmo',
+            });
+            assert.ok(result);
+            assert.equal(result.verifier, VENMO_VERIFIER);
+        });
+    });
+    describe('getPrimaryConversionRate', () => {
+        it('should return null for empty provider rates', () => {
+            const result = getPrimaryConversionRate(new Map());
+            assert.equal(result, null);
+        });
+        it('should prioritize USD over other currencies', () => {
+            const usdRate = createMockEvent({ currency: USD_CONTRACT_ID });
+            const eurRate = createMockEvent({ currency: EUR_CONTRACT_ID });
+            const providerRates = new Map([
+                ['venmo', new Map([[EUR_CONTRACT_ID, eurRate]])],
+                ['zelle', new Map([[USD_CONTRACT_ID, usdRate]])],
+            ]);
+            const result = getPrimaryConversionRate(providerRates);
+            assert.ok(result);
+            assert.equal(result.currency, USD_CONTRACT_ID);
+        });
+        it('should return first available rate if no USD', () => {
+            const eurRate = createMockEvent({ currency: EUR_CONTRACT_ID });
+            const providerRates = new Map([
+                ['venmo', new Map([[EUR_CONTRACT_ID, eurRate]])],
+            ]);
+            const result = getPrimaryConversionRate(providerRates);
+            assert.ok(result);
+            assert.equal(result.currency, EUR_CONTRACT_ID);
+        });
+    });
+    describe('getPrimaryRateForCurrency', () => {
+        it('should return rate for specified currency', () => {
+            const eurRate = createMockEvent({ currency: EUR_CONTRACT_ID });
+            const providerRates = new Map([
+                ['venmo', new Map([[EUR_CONTRACT_ID, eurRate]])],
+            ]);
+            const result = getPrimaryRateForCurrency(providerRates, EUR_CONTRACT_ID);
+            assert.ok(result);
+            assert.equal(result.currency, EUR_CONTRACT_ID);
+        });
+        it('should return null if currency not found', () => {
+            const usdRate = createMockEvent({ currency: USD_CONTRACT_ID });
+            const providerRates = new Map([
+                ['venmo', new Map([[USD_CONTRACT_ID, usdRate]])],
+            ]);
+            const result = getPrimaryRateForCurrency(providerRates, EUR_CONTRACT_ID);
+            assert.equal(result, null);
+        });
+    });
+    describe('getPrimaryVerifier', () => {
+        it('should return verifier from primary rate', () => {
+            const rate = createMockEvent({ verifier: VENMO_VERIFIER });
+            const providerRates = new Map([
+                ['venmo', new Map([[USD_CONTRACT_ID, rate]])],
+            ]);
+            const result = getPrimaryVerifier(providerRates);
+            assert.equal(result, VENMO_VERIFIER);
+        });
+        it('should return null for empty rates', () => {
+            const result = getPrimaryVerifier(new Map());
+            assert.equal(result, null);
+        });
+    });
+    describe('getPrimaryCurrency', () => {
+        it('should return currency from primary rate', () => {
+            const rate = createMockEvent({ currency: USD_CONTRACT_ID });
+            const providerRates = new Map([
+                ['venmo', new Map([[USD_CONTRACT_ID, rate]])],
+            ]);
+            const result = getPrimaryCurrency(providerRates);
+            assert.equal(result, USD_CONTRACT_ID);
+        });
+        it('should return null for empty rates', () => {
+            const result = getPrimaryCurrency(new Map());
+            assert.equal(result, null);
+        });
+    });
+    describe('convertTokenInputToCurrency', () => {
+        it('should convert token amount at 1:1 rate', () => {
+            const rate = 10n ** 18n; // 1.0 rate
+            const amountOutInt = 100000000n; // 100 USDC
+            const result = convertTokenInputToCurrency({
+                token: MOCK_TOKEN,
+                amountOutInt,
+                rate,
+            });
+            // At 1:1, 100 tokens should give ~100 fiat units
+            // Result is rounded up to nearest cent (10^4 for USDC with 6 decimals)
+            assert.equal(result, 100000000n);
+        });
+        it('should convert token amount at 1.05 rate', () => {
+            const rate = 1050000000000000000n; // 1.05 rate
+            const amountOutInt = 100000000n; // 100 USDC
+            const result = convertTokenInputToCurrency({
+                token: MOCK_TOKEN,
+                amountOutInt,
+                rate,
+            });
+            // 100 * 1.05 = 105, rounded up to nearest cent
+            assert.equal(result, 105000000n);
+        });
+        it('should round up to nearest cent', () => {
+            const rate = 10n ** 18n;
+            const amountOutInt = 100000001n; // 100.000001 USDC
+            const result = convertTokenInputToCurrency({
+                token: MOCK_TOKEN,
+                amountOutInt,
+                rate,
+            });
+            // Should round up from 100.000001 to 100.01 (nearest cent in 6 decimals)
+            assert.equal(result, 100010000n);
+        });
+    });
+    describe('convertCurrencyToTokenOutput', () => {
+        it('should convert fiat to tokens at 1:1 rate', () => {
+            const rate = 10n ** 18n;
+            const currencyAmountInt = 10000n; // $100.00 in cents
+            const result = convertCurrencyToTokenOutput({
+                token: MOCK_TOKEN,
+                currency: SUPPORTED_CURRENCIES.USD,
+                currencyAmountInt,
+                rate,
+            });
+            // At 1:1, $100 should give 100 USDC = 100_000000
+            assert.equal(result, 100000000n);
+        });
+        it('should convert fiat to tokens at 1.05 rate', () => {
+            const rate = 1050000000000000000n; // 1.05 rate
+            const currencyAmountInt = 10500n; // $105.00 in cents
+            const result = convertCurrencyToTokenOutput({
+                token: MOCK_TOKEN,
+                currency: SUPPORTED_CURRENCIES.USD,
+                currencyAmountInt,
+                rate,
+            });
+            // $105 at 1.05 rate should give 100 USDC
+            assert.equal(result, 100000000n);
+        });
+        it('should floor to smallest token unit', () => {
+            const rate = 10n ** 18n;
+            const currencyAmountInt = 10001n; // $100.01
+            const result = convertCurrencyToTokenOutput({
+                token: MOCK_TOKEN,
+                currency: SUPPORTED_CURRENCIES.USD,
+                currencyAmountInt,
+                rate,
+            });
+            // $100.01 at 1:1 = 100.01 USDC = 100_010000 base units
+            // Floored to smallest unit (10^4 for 6-2 decimal difference)
+            assert.equal(result, 100010000n);
+        });
+    });
+});

package/dist/src/currencies.d.ts

@@ -1,15 +1,38 @@
+/**
+ * @fileoverview Fiat currency definitions and utilities for the Provex protocol.
+ *
+ * This module defines supported fiat currencies with their symbols, decimals,
+ * and contract IDs (keccak256 hashes used for on-chain identification).
+ *
+ * @remarks
+ * - Currency contract IDs are keccak256(currencyCode) used in smart contracts
+ * - Most currencies use 2 decimal places, but JPY/KRW/VND/UGX use 0
+ * - The Currency class provides parsing/formatting utilities for amounts
+ *
+ * @see {@link payment} for payment provider currency support
+ * @see {@link conversionRates} for exchange rate calculations
+ */
 import { type Hex } from 'viem';
 import { type FormatRateDisplayOptions } from './units.js';
 /**
- * Relevant info for a currency
+ * Currency information interface for display and calculations.
+ * Used for both the Currency class instances and serialized JSON representations.
  */
 export interface CurrencyInfo {
+    /** ISO 4217 currency code (e.g., 'USD', 'EUR') */
     ticker: string;
+    /** Currency symbol for display (e.g., '$', '€', '£') */
     symbol: string;
+    /** Full currency name (e.g., 'US Dollar') */
     name: string;
+    /** Number of decimal places (2 for most, 0 for JPY/KRW) */
     decimals: number;
+    /** keccak256 hash of the currency code, used in smart contracts */
     contractId: Hex;
+    /** Flag image URL or data URL for display */
     flag: string;
+    /** Zoom level for flag display (1 for square flags USD/EUR, 1.5 for rectangular) */
+    zoom: number;
 }
 /**
  * Country info from the countries.json file
@@ -28,12 +51,20 @@ export interface CountryInfo {
  */
 export declare const tickerToContractId: (ticker: string) => Hex;
 /**
- * Currency class that automatically generates contract ID
- * @param code - The currency code
- * @param symbol - The currency symbol
- * @param name - The currency name
- * @param decimals - The number of decimals
- * @param flag - The flag image path
+ * Currency class representing a fiat currency with parsing and formatting utilities.
+ *
+ * Each currency has:
+ * - A unique ticker (ISO 4217 code)
+ * - A display symbol
+ * - A contract ID (keccak256 hash for on-chain use)
+ * - Decimal precision for amount formatting
+ *
+ * @example
+ * ```ts
+ * const usd = SUPPORTED_CURRENCIES.USD
+ * const amount = usd.parseAmount('100.50')    // 10050n (2 decimals)
+ * const display = usd.formatAmount(10050n)   // '100.50'
+ * ```
  */
 export declare class Currency implements CurrencyInfo {
     readonly ticker: string;
@@ -42,7 +73,18 @@ export declare class Currency implements CurrencyInfo {
     readonly decimals: number;
     readonly contractId: Hex;
     readonly flag: string;
-    constructor(code: string, symbol: string, name: string, decimals: number, flag?: string);
+    readonly zoom: number;
+    /**
+     * Create a new Currency instance.
+     *
+     * @param code - ISO 4217 currency code (converted to uppercase)
+     * @param symbol - Display symbol (e.g., '$')
+     * @param name - Full currency name
+     * @param decimals - Number of decimal places
+     * @param flag - Optional flag image URL
+     * @param zoom - Optional zoom level for flag display (default: 1.5)
+     */
+    constructor(code: string, symbol: string, name: string, decimals: number, flag?: string, zoom?: number);
     /**
      * Generate a contract ID for the currency
      * @returns The contract ID
@@ -71,6 +113,30 @@ export declare class Currency implements CurrencyInfo {
  * @param currencyCode - The currency code
  */
 export declare function generateCurrencyId(currencyCode: string): string;
+/**
+ * Registry of all supported fiat currencies.
+ *
+ * Each currency is a Currency instance with:
+ * - Correct decimal precision (0 for JPY/KRW/VND/UGX, 2 for others)
+ * - Unique contract ID (keccak256 hash)
+ * - Flag image for UI display
+ *
+ * @remarks
+ * Payment providers support different subsets of currencies.
+ * Use `getCurrenciesForProvider()` in payment.ts to get supported currencies
+ * for a specific payment method.
+ *
+ * @example
+ * ```ts
+ * // Get USD currency info
+ * const usd = SUPPORTED_CURRENCIES.USD
+ * console.log(usd.symbol)      // '$'
+ * console.log(usd.contractId)  // '0x...' (keccak256('USD'))
+ *
+ * // Parse user input
+ * const amount = usd.parseAmount('100.50')
+ * ```
+ */
 export declare const SUPPORTED_CURRENCIES: {
     readonly USD: Currency;
     readonly EUR: Currency;
@@ -109,9 +175,31 @@ export declare const SUPPORTED_CURRENCIES: {
     readonly RON: Currency;
     readonly HUF: Currency;
 };
-/** Supported currency code */
+/**
+ * Union type of all supported currency codes.
+ * Use for type-safe currency code parameters.
+ */
 export type SupportedCurrencyCode = keyof typeof SUPPORTED_CURRENCIES;
+/**
+ * Map from contract ID (keccak256 hash) to Currency instance.
+ * Used for O(1) lookup of currency info from on-chain data.
+ *
+ * @example
+ * ```ts
+ * const contractId = '0x...' // from blockchain event
+ * const currency = currencyById.get(contractId)
+ * if (currency) {
+ *   console.log(currency.ticker) // 'USD'
+ * }
+ * ```
+ */
 export declare const currencyById: Map<`0x${string}`, Currency>;
+/**
+ * Get the currency name/ticker by contract ID
+ * @param contractId - The contract ID (keccak256 hash)
+ * @returns The currency ticker or the original contractId if not found
+ */
+export declare function getCurrencyNameByContractId(contractId: string): string;
 /**
  * Get the currency info for a currency code
  * @param currencyCode - The currency code
@@ -142,3 +230,19 @@ export declare function getAllSupportedCurrencies(): CurrencyInfo[];
  * @returns True if the currency is supported, false otherwise
  */
 export declare function isSupportedCurrency(currencyCode: string): boolean;
+/**
+ * Format the default conversion rate based on currency decimals.
+ * Returns "1" for zero-decimal currencies (JPY, KRW, VND, UGX),
+ * or "1.00" for standard 2-decimal currencies (USD, EUR, etc.).
+ *
+ * @param currency - The currency to format the default rate for
+ * @returns Formatted default rate string matching the currency's decimal precision
+ *
+ * @example
+ * ```ts
+ * formatDefaultRate(SUPPORTED_CURRENCIES.JPY) // "1" (0 decimals)
+ * formatDefaultRate(SUPPORTED_CURRENCIES.USD) // "1.00" (2 decimals)
+ * formatDefaultRate(SUPPORTED_CURRENCIES.EUR) // "1.00" (2 decimals)
+ * ```
+ */
+export declare function formatDefaultRate(currency: Currency | CurrencyInfo): string;