@pear-protocol/utils 0.5.2 → 0.6.0

package/dist/basket/basket.types.d.ts

@@ -1,6 +1,56 @@
-import type { InstrumentId, Side } from '@pear-protocol/types';
+import type { HttpTypes, InstrumentId, Side } from '@pear-protocol/types';
 export type BasketLeg = {
     symbol: InstrumentId;
     side: Side;
     weight: number;
 };
+/**
+ * Mirrors the shipped basket model (`BasketItem` in the frontend): unsigned `weight`
+ * with `side` alongside, weights summing to 100. Sizing ignores `side` — margin
+ * requirement does not depend on direction — and normalises by Σweight.
+ */
+export type MaxBasketSizeLeg = {
+    asset: InstrumentId;
+    side: Side;
+    /** Unsigned percentage. The set sums to 100. */
+    weight: number;
+};
+export type MaxBasketSizeInput = {
+    legs: MaxBasketSizeLeg[];
+    /** What the caller is requesting for the whole basket, before each leg's own venue max caps it. */
+    requestedLeverage: number;
+};
+export type MaxBasketSizeResult = {
+    /**
+     * The whole basket's max GROSS notional in USD — Σ leg notional, not per-side and not per-asset.
+     * The basket is atomic, so this is one ceiling for the entire structure, not a per-leg maximum.
+     * Null when the caller could not supply an available balance, or a leg names an asset the
+     * caller's max-leverage map does not list.
+     */
+    maxNotional: string | null;
+    /**
+     * The margin `maxNotional` spends — always the whole `budget`/`availableBalance` the caller
+     * supplied, since that is exactly the point at which the basket stops growing. Stated explicitly
+     * rather than left for the caller to infer, and `null` on the same terms as `maxNotional`.
+     */
+    marginRequired: string | null;
+};
+/** One basket leg with its leverage already capped by the caller. */
+export type CappedBasketLeg = {
+    /** Unsigned, in the caller's own scale — `computeMaxBasketSize` normalises by Σweight. */
+    weight: number;
+    effectiveLeverage: string;
+};
+/** The one margin budget every leg funds out of. */
+export type MaxBasketSizeCalculation = {
+    /** USD-equivalent margin available. Every connector this sizes for funds a basket from one balance. */
+    budget: string;
+    legs: CappedBasketLeg[];
+};
+/** What `sizeSinglePoolBasket` needs beyond the legs: the account's balance and the leverage ceilings. */
+export type SinglePoolSizingContext = {
+    /** The account's whole available margin, or `null` when the caller could not read one. */
+    availableBalance: string | null;
+    /** Off the core-sdk instrument catalog — only `id` and `leverage` are read. */
+    instruments: Pick<HttpTypes.Instrument, 'id' | 'leverage'>[];
+};

package/dist/basket/index.d.ts

@@ -1,2 +1,4 @@
+export * from './basket.types';
 export * from './compute';
 export * from './derive-basket-key';
+export * from './max-size';

package/dist/basket/max-size.d.ts

@@ -0,0 +1,18 @@
+import type { MaxBasketSizeCalculation, MaxBasketSizeInput, MaxBasketSizeResult, SinglePoolSizingContext } from './basket.types';
+/**
+ * The largest gross notional this basket can reach while every leg stays funded at its weight.
+ *
+ * Takes the caller's figures as given — a malformed budget or leverage is the caller's own
+ * responsibility to keep clean (enforce it with a schema at the boundary if that matters to you),
+ * not something this function guards against.
+ */
+export declare function computeMaxBasketSize(input: MaxBasketSizeCalculation): MaxBasketSizeResult;
+/**
+ * Sizes a basket that funds every leg out of one account-wide balance and caps leverage at nothing
+ * but the caller-supplied max: `effectiveLeverage = min(requested, catalogMax)`.
+ *
+ * A leg naming an asset the caller's catalog does not list leaves its ceiling unknown, and sizing
+ * against the request alone would overstate the basket — so one unknown leg (or no available
+ * balance at all) reports no size rather than a wrong one.
+ */
+export declare function sizeSinglePoolBasket(input: MaxBasketSizeInput, context: SinglePoolSizingContext): MaxBasketSizeResult;

