@lifi/perps-sdk 23.1.0 → 25.0.0

package/src/wire/refuel.ts

@@ -1,32 +1,55 @@
 import { type DecimalString, PerpsErrorCode } from '@lifi/perps-types'
+import type Big from 'big.js'
 import { DivBig } from '../decimal/big.js'
-import { requireDecimal } from '../decimal/requireDecimal.js'
+import { BASE_UNITS_PATTERN } from '../decimal/convert.js'
+import { decimalStringToDivBig } from '../decimal/decimalStringToBig.js'
 import { PerpsError } from '../errors/PerpsError.js'
 
+/**
+ * Headroom, in percent, that {@link calculateRefuelAmount} adds over the gas
+ * deficit to pay the refuel route's own swap and bridge fees.
+ *
+ * @public
+ */
+export const REFUEL_FEE_MARGIN_PERCENT = 20
+
 /** @public */
 export interface RefuelAmountInput {
-  /** USD value of the gas the route recommends. */
-  gasUsd: DecimalString
+  /** Native gas amount the LI.FI gas suggestion recommends, in base units. */
+  recommendedAmount: DecimalString
+  /** USD value of `recommendedAmount`. */
+  recommendedUsd: DecimalString
+  /** Native balance the wallet holds on the recommendation's chain, in base units. */
+  nativeBalance: DecimalString
   /** USD price of one whole source token. */
   priceUsd: DecimalString
   /** Decimals of the source token, which the result is spelled to exactly. */
   decimals: number
 }
 
+function requireBaseUnits(value: DecimalString, field: string): Big {
+  if (!BASE_UNITS_PATTERN.test(value)) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Invalid \`${field}\`: '${value}' is not an integer base-unit string.`
+    )
+  }
+  return new DivBig(value)
+}
+
 /**
- * Source-token amount whose USD value covers `gasUsd`, rounded **up** onto
- * the token's decimal grid so a refuel never lands short of the
- * recommendation. The result keeps trailing zeros to `decimals`, so it seeds
- * an amount input at the token's own precision.
- *
- * The quotient does not terminate for most prices, which is why this is a
- * big.js primitive: an 18-decimal token needs a ceiling at 10^-18, far past
- * what a `number` can carry.
+ * Source-token amount that buys the native gas the wallet lacks: the part of
+ * the recommendation above `nativeBalance`, valued pro rata on
+ * `recommendedUsd`, plus {@link REFUEL_FEE_MARGIN_PERCENT}. Rounded **up**
+ * onto the token's decimal grid so a refuel never lands short, and spelled
+ * with trailing zeros to `decimals` to seed an amount input.
  *
- * @returns `undefined` when `gasUsd` or `priceUsd` is not greater than zero,
- *   which is a route with nothing to refuel rather than a failure.
- * @throws {PerpsError} `ValidationError` when `gasUsd` or `priceUsd` is not a
- *   {@link DecimalString}, or when `decimals` is not a non-negative integer.
+ * @returns `undefined` when the wallet already holds the recommendation, or
+ *   when `recommendedAmount`, `recommendedUsd` or `priceUsd` is not greater
+ *   than zero: a route with nothing to refuel, not a failure.
+ * @throws {PerpsError} `ValidationError` when a base-unit field is not an
+ *   integer string, a USD field does not match the decimal pattern, or `decimals`
+ *   is not a non-negative integer.
  * @public
  */
 export function calculateRefuelAmount(
@@ -39,13 +62,26 @@ export function calculateRefuelAmount(
       `Invalid \`decimals\` for a refuel amount: ${decimals}`
     )
   }
-  const gasUsd = requireDecimal(input.gasUsd, 'gasUsd')
-  const priceUsd = requireDecimal(input.priceUsd, 'priceUsd')
-  if (!gasUsd.gt(0) || !priceUsd.gt(0)) {
+  const recommended = requireBaseUnits(
+    input.recommendedAmount,
+    'recommendedAmount'
+  )
+  const balance = requireBaseUnits(input.nativeBalance, 'nativeBalance')
+  const recommendedUsd = decimalStringToDivBig(input.recommendedUsd)
+  const priceUsd = decimalStringToDivBig(input.priceUsd)
+  const deficit = recommended.minus(balance)
+  if (
+    !recommended.gt(0) ||
+    !recommendedUsd.gt(0) ||
+    !priceUsd.gt(0) ||
+    !deficit.gt(0)
+  ) {
     return undefined
   }
-  return new DivBig(gasUsd)
-    .div(priceUsd)
+  return recommendedUsd
+    .times(deficit)
+    .times(100 + REFUEL_FEE_MARGIN_PERCENT)
+    .div(recommended.times(100).times(priceUsd))
     .round(decimals, DivBig.roundUp)
     .toFixed(decimals)
 }

package/src/wire/transferable.ts

@@ -1,5 +1,5 @@
 import type { DecimalString } from '@lifi/perps-types'
