@reyaxyz/common 0.362.0 → 0.363.0

package/src/types.ts

@@ -49,6 +49,7 @@ export type MarketEntity = {
 
 export enum ReyaChainId {
   reyaNetwork = 1729,
+  reyaLocal = 31337,
   reyaCronos = 89346162,
 }
 
@@ -145,16 +146,14 @@ export type StrippedMarginAccountEntity = Pick<
   'id' | 'name'
 >;
 
-export type ConditionalOrdersInfo = {
-  stopLoss?: {
-    stopLossPrice: number;
-    orderId: string;
-  };
-  takeProfit?: {
-    takeProfitPrice: number;
-    orderId: string;
-  };
-};
+// PRO-126 Bug 5: `ConditionalOrdersInfo` and the
+// `PositionEntity.conditionalOrdersInfo` field that surfaced
+// pending SL/TP info on positions were retired alongside the
+// `OrdersGateway.execute` / conditional-orders DB pipeline. The
+// off-chain API no longer has a backing source for live trigger
+// metadata; once the ME exposes pending trigger info via its own
+// surface, an equivalent field can be reintroduced sourcing from
+// there.
 
 export type PositionEntity = {
   id: number;
@@ -162,7 +161,6 @@ export type PositionEntity = {
   size: number;
   base: number;
   price: number;
-  conditionalOrdersInfo?: ConditionalOrdersInfo;
   markPrice: number;
   orderStatus: Status;
   realisedPnl: number;
@@ -175,8 +173,6 @@ export type PositionEntity = {
   accountId: number;
 };
 
-export type OrderType = 'market';
-
 export type OrderHistoryType =
   | 'long-trade'
   | 'short-trade'
@@ -186,7 +182,7 @@ export type OrderHistoryType =
 export type OrderHistoryEntity = {
   id: string;
   action: OrderHistoryType;
-  orderType: OrderType;
+  orderType: 'market';
   base: number;
   executionPrice: number;
   realisedPnl?: number | null;
@@ -260,34 +256,6 @@ export type LpTransactionHistoryEntity = {
   timestamp: number;
 };
 
-export type MarginAccountTransactionHistoryType =
-  | 'deposit'
-  | 'withdrawal'
-  | 'transfer'
-  | 'auto_exchange_deposit'
-  | 'auto_exchange_withdrawal';
-
-export type MarginAccountTransactionStatus = 'confirmed' | 'pending';
-
-export type MarginAccountTransactionHistoryEntity = {
-  id: number;
-  type: MarginAccountTransactionHistoryType;
-  token: string;
-  amount: number;
-  transactionLink: string;
-  status: MarginAccountTransactionStatus;
-  timestamp: number;
-};
-
-export type ReferralFeeTransactionHistoryEntity = {
-  id: number;
-  referee_wallet_address: string;
-  token: string;
-  amount: number;
-  transactionLink: string;
-  timestamp: number;
-};
-
 export type TokenEntity = {
   name: TokenName;
   address: Address;
@@ -776,6 +744,23 @@ export type TransactionExecutionOutput = {
   txHash: string | null;
   txSubmitted?: boolean;
   errorMessage?: string;
+  /**
+   * Structured error discriminator surfaced by the slim
+   * `executeReyaTransaction` core. One of
+   * `TRANSACTION_FAILED_TO_SEND` (pre-send: wallet manager rejected),
+   * `RECEIPT_NOT_FOUND` (post-send: receipt fetch failed),
+   * `TRANSACTION_REVERTED` (post-send: receipt.status === 0), or
+   * `FAILED_FILL` (post-send: FailedUnifiedFillBytes / FailedFillBytes).
+   * Optional — populated when the slim core returned a discriminated
+   * failure. May coexist with a non-null `txHash` on post-send failures
+   * (the on-chain hash is surfaced for `RECEIPT_NOT_FOUND`,
+   * `TRANSACTION_REVERTED`, and `FAILED_FILL`). UI consumers should prefer
+   * `errorMessage` for display; this field is for analytics + logs.
+   *
+   * `FAILED_ORDER` (used to be: FailedOrderBytes) is retired alongside
+   * the legacy `OrdersGateway.execute` IOC handler in PRO-126 Bug 5.
+   */
+  errorCode?: string;
   accountId?: string | null;
   coreSigNonce?: string | null;
   poolSigNonce?: string | null;
@@ -841,16 +826,29 @@ export type PendingWithdrawal = {
   tokenAmount: number;
 } & (PendingWithdrawalStatus | ReadyWithdrawalStatus);
 
-export enum OrdersGatewayOrderType {
-  STOP_LOSS = 0,
-  TAKE_PROFIT = 1,
-  LIMIT_ORDER = 2,
-  MARKET_ORDER = 3,
-  REDUCE_ONLY_MARKET_ORDER = 4,
-  FULL_CLOSE_ORDER = 5,
-  LIMIT_ORDER_SPOT = 6,
+// PRO-126 Bug 5 retired the legacy `OrdersGatewayOrderType` enum (the
+// 8-field `ConditionalOrderDetails` typehash discriminator). The
+// on-chain `OrdersGateway.execute` selector that consumed those values
+// is gone; every order class now uses `OrderType` below, whose values
+// mirror the on-chain `OrderType` enum in
+// orders-gateway/src/libraries/DataTypes.sol.
+export enum OrderType {
+  Limit = 0,
+  StopLoss = 1,
+  TakeProfit = 2,
+}
+
+// Matches the on-chain `MarketType` enum. Used to discriminate spot vs perp
+// in unified off-chain code paths and with the market-id namespace helpers in
+// packages/common-backend/src/market-id-namespace.
+export enum MarketType {
+  Spot = 0,
+  Perp = 1,
 }
 
+// Canonical on-chain V3 codes, also written by the pre-cutover V2 indexer.
+export { CanonicalExecutionType as ExecutionType } from './canonical-execution-type';
+
 export enum ConditionalOrderType {
   STOP_LOSS = 0,
   TAKE_PROFIT = 1,
@@ -965,23 +963,6 @@ export type V1AuthenticatorTransport =
   | 'AUTHENTICATOR_TRANSPORT_HYBRID';
 
 // on-chain events (consider pushing into a separate file)
-export type PositionDataUpdatedDetails = {
-  marketId: string;
-  accountId: string;
-  // todo: p1: argument names don't align with the on-chain event
-  orderBase: string;
-  realisedPnl: string;
-  lastPrice: string;
-  lastPriceTimestamp: string;
-  fundingValue: string;
-  baseMultiplier: string;
-  adlUnwindPrice: string;
-  blockTimestamp: string;
-  transactionHash: string;
-  blockNumber: number;
-  uniqueId: string;
-};
-
 export type MatchOrderDetails = {
   uniqueId: string;
   transactionHash: string;
@@ -1040,10 +1021,11 @@ export interface PassivePerpOrderAndPositionUpdate {
   uniqueId: bigint;
 }
 
-export type AssetPair =
+export type ConfiguredAssetPair =
   | 'ETHUSD'
   | 'WSTETHUSD'
   | 'WBTCUSD'
+  | 'BTCUSD' // Localnet's mock BTC collateral feed
   | 'USDCUSD'
   | 'USDEUSD'
   | 'SUSDEUSD'
@@ -1132,6 +1114,19 @@ export type AssetPair =
   | 'LINEAUSDMARK'
   | 'MEGAUSDMARK';
 
+type SpotPair<T extends string> = T extends `${infer Base}USDMARK`
+  ? `${Base}USD`
+  : never;
+
+/** Internal cache keys whose prices mirror an existing reference feed. */
+export type MirroredAssetPair = 'REYALM#KEYROCKRUSD' | 'REYALM#FLOWRUSD';
+
+/** Includes Stork spot feeds and mirrored price cache keys. */
+export type AssetPair =
+  | ConfiguredAssetPair
+  | SpotPair<ConfiguredAssetPair>
+  | MirroredAssetPair;
+
 export type ContractId = string;
 
 export type Price = {
@@ -1143,9 +1138,31 @@ export type Price = {
 
 export type MarketPrice = {
   marketId: number;
-  price: string;
+  /** @deprecated No longer written; will be removed when V1 prices endpoints are dropped. */
+  price?: string;
+  /**
+   * ME mark price (E18), despite the name — the pool-price task has written the
+   * matching-engine mark here since the perpOB rewire. Surfaced as the v2
+   * `MarketSummary.markPrice`. The genuine index price is `indexPrice`.
+   */
   oraclePrice: string;
-  poolPrice: string;
+  /**
+   * Orderbook mid (E18). Absent on an empty or one-sided book — there is
+   * deliberately no mark-price fallback, because publishing the mark under the
+   * name "mid" makes a book with no two-sided quote indistinguishable from one
+   * trading exactly at the mark. Consumers must treat it as optional, the same
+   * way `SpotMarketSummary.throttledMidPrice` has always been treated.
+   */
+  poolPrice?: string;
+  /**
+   * Stork spot `*USD` index price (E18), rUSD-quoted — divided by USDCUSD the
+   * same way the collateral prices are, since Stork publishes it as X/USD and
+   * every price this API serves is X/USDC. Absent when the feed has no fresh
+   * tick, when the USDCUSD cross-rate is unavailable, and permanently on
+   * markets with no Stork feed, so consumers must treat it as optional rather
+   * than substituting a stale value.
+   */
+  indexPrice?: string;
   updatedAt: number;
 };
 
@@ -1163,9 +1180,13 @@ export const isMarketPrice = (
 // Replication-derived types
 type Unpacked<T> = T extends (infer U)[] ? U : T;
 
-export type ConditionalOrderSensitive = Unpacked<
-  Replication['replication:ConditionalOrdersSensitive']['result']
->;
+// PRO-126 Bug 7: `ConditionalOrderSensitive` + `OrderReplicationData`
+// retired with the rest of the `ConditionalOrders` DB pipeline. The
+// `replication:ConditionalOrdersSensitive` channel is no longer
+// subscribed (bun-socket/index.ts) and no longer publishes
+// (common-backend/src/config/database.ts). Order data flows through
+// the ME's `{orders}:changes` stream consumed by AccountOrdersMap;
+// callers should derive types from the ME's protobuf `Order` schema.
 
 export type Position = Unpacked<Replication['replication:position']['result']>;
 
@@ -1174,13 +1195,12 @@ export type PositionReplicationData = Stringified<
   Unpacked<Replication['replication:position']['result']>
 >;
 
-export type OrderReplicationData = Stringified<
-  Unpacked<Replication['replication:ConditionalOrdersSensitive']['result']>
->;
-
-export type PerpExecutionReplicationData = Stringified<
-  Unpacked<Replication['replication:orders']['result']>
->;
+export type PerpExecutionReplicationData = Omit<
+  Stringified<Unpacked<Replication['replication:orders']['result']>>,
+  'created_at'
+> & {
+  created_at?: string;
+};
 
 export type AccountRealBalanceReplicationData = Stringified<
   Unpacked<Replication['replication:account_real_balances']['result']>
@@ -1190,8 +1210,8 @@ export type SpotExecutionReplicationData = Stringified<
   Unpacked<Replication['replication:spot_executions']['result']>
 >;
 
-export type SpotExecutionBustReplicationData = Stringified<
-  Unpacked<Replication['replication:spot_execution_busts']['result']>
+export type ExecutionBustReplicationData = Stringified<
+  Unpacked<Replication['replication:execution_busts']['result']>
 >;
 
 export type MarketDataReplicationData = Stringified<

package/src/utils/calculate.ts

@@ -593,7 +593,10 @@ export const calculateTotalMargin = ({
     let fundingCashFlow = 0;
     let adlCashFlow = 0;
 
-    if (marketTracker) {
+    // Mirrors calculateSettledPositionPnl: a flat position accrues nothing, and
+    // a zero position multiplier (reopened after full ADL) cannot be divided by,
+    // so only realized and mark PnL count for it.
+    if (marketTracker && position.base !== 0 && position.baseMultiplier > 0) {
       // fundingCashFlow
       const marketTrackerFundingValue =
         position.base < 0
@@ -619,13 +622,18 @@ export const calculateTotalMargin = ({
       adlCashFlow = (adlUnwindPrice - initialPrice) * position.base;
     }
 
+    // The underlying supplies the mark; all position cashflows are in the quote token.
+    // A missing mark means "no price for this bucket", not a price of zero:
+    // carry the position at its last price rather than swinging by its notional.
+    const markPrice = markPrices.get(tokenInfo.underlyingAssetId);
     const unrealizedPnl =
-      ((markPrices.get(tokenInfo.quoteTokenId) ?? 0) - position.lastPrice) *
-      position.base;
+      markPrice === undefined
+        ? 0
+        : (markPrice - position.lastPrice) * position.base;
 
     pnl.set(
-      tokenInfo.underlyingAssetId,
-      (pnl.get(tokenInfo.underlyingAssetId) ?? 0) +
+      tokenInfo.quoteTokenId,
+      (pnl.get(tokenInfo.quoteTokenId) ?? 0) +
         position.realizedPnl +
         fundingCashFlow +
         adlCashFlow +
@@ -633,10 +641,15 @@ export const calculateTotalMargin = ({
     );
   });
 
-  return Array.from(accountBalances.entries()).reduce(
-    (sum, [address, balance]) =>
+  // A quote-token PnL balance can exist without a collateral deposit row.
+  const assets = new Set([
+    ...Array.from(accountBalances.keys()),
+    ...Array.from(pnl.keys()),
+  ]);
+  return Array.from(assets).reduce(
+    (sum, address) =>
       sum +
-      (balance + (pnl.get(address) ?? 0)) *
+      ((accountBalances.get(address) ?? 0) + (pnl.get(address) ?? 0)) *
         (address === rUSDAddress
           ? 1
           : (assetPrices.get(address) ?? 0) / (rUSDPrice || 1)),

package/src/utils/consts.ts

@@ -1,10 +1,4 @@
-import {
-  ConditionalOrderType,
-  ConditionalOrderTypeName,
-  Rank,
-  RankTrading,
-  TierType,
-} from '../types';
+import { Rank, RankTrading, TierType } from '../types';
 
 export const MAX_UINT128 = 2 ** 128 - 1;
 export const API_TIMEOUT: number = 2500;
@@ -111,15 +105,6 @@ export const RANKS_TRADING: Record<number, RankTrading> = {
   },
 };
 
-export const conditionalOrderTypeNames: Record<
-  ConditionalOrderType,
-  ConditionalOrderTypeName
-> = {
-  [ConditionalOrderType.STOP_LOSS]: 'Stop Loss',
-  [ConditionalOrderType.TAKE_PROFIT]: 'Take Profit',
-  [ConditionalOrderType.LIMIT_ORDER]: 'Limit Order',
-};
-
 export const INSTANT_TRADING_RATE_XP = 2;
 export const TRADING_LOTTERY_BOOST = 10;
 
@@ -135,6 +120,9 @@ export const VOLUME_TIER_MAP: Record<number, number> = {
   6: 5_000_000_000, // Tier 6: $5,000,000,000 volume
 };
 
+export const FEE_TIER_VOLUME_LOOKBACK_WINDOW_IN_SECONDS =
+  30 * ONE_DAY_IN_SECONDS;
+
 export const TIER_TYPE_MAP: Record<number, TierType> = {
   0: TierType.REGULAR,
   1: TierType.REGULAR,

package/src/utils/error-sanitizer.ts

@@ -0,0 +1,137 @@
+// Redis can echo command arguments inside an error's message. Once an error is
+// known to carry command metadata, its message and stack must therefore be
+// treated as tainted rather than attempting value-by-value replacement.
+const REDACTED_COMMAND_ERROR =
+  '[redacted: Redis command error — message/stack withheld (may echo arguments)]';
+
+function commandField(source: unknown): { name?: unknown } | undefined {
+  if (source === null || typeof source !== 'object') return undefined;
+  const command = (source as { command?: unknown }).command;
+  return command !== null && typeof command === 'object'
+    ? (command as { name?: unknown })
+    : undefined;
+}
+
+function redactCommandBearing(
+  source: { name?: unknown; code?: unknown; cause?: unknown },
+  command: { name?: unknown },
+  depth: number,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (typeof source.name === 'string') out.name = source.name;
+  if (typeof source.code === 'string' || typeof source.code === 'number') {
+    out.code = source.code;
+  }
+  out.command = typeof command.name === 'string' ? { name: command.name } : {};
+  out.message = REDACTED_COMMAND_ERROR;
+  // The stack is intentionally withheld because it can repeat the tainted
+  // message. Causes are projected independently so safe diagnostics survive.
+  if (source.cause !== undefined && depth < 3) {
+    out.cause = normalizeError(source.cause, depth + 1);
+  }
+  return out;
+}
+
+/**
+ * Project an unknown error into a serializable diagnostic record. An ioredis
+ * error carrying `command: { name, args }` is fail-closed: arguments plus the
+ * potentially argument-bearing message/stack are withheld, while safe fields
+ * such as the error name, code, command name, and projected cause survive.
+ */
+export function normalizeError(
+  err: unknown,
+  depth = 0,
+): Record<string, unknown> {
+  if (err instanceof Error) {
+    // A logger must never throw because an error object has a hostile getter.
+    try {
+      const command = commandField(err);
+      if (command) return redactCommandBearing(err, command, depth);
+
+      const out: Record<string, unknown> = {};
+      if (typeof err.name === 'string') out.name = err.name;
+      if (typeof err.message === 'string') out.message = err.message;
+      if (typeof err.stack === 'string') out.stack = err.stack;
+      const { code } = err as { code?: unknown };
+      if (typeof code === 'string' || typeof code === 'number') out.code = code;
+      const { cause } = err as { cause?: unknown };
+      if (cause !== undefined && depth < 3) {
+        out.cause = normalizeError(cause, depth + 1);
+      }
+      return out;
+    } catch {
+      return { message: '[unserializable error]' };
+    }
+  }
+
+  // Plain objects use the same command-taint rule and an allow-list projection
+  // so arbitrary password/argument fields never reach a log record.
+  if (err !== null && typeof err === 'object') {
+    try {
+      const command = commandField(err);
+      if (command) {
+        return redactCommandBearing(
+          err as { name?: unknown; code?: unknown; cause?: unknown },
+          command,
+          depth,
+        );
+      }
+      const src = err as Record<string, unknown>;
+      const out: Record<string, unknown> = {};
+      if (typeof src.message === 'string') out.message = src.message;
+      if (typeof src.name === 'string') out.name = src.name;
+      if (typeof src.code === 'string' || typeof src.code === 'number') {
+        out.code = src.code;
+      }
+      if (src.cause !== undefined && depth < 3) {
+        out.cause = normalizeError(src.cause, depth + 1);
+      }
+      return out;
+    } catch {
+      return { message: '[unserializable error]' };
+    }
+  }
+
+  try {
+    return { message: String(err) };
+  } catch {
+    return { message: '[unserializable error]' };
+  }
+}
+
+/**
+ * Pure, in-place log-record sanitizer. Keeping this free of Winston types lets
+ * every package install a tiny adapter around the same implementation without
+ * introducing package cycles or forcing the shared leaf package to depend on a
+ * logging framework.
+ */
+export function sanitizeErrorLogInfo<T extends Record<string, unknown>>(
+  info: T,
+): T {
+  const record = info as Record<string, unknown>;
+  // Nested `{ error }` and `{ cause }` are the preferred contextual shapes.
+  // Primitive values cannot carry command metadata, so preserve their existing
+  // field shape rather than wrapping them in `{ message }`.
+  if (record.error !== null && typeof record.error === 'object') {
+    record.error = normalizeError(record.error);
+  }
+  if (record.cause !== null && typeof record.cause === 'object') {
+    record.cause = normalizeError(record.cause);
+  }
+
+  // Winston can flatten a raw Error passed as the second argument. Command
+  // presence alone makes the merged message/stack tainted, including stackless
+  // and plain-object variants.
+  const command = commandField(record);
+  if (command) {
+    record.message = REDACTED_COMMAND_ERROR;
+    record.stack = undefined;
+    try {
+      record.command =
+        typeof command.name === 'string' ? { name: command.name } : {};
+    } catch {
+      record.command = {};
+    }
+  }
+  return info;
+}

package/src/utils/index.ts

@@ -15,3 +15,6 @@ export * from './stringify';
 export * from './delay';
 export * from './transaction-receipt';
 export * from './layerzero';
+export * from './throttled-error';
+export * from './error-sanitizer';
+export * from './realized-balance';

package/src/utils/network.ts

@@ -19,6 +19,8 @@ export function getMoneyInOutNetworks(
       MoneyInOutChainId.arbitrumSepolia,
     ];
 
+  if (chainId === ReyaChainId.reyaLocal) return [];
+
   throw new Error(`Unknown Reya chain id ${chainId}`);
 }
 
@@ -52,11 +54,13 @@ export const chainIdToExplorerURL: {
   [MoneyInOutChainId.opSepolia]: 'https://sepolia-optimism.etherscan.io',
   [MoneyInOutChainId.ethereumSepolia]: 'https://sepolia.etherscan.io',
   [ReyaChainId.reyaNetwork]: 'https://explorer.reya.network',
+  [ReyaChainId.reyaLocal]: 'http://127.0.0.1:4000',
   [ReyaChainId.reyaCronos]: 'https://reya-cronos.blockscout.com',
 };
 
 const ChainRpcUrls: Record<MoneyInOutChainId | ReyaChainId, string[]> = {
   [ReyaChainId.reyaNetwork]: ['https://rpc.reya.network'],
+  [ReyaChainId.reyaLocal]: ['http://127.0.0.1:8545'],
   [MoneyInOutChainId.ethereumMainnet]: [
     'https://mainnet.gateway.tenderly.co',
     'https://eth.llamarpc.com',

package/src/utils/number.ts

@@ -12,6 +12,116 @@ export function amountNormalizer(
   );
 }
 
+/**
+ * Divide a plain-integer decimal string by 10**decimals by shifting the decimal
+ * point, returning EXACTLY what `amountNormalizer(value, decimals).toString()`
+ * would return — or `null` when that cannot be guaranteed, so the caller falls
+ * back to BigNumber.
+ *
+ * This exists because the perp-execution row transform is the single largest
+ * CPU consumer on the api tier (PRO-1025: `transformTrade` 26% inclusive,
+ * `amountNormalizer` 19%, self time dominated by bignumber.js multiply/divide
+ * and the BigNumber constructor). Each row normalises ~30 Decimal fields and a
+ * response carries up to 100 rows, so this runs a few thousand times per
+ * request. Dividing a decimal string by a power of ten is a decimal-point
+ * shift; it does not need arbitrary-precision arithmetic.
+ *
+ * Measured: 9.8x faster than the BigNumber path on realistic devnet values,
+ * with a 100% fast-path hit rate on those shapes.
+ *
+ * TWO BigNumber behaviours make the naive shift wrong, and both are why this
+ * returns null rather than guessing. Each would have silently changed the
+ * public API's serialisation:
+ *
+ *  1. `toString()` switches to EXPONENTIAL notation outside a magnitude window.
+ *     BigNumber's EXPONENTIAL_AT default is [-7, 21], so plain notation holds
+ *     only for a decimal exponent in [-6, 20]; `1e-7` renders "1e-7", not
+ *     "0.0000001". A plain shift would emit the long form for those.
+ *  2. `.div()` ROUNDS to DECIMAL_PLACES (default 20). So amountNormalizer is
+ *     already lossy past 20 fractional digits, and an exact shift produces MORE
+ *     digits than the current output. Verified: 4000164727132806080849 / 1e27
+ *     is 0.00000400016472713281 through BigNumber, not the exact value.
+ *
+ * The fast path is therefore taken only when the result is provably identical:
+ * inside the plain-notation window, and with no rounding possible.
+ */
+const PLAIN_INTEGER = /^[0-9]+$/;
+const BN_PLAIN_NOTATION_MIN_EXPONENT = -6;
+const BN_PLAIN_NOTATION_MAX_EXPONENT = 20;
+const BN_DECIMAL_PLACES = 20;
+
+export function normalizeAmountFast(
+  value: string,
+  decimals: number,
+): string | null {
+  let digits = value;
+  let negative = false;
+  if (digits.charCodeAt(0) === 45 /* '-' */) {
+    negative = true;
+    digits = digits.slice(1);
+  }
+  if (!PLAIN_INTEGER.test(digits)) return null;
+
+  digits = digits.replace(/^0+(?=[0-9])/, '');
+  if (digits === '0') {
+    // Negative zero: BigNumber disagrees with itself here — toString() gives
+    // "0" but toNumber() gives -0, and Object.is(-0, 0) is false. Rather than
+    // reproduce that split, decline so both wrappers fall back and inherit the
+    // exact behaviour. Costs nothing: only a literal zero input reaches here.
+    return negative ? null : '0';
+  }
+
+  // Decimal exponent of the result: BigNumber renders plain only inside the
+  // window, and rounds beyond BN_DECIMAL_PLACES fractional digits.
+  const exponent = digits.length - 1 - decimals;
+  if (
+    exponent < BN_PLAIN_NOTATION_MIN_EXPONENT ||
+    exponent > BN_PLAIN_NOTATION_MAX_EXPONENT ||
+    decimals > BN_DECIMAL_PLACES
+  ) {
+    return null;
+  }
+
+  if (decimals === 0) return negative ? `-${digits}` : digits;
+
+  const padded =
+    digits.length <= decimals
+      ? '0'.repeat(decimals - digits.length + 1) + digits
+      : digits;
+  const integerPart = padded.slice(0, padded.length - decimals);
+  const fractionPart = padded
+    .slice(padded.length - decimals)
+    .replace(/0+$/, '');
+  const rendered = fractionPart
+    ? `${integerPart}.${fractionPart}`
+    : integerPart;
+
+  if (rendered === '0') return '0';
+  return negative ? `-${rendered}` : rendered;
+}
+
+/** `amountNormalizer(value, decimals).toString()`, fast path where provable. */
+export function normalizeAmountToString(
+  value: string,
+  decimals: number = 18,
+): string {
+  return (
+    normalizeAmountFast(value, decimals) ??
+    amountNormalizer(value, decimals).toString()
+  );
+}
+
+/** `amountNormalizer(value, decimals).toNumber()`, fast path where provable. */
+export function normalizeAmountToNumber(
+  value: string,
+  decimals: number = 18,
+): number {
+  const fast = normalizeAmountFast(value, decimals);
+  return fast !== null
+    ? Number(fast)
+    : amountNormalizer(value, decimals).toNumber();
+}
+
 export function amountDenormalizer(
   value: BigNumber | number | string,
   decimals: number = 18,