package/dist/index.js

@@ -328,6 +328,81 @@ function deriveBasketKey(longInstrumentIds, shortInstrumentIds) {
   return bytesToHex(sha256(new TextEncoder().encode(payload)));
 }
 __name(deriveBasketKey, "deriveBasketKey");
+
+// src/basket/max-size.ts
+function computeMaxBasketSize(input) {
+  const weightSum = sumWeights(input.legs);
+  if (isZero(weightSum)) {
+    return unsizedResult();
+  }
+  const shares = input.legs.map((leg) => toLegShare(leg, weightSum));
+  const size = divide(input.budget, marginPerUnitNotional(shares));
+  return {
+    maxNotional: size.toFixed(),
+    marginRequired: input.budget
+  };
+}
+__name(computeMaxBasketSize, "computeMaxBasketSize");
+function sizeSinglePoolBasket(input, context) {
+  if (context.availableBalance === null) {
+    return unsizedResult();
+  }
+  const maxLeverageById = new Map(context.instruments.map((instrument) => [
+    instrument.id,
+    instrument.leverage
+  ]));
+  const capped = [];
+  for (const leg of input.legs) {
+    const maxLeverage = maxLeverageById.get(leg.asset);
+    if (maxLeverage === void 0) {
+      return unsizedResult();
+    }
+    capped.push({
+      weight: leg.weight,
+      effectiveLeverage: cappedLeverage(input.requestedLeverage, maxLeverage)
+    });
+  }
+  return computeMaxBasketSize({
+    budget: context.availableBalance,
+    legs: capped
+  });
+}
+__name(sizeSinglePoolBasket, "sizeSinglePoolBasket");
+function cappedLeverage(requested, maxLeverage) {
+  const granted = min(String(requested), String(maxLeverage));
+  return isFiniteDecimal(granted) && granted.isGreaterThan(0) ? granted.toFixed() : "1";
+}
+__name(cappedLeverage, "cappedLeverage");
+function sumWeights(legs) {
+  let total = ZERO;
+  for (const leg of legs) {
+    total = add(total, String(leg.weight));
+  }
+  return total;
+}
+__name(sumWeights, "sumWeights");
+function unsizedResult() {
+  return {
+    maxNotional: null,
+    marginRequired: null
+  };
+}
+__name(unsizedResult, "unsizedResult");
+function toLegShare(leg, weightSum) {
+  return {
+    share: divide(String(leg.weight), weightSum),
+    imr: divide("1", leg.effectiveLeverage)
+  };
+}
+__name(toLegShare, "toLegShare");
+function marginPerUnitNotional(shares) {
+  let demand = ZERO;
+  for (const leg of shares) {
+    demand = add(demand, multiply(leg.share, leg.imr));
+  }
+  return demand;
+}
+__name(marginPerUnitNotional, "marginPerUnitNotional");
 function contractsToBase(contracts, contractSize) {
   return new BigNumber7(contracts).times(contractSize);
 }
