@provex/utils 1.0.16 → 1.2.4

package/dist/currencies.d.ts

@@ -0,0 +1,248 @@
+/**
+ * @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';
+/**
+ * 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
+ */
+export interface CountryInfo {
+    code: string;
+    name: string;
+    country: string;
+    countryCode: string;
+    flag?: string;
+}
+/**
+ * Convert a ticker to a contract ID
+ * @param ticker - The ticker to convert
+ * @returns The contract ID
+ */
+export declare const tickerToContractId: (ticker: string) => Hex;
+/**
+ * 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;
+    readonly symbol: string;
+    readonly name: string;
+    readonly decimals: number;
+    readonly contractId: Hex;
+    readonly 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
+     */
+    private generateContractId;
+    /**
+     * Parse an amount to a bigint
+     * @param amount - The amount to parse
+     * @returns The amount as a bigint
+     */
+    parseAmount(amount: string): bigint | null;
+    /**
+     * Format an amount to a string
+     * @param amount - The amount to format
+     * @returns The amount as a string
+     */
+    formatAmount(amount: bigint | null, options?: Partial<FormatRateDisplayOptions>): string | null;
+    /**
+     * Convert to plain object for compatibility
+     * @returns The currency info
+     */
+    toJSON(): CurrencyInfo;
+}
+/**
+ * Generate contract ID for a currency code (standalone function for backward compatibility)
+ * @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;
+    readonly GBP: Currency;
+    readonly AUD: Currency;
+    readonly CAD: Currency;
+    readonly NZD: Currency;
+    readonly CHF: Currency;
+    readonly SEK: Currency;
+    readonly NOK: Currency;
+    readonly DKK: Currency;
+    readonly PLN: Currency;
+    readonly CZK: Currency;
+    readonly ARS: Currency;
+    readonly CNY: Currency;
+    readonly MXN: Currency;
+    readonly JPY: Currency;
+    readonly THB: Currency;
+    readonly RUB: Currency;
+    readonly AED: Currency;
+    readonly ZAR: Currency;
+    readonly HKD: Currency;
+    readonly SGD: Currency;
+    readonly SAR: Currency;
+    readonly ILS: Currency;
+    readonly IDR: Currency;
+    readonly MYR: Currency;
+    readonly PHP: Currency;
+    readonly VND: Currency;
+    readonly KRW: Currency;
+    readonly INR: Currency;
+    readonly BRL: Currency;
+    readonly KES: Currency;
+    readonly TRY: Currency;
+    readonly UGX: Currency;
+    readonly RON: Currency;
+    readonly HUF: Currency;
+};
+/**
+ * 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
+ * @returns The currency info
+ */
+export declare function getCurrencyInfo(currencyCode: string): CurrencyInfo | null;
+/**
+ * Get the currency info for a contract ID
+ * @param contractId - The contract ID
+ * @returns The currency info
+ */
+export declare function getCurrencyByContractId(contractId: string): Currency | null;
+/**
+ * Format a currency amount
+ * @param amount - The amount to format
+ * @param currencyCode - The currency code
+ * @returns The formatted currency amount
+ */
+export declare function formatCurrencyAmount(amount: string | number, currencyCode: string): string;
+/**
+ * Get all supported currencies
+ * @returns All supported currencies
+ */
+export declare function getAllSupportedCurrencies(): CurrencyInfo[];
+/**
+ * Check if a currency is supported
+ * @param currencyCode - The currency code
+ * @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;

package/dist/{src/currencies.js → currencies.js}

@@ -1,9 +1,24 @@
+/**
+ * @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 { isHash, keccak256, toBytes } from 'viem';
 import { addThousandsSeparator, formatUnits, parseUnits } from './units.js';
 import countriesData from './data/countries.json' with { type: 'json' };
 import { USD_FLAG_SVG, EUR_FLAG_SVG } from './flags.js';
-// Convert SVG strings to data URLs
+/** Pre-computed data URL for USD flag (custom square design) */
 const USD_FLAG_DATA_URL = `data:image/svg+xml;base64,${btoa(USD_FLAG_SVG)}`;
