@nktkas/hyperliquid 0.25.5 → 0.25.7

package/src/src/api/subscription/l2Book.ts

@@ -1,6 +1,6 @@
 import * as v from "valibot";
 import { type DeepImmutable, Integer, parser, UnsignedInteger } from "../_base.js";
-import type { SubscriptionRequestConfig } from "./_base.js";
+import type { SubscriptionRequestConfig } from "./_types.js";
 import type { Subscription } from "../../transport/base.js";
 
 import { L2BookLevelSchema } from "../_common_schemas.js";

package/src/src/api/subscription/notification.ts

@@ -1,6 +1,6 @@
 import * as v from "valibot";
 import { Address, type DeepImmutable, parser } from "../_base.js";
-import type { SubscriptionRequestConfig } from "./_base.js";
+import type { SubscriptionRequestConfig } from "./_types.js";
 import type { Subscription } from "../../transport/base.js";
 
 // -------------------- Schemas --------------------

package/src/src/api/subscription/openOrders.ts

@@ -1,6 +1,6 @@
 import * as v from "valibot";
 import { Address, type DeepImmutable, parser } from "../_base.js";
-import type { SubscriptionRequestConfig } from "./_base.js";
+import type { SubscriptionRequestConfig } from "./_types.js";
 import type { Subscription } from "../../transport/base.js";
 
 import { DetailedOrderSchema } from "../_common_schemas.js";

package/src/src/api/subscription/orderUpdates.ts

@@ -1,6 +1,6 @@
 import * as v from "valibot";
 import { Address, type DeepImmutable, parser, UnsignedInteger } from "../_base.js";
-import type { SubscriptionRequestConfig } from "./_base.js";
+import type { SubscriptionRequestConfig } from "./_types.js";
 import type { Subscription } from "../../transport/base.js";
 
 import { OrderProcessingStatusSchema, OrderSchema } from "../_common_schemas.js";

package/src/src/api/subscription/trades.ts

@@ -1,6 +1,6 @@
 import * as v from "valibot";
 import { type DeepImmutable, parser } from "../_base.js";
-import type { SubscriptionRequestConfig } from "./_base.js";
+import type { SubscriptionRequestConfig } from "./_types.js";
 import type { Subscription } from "../../transport/base.js";
 
 import { RecentTradesResponse } from "../info/recentTrades.js";

package/src/src/api/subscription/userEvents.ts

@@ -1,6 +1,6 @@
 import * as v from "valibot";
 import { Address, Decimal, type DeepImmutable, parser, UnsignedDecimal, UnsignedInteger } from "../_base.js";
-import type { SubscriptionRequestConfig } from "./_base.js";
+import type { SubscriptionRequestConfig } from "./_types.js";
 import type { Subscription } from "../../transport/base.js";
 
 import { FillSchema, TwapFillSchema, TwapStateSchema, TwapStatusSchema } from "../_common_schemas.js";

package/src/src/api/subscription/userFills.ts

@@ -1,6 +1,6 @@
 import * as v from "valibot";
 import { Address, type DeepImmutable, parser } from "../_base.js";
-import type { SubscriptionRequestConfig } from "./_base.js";
+import type { SubscriptionRequestConfig } from "./_types.js";
 import type { Subscription } from "../../transport/base.js";
 
 import { FillSchema } from "../_common_schemas.js";

package/src/src/api/subscription/userFundings.ts

@@ -1,6 +1,6 @@
 import * as v from "valibot";
 import { Address, Decimal, type DeepImmutable, parser, UnsignedInteger } from "../_base.js";
-import type { SubscriptionRequestConfig } from "./_base.js";
+import type { SubscriptionRequestConfig } from "./_types.js";
 import type { Subscription } from "../../transport/base.js";
 
 // -------------------- Schemas --------------------

package/src/src/api/subscription/userHistoricalOrders.ts

@@ -1,6 +1,6 @@
 import * as v from "valibot";
 import { Address, type DeepImmutable, parser, UnsignedInteger } from "../_base.js";
