Numbers

The DecimalString contract, the three numeric tiers, and the naming vocabulary of the SDK helpers

The SDK moves every monetary and quantity value as a DecimalString. A number appears only inside display math. This page describes the contract, the three tiers of numeric helpers, and the verbs that name them.

The DecimalString contract

Every monetary or quantity value that crosses a package, provider, or network boundary is a DecimalString from @lifi/perps-types. It matches DECIMAL_PATTERN: an optional leading -, digits, and an optional . with digits. It has no grouping, exponent, currency sign, or whitespace.

Value	DecimalString
'0.5'	Yes
'-1250'	Yes
'1e-7'	No
'1,000'	No
'.5'	No
'$1'	No

• isDecimalString(value) tests a value against the pattern.
• truncateDecimal, decimalToBaseUnits, and the account-side wire/ helpers throw PerpsError with ValidationError for a string that fails the pattern. calculateOrderAmounts gives null for one.
• baseUnitsToDecimal throws PerpsError with ValidationError for an amount that is not an integer string, such as '1.5' or '1e3'.
• No exported signature carries a Big. The SDK and the providers compute with big.js internally, and give back a DecimalString or a number.
• A number is for display math and small integers only, such as leverage, decimals, percentages, and chart values. A number never goes to a venue.
• A producer that builds a DecimalString from a number writes plain notation, never exponent notation. numberToDecimalString does this.

import { isDecimalString, numberToDecimalString } from '@lifi/perps-sdk';

isDecimalString('0.5');          // true
isDecimalString('1e-7');         // false
numberToDecimalString(1e-7);     // '0.0000001'

Three tiers

The numeric helpers sit in three tiers. Each tier has one input type, one output type, and one rule.

Tier	Holds	In → out	Rule
decimal/	parseDecimal, <a>To<B> conversions, format*	representation → representation	No domain words. Conversions throw on invalid input.
math/	Display-tier formulas (calculate*, estimate*)	number → number	Results are for format*. Never send one to a venue.
wire/	calculateOrderAmounts, snapOrder*, account helpers	DecimalString → DecimalString	Venue-ready values, snapped by the market’s own provider.

A value for a venue comes from wire/ or from a provider field. A value for a screen goes through parseDecimal, then math/, then format*.

import {
  calculateUnrealizedPnl,
  formatUsd,
  parseDecimal,
} from '@lifi/perps-sdk';
import type { Position } from '@lifi/perps-sdk';

function pnlLabel(position: Position, markPrice: string) {
  const entry = parseDecimal(position.entryPrice);
  const mark = parseDecimal(markPrice);
  const size = parseDecimal(position.size);
  if (entry === undefined || mark === undefined || size === undefined) {
    return formatUsd(undefined);
  }
  return formatUsd(calculateUnrealizedPnl(entry, mark, size));
}

Vocabulary

One verb names one kind of transformation.

Verb	Input → output	Fallible	Example
parse<X>	string → typed value, or undefined on garbage	Yes	parseDecimal
<a>To<B>	Representation A → B with no domain meaning. A and B are each baseUnits, decimal, decimalString, or number.	Throws on invalid input, never guesses	decimalToBaseUnits, baseUnitsToDecimal, numberToDecimalString
format<X>	Value → human string (grouped, localised)	No, renders a placeholder	formatUsd, formatNumber
snap<X>	DecimalString → venue-grid DecimalString	Throws on a missing grid	snapOrderSize, snapOrderPrice
calculate<X>	Values → exact result by formula	No	calculateNotionalValue, calculateOrderAmounts
estimate<X>	Values → approximation or forward-looking value	No	estimateLiquidationPrice, estimateAverageEntryPrice
resolve<X>	Candidates and rules → the one to use	No	resolveCloseSize, resolveQuote
is<X>, would<X>, has<X>	Value → boolean	—	isDecimalString, wouldImmediatelyLiquidate
build<X>	Inputs → payload struct	—	buildQuote

No function in decimal/, math/, or wire/ uses a derive, predict, or convert verb, or a bare noun as its name.

See Utilities for the signature and an example of each helper.