@pear-protocol/utils 1.3.0 → 1.5.0

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export * from './position/index';
 export * from './precise-price';
 export * from './precise-quantity';
 export * from './proxy';
+export * from './reduce-only-minimum';
 export * from './sync/index';
 export * from './validate-leverage';
 export * from './validate-quantity';

package/dist/index.js

@@ -1188,21 +1188,56 @@ BigNumber7.config({
   DECIMAL_PLACES: 30,
   ROUNDING_MODE: BigNumber7.ROUND_DOWN
 });
-function precisePrice(connector, raw, precision, side = "BUY", slippageToleranceBps = 0) {
+var InvalidPriceError = class extends Error {
+  static {
+    __name(this, "InvalidPriceError");
+  }
+};
+function precisePrice(connector, raw, precision, side = "BUY", slippageToleranceBps = 0, rounding = "marketable") {
   const normalized = normalizePrice(raw);
+  if (!normalized.isFinite() || !normalized.isGreaterThan(0)) {
+    throw new InvalidPriceError(`Price ${String(raw)} is not a positive, finite price`);
+  }
   const effectiveRaw = withSlippageTolerance(normalized, slippageToleranceBps, side);
+  const roundingMode = resolveRoundingMode(side, rounding);
+  const precise = preciseOnGrid(connector, effectiveRaw, precision, roundingMode);
+  const clampsToOneStep = rounding === "marketable" && side === "SELL" && !new BigNumber7(precise).isGreaterThan(0);
+  const result = clampsToOneStep ? smallestGridPrice(connector, precision) : precise;
+  const resultBN = new BigNumber7(result);
+  if (!resultBN.isFinite() || !resultBN.isGreaterThan(0)) {
+    throw new InvalidPriceError(`Price ${effectiveRaw.toFixed()} has no valid ${side} price on the grid`);
+  }
+  return result;
+}
+__name(precisePrice, "precisePrice");
+function preciseOnGrid(connector, price, precision, rounding) {
   switch (connector) {
     case "hyperliquid":
-      return preciseHyperliquidPrice(effectiveRaw, precision, side);
+      return preciseHyperliquidPrice(price, precision, rounding);
     case "binance":
     case "bybit":
     case "okx":
     case "lighter":
     case "lighter_rhc":
-      return preciseTickGridPrice(effectiveRaw, precision, side);
+      return preciseTickGridPrice(price, precision, rounding);
   }
 }
-__name(precisePrice, "precisePrice");
+__name(preciseOnGrid, "preciseOnGrid");
+function smallestGridPrice(connector, precision) {
+  return preciseOnGrid(connector, new BigNumber7(1).shiftedBy(-precision.price.decimals), precision, BigNumber7.ROUND_CEIL);
+}
+__name(smallestGridPrice, "smallestGridPrice");
+function resolveRoundingMode(side, rounding) {
+  switch (rounding) {
+    // Towards crossing: the buffer survives rounding.
+    case "marketable":
+      return side === "BUY" ? BigNumber7.ROUND_CEIL : BigNumber7.ROUND_FLOOR;
+    // Away from crossing: the limit holds.
+    case "within_limit":
+      return side === "BUY" ? BigNumber7.ROUND_FLOOR : BigNumber7.ROUND_CEIL;
+  }
+}
+__name(resolveRoundingMode, "resolveRoundingMode");
 function withSlippageTolerance(normalized, slippageToleranceBps, side) {
   if (slippageToleranceBps === 0) {
     return normalized;
@@ -1212,18 +1247,16 @@ function withSlippageTolerance(normalized, slippageToleranceBps, side) {
   return side === "BUY" ? normalized.times(new BigNumber7(1).plus(factor)) : normalized.times(new BigNumber7(1).minus(factor));
 }
 __name(withSlippageTolerance, "withSlippageTolerance");
-function preciseHyperliquidPrice(price, precision, side) {
+function preciseHyperliquidPrice(price, precision, rounding) {
   const maxDecimals = precision.price.decimals;
   const maxSigFigs = precision.price.sigFigs ?? 5;
-  const rounding = side === "BUY" ? BigNumber7.ROUND_FLOOR : BigNumber7.ROUND_CEIL;
   price = price.decimalPlaces(maxDecimals, rounding);
   price = clampSigFigs(price, maxSigFigs, maxDecimals, rounding);
   return price.toFixed();
 }
 __name(preciseHyperliquidPrice, "preciseHyperliquidPrice");
-function preciseTickGridPrice(price, precision, side) {
+function preciseTickGridPrice(price, precision, rounding) {
   const tick = precision.price.tick ?? 1e-4;
-  const rounding = side === "BUY" ? BigNumber7.ROUND_FLOOR : BigNumber7.ROUND_CEIL;
   const tickBN = new BigNumber7(tick);
   const scaled = price.div(tickBN);
   const snapped = scaled.integerValue(rounding).times(tickBN);
@@ -1237,13 +1270,13 @@ function clampSigFigs(price, maxSigFigs, maxDecimals, rounding) {
   if (countSigFigs(price) <= maxSigFigs) {
     return price;
   }
-  for (let decimals = maxDecimals; decimals >= 0; decimals--) {
+  for (let decimals = maxDecimals; decimals >= 1; decimals--) {
     const candidate = price.decimalPlaces(decimals, rounding);
     if (countSigFigs(candidate) <= maxSigFigs) {
       return candidate;
     }
   }
-  return price;
+  return price.decimalPlaces(0, rounding);
 }
 __name(clampSigFigs, "clampSigFigs");
 function normalizePrice(value) {
@@ -1330,6 +1363,85 @@ function proxyFetch(input, init) {
   }), () => fetch(input, init));
 }
 __name(proxyFetch, "proxyFetch");
+function validateQuantity(quantity, price, precision) {
+  const parsedQuantity = new BigNumber7(quantity);
+  if (!parsedQuantity.isFinite() || parsedQuantity.lte(0)) {
+    return false;
+  }
+  const parsedPrice = new BigNumber7(price);
+  if (!parsedPrice.isFinite() || parsedPrice.lte(0)) {
+    return false;
+  }
+  const step = new BigNumber7(precision.quantity.step);
+  const scaled = parsedQuantity.div(step);
+  if (!scaled.isInteger()) {
+    return false;
+  }
+  const minQuantity = precision.quantity.min;
+  if (minQuantity !== void 0 && minQuantity !== null && parsedQuantity.lt(minQuantity)) {
+    return false;
+  }
+  const notional = contractsToBase(parsedQuantity, precision.quantity.contractSize).times(parsedPrice);
+  if (precision.notional?.min !== void 0 && precision.notional.min !== null && precision.notional.min > 0) {
+    if (notional.lt(new BigNumber7(precision.notional.min))) {
+      return false;
+    }
+  }
+  if (precision.notional?.max !== void 0 && precision.notional.max !== null && precision.notional.max > 0) {
+    if (notional.gt(new BigNumber7(precision.notional.max))) {
+      return false;
+    }
+  }
+  return true;
+}
+__name(validateQuantity, "validateQuantity");
+
+// src/reduce-only-minimum.ts
+function findWholeCloseQuantity(input) {
+  if (input.heldByAnotherPosition) {
+    return void 0;
+  }
+  if (input.exposure === void 0 || isZero(input.exposure)) {
+    return void 0;
+  }
+  if (input.side === "BUY" !== isNegative(input.exposure)) {
+    return void 0;
+  }
+  const { step, contractSize } = input.precision.quantity;
+  const exposureQuantity = divide(abs(input.exposure), String(contractSize));
+  const coversExposure = isGreaterThanOrEqual(input.quantity, exposureQuantity);
+  const requestsExposure = isGreaterThanOrEqual(input.requestedQuantity, abs(input.exposure));
+  const roundedShort = isGreaterThan(input.requestedQuantity, subtract(abs(input.exposure), multiply(String(step), String(contractSize))));
+  const refusedShort = roundedShort && !validateQuantity(input.quantity, input.price, input.precision);
+  if (!coversExposure && !requestsExposure && !refusedShort) {
+    return void 0;
+  }
+  const steps = divide(exposureQuantity, String(step)).integerValue(BigNumber7.ROUND_CEIL);
+  return multiply(steps, String(step)).toFixed();
+}
+__name(findWholeCloseQuantity, "findWholeCloseQuantity");
+function requestedBaseQuantity(leg, referencePrice) {
+  switch (leg.mode) {
+    case "QUANTITY":
+      return leg.amount;
+    case "USD":
+      return divide(leg.amount, referencePrice).toFixed();
+  }
+}
+__name(requestedBaseQuantity, "requestedBaseQuantity");
+function isRefusedBelowMinimum(quantity, price, precision, heldByAnotherPosition) {
+  if (!heldByAnotherPosition) {
+    return false;
+  }
+  const minQuantity = precision.quantity.min;
+  if (minQuantity !== void 0 && minQuantity !== null && isLessThan(quantity, String(minQuantity))) {
+    return true;
+  }
+  const notional = multiply(contractsToBase(quantity, precision.quantity.contractSize), price);
+  const minNotional = precision.notional?.min;
+  return minNotional !== void 0 && minNotional !== null && isLessThan(notional, String(minNotional));
+}
+__name(isRefusedBelowMinimum, "isRefusedBelowMinimum");
 
 // src/sync/applicables/constants.ts
 var DUST = parse("0.00000001");
@@ -1674,7 +1786,7 @@ function buildMissedHistoryFills(args) {
     });
     result.push({
       connector,
-      exchangeFillId: `${MISSED_HISTORY_FILL_PREFIX}${symbol}-${gap.side.toLowerCase()}`,
+      exchangeFillId: `${MISSED_HISTORY_FILL_PREFIX}${symbol}-${gap.side.toLowerCase()}-${watermark}`,
       cloid: null,
       symbol,
       price,
@@ -2658,34 +2770,6 @@ function validateLeverage(leverage, instrument) {
   return true;
 }
 __name(validateLeverage, "validateLeverage");
-function validateQuantity(quantity, price, precision) {
-  const parsedQuantity = new BigNumber7(quantity);
-  if (!parsedQuantity.isFinite() || parsedQuantity.lte(0)) {
-    return false;
-  }
-  const parsedPrice = new BigNumber7(price);
-  if (!parsedPrice.isFinite() || parsedPrice.lte(0)) {
-    return false;
-  }
-  const step = new BigNumber7(precision.quantity.step);
-  const scaled = parsedQuantity.div(step);
-  if (!scaled.isInteger()) {
-    return false;
-  }
-  const notional = contractsToBase(parsedQuantity, precision.quantity.contractSize).times(parsedPrice);
-  if (precision.notional?.min !== void 0 && precision.notional.min !== null && precision.notional.min > 0) {
-    if (notional.lt(new BigNumber7(precision.notional.min))) {
-      return false;
-    }
-  }
-  if (precision.notional?.max !== void 0 && precision.notional.max !== null && precision.notional.max > 0) {
-    if (notional.gt(new BigNumber7(precision.notional.max))) {
-      return false;
-    }
-  }
-  return true;
-}
-__name(validateQuantity, "validateQuantity");
 var VAULT_ACTION_DOMAIN = {
   name: "PearVaultService",
   version: "1",
@@ -2997,4 +3081,4 @@ function takeVerifier(handoffId, storage) {
 }
 __name(takeVerifier, "takeVerifier");
 
-export { BIPS, CREATE_VAULT_TYPES, VAULT_ACTION_DOMAIN, VAULT_ACTION_TYPES, ZERO, abs, add, aggregateRealizedPositionState, baseToContracts, buildApplicables, buildCreateVaultMessage, buildLeaderActionTypedData, compareValue, computeAssetEntryNotional, computeAssetGrossRealizedPnL, computeAssetRealizedPnLs, computeAssetUndeterminedSizes, computeAssetUnrealizedPnL, computeAssetUnrealizedPnLs, computeBasketWeightedRatioV1, computeDeployedCapital, computeDeployedCapitalState, computeEntryEquityFraction, computeEntryPriceForAsset, computeEquityFraction, computeFillTransitions, computeFilledEntrySizing, computeMaxBasketSize, computeMultiQuoteBasketSize, computeNotionalEquityFraction, computePositionEntryPrices, computeRealizedPnlBySymbol, computeRealizedPnlFromFills, computeRealizedPositionState, computeSyncPayload, computeUnrealizedPositionState, computeUnrealizedPositionStateFromEntryPrices, configureProxy, contractsToBase, countDecimals, deriveBasketKey, divide, exponentiate, finishXHandoff, generateDeterministicPositionKey, groupFillsByAsset, groupFillsByPosition, isEqualTo, isFiniteDecimal, isGreaterThan, isGreaterThanOrEqual, isLessThan, isLessThanOrEqual, isNegative, isPositive, isZero, min, multiply, negate, parse, precisePrice, preciseQuantity, proxyFetch, sideSign, sign, signed, signedBySide, sizeBasket, sizeBasketByLeverageMode, sizeBasketPerAssetLeverage, startXHandoff, stripXReturn, subtract, sumAttributedFunding, toDecimalString, validateLeverage, validateQuantity, walkPositionLedger, walkPositionTransitions };
+export { BIPS, CREATE_VAULT_TYPES, InvalidPriceError, VAULT_ACTION_DOMAIN, VAULT_ACTION_TYPES, ZERO, abs, add, aggregateRealizedPositionState, baseToContracts, buildApplicables, buildCreateVaultMessage, buildLeaderActionTypedData, compareValue, computeAssetEntryNotional, computeAssetGrossRealizedPnL, computeAssetRealizedPnLs, computeAssetUndeterminedSizes, computeAssetUnrealizedPnL, computeAssetUnrealizedPnLs, computeBasketWeightedRatioV1, computeDeployedCapital, computeDeployedCapitalState, computeEntryEquityFraction, computeEntryPriceForAsset, computeEquityFraction, computeFillTransitions, computeFilledEntrySizing, computeMaxBasketSize, computeMultiQuoteBasketSize, computeNotionalEquityFraction, computePositionEntryPrices, computeRealizedPnlBySymbol, computeRealizedPnlFromFills, computeRealizedPositionState, computeSyncPayload, computeUnrealizedPositionState, computeUnrealizedPositionStateFromEntryPrices, configureProxy, contractsToBase, countDecimals, deriveBasketKey, divide, exponentiate, findWholeCloseQuantity, finishXHandoff, generateDeterministicPositionKey, groupFillsByAsset, groupFillsByPosition, isEqualTo, isFiniteDecimal, isGreaterThan, isGreaterThanOrEqual, isLessThan, isLessThanOrEqual, isNegative, isPositive, isRefusedBelowMinimum, isZero, min, multiply, negate, parse, precisePrice, preciseQuantity, proxyFetch, requestedBaseQuantity, sideSign, sign, signed, signedBySide, sizeBasket, sizeBasketByLeverageMode, sizeBasketPerAssetLeverage, startXHandoff, stripXReturn, subtract, sumAttributedFunding, toDecimalString, validateLeverage, validateQuantity, walkPositionLedger, walkPositionTransitions };

package/dist/precise-price.d.ts

@@ -1,8 +1,30 @@
 import type { Connector, InstrumentPrecision, Side } from '@pear-protocol/types';
 import BigNumber from 'bignumber.js';
+/**
+ * Which way a price is rounded onto the exchange grid.
+ * - `marketable`: towards crossing (BUY up, SELL down), so a market order keeps its slippage buffer
+ *   and still reaches the opposite touch; it may cost up to one grid step beyond the buffer (#785).
+ * - `within_limit`: away from crossing (BUY down, SELL up), so a user-set limit is never exceeded.
+ */
+export type PriceRounding = 'marketable' | 'within_limit';
+/**
+ * A price `precisePrice` produced: on the venue's grid and greater than zero (#1157), so it can be an
+ * order's limit. USD sizing deliberately does not require it: an unconstrained leg is sized off the
+ * unpadded mid, a raw reference price (#1145). It is still a string, so it passes anywhere a string is
+ * accepted, `validateQuantity` included.
+ */
+export type GridPrice = string & {
+    readonly __brand: 'GridPrice';
+};
+/**
+ * Thrown by `precisePrice` when no placeable price exists: a raw price that is not positive and
+ * finite, or a limit that rounds to zero on the grid (a BUY cap below one grid step).
+ */
+export declare class InvalidPriceError extends Error {
+}
 /**
  * Round a raw price to an exchange-valid string for the given connector,
- * biased so the order stays marketable (BUY rounds down, SELL rounds up),
- * optionally padded with slippage tolerance first.
+ * optionally padded with slippage tolerance first, biased per `rounding`.
+ * The result is always on the grid and above zero; otherwise this throws `InvalidPriceError`.
  */
-export declare function precisePrice(connector: Connector, raw: BigNumber.Value, precision: InstrumentPrecision, side?: Side, slippageToleranceBps?: number): string;
+export declare function precisePrice(connector: Connector, raw: BigNumber.Value, precision: InstrumentPrecision, side?: Side, slippageToleranceBps?: number, rounding?: PriceRounding): GridPrice;

package/dist/reduce-only-minimum.d.ts

@@ -0,0 +1,42 @@
+/** When a reduce-only order is held to the venue minimum (#1184). Pure, so the backend and the frontend share one rule. */
+import type { InstrumentPrecision, Side } from '@pear-protocol/types';
+/**
+ * The quantity that closes the whole venue position a reduce-only leg reduces, or undefined when the leg
+ * is only a partial reduce. Under #1184's rule a whole close is the only reduce-only order exempt from the
+ * venue minimum; this is Pear's product rule, not a venue constraint (Binance, for one, exempts every
+ * reduce-only order from its minimum order value, -4164, though not from its minimum quantity, -4004).
+ *
+ * The venue nets every position of the account holding the asset, so the leg is a whole close only when no
+ * other position holds the asset, its side opposes the exposure (a BUY closes a short, a SELL a long), and
+ * it covers the exposure: its rounded quantity reaches it, the quantity requested before rounding reaches it
+ * (so a request for the whole position always closes it), or that request falls short of it by less than
+ * one step and the rounded partial would be refused at the order price, so a USD amount sized at a slightly
+ * different price that rounds a step short below the minimum still closes it, while a partial the venue
+ * accepts, or an exact reduce of one step less, stays partial. A whole close is
+ * the exposure rounded up onto the venue's step grid; the venue caps reduce-only at the position. The
+ * quantity and the returned quantity are in the venue's contract units (base units where a contract is one
+ * unit); the requested quantity and the exposure are in base units.
+ */
+export declare function findWholeCloseQuantity(input: {
+    quantity: string;
+    requestedQuantity: string;
+    side: Side;
+    exposure: string | undefined;
+    price: string;
+    precision: InstrumentPrecision;
+    heldByAnotherPosition: boolean;
+}): string | undefined;
+/**
+ * The base quantity a leg asked for before venue rounding: a quantity leg's own amount, a USD leg's amount
+ * at the price it is sized against.
+ */
+export declare function requestedBaseQuantity(leg: {
+    mode: 'QUANTITY' | 'USD';
+    amount: string;
+}, referencePrice: string): string;
+/**
+ * Whether a close leg is refused for its size. A close places the position's whole exposure, so it closes
+ * the venue position, valid at any size, unless another position holds the asset: then the venue reads it
+ * as a partial reduce, held to its minimum order quantity and minimum order value at the order price (#1184).
+ */
+export declare function isRefusedBelowMinimum(quantity: string, price: string, precision: InstrumentPrecision, heldByAnotherPosition: boolean): boolean;

package/dist/validate-quantity.d.ts

@@ -1,6 +1,7 @@
 import type { InstrumentPrecision } from '@pear-protocol/types';
 /**
- * True when an order quantity is positive, step-aligned, and within the
- * instrument's optional notional bounds at the given price.
+ * True when an order quantity is positive, step-aligned, at or above the venue's
+ * optional minimum order quantity, and within the instrument's optional notional
+ * bounds at the given price.
  */
 export declare function validateQuantity(quantity: string, price: string, precision: InstrumentPrecision): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pear-protocol/utils",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Pear Protocol Utility functions",
   "private": false,
   "type": "module",
@@ -23,11 +23,11 @@
     "test": "vitest run",
     "build": "tsup && tsc -p tsconfig.build.json",
     "clean": "rm -rf dist .turbo",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "bunx --package bun@1.4.3 bun --check --threads=2"
   },
   "dependencies": {
     "@noble/hashes": "^1.3.2",
-    "@pear-protocol/types": "^2.12.0",
+    "@pear-protocol/types": "^2.21.0",
     "@scure/base": "^2.3.0",
     "bignumber.js": "9.3.1"
   },