@pear-protocol/utils - npm Package Compare versions

Comparing version 0.6.0 to 0.7.0

dist/basket/basket.types.d.ts

@@ -23,2 +23,19 @@ import type { HttpTypes, InstrumentId, Side } from '@pear-protocol/types';
 };
+/** 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 = {
@@ -28,13 +45,36 @@ /**
      * 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. */
@@ -45,2 +85,4 @@ export type CappedBasketLeg = {
     effectiveLeverage: string;
+    /** Identifies this leg in `MaxBasketSizeResult.legs`. Omit to keep the leg anonymous. */
+    asset?: InstrumentId;
 };
@@ -53,8 +95,19 @@ /** The one margin budget every leg funds out of. */
 };
-/** 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'>[];
+};

dist/basket/max-size.d.ts

@@ -1,2 +0,2 @@
-import type { MaxBasketSizeCalculation, MaxBasketSizeInput, MaxBasketSizeResult, SinglePoolSizingContext } from './basket.types';
+import type { BasketSizingContext, MaxBasketSizeCalculation, MaxBasketSizeInput, MaxBasketSizePerAssetLeverageInput, MaxBasketSizeRequest, MaxBasketSizeResult, MultiQuoteBasketSizeCalculation } from './basket.types';
 /**
@@ -11,9 +11,31 @@ * The largest gross notional this basket can reach while every leg stays funded at its weight.
 /**
- * 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.json

 {
   "name": "@pear-protocol/utils",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Pear Protocol Utility functions",
@@ -5,0 +5,0 @@ "private": false,

No alert changes

Improved metrics

Total package byte prevSize

128662

6.53%

Lines of code

3410

5.64%

No dependency changes