@pear-protocol/utils 0.6.0 → 0.7.0

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

@@ -20,26 +20,68 @@ export type MaxBasketSizeInput = {
     /** What the caller is requesting for the whole basket, before each leg's own venue max caps it. */
     requestedLeverage: number;
 };
+/** Same shape as `MaxBasketSizeLeg`, but leverage is requested per leg instead of once for the basket. */
+export type MaxBasketSizePerAssetLeverageLeg = MaxBasketSizeLeg & {
+    /** What the caller is requesting for THIS leg, before the venue max caps it. */
+    requestedLeverage: number;
+};
+export type MaxBasketSizePerAssetLeverageInput = {
+    legs: MaxBasketSizePerAssetLeverageLeg[];
+};
+/**
+ * Either shape a caller can size a basket from, tagged by how leverage is requested —
+ * once for the whole basket, or once per leg. `sizeBasketByLeverageMode` switches on it.
+ */
+export type MaxBasketSizeRequest = ({
+    leverageMode: 'shared';
+} & MaxBasketSizeInput) | ({
+    leverageMode: 'perAsset';
+} & MaxBasketSizePerAssetLeverageInput);
 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.
+     * Null when a leg names an asset the caller's instrument catalog does not list, or names a quote
+     * currency the caller's `balanceByQuote` map does not fund — either gap leaves the basket unsized.
      */
     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`.
+     * The margin `maxNotional` spends, summed across every pool it draws from. For a single budget
+     * (`computeMaxBasketSize`) this is always the whole budget supplied, since that is exactly the
+     * point at which the basket stops growing. Across several quote-currency pools
+     * (`computeMultiQuoteBasketSize`) it is the total actually drawn — the full balance of whichever
+     * pool is the tightest constraint, but not necessarily the others. `null` on the same terms as
+     * `maxNotional`.
      */
     marginRequired: string | null;
+    /**
+     * `marginRequired` broken out per leg, in the caller's own leg order — `null` when a leg carries
+     * no identity to report it under (`computeMaxBasketSize`/`computeMultiQuoteBasketSize` called
+     * directly on anonymous `CappedBasketLeg`s), never partial: every leg reports or none does.
+     */
+    legs: LegMarginRequired[] | null;
+    /**
+     * `marginRequired` grouped by quote currency instead of by leg, e.g. `{ USDC: '20', USDT: '20' }`
+     * — how much of each currency the basket actually needs, not how much each asset draws. Two legs
+     * settling in the same currency fold into one entry here, unlike `legs`. Always `null` from
+     * `computeMaxBasketSize` — a single budget has no quote to group by.
+     */
+    marginRequiredByQuote: Record<string, string> | null;
+};
+/** One leg's own share of `marginRequired`, identified so the caller can show it per asset. */
+export type LegMarginRequired = {
+    asset: InstrumentId;
+    /** The leverage this leg was actually granted — after the venue-max cap, not the raw request. */
+    effectiveLeverage: string;
+    marginRequired: string;
 };
 /** 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;
+    /** Identifies this leg in `MaxBasketSizeResult.legs`. Omit to keep the leg anonymous. */
+    asset?: InstrumentId;
 };
 /** The one margin budget every leg funds out of. */
 export type MaxBasketSizeCalculation = {
@@ -47,10 +89,21 @@ export type MaxBasketSizeCalculation = {
     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'>[];
+/** One capped leg, tagged with the quote-currency pool its margin draws from. */
+export type CappedBasketLegWithQuote = CappedBasketLeg & {
+    /** The instrument's quote asset, e.g. `"USDC"` — the key into `MultiQuoteBasketSizeCalculation.balanceByQuote`. */
+    quote: string;
+};
+/** The margin budgets a basket whose legs settle in more than one quote currency funds out of. */
+export type MultiQuoteBasketSizeCalculation = {
+    /** Available margin per quote currency, e.g. `{ USDC: '500', USDT: '300' }`. */
+    balanceByQuote: Record<string, string>;
+    legs: CappedBasketLegWithQuote[];
+};
+/** What the sizing functions need beyond the legs: balance per quote pool, and the leverage ceilings. */
+export type BasketSizingContext = {
+    /** Available margin per quote currency. A leg whose instrument quotes in a currency absent here can't be sized. */
+    balanceByQuote: Record<string, string>;
+    /** Off the core-sdk instrument catalog — only `id`, `leverage`, and `quote` are read. */
+    instruments: Pick<HttpTypes.Instrument, 'id' | 'leverage' | 'quote'>[];
 };

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

@@ -1,4 +1,4 @@
-import type { MaxBasketSizeCalculation, MaxBasketSizeInput, MaxBasketSizeResult, SinglePoolSizingContext } from './basket.types';
+import type { BasketSizingContext, MaxBasketSizeCalculation, MaxBasketSizeInput, MaxBasketSizePerAssetLeverageInput, MaxBasketSizeRequest, MaxBasketSizeResult, MultiQuoteBasketSizeCalculation } from './basket.types';
 /**
  * The largest gross notional this basket can reach while every leg stays funded at its weight.
  *
@@ -8,11 +8,33 @@ import type { MaxBasketSizeCalculation, MaxBasketSizeInput, MaxBasketSizeResult,
  */
 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)`.
