> ## Documentation Index
> Fetch the complete documentation index at: https://public-perps-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 `-`, an integer part with no leading zero (`0` or a digit `1`-`9` followed by digits), and an optional `.` with one or more digits. It allows no grouping, exponent, currency sign, or whitespace.

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

* `isDecimalString(value)` tests a value against the pattern.
* `roundDecimalString`, `decimalStringToScaledInteger`, the `math/` formulas, and the `wire/` helpers throw `PerpsError` with `ValidationError` for a string that fails the pattern. `calculateOrderAmounts` throws too, and `safeCalculateOrderAmounts` gives `undefined`.
* `scaledIntegerToDecimalString` throws `PerpsError` with `ValidationError` for an amount that is not an integer string, such as `'1.5'` or `'1e3'`.
* Every throwing helper has a `safe*` pair that logs a warning and gives `undefined` in place of the throw. `createSafeFunction(name, fn)` builds such a pair for your own function.
* No exported signature carries a `Big`. The SDK and the providers compute with `big.js` internally, and give back a `DecimalString`.
* A `number` is for small integers and chart values only, such as decimals, leverage, and pixel positions. `decimalStringToNumber` reads a `DecimalString` as a `number` for a chart. 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.

```typescript theme={null}
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/` | Decimal-string arithmetic and compare helpers, `decimalStringToNumber`, `<a>To<B>` conversions, `format*` | representation → representation | No domain words. Conversions throw on invalid input. |
| `math/` | Display-tier formulas (`calculate*`, `estimate*`) | `DecimalString` → `DecimalString` | Exact decimal arithmetic. 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 `math/`, then `format*`. Every `math/` formula takes and gives decimal strings and throws `PerpsError` with `ValidationError` on a bad or zero-divisor input. Each formula has a `safe*` pair that gives `undefined`.

```typescript theme={null}
import { formatUsd, safeCalculateUnrealizedPnl } from '@lifi/perps-sdk';
import type { Position } from '@lifi/perps-sdk';

function pnlLabel(position: Position, markPrice: string) {
  return formatUsd(
    safeCalculateUnrealizedPnl(position.entryPrice, markPrice, position.size)
  );
}
```

## Vocabulary

One verb names one kind of transformation.

| Verb | Input → output | Fallible | Example |
| - | - | - | - |
| `<a>To<B>` | Representation A → B with no domain meaning. A and B are each `scaledInteger`, `decimalString`, `number`, or `unknown`. | Throws on invalid input, never guesses | `decimalStringToScaledInteger`, `scaledIntegerToDecimalString`, `decimalStringToNumber`, `numberToDecimalString` |
| `round<X>` | `DecimalString` → `DecimalString` on a decimal grid, with an explicit `DecimalRounding` | Throws on invalid input | `roundDecimalString` |
| `format<X>` | Value → human string (grouped, localised) | No, renders a placeholder, or shows a non-decimal string unchanged | `formatUsd`, `formatNumber` |
| `snap<X>` | `DecimalString` → venue-grid `DecimalString` | Throws on a missing grid | `snapOrderSize`, `snapOrderPrice` |
| `calculate<X>` | Values → exact result by formula | Throws on invalid input | `calculateNotionalValue`, `calculateOrderAmounts` |
| `estimate<X>` | Values → approximation or forward-looking value | Throws on invalid input | `estimateLiquidationPrice`, `estimateAverageEntryPrice` |
| `resolve<X>` | Candidates and rules → the one to use | Throws on invalid input | `resolveCloseSize`, `resolveQuote` |
| `safe<X>` | The throwing helper `<X>` → the same result, or `undefined` with a warning | No | `safeCalculateRoe`, `safeRoundDecimalString` |
| `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](/sdk/utilities) for the signature and an example of each helper.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.