-import type { SubscriptionRequestConfig } from "./_base.js";
+import type { SubscriptionRequestConfig } from "./_types.js";
 import type { Subscription } from "../../transport/base.js";
 
 import { DetailedOrderSchema, OrderProcessingStatusSchema } from "../_common_schemas.js";

package/src/src/api/subscription/userNonFundingLedgerUpdates.ts

@@ -1,6 +1,6 @@
 import * as v from "valibot";
 import { Address, type DeepImmutable, parser } from "../_base.js";
-import type { SubscriptionRequestConfig } from "./_base.js";
+import type { SubscriptionRequestConfig } from "./_types.js";
 import type { Subscription } from "../../transport/base.js";
 
 import { UserNonFundingLedgerUpdatesResponse } from "../info/userNonFundingLedgerUpdates.js";

package/src/src/api/subscription/userTwapHistory.ts

@@ -1,6 +1,6 @@
 import * as v from "valibot";
 import { Address, type DeepImmutable, parser, UnsignedInteger } from "../_base.js";
-import type { SubscriptionRequestConfig } from "./_base.js";
+import type { SubscriptionRequestConfig } from "./_types.js";
 import type { Subscription } from "../../transport/base.js";
 
 import { TwapStateSchema, TwapStatusSchema } from "../_common_schemas.js";

package/src/src/api/subscription/userTwapSliceFills.ts

@@ -1,6 +1,6 @@
 import * as v from "valibot";
 import { Address, type DeepImmutable, parser, UnsignedInteger } from "../_base.js";
-import type { SubscriptionRequestConfig } from "./_base.js";
+import type { SubscriptionRequestConfig } from "./_types.js";
 import type { Subscription } from "../../transport/base.js";
 
 import { TwapFillSchema } from "../_common_schemas.js";

package/src/src/api/subscription/webData2.ts

@@ -1,6 +1,6 @@
 import * as v from "valibot";
 import { Address, type DeepImmutable, parser, UnsignedDecimal, UnsignedInteger } from "../_base.js";
-import type { SubscriptionRequestConfig } from "./_base.js";
+import type { SubscriptionRequestConfig } from "./_types.js";
 import type { Subscription } from "../../transport/base.js";
 
 import { DetailedOrderSchema, TwapStateSchema } from "../_common_schemas.js";
