@pear-protocol/utils 0.7.0 → 0.8.1

package/dist/asset/asset.types.d.ts

@@ -1,5 +1,6 @@
 import type { InstrumentId } from '@pear-protocol/types';
 import BigNumber from 'bignumber.js';
+import type { Fill } from '../fills/fill.types';
 export type AssetUnrealizedPnL = {
     id: InstrumentId;
     signedQuantity: BigNumber;
@@ -45,3 +46,4 @@ export type AssetRealizedPnL = {
     pearFees: BigNumber;
     closures: AssetClosure[];
 };
+export type DeployedCapitalFill = Pick<Fill, 'symbol' | 'side' | 'price' | 'quantity'>;

package/dist/asset/compute.d.ts

@@ -1,7 +1,7 @@
 import type { InstrumentId } from '@pear-protocol/types';
 import BigNumber from 'bignumber.js';
 import type { Fill } from '../fills/fill.types';
-import type { AssetRealizedPnL, AssetUnrealizedPnL } from './asset.types';
+import type { AssetRealizedPnL, AssetUnrealizedPnL, DeployedCapitalFill } from './asset.types';
 type ExposureMap = Record<InstrumentId, string>;
 type PriceMap = Record<InstrumentId, string>;
 /**
@@ -43,4 +43,44 @@ export declare function computeAssetUnrealizedPnLs(exposureMap: ExposureMap, pri
  * Formula: Σ(realizedPnL)
  */
 export declare function computeAssetRealizedPnLs(fills: Fill[]): AssetRealizedPnL[];
+/**
+ * The most cash the position's selected legs had committed at one time.
+ *
+ * Cash, not market value: each opening fill commits what it actually paid, at its own
+ * execution price, and each closing fill releases the share of that commitment the quantity
+ * it closed was holding. No price beyond the fills' own is read, which matters because there
+ * is none to read — this system keeps no historical price series, so a market-value
+ * denominator could only ever be sampled at fills anyway.
+ *
+ * Sampling it that way was the earlier rule, and it failed in the direction that flatters.
+ * Revaluing a whole leg at each fill's price lets the denominator fall BELOW the money the
+ * trader put in: buy 10 at 200 then 10 more at 100 and the leg's worth never exceeds 2,000
+ * though 3,000 went in, so the return comes out 1.5x too large. Averaging down is ordinary
+ * trading, and a public board must not pay for it. Counting cash cannot do this — the
+ * denominator only ever rises when money goes in.
+ *
+ * Walked from the fills rather than read off the size stamped at the open, because a
+ * position is routinely scaled up long after it opens. Dividing by the opening size measures
+ * a return against capital the trader has since multiplied, and overstates it by exactly
+ * that factor — a position opened at 73 and grown to 33,499 reported 774% for a trade that
+ * made 1.7%.
+ *
+ * The peak rather than the running total of everything opened, so a position that reduces
+ * and rebuilds is charged for the capital it committed, not for the same capital counted
+ * twice. Unsigned per leg, because a pair trade's short leg is size the trader put at risk,
+ * not a credit against the long.
+ *
+ * Every loaded fill moves the commitment, an external one included: exposure has no per-fill
+ * provenance, so dropping a venue-merged fill would misstate what the position tied up rather
+ * than narrow the measure. Read in the chronological order the reader guarantees — unlike
+ * the per-asset realized walk, this total spans every leg at once, so a leg out of sequence
+ * misstates the basket in either direction: it can show two legs held together that never
+ * were, or miss a pairing that was.
+ *
+ * Fills sharing one timestamp are separated by symbol, which is alphabetical rather than
+ * causal: a leg swapped for another in the same instant may be seen committed alongside it.
+ * That only ever adds to the peak, so the denominator errs large and the return it produces
+ * errs small — the safe direction for a public board.
+ */
+export declare function computeDeployedCapital(fills: DeployedCapitalFill[], assets: Set<string> | undefined): BigNumber;
 export {};

package/dist/asset/index.d.ts

@@ -1,2 +1,2 @@
-export type { AssetClosure, AssetRealizedPnL, AssetUnrealizedPnL } from './asset.types';
+export type { AssetClosure, AssetRealizedPnL, AssetUnrealizedPnL, DeployedCapitalFill } from './asset.types';
 export * from './compute';

package/dist/index.js

@@ -239,6 +239,35 @@ function computeAssetRealizedPnLs(fills) {
   return result;
 }
 __name(computeAssetRealizedPnLs, "computeAssetRealizedPnLs");
+function computeDeployedCapital(fills, assets) {
+  const legs = /* @__PURE__ */ new Map();
+  let committed = ZERO;
+  let peak = ZERO;
+  for (const fill of fills) {
+    if (assets && !assets.has(fill.symbol.toUpperCase())) {
+      continue;
+    }
+    const leg = legs.get(fill.symbol) ?? {
+      quantity: ZERO,
+      basis: ZERO
+    };
+    const delta = signedBySide(fill.quantity, fill.side);
+    const closed = closesAgainstHolding(leg.quantity, delta);
+    const opened = subtract(abs(delta), closed);
+    const released = isZero(leg.quantity) ? ZERO : divide(multiply(leg.basis, closed), abs(leg.quantity));
+    const basis = add(subtract(leg.basis, released), multiply(opened, fill.price));
+    committed = add(subtract(committed, leg.basis), basis);
+    legs.set(fill.symbol, {
+      quantity: add(leg.quantity, delta),
+      basis
+    });
+    if (isGreaterThan(committed, peak)) {
+      peak = committed;
+    }
+  }
+  return peak;
+}
+__name(computeDeployedCapital, "computeDeployedCapital");
 function walkAssetFills(fills) {
   let entryPrice = ZERO;
   let positionSize = ZERO;
@@ -297,6 +326,13 @@ function walkAssetFills(fills) {
   };
 }
 __name(walkAssetFills, "walkAssetFills");
+function closesAgainstHolding(held, delta) {
+  if (isZero(held) || isPositive(held) === isPositive(delta)) {
+    return ZERO;
+  }
+  return min(abs(delta), abs(held));
+}
+__name(closesAgainstHolding, "closesAgainstHolding");
 
 // src/basket/compute.ts
 function computeBasketWeightedRatioV1(basket, priceMap) {
@@ -2316,4 +2352,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, 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 };
+export { BIPS, ZERO, abs, add, aggregateRealizedPositionState, baseToContracts, buildApplicables, compareValue, computeAssetEntryNotional, computeAssetGrossRealizedPnL, computeAssetRealizedPnLs, computeAssetUndeterminedSizes, computeAssetUnrealizedPnL, computeAssetUnrealizedPnLs, computeBasketWeightedRatioV1, computeDeployedCapital, 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/dist/position/key.d.ts

@@ -10,6 +10,9 @@ type PositionKeyInput = {
  * no side — same-asset positions therefore produce the SAME key, which is
  * exactly what the active-position unique index relies on and what makes the
  * apply UPSERT find-or-create the single correct target.
+ *
+ * PHASE-1 LEG ID WARNING: `symbols` must be instrument ids
+ * (`leg.id ?? leg.symbol`, or exposure keys). A phase-3 ticker here re-hashes and orphans every position.
  */
 export declare function generateDeterministicPositionKey(input: PositionKeyInput): string;
 export {};

package/package.json

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