+ * The largest gross notional this basket can reach when its legs settle in more than one quote
+ * currency. Each leg's margin draws from its own quote pool, and the pool that runs out first caps
+ * the whole basket — the same "tightest constraint wins" logic `computeMaxBasketSize` applies to
+ * leverage, one level up. A basket whose legs all share one quote reduces to exactly one pool, so
+ * this is a strict superset of `computeMaxBasketSize`'s single-budget math.
  *
- * 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.
+ * Takes the caller's figures as given — a malformed balance or leverage is the caller's own
+ * responsibility to keep clean, not something this function guards against.
  */
-export declare function sizeSinglePoolBasket(input: MaxBasketSizeInput, context: SinglePoolSizingContext): MaxBasketSizeResult;
+export declare function computeMultiQuoteBasketSize(input: MultiQuoteBasketSizeCalculation): MaxBasketSizeResult;
+/**
+ * Sizes a basket that caps leverage at nothing but the caller-supplied max —
+ * `effectiveLeverage = min(requested, catalogMax)` — and funds each leg out of its own instrument's
+ * quote-currency pool.
+ *
+ * A leg naming an asset the caller's catalog does not list leaves its ceiling and pool unknown, and
+ * a leg naming a quote the caller's balance map does not list leaves its pool's budget unknown —
+ * either gap reports no size rather than a wrong one.
+ */
+export declare function sizeBasket(input: MaxBasketSizeInput, context: BasketSizingContext): MaxBasketSizeResult;
+/**
+ * Sizes a basket the same way `sizeBasket` does, but each leg requests its own leverage
+ * instead of the whole basket sharing one figure — still capped at that leg's own venue max.
+ */
+export declare function sizeBasketPerAssetLeverage(input: MaxBasketSizePerAssetLeverageInput, context: BasketSizingContext): MaxBasketSizeResult;
+/**
+ * Single entry point for sizing a basket regardless of how the caller requests
+ * leverage — dispatches on `leverageMode` to the shared-basket or per-asset implementation.
+ */
+export declare function sizeBasketByLeverageMode(request: MaxBasketSizeRequest, context: BasketSizingContext): MaxBasketSizeResult;

package/dist/index.js

@@ -335,39 +335,109 @@ function computeMaxBasketSize(input) {
   if (isZero(weightSum)) {
     return unsizedResult();
   }
-  const shares = input.legs.map((leg) => toLegShare(leg, weightSum));
-  const size = divide(input.budget, marginPerUnitNotional(shares));
+  const demands = input.legs.map((leg) => toLegDemand(leg, weightSum));
+  const size = divide(input.budget, sumDemand(demands));
   return {
     maxNotional: size.toFixed(),
-    marginRequired: input.budget
+    marginRequired: input.budget,
+    legs: legMarginBreakdown(demands, size),
+    marginRequiredByQuote: null
   };
 }
 __name(computeMaxBasketSize, "computeMaxBasketSize");
