@provex/utils 1.0.16 → 1.2.3

package/dist/src/tokens.js

@@ -1,6 +1,56 @@
+/**
+ * @fileoverview Token definitions and utilities for supported ERC20 tokens.
+ *
+ * This module defines the supported tokens (currently USDC) on each chain
+ * and provides utilities for token lookups and public client access.
+ *
+ * @remarks
+ * - USDC is the primary token used for escrow deposits
+ * - Each chain has its own USDC contract address
+ * - Base uses native USDC, Pulsechain uses bridged USDC from Ethereum
+ *
+ * @see {@link chain} for chain configuration
+ * @see {@link contracts} for escrow contract addresses
+ */
 import { createPublicClient, getAddress, http } from 'viem';
 import { base, pulsechain } from 'viem/chains';
 import { chains } from './chain.js';
+/**
+ * Pre-configured public clients for supported chains.
+ * Used for read-only blockchain interactions (balances, contract reads).
+ *
+ * @internal
+ */
+const clients = {
+    [base.id]: createPublicClient({
+        chain: base,
+        transport: http(),
+    }),
+    [pulsechain.id]: createPublicClient({
+        chain: pulsechain,
+        transport: http(),
+    }),
+};
+/**
+ * Get a public client for a given chain.
+ * @param chain - The viem chain object
+ * @returns A viem public client instance for the chain
+ * @throws Error if chain is undefined or not configured
+ */
+export const publicClient = (chain) => {
+    if (!chain || !chain.id) {
+        throw new Error('Chain parameter is required and must have an id property');
+    }
+    const client = clients[chain.id];
+    if (!client) {
+        throw new Error(`No client configured for chainId ${chain.id}. Supported chains: ${Object.keys(clients).join(', ')}`);
+    }
+    return client;
+};
+/**
+ * USDC token configuration for Base network.
+ * This is native Circle-issued USDC on Base.
+ */
 const BASE_USDC = {
     address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
     decimals: 6,
@@ -8,6 +58,14 @@ const BASE_USDC = {
     name: 'USD Coin',
     chainId: base.id,
 };
+/**
+ * USDC token configuration for Pulsechain.
+ * This is bridged USDC from Ethereum mainnet.
+ *
+ * @remarks
+ * The mainnetAddress field references the original Ethereum USDC contract,
+ * which can be useful for price oracle lookups and cross-chain verification.
+ */
 export const PULSECHAIN_USDC = {
     address: '0x15D38573d2feeb82e7ad5187aB8c1D52810B1f07',
     decimals: 6,
@@ -16,7 +74,19 @@ export const PULSECHAIN_USDC = {
     chainId: pulsechain.id,
     mainnetAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
 };
-/** All tokens info */
+/**
+ * Registry of all supported tokens organized by chain ID and symbol.
+ * Currently only USDC is supported, but the structure allows for future expansion.
+ *
+ * @example
+ * ```ts
+ * // Get Base USDC
+ * const baseUsdc = allTokensInfo[8453].USDC
+ *
+ * // Get Pulsechain USDC
+ * const pulseUsdc = allTokensInfo[369].USDC
+ * ```
+ */
 export const allTokensInfo = {
     [base.id]: {
         // Base Network Tokens
@@ -94,9 +164,36 @@ export const allTokensInfo = {
     //   mainnetAddress: '0x0000000000000000000000000000000000000000',
     // } as TokenInfo,
 };
+/**
+ * Get the default token (USDC) for a given chain.
+ *
+ * @param chainId - The chain ID, or null to default to Pulsechain
+ * @returns TokenInfo for USDC on the specified chain, or null if chain not supported
+ *
+ * @example
+ * ```ts
+ * const baseUsdc = getDefaultToken(8453)
+ * // { address: '0x833589...', decimals: 6, symbol: 'USDC', ... }
+ * ```
+ */
 export const getDefaultToken = (chainId) => {
     return allTokensInfo[chainId ?? pulsechain.id]?.USDC ?? null;
 };
+/**
+ * Get default tokens (USDC) for multiple chains.
+ *
+ * @param chainIds - Array of chain IDs. If empty, returns tokens for all supported chains.
+ * @returns Array of TokenInfo objects, one per chain
+ *
+ * @example
+ * ```ts
+ * // Get USDC for Base and Pulsechain
+ * const tokens = getDefaultTokens([8453, 369])
+ *
+ * // Get USDC for all supported chains
+ * const allTokens = getDefaultTokens([])
+ * ```
+ */
 export const getDefaultTokens = (chainIds) => {
     return chainIds.length ? chainIds.map((chainId) => getDefaultToken(chainId)) : chains.map((chain) => getDefaultToken(chain.id));
 };
@@ -116,19 +213,3 @@ export const getTokensByChainId = (chainId) => {
 export const tokenByAddress = (chainId, address) => {
     return !address ? null : Object.values(allTokensInfo[chainId] ?? {}).find(token => getAddress(token.address) === getAddress(address)) ?? null;
 };
-/**
- * Create a public client for reading from contracts
- * @param chain - The chain
- * @returns The public client
- */
-export const publicClient = (chain) => createPublicClient({
-    chain,
-    transport: http()
-});
-// export const pulseChainTokenToMainnet = (pulsechainToken: TokenInfo) => {
-//   const tokens = allTokensInfo[mainnet.id]
-//   const token = Object.values(tokens).find((t) => (
-//     getAddress(t.address) === getAddress(pulsechainToken.mainnetAddress!)
-//   ))
-//   return token!
-// }

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

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

package/dist/src/tokens.test.js

@@ -0,0 +1,193 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { base, pulsechain } from 'viem/chains';
+import { publicClient, getDefaultToken, getDefaultTokens, getTokensByChainId, tokenByAddress, allTokensInfo, PULSECHAIN_USDC, } from './tokens.js';
+import { chains, chainIds } from './chain.js';
+describe('tokens', () => {
+    describe('allTokensInfo', () => {
+        it('should have token info for Base', () => {
+            const baseTokens = allTokensInfo[base.id];
+            assert.ok(baseTokens, 'Base tokens should exist');
+            assert.ok(baseTokens.USDC, 'Base should have USDC');
+        });
+        it('should have token info for Pulsechain', () => {
+            const pulseTokens = allTokensInfo[pulsechain.id];
+            assert.ok(pulseTokens, 'Pulsechain tokens should exist');
+            assert.ok(pulseTokens.USDC, 'Pulsechain should have USDC');
+        });
+        it('should have correct USDC address for Base', () => {
+            const baseUSDC = allTokensInfo[base.id].USDC;
+            assert.equal(baseUSDC.address, '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913');
+            assert.equal(baseUSDC.decimals, 6);
+            assert.equal(baseUSDC.symbol, 'USDC');
+            assert.equal(baseUSDC.name, 'USD Coin');
+            assert.equal(baseUSDC.chainId, base.id);
+        });
+        it('should have correct USDC address for Pulsechain', () => {
+            const pulseUSDC = allTokensInfo[pulsechain.id].USDC;
+            assert.equal(pulseUSDC.address, '0x15D38573d2feeb82e7ad5187aB8c1D52810B1f07');
+            assert.equal(pulseUSDC.decimals, 6);
+            assert.equal(pulseUSDC.symbol, 'USDC');
+            assert.equal(pulseUSDC.chainId, pulsechain.id);
+        });
+    });
+    describe('PULSECHAIN_USDC', () => {
+        it('should have mainnetAddress for bridged token', () => {
+            assert.ok(PULSECHAIN_USDC.mainnetAddress, 'Should have mainnet address');
+            assert.equal(PULSECHAIN_USDC.mainnetAddress, '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48');
+        });
+        it('should have correct properties', () => {
+            assert.equal(PULSECHAIN_USDC.address, '0x15D38573d2feeb82e7ad5187aB8c1D52810B1f07');
+            assert.equal(PULSECHAIN_USDC.decimals, 6);
+            assert.equal(PULSECHAIN_USDC.symbol, 'USDC');
+            assert.equal(PULSECHAIN_USDC.name, 'USD Coin from Ethereum');
+            assert.equal(PULSECHAIN_USDC.chainId, pulsechain.id);
+        });
+    });
+    describe('publicClient', () => {
+        it('should return client for Base', () => {
+            const client = publicClient(base);
+            assert.ok(client, 'Client should exist');
+            assert.ok(client.readContract, 'Client should have readContract method');
+        });
+        it('should return client for Pulsechain', () => {
+            const client = publicClient(pulsechain);
+            assert.ok(client, 'Client should exist');
+            assert.ok(client.readContract, 'Client should have readContract method');
+        });
+        it('should throw for undefined chain', () => {
+            assert.throws(() => publicClient(undefined), { message: 'Chain parameter is required and must have an id property' });
+        });
+        it('should throw for chain without id', () => {
+            assert.throws(() => publicClient({}), { message: 'Chain parameter is required and must have an id property' });
+        });
+        it('should throw for unsupported chain', () => {
+            const unsupportedChain = { id: 99999, name: 'Unsupported' };
+            assert.throws(() => publicClient(unsupportedChain), /No client configured for chainId 99999/);
+        });
+    });
+    describe('getDefaultToken', () => {
+        it('should return USDC for Base', () => {
+            const token = getDefaultToken(base.id);
+            assert.ok(token, 'Token should exist');
+            assert.equal(token.symbol, 'USDC');
+            assert.equal(token.chainId, base.id);
+        });
+        it('should return USDC for Pulsechain', () => {
+            const token = getDefaultToken(pulsechain.id);
+            assert.ok(token, 'Token should exist');
+            assert.equal(token.symbol, 'USDC');
+            assert.equal(token.chainId, pulsechain.id);
+        });
+        it('should default to Pulsechain when chainId is null', () => {
+            const token = getDefaultToken(null);
+            assert.ok(token, 'Token should exist');
+            assert.equal(token.chainId, pulsechain.id);
+        });
+        it('should return null for unsupported chain', () => {
+            const token = getDefaultToken(99999);
+            assert.equal(token, null);
+        });
+    });
+    describe('getDefaultTokens', () => {
+        it('should return tokens for specified chains', () => {
+            const tokens = getDefaultTokens([base.id, pulsechain.id]);
+            assert.equal(tokens.length, 2);
+            assert.ok(tokens[0], 'First token should exist');
+            assert.ok(tokens[1], 'Second token should exist');
+            assert.equal(tokens[0].chainId, base.id);
+            assert.equal(tokens[1].chainId, pulsechain.id);
+        });
+        it('should return tokens for all chains when empty array provided', () => {
+            const tokens = getDefaultTokens([]);
+            assert.equal(tokens.length, chains.length);
+        });
+        it('should return tokens in order of chainIds', () => {
+            const tokens = getDefaultTokens([pulsechain.id, base.id]);
+            assert.equal(tokens[0].chainId, pulsechain.id);
+            assert.equal(tokens[1].chainId, base.id);
+        });
+    });
+    describe('getTokensByChainId', () => {
+        it('should return array of tokens for Base', () => {
+            const tokens = getTokensByChainId(base.id);
+            assert.ok(Array.isArray(tokens), 'Should return an array');
+            assert.ok(tokens.length > 0, 'Should have at least one token');
+            assert.ok(tokens.some(t => t.symbol === 'USDC'), 'Should include USDC');
+        });
+        it('should return array of tokens for Pulsechain', () => {
+            const tokens = getTokensByChainId(pulsechain.id);
+            assert.ok(Array.isArray(tokens), 'Should return an array');
+            assert.ok(tokens.length > 0, 'Should have at least one token');
+            assert.ok(tokens.some(t => t.symbol === 'USDC'), 'Should include USDC');
+        });
+        it('should return empty array for unsupported chain', () => {
+            const tokens = getTokensByChainId(99999);
+            assert.ok(Array.isArray(tokens), 'Should return an array');
+            assert.equal(tokens.length, 0);
+        });
+    });
+    describe('tokenByAddress', () => {
+        it('should find Base USDC by address', () => {
+            const address = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+            const token = tokenByAddress(base.id, address);
+            assert.ok(token, 'Token should be found');
+            assert.equal(token.symbol, 'USDC');
+            assert.equal(token.chainId, base.id);
+        });
+        it('should find Pulsechain USDC by address', () => {
+            const address = '0x15D38573d2feeb82e7ad5187aB8c1D52810B1f07';
+            const token = tokenByAddress(pulsechain.id, address);
+            assert.ok(token, 'Token should be found');
+            assert.equal(token.symbol, 'USDC');
+            assert.equal(token.chainId, pulsechain.id);
+        });
+        it('should be case-insensitive for address lookup', () => {
+            const lowerAddress = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913';
+            const upperAddress = '0x833589FCD6EDB6E08F4C7C32D4F71B54BDA02913';
+            const tokenLower = tokenByAddress(base.id, lowerAddress);
+            const tokenUpper = tokenByAddress(base.id, upperAddress);
+            assert.ok(tokenLower, 'Should find token with lowercase address');
+            assert.ok(tokenUpper, 'Should find token with uppercase address');
+            assert.deepEqual(tokenLower, tokenUpper);
+        });
+        it('should return null for undefined address', () => {
+            const token = tokenByAddress(base.id, undefined);
+            assert.equal(token, null);
+        });
+        it('should return null for non-existent address', () => {
+            const token = tokenByAddress(base.id, '0x0000000000000000000000000000000000000001');
+            assert.equal(token, null);
+        });
+        it('should return null for unsupported chain', () => {
+            const token = tokenByAddress(99999, '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913');
+            assert.equal(token, null);
+        });
+    });
+    describe('TokenInfo interface', () => {
+        it('all tokens have required properties', () => {
+            for (const chainId of chainIds) {
+                const chainTokens = allTokensInfo[chainId];
+                if (!chainTokens)
+                    continue;
+                for (const [symbol, token] of Object.entries(chainTokens)) {
+                    assert.ok(token.address, `${symbol} should have address`);
+                    assert.ok(typeof token.decimals === 'number', `${symbol} should have decimals`);
+                    assert.ok(token.symbol, `${symbol} should have symbol`);
+                    assert.ok(token.name, `${symbol} should have name`);
+                    assert.ok(token.chainId, `${symbol} should have chainId`);
+                }
+            }
+        });
+        it('all token addresses are valid ethereum addresses', () => {
+            for (const chainId of chainIds) {
+                const chainTokens = allTokensInfo[chainId];
+                if (!chainTokens)
+                    continue;
+                for (const [symbol, token] of Object.entries(chainTokens)) {
+                    assert.match(token.address, /^0x[a-fA-F0-9]{40}$/, `${symbol} address should be valid`);
+                }
+            }
+        });
+    });
+});

package/dist/src/units.d.ts

@@ -1,17 +1,200 @@
+/**
+ * @fileoverview Unit conversion and formatting utilities for token amounts.
+ *
+ * This module provides utilities for converting between human-readable amounts
+ * and blockchain-native bigint values, with support for:
+ * - Decimal precision (6 for USDC, 18 for ETH)
+ * - Thousands separators for display
+ * - Truncation and padding options
+ * - Number abbreviation (k, M, B, T)
+ *
+ * @remarks
+ * All amounts in smart contracts are stored as bigints without decimals.
+ * For example, 100 USDC = 100_000000n (6 decimals).
+ *
+ * @see {@link tokens} for token decimal configurations
+ * @see {@link currencies} for fiat currency decimals
+ */
 import type { TokenInfo } from './tokens.js';
+/**
+ * Constant representing 1 ether in wei (10^18).
+ * Used for 18-decimal precision calculations.
+ */
 export declare const oneEther: bigint;
+/**
+ * Add thousands separators to a number string for improved readability.
+ *
+ * @param numberString - The number string to format
+ * @param delimiter - The separator character (default: ',')
+ * @returns Formatted string with separators
+ *
+ * @example
+ * ```ts
+ * addThousandsSeparator('1234567.89')    // '1,234,567.89'
+ * addThousandsSeparator('1000', ' ')     // '1 000'
+ * ```
+ */
 export declare function addThousandsSeparator(numberString: string, delimiter?: string): string;
+/**
+ * Options for formatting bigint amounts as human-readable strings.
+ */
 export interface FormatRateDisplayOptions {
+    /** Number of decimal places in the bigint (e.g., 6 for USDC, 18 for ETH) */
     decimals: number;
+    /** Maximum decimal places to show (truncates excess precision) */
     truncateDecimals?: number;
+    /** Minimum decimal places to show (pads with zeros) */
     padDecimals?: number;
+    /** If amount is below this, display as "<cutoff" (e.g., "<0.01") */
     cutoff?: bigint;
+    /** Thousands separator character (default: ',') */
     delimiter?: string;
+    /** Whether to round up instead of truncating (default: false) */
     roundUp?: boolean;
 }
+/**
+ * Parse a human-readable amount string into a bigint.
+ * Handles thousands separators and decimal places.
+ *
+ * @param amount - Human-readable amount (e.g., '1,234.56')
+ * @param options - Parsing options with decimals and optional delimiter
+ * @returns BigInt representation of the amount
+ *
+ * @example
+ * ```ts
+ * // Parse USDC amount (6 decimals)
+ * parseUnits('100.50', { decimals: 6 })  // 100_500000n
+ *
+ * // Parse with thousands separator
+ * parseUnits('1,234.56', { decimals: 6 })  // 1_234_560000n
+ * ```
+ */
 export declare const parseUnits: (amount: string, options: Pick<FormatRateDisplayOptions, "decimals" | "delimiter">) => bigint;
+/**
+ * Format a bigint amount as a human-readable string with configurable precision.
+ *
+ * @param amount - BigInt amount to format
+ * @param options - Formatting options
+ * @returns Formatted string with decimal point and thousands separators
+ *
+ * @example
+ * ```ts
+ * // Basic formatting
+ * formatUnits(100_500000n, { decimals: 6, padDecimals: 2 })  // '100.50'
+ *
+ * // With truncation
+ * formatUnits(100_123456n, { decimals: 6, truncateDecimals: 2 })  // '100.12'
+ *
+ * // With cutoff for small amounts
+ * formatUnits(100n, { decimals: 6, cutoff: 1000n })  // '<0.001'
+ * ```
+ */
 export declare function formatUnits(amount: bigint, options: FormatRateDisplayOptions): string;
+/**
+ * Format a token amount for display with 2 decimal places.
+ * Convenience wrapper around formatUnits with truncateDecimals: 2.
+ *
+ * @param amount - BigInt amount to format
+ * @param options - Formatting options (truncateDecimals defaults to 2)
+ * @returns Formatted string with 2 decimal places
+ */
 export declare function formatTokenAmountForDisplay(amount: bigint, options: FormatRateDisplayOptions): string;
+/**
+ * Safely parse a string to an integer without using Number() constructor.
+ * Uses parseInt which is more predictable for integer-only parsing.
+ *
+ * @param value - String value to parse
+ * @returns Parsed integer or null if invalid
+ *
+ * @example
+ * ```ts
+ * parseIntegerSafe('123')     // 123
+ * parseIntegerSafe('123.45')  // 123 (truncates decimal)
+ * parseIntegerSafe('abc')     // null
+ * ```
+ */
 export declare function parseIntegerSafe(value: string): number | null;
+/**
+ * Convert a blockchain timestamp (Unix seconds) to a JavaScript Date object.
+ *
+ * @param timestamp - Unix timestamp in seconds (string, number, or bigint)
+ * @returns Date object, or null if timestamp is falsy
+ *
+ * @example
+ * ```ts
+ * timestampToDate(1704067200)      // Date: 2024-01-01T00:00:00.000Z
+ * timestampToDate('1704067200')    // Date: 2024-01-01T00:00:00.000Z
+ * timestampToDate(1704067200n)     // Date: 2024-01-01T00:00:00.000Z
+ * timestampToDate(null)            // null
+ * ```
+ */
 export declare function timestampToDate(timestamp: string | number | bigint | undefined | null): Date | null;
+/**
+ * Format a token amount using the token's decimal configuration.
+ *
+ * @param token - Token info with decimals
+ * @param amount - BigInt amount to format, or null
+ * @param options - Optional formatting overrides
+ * @returns Formatted string, or null if amount is null
+ *
+ * @example
+ * ```ts
+ * const usdc = { decimals: 6, ... }
+ * formatAmount(usdc, 100_500000n)  // '100.50'
+ * formatAmount(usdc, null)         // null
+ * ```
+ */
 export declare const formatAmount: (token: TokenInfo, amount: bigint | null, options?: Partial<FormatRateDisplayOptions>) => string | null;
+/**
+ * Numeric abbreviation suffixes and their divisors.
+ * Used by abbreviateNumber() for compact number display.
+ */
+export declare const numericAbbreviations: readonly [{
+    readonly divisor: 1000000000000n;
+    readonly suffix: "T";
+}, {
+    readonly divisor: 1000000000n;
+    readonly suffix: "B";
+}, {
+    readonly divisor: 1000000n;
+    readonly suffix: "M";
+}, {
+    readonly divisor: 1000n;
+    readonly suffix: "k";
+}];
+/**
+ * Formats a bigint value with a specific numeric abbreviation suffix
+ * @param value - The bigint value to format
+ * @param options - Configuration for formatting
+ * @returns Formatted string with suffix (e.g., "1.23k", "400M")
+ *
+ * @example
+ * formatWithAbbreviation(1234567n, { decimals: 2, divisor: 1_000n, suffix: 'k' }) // "1234.57k"
+ * formatWithAbbreviation(400000000n, { decimals: 2, divisor: 1_000_000n, suffix: 'M' }) // "400M"
+ */
+export declare function formatWithAbbreviation(value: bigint, options: {
+    decimals: number;
+    divisor: bigint;
+    suffix: string;
+    maxDecimals?: number;
+    /** Minimum decimal places to show — prevents auto-reduction for large values. */
+    minDecimals?: number;
+}): string;
+/**
+ * Abbreviates large numbers using k, M, B, T suffixes
+ * @param value - The bigint value to abbreviate
+ * @param options - Optional configuration for decimal places and decimals precision
+ * @returns Abbreviated number string (e.g., "1.5k", "200k", "1.2M")
+ *
+ * @example
+ * abbreviateNumber(1500n, { decimals: 0 }) // "1.5k"
+ * abbreviateNumber(200000n, { decimals: 0 }) // "200k"
+ * abbreviateNumber(1234567n, { decimals: 0 }) // "1.23M"
+ * abbreviateNumber(1000000000n, { decimals: 0 }) // "1B"
+ * abbreviateNumber(123456n, { decimals: 2 }) // "1.23k" (if input is 1234.56 with 2 decimals)
+ */
+export declare function abbreviateNumber(value: bigint, options: {
+    decimals: number;
+    maxDecimals?: number;
+    minDecimals?: number;
+}): string;