-import { requireDecimal } from '../decimal/requireDecimal.js'
+import { decimalStringToBig } from '../decimal/decimalStringToBig.js'
 
 /**
  * The part of `units` that a venue-wide free figure releases: never below
@@ -9,16 +9,16 @@ import { requireDecimal } from '../decimal/requireDecimal.js'
  * @param venueFigure - The venue's free figure for the category, which can
  *   exceed `units` or fall below zero.
  * @param units - Units held in the category, the upper bound of the clamp.
- * @throws {PerpsError} `ValidationError` when either input is not a
- *   {@link DecimalString}, naming the field.
+ * @throws {PerpsError} `ValidationError` when either input does not match the
+ *   decimal pattern, naming the field.
  * @public
  */
 export function calculateTransferable(
   venueFigure: DecimalString,
   units: DecimalString
 ): DecimalString {
-  const figure = requireDecimal(venueFigure, 'venueFigure')
-  const held = requireDecimal(units, 'units')
+  const figure = decimalStringToBig(venueFigure)
+  const held = decimalStringToBig(units)
   if (figure.lt(0)) {
     return '0'
   }

package/src/wire/withdraw.ts

@@ -1,5 +1,5 @@
 import type { DecimalString } from '@lifi/perps-types'
-import { requireDecimal } from '../decimal/requireDecimal.js'
+import { decimalStringToBig } from '../decimal/decimalStringToBig.js'
 import type { WithdrawableBalance } from '../types/withdrawal.js'
 
 /**
@@ -18,12 +18,10 @@ export function calculateWithdrawMax(
     'available' | 'withdrawalFee' | 'isFeeDeducted'
   >
 ): DecimalString {
-  const available = requireDecimal(row.available, 'available')
+  const available = decimalStringToBig(row.available)
   if (row.isFeeDeducted !== false || row.withdrawalFee === undefined) {
     return available.toFixed()
   }
-  const funded = available.minus(
-    requireDecimal(row.withdrawalFee, 'withdrawalFee')
-  )
+  const funded = available.minus(decimalStringToBig(row.withdrawalFee))
   return funded.gt(0) ? funded.toFixed() : '0'
 }

package/dist/cjs/decimal/requireDecimal.d.ts

@@ -1,4 +0,0 @@
-import type { DecimalString } from '@lifi/perps-types';
-import Big from 'big.js';
-export declare function requireDecimal(value: DecimalString, field: string): Big;
-//# sourceMappingURL=requireDecimal.d.ts.map

package/dist/cjs/decimal/requireDecimal.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"requireDecimal.d.ts","sourceRoot":"","sources":["../../../src/decimal/requireDecimal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,GAAG,MAAM,QAAQ,CAAA;AAIxB,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,GAAG,CAEvE"}

package/dist/cjs/decimal/requireDecimal.js

@@ -1,12 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.requireDecimal = requireDecimal;
-const big_js_1 = __importDefault(require("big.js"));
-const parse_js_1 = require("./parse.js");
-function requireDecimal(value, field) {
-    return new big_js_1.default((0, parse_js_1.validateDecimalString)(value, field));
-}
-//# sourceMappingURL=requireDecimal.js.map

package/dist/cjs/decimal/requireDecimal.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"requireDecimal.js","sourceRoot":"","sources":["../../../src/decimal/requireDecimal.ts"],"names":[],"mappings":";;;;;AAKA,wCAEC;AAND,oDAAwB;AACxB,yCAAkD;AAGlD,SAAgB,cAAc,CAAC,KAAoB,EAAE,KAAa;IAChE,OAAO,IAAI,gBAAG,CAAC,IAAA,gCAAqB,EAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAA;AACrD,CAAC"}

package/dist/esm/decimal/requireDecimal.d.ts

@@ -1,5 +0,0 @@
-import type { DecimalString } from '@lifi/perps-types';
-import Big from 'big.js';
-/** Parse a decimal input after {@link validateDecimalString} accepts it. */
-export declare function requireDecimal(value: DecimalString, field: string): Big;
-//# sourceMappingURL=requireDecimal.d.ts.map

package/dist/esm/decimal/requireDecimal.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"requireDecimal.d.ts","sourceRoot":"","sources":["../../../src/decimal/requireDecimal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,GAAG,MAAM,QAAQ,CAAA;AAGxB,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,GAAG,CAEvE"}

package/dist/esm/decimal/requireDecimal.js

@@ -1,7 +0,0 @@
-import Big from 'big.js';
-import { validateDecimalString } from './parse.js';
-/** Parse a decimal input after {@link validateDecimalString} accepts it. */
-export function requireDecimal(value, field) {
-    return new Big(validateDecimalString(value, field));
-}
-//# sourceMappingURL=requireDecimal.js.map

package/dist/esm/decimal/requireDecimal.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"requireDecimal.js","sourceRoot":"","sources":["../../../src/decimal/requireDecimal.ts"],"names":[],"mappings":"AACA,OAAO,GAAG,MAAM,QAAQ,CAAA;AACxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAElD,4EAA4E;AAC5E,MAAM,UAAU,cAAc,CAAC,KAAoB,EAAE,KAAa;IAChE,OAAO,IAAI,GAAG,CAAC,qBAAqB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAA;AACrD,CAAC"}

package/dist/types/decimal/requireDecimal.d.ts

@@ -1,5 +0,0 @@
-import type { DecimalString } from '@lifi/perps-types';
-import Big from 'big.js';
-/** Parse a decimal input after {@link validateDecimalString} accepts it. */
-export declare function requireDecimal(value: DecimalString, field: string): Big;
-//# sourceMappingURL=requireDecimal.d.ts.map

package/dist/types/decimal/requireDecimal.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"requireDecimal.d.ts","sourceRoot":"","sources":["../../../src/decimal/requireDecimal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,GAAG,MAAM,QAAQ,CAAA;AAGxB,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,GAAG,CAEvE"}

package/src/decimal/requireDecimal.ts

@@ -1,8 +0,0 @@
-import type { DecimalString } from '@lifi/perps-types'
-import Big from 'big.js'
-import { validateDecimalString } from './parse.js'
-
-/** Parse a decimal input after {@link validateDecimalString} accepts it. */
-export function requireDecimal(value: DecimalString, field: string): Big {
-  return new Big(validateDecimalString(value, field))
-}