@@ -118,7 +118,7 @@ export const WebData2Event = /* @__PURE__ */ (() => {
         v.description("Array of TWAP states."),
       ),
       /** Account summary for spot trading. */
-      spotState: SpotClearinghouseStateResponse,
+      spotState: v.optional(SpotClearinghouseStateResponse),
       /** Context for each spot asset. */
       spotAssetCtxs: SpotMetaAndAssetCtxsResponse.items[1],
       /** Whether the user has opted out of spot dusting. */

package/src/src/api/subscription/webData3.ts

@@ -0,0 +1,179 @@
+import * as v from "valibot";
+import { Address, type DeepImmutable, parser, UnsignedDecimal, UnsignedInteger } from "../_base.js";
+import type { SubscriptionRequestConfig } from "./_types.js";
+import type { Subscription } from "../../transport/base.js";
+
+import { DetailedOrderSchema } from "../_common_schemas.js";
+import { MetaAndAssetCtxsResponse } from "../info/metaAndAssetCtxs.js";
+import { ClearinghouseStateResponse } from "../info/clearinghouseState.js";
+
+// -------------------- Schemas --------------------
+
+/** Subscription to comprehensive user and market data events. */
+export const WebData3Request = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Type of subscription. */
+      type: v.pipe(
+        v.literal("webData3"),
+        v.description("Type of subscription."),
+      ),
+      /** User address. */
+      user: v.pipe(
+        Address,
+        v.description("User address."),
+      ),
+    }),
+    v.description("Subscription to comprehensive user and market data events."),
+  );
+})();
+export type WebData3Request = v.InferOutput<typeof WebData3Request>;
+
+/** Event of comprehensive user and market data. */
+export const WebData3Event = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** User state information. */
+      userState: v.pipe(
+        v.object({
+          /** Agent address if one exists. */
+          agentAddress: v.pipe(
+            v.nullable(Address),
+            v.description("Agent address if one exists."),
+          ),
+          /** Timestamp until which the agent is valid. */
+          agentValidUntil: v.pipe(
+            v.nullable(UnsignedInteger),
+            v.description("Timestamp until which the agent is valid."),
+          ),
+          /** Cumulative ledger value. */
+          cumLedger: v.pipe(
+            UnsignedDecimal,
+            v.description("Cumulative ledger value."),
+          ),
+          /** Server timestamp (in ms since epoch). */
+          serverTime: v.pipe(
+            UnsignedInteger,
+            v.description("Server timestamp (in ms since epoch)."),
+          ),
+          /** Whether this account is a vault. */
+          isVault: v.pipe(
+            v.boolean(),
+            v.description("Whether this account is a vault."),
+          ),
+          /** User address. */
+          user: v.pipe(
+            Address,
+            v.description("User address."),
+          ),
+          /** Whether the user has opted out of spot dusting. */
+          optOutOfSpotDusting: v.pipe(
+            v.optional(v.literal(true)),
+            v.description("Whether the user has opted out of spot dusting."),
+          ),
+          /** Whether DEX abstraction is enabled. */
+          dexAbstractionEnabled: v.pipe(
+            v.optional(v.boolean()),
+            v.description("Whether DEX abstraction is enabled."),
+          ),
+        }),
+        v.description("User state information."),
+      ),
+      /** Array of perpetual DEX states. */
+      perpDexStates: v.pipe(
+        v.array(
+          v.object({
+            /** Account summary for perpetual trading. */
+            clearinghouseState: ClearinghouseStateResponse,
+            /** Total equity in vaults. */
+            totalVaultEquity: v.pipe(
+              UnsignedDecimal,
+              v.description("Total equity in vaults."),
+            ),
+            /** Array of user open orders with frontend information. */
+            openOrders: v.pipe(
+              v.optional(v.array(DetailedOrderSchema)),
+              v.description("User open orders with frontend information."),
+            ),
+            /** Context for each perpetual asset. */
+            assetCtxs: MetaAndAssetCtxsResponse.items[1],
+            /** Assets currently at their open interest cap. */
+            perpsAtOpenInterestCap: v.pipe(
+              v.optional(v.array(v.string())),
+              v.description("Assets currently at their open interest cap."),
+            ),
+            /** Array of leading vaults. */
+            leadingVaults: v.pipe(
+              v.optional(
+                v.array(
+                  /** Vault that a user is leading. */
+                  v.pipe(
+                    v.object({
+                      /** Address of the vault. */
+                      address: v.pipe(
+                        Address,
+                        v.description("Address of the vault."),
+                      ),
+                      /** Name of the vault. */
+                      name: v.pipe(
+                        v.string(),
+                        v.description("Name of the vault."),
+                      ),
+                    }),
+                    v.description("Vault that a user is leading."),
+                  ),
+                ),
+              ),
+              v.description("Array of leading vaults."),
+            ),
+          }),
+        ),
+        v.description("Array of perpetual DEX states."),
+      ),
+    }),
+    v.description("Comprehensive user and market data."),
+  );
+})();
+export type WebData3Event = v.InferOutput<typeof WebData3Event>;
+
+// -------------------- Function --------------------
+
+/** Request parameters for the {@linkcode webData3} function. */
+export type WebData3Parameters = Omit<v.InferInput<typeof WebData3Request>, "type">;
+
+/**
+ * Subscribe to comprehensive user and market data updates.
+ * @param config - General configuration for Subscription API subscriptions.
+ * @param params - Parameters specific to the API subscription.
+ * @param listener - A callback function to be called when the event is received.
+ * @returns A request-promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
+ *
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ * @example
+ * ```ts
+ * import { WebSocketTransport } from "@nktkas/hyperliquid";
+ * import { webData3 } from "@nktkas/hyperliquid/api/subscription";
+ *
+ * const transport = new WebSocketTransport();
+ *
+ * const sub = await webData3(
+ *   { transport },
+ *   { user: "0x..." },
+ *   (data) => console.log(data),
+ * );
+ * ```
+ */
+export function webData3(
+  config: SubscriptionRequestConfig,
+  params: DeepImmutable<WebData3Parameters>,
+  listener: (data: WebData3Event) => void,
+): Promise<Subscription> {
+  const payload = parser(WebData3Request)({ type: "webData3", ...params });
+  return config.transport.subscribe<WebData3Event>(payload.type, payload, (e) => {
+    if (e.detail.userState.user === payload.user) {
+      listener(e.detail);
+    }
+  });
+}