@@ -1108,13 +1183,9 @@ function resolveLeftoverTarget(args) {
   const leftoverShorts = new Set(leftover.filter((entry) => entry.side === "SELL").map((entry) => entry.leg.symbol));
   const target = book.open().find((position) => {
     const { longs, shorts } = position.exposure.activeLegs();
-    const longOk = [
-      ...leftoverLongs
-    ].every((a) => longs.has(a));
-    const shortOk = [
-      ...leftoverShorts
-    ].every((a) => shorts.has(a));
-    return longOk && shortOk;
+    const sameActiveShape = setEq(leftoverLongs, longs) && setEq(leftoverShorts, shorts);
+    const noDormantLegs = position.exposure.symbols().length === longs.size + shorts.size;
+    return sameActiveShape && noDormantLegs;
   });
   if (target) {
     return target;
@@ -2139,4 +2210,4 @@ function takeVerifier(handoffId, storage) {
 }
 __name(takeVerifier, "takeVerifier");
 
-export { BIPS, ZERO, abs, add, aggregateRealizedPositionState, baseToContracts, buildApplicables, compareValue, computeAssetEntryNotional, computeAssetGrossRealizedPnL, computeAssetRealizedPnLs, computeAssetUndeterminedSizes, computeAssetUnrealizedPnL, computeAssetUnrealizedPnLs, computeBasketWeightedRatioV1, computeEntryPriceForAsset, computePositionEntryPrices, computeRealizedPnlBySymbol, computeRealizedPnlFromFills, computeRealizedPositionState, computeSyncPayload, computeUnrealizedPositionState, computeUnrealizedPositionStateFromEntryPrices, configureProxy, contractsToBase, countDecimals, deriveBasketKey, divide, exponentiate, finishXHandoff, generateDeterministicPositionKey, isEqualTo, isFiniteDecimal, isGreaterThan, isGreaterThanOrEqual, isLessThan, isLessThanOrEqual, isNegative, isPositive, isZero, min, multiply, negate, parse, precisePrice, preciseQuantity, proxyFetch, sideSign, sign, signed, signedBySide, startXHandoff, stripXReturn, subtract, toDecimalString, validateLeverage, validateQuantity };
+export { BIPS, ZERO, abs, add, aggregateRealizedPositionState, baseToContracts, buildApplicables, compareValue, computeAssetEntryNotional, computeAssetGrossRealizedPnL, computeAssetRealizedPnLs, computeAssetUndeterminedSizes, computeAssetUnrealizedPnL, computeAssetUnrealizedPnLs, computeBasketWeightedRatioV1, computeEntryPriceForAsset, computeMaxBasketSize, computePositionEntryPrices, computeRealizedPnlBySymbol, computeRealizedPnlFromFills, computeRealizedPositionState, computeSyncPayload, computeUnrealizedPositionState, computeUnrealizedPositionStateFromEntryPrices, configureProxy, contractsToBase, countDecimals, deriveBasketKey, divide, exponentiate, finishXHandoff, generateDeterministicPositionKey, isEqualTo, isFiniteDecimal, isGreaterThan, isGreaterThanOrEqual, isLessThan, isLessThanOrEqual, isNegative, isPositive, isZero, min, multiply, negate, parse, precisePrice, preciseQuantity, proxyFetch, sideSign, sign, signed, signedBySide, sizeSinglePoolBasket, startXHandoff, stripXReturn, subtract, toDecimalString, validateLeverage, validateQuantity };

package/dist/sync/applicables/matching.d.ts

@@ -6,8 +6,8 @@ import type { MatchedPosition } from './types';
  *   - findExactCloseTarget picks the open position whose ACTIVE legs mirror the
  *     basket (dead legs ignored) — the basket closes that position first,
  *   - applyCloses reduces holders (the mirrored target first, then any other),
- *   - resolveLeftoverTarget subset-merges into a compatible position, else opens
- *     new (same-shape ADDs consolidate here).
+ *   - resolveLeftoverTarget merges into a position whose FULL leg set (active and
+ *     dormant) is exactly the leftover's, else opens new (same-shape ADDs consolidate here).
  * The asset SET of a position never grows, so positionKey == key(opening symbols).
  */
 export declare function matchPositions(args: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pear-protocol/utils",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Pear Protocol Utility functions",
   "private": false,
   "type": "module",
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@noble/hashes": "^1.3.2",
-    "@pear-protocol/types": "^1.24.1",
+    "@pear-protocol/types": "^1.28.0",
     "@scure/base": "^2.3.0",
     "bignumber.js": "9.3.1"
   },