+/** Pre-computed data URL for EUR flag (custom square design) */
 const EUR_FLAG_DATA_URL = `data:image/svg+xml;base64,${btoa(EUR_FLAG_SVG)}`;
 const countries = countriesData;
 /**
@@ -15,12 +30,20 @@ export const tickerToContractId = (ticker) => {
     return keccak256(toBytes(ticker.toUpperCase()));
 };
 /**
- * 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 class Currency {
     ticker;
@@ -29,12 +52,24 @@ export class Currency {
     decimals;
     contractId;
     flag;
-    constructor(code, symbol, name, decimals, flag) {
+    zoom;
+    /**
+     * 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, symbol, name, decimals, flag, zoom) {
         this.ticker = code.toUpperCase();
         this.symbol = symbol;
         this.name = name;
         this.decimals = decimals;
-        this.flag = flag || ''; // figure out a fallback flag
+        this.flag = flag || '';
+        this.zoom = zoom ?? 1.5;
         this.contractId = this.generateContractId();
     }
     /**
@@ -64,21 +99,9 @@ export class Currency {
      * @returns The amount as a string
      */
     formatAmount(amount, options = {}) {
-        try {
-            if (amount === null) {
-                return null;
-            }
-            return formatUnits(amount, {
-                decimals: this.decimals,
-                truncateDecimals: 2,
-                padDecimals: 2,
-                ...options,
-            });
-        }
-        catch (err) {
-            console.error('Error formatting amount: %o', amount, err);
+        if (amount === null)
             return null;
-        }
+        return formatUnits(amount, { decimals: this.decimals, truncateDecimals: 2, padDecimals: 2, ...options });
     }
     /**
      * Convert to plain object for compatibility
@@ -92,6 +115,7 @@ export class Currency {
             decimals: this.decimals,
             contractId: this.contractId,
             flag: this.flag,
+            zoom: this.zoom,
         };
     }
 }
@@ -109,13 +133,35 @@ export function generateCurrencyId(currencyCode) {
  * @returns The flag image path
  */
 const flagFromCountries = (countryCode) => {
-    const country = countries.find((country) => country.code === countryCode);
-    return country?.flag || '';
+    return countries.find((country) => country.code === countryCode)?.flag ?? '';
 };
-// Supported fiat currencies with local flag files for major ones
+/**
+ * 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 const SUPPORTED_CURRENCIES = {
-    USD: new Currency('USD', '$', 'US Dollar', 2, USD_FLAG_DATA_URL),
-    EUR: new Currency('EUR', '€', 'Euro', 2, EUR_FLAG_DATA_URL),
+    USD: new Currency('USD', '$', 'US Dollar', 2, USD_FLAG_DATA_URL, 1),
+    EUR: new Currency('EUR', '€', 'Euro', 2, EUR_FLAG_DATA_URL, 1),
     GBP: new Currency('GBP', '£', 'British Pound', 2, flagFromCountries('GBP')),
     AUD: new Currency('AUD', 'A$', 'Australian Dollar', 2, flagFromCountries('AUD')),
     CAD: new Currency('CAD', 'C$', 'Canadian Dollar', 2, flagFromCountries('CAD')),
@@ -151,17 +197,33 @@ export const SUPPORTED_CURRENCIES = {
     RON: new Currency('RON', 'RON', 'Romanian Leu', 2, flagFromCountries('RON')),
     HUF: new Currency('HUF', 'Ft', 'Hungarian Forint', 2, flagFromCountries('HUF')),
 };
-/** Entries for the supported currencies */
+/** Sorted entries for consistent iteration order */
 const entries = Object.entries(SUPPORTED_CURRENCIES).sort(([a], [b]) => a.localeCompare(b));
-entries.forEach(([, currency]) => {
-    // console.log(currency.ticker, currency.contractId)
-    if (!currency.flag) {
-        console.error(`missing flag for ${currency.ticker}`);
-    }
-});
+/**
+ * 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 const currencyById = new Map(entries.map(([, currency]) => {
     return [currency.contractId, 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 function getCurrencyNameByContractId(contractId) {
+    const currency = currencyById.get(contractId);
+    return currency?.ticker ?? contractId;
+}
 /**
  * Get the currency info for a currency code
  * @param currencyCode - The currency code
@@ -169,7 +231,7 @@ export const currencyById = new Map(entries.map(([, currency]) => {
  */
 export function getCurrencyInfo(currencyCode) {
     const currency = SUPPORTED_CURRENCIES[currencyCode.toUpperCase()];
-    return currency ? currency.toJSON() : null;
+    return currency?.toJSON() ?? null;
 }
 /**
  * Get the currency info for a contract ID
@@ -180,8 +242,7 @@ export function getCurrencyByContractId(contractId) {
     if (!isHash(contractId)) {
         throw new Error('Invalid contract ID');
     }
-    const currency = currencyById.get(contractId);
-    return currency ? currency : null;
+    return currencyById.get(contractId) ?? null;
 }
 /**
  * Format currency amount safely without Number() constructor, preserving decimal places
@@ -232,3 +293,23 @@ export function getAllSupportedCurrencies() {
 export function isSupportedCurrency(currencyCode) {
     return currencyCode.toUpperCase() in SUPPORTED_CURRENCIES;
 }
+/**
+ * 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 function formatDefaultRate(currency) {
+    if (currency.decimals === 0)
+        return '1';
+    return `1.${'0'.repeat(currency.decimals)}`;
+}