package/src/src/api/subscription/~client.ts

@@ -1,6 +1,6 @@
 import type { OmitFirst, OverloadedParameters } from "../_base.js";
 import type { ISubscriptionTransport } from "../../transport/base.js";
-import type { SubscriptionRequestConfig } from "./_base.js";
+import type { SubscriptionRequestConfig } from "./_types.js";
 
 import { activeAssetCtx } from "./activeAssetCtx.js";
 import { activeAssetData } from "./activeAssetData.js";
@@ -25,6 +25,7 @@ import { userNonFundingLedgerUpdates } from "./userNonFundingLedgerUpdates.js";
 import { userTwapHistory } from "./userTwapHistory.js";
 import { userTwapSliceFills } from "./userTwapSliceFills.js";
 import { webData2 } from "./webData2.js";
+import { webData3 } from "./webData3.js";
 
 export type {
   ActiveAssetCtxEvent as WsActiveAssetCtxEvent,
@@ -94,6 +95,9 @@ export type {
   UserTwapSliceFillsParameters as WsUserTwapSliceFillsParameters,
 } from "./userTwapSliceFills.js";
 export type { WebData2Event as WsWebData2Event, WebData2Parameters as WsWebData2Parameters } from "./webData2.js";
+export type { WebData3Event as WsWebData3Event, WebData3Parameters as WsWebData3Parameters } from "./webData3.js";
+
+export type { SubscriptionRequestConfig } from "./_types.js";
 
 /**
  * A client for interacting with the Hyperliquid Subscription API.
@@ -658,4 +662,27 @@ export class SubscriptionClient<
   webData2(...args: OmitFirst<OverloadedParameters<typeof webData2>>) {
     return webData2(this, ...args);
   }
+
+  /**
+   * Subscribe to comprehensive user and market data updates.
+   * @param params - Parameters specific to the API subscription.
+   * @param listener - A callback function to be called when the event is received.
+   * @returns A request-promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
+   *
+   * @throws {TransportError} When the transport layer throws an error.
+   *
+   * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+   * @example
+   * ```ts
+   * import * as hl from "@nktkas/hyperliquid";
+   *
+   * const transport = new hl.WebSocketTransport();
+   *
+   * const client = new hl.SubscriptionClient({ transport });
+   * const sub = await client.webData3({ user: "0x..." }, (data) => console.log(data));
+   * ```
+   */
+  webData3(...args: OmitFirst<OverloadedParameters<typeof webData3>>) {
+    return webData3(this, ...args);
+  }
 }

package/src/src/api/subscription/~mod.ts

@@ -24,7 +24,7 @@
  */
 
 export { parser, SchemaError } from "../_base.js";
-export type { SubscriptionRequestConfig } from "./_base.js";
+export type { SubscriptionRequestConfig } from "./_types.js";
 
 export * from "./activeAssetCtx.js";
 export * from "./activeAssetData.js";
@@ -49,3 +49,4 @@ export * from "./userNonFundingLedgerUpdates.js";
 export * from "./userTwapHistory.js";
 export * from "./userTwapSliceFills.js";
 export * from "./webData2.js";
+export * from "./webData3.js";

package/src/src/signing/_signTypedData.ts

