@lifi/perps-sdk 24.0.0 → 25.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/perps-sdk",
-  "version": "24.0.0",
+  "version": "25.0.0",
   "description": "LI.FI Perps SDK for perpetuals trading",
   "homepage": "https://github.com/lifinance/perps-sdk",
   "bugs": {
@@ -46,7 +46,7 @@
     "big.js": "^7.0.1",
     "partysocket": "^1.1.19",
     "viem": "^2.55.18",
-    "@lifi/perps-types": "^21.0.0"
+    "@lifi/perps-types": "^22.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/decimal/arithmetic.ts

@@ -6,10 +6,9 @@ import { DivBig, TruncBig } from './big.js'
 import { bigToDecimalString, decimalStringToBig } from './decimalStringToBig.js'
 
 /**
- * Exact `a + b`. Each input may carry `$`, `%`, `,` or whitespace:
- * `addDecimalString('$4', '$6')` is `'10'`.
+ * Exact `a + b`.
  *
- * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
  * @public
  */
 export function addDecimalString(a: string, b: string): string {
@@ -26,10 +25,37 @@ export const safeAddDecimalString = createSafeFunction(
   addDecimalString
 )
 
+/**
+ * Exact sum of every value; `'0'` for an empty list.
+ *
+ * @throws {PerpsError} `ValidationError` when a value does not match the
+ *   decimal pattern.
+ * @public
+ */
+export function addDecimalStrings(values: readonly string[]): string {
+  return bigToDecimalString(
+    values.reduce<Big>(
+      (sum, value) => sum.plus(decimalStringToBig(value)),
+      decimalStringToBig('0')
+    )
+  )
+}
+
+/**
+ * {@link addDecimalStrings}, or `undefined` with a warning when it throws.
+ * One bad value gives `undefined`, never a partial sum.
+ *
+ * @public
+ */
+export const safeAddDecimalStrings = createSafeFunction(
+  'addDecimalStrings',
+  addDecimalStrings
+)
+
 /**
  * Exact `a - b`.
  *
- * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
  * @public
  */
 export function subtractDecimalString(a: string, b: string): string {
@@ -49,7 +75,7 @@ export const safeSubtractDecimalString = createSafeFunction(
 /**
  * Exact `a × b`.
  *
- * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
  * @public
  */
 export function multiplyDecimalString(a: string, b: string): string {
@@ -80,8 +106,8 @@ function requireNonZeroDivisor(divisor: string): Big {
 /**
  * `a ÷ b` to 40 decimal places, rounded half up.
  *
- * @throws {PerpsError} `ValidationError` when an input is not a decimal
- *   string or `b` is zero.
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern or `b` is zero.
  * @public
  */
 export function divideDecimalString(a: string, b: string): string {
@@ -103,8 +129,8 @@ export const safeDivideDecimalString = createSafeFunction(
  * `a ÷ b` to 40 decimal places, truncated toward zero, so a derived amount
  * never exceeds the exact quotient.
  *
- * @throws {PerpsError} `ValidationError` when an input is not a decimal
- *   string or `b` is zero.
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern or `b` is zero.
  * @public
  */
 export function divideDecimalStringRoundDown(a: string, b: string): string {
@@ -126,7 +152,7 @@ export const safeDivideDecimalStringRoundDown = createSafeFunction(
 /**
  * Exact `|value|`.
  *
- * @throws {PerpsError} `ValidationError` when `value` is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when `value` does not match the decimal pattern.
  * @public
  */
 export function absDecimalString(value: string): string {

package/src/decimal/compare.ts

@@ -6,7 +6,7 @@ import { decimalStringToBig } from './decimalStringToBig.js'
  * gate can tell `'1.0000000000000001'` from `'1'`. The other relations follow
  * from it: `a <= b` is `!isDecimalStringGreaterThan(a, b)`.
  *
- * @throws {PerpsError} `ValidationError` when either operand is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when either operand does not match the decimal pattern.
  * @public
  */
 export function isDecimalStringGreaterThan(a: string, b: string): boolean {
@@ -28,7 +28,7 @@ export const safeIsDecimalStringGreaterThan = createSafeFunction(
  * Exact `value == 0`, so a flat-position check never reads `'0.0'` as
  * non-zero.
  *
- * @throws {PerpsError} `ValidationError` when `value` is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when `value` does not match the decimal pattern.
  * @public
  */
 export function isDecimalStringZero(value: string): boolean {
@@ -49,7 +49,7 @@ export const safeIsDecimalStringZero = createSafeFunction(
  * Exact three-way compare for a sort: `-1` when `a < b`, `0` when equal, `1`
  * when `a > b`.
  *
- * @throws {PerpsError} `ValidationError` when either operand is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when either operand does not match the decimal pattern.
  * @public
  */
 export function compareDecimalStrings(a: string, b: string): -1 | 0 | 1 {

package/src/decimal/convert.ts

@@ -27,7 +27,7 @@ const BIG_ROUNDING = {
  * The result has no trailing zeros: `roundDecimalString('1.50', 1, 'round')`
  * is `'1.5'`.
  *
- * @throws {PerpsError} `ValidationError` when `value` is not a decimal string,
+ * @throws {PerpsError} `ValidationError` when `value` does not match the decimal pattern,
  *   or `decimals` is not a non-negative integer.
  * @public
  */
@@ -62,7 +62,7 @@ export const safeRoundDecimalString = createSafeFunction(
  * arithmetic: `'0.29'` at 2 decimals is 29, never 28. Off-grid input resolves
  * per `rounding`. No `$`, `%` or `,` is removed first.
  *
- * @throws {PerpsError} `ValidationError` when `value` is not a decimal string,
+ * @throws {PerpsError} `ValidationError` when `value` does not match the decimal pattern,
  *   `decimals` is not a non-negative integer, or the result's magnitude
  *   exceeds `Number.MAX_SAFE_INTEGER`.
  * @public
@@ -75,7 +75,7 @@ export function decimalStringToScaledInteger(
   if (!isDecimalString(value)) {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
-      `'${value}' is not a decimal string.`
+      `'${value}' does not match the decimal pattern.`
     )
   }
   if (!Number.isInteger(decimals) || decimals < 0) {
@@ -147,43 +147,6 @@ export const safeScaledIntegerToDecimalString = createSafeFunction(
   scaledIntegerToDecimalString
 )
 
-/**
- * Round `value` down to `decimals` and pad the result to exactly that many
- * decimal places. The padding is the point: this seeds a fixed-decimal input,
- * where `'500.00'` and `'500'` are two renderings of one amount and the field
- * wants the first. For a canonical wire amount with no trailing zeros, read
- * the amount off `calculateOrderAmounts` or a provider snap instead.
- *
- * Exact decimal arithmetic throughout, so there is no 2^53 ceiling and no
- * float artifact: `'0.01'` at 18 decimals gives
- * `'0.010000000000000000'`, which `Number#toFixed` cannot.
- *
- * @throws {PerpsError} `ValidationError` when `value` is not a
- *   decimal string, or `decimals` is not a non-negative integer.
- * @public
- */
-export function truncateDecimal(value: string, decimals: number): string {
-  if (!Number.isInteger(decimals) || decimals < 0) {
-    throw new PerpsError(
-      PerpsErrorCode.ValidationError,
-      `Invalid decimals for truncation: ${decimals}`
-    )
-  }
-  const truncated = decimalStringToBig(value).round(decimals, Big.roundDown)
-  // big.js carries the sign through a round to zero; '-0.00' is not a spelling.
-  return (truncated.eq(0) ? new Big(0) : truncated).toFixed(decimals)
-}
-
-/**
- * {@link truncateDecimal}, or `undefined` with a warning when it throws.
- *
- * @public
- */
-export const safeTruncateDecimal = createSafeFunction(
-  'truncateDecimal',
-  truncateDecimal
-)
-
 /**
  * Spell a `number` as a {@link DecimalString} in plain notation: `1e-7`
  * becomes `'0.0000001'`, never `'1e-7'`. The boundary helper for a venue or

package/src/decimal/decimalStringToBig.ts

@@ -3,27 +3,22 @@ import Big from 'big.js'
 import { PerpsError } from '../errors/PerpsError.js'
 import { DivBig } from './big.js'
 
-const DISPLAY_CHARACTERS = /[\s$%,]/g
-
 /**
- * Read a decimal string as a `Big`. Whitespace, `$`, `%` and `,` are removed
- * first, so `'$1,234.5'` reads as `1234.5`; the rest must match
- * `DECIMAL_PATTERN`, so an exponent form such as `'1e5'` is rejected.
+ * Read a decimal string as a `Big`. The string must match `DECIMAL_PATTERN`,
+ * so `'$1,234.5'`, `'0.05%'` and the exponent form `'1e5'` are rejected.
  *
- * @throws {PerpsError} `ValidationError` when `value` is not a string or the
- *   cleaned string is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when `value` does not match the
+ *   decimal pattern.
  * @internal
  */
 export function decimalStringToBig(value: string): Big {
-  const cleaned =
-    typeof value === 'string' ? value.replace(DISPLAY_CHARACTERS, '') : ''
-  if (!DECIMAL_PATTERN.test(cleaned)) {
+  if (typeof value !== 'string' || !DECIMAL_PATTERN.test(value)) {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
-      `'${String(value)}' is not a decimal string.`
+      `'${String(value)}' does not match the decimal pattern.`
     )
   }
-  return new Big(cleaned)
+  return new Big(value)
 }
 
 /**

package/src/decimal/format.ts

@@ -38,9 +38,9 @@ const DEFAULT_PLACEHOLDER = '—'
 type FormatInput = number | DecimalString | string | null | undefined
 
 /**
- * Read a display input as a `Big`: `$`, `%`, `,` and whitespace are removed
- * from a string first. `null` means the formatter renders the placeholder;
- * a string it cannot read is returned unchanged for display.
+ * Read a display input as a `Big`. `null` means the formatter renders the
+ * placeholder; a string that does not match the decimal pattern is returned
+ * unchanged for display.
  */
 function toBig(value: FormatInput): Big | null | string {
   if (typeof value === 'number') {

package/src/decimal/parse.ts

@@ -9,7 +9,7 @@ import { decimalStringToBig } from './decimalStringToBig.js'
  * float holds about 15 significant digits, so the result can lose precision;
  * never use it for an amount sent to a venue.
  *
- * @throws {PerpsError} `ValidationError` when `value` is not a decimal string
+ * @throws {PerpsError} `ValidationError` when `value` does not match the decimal pattern
  *   or is too large for a finite float.
  * @public
  */
@@ -95,3 +95,14 @@ export function unknownToDecimalString(
   error.tool = tool
   throw error
 }
+
+/**
+ * The safe pair of {@link unknownToDecimalString}: `undefined` and a warning
+ * in place of a throw.
+ *
+ * @public
+ */
+export const safeUnknownToDecimalString = createSafeFunction(
+  'unknownToDecimalString',
+  unknownToDecimalString
+)

package/src/errors/invalidInput.ts

@@ -0,0 +1,10 @@
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { PerpsError } from './PerpsError.js'
+
+/** A `ValidationError` that names the input parameter and the rule it breaks. */
+export function invalidInput(parameter: string, rule: string): PerpsError {
+  return new PerpsError(
+    PerpsErrorCode.ValidationError,
+    `\`${parameter}\` ${rule}.`
+  )
+}

package/src/index.ts

@@ -20,11 +20,13 @@ export { requireProvider } from './client/requireProvider.js'
 export {
   absDecimalString,
   addDecimalString,
+  addDecimalStrings,
   divideDecimalString,
   divideDecimalStringRoundDown,
   multiplyDecimalString,
   safeAbsDecimalString,
   safeAddDecimalString,
+  safeAddDecimalStrings,
   safeDivideDecimalString,
   safeDivideDecimalStringRoundDown,
   safeMultiplyDecimalString,
@@ -48,9 +50,7 @@ export {
   safeNumberToDecimalString,
   safeRoundDecimalString,
   safeScaledIntegerToDecimalString,
-  safeTruncateDecimal,
   scaledIntegerToDecimalString,
-  truncateDecimal,
 } from './decimal/convert.js'
 export type { FormatOptions, RoundingMode } from './decimal/format.js'
 export {
@@ -65,6 +65,7 @@ export {
   decimalStringToNumber,
   isDecimalString,
   safeDecimalStringToNumber,
+  safeUnknownToDecimalString,
   unknownToDecimalString,
 } from './decimal/parse.js'
 export { PerpsErrorMessage } from './errors/constants.js'
@@ -293,6 +294,7 @@ export type {
   WithdrawFlowSetupRequired,
 } from './types/withdrawal.js'
 export { paginateActivity } from './utils/activityPaging.js'
+export { createSafeFunction } from './utils/createSafeFunction.js'
 export {
   ETHEREUM_NATIVE_GAS,
   ETHEREUM_USDC,
@@ -359,7 +361,10 @@ export type {
   OrderAmounts,
   OrderAmountsInput,
 } from './wire/orderAmounts.js'
-export { calculateOrderAmounts } from './wire/orderAmounts.js'
+export {
+  calculateOrderAmounts,
+  safeCalculateOrderAmounts,
+} from './wire/orderAmounts.js'
 export type { RefuelAmountInput } from './wire/refuel.js'
 export {
   calculateRefuelAmount,

package/src/math/fills.ts

@@ -21,8 +21,8 @@ export { FillClassification }
  * @param startPosition Signed position held BEFORE this fill (`> 0` long,
  *   `< 0` short, `0` flat).
  * @param sz Unsigned fill size.
- * @returns `BUY` or `SELL` when `startPosition` or `sz` is not a decimal
- *   string, so one malformed venue fill still maps.
+ * @returns `BUY` or `SELL` when `startPosition` or `sz` does not match the
+ *   decimal pattern, so one malformed venue fill still maps.
  * @public
  */
 export function classifyFillFromPosition(
@@ -74,8 +74,8 @@ export function classifyFillFromPosition(
  * Classify a fill as open or close based on realizedPnl.
  * @deprecated Use `Fill.classification` instead — it uses startPosition
  * for accurate open/increase/reduce/close/reverse classification.
- * @returns `BUY` or `SELL` when `realizedPnl` is a string that is not a
- *   decimal string.
+ * @returns `BUY` or `SELL` when `realizedPnl` is a string that does not match the
+ *   decimal pattern.
  * @public
  */
 export function classifyFill(

package/src/math/order.ts

@@ -1,8 +1,8 @@
 /**
  * Display-tier order formulas. Every function takes and gives decimal
  * strings; arithmetic is exact Big.js, with division to 40 decimal places.
- * Each formula throws `ValidationError` on an input that is not a decimal
- * string and has a `safe*` pair that gives `undefined` in place of the throw.
+ * Each formula throws `ValidationError` on an input that does not match the
+ * decimal pattern and has a `safe*` pair that gives `undefined` in place of the throw.
  */
 
 import {
@@ -28,6 +28,7 @@ import {
   decimalStringToBig,
   decimalStringToDivBig,
 } from '../decimal/decimalStringToBig.js'
+import { invalidInput } from '../errors/invalidInput.js'
 import { PerpsError } from '../errors/PerpsError.js'
 import { createSafeFunction } from '../utils/createSafeFunction.js'
 import {
@@ -44,7 +45,7 @@ import { calculateRealizedPnl } from './position.js'
  * ```ts
  * calculateSize('100', '10', '2000') // '0.5' (ETH at $2000)
  * ```
- * @throws {PerpsError} `ValidationError` when an input is not a decimal string
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern
  *   or `price` is zero.
  * @public
  */
@@ -58,10 +59,7 @@ export function calculateSize(
   )
   const priceBig = decimalStringToBig(price)
   if (priceBig.eq(0)) {
-    throw new PerpsError(
-      PerpsErrorCode.ValidationError,
-      'Price must not be zero.'
-    )
+    throw invalidInput('price', 'must not be zero')
   }
   return bigToDecimalString(notional.div(priceBig))
 }
@@ -76,7 +74,7 @@ export const safeCalculateSize = createSafeFunction(
  * Estimated trading fee in USD: `sizeUsd × feeRate`.
  *
  * @param feeRate - Fee rate as a fraction (`'0.00035'` for 0.035%).
- * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
  * @public
  */
 export function estimateFees(sizeUsd: string, feeRate: string): string {
@@ -94,8 +92,8 @@ export const safeEstimateFees = createSafeFunction('estimateFees', estimateFees)
  * is not rounded; snap it to the market tick before it goes to a venue.
  *
  * @param slippagePercent - Slippage tolerance as a percentage (`'0.5'` is 0.5%).
- * @throws {PerpsError} `ValidationError` when an input is not a decimal
- *   string, or `slippagePercent` is -100 or less.
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern, or `slippagePercent` is -100 or less.
  * @public
  */
 export function applySlippageToPrice(
@@ -141,9 +139,8 @@ export interface ExpectedPnl {
  *
  * @param entryPrice - Position entry or current market price.
  * @param margin - Margin amount in USD.
- * @returns The expected PnL, or `null` when `triggerPrice`, `entryPrice` or
- *   `margin` is zero.
- * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern, or `triggerPrice`, `entryPrice` or `margin` is zero.
  * @public
  */
 export function calculateExpectedPnl(
@@ -152,13 +149,19 @@ export function calculateExpectedPnl(
   leverage: string,
   isLong: boolean,
   margin: string
-): ExpectedPnl | null {
+): ExpectedPnl {
   const trigger = decimalStringToDivBig(triggerPrice)
   const entry = decimalStringToBig(entryPrice)
   const leverageBig = decimalStringToBig(leverage)
   const marginBig = decimalStringToBig(margin)
-  if (trigger.eq(0) || entry.eq(0) || marginBig.eq(0)) {
-    return null
+  if (trigger.eq(0)) {
+    throw invalidInput('triggerPrice', 'must not be zero')
+  }
+  if (entry.eq(0)) {
+    throw invalidInput('entryPrice', 'must not be zero')
+  }
+  if (marginBig.eq(0)) {
+    throw invalidInput('margin', 'must not be zero')
   }
   const priceDiff = isLong
     ? trigger.minus(entry)
@@ -178,12 +181,11 @@ export const safeCalculateExpectedPnl = createSafeFunction(
 )
 
 /**
- * Trigger price that realises a percentage gain or loss. A zero `entryPrice`
- * or `leverage` gives `'0'`.
+ * Trigger price that realises a percentage gain or loss.
  *
  * @param percent - Target gain or loss percentage (positive = profitable
  *   direction).
- * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
  * @public
  */
 export function calculateTriggerPrice(
@@ -195,8 +197,11 @@ export function calculateTriggerPrice(
   const percentBig = decimalStringToDivBig(percent)
   const entry = decimalStringToBig(entryPrice)
   const leverageBig = decimalStringToBig(leverage)
-  if (entry.eq(0) || leverageBig.eq(0)) {
-    return '0'
+  if (entry.eq(0)) {
+    throw invalidInput('entryPrice', 'must not be zero')
+  }
+  if (leverageBig.eq(0)) {
+    throw invalidInput('leverage', 'must not be zero')
   }
   const priceDelta = percentBig.times(entry).div(leverageBig.times(100))
   return bigToDecimalString(
@@ -211,10 +216,9 @@ export const safeCalculateTriggerPrice = createSafeFunction(
 )
 
 /**
- * Percentage gain or loss that a trigger price realises. A zero `entryPrice`
- * or `leverage` gives `'0'`.
+ * Percentage gain or loss that a trigger price realises.
  *
- * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
  * @public
  */
 export function calculateTriggerPercent(
@@ -226,8 +230,11 @@ export function calculateTriggerPercent(
   const priceBig = decimalStringToDivBig(price)
   const entry = decimalStringToBig(entryPrice)
   const leverageBig = decimalStringToBig(leverage)
-  if (entry.eq(0) || leverageBig.eq(0)) {
-    return '0'
+  if (entry.eq(0)) {
+    throw invalidInput('entryPrice', 'must not be zero')
+  }
+  if (leverageBig.eq(0)) {
+    throw invalidInput('leverage', 'must not be zero')
   }
   const priceDiff = isLong
     ? priceBig.minus(entry)
@@ -243,9 +250,10 @@ export const safeCalculateTriggerPercent = createSafeFunction(
 
 /**
  * Realized PnL as a percentage of the position value at close:
- * `realizedPnl ÷ (|size| × price) × 100`. A zero position value gives `'0'`.
+ * `realizedPnl ÷ (|size| × price) × 100`.
  *
- * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when an input does not match the
+ *   decimal pattern or `size × price` is zero.
  * @public
  */
 export function calculateRealizedPnlPercent(
@@ -258,7 +266,7 @@ export function calculateRealizedPnlPercent(
     .abs()
     .times(decimalStringToBig(price))
   if (positionValue.eq(0)) {
-    return '0'
+    throw invalidInput('size × price', 'must not be zero')
   }
   return bigToDecimalString(pnl.div(positionValue).times(100))
 }
@@ -290,7 +298,7 @@ interface BookWalk {
  * returning the best obtainable fill.
  *
  * @throws {PerpsError} `ValidationError` when `sizeUsd` or a level's `price`
- *   or `size` is not a decimal string.
+ *   or `size` does not match the decimal pattern.
  * @public
  */
 export function walkOrderbook(
@@ -354,7 +362,7 @@ interface BuildQuoteInput {
  * the market's `funding` (`null` for spot, which has none).
  *
  * @throws {PerpsError} `ValidationError` when `sizeUsd`, the mark price, the
- *   taker fee or a book level is not a decimal string.
+ *   taker fee or a book level does not match the decimal pattern.
  * @public
  */
 export function buildQuote(input: BuildQuoteInput): Quote {
@@ -415,7 +423,7 @@ export function findMatchingPosition(
  *
  * Inputs are non-negative magnitudes.
  *
- * @throws {PerpsError} `ValidationError` when an input is not a decimal string.
+ * @throws {PerpsError} `ValidationError` when an input does not match the decimal pattern.
  * @public
  */
 export function resolveCloseSize(
@@ -440,7 +448,7 @@ export const safeResolveCloseSize = createSafeFunction(
  * Expected rPnL for a resting limit order against a matching position.
  *
  * Reducing requires opposite sides (long position + SELL, short position +
- * BUY). Same-side orders add to the position and have no rPnL → `null`.
+ * BUY). Same-side orders add to the position and have no rPnL → `undefined`.
  * Projects `remainingSize`, because an already-filled quantity has realised
  * its PnL at the fill price rather than at this order's limit price. A
  * `remainingSize` of zero leaves nothing to project.
@@ -448,9 +456,9 @@ export const safeResolveCloseSize = createSafeFunction(
 function regularOrderRealizedPnl(
   order: RegularOrder,
   position: Position | undefined
-): string | null {
+): string | undefined {
   if (!position || !isActiveOrderStatus(order.status)) {
-    return null
+    return undefined
   }
 
   const isLong = position.side === PositionSide.LONG
@@ -458,23 +466,23 @@ function regularOrderRealizedPnl(
     (isLong && order.side === OrderSide.SELL) ||
     (!isLong && order.side === OrderSide.BUY)
   if (!reducesPosition) {
-    return null
+    return undefined
   }
 
   if (order.price === undefined) {
-    return null
+    return undefined
   }
   const orderSize = decimalStringToBig(order.remainingSize).abs()
   const positionSize = decimalStringToBig(position.size).abs()
   if (positionSize.lte(0)) {
-    return null
+    return undefined
   }
 
   // `resolveCloseSize` reads a zero size as "close the whole position", a
   // convention that belongs to an order's submitted size. `remainingSize` is
   // the unfilled quantity, so zero means nothing is left to fill.
   if (orderSize.eq(0)) {
-    return null
+    return undefined
   }
 
   return calculateRealizedPnl({
@@ -492,14 +500,14 @@ function regularOrderRealizedPnl(
 function triggerOrderRealizedPnl(
   order: TriggerOrder,
   position: Position | undefined
-): string | null {
+): string | undefined {
   if (
     !position ||
     order.triggerPrice === undefined ||
     !isActiveOrderStatus(order.status) ||
     order.status === OrderStatus.PENDING
   ) {
-    return null
+    return undefined
   }
 
   const isLong = position.side === PositionSide.LONG
@@ -507,18 +515,18 @@ function triggerOrderRealizedPnl(
     (isLong && order.side !== OrderSide.SELL) ||
     (!isLong && order.side !== OrderSide.BUY)
   ) {
-    return null
+    return undefined
   }
   const orderSize = decimalStringToBig(order.remainingSize).abs()
   const positionSize = decimalStringToBig(position.size).abs()
   if (positionSize.lte(0)) {
-    return null
+    return undefined
   }
   if (
     orderSize.eq(0) &&
     (!decimalStringToBig(order.originalSize).eq(0) || !order.reduceOnly)
   ) {
-    return null
+    return undefined
   }
 
   return calculateRealizedPnl({
@@ -539,22 +547,22 @@ function triggerOrderRealizedPnl(
  * nothing.
  *
  * @returns Realised PnL if the order would reduce the position, otherwise
- *   `null`.
+ *   `undefined`.
  * @throws {PerpsError} `ValidationError` when a price or size on the order or
- *   the position is not a decimal string.
+ *   the position does not match the decimal pattern.
  * @public
  */
 export function estimateRealizedPnl(
   order: Order,
   position: Position | undefined
-): string | null {
+): string | undefined {
   if (isTriggerOrder(order)) {
     return triggerOrderRealizedPnl(order, position)
   }
   if (isRegularOrder(order)) {
     return regularOrderRealizedPnl(order, position)
   }
-  return null
+  return undefined
 }
 
 /** @public */