@pear-protocol/utils 0.5.3 → 0.7.0

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

@@ -1,6 +1,109 @@
-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;
+};
+/** 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 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, 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 = {
+    /** USD-equivalent margin available. Every connector this sizes for funds a basket from one balance. */
+    budget: string;
+    legs: CappedBasketLeg[];
+};
+/** 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/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,40 @@
+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.
+ *
+ * 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;
+/**
+ * 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.
+ *
+ * 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 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

@@ -328,6 +328,187 @@ 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 demands = input.legs.map((leg) => toLegDemand(leg, weightSum));
+  const size = divide(input.budget, sumDemand(demands));
+  return {
+    maxNotional: size.toFixed(),
+    marginRequired: input.budget,
+    legs: legMarginBreakdown(demands, size),
+    marginRequiredByQuote: null
+  };
+}
+__name(computeMaxBasketSize, "computeMaxBasketSize");
+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();
+  }
+  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
+  ]));
+  const capped = [];
+  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(leg.requestedLeverage, instrument.leverage),
+      quote: instrument.quote
+    });
+  }
+  return capped;
+}
+__name(capLegsAgainstCatalog, "capLegsAgainstCatalog");
+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,
+    legs: null,
+    marginRequiredByQuote: null
+  };
+}
+__name(unsizedResult, "unsizedResult");
+function toLegDemand(leg, weightSum) {
+  const share = divide(String(leg.weight), weightSum);
+  const marginFraction = divide("1", leg.effectiveLeverage);
+  return {
+    leg,
+    demand: multiply(share, marginFraction)
+  };
+}
+__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 marginByQuote;
+}
+__name(marginRequiredByQuote, "marginRequiredByQuote");
 function contractsToBase(contracts, contractSize) {
   return new BigNumber7(contracts).times(contractSize);
 }
@@ -2135,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, 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, 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.5.3",
+  "version": "0.7.0",
   "description": "Pear Protocol Utility functions",
   "private": false,
   "type": "module",