@@ -222,14 +222,15 @@ export async function getWalletChainId(wallet: AbstractWallet): Promise<`0x${str
 export async function getWalletAddress(wallet: AbstractWallet): Promise<`0x${string}`> {
   if (isAbstractViemWallet(wallet)) {
     if ("address" in wallet && wallet.address) {
-      return wallet.address;
+      return wallet.address.toLowerCase() as `0x${string}`;
     } else if ("getAddresses" in wallet && wallet.getAddresses) {
       const addresses = await wallet.getAddresses();
-      return addresses[0];
+      return addresses[0].toLowerCase() as `0x${string}`;
     }
   } else if (isAbstractEthersV6Signer(wallet) || isAbstractEthersV5Signer(wallet)) {
     if ("getAddress" in wallet && wallet.getAddress) {
-      return await wallet.getAddress() as `0x${string}`;
+      const address = await wallet.getAddress();
+      return address.toLowerCase() as `0x${string}`;
     }
   }
   throw new Error("Unsupported wallet for getting address");

package/src/src/transport/http/mod.ts

@@ -30,17 +30,17 @@ export class HttpRequestError extends TransportError {
 export interface HttpTransportOptions {
   /**
    * Specifies whether to use the testnet API endpoints from the {@linkcode server} property.
-   * @defaultValue `false`
+   * @default false
    */
   isTestnet?: boolean;
   /**
    * Request timeout in ms. Set to `null` to disable.
-   * @defaultValue `10_000`
+   * @default 10_000
    */
   timeout?: number | null;
   /**
    * Custom server to use for API requests.
-   * @defaultValue `https://api.hyperliquid.xyz` for mainnet and `https://api.hyperliquid-testnet.xyz` for testnet.
+   * @default `https://api.hyperliquid.xyz` for mainnet and `https://api.hyperliquid-testnet.xyz` for testnet.
    */
   server?: {
     mainnet?: { api?: string | URL; rpc?: string | URL };

package/src/src/transport/websocket/_reconnecting_websocket.ts

@@ -6,25 +6,25 @@ import { AbortSignal_ } from "../_polyfills.js";
 export interface ReconnectingWebSocketOptions {
   /**
    * Custom WebSocket constructor.
-   * @defaultValue The global `WebSocket` constructor.
+   * @default globalThis.WebSocket
    */
   WebSocket?: new (url: string | URL, protocols?: string | string[]) => WebSocket;
   /**
    * Maximum number of reconnection attempts.
-   * @defaultValue `3`
+   * @default 3
    */
   maxRetries?: number;
   /**
    * Maximum time in ms to wait for a connection to open.
    * Set to `null` to disable.
-   * @defaultValue `10_000`
+   * @default 10_000
    */
   connectionTimeout?: number | null;
   /**
    * Delay before reconnection in ms.
    * May be a number or a function that returns a number.
    * @param attempt - The current attempt number.
-   * @defaultValue `(attempt) => Math.min(~~(1 << attempt) * 150, 10_000)` - Exponential backoff (max 10s)
+   * @default (attempt) => Math.min(~~(1 << attempt) * 150, 10_000); // Exponential backoff (max 10s)
    */
   reconnectionDelay?: number | ((attempt: number) => number);
 }

package/src/src/transport/websocket/mod.ts

@@ -16,7 +16,7 @@ type MaybePromise<T> = T | Promise<T>;
 export interface WebSocketTransportOptions {
   /**
    * Indicates this transport uses testnet endpoint.
-   * @defaultValue `false`
+   * @default false
    */
   isTestnet?: boolean;
   /**
@@ -27,26 +27,26 @@ export interface WebSocketTransportOptions {
    * - Testnet:
    *   - API: `wss://api.hyperliquid-testnet.xyz/ws`
    *   - Explorer: `wss://rpc.hyperliquid-testnet.xyz/ws`
-   * @defaultValue `wss://api.hyperliquid.xyz/ws` for mainnet, `wss://api.hyperliquid-testnet.xyz/ws` for testnet
+   * @default `wss://api.hyperliquid.xyz/ws` for mainnet, `wss://api.hyperliquid-testnet.xyz/ws` for testnet
    */
   url?: string | URL;
   /**
    * Timeout for requests in ms.
    * Set to `null` to disable.
-   * @defaultValue `10_000`
+   * @default 10_000
    */
   timeout?: number | null;
   /**
    * Interval between sending ping messages in ms.
    * Set to `null` to disable.
-   * @defaultValue `30_000`
+   * @default 30_000
    */
   keepAliveInterval?: number | null;
   /** Reconnection policy configuration for closed connections. */
   reconnect?: ReconnectingWebSocketOptions;
   /**
    * Enable automatic re-subscription to Hyperliquid subscription after reconnection.
-   * @defaultValue `true`
+   * @default true
    */
   resubscribe?: boolean;
   onRequest?: (type: string, payload: unknown) => MaybePromise<unknown | void | null | undefined>;

package/src/src/utils/_format.ts

@@ -0,0 +1,172 @@
+import { HyperliquidError } from "../_base.js";
+
+/**
+ * Format price according to Hyperliquid {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size | rules}:
+ * - Maximum 5 significant figures
+ * - Maximum (6 for perp, 8 for spot) - `szDecimals` decimal places
+ * - Integer prices are always allowed regardless of significant figures
+ * - Remove trailing zeros
+ * @example
+ * ```ts
+ * import { formatPrice } from "@nktkas/hyperliquid/utils";
+ *
+ * //        `true` for perp (default), `false` for spot
+ * //                                              ⌄⌄⌄⌄⌄
+ * const price = formatPrice("0.0000123456789", 0, false); // → "0.00001234"
+ * ```
+ */
+export function formatPrice(
+  price: string | number,
+  szDecimals: number,
+  isPerp: boolean = true,
+): string {
+  // Prepare: trim, validate, normalize leading/trailing zeros
+  let priceStr = prepareNumber(typeof price === "string" ? price : price.toString());
+
+  // Integer prices bypass sig figs limit per spec
+  if (!priceStr.includes(".")) {
+    return priceStr;
+  }
+
+  // Apply decimal limit: max (6 for perp, 8 for spot) - `szDecimals` decimals
+  const maxDecimals = Math.max((isPerp ? 6 : 8) - szDecimals, 0);
+  priceStr = truncateDecimals(priceStr, maxDecimals);
+
+  // Apply sig figs limit: max 5 significant figures
+  priceStr = truncateSigFigs(priceStr, 5);
+
+  return priceStr;
+}
+
+/**
+ * Format size according to Hyperliquid {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size | rules}:
+ * - Truncate to `szDecimals` decimal places
+ * - Remove trailing zeros
+ * @example
+ * ```ts
+ * import { formatSize } from "@nktkas/hyperliquid/utils";
+ *
+ * const size = formatSize("1.23456789", 5); // → "1.23456"
+ * ```
+ */
+export function formatSize(size: string | number, szDecimals: number): string {
+  // Prepare: trim, validate, normalize leading/trailing zeros
+  let sizeStr = prepareNumber(typeof size === "string" ? size : size.toString());
+
+  // Truncate to `szDecimals` decimal places
+  sizeStr = truncateDecimals(sizeStr, szDecimals);
+
+  return sizeStr;
+}
+
+/**
+ * Prepare number string for processing:
+ * 1. Trim whitespace
+ * 2. Validate format (decimal number, not hex/scientific)
+ * 3. Normalize: remove leading zeros from integer part, trailing zeros from decimal part
+ */
+function prepareNumber(numStr: string): string {
+  const trimmed = numStr.trim();
+
+  // Validate: only decimal numbers allowed (no hex, scientific notation, etc)
+  if (!/^-?(\d+\.?\d*|\.\d+)$/.test(trimmed)) {
+    throw new HyperliquidError(`Invalid number format: ${numStr}`);
+  }
+
+  // Normalize: remove leading zeros from integer, trailing zeros from decimal
+  const [int, dec] = trimmed.split(".");
+  const trimmedInt = int.replace(/^0+/, "") || "0";
+  const trimmedDec = dec?.replace(/0+$/, "");
+  return trimmedInt + (trimmedDec ? "." + trimmedDec : "");
+}
+
+/** String-based Math operations for arbitrary precision */
+const StringMath = {
+  /** Absolute value: remove negative sign if present */
+  abs(numStr: string): string {
+    return numStr[0] === "-" ? numStr.slice(1) : numStr;
+  },
+
+  /** Floor log10 (magnitude): position of most significant digit */
+  log10Floor(numStr: string): number {
+    const abs = this.abs(numStr);
+    const [int, dec] = abs.split(".");
+
+    // Number >= 1: magnitude = length of integer part - 1
+    if (int !== "0") {
+      const trimmed = int.replace(/^0+/, "");
+      return trimmed.length - 1;
+    }
+
+    // Number < 1: count leading zeros in decimal part
+    if (!dec) return -Infinity;
+    const leadingZeros = dec.match(/^0*/)?.[0].length ?? 0;
+    return -(leadingZeros + 1);
+  },
+
+  /** Multiply by 10^exp: shift decimal point left (negative) or right (positive) */
+  multiplyByPow10(numStr: string, exp: number): string {
+    if (exp === 0) return numStr;
+
+    const neg = numStr[0] === "-";
+    const abs = neg ? numStr.slice(1) : numStr;
+    const [int, dec = ""] = abs.split(".");
+
+    if (exp > 0) {
+      // Shift right: move digits from decimal to integer
+      if (exp >= dec.length) {
+        return (neg ? "-" : "") + int + dec + "0".repeat(exp - dec.length);
+      }
+      return (neg ? "-" : "") + int + dec.slice(0, exp) + "." + dec.slice(exp);
+    } else {
+      // Shift left: move digits from integer to decimal
+      const absExp = -exp;
+      if (absExp >= int.length) {
+        return (neg ? "-" : "") + "0." + "0".repeat(absExp - int.length) + int + dec;
+      }
+      return (neg ? "-" : "") + int.slice(0, -absExp) + "." + int.slice(-absExp) + dec;
+    }
+  },
+
+  /** Truncate: remove decimal part */
+  trunc(numStr: string): string {
+    const dotIndex = numStr.indexOf(".");
+    return dotIndex === -1 ? numStr : numStr.slice(0, dotIndex);
+  },
+};
+
+/** Truncate to specified decimal places */
+function truncateDecimals(numStr: string, maxDecimals: number): string {
+  const dotIndex = numStr.indexOf(".");
+  if (dotIndex === -1) return numStr;
+
+  const truncated = numStr.substring(0, dotIndex + maxDecimals + 1);
+
+  // Remove trailing zeros from decimal
+  const [int, dec] = truncated.split(".");
+  const trimmedDec = dec?.replace(/0+$/, "");
+  return trimmedDec ? int + "." + trimmedDec : int;
+}
+
+/** Truncate to specified significant figures using string-based math */
+function truncateSigFigs(numStr: string, maxSigFigs: number): string {
+  if (parseFloat(numStr) === 0) return "0";
+
+  const neg = numStr[0] === "-";
+  const abs = neg ? numStr.slice(1) : numStr;
+
+  // Calculate how much to shift: align most significant digit to ones place + (maxSigFigs-1)
+  const magnitude = StringMath.log10Floor(abs);
+  const shiftAmount = maxSigFigs - magnitude - 1;
+
+  // Shift right, truncate integer part, shift back
+  const shifted = StringMath.multiplyByPow10(abs, shiftAmount);
+  const truncated = StringMath.trunc(shifted);
+  const result = StringMath.multiplyByPow10(truncated, -shiftAmount);
+
+  // Remove trailing zeros introduced by shifting
+  const final = neg ? "-" + result : result;
+  const [int, dec] = final.split(".");
+  const trimmedDec = dec?.replace(/0+$/, "");
+  return trimmedDec ? int + "." + trimmedDec : int;
+}