@liberfi.io/utils 0.2.27 → 0.2.29

package/dist/index.d.mts

@@ -140,118 +140,195 @@ declare class SafeBigNumber extends BigNumber {
  */
 declare const isValidNumber: (num: unknown) => boolean;
 type FormatAmountOptions = {
-    showPlusGtThanZero: boolean;
+    showPlusGtThanZero?: boolean;
 };
 /**
  * Format a raw token / asset amount (no currency symbol).
  *
- * Precision tiers (ROUND_DOWN):
- * | Range         | Format                  | Example input → output       |
- * |---------------|-------------------------|------------------------------|
- * | < 0.001       | 5 decimal places        | 0.0001234  → "0.00012"       |
- * | < 1           | 3 decimal places        | 0.56789    → "0.567"         |
- * | < 100         | 2 decimal places        | 42.678     → "42.67"         |
- * | < 100 000     | grouped, 2 dp           | 12345.6    → "12,345.60"     |
- * | ≥ 100 000     | abbreviated (K/M/B/T)   | 1_500_000  → "1.5M"          |
+ * Use cases:
+ * - Activity-list quantity column from `base_amount`.
+ * - Activity-list total in native token mode before the UI appends a symbol.
+ * - Holder, trader, transaction, and token balance counts where compact
+ *   K/M/B/T output is acceptable.
+ *
+ * Examples:
+ * - `41.8701` -> `"41.87"`
+ * - `1.087` -> `"1.087"`
+ * - `0.000032564` -> `"0.0₄3256"`
+ * - `12345.6` -> `"12.3K"`
+ * - `2089491826.331852` -> `"2.08B"`
  *
  * @param num - The numeric value.
  * @param options.showPlusGtThanZero - Prefix positive values with "+".
  */
 declare const formatAmount: (num?: BigNumber.Value, options?: FormatAmountOptions) => string;
 /**
- * Format a USD dollar amount with "$" prefix (standard precision).
+ * Format an amount with "$" prefix.
  *
- * Precision tiers (ROUND_DOWN):
- * | Range         | Format                  | Example input → output       |
- * |---------------|-------------------------|------------------------------|
- * | < 0.001       | "$0"                    | 0.00001    → "$0"            |
- * | < 1           | 3 decimal places        | 0.56789    → "$0.567"        |
- * | < 100         | 2 decimal places        | 42.678     → "$42.67"        |
- * | < 10 000      | grouped, 2 dp           | 1234.5     → "$1,234.50"     |
- * | ≥ 10 000      | abbreviated (K/M/B/T)   | 1_500_000  → "$1.5M"         |
+ * Use cases:
+ * - Activity-list total in USD mode from `amount_usd`.
+ * - USD notional amount displays where the numeric body should match
+ *   `formatSignificantCompactNumber`.
+ * - Compact USD volume / liquidity text when 4 significant digits are enough.
  *
- * Use this for standard financial displays (volume, market cap, liquidity).
+ * Examples:
+ * - `96.32167791184` -> `"$96.32"`
+ * - `0.000032564` -> `"$0.0₄3256"`
+ * - `12345.6` -> `"$12.3K"`
+ * - `2089491826.331852` -> `"$2.08B"`
+ * - `-42.678` -> `"-$42.67"`
  *
  * @param num - The numeric value.
  * @param options.showPlusGtThanZero - Prefix positive values with "+".
  */
-declare const formatAmountUSD: (num?: BigNumber.Value, options?: FormatAmountOptions) => string;
+declare const formatAmountInUsd: (num?: BigNumber.Value, options?: FormatAmountOptions) => string;
+type FormatDecimalCompactNumberOptions = {
+    /** Prefix to prepend after sign handling. Use "$" for USD displays. */
+    prefix?: string;
+    /** Abbreviate values >= 1_000 with K/M/B/T suffixes. Default: true. */
+    short?: boolean;
+    /**
+     * Decimal precision after scaling. This is the practical equivalent of the
+     * GMGN `$num` call sites that pass explicit formatting options.
+     */
+    precision?: number;
+    /**
+     * Minimum decimal places when `pad` is true. For example, GMGN token prices
+     * pass `pad: true` and use 3 decimals for values > 1.
+     */
+    minPrecision?: number;
+    /** Keep trailing zeros up to `max(precision, minPrecision)`. */
+    pad?: boolean;
+    /** String returned when the input is invalid. */
+    invalidPlaceholder?: string;
+    /** BigNumber rounding mode. GMGN display numbers truncate by default. */
+    rounding?: BigNumber.RoundingMode;
+};
 /**
- * Format a raw token / asset amount (no currency symbol) — **compact** variant.
- *
- * Same tier ladder as {@link formatAmountUSDCompact} but without the `"$"`
- * prefix. Suited for space-constrained UIs that need to render an amount
- * alongside a token symbol (e.g. `"15K SOL"`) inside narrow buttons or
- * badges.
- *
- * | Range         | Format                  | Example input → output       |
- * |---------------|-------------------------|------------------------------|
- * | < 0.001       | "0"                     | 0.00001    → "0"             |
- * | < 1           | 3 decimal places        | 0.56789    → "0.567"         |
- * | < 100         | 2 decimal places        | 42.678     → "42.67"         |
- * | < 1 000       | 0 decimal places        | 567.89     → "567"           |
- * | ≥ 1 000       | abbreviated, 0 dp,      | 15 678     → "15K"           |
- * |               | rounded to nearest 100  | 1 234 567  → "1M"            |
- *
- * @param num - The numeric value.
- * @param options.showPlusGtThanZero - Prefix positive values with "+".
+ * Format numbers with the GMGN `$num`-style display rules.
+ *
+ * This is the configurable formatter behind GMGN's token price and activity
+ * price / market-cap displays:
+ *
+ * | GMGN field / scenario                 | Call pattern                                                           | Example output |
+ * |---------------------------------------|------------------------------------------------------------------------|----------------|
+ * | Token header price                    | `formatDecimalCompactNumber(price, { prefix: "$", precision: 3, pad: true })` | `"$2.089"`     |
+ * | Activity price column in price mode   | `formatDecimalCompactNumber(price, { prefix: "$", precision: 3, pad: true })` | `"$2.092"`     |
+ * | Activity price column in market-cap mode | `formatDecimalCompactNumber(price * totalSupply, { prefix: "$", precision: 2 })` | `"$2.09B"`     |
+ * | Basic metric market cap               | `formatDecimalCompactNumber(marketCap, { prefix: "$", precision: 2 })`       | `"$2.08B"`     |
+ * | Tiny token price                      | `formatDecimalCompactNumber(0.00003, { prefix: "$" })`                       | `"$0.0₄3"`     |
+ *
+ * Notes:
+ * - Values are truncated by default, matching the observed GMGN production
+ *   bundle behavior.
+ * - `short` defaults to true and applies K/M/B/T after scaling.
+ * - For market-cap displays, callers should multiply `price * totalSupply`
+ *   before calling this function; this keeps the formatter single-purpose.
  */
-declare const formatAmountCompact: (num?: BigNumber.Value, options?: FormatAmountOptions) => string;
+declare const formatDecimalCompactNumber: (num?: BigNumber.Value, options?: FormatDecimalCompactNumberOptions) => string;
 /**
- * Format a USD dollar amount with "$" prefix — **compact** variant.
- *
- * Compared to {@link formatAmountUSD}, this variant is more aggressively
- * rounded and suited for space-constrained UIs (cards, badges, list items):
- *
- * | Range         | Format                  | Example input → output       |
- * |---------------|-------------------------|------------------------------|
- * | < 0.001       | "$0"                    | 0.00001    → "$0"            |
- * | < 1           | 3 decimal places        | 0.56789    → "$0.567"        |
- * | < 100         | 2 decimal places        | 42.678     → "$42.67"        |
- * | < 1 000       | 0 decimal places        | 567.89     → "$567"          |
- * | ≥ 1 000       | abbreviated, 0 dp,      | 15 678     → "$15.6K"        |
- * |               | rounded to nearest 100  | 1 234 567  → "$1.2M"         |
- *
- * Key differences from `formatAmountUSD`:
- * - 100–1 000: shows 0 dp instead of 2 dp
- * - ≥ 1 000: abbreviates earlier (1K vs 10K) with 0 precision, rounded to 100s
- *
- * @param num - The numeric value.
- * @param options.showPlusGtThanZero - Prefix positive values with "+".
+ * Format a non-negative token price without a currency symbol.
+ *
+ * Use cases:
+ * - Token price text when the surrounding UI already renders the currency.
+ * - Activity-list price mode when the column header or cell chrome supplies
+ *   the unit separately.
+ * - Token rows where values should match the GMGN-style 3-decimal padded
+ *   price display and compact K/M/B/T behavior.
+ *
+ * Examples:
+ * - `2.089` -> `"2.089"`
+ * - `2.1` -> `"2.100"`
+ * - `0.00003` -> `"0.0₄3"`
+ * - `1234.567` -> `"1.234K"`
  */
-declare const formatAmountUSDCompact: (num?: BigNumber.Value, options?: FormatAmountOptions) => string;
-type FormatPriceOptions = {
-    isHighPrecise: boolean;
-};
+declare const formatPrice: (num?: BigNumber.Value) => string;
 /**
- * Format a token price (no currency symbol). Negative inputs render as `"--"`.
- *
- * Same precision tiers as {@link formatPriceUSD} but without the "$" prefix.
- *
- * @param num - The price value.
- * @param options.isHighPrecise - Use high-precision mode (default: true).
+ * Format a non-negative token price with a "$" prefix.
+ *
+ * Use cases:
+ * - Token header price in USD.
+ * - Activity-list price column in price mode.
+ * - Any USD price display that should keep exactly 3 decimals after the
+ *   scaled value, except zero and subscript-zero tiny values.
+ *
+ * Examples:
+ * - `2.089` -> `"$2.089"`
+ * - `2.1` -> `"$2.100"`
+ * - `0.00003` -> `"$0.0₄3"`
+ * - `1234.567` -> `"$1.234K"`
  */
-declare const formatPrice: (num?: BigNumber.Value, options?: FormatPriceOptions) => string;
+declare const formatPriceInUsd: (num?: BigNumber.Value) => string;
+/**
+ * Format a non-negative market-cap or fully diluted valuation number without a
+ * currency symbol.
+ *
+ * Use cases:
+ * - Market-cap column text when the surrounding UI already renders the unit.
+ * - Activity-list price column in market-cap mode after the caller multiplies
+ *   `price * totalSupply`.
+ * - Metrics that should use compact K/M/B/T notation with 2 decimal places.
+ *
+ * Examples:
+ * - `2089491826.331852` -> `"2.08B"`
+ * - `2092491826.331852` -> `"2.09B"`
+ * - `1234567` -> `"1.23M"`
+ * - `999.999` -> `"999.99"`
+ */
+declare const formatMCap: (num?: BigNumber.Value) => string;
+/**
+ * Format a non-negative market-cap or fully diluted valuation number with a
+ * "$" prefix.
+ *
+ * Use cases:
+ * - Token header market-cap / FDV metrics.
+ * - Activity-list price column in market-cap mode.
+ * - USD market-cap displays that should compact large values with K/M/B/T.
+ *
+ * Examples:
+ * - `2089491826.331852` -> `"$2.08B"`
+ * - `2092491826.331852` -> `"$2.09B"`
+ * - `1234567` -> `"$1.23M"`
+ * - `999.999` -> `"$999.99"`
+ */
+declare const formatMCapInUsd: (num?: BigNumber.Value) => string;
+type FormatSignificantCompactNumberOptions = {
+    /** Abbreviate values >= 1_000 with K/M/B/T suffixes. Default: true. */
+    short?: boolean;
+    /**
+     * Number of significant digits retained before truncation. GMGN's activity
+     * amount formatter uses 4 significant digits for normal values and 3 after
+     * K/M/B/T scaling.
+     */
+    significantDigits?: number;
+    /** String returned when the input is invalid. */
+    invalidPlaceholder?: string;
+};
 /**
- * Format a token price with "$" prefix. Negative inputs render as `"--"`.
- *
- * Two precision modes controlled by `isHighPrecise` (default: `true`):
- *
- * | Range         | High precision (default)       | Low precision                |
- * |---------------|-------------------------------|------------------------------|
- * | < 0.0001      | subscript notation, 4 sig     | subscript notation, 2 sig    |
- * |               | 0.0000382 → "$0.0₄382"        | 0.0000382 → "$0.0₄38"       |
- * | < 1           | 4 dp, grouped                 | 2 significant dp             |
- * |               | 0.12345 → "$0.1234"           | 0.12345 → "$0.12"           |
- * | < 10 000      | 4 dp, grouped                 | 2 dp, grouped                |
- * |               | 1234.567 → "$1,234.5670"      | 1234.567 → "$1,234.56"      |
- * | < 100 000     | 2 dp, grouped                 | 2 dp, grouped                |
- * | ≥ 100 000     | abbreviated (K/M/B/T)         | abbreviated (K/M/B/T)        |
- *
- * @param num - The price value.
- * @param options.isHighPrecise - Use high-precision mode (default: true).
+ * Format numbers with the GMGN `ej`-style activity amount rules.
+ *
+ * This is the formatter GMGN uses for activity-list amount-like cells:
+ *
+ * | GMGN field / scenario             | Source value                                     | Call pattern                       | Example output |
+ * |-----------------------------------|--------------------------------------------------|------------------------------------|----------------|
+ * | Activity quantity column          | `record.base_amount`                             | `formatSignificantCompactNumber(value)`  | `"41.87"`      |
+ * | Activity quantity in mempool buy  | `record.amount_out`                              | `formatSignificantCompactNumber(value)`  | token amount   |
+ * | Activity quantity in mempool sell | `record.amount_in`                               | `formatSignificantCompactNumber(value)`  | token amount   |
+ * | Activity total in SOL/native mode | native quote `record.quote_amount`               | `formatSignificantCompactNumber(value)`  | `"1.087"`      |
+ * | Activity total in USD mode        | `record.amount_usd`, then prepend `"$"` in UI    | `formatSignificantCompactNumber(value)`  | `"96.32"`      |
+ * | Activity total via non-native quote | `record.amount_usd / nativeTokenUsdPrice`      | `formatSignificantCompactNumber(value)`  | native amount  |
+ * | Tiny gas/native amount            | native amount below 0.0001                       | `formatSignificantCompactNumber(value)`  | `"0.0₄3"`      |
+ * | Large notional value              | any amount >= 1_000                              | `formatSignificantCompactNumber(value)`  | `"2.08B"`      |
+ *
+ * Notes:
+ * - The function returns the numeric text only. Add `$`, token symbols, SOL,
+ *   or other unit labels at the call site.
+ * - Values are truncated, not rounded, matching the observed GMGN bundle.
+ * - GMGN's separate gas column often uses a threshold display such as
+ *   `"<0.0001"`; use this function when you want the `ej` amount behavior,
+ *   and add threshold handling outside when the UI contract requires it.
  */
-declare const formatPriceUSD: (num?: BigNumber.Value, options?: FormatPriceOptions) => string;
+declare const formatSignificantCompactNumber: (num?: BigNumber.Value, options?: FormatSignificantCompactNumberOptions) => string;
 type FormatPercentOptions = {
     showPlusGtThanZero?: boolean;
     precision?: number;
@@ -378,4 +455,4 @@ declare function groupBy<T>(array: T[], iteratee: Iteratee<T, string>): Record<s
 declare function mapKeys<T>(obj: Record<string, T>, iteratee: (value: T, key: string) => string): Record<string, T>;
 declare function mapValues<T, R>(obj: Record<string, T>, iteratee: (value: T, key: string) => R): Record<string, R>;
 
-export { ARBITRUM_TOKENS, AVALANCHE_TOKENS, ApiError, BSC_TOKENS, CHAIN_REGISTRY, CHAIN_TOKENS, type ChainMetadata, type ChainPredefinedTokens, ETHEREUM_TOKENS, type FormatAgeOptions, type FormatAmountOptions, type FormatPercentOptions, type FormatPriceOptions, OPTIMISM_TOKENS, type PredefinedToken, SOLANA_TOKENS, SafeBigNumber, accountExplorerUrl, capitalize, chainColor, chainDisplayName, chainIcon, chainIdBySlug, chainSlug, chainToNamespace, debounce, formatAge, formatAgeInSeconds, formatAmount, formatAmountCompact, formatAmountUSD, formatAmountUSDCompact, formatPercent, formatPrice, formatPriceUSD, formatSymbol, formatTokenProtocolName, getCommonTokenAddresses, getCommonTokenSymbolsMap, getNativeToken, getStablecoins, getWrappedToken, groupBy, httpDelete, httpGet, httpMutate, httpPost, httpPut, httpRequest, intersectionBy, isBinanceChain, isEthereumChain, isSolanaChain, isValidEvmAddress, isValidNumber, isValidSolanaAddress, isValidWalletAddress, keyBy, mapKeys, mapValues, parseTokenProtocolFamily, searchImageUrl, searchTwitterUrl, throttle, truncateAddress, twitterTweetUrl, twitterUserUrl, txExplorerUrl, uniqBy };
+export { ARBITRUM_TOKENS, AVALANCHE_TOKENS, ApiError, BSC_TOKENS, CHAIN_REGISTRY, CHAIN_TOKENS, type ChainMetadata, type ChainPredefinedTokens, ETHEREUM_TOKENS, type FormatAgeOptions, type FormatAmountOptions, type FormatDecimalCompactNumberOptions, type FormatPercentOptions, type FormatSignificantCompactNumberOptions, OPTIMISM_TOKENS, type PredefinedToken, SOLANA_TOKENS, SafeBigNumber, accountExplorerUrl, capitalize, chainColor, chainDisplayName, chainIcon, chainIdBySlug, chainSlug, chainToNamespace, debounce, formatAge, formatAgeInSeconds, formatAmount, formatAmountInUsd, formatDecimalCompactNumber, formatMCap, formatMCapInUsd, formatPercent, formatPrice, formatPriceInUsd, formatSignificantCompactNumber, formatSymbol, formatTokenProtocolName, getCommonTokenAddresses, getCommonTokenSymbolsMap, getNativeToken, getStablecoins, getWrappedToken, groupBy, httpDelete, httpGet, httpMutate, httpPost, httpPut, httpRequest, intersectionBy, isBinanceChain, isEthereumChain, isSolanaChain, isValidEvmAddress, isValidNumber, isValidSolanaAddress, isValidWalletAddress, keyBy, mapKeys, mapValues, parseTokenProtocolFamily, searchImageUrl, searchTwitterUrl, throttle, truncateAddress, twitterTweetUrl, twitterUserUrl, txExplorerUrl, uniqBy };

package/dist/index.d.ts

@@ -140,118 +140,195 @@ declare class SafeBigNumber extends BigNumber {
  */
 declare const isValidNumber: (num: unknown) => boolean;
 type FormatAmountOptions = {
-    showPlusGtThanZero: boolean;
+    showPlusGtThanZero?: boolean;
 };
 /**
  * Format a raw token / asset amount (no currency symbol).
  *
- * Precision tiers (ROUND_DOWN):
- * | Range         | Format                  | Example input → output       |
- * |---------------|-------------------------|------------------------------|
- * | < 0.001       | 5 decimal places        | 0.0001234  → "0.00012"       |
- * | < 1           | 3 decimal places        | 0.56789    → "0.567"         |
- * | < 100         | 2 decimal places        | 42.678     → "42.67"         |
- * | < 100 000     | grouped, 2 dp           | 12345.6    → "12,345.60"     |
- * | ≥ 100 000     | abbreviated (K/M/B/T)   | 1_500_000  → "1.5M"          |
+ * Use cases:
+ * - Activity-list quantity column from `base_amount`.
+ * - Activity-list total in native token mode before the UI appends a symbol.
+ * - Holder, trader, transaction, and token balance counts where compact
+ *   K/M/B/T output is acceptable.
+ *
+ * Examples:
+ * - `41.8701` -> `"41.87"`
+ * - `1.087` -> `"1.087"`
+ * - `0.000032564` -> `"0.0₄3256"`
+ * - `12345.6` -> `"12.3K"`
+ * - `2089491826.331852` -> `"2.08B"`
  *
  * @param num - The numeric value.
  * @param options.showPlusGtThanZero - Prefix positive values with "+".
  */
 declare const formatAmount: (num?: BigNumber.Value, options?: FormatAmountOptions) => string;
 /**
- * Format a USD dollar amount with "$" prefix (standard precision).
+ * Format an amount with "$" prefix.
  *
- * Precision tiers (ROUND_DOWN):
- * | Range         | Format                  | Example input → output       |
- * |---------------|-------------------------|------------------------------|
- * | < 0.001       | "$0"                    | 0.00001    → "$0"            |
- * | < 1           | 3 decimal places        | 0.56789    → "$0.567"        |
- * | < 100         | 2 decimal places        | 42.678     → "$42.67"        |
- * | < 10 000      | grouped, 2 dp           | 1234.5     → "$1,234.50"     |
- * | ≥ 10 000      | abbreviated (K/M/B/T)   | 1_500_000  → "$1.5M"         |
+ * Use cases:
+ * - Activity-list total in USD mode from `amount_usd`.
+ * - USD notional amount displays where the numeric body should match
+ *   `formatSignificantCompactNumber`.
+ * - Compact USD volume / liquidity text when 4 significant digits are enough.
  *
- * Use this for standard financial displays (volume, market cap, liquidity).
+ * Examples:
+ * - `96.32167791184` -> `"$96.32"`
+ * - `0.000032564` -> `"$0.0₄3256"`
+ * - `12345.6` -> `"$12.3K"`
+ * - `2089491826.331852` -> `"$2.08B"`
+ * - `-42.678` -> `"-$42.67"`
  *
  * @param num - The numeric value.
  * @param options.showPlusGtThanZero - Prefix positive values with "+".
  */
-declare const formatAmountUSD: (num?: BigNumber.Value, options?: FormatAmountOptions) => string;
+declare const formatAmountInUsd: (num?: BigNumber.Value, options?: FormatAmountOptions) => string;
+type FormatDecimalCompactNumberOptions = {
+    /** Prefix to prepend after sign handling. Use "$" for USD displays. */
+    prefix?: string;
+    /** Abbreviate values >= 1_000 with K/M/B/T suffixes. Default: true. */
+    short?: boolean;
+    /**
+     * Decimal precision after scaling. This is the practical equivalent of the
+     * GMGN `$num` call sites that pass explicit formatting options.
+     */
+    precision?: number;
+    /**
+     * Minimum decimal places when `pad` is true. For example, GMGN token prices
+     * pass `pad: true` and use 3 decimals for values > 1.
+     */
+    minPrecision?: number;
+    /** Keep trailing zeros up to `max(precision, minPrecision)`. */
+    pad?: boolean;
+    /** String returned when the input is invalid. */
+    invalidPlaceholder?: string;
+    /** BigNumber rounding mode. GMGN display numbers truncate by default. */
+    rounding?: BigNumber.RoundingMode;
+};
 /**
- * Format a raw token / asset amount (no currency symbol) — **compact** variant.
- *
- * Same tier ladder as {@link formatAmountUSDCompact} but without the `"$"`
- * prefix. Suited for space-constrained UIs that need to render an amount
- * alongside a token symbol (e.g. `"15K SOL"`) inside narrow buttons or
- * badges.
- *
- * | Range         | Format                  | Example input → output       |
- * |---------------|-------------------------|------------------------------|
- * | < 0.001       | "0"                     | 0.00001    → "0"             |
- * | < 1           | 3 decimal places        | 0.56789    → "0.567"         |
- * | < 100         | 2 decimal places        | 42.678     → "42.67"         |
- * | < 1 000       | 0 decimal places        | 567.89     → "567"           |
- * | ≥ 1 000       | abbreviated, 0 dp,      | 15 678     → "15K"           |
- * |               | rounded to nearest 100  | 1 234 567  → "1M"            |
- *
- * @param num - The numeric value.
- * @param options.showPlusGtThanZero - Prefix positive values with "+".
+ * Format numbers with the GMGN `$num`-style display rules.
+ *
+ * This is the configurable formatter behind GMGN's token price and activity
+ * price / market-cap displays:
+ *
+ * | GMGN field / scenario                 | Call pattern                                                           | Example output |
+ * |---------------------------------------|------------------------------------------------------------------------|----------------|
+ * | Token header price                    | `formatDecimalCompactNumber(price, { prefix: "$", precision: 3, pad: true })` | `"$2.089"`     |
+ * | Activity price column in price mode   | `formatDecimalCompactNumber(price, { prefix: "$", precision: 3, pad: true })` | `"$2.092"`     |
+ * | Activity price column in market-cap mode | `formatDecimalCompactNumber(price * totalSupply, { prefix: "$", precision: 2 })` | `"$2.09B"`     |
+ * | Basic metric market cap               | `formatDecimalCompactNumber(marketCap, { prefix: "$", precision: 2 })`       | `"$2.08B"`     |
+ * | Tiny token price                      | `formatDecimalCompactNumber(0.00003, { prefix: "$" })`                       | `"$0.0₄3"`     |
+ *
+ * Notes:
+ * - Values are truncated by default, matching the observed GMGN production
+ *   bundle behavior.
+ * - `short` defaults to true and applies K/M/B/T after scaling.
+ * - For market-cap displays, callers should multiply `price * totalSupply`
+ *   before calling this function; this keeps the formatter single-purpose.
  */
-declare const formatAmountCompact: (num?: BigNumber.Value, options?: FormatAmountOptions) => string;
+declare const formatDecimalCompactNumber: (num?: BigNumber.Value, options?: FormatDecimalCompactNumberOptions) => string;
 /**
- * Format a USD dollar amount with "$" prefix — **compact** variant.
- *
- * Compared to {@link formatAmountUSD}, this variant is more aggressively
- * rounded and suited for space-constrained UIs (cards, badges, list items):
- *
- * | Range         | Format                  | Example input → output       |
- * |---------------|-------------------------|------------------------------|
- * | < 0.001       | "$0"                    | 0.00001    → "$0"            |
- * | < 1           | 3 decimal places        | 0.56789    → "$0.567"        |
- * | < 100         | 2 decimal places        | 42.678     → "$42.67"        |
- * | < 1 000       | 0 decimal places        | 567.89     → "$567"          |
- * | ≥ 1 000       | abbreviated, 0 dp,      | 15 678     → "$15.6K"        |
- * |               | rounded to nearest 100  | 1 234 567  → "$1.2M"         |
- *
- * Key differences from `formatAmountUSD`:
- * - 100–1 000: shows 0 dp instead of 2 dp
- * - ≥ 1 000: abbreviates earlier (1K vs 10K) with 0 precision, rounded to 100s
- *
- * @param num - The numeric value.
- * @param options.showPlusGtThanZero - Prefix positive values with "+".
+ * Format a non-negative token price without a currency symbol.
+ *
+ * Use cases:
+ * - Token price text when the surrounding UI already renders the currency.
+ * - Activity-list price mode when the column header or cell chrome supplies
+ *   the unit separately.
+ * - Token rows where values should match the GMGN-style 3-decimal padded
+ *   price display and compact K/M/B/T behavior.
+ *
+ * Examples:
+ * - `2.089` -> `"2.089"`
+ * - `2.1` -> `"2.100"`
+ * - `0.00003` -> `"0.0₄3"`
+ * - `1234.567` -> `"1.234K"`
  */
-declare const formatAmountUSDCompact: (num?: BigNumber.Value, options?: FormatAmountOptions) => string;
-type FormatPriceOptions = {
-    isHighPrecise: boolean;
-};
+declare const formatPrice: (num?: BigNumber.Value) => string;
 /**
- * Format a token price (no currency symbol). Negative inputs render as `"--"`.
- *
- * Same precision tiers as {@link formatPriceUSD} but without the "$" prefix.
- *
- * @param num - The price value.
- * @param options.isHighPrecise - Use high-precision mode (default: true).
+ * Format a non-negative token price with a "$" prefix.
+ *
+ * Use cases:
+ * - Token header price in USD.
+ * - Activity-list price column in price mode.
+ * - Any USD price display that should keep exactly 3 decimals after the
+ *   scaled value, except zero and subscript-zero tiny values.
+ *
+ * Examples:
+ * - `2.089` -> `"$2.089"`
+ * - `2.1` -> `"$2.100"`
+ * - `0.00003` -> `"$0.0₄3"`
+ * - `1234.567` -> `"$1.234K"`
  */
-declare const formatPrice: (num?: BigNumber.Value, options?: FormatPriceOptions) => string;
+declare const formatPriceInUsd: (num?: BigNumber.Value) => string;
+/**
+ * Format a non-negative market-cap or fully diluted valuation number without a
+ * currency symbol.
+ *
+ * Use cases:
+ * - Market-cap column text when the surrounding UI already renders the unit.
+ * - Activity-list price column in market-cap mode after the caller multiplies
+ *   `price * totalSupply`.
+ * - Metrics that should use compact K/M/B/T notation with 2 decimal places.
+ *
+ * Examples:
+ * - `2089491826.331852` -> `"2.08B"`
+ * - `2092491826.331852` -> `"2.09B"`
+ * - `1234567` -> `"1.23M"`
+ * - `999.999` -> `"999.99"`
+ */
+declare const formatMCap: (num?: BigNumber.Value) => string;
+/**
+ * Format a non-negative market-cap or fully diluted valuation number with a
+ * "$" prefix.
+ *
+ * Use cases:
+ * - Token header market-cap / FDV metrics.
+ * - Activity-list price column in market-cap mode.
+ * - USD market-cap displays that should compact large values with K/M/B/T.
+ *
+ * Examples:
+ * - `2089491826.331852` -> `"$2.08B"`
+ * - `2092491826.331852` -> `"$2.09B"`
+ * - `1234567` -> `"$1.23M"`
+ * - `999.999` -> `"$999.99"`
+ */
+declare const formatMCapInUsd: (num?: BigNumber.Value) => string;
+type FormatSignificantCompactNumberOptions = {
+    /** Abbreviate values >= 1_000 with K/M/B/T suffixes. Default: true. */
+    short?: boolean;
+    /**
+     * Number of significant digits retained before truncation. GMGN's activity
+     * amount formatter uses 4 significant digits for normal values and 3 after
+     * K/M/B/T scaling.
+     */
+    significantDigits?: number;
+    /** String returned when the input is invalid. */
+    invalidPlaceholder?: string;
+};
 /**
- * Format a token price with "$" prefix. Negative inputs render as `"--"`.
- *
- * Two precision modes controlled by `isHighPrecise` (default: `true`):
- *
- * | Range         | High precision (default)       | Low precision                |
- * |---------------|-------------------------------|------------------------------|
- * | < 0.0001      | subscript notation, 4 sig     | subscript notation, 2 sig    |
- * |               | 0.0000382 → "$0.0₄382"        | 0.0000382 → "$0.0₄38"       |
- * | < 1           | 4 dp, grouped                 | 2 significant dp             |
- * |               | 0.12345 → "$0.1234"           | 0.12345 → "$0.12"           |
- * | < 10 000      | 4 dp, grouped                 | 2 dp, grouped                |
- * |               | 1234.567 → "$1,234.5670"      | 1234.567 → "$1,234.56"      |
- * | < 100 000     | 2 dp, grouped                 | 2 dp, grouped                |
- * | ≥ 100 000     | abbreviated (K/M/B/T)         | abbreviated (K/M/B/T)        |
- *
- * @param num - The price value.
- * @param options.isHighPrecise - Use high-precision mode (default: true).
+ * Format numbers with the GMGN `ej`-style activity amount rules.
+ *
+ * This is the formatter GMGN uses for activity-list amount-like cells:
+ *
+ * | GMGN field / scenario             | Source value                                     | Call pattern                       | Example output |
+ * |-----------------------------------|--------------------------------------------------|------------------------------------|----------------|
+ * | Activity quantity column          | `record.base_amount`                             | `formatSignificantCompactNumber(value)`  | `"41.87"`      |
+ * | Activity quantity in mempool buy  | `record.amount_out`                              | `formatSignificantCompactNumber(value)`  | token amount   |
+ * | Activity quantity in mempool sell | `record.amount_in`                               | `formatSignificantCompactNumber(value)`  | token amount   |
+ * | Activity total in SOL/native mode | native quote `record.quote_amount`               | `formatSignificantCompactNumber(value)`  | `"1.087"`      |
+ * | Activity total in USD mode        | `record.amount_usd`, then prepend `"$"` in UI    | `formatSignificantCompactNumber(value)`  | `"96.32"`      |
+ * | Activity total via non-native quote | `record.amount_usd / nativeTokenUsdPrice`      | `formatSignificantCompactNumber(value)`  | native amount  |
+ * | Tiny gas/native amount            | native amount below 0.0001                       | `formatSignificantCompactNumber(value)`  | `"0.0₄3"`      |
+ * | Large notional value              | any amount >= 1_000                              | `formatSignificantCompactNumber(value)`  | `"2.08B"`      |
+ *
+ * Notes:
+ * - The function returns the numeric text only. Add `$`, token symbols, SOL,
+ *   or other unit labels at the call site.
+ * - Values are truncated, not rounded, matching the observed GMGN bundle.
+ * - GMGN's separate gas column often uses a threshold display such as
+ *   `"<0.0001"`; use this function when you want the `ej` amount behavior,
+ *   and add threshold handling outside when the UI contract requires it.
  */
-declare const formatPriceUSD: (num?: BigNumber.Value, options?: FormatPriceOptions) => string;
+declare const formatSignificantCompactNumber: (num?: BigNumber.Value, options?: FormatSignificantCompactNumberOptions) => string;
 type FormatPercentOptions = {
     showPlusGtThanZero?: boolean;
     precision?: number;
@@ -378,4 +455,4 @@ declare function groupBy<T>(array: T[], iteratee: Iteratee<T, string>): Record<s
 declare function mapKeys<T>(obj: Record<string, T>, iteratee: (value: T, key: string) => string): Record<string, T>;
 declare function mapValues<T, R>(obj: Record<string, T>, iteratee: (value: T, key: string) => R): Record<string, R>;
 
-export { ARBITRUM_TOKENS, AVALANCHE_TOKENS, ApiError, BSC_TOKENS, CHAIN_REGISTRY, CHAIN_TOKENS, type ChainMetadata, type ChainPredefinedTokens, ETHEREUM_TOKENS, type FormatAgeOptions, type FormatAmountOptions, type FormatPercentOptions, type FormatPriceOptions, OPTIMISM_TOKENS, type PredefinedToken, SOLANA_TOKENS, SafeBigNumber, accountExplorerUrl, capitalize, chainColor, chainDisplayName, chainIcon, chainIdBySlug, chainSlug, chainToNamespace, debounce, formatAge, formatAgeInSeconds, formatAmount, formatAmountCompact, formatAmountUSD, formatAmountUSDCompact, formatPercent, formatPrice, formatPriceUSD, formatSymbol, formatTokenProtocolName, getCommonTokenAddresses, getCommonTokenSymbolsMap, getNativeToken, getStablecoins, getWrappedToken, groupBy, httpDelete, httpGet, httpMutate, httpPost, httpPut, httpRequest, intersectionBy, isBinanceChain, isEthereumChain, isSolanaChain, isValidEvmAddress, isValidNumber, isValidSolanaAddress, isValidWalletAddress, keyBy, mapKeys, mapValues, parseTokenProtocolFamily, searchImageUrl, searchTwitterUrl, throttle, truncateAddress, twitterTweetUrl, twitterUserUrl, txExplorerUrl, uniqBy };
+export { ARBITRUM_TOKENS, AVALANCHE_TOKENS, ApiError, BSC_TOKENS, CHAIN_REGISTRY, CHAIN_TOKENS, type ChainMetadata, type ChainPredefinedTokens, ETHEREUM_TOKENS, type FormatAgeOptions, type FormatAmountOptions, type FormatDecimalCompactNumberOptions, type FormatPercentOptions, type FormatSignificantCompactNumberOptions, OPTIMISM_TOKENS, type PredefinedToken, SOLANA_TOKENS, SafeBigNumber, accountExplorerUrl, capitalize, chainColor, chainDisplayName, chainIcon, chainIdBySlug, chainSlug, chainToNamespace, debounce, formatAge, formatAgeInSeconds, formatAmount, formatAmountInUsd, formatDecimalCompactNumber, formatMCap, formatMCapInUsd, formatPercent, formatPrice, formatPriceInUsd, formatSignificantCompactNumber, formatSymbol, formatTokenProtocolName, getCommonTokenAddresses, getCommonTokenSymbolsMap, getNativeToken, getStablecoins, getWrappedToken, groupBy, httpDelete, httpGet, httpMutate, httpPost, httpPut, httpRequest, intersectionBy, isBinanceChain, isEthereumChain, isSolanaChain, isValidEvmAddress, isValidNumber, isValidSolanaAddress, isValidWalletAddress, keyBy, mapKeys, mapValues, parseTokenProtocolFamily, searchImageUrl, searchTwitterUrl, throttle, truncateAddress, twitterTweetUrl, twitterUserUrl, txExplorerUrl, uniqBy };