-function sizeSinglePoolBasket(input, context) {
-  if (context.availableBalance === null) {
+function computeMultiQuoteBasketSize(input) {
+  const weightSum = sumWeights(input.legs);
+  if (isZero(weightSum)) {
+    return unsizedResult();
+  }
+  const demands = input.legs.map((leg) => toLegDemand(leg, weightSum));
+  const demandByQuote = demandPerQuote(demands);
+  let binding;
+  for (const [quote, demand] of demandByQuote) {
+    const balance = input.balanceByQuote[quote];
+    if (balance === void 0) {
+      return unsizedResult();
+    }
+    if (isZero(demand)) {
+      continue;
+    }
+    const notional = divide(balance, demand);
+    if (binding === void 0 || isLessThan(notional, binding.maxNotional)) {
+      binding = {
+        quote,
+        balance,
+        maxNotional: notional
+      };
+    }
+  }
+  if (binding === void 0) {
+    return unsizedResult();
+  }
+  const marginByQuote = marginRequiredByQuote(demandByQuote, binding);
+  const marginRequired = Object.values(marginByQuote).reduce((total, drawn) => add(total, drawn), ZERO);
+  return {
+    maxNotional: binding.maxNotional.toFixed(),
+    marginRequired: marginRequired.toFixed(),
+    legs: legMarginBreakdown(demands, binding.maxNotional),
+    marginRequiredByQuote: marginByQuote
+  };
+}
+__name(computeMultiQuoteBasketSize, "computeMultiQuoteBasketSize");
+function sizeBasket(input, context) {
+  const legs = capLegsAgainstCatalog(input.legs.map((leg) => ({
+    ...leg,
+    requestedLeverage: input.requestedLeverage
+  })), context.instruments);
+  if (legs === null) {
+    return unsizedResult();
+  }
+  return computeMultiQuoteBasketSize({
+    balanceByQuote: context.balanceByQuote,
+    legs
+  });
+}
+__name(sizeBasket, "sizeBasket");
+function sizeBasketPerAssetLeverage(input, context) {
+  const legs = capLegsAgainstCatalog(input.legs, context.instruments);
+  if (legs === null) {
     return unsizedResult();
   }
-  const maxLeverageById = new Map(context.instruments.map((instrument) => [
+  return computeMultiQuoteBasketSize({
+    balanceByQuote: context.balanceByQuote,
+    legs
+  });
+}
+__name(sizeBasketPerAssetLeverage, "sizeBasketPerAssetLeverage");
+function sizeBasketByLeverageMode(request, context) {
+  switch (request.leverageMode) {
+    case "shared":
+      return sizeBasket(request, context);
+    case "perAsset":
+      return sizeBasketPerAssetLeverage(request, context);
+  }
+}
+__name(sizeBasketByLeverageMode, "sizeBasketByLeverageMode");
+function capLegsAgainstCatalog(legs, instruments) {
+  const instrumentById = new Map(instruments.map((instrument) => [
     instrument.id,
-    instrument.leverage
+    instrument
   ]));
   const capped = [];
-  for (const leg of input.legs) {
-    const maxLeverage = maxLeverageById.get(leg.asset);
-    if (maxLeverage === void 0) {
-      return unsizedResult();
+  for (const leg of legs) {
+    const instrument = instrumentById.get(leg.asset);
+    if (instrument === void 0) {
+      return null;
     }
     capped.push({
+      asset: leg.asset,
       weight: leg.weight,
-      effectiveLeverage: cappedLeverage(input.requestedLeverage, maxLeverage)
+      effectiveLeverage: cappedLeverage(leg.requestedLeverage, instrument.leverage),
+      quote: instrument.quote
     });
   }
-  return computeMaxBasketSize({
-    budget: context.availableBalance,
-    legs: capped
-  });
+  return capped;
 }
-__name(sizeSinglePoolBasket, "sizeSinglePoolBasket");
+__name(capLegsAgainstCatalog, "capLegsAgainstCatalog");
 function cappedLeverage(requested, maxLeverage) {
   const granted = min(String(requested), String(maxLeverage));
   return isFiniteDecimal(granted) && granted.isGreaterThan(0) ? granted.toFixed() : "1";
@@ -384,25 +454,61 @@ __name(sumWeights, "sumWeights");
 function unsizedResult() {
   return {
     maxNotional: null,
-    marginRequired: null
+    marginRequired: null,
+    legs: null,
+    marginRequiredByQuote: null
   };
 }
 __name(unsizedResult, "unsizedResult");
-function toLegShare(leg, weightSum) {
+function toLegDemand(leg, weightSum) {
+  const share = divide(String(leg.weight), weightSum);
+  const marginFraction = divide("1", leg.effectiveLeverage);
   return {
-    share: divide(String(leg.weight), weightSum),
-    imr: divide("1", leg.effectiveLeverage)
+    leg,
+    demand: multiply(share, marginFraction)
   };
 }
-__name(toLegShare, "toLegShare");
-function marginPerUnitNotional(shares) {
-  let demand = ZERO;
-  for (const leg of shares) {
-    demand = add(demand, multiply(leg.share, leg.imr));
+__name(toLegDemand, "toLegDemand");
+function legMarginBreakdown(demands, maxNotional) {
+  const breakdown = [];
+  for (const { leg, demand } of demands) {
+    if (leg.asset === void 0) {
+      return null;
+    }
+    breakdown.push({
+      asset: leg.asset,
+      effectiveLeverage: leg.effectiveLeverage,
+      marginRequired: multiply(maxNotional, demand).toFixed()
+    });
+  }
+  return breakdown;
+}
+__name(legMarginBreakdown, "legMarginBreakdown");
+function sumDemand(demands) {
+  let total = ZERO;
+  for (const { demand } of demands) {
+    total = add(total, demand);
+  }
+  return total;
+}
+__name(sumDemand, "sumDemand");
+function demandPerQuote(demands) {
+  const demandByQuote = /* @__PURE__ */ new Map();
+  for (const { leg, demand } of demands) {
+    const current = demandByQuote.get(leg.quote) ?? ZERO;
+    demandByQuote.set(leg.quote, add(current, demand));
+  }
+  return demandByQuote;
+}
+__name(demandPerQuote, "demandPerQuote");
+function marginRequiredByQuote(demandByQuote, binding) {
+  const marginByQuote = {};
+  for (const [quote, demand] of demandByQuote) {
+    marginByQuote[quote] = quote === binding.quote ? parse(binding.balance).toFixed() : multiply(binding.maxNotional, demand).toFixed();
   }
-  return demand;
+  return marginByQuote;
 }
-__name(marginPerUnitNotional, "marginPerUnitNotional");
+__name(marginRequiredByQuote, "marginRequiredByQuote");
 function contractsToBase(contracts, contractSize) {
   return new BigNumber7(contracts).times(contractSize);
 }
@@ -2210,4 +2316,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, 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 };
+export { BIPS, ZERO, abs, add, aggregateRealizedPositionState, baseToContracts, buildApplicables, compareValue, computeAssetEntryNotional, computeAssetGrossRealizedPnL, computeAssetRealizedPnLs, computeAssetUndeterminedSizes, computeAssetUnrealizedPnL, computeAssetUnrealizedPnLs, computeBasketWeightedRatioV1, computeEntryPriceForAsset, computeMaxBasketSize, computeMultiQuoteBasketSize, 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, sizeBasket, sizeBasketByLeverageMode, sizeBasketPerAssetLeverage, startXHandoff, stripXReturn, subtract, toDecimalString, validateLeverage, validateQuantity };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pear-protocol/utils",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Pear Protocol Utility functions",
   "private": false